Achilles — Auth / Security

A cross-cutting security layer that runs through every module. It handles user authentication, action authorization, and data access control at the level of individual records.

Architecture

Entry points

Admin Panel admin shell · email + password → JWT Web App user shell · email + password → JWT MCP API key → user Slack ID → identity map Telegram ID → identity map Mattermost ID → identity map Extension OAuth / token

Authentication — who is the user?

Identifying the user. Every entry point converges on a single user_id.

argon2id JWT HS256 NIST 800-63B zxcvbn + HIBP SSO/OIDC MFA TOTP

Authorization — what is allowed?

Owner › Admin › Member

Endpoints check permissions via require() → ROLE_PERMISSIONS, not roles directly

Data-level ACL — what is accessible?

The data source is the sole authority on who sees what.
Double filter: Source ACL + Platform ACL — access is granted only when both pass.

Identity Mapping Container ACL Email auto-match Fail-safe

Tokens and sessions

request → Access → expired → Refresh → new pair ↻

Access Token short · 15m

Type JWT, stateless

TTL 15 minutes

Storage In JS memory

Transport Authorization: Bearer

Header alg, typ, kid

Claims sub, role, exp, iat, jti, iss, aud

rotation

Refresh Token long · 30d

Type Stateful (DB)

TTL 30d sliding / 90d ceiling

Storage cookie

Flags httpOnly, Secure, SameSite=Strict

Family family_id (UUIDv7)

⟳ Rotation & Reuse Detection

Every refresh issues a new pair and invalidates the old token. Reusing a revoked token voids the entire chain (token family), but not all of the user's sessions.

Protection

request → TLS → Headers → CORS → CSRF → Brute force → Crypto core → Audit log → ✓ handling

Brute-force defense line — in detail:

by IP from 3rd failure 10 failures

threshold by IP

Rate limit by IP

20 attempts / 15 min. Redis sliding window.

from 3rd failure

Account-level delay

First 2 attempts with no delay, then 1s → 2s → 4s → 8s (cap 30s). Server-side.

after 10 failures

Alert Owner/Admin

Notify Owner/Admin — without locking out.

API

POST/api/v1/auth/login
POST/api/v1/auth/refresh
POST/api/v1/auth/logout
POST/api/v1/auth/logout-all
POST/api/v1/auth/setup
POST/api/v1/auth/password/change
POST/api/v1/auth/password/forgot
POST/api/v1/auth/password/reset
GET · POST/api/v1/api-keys
DELETE/api/v1/api-keys/{id}
POST/api/v1/invites
POST/api/v1/invites/bulk
POST/api/v1/invites/{token}/accept
POST/api/v1/link/{platform}
POST/api/v1/link/{platform}/confirm
GET · PATCH/api/v1/admin/users · /{id}
DELETE/api/v1/admin/users/{id}
POST/api/v1/admin/users/{id}/reset-password · /terminate-sessions
GET/api/v1/admin/audit-log

Workzone Design

Detailed design decisions for the module.

Routing and redirects Authentication Authorization Protection Data model and contracts Stack and structure Tests

Wireframes Wireframes

Screens — a description and wireframe of each.

Public — before sign-in

Setup Wizard wireframe Login wireframe Invite Accept wireframe Status Screen wireframe

User — after sign-in

Profile / Account wireframe Session Management wireframe Re-auth modal wireframe Messenger linking wireframe

Features Features

Multi-screen flows — description, technical requirements, transitions.

Password recovery

Password recovery Forgot Password wireframe Reset Password wireframe

Two-factor authentication

Two-factor authentication MFA Setup wireframe MFA Management wireframe

Forced password change

Forced password change Change Temp Password wireframe

API keys

API keys API Key Create wireframe

User onboarding

User onboarding Bulk Invite · Upload wireframe Bulk Invite · Preview wireframe