@techelusive/nest-auth 0.0.0-stage → 0.2.0

package/docs/manual-testing.md

@@ -0,0 +1,215 @@
+# Manual testing (before publishing)
+
+The **playground** runs the library on your machine with every feature switched on. Emails and SMS never leave your computer: they land in a dev inbox you can see. Three ways to drive it:
+
+| Tool | Best for | Where |
+|---|---|---|
+| **Dev dashboard** | Watching what happens: emails, SMS codes, live auth events, received webhooks. Also passkeys and Google sign-in, which need a browser | http://localhost:3000/dev |
+| **Postman** | Running every flow step by step: tokens, codes and links are captured automatically | import `api/techelusive-authentication.postman_collection.json` |
+| **Swagger UI** | Browsing and trying every endpoint in the browser | http://localhost:3000/docs |
+
+## 1. Start the playground
+
+You need Node.js 22+ and Docker Desktop.
+
+```bash
+cd techelusive-authentication
+npm install                 # once
+npm run playground:db       # starts PostgreSQL (and Redis) in Docker
+npm run playground          # builds and starts the API on http://localhost:3000
+```
+
+You should see:
+
+```
+[Playground] Dev dashboard:  http://localhost:3000/dev
+[Playground] Swagger UI:     http://localhost:3000/docs
+[Playground] Postman:        import api/techelusive-authentication.postman_collection.json
+```
+
+The database and its tables are created automatically on start. If a PostgreSQL already installed on your Mac (Homebrew, Postgres.app) is using port 5432, the playground uses that one instead of Docker's, which is fine. To use Docker's anyway, stop the local one first (`brew services stop postgresql@16`).
+
+To start from an empty database:
+
+```bash
+docker compose -f playground/docker-compose.yml down -v && npm run playground:db
+```
+
+Optional settings: copy `playground/.env.example` to `playground/.env` and uncomment what you need (or set them in the shell). Restart the playground after changing it.
+
+| Variable | Effect |
+|---|---|
+| `GOOGLE_CLIENT_ID` | Turns on Google sign-in and shows the Google button on the dashboard. Create a "Web application" OAuth client in Google Cloud Console with `http://localhost:3000` as an authorized JavaScript origin |
+| `APPLE_CLIENT_ID`, `FACEBOOK_APP_ID` + `FACEBOOK_APP_SECRET` | Turn on Apple / Facebook (tokens must then be pasted into Postman's `socialToken`) |
+| `CHECK_BREACHED_PASSWORDS=true` | Turns on the data-breach password check, which is off in the playground so any password meeting the rules works. Apps using the library have it on by default |
+| `REDIS_URL=redis://localhost:6379` | Rate limits counted in Redis instead of memory |
+| `DATABASE_URL` | A different database (default `postgres://postgres:postgres@localhost:5432/techelusive_playground`) |
+
+### Real emails, real SMS and Google sign-in (optional)
+
+Every message always appears on the dashboard. To also receive them for real, add these to `playground/.env` and restart:
+
+**Email (Resend, free):** sign up at resend.com → API Keys → create one → `RESEND_API_KEY=re_...`. Until you verify your own domain, Resend only delivers to the email address you signed up with, so test with that address. Links in the emails open the dashboard and show the token to paste into Postman.
+
+**SMS (MSG91):** `MSG91_AUTH_KEY`, `MSG91_TEMPLATE_ID` and `MSG91_CODE_VARIABLE` (the variable in your template, e.g. `otp`). Indian numbers need a DLT-approved template, so SMS is usually the last thing to set up; until then, use the codes on the dashboard.
+
+If a real send fails, the terminal shows a warning and the flow carries on: the code is still on the dashboard.
+
+**Google with the OAuth 2.0 Playground** (developers.google.com/oauthplayground):
+
+1. Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID → **Web application**.
+   - Authorized JavaScript origins: `http://localhost:3000` (for the dashboard button)
+   - Authorized redirect URIs: `https://developers.google.com/oauthplayground`
+2. Put the client ID in `playground/.env` as `GOOGLE_CLIENT_ID=...` and restart the playground.
+3. In the OAuth Playground, click the gear icon → tick **Use your own OAuth credentials** → paste your client ID and secret. Without this the token is issued for Google's own client and the library rejects it (`INVALID_SOCIAL_TOKEN`), which is correct.
+4. Step 1: in "Input your own scopes" enter `openid email profile` → **Authorize APIs** → sign in.
+5. Step 2: **Exchange authorization code for tokens** → copy the `id_token` value (not the access token).
+6. Postman → folder 5 → **Sign in with provider**, with `provider` = `google` (`POST /auth/social/google`): set `socialToken` to the id_token and send. A new user is created and signed in, or an existing user with the same verified email is linked.
+
+ID tokens expire after an hour; repeat step 5 for a fresh one. The **Sign in with Google** button on the dashboard does the same thing in one click.
+
+## 2. Use Postman
+
+1. Postman → **Import** → choose `api/techelusive-authentication.postman_collection.json`.
+2. Open the collection's **Variables** tab to see `email`, `password`, `secondEmail` and `phoneNumber`. Change them if you like.
+3. Run requests **top to bottom within a folder**. The scripts do the copying for you:
+   - sign-in responses save `accessToken`, `refreshToken`, `sessionId`, `userId`, and `challengeToken` when 2FA is on,
+   - "(from inbox)" requests read the latest code or link token from the dev inbox before sending,
+   - 2FA requests compute the current authenticator code from the saved `totpSecret`,
+   - ids (`organizationId`, `webhookId`, `apiKeyId`...) are saved when created.
+4. Open **View → Show Postman Console** to see what was saved and the `code` of any error.
+
+Protected requests use the collection's Bearer token `{{accessToken}}`. Public ones are set to "No auth".
+
+## 3. Use Swagger
+
+Open http://localhost:3000/docs → pick an endpoint → **Try it out** → **Execute**. After any sign-in (Login, verify code, refresh...) Swagger authorizes itself with the returned access token, so protected endpoints work right away. Codes and link tokens are on the dev dashboard.
+
+## 4. Test checklist
+
+Work through these in order; each line says what you should see. Folder names refer to Postman.
+
+### Email + password (folder 1)
+
+| # | Do | Expect |
+|---|---|---|
+| 1 | Register | `201`, `status: "verification_required"`, `pendingVerifications: ["email"]`; a `verify_email` message in the inbox; event `user.created` |
+| 2 | Register again with the same email | Exactly the same response; no second account (no enumeration) |
+| 3 | Login before verifying | `403 ACCOUNT_NOT_VERIFIED` with `pendingVerifications: ["email"]` |
+| 4 | Login with a wrong password, then with an unknown email | `401 INVALID_CREDENTIALS` both times, same message |
+| 5 | Verify email (token from inbox) | `status: "ACTIVE"`; event `user.email_verified`, `user.activated` |
+| 6 | Verify email again with the same token | `400 INVALID_TOKEN` (links work once) |
+| 7 | Login | `status: "signed_in"`; tokens saved; event `user.signed_in`. On the dashboard, the claims show `roles: ["user"]`, `amr: ["password"]` |
+| 8 | Register with a short password (edit the body: `"password": "short"`) | `400 INVALID_PASSWORD`, `requirements: ["at least 10 characters"]` |
+| 9 | Admin > Change settings `{ "password": { "rejectBreachedPasswords": true } }` (or start with `CHECK_BREACHED_PASSWORDS=true`), then Register with `"password": "password1234"` | `400 INVALID_PASSWORD` with the data-breach message (needs internet) |
+| 10 | Register with an extra field such as `"roles": ["admin"]` | `400 VALIDATION_ERROR`, "property roles should not exist" |
+| 11 | Forgot password, then Reset password (token from inbox) | Success; you are signed out everywhere; `user.password_changed`. Then Login with `{{newPassword}}`, and set `password` = `newPassword` in the variables |
+| 12 | Change password | Success; other devices signed out, this one still works; a `password_changed` notice in the inbox |
+| 13 | Login with a wrong password 11 times | Eventually `429 TOO_MANY_REQUESTS` with `retryAfterSeconds` |
+
+### Passwordless (folder 2)
+
+| # | Do | Expect |
+|---|---|---|
+| 14 | Send email code → Send it again immediately | Second time `429 TOO_MANY_REQUESTS` (`retryAfterSeconds: 60`) |
+| 15 | Verify email code but remove `firstName` from the body | `400 VALIDATION_ERROR` with `missingSignUpDetails`; then send with the names, using the **same** code → signed in (the code was not used up) |
+| 16 | Verify email code with a wrong code | `400 INVALID_OTP` with `attemptsLeft` |
+| 17 | Send magic link → Verify magic link | Signed in; the link fails on a second use |
+| 18 | Send phone code → Verify phone code | The SMS appears in the inbox (`sms_code`); signed in as a new phone-only user |
+| 19 | Send phone code to `+15555550100` after setting `phoneOtp.allowedCountryCodes: ["+91"]` via Admin > Change settings | `400 PHONE_COUNTRY_NOT_ALLOWED` |
+
+### Account and sessions (folder 3)
+
+| # | Do | Expect |
+|---|---|---|
+| 20 | Get my profile, Update my profile | Profile shows the new name and `metadata` |
+| 21 | My devices | Several sessions; the current one has `isCurrentDevice: true` |
+| 22 | Refresh tokens → run it **again** with the old refresh token (Postman saved the new one, so paste the old value) | First succeeds; second `401 INVALID_TOKEN`, the session is ended, and event `session.refresh_token_reused` |
+| 23 | Logout, then Get my profile | `401 INVALID_TOKEN` on `/auth/me` (it checks the session live) |
+| 24 | Deactivate → Login → Reactivate | Login gives `403 ACCOUNT_DEACTIVATED` (reactivationToken saved automatically); Reactivate signs you in |
+| 25 | Delete my account → Login | Login `401 INVALID_CREDENTIALS`; event `user.deleted`. (Do this last, or use a second user) |
+
+### Two-factor (folder 4)
+
+| # | Do | Expect |
+|---|---|---|
+| 26 | Start 2FA setup | `secret` and `authenticatorAppUrl` (scan the URL as a QR code in Google/Microsoft Authenticator to try a real app) |
+| 27 | Enable 2FA | 10 backup codes; other devices signed out |
+| 28 | Login | `status: "two_factor_required"` with `challengeToken` |
+| 29 | Verify 2FA sign-in | `signed_in`; claims show `amr: ["password", "two_factor"]` |
+| 30 | Verify 2FA sign-in again with the same code in the same 30 seconds | `401 INVALID_OTP` (codes can't be replayed) |
+| 31 | Login, then Verify 2FA sign-in with `{{backupCode}}` as the code | Signed in; the same backup code fails next time |
+| 32 | Disable 2FA | Login no longer asks for a code |
+
+### Passkeys (dashboard)
+
+| # | Do | Expect |
+|---|---|---|
+| 33 | Sign in on the dashboard → **Add a passkey** | The browser asks for Touch ID / Windows Hello / phone; "Passkey added"; event `user.passkey_added` |
+| 34 | Logout → **Sign in with a passkey** | Signed in without email or password; no 2FA step even if 2FA is on |
+| 35 | Postman: List my passkeys → Remove passkey | Removed. If it's the only sign-in method left: `409 LAST_SIGN_IN_METHOD` |
+
+### Social (dashboard / folder 5)
+
+| # | Do | Expect |
+|---|---|---|
+| 36 | With `GOOGLE_CLIENT_ID` set: the Google button on the dashboard | Signed in; a new user is created, or an existing user with the same verified email is linked (`user.social_account_linked`) |
+| 37 | Send `{"token": "garbage"}` to Sign in with provider | `401 INVALID_SOCIAL_TOKEN` |
+
+### Organizations (folder 7)
+
+| # | Do | Expect |
+|---|---|---|
+| 38 | Create organization → create it again | Second time `409 ORGANIZATION_SLUG_TAKEN` |
+| 39 | Invite member | An `organization_invitation` message for `{{secondEmail}}` |
+| 40 | Sign in as `{{secondEmail}}` (folder 2, email code) → Accept invitation | Joined as `member` |
+| 41 | Switch active organization | The new access token has `org_id` and `org_role: "member"` (see the claims on the dashboard, or decode at jwt.io) |
+| 42 | As the member: Update organization | `403 FORBIDDEN` |
+| 43 | As the owner (Login as `{{email}}`): Remove member with your own id while you are the only owner | `409 LAST_OWNER` |
+
+### Admin, API keys and webhooks (folder 8)
+
+| # | Do | Expect |
+|---|---|---|
+| 44 | Search users before being admin | `403 FORBIDDEN` |
+| 45 | Folder 10: Make me admin (or the dashboard button) → folder 3: Refresh tokens | Claims now include `admin`; Search users works |
+| 46 | Search users → copy the second user's `id` into the `userId` variable → Suspend user → that user signs in (folder 2) | `403 ACCOUNT_SUSPENDED`; their sessions are ended. Unsuspend user afterwards, and set `userId` back to yours |
+| 47 | Change settings `{ "magicLink": { "enabled": false } }` → Send magic link | `403 SIGN_IN_METHOD_DISABLED`, no restart needed |
+| 48 | Change settings `{ "tokens": { "accessTokenMinutes": 999 } }` | `400 INVALID_SETTINGS` with a `problems` list |
+| 49 | Create webhook (to the playground receiver) → Login | The dashboard's "Webhooks received" shows `user.signed_in` with **signature valid** |
+| 50 | Create webhook with `"url": "https://169.254.169.254/x"` | `400 UNSAFE_WEBHOOK_URL` |
+| 51 | Create API key → folder 10: Call an app route with the API key → Revoke API key → call it again | Key returned once; the call succeeds (`calledBy` shows the key); after revoking `401 INVALID_API_KEY` |
+| 52 | Audit log | Every action above, newest first, with IP and user agent |
+| 53 | Rotate signing key → Get my profile with the old access token | Still works; JWKS now lists two keys |
+| 54 | Stats | Users by status, active sessions, last-24-hours sign-ins and failures |
+| 55 | Run data cleanup now | `removed` counts per step (mostly 0 on a fresh database: rows must be older than the `retention` settings) |
+
+### Email change, data export, health (folder 3)
+
+| # | Do | Expect |
+|---|---|---|
+| 56 | Change my email with a wrong `currentPassword` | `401 INVALID_CREDENTIALS` |
+| 57 | Change my email (to `{{changedEmail}}`) | Same success message whatever the address; a `confirm_email_change` message to the new address |
+| 58 | Change my email to `{{secondEmail}}` (an existing account) | The same success message, but no message arrives (no enumeration) |
+| 59 | Confirm email change (token from inbox) → run it again | First: `user.email` is the new address, verified; the old address gets `email_changed`. Second: `400 INVALID_TOKEN`. Then set the `email` variable to `{{changedEmail}}` |
+| 60 | Sign in with a phone code (folder 2) → Change my email without `currentPassword` | Works right after signing in; more than 10 minutes later `403 RECENT_SIGN_IN_REQUIRED` |
+| 61 | Download my data | Profile, devices, organizations, security history; no hashes, secrets or tokens |
+| 62 | Health check | `200`, `"database": "ok"` (stop PostgreSQL to see `503`) |
+
+### Web cookie mode
+
+Start with `REFRESH_TOKEN_COOKIE_ORIGINS=http://localhost:3000 npm run playground`, then run `npm run check:cookies` in another terminal. It checks the cookie flags, refresh with the cookie, cross-site refusal, rotation, mobile clients on the same API and logout. Postman doesn't send an `Origin` header, so in Postman everything behaves like a mobile app.
+
+When everything matches, record the version and date in `CHANGELOG.md` and publish.
+
+## Automated checks (run these too)
+
+```bash
+npm run typecheck && npm test && npm run build
+createdb -h localhost -U postgres auth_e2e   # once: an empty database for e2e
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/auth_e2e npm run e2e
+npm run playground                                                                   # in a second terminal
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/techelusive_playground npm run check:http
+```
+
+`npm run e2e` creates and drops its own tables, so point it at an empty database (not the playground's). `npm run check:http` runs every flow over HTTP against the running playground (38 checks); start the playground on an empty database for it (`dropdb techelusive_playground`), since it registers fixed test users. CI runs all of these on every change.

package/docs/organizations.md

@@ -0,0 +1,86 @@
+# Organizations
+
+Organizations let users work in teams: companies, workspaces, fleets, households. A user can belong to many organizations, with a different role in each. Turn them on with `organizations.enabled: true`.
+
+## Roles
+
+| Role | Can |
+|---|---|
+| `owner` | Everything, including deleting the organization and managing other owners |
+| `admin` | Rename the organization, invite people, change roles of members and admins, remove members and admins |
+| `member` | See the organization and its members |
+
+Rules the API enforces:
+
+- **Creators:** whoever creates an organization becomes its owner.
+- **Owners:** only an owner can make someone an owner, demote an owner, or remove an owner.
+- **Last owner:** an organization always keeps at least one owner (`LAST_OWNER`).
+- **Leaving:** anyone can leave by removing themselves.
+- **Outsiders:** non-members get `NOT_FOUND`, not `FORBIDDEN`, so they can't discover which organizations exist.
+
+These organization roles are separate from app-wide roles (`user.roles`, e.g. `admin`), which are managed by app admins.
+
+## Invitations
+
+```http
+POST /auth/organizations/:id/invitations
+{ "email": "ravi@example.com", "role": "member" }
+```
+
+The library asks your `emailSender` to send an `organization_invitation` email with a `token`. Link it to a page in your app. Once the invited person has signed in, the page calls:
+
+```http
+POST /auth/organizations/invitations/accept
+{ "token": "oi_..." }
+```
+
+- **Security:** the signed-in user's **verified email must match** the invited email, so a forwarded link is useless to anyone else.
+- **Lifetime:** invitations expire after `organizations.invitationExpiresInDays` (7 days by default).
+- **Replacement:** sending a new invitation to the same email cancels the old one.
+- **Cancelling:** an admin can cancel an invitation with `DELETE .../invitations/:invitationId`.
+
+## The active organization
+
+A device works in one organization at a time:
+
+```http
+POST /auth/organizations/switch
+{ "organizationId": "a1b2..." }
+→ { "accessToken": "eyJ...", "expiresIn": 900, "organizationId": "a1b2..." }
+```
+
+Replace the stored access token with the returned one. From then on, every token for this device (including after refresh) carries:
+
+```json
+{ "org_id": "a1b2...", "org_role": "admin" }
+```
+
+Send `{ "organizationId": null }` to leave organization mode.
+
+## Scoping your own data
+
+Store `organization_id` on your own rows and filter by the claim:
+
+```ts
+@Get('vehicles')
+listVehicles(@CurrentUser() user: AccessTokenClaims) {
+  if (!user.org_id) throw new AuthError(AUTH_ERRORS.forbidden);
+  return this.vehicles.find({ where: { organizationId: user.org_id } });
+}
+
+@Delete('vehicles/:id')
+removeVehicle(@CurrentUser() user: AccessTokenClaims) {
+  if (user.org_role !== ORGANIZATION_ROLE.owner && user.org_role !== ORGANIZATION_ROLE.admin) throw new AuthError(AUTH_ERRORS.forbidden);
+  // ...
+}
+```
+
+When a member is removed, their devices leave the organization at the next token refresh. For immediate effect on sensitive routes, add `@CheckSession()` and re-check membership with `OrganizationsService.listMembers()` or your own query.
+
+## API keys for an organization
+
+An API key created with an `organizationId` acts on behalf of that organization. In routes marked `@ApiKeyScopes()`, read it from `@CurrentCaller().apiKey.organizationId`.
+
+## Deleting
+
+`DELETE /auth/organizations/:id` (owners only) removes the organization, its memberships, invitations and API keys. Delete your own organization data in an `onEvent` handler for `organization.deleted`.

package/docs/production-checklist.md

@@ -0,0 +1,60 @@
+# Production checklist
+
+Go through this list before launch. Each item says **why**, so you can make an informed exception.
+
+## Configuration
+
+- [ ] **`NODE_ENV=production`.** At startup, this refuses a local encryption key, a non-https issuer, and a missing `redisUrl` (unless `singleServer: true`). `ConsoleEmailSender` throws on its first send.
+- [ ] **`issuer` is your real https API URL.** It is written into every token. Changing it later signs everyone out, because existing tokens fail the issuer check.
+- [ ] **Encryption uses AWS KMS** (`{ awsKmsKeyId, awsRegion }`).
+  - Create a symmetric KMS key and give the API's IAM role only `kms:Encrypt` and `kms:Decrypt` on it.
+  - Turn on automatic key rotation in KMS.
+  - **Moving an existing database from the local key to KMS:** configure `{ awsKmsKeyId, awsRegion, legacyLocalKey: '<old localKey>' }`. Older values (2FA secrets, webhook secrets, the signing key) still decrypt, and everything new is encrypted with KMS. Then rotate the signing key (`POST /auth/admin/signing-keys/rotate`) so the active key is KMS-protected. Without `legacyLocalKey`, users with 2FA would be locked out.
+- [ ] **A real `emailSender`** (SES, Resend, Postmark...) with SPF, DKIM and DMARC set up for your sending domain, so codes don't land in spam.
+- [ ] **SMS:** a DLT-registered template on MSG91 (India), and `phoneOtp.allowedCountryCodes` limited to the countries you serve. This limits "SMS pumping" fraud costs.
+- [ ] **Secrets come from a secret manager** (AWS Secrets Manager / SSM): database URL, KMS key id, MSG91 key, Facebook app secret.
+- [ ] **Settings reviewed:** sign-in methods, `defaultRoles`, `adminRoles`, token lifetimes, `allowedEmailDomains`.
+
+## Infrastructure
+
+- [ ] **`app.set('trust proxy', 1)`**, or the exact number of proxies in front of the app.
+  - **Too low:** every user shares the load balancer's IP, so rate limits hit everyone at once.
+  - **Too high:** attackers can fake their IP with an `X-Forwarded-For` header and dodge rate limits.
+- [ ] **Redis (`redisUrl`)**. Required in production: without it each server counts rate limits separately, which multiplies the allowed attempts. Use a managed Redis (ElastiCache) with TLS (`rediss://`). Only a deployment with exactly one server process may set `singleServer: true` instead.
+- [ ] **Health check:** point the load balancer / uptime monitor at `GET /auth/health` (503 when PostgreSQL or Redis don't answer).
+- [ ] **TLS everywhere:** HTTPS at the load balancer with HSTS, and TLS to Postgres and Redis.
+- [ ] **CORS** allows only your web app origins (with `credentials: true` if you use cookie mode). Mobile apps don't need CORS.
+- [ ] **Web apps use cookie mode** (`refreshTokenCookie`), so the refresh token is out of reach of page scripts. See [Client integration](client-integration.md#web-apps-refresh-token-in-a-cookie).
+- [ ] **`helmet()`** for security headers on any web pages you serve.
+- [ ] **Request body size limit** (Express's default 100 kB is fine; don't raise it for auth routes).
+
+## Database
+
+- [ ] **Migrations run in your deploy pipeline** (`typeorm migration:run`), never `synchronize`.
+- [ ] **Backups** are encrypted, with point-in-time recovery turned on, and restores are tested.
+- [ ] **Least-privilege database user:** the app needs only read/write on its tables, not superuser.
+- [ ] **Data retention reviewed.** Old sessions, codes, links, webhook deliveries and audit entries are deleted every hour automatically. Check that `retention.auditLogDays` (default 365) matches your legal requirements. See [Data retention](configuration.md#data-retention).
+
+## Monitoring and response
+
+- [ ] **Alerts on events** (via `onEvent` or a webhook to your alerting):
+  - `session.refresh_token_reused`: possible token theft.
+  - Spikes of `user.sign_in_failed`: credential stuffing.
+  - Spikes of `TOO_MANY_REQUESTS` responses.
+- [ ] **Logs:** forward server logs. Unexpected errors are logged with stack traces, while clients only see `INTERNAL_SERVER_ERROR`.
+- [ ] **Failed webhooks:** watch `GET /auth/admin/webhooks/:id/deliveries` for `failed` deliveries.
+- [ ] **Dashboard numbers:** `GET /auth/admin/stats` gives accounts by status, active sessions and the last 24 hours of sign-ins, failures and refresh-token reuses.
+- [ ] **Incident runbook:**
+  - **Leaked signing key:** `POST /auth/admin/signing-keys/rotate`, then rotate again two days later.
+  - **Compromised account:** suspend it, then `POST /auth/admin/users/:id/logout-all`.
+  - **Leaked API key:** `DELETE /auth/admin/api-keys/:id`.
+  - **Leaked webhook secret:** `POST .../rotate-secret`.
+- [ ] **First admin** created, using a strong password plus 2FA or a passkey.
+
+## Client apps
+
+- [ ] Refresh tokens are stored securely and **only one refresh runs at a time** ([Client integration](client-integration.md#refreshing-tokens)).
+- [ ] Email link pages act on a button press, not on page load (security scanners open links). This includes the `confirm_email_change` page.
+- [ ] A "download my data" button calls `GET /auth/me/export` (and adds your app's own data).
+- [ ] Google, Apple and Facebook client ids for **every** platform are in the settings.
+- [ ] For passkeys, `apple-app-site-association` and `assetlinks.json` are published, and `passkeys.allowedOrigins` lists every web origin and Android app hash.

package/docs/protecting-routes.md

@@ -0,0 +1,147 @@
+# Protecting routes
+
+`AuthModule` installs `AuthGuard` for the whole app, so **every route requires a signed-in user unless you say otherwise**. Forgetting a decorator therefore fails closed, never open.
+
+## Decorators
+
+```ts
+import { Public, Roles, CheckSession, ApiKeyScopes, AdminOnly, CurrentUser, CurrentUserId, CurrentCaller, AccessTokenClaims } from '@techelusive/nest-auth';
+
+@Controller('orders')
+export class OrdersController {
+  @Get('menu')
+  @Public()                                   // anyone; @CurrentUser() still works if a token is sent
+  getMenu() {}
+
+  @Get('mine')                                 // any signed-in user (default)
+  listMine(@CurrentUser() user: AccessTokenClaims) {}
+
+  @Post()
+  @Roles('seller', 'admin')                    // at least one of these roles
+  create(@CurrentUserId() userId: string) {}
+
+  @Post(':id/refund')
+  @CheckSession()                              // also check the session is still active right now
+  refund() {}
+
+  @Get('export')
+  @ApiKeyScopes('orders:read')                 // servers with an API key holding this scope (users still allowed)
+  export(@CurrentCaller() caller) {}            // caller.user or caller.apiKey
+
+  @Delete(':id')
+  @AdminOnly()                                 // roles in settings.admin.adminRoles, checked live
+  remove() {}
+}
+```
+
+Decorators work on methods and on whole controllers. A method decorator wins over its controller's.
+
+## What's in the token
+
+`@CurrentUser()` returns the access-token claims:
+
+| Claim | Example | Meaning |
+|---|---|---|
+| `sub` | `"5f0c..."` | User id. Use it as the foreign key in your tables. |
+| `sid` | `"8c1e..."` | Session (device) id |
+| `roles` | `["user"]` | App-wide roles |
+| `amr` | `["password", "two_factor"]` | How the user signed in. Require `two_factor` for very sensitive actions if you like. |
+| `org_id`, `org_role` | `"a1b2..."`, `"admin"` | The organization chosen on this device, if any ([Organizations](organizations.md)) |
+| `iss`, `aud` | `"https://api.myapp.com"` | Your issuer |
+| `iat`, `exp`, `jti` | | Issued at, expiry, unique id |
+
+`@CurrentUserId()` returns just the user id (`sub`).
+
+## How fresh is the token?
+
+An access token is valid until it expires (`tokens.accessTokenMinutes`, 15 by default). Within that window, a user who signed out, was suspended or lost a role still holds a working token. Two ways to close the gap:
+
+- **`@CheckSession()`** on sensitive routes checks in the database that the session is still active and the user is `ACTIVE`. The answer is cached for 5 seconds per server, which costs at most one small query per user every 5 seconds. `@AdminOnly()` always does this.
+- **Shorter access tokens.** For example `tokens.accessTokenMinutes: 5`, at the cost of more refreshes.
+
+Role changes appear in the user's **next** access token (at the next refresh).
+
+## Opt-in instead of protect-all
+
+```ts
+AuthModule.forRoot({ protectAllRoutes: false, useFactory: ... })
+
+@UseGuards(AuthGuard)       // then protect controllers explicitly
+@Controller('orders')
+export class OrdersController {}
+```
+
+## Verifying tokens in other services
+
+Access tokens are standard JWTs signed with ES256. Any service in any language can verify them using the public keys at `GET https://api.myapp.com/.well-known/jwks.json`, with no shared secret.
+
+Node.js with [`jose`](https://github.com/panva/jose):
+
+```ts
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+
+const keys = createRemoteJWKSet(new URL('https://api.myapp.com/.well-known/jwks.json'));
+
+export async function verifyAccessToken(token: string) {
+  const { payload } = await jwtVerify(token, keys, {
+    issuer: 'https://api.myapp.com',
+    audience: 'https://api.myapp.com',
+    algorithms: ['ES256'],
+    typ: 'at+jwt',
+  });
+  return payload; // payload.sub, payload.roles, ...
+}
+```
+
+Python with [PyJWT](https://pyjwt.readthedocs.io):
+
+```python
+import jwt
+jwks = jwt.PyJWKClient("https://api.myapp.com/.well-known/jwks.json")
+
+def verify_access_token(token: str) -> dict:
+    key = jwks.get_signing_key_from_jwt(token).key
+    return jwt.decode(token, key, algorithms=["ES256"],
+                      issuer="https://api.myapp.com", audience="https://api.myapp.com")
+```
+
+Always pin the algorithm (`ES256`) and check `iss` and `aud`. These other services can't see sign-outs before expiry. If they need that, have them call an endpoint on the main API that is marked `@CheckSession()`.
+
+## API keys (server to server)
+
+Other servers (partners, cron jobs, internal services) call your API with a key instead of a user token:
+
+```http
+GET /orders/export
+x-api-key: ak_3Fx9...
+```
+
+- An admin creates keys with `POST /auth/admin/api-keys` ([details](admin-api-keys-webhooks.md#api-keys)).
+- Keys only work on routes marked `@ApiKeyScopes(...)`, and only if they hold **all** the listed scopes. On any other route, an API key is not accepted.
+- In the route, `@CurrentCaller()` returns `{ apiKey: { id, name, scopes, organizationId } }`.
+
+## Using the services from your own code
+
+The module is global, so inject its services anywhere:
+
+```ts
+@Injectable()
+export class ProfileService {
+  constructor(private readonly users: UsersService) {}
+
+  async finishOnboarding(userId: string, request: RequestContext) {
+    await this.users.completeOnboarding(userId, request);
+  }
+}
+```
+
+| Service | Useful methods |
+|---|---|
+| `UsersService` | `findUserById`, `findUserByEmail`, `completeOnboarding`, `updateProfile`, `setRoles`, `suspendUser`, `deleteUser`, `toPublicProfile` |
+| `SessionService` | `listActiveSessions`, `revokeSession`, `revokeAllSessions`, `verifyAccessToken` |
+| `OrganizationsService` | `listMyOrganizations`, `listMembers`, `createOrganization` |
+| `SettingsService` | `getSettings()`, the settings in force right now |
+| `AuthEventsService` | `record()`, to write your own entries to the audit log |
+| `ApiKeysService`, `WebhooksService`, `TwoFactorService`, `SigningKeysService` | Same operations as the admin API |
+
+Use `@CurrentRequest()` in controllers to get the `RequestContext` (IP and user agent). Use `SYSTEM_REQUEST` in scripts and jobs.

package/docs/security.md

@@ -0,0 +1,61 @@
+# Security design
+
+This page explains how the library protects users, so you can review it, explain it to auditors, and avoid undoing a protection by accident. To report a vulnerability, see [SECURITY.md](../SECURITY.md).
+
+## Secrets at rest
+
+| Secret | How it is stored |
+|---|---|
+| Passwords | Argon2id (64 MiB, 3 iterations), re-hashed automatically if the parameters are raised |
+| Refresh, link, challenge and API-key tokens | SHA-256 hash only (they are 256-bit random, so a fast hash is safe) |
+| Email/SMS codes and backup codes | Salted SHA-256, with attempt limits |
+| Token-signing private key, 2FA secrets, webhook secrets | Encrypted with AWS KMS (or AES-256-GCM with a local key in development), bound to their row so a value copied elsewhere won't decrypt |
+
+A full database leak therefore exposes no usable password, token, code or key.
+
+## Tokens
+
+- **Access tokens:** ES256 JWTs. Verification **pins the algorithm** (no `alg: none`, no algorithm confusion) and checks the `typ` (`at+jwt`), issuer, audience and expiry, with 30 seconds of clock tolerance.
+- **Refresh tokens:** opaque, single use and rotated on every refresh. Marking a token used is a single atomic `UPDATE`, so two parallel refreshes can't both succeed. A reused token **ends the session** and records `session.refresh_token_reused`.
+- **Lifetimes:** refresh tokens never outlive their session (`sessionDays`).
+- **Web apps (cookie mode):** the refresh token lives in an `HttpOnly; Secure; SameSite=Strict` cookie that page scripts can't read, and a refresh using the cookie must carry an allowed `Origin` header, so other sites can't trigger it (CSRF).
+- **Email change:** needs the current password (or a sign-in from the last 10 minutes for accounts without one), is confirmed by a link to the new address, and notifies the old address. A stolen access token alone can't take over the account by changing its email.
+- **Data minimization:** old sessions, codes, links and audit entries are deleted on a schedule (`retention` settings), and users can export what is stored about them.
+- **Key rotation:** keys rotate without downtime. Old public keys stay published for 2 days.
+
+## Attacks considered
+
+| Attack | Defense |
+|---|---|
+| Password guessing | Rate limits per IP and per account; Argon2id; breached-password check (k-anonymity, the password never leaves the server) |
+| Credential stuffing | The same limits, plus `user.sign_in_failed` events for alerting; 2FA; passkeys |
+| Account enumeration | Send/forgot/register answer the same for known and unknown accounts; unknown-email sign-in still runs a full Argon2 check so timing matches; account status errors appear only after the user proved who they are; non-members get `NOT_FOUND` for organizations |
+| Code guessing | 5 attempts per code; 1 code per minute and 5 per hour per destination; codes expire in 10 minutes |
+| Token replay | Single-use links, codes, challenges and refresh tokens, each consumed atomically |
+| TOTP replay | The last accepted time step is stored, so a code can't be used twice |
+| Account pre-hijacking | If an account's email is still unverified after 24 hours, the owner proving it later (code, link or verified social email) removes any password set before and ends all sessions |
+| Social account takeover | A provider email is trusted only if the provider marks it verified. Facebook emails are never trusted for linking |
+| Stolen social token reuse | Tokens must be issued to **your** client ids / app id; optional nonce binding |
+| Mass assignment | Unknown body fields are rejected; roles and status can't be set by users |
+| SSRF via webhooks | https only; DNS resolved and private, loopback, link-local and metadata ranges blocked when saving and before every send; redirects not followed |
+| Webhook spoofing / replay | HMAC-SHA256 signature with timestamp; 5-minute window |
+| Clickjacking / XSS | Not applicable to a JSON API. Protect your web pages with CSP and `frame-ancestors` |
+| Brute force on admin | Admin routes check the session live; all admin actions are audited |
+| Leaked API key | Keys are hashed, scoped, revocable and optionally expiring; `lastUsedAt` shows use |
+
+## Rate limiting
+
+Limits are counted in Redis when `redisUrl` is set (shared by all servers), otherwise in each server's memory. If Redis is configured but unreachable, limited requests are **refused** (fail closed) rather than allowed. Limits are keyed by `request.ip`, so set `trust proxy` correctly ([Production checklist](production-checklist.md)). If you don't, every user shares the load balancer's IP and its limits.
+
+## What the library does not do
+
+- **No CAPTCHA.** Add one in front of sign-up and send-code endpoints if bots target you (e.g. Cloudflare Turnstile, verified in a guard or middleware).
+- **No HTTP security headers.** Use `helmet` in your app.
+- **No geo-blocking or IP reputation.** Use your edge provider.
+- **No forced 2FA.** It is the user's choice. To require it, check `amr` contains `two_factor` on the routes that need it.
+
+## Data protection
+
+- **Deletion:** account deletion wipes personal data and every way to sign in, while keeping the row for referential integrity. The audit log keeps IP addresses and user agents. Prune it to match your retention policy.
+- **Consent:** acceptance times of the terms and privacy policy are stored (`termsAcceptedAt`, `privacyPolicyAcceptedAt`).
+- **Data export:** for data-access requests, export with `GET /auth/admin/users/:id` plus your own data.