@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/docs/architecture.md

@@ -0,0 +1,119 @@
+# Architecture
+
+For contributors, and for anyone who wants to know what happens inside.
+
+## Layout
+
+```
+src/
+├── index.ts                   public exports (the only import path apps use)
+├── auth.module.ts             AuthModule.forRoot(): wires providers, controllers, guard, filter
+├── auth-options.ts            AuthOptions and sender interfaces
+├── auth-options.validation.ts startup checks of the options
+├── constants.ts               ALL constants: limits, lifetimes, patterns, errors, events
+├── common/                    building blocks with no business rules
+│   ├── crypto/                jwt (ES256/RS256), totp (RFC 6238), random-secrets, remote-public-keys
+│   ├── auth-error.ts          AuthError(AUTH_ERRORS.x) → { status, code, message }
+│   ├── auth-exception.filter  one error format for the whole app
+│   ├── encryption.service     KMS / local AES-GCM envelope with context binding
+│   ├── rate-limiter.service   Redis or memory, fails closed
+│   ├── network-safety.ts      SSRF guard for outgoing webhook calls
+│   └── identifiers.ts         email / phone normalization
+├── database/
+│   ├── entities/              one TypeORM entity per table
+│   └── create-auth-tables.migration.ts
+├── guards/                    AuthGuard + decorators
+├── integrations/              ready-made senders (MSG91, console email)
+└── features/                  one folder per feature: service (+ controller + dto)
+    ├── settings/              defaults → code → admin layering, validation
+    ├── signing-keys/          ES256 key creation, rotation, JWKS endpoint
+    ├── sessions/              sessions, access and refresh tokens
+    ├── users/                 account life cycle, sign-up rules, sign-in method inventory
+    ├── sign-in/               completeSignIn pipeline, 2FA / reactivation challenges
+    ├── passwords/             register, login, reset, change, password policy
+    ├── email-links/           link tokens, email verification
+    ├── one-time-codes/        email/SMS codes
+    ├── passwordless/          email OTP, magic link, phone OTP
+    ├── social/                Google / Apple / Facebook verification and linking
+    ├── passkeys/              WebAuthn via @simplewebauthn/server
+    ├── two-factor/            TOTP + backup codes
+    ├── organizations/         organizations, members, invitations
+    ├── api-keys/              machine keys
+    ├── webhooks/              admin CRUD, signatures, delivery worker
+    ├── events/                audit log → onEvent → webhook queue
+    ├── notifications/         wraps the app's email/SMS senders
+    ├── account/               /auth/me, sessions, refresh, deactivate
+    └── admin/                 admin API
+```
+
+## The sign-in pipeline
+
+Every method only **proves identity**, then hands over to `SignInService.completeSignIn()`:
+
+```
+ password │ email code │ magic link │ SMS code │ Google/Apple/Facebook │ passkey
+          └─────────────────────────────┬──────────────────────────────────────┘
+                                        ▼
+                         SignInService.completeSignIn(user, method)
+                          1. account status check  (NOT_VERIFIED / DEACTIVATED / SUSPENDED)
+                          2. 2FA on? → challenge token (except passkeys)
+                          3. SessionService.startSession → tokens
+                          4. lastSignedInAt, user.signed_in event, new-device email
+```
+
+Adding a sign-in method therefore can't skip a security check: it only has to produce a `UserEntity`.
+
+## Data model
+
+```
+auth_users ─┬─ auth_passwords (1:1)
+            ├─ auth_social_accounts (1:n, unique provider+provider_user_id)
+            ├─ auth_passkeys (1:n)
+            ├─ auth_two_factor_secrets (1:1) ─ auth_backup_codes (1:n)
+            ├─ auth_sessions (1:n) ─ auth_refresh_tokens (1:n)
+            ├─ auth_organization_members (n:m) ─ auth_organizations ─ auth_organization_invitations
+            └─ auth_audit_logs
+auth_link_tokens, auth_one_time_codes, auth_sign_in_challenges   short-lived, single-use
+auth_signing_keys        one current key (partial unique index), retired keys kept 2 days
+auth_settings            one row (id = 1): the admin's changes
+auth_api_keys, auth_webhooks ─ auth_webhook_deliveries
+```
+
+The database itself enforces key invariants:
+- lowercase emails and E.164 phone numbers
+- valid statuses
+- every live user has an email or phone
+- only one current signing key
+- one settings row
+
+## Concurrency
+
+Anything that must happen at most once is a single conditional `UPDATE`:
+
+| What | How |
+|---|---|
+| Refresh-token use | `UPDATE ... SET used_at = now() WHERE used_at IS NULL ... RETURNING` |
+| Link tokens, codes, challenges | Same pattern |
+| TOTP replay | `UPDATE ... WHERE last_used_time_step < :step` |
+| Status changes | `UPDATE ... WHERE status = :expected` |
+| Webhook delivery claims | `FOR UPDATE SKIP LOCKED`, so many servers can run the worker |
+
+## Caches (per server)
+
+| What | Lifetime | Effect |
+|---|---|---|
+| Settings | 10 s | Admin changes reach every server within 10 s |
+| Signing keys | 60 s | Rotation reaches every server within a minute |
+| Session checks (`@CheckSession`) | 5 s | Sign-out and suspension take effect within 5 s on those routes |
+| Google / Apple public keys | 6 h | Refetched early when an unknown key id appears (at most once a minute) |
+
+## Design rules for contributors
+
+1. **Constants:** every route, status, name, number, pattern, header, message and code goes in `constants.ts`. `test/no-hardcoded-values.test.ts` fails the build otherwise. The only exceptions are code itself (SQL, entity property names), human-readable log text, and released migrations, which must never change.
+2. **Names:** use descriptive names, and comments that explain *why*.
+3. **Errors:** throw `new AuthError(AUTH_ERRORS.x)`. Never leak internals.
+4. **Enumeration:** never reveal whether an account exists before the user proves who they are.
+5. **Single use:** anything single-use is consumed with one atomic statement.
+6. **Events:** every security-relevant action records an event. Event details never contain secrets.
+7. **Settings:** new behavior is controlled by a setting (with validation and a secure default) or a constant. Code does not branch on environment variables.
+8. **Tests:** pure logic gets unit tests (`test/`), and SQL changes are run against a real PostgreSQL.

package/docs/client-integration.md

@@ -0,0 +1,192 @@
+# Client integration
+
+Guidance for the web and mobile apps that call the auth API.
+
+## Storing tokens
+
+| Client | Access token | Refresh token |
+|---|---|---|
+| iOS | Memory | Keychain (`kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`) |
+| Android | Memory | EncryptedSharedPreferences / Android Keystore |
+| React Native / Flutter | Memory | `react-native-keychain` / `flutter_secure_storage` |
+| Web SPA | Memory (a JS variable) | See below |
+
+**Never put tokens in URLs or logs.** On the web, avoid `localStorage` for the refresh token if you can: any script injected into the page (XSS) can read it. Options, from most to least secure:
+
+1. **Cookie mode (recommended for web):** turn on `refreshTokenCookie` and the API itself keeps the refresh token in an `HttpOnly; Secure` cookie. Page scripts never see it. See [below](#web-apps-refresh-token-in-a-cookie).
+2. **Backend-for-frontend:** a small server on your web domain calls this API and keeps the refresh token in its own cookie. Same protection; useful when you already have such a server.
+3. **In memory only:** the user signs in again after a page reload. Simple, and safe for admin dashboards.
+4. **`localStorage`:** acceptable only with a strict Content Security Policy and short sessions (`tokens.sessionDays`).
+
+## Calling the API
+
+```ts
+const response = await fetch('https://api.myapp.com/rides/mine', {
+  headers: { Authorization: `Bearer ${accessToken}` },
+});
+const body = await response.json();
+if (!body.success) handleError(body.code, body);
+```
+
+Decide by `code`, never by `message` (see [Error codes](error-codes.md)).
+
+## Refreshing tokens
+
+Refresh when a request fails with `401 INVALID_TOKEN`, or a little before `expiresIn` runs out. Two rules matter:
+
+1. **Store the new refresh token every time.** The old one is now used up.
+2. **Only one refresh at a time.** If five requests fail together and all five refresh with the same token, the second one looks like token theft and the session is ended.
+
+```ts
+let refreshInFlight: Promise<void> | null = null;
+
+async function refreshTokens(): Promise<void> {
+  // Every caller waits for the same refresh.
+  refreshInFlight ??= (async () => {
+    const response = await fetch('https://api.myapp.com/auth/refresh', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ refreshToken: await secureStore.get('refreshToken') }),
+    });
+    const body = await response.json();
+    if (!body.success) {
+      await signOutLocally();        // session over: go to sign-in
+      throw new Error(body.code);
+    }
+    accessToken = body.accessToken;
+    await secureStore.set('refreshToken', body.refreshToken);
+  })().finally(() => (refreshInFlight = null));
+  return refreshInFlight;
+}
+
+async function apiFetch(path: string, init: RequestInit = {}, isRetry = false): Promise<any> {
+  const response = await fetch(`https://api.myapp.com${path}`, {
+    ...init,
+    headers: { ...init.headers, Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
+  });
+  const body = await response.json();
+  if (response.status === 401 && body.code === 'INVALID_TOKEN' && !isRetry) {
+    await refreshTokens();
+    return apiFetch(path, init, true);
+  }
+  return body;
+}
+```
+
+On mobile, also make sure two app processes (e.g. the app and a widget) don't refresh at the same time.
+
+## Web apps: refresh token in a cookie
+
+```ts
+AuthModule.forRoot({
+  useFactory: () => ({
+    // ...
+    refreshTokenCookie: { allowedOrigins: ['https://app.myapp.com'] },
+  }),
+});
+```
+
+Your API must also allow these origins with credentials in CORS: `app.enableCors({ origin: ['https://app.myapp.com'], credentials: true })`.
+
+What changes, **only for requests whose `Origin` header is in `allowedOrigins`** (browsers add it themselves; mobile apps and servers don't send it, so they keep getting the refresh token in the body from the same API):
+
+- Every response that used to contain `refreshToken` now sets the cookie `__Host-refresh_token` (`HttpOnly; Secure; SameSite=Strict; Path=/`) and says `"refreshTokenInCookie": true` instead.
+- Refresh with an empty body and `credentials: 'include'`. A refresh that uses the cookie is refused (`403`) unless it comes from an allowed origin, which blocks cross-site request forgery.
+- Logout, logout everywhere, deactivate and delete account clear the cookie.
+
+```ts
+async function refreshTokens(): Promise<void> {
+  refreshInFlight ??= (async () => {
+    const response = await fetch('https://api.myapp.com/auth/refresh', {
+      method: 'POST',
+      credentials: 'include',                     // send the cookie
+      headers: { 'Content-Type': 'application/json' },
+      body: '{}',
+    });
+    const body = await response.json();
+    if (!body.success) {
+      await signOutLocally();
+      throw new Error(body.code);
+    }
+    accessToken = body.accessToken;               // the access token still lives in memory only
+  })().finally(() => (refreshInFlight = null));
+  return refreshInFlight;
+}
+```
+
+Send `credentials: 'include'` on sign-in requests too, so the browser stores the cookie. After a page reload, call `refreshTokens()` once to get a new access token.
+
+Options: `name` (default `__Host-refresh_token`), `domain` (to share with subdomains; not allowed with a `__Host-` name), `path` (default `/`), `sameSite` (default `Strict`; use `Lax` when the web app and the API are on different sites, e.g. `myapp.com` and `myapp-api.com`). Browsers accept `Secure` cookies on `http://localhost`, so cookie mode works in local development.
+
+## Changing email
+
+1. Signed in: `POST /auth/email/change` with `newEmail` (and `currentPassword` if the user has a password). Show "check your new inbox".
+2. Your page for the emailed link (`confirm_email_change`) calls `POST /auth/email/change/confirm` with the token.
+3. If the response is `403 RECENT_SIGN_IN_REQUIRED`, ask the user to sign in again, then retry.
+
+## Handling the sign-in result
+
+```ts
+async function handleSignInResponse(body: any) {
+  if (body.success && body.status === 'signed_in') return saveTokensAndEnterApp(body);
+  if (body.success && body.status === 'two_factor_required') return showTwoFactorScreen(body.challengeToken);
+
+  switch (body.code) {
+    case 'ACCOUNT_NOT_VERIFIED':
+      return showVerificationScreen(body.pendingVerifications, body.email, body.phoneNumber);
+    case 'ACCOUNT_DEACTIVATED':
+      return askToReactivate(body.reactivationToken);   // POST /auth/reactivate
+    case 'ACCOUNT_SUSPENDED':
+      return showContactSupport();
+    case 'VALIDATION_ERROR':
+      if (body.missingSignUpDetails) return showSignUpDetailsForm(body.missingSignUpDetails); // then retry
+      return showFormErrors(body.problems);
+    case 'TOO_MANY_REQUESTS':
+      return showRetryLater(body.retryAfterSeconds);
+    default:
+      return showMessage(body.message);
+  }
+}
+```
+
+## After sign-in
+
+- **Onboarding:** if `user.onboardingCompleted` is `false`, show your onboarding. When it's done, your backend calls `UsersService.completeOnboarding`.
+- **Pending verification:** `user.pendingVerifications` tells you what to verify, even for active users when the settings change later.
+- **Profile screen:** use `GET /auth/me` and `GET /auth/sign-in-methods`.
+
+## Links in emails
+
+Link tokens (`ev_`, `pr_`, `ml_`, `oi_`) arrive in your `emailSender`. Build links to your own pages or deep links:
+
+| Email | Example link | Page calls |
+|---|---|---|
+| Verify email | `https://myapp.com/verify-email?token=ev_...` | `POST /auth/email/verify` |
+| Reset password | `https://myapp.com/reset-password?token=pr_...` | `POST /auth/password/reset` (after the user types a new password) |
+| Magic link | `https://myapp.com/magic?token=ml_...` or `myapp://magic?token=...` | `POST /auth/magic-link/verify` |
+| Invitation | `https://myapp.com/join?token=oi_...` | `POST /auth/organizations/invitations/accept` (after sign-in) |
+
+Tips:
+
+- Call the API from the page **after a user action** (a button press), not automatically on load. Email security scanners open links automatically and would use up single-use tokens.
+- Remove the token from the address bar after reading it (`history.replaceState`).
+- Use universal links (iOS) or app links (Android) so magic links open the app.
+
+## Social sign-in on each platform
+
+| Platform | Google | Apple | Facebook |
+|---|---|---|---|
+| Web | [Google Identity Services](https://developers.google.com/identity/gsi/web): use the `credential` (ID token) | [Sign in with Apple JS](https://developer.apple.com/documentation/signinwithapplejs): `authorization.id_token` | Facebook JS SDK: `authResponse.accessToken` |
+| iOS | Google Sign-In SDK: `user.idToken` | `ASAuthorizationAppleIDCredential.identityToken` | Facebook iOS SDK access token |
+| Android | Credential Manager + `GetGoogleIdOption`: `idToken` | Web flow | Facebook Android SDK access token |
+
+Add every client id that issues tokens (web, iOS and Android each have one for Google) to `google.clientIds` / `apple.clientIds`.
+
+## Passkeys
+
+Web: use [`@simplewebauthn/browser`](https://simplewebauthn.dev/docs/packages/browser), see [Sign-in flows](sign-in-flows.md#passkeys). Native apps use the platform APIs (iOS `ASAuthorizationPlatformPublicKeyCredentialProvider`, Android Credential Manager) and need your domain's association files:
+
+- **iOS:** `https://myapp.com/.well-known/apple-app-site-association` with `webcredentials`
+- **Android:** `https://myapp.com/.well-known/assetlinks.json` with `delegate_permission/common.get_login_creds`
+
+Add the Android app's origin (`android:apk-key-hash:...`) to `passkeys.allowedOrigins`.

package/docs/code-walkthrough.md

@@ -0,0 +1,273 @@
+# Code walkthrough
+
+A guided tour of the source code, for anyone who wants to understand how the library works inside, maintain it, or contribute. Each flow is traced from the HTTP request to the database, naming the file and function at every hop, so you can open them side by side.
+
+If you only want to *use* the library, read [Getting started](getting-started.md) instead.
+
+## How to study it
+
+**Watch it run, then read it.** Reading code without seeing it run is slow. The fastest way to learn a flow is to stop the server in the middle of it:
+
+- In VS Code, open the command palette and run **JavaScript Debug Terminal**. In that terminal, run `npm run playground`. Source maps are on, so breakpoints in the `.ts` files under `src/` work.
+- Put a breakpoint on the first line of the function named in a flow below (for example `signInWithPassword` in `src/features/passwords/password-auth.service.ts`).
+- Send the request from Postman or Swagger. The debugger stops there; step through with **F10** (next line) and **F11** (into a function), and look at the variables panel.
+- Keep the dev dashboard (http://localhost:3000/dev) open to see the emails, events and webhooks each step produces, and a database viewer (TablePlus, DBeaver or `psql`) on the `auth_*` tables to see each row appear.
+
+**Suggested order:** the map, then "Every request", then email + password from register to refresh. Those cover most of the shared machinery; every other flow reuses it. Then read the other flows in any order.
+
+**Background you need:** NestJS modules, controllers, providers and decorators (the official NestJS "First steps" and "Guards" pages), and basic TypeORM repositories. Security terms are explained in the code comments and in [Security](security.md).
+
+---
+
+## The map
+
+```
+src/
+  index.ts                     everything apps can import (start here to see the public API)
+  auth.module.ts               AuthModule.forRoot(): wires every controller and service together
+  auth-options.ts              what an app must pass in (database, URLs, senders...)
+  auth-options.validation.ts   checks those options at startup
+  constants.ts                 every fixed value: routes, error codes, limits, default settings
+  common/                      small shared helpers (errors, rate limiting, encryption, crypto)
+  guards/                      AuthGuard and the decorators (@Public, @Roles, @CurrentUser...)
+  database/                    entities (tables) and migrations
+  features/                    one folder per feature
+    passwords/  passwordless/  social/  passkeys/  two-factor/     ways to sign in
+    sign-in/                   what happens after any method proves who the user is
+    sessions/                  sessions, access and refresh tokens
+    users/                     accounts and their life cycle
+    email-links/  one-time-codes/  notifications/                  links, codes, sending them
+    account/  email-change/    the signed-in user's own account
+    organizations/  api-keys/  webhooks/  events/  admin/  settings/  signing-keys/  maintenance/
+  integrations/                ready-made senders (MSG91 SMS, console email)
+```
+
+Most feature folders hold the same three kinds of file:
+
+| File | Job |
+|---|---|
+| `*.controller.ts` | HTTP only: route, request body, calls one service method. No business rules. |
+| `*.dto.ts` | The shape of request bodies (types and lengths). Unknown fields are rejected. |
+| `*.service.ts` | The rules: what is allowed, what is saved, which events and emails go out. |
+
+So for any endpoint: find its route in `ROUTES` (constants.ts), find the controller method with that route, and follow the one service call it makes.
+
+---
+
+## App startup
+
+**`AuthModule.forRoot()`** in `auth.module.ts`:
+
+- Calls the app's `useFactory` to get the `AuthOptions`, then `assertValidAuthOptions` (`auth-options.validation.ts`) stops the app with a clear list of problems if something is missing (no email sender, local key in production, no Redis in production...).
+- Registers every controller and service, plus three app-wide pieces:
+  - `AuthGuard` as `APP_GUARD`: runs before **every** route in the app.
+  - `AuthExceptionFilter` as `APP_FILTER`: turns every error into `{ success: false, code, message }`.
+  - `RefreshTokenCookieInterceptor` as `APP_INTERCEPTOR`: only does anything in cookie mode.
+- Background jobs start on `onApplicationBootstrap`: `WebhookDeliveryWorker` (every few seconds) and `DataRetentionService` (every hour).
+- On the first request needing a token, `SigningKeysService.getSigningKeys` creates the first signing key if there is none.
+
+What to notice: nothing is global or hidden. Every service gets what it needs through its constructor, and `AUTH_OPTIONS_TOKEN` is how they all reach the app's options (database, senders).
+
+---
+
+## Every request: the guard
+
+**`AuthGuard.canActivate`** in `guards/auth.guard.ts` decides who may call any route, in this order:
+
+- A route marked `@Public()` lets everyone in. If a token is sent anyway, it is read so `@CurrentUser()` works.
+- An `x-api-key` header on a route marked `@ApiKeyScopes(...)` → `ApiKeysService.verifyApiKey` (hash lookup) and a scope check.
+- Otherwise an `Authorization: Bearer` access token is required → `SessionService.verifyAccessToken` checks the signature (ES256, keys from `SigningKeysService`), issuer, audience, type and expiry. No database query: that is why access tokens are fast.
+- `@CheckSession()` / `@AdminOnly()` routes also call `SessionService.isSessionStillAllowed`, which asks the database whether the session is still open and the account still active (cached for a few seconds). This is how "sign out everywhere" and "suspend" take effect before the access token expires.
+- `@Roles(...)` / `@AdminOnly()` compare the roles in the token.
+- The caller is attached to the request; `@CurrentUser()`, `@CurrentUserId()` and `@CurrentCaller()` (`guards/auth.decorators.ts`) read it back in controllers.
+
+**When something fails**, services throw `new AuthError(AUTH_ERRORS.someError, extraFields?)` (`common/auth-error.ts`). `AuthExceptionFilter` (`common/auth-exception.filter.ts`) turns it into the JSON response with the right HTTP status. Unexpected errors are logged with their stack trace and answered with a generic `INTERNAL_SERVER_ERROR`.
+
+---
+
+## Email + password
+
+### Register: `POST /auth/register`
+
+`PasswordController.register` → **`PasswordAuthService.register`** (`features/passwords/password-auth.service.ts`):
+
+- `RateLimiterService.consume` counts sign-ups per IP (`common/rate-limiter.service.ts`; counters in Redis or memory).
+- `normalizeEmail` (`common/identifiers.ts`) lowercases and validates the email.
+- `assertRegistrationRules` applies the settings (sign-up open? allowed domains? names and terms required?).
+- `PasswordPolicyService.assertPasswordIsAcceptable` checks length and character rules, and asks haveibeenpwned.com (only the first 5 characters of the SHA-1 hash are sent) whether the password was in a breach.
+- **If the email already has an account**, the same "verification required" answer is returned as for a new account, so nobody can find out who is registered. If that existing account never verified, it gets a fresh verification email.
+- Otherwise, in one database transaction: `UsersService.createUser` (default roles, status `PENDING_VERIFICATION` or `ACTIVE`, event `user.created`) and the Argon2id hash (`hashPassword`) goes into `auth_passwords`.
+- If verification is needed, `EmailVerificationService.sendVerificationEmail` → `LinkTokensService.createLinkToken` (random token; only its SHA-256 hash is stored) → `NotificationsService.sendRequiredEmail` → the app's `emailSender`.
+
+### Verify email: `POST /auth/email/verify`
+
+`EmailVerificationService.verifyEmail` (`features/email-links/email-verification.service.ts`):
+
+- `LinkTokensService.useLinkToken` marks the token used **in one UPDATE ... WHERE used_at IS NULL**. If two clicks arrive together, only one gets a row back, so a link can never be used twice.
+- `UsersService.markEmailVerified` → `activateIfReady` moves the account to `ACTIVE` once nothing is left to verify (events `user.email_verified`, `user.activated`).
+
+### Login: `POST /auth/login`
+
+`PasswordController.login` → **`PasswordAuthService.signInWithPassword`**:
+
+- Rate limits per IP **and** per account (stops password guessing on one account from many IPs).
+- `PasswordPolicyService.verifyPassword` always runs the slow Argon2 check, even when the email has no account (against a dummy hash), so the response time doesn't reveal which emails exist.
+- Wrong email or password → `SignInService.recordFailedSignIn` (event `user.sign_in_failed`) and the same `INVALID_CREDENTIALS` either way.
+- Right password → the account's counter is reset, an old-style hash is upgraded (`needsRehash`), then **`SignInService.completeSignIn`**.
+
+### The shared ending: `completeSignIn`
+
+Every sign-in method (password, codes, links, Google, passkeys) ends in **`SignInService.completeSignIn`** (`features/sign-in/sign-in.service.ts`). This is the most important function to understand: because every method goes through it, no method can skip a check.
+
+- `assertAccountCanSignIn` looks at the account status:
+  - `PENDING_VERIFICATION` → `ACCOUNT_NOT_VERIFIED` with `pendingVerifications`
+  - `DEACTIVATED` → `ACCOUNT_DEACTIVATED` with a `reactivationToken`
+  - `SUSPENDED` → `ACCOUNT_SUSPENDED`
+- 2FA on (and not a passkey)? → `SignInChallengesService.createChallenge` stores a short-lived challenge and the response is `two_factor_required` with a `challengeToken`. No tokens yet.
+- Otherwise `startSignedInSession`:
+  - `SessionService.startSession` creates the `auth_sessions` row, then `issueTokens` signs the JWT access token (claims: user id `sub`, session id `sid`, roles, sign-in method `amr`...) and creates a refresh token (random, only its hash stored in `auth_refresh_tokens`).
+  - `UsersService.recordSignIn`, event `user.signed_in`, and a "new device" email if that setting is on.
+
+### Refresh: `POST /auth/refresh`
+
+`AccountController.refresh` → **`SessionService.refreshSession`** (`features/sessions/session.service.ts`):
+
+- The refresh token is marked used in **one UPDATE**, like link tokens. Exactly one of several parallel refreshes wins.
+- No row came back? Either the token is unknown, or it was **already used**: `handleRefreshTokenReuse` treats that as possible theft, ends the whole session and records `session.refresh_token_reused`.
+- The session must still be open and the account `ACTIVE`; then `issueTokens` returns a new pair. The old refresh token can never work again (rotation).
+
+### Logout
+
+`AccountController.logout` → `SignInService.signOut` → `SessionService.revokeSession` sets `revoked_at`. The access token still verifies until it expires (a few minutes), except on `@CheckSession()` routes, which see the revoked session immediately.
+
+### Forgot / reset / change password
+
+- `requestPasswordReset`: link token `reset_password`, same answer whether the email exists or not.
+- `resetPassword`: `useLinkToken` → save the new hash → `SessionService.revokeAllSessions` (everyone signed out) → event and "password changed" email.
+- `changePassword`: needs the current password; other devices are signed out, this one stays.
+
+---
+
+## Two-factor authentication
+
+All in `features/two-factor/two-factor.service.ts`:
+
+- **`startSetup`**: `createTotpSecret` (`common/crypto/totp.ts`), stored encrypted (`EncryptionService.encrypt`: AWS KMS or the local AES-GCM key), not yet active. Returns the `otpauth://` URL for the QR code.
+- **`confirmSetup`**: the first code from the app must be right (`checkAuthenticatorCode`). Then 2FA turns on, 10 backup codes are created (only hashes stored), and other devices are signed out.
+- **Sign-in**: `completeSignIn` returned a `challengeToken`. `POST /auth/2fa/verify` → **`verifySignInChallenge`**: `findOpenChallenge`, rate limit per user, then the code is checked as an authenticator code **or** a backup code. A code's 30-second time step is remembered (`last_used_time_step`), so the same code can't be replayed. Wrong code → `recordFailedAttempt` (the challenge dies after 5). Right code → `markChallengeUsed` → `SignInService.finishTwoFactorSignIn` → the same `startSignedInSession` as above.
+
+What to notice: the TOTP maths (`common/crypto/totp.ts`) is small and readable. It's a good place to see RFC 6238 implemented in about 100 lines.
+
+---
+
+## Passwordless
+
+All in `features/passwordless/passwordless-auth.service.ts`:
+
+- **Email code**: `sendEmailCode` → `OneTimeCodesService.createCode` (`features/one-time-codes/`; refuses if a code went out less than `resendAfterSeconds` ago; stores a salted hash) → email. `verifyEmailCode`:
+  - For a new email, the sign-up details are checked **before** the code is used, so a missing name doesn't waste the code.
+  - `OneTimeCodesService.verifyCode` (5 wrong tries kill the code).
+  - `UsersService.removeUnprovenPassword`: if someone registered this email long ago with *their* password and never verified it, proving the email now removes that password (account pre-hijacking protection).
+  - New user created already verified, or existing user marked verified, then `completeSignIn`.
+- **Magic link**: the same shape with a link token (`magic_sign_in`) instead of a code.
+- **Phone code**: the same shape with channel `sms`, sent by `NotificationsService.sendSmsCode` through the app's `smsSender` (e.g. `integrations/msg91-sms-sender.ts`).
+
+---
+
+## Social sign-in
+
+`SocialAuthService.signInWithProvider` (`features/social/social-auth.service.ts`):
+
+- `SocialProvidersService.verifyCredential` (`social-providers.service.ts`) checks the token with the provider: Google and Apple ID tokens are verified locally against their public keys (fetched and cached by `common/crypto/remote-public-keys.ts`), checking the audience is one of your client ids; Facebook tokens are checked with the Graph API and your app secret.
+- Then the decision described at the top of the file: already linked → sign in; provider proved the email and a user has it → link and sign in; email not proven but taken → refuse; nobody has it → create the user. Every branch ends in `completeSignIn`.
+
+---
+
+## Passkeys
+
+`features/passkeys/passkeys.service.ts`, built on `@simplewebauthn/server`:
+
+- **Adding one**: `startRegistration` creates WebAuthn options and stores the random challenge; the browser or phone creates a key pair and signs it; `finishRegistration` verifies the response and saves the public key (`auth_passkeys`).
+- **Signing in**: `startSignIn` → the device signs the challenge with the private key (which never leaves it) → `finishSignIn` checks the signature with the stored public key and the signature counter, then `completeSignIn` with method `passkey`, which skips the 2FA step because the passkey already required a fingerprint, face or PIN.
+
+---
+
+## Email change
+
+`features/email-change/email-change.service.ts`:
+
+- `requestEmailChange`: `confirmOwner` (current password, or a sign-in within the last 10 minutes for accounts without one), then a `change_email` link token is created for the **new** address, unless another account already has that address. The answer is the same in both cases.
+- `confirmEmailChange`: `useLinkToken` → update the email (the unique index catches a race with another account) → cancel old links → notice email to the **old** address → event → `activateIfReady`.
+
+---
+
+## Events, audit log and webhooks
+
+Every important action calls **`AuthEventsService.record`** (`features/events/auth-events.service.ts`). One call:
+
+- writes a row to `auth_audit_logs` (who, what, IP, device, details),
+- calls the app's `onEvent` handler,
+- inserts one `auth_webhook_deliveries` row (status `pending`) per webhook subscribed to that event.
+
+A failure here is logged but never breaks the action that caused it.
+
+**`WebhookDeliveryWorker.sendDueDeliveries`** (`features/webhooks/webhook-delivery.worker.ts`) runs every few seconds on every server:
+
+- Claims due deliveries with `FOR UPDATE SKIP LOCKED`, so two servers never send the same delivery.
+- Re-checks the URL is public (`common/network-safety.ts`) before each send, and never follows redirects (protection against requests to internal addresses).
+- Signs the body with HMAC (`webhook-signature.ts`; the receiver checks it with `verifyWebhookSignature`).
+- 2xx → `delivered`; anything else → retried with growing delays, then `failed`.
+
+---
+
+## Settings
+
+`SettingsService.getSettings` (`features/settings/settings.service.ts`) builds the settings in force from three layers: `DEFAULT_SETTINGS` (constants.ts) ← the app's `settings` in code ← admin changes stored in `auth_settings`. The result is cached for 10 seconds per server, which is how an admin change reaches every server without a restart.
+
+Every change goes through `settings.validation.ts`: field rules (types and ranges, e.g. `magicLink.expiresInMinutes` between 5 and 60) and `findSettingsConflicts` (combinations, e.g. not every sign-in method off).
+
+To add a setting: add it to `AuthSettings` (`settings.types.ts`), give it a default in `DEFAULT_SETTINGS`, add a rule in `settings.validation.ts`, use `settings.yourSection.yourField` in the service, and document it in [Configuration](configuration.md#reference).
+
+---
+
+## Organizations
+
+`features/organizations/organizations.service.ts`: members have a role (`owner`, `admin`, `member`) in `auth_organization_members`. `requireRole` and `assertMayManage` enforce who may do what (an admin can't touch owners; the last owner can't leave). Invitations are link-token-like rows in `auth_organization_invitations`. `switchActiveOrganization` stores the active organization on the session and issues a new access token with `org_id` and `org_role`.
+
+---
+
+## Background cleanup
+
+`DataRetentionService` (`features/maintenance/data-retention.service.ts`) runs every hour. Each step in its `steps` list names a table and a setting; the SQL condition for "old" is in `DATA_RETENTION_OLD_ROW_CONDITION` (constants.ts). Rows are deleted 5,000 at a time so locks stay short.
+
+---
+
+## Where the security decisions are
+
+Good places to slow down and read every comment:
+
+| Topic | Where |
+|---|---|
+| No account enumeration | `register`, `requestPasswordReset`, `sendEmailCode`, `requestEmailChange` all answer the same either way |
+| Timing-safe password check | `PasswordPolicyService.verifyPassword` (dummy hash) |
+| Single-use links, codes, refresh tokens | the one-UPDATE pattern in `useLinkToken`, `verifyCode`, `refreshSession` |
+| Refresh token theft detection | `SessionService.handleRefreshTokenReuse` |
+| Account pre-hijacking | `UsersService.removeUnprovenPassword` |
+| 2FA replay | `last_used_time_step` in `two-factor.service.ts` |
+| Secrets at rest | `common/encryption.service.ts` (KMS or AES-GCM, with a context per record) |
+| Webhook SSRF | `common/network-safety.ts` and the worker |
+| Cookie mode CSRF | `common/refresh-token-cookie.ts` (`assertAllowedOrigin`) |
+
+---
+
+## Practice exercises
+
+Small changes that force you through the code. Do them on a branch; the tests tell you if something broke.
+
+- **Trace a refresh token reuse** in the debugger: refresh once, then send the *old* refresh token again. Watch `handleRefreshTokenReuse` end the session, and find the `session.refresh_token_reused` row in `auth_audit_logs`.
+- **Add a setting** `security.notifyOnPasswordReset` following the recipe in "Settings" above.
+- **Add an event**: record `user.backup_codes_regenerated` in `TwoFactorService.regenerateBackupCodes` (add it to `AUTH_EVENTS` and to [Events](events.md)).
+- **Write a test** in `test/` for `buildRefreshCookie` (`common/refresh-token-cookie.ts`) checking every cookie attribute.
+- **Read a test**: `scripts/e2e-check.js` and `scripts/http-flow-check.js` are executable descriptions of every flow; reading them next to this page shows what each flow must guarantee.
+
+Before opening a pull request: `npm run typecheck && npm test && npm run build`, and see [Architecture](architecture.md#design-rules-for-contributors) for the house rules.