@luckystack/login 0.10.2 → 0.11.0

package/docs/password-reset.md

@@ -1,335 +1,5 @@
 # Password reset
 
-Deep-dive on the password-reset primitives, the framework-mode email orchestrator, and the password-policy validator. Canonical sources: [`./src/passwordReset.ts`](../src/passwordReset.ts), [`./src/forgotPassword.ts`](../src/forgotPassword.ts), [`./src/passwordPolicy.ts`](../src/passwordPolicy.ts).
+Framework-managed email and consumer-managed UI are separate choices so a project need not install mail infrastructure it does not use. Reset and email-change credentials are short-lived, single-use and hashed at rest: a Redis snapshot should not contain a redeemable link. They do not share the pluggable session-store adapter. See `../src/forgotPassword.ts`, `../src/passwordReset.ts`, `../../core/src/oneTimeToken.ts`.
 
-This is the password lifecycle from "user clicks Forgot password" through "new password landed in the user record". The flow is intentionally split into a small set of primitives that consumers can compose into a fully custom UI, with an opt-in `'framework'` mode that bundles all the pieces into a single end-to-end orchestrator.
-
----
-
-## Three modes — `auth.forgotPassword`
-
-`ProjectConfig.auth.forgotPassword` selects the operating mode:
-
-| Mode          | Behavior                                                                                                       | Email peer dep |
-| ------------- | -------------------------------------------------------------------------------------------------------------- | -------------- |
-| `'framework'` | `sendPasswordResetEmail` orchestrates token + email send. Reset URL points at the bundled `/reset-password` page. | `@luckystack/email` REQUIRED — lazy-imported on first call |
-| `'custom'`    | `sendPasswordResetEmail` returns `{ ok: false, reason: 'forgotPassword-not-framework' }`. Consumer wires their own email + UI using the primitives. | Not required — install `@luckystack/email` only if you call it yourself |
-| `'disabled'`  | Same as `'custom'` from the package's perspective. Convention is "the consumer-side UI does not expose a forgot-password link at all". | Not required |
-
-The mode is read at call time via `getProjectConfig()`, so consumers can toggle it through `registerProjectConfig` without restarting. In practice, switching modes mid-process is uncommon — pick a mode at boot and stick with it.
-
-## Token layout and hash-at-rest contract
-
-```ts
-const handle = issueOneTimeToken('-pwreset', auth.passwordResetTtlSeconds, userId);
-await handle.store();
-
-// Redis stores only the hash-derived key:
-// <projectName>-pwreset:<sha256(handle.token)> -> userId
-return handle.token; // raw 64-character token, returned only for delivery
-```
-
-- **Entropy** — 256 bits via `randomBytes(32)`, hex-encoded as a 64-character URL-safe token.
-- **Hash at rest** — the raw token is never persisted. `issueOneTimeToken` derives a SHA-256 key suffix, so a Redis keyspace/backup leak does not yield a redeemable reset link.
-- **Namespace** — `formatKey('-pwreset', sha256(token))`; the active project/tenant key formatter remains authoritative.
-- **Single active token per user** — `${projectName}-pwreset-user:<userId>` points to the current hash key. Issuing a replacement deletes the previous outstanding token before storing the new one.
-- **TTL** — both the hash record and per-user pointer use `auth.passwordResetTtlSeconds` (default 3600 seconds).
-- **Storage boundary** — password-reset tokens intentionally use the core one-time-token Redis primitive; this is independent of the pluggable session-storage adapter.
-
-## Primitives
-
-### `createPasswordResetToken(userId)`
-
-```ts
-createPasswordResetToken(userId: string): Promise<string>;
-```
-
-Invalidate the user's previous outstanding reset token, mint/store a new hash-at-rest token, persist the per-user pointer, and return the raw token. The caller is responsible for delivering it—normally in an `${appPublicUrl}/reset-password?token=<token>` URL.
-
-The promise rejects when Redis cannot read/delete/store the token records. Framework-mode callers normalize that failure; custom callers should use the standard `tryCatch` helper when they need a typed degradation path.
-
-### `consumePasswordResetToken(token)`
-
-```ts
-consumePasswordResetToken(token: string): Promise<string | null>;
-```
-
-Delegates to `consumeOneTimeToken('-pwreset', token)`. The shared primitive hashes the supplied raw token to derive the Redis key and performs one `MULTI` containing `GET` + `DEL`. It returns the bound `userId` only when both commands succeed.
-
-Returns `null` for an empty/malformed token, missing or expired hash record, an already-consumed token, or any transaction/DEL failure. A concurrent second redemption sees no value and fails closed, providing at-most-once consumption.
-
-### `updatePasswordHash(userId, plaintext)`
-
-```ts
-updatePasswordHash(userId: string, plaintext: string): Promise<void>;
-```
-
-Three-step: validate against policy → bcrypt-hash → write through `UserAdapter.update`.
-
-```ts
-const reason = validatePassword(plaintext);
-if (reason) throw new PasswordPolicyError(reason);
-const salt = await bcrypt.genSalt(getProjectConfig().auth.bcryptRounds);
-const hashedPassword = await bcrypt.hash(plaintext, salt);
-const patch: Record<string, unknown> = { password: hashedPassword };
-await getUserAdapter().update(userId, patch);
-```
-
-Throws `PasswordPolicyError` on policy violation. `UserAdapter.update` accepts a loose patch because custom user stores may expose different optional credential fields; no transport-typing cast is needed.
-
-Note this primitive deliberately does NOT consume a reset token. The reset-password completion API is responsible for the sequence:
-
-```ts
-const userId = await consumePasswordResetToken(token);
-if (!userId) return { status: false, reason: 'login.invalidResetToken' };
-await updatePasswordHash(userId, newPassword);
-// optional: dispatch passwordResetCompleted hook
-// optional: revokeUserSessions(userId)
-```
-
-Splitting these lets consumers compose the same primitive into a "change my password" endpoint (no token, just verify the current password first), an admin-reset endpoint (no token, no verification), or a forced-reset flow.
-
-### `verifyPassword(plaintext, hash)`
-
-```ts
-verifyPassword(plaintext: string, hash: string): Promise<boolean>;
-```
-
-Bcrypt comparison. Used by the in-session "change my password" endpoint to verify the user's current password before accepting a new one.
-
-### `PasswordPolicyError`
-
-```ts
-class PasswordPolicyError extends Error {
-  readonly errorCode: string;
-  constructor(errorCode: string) {
-    super(`Password policy violation: ${errorCode}`);
-    this.name = 'PasswordPolicyError';
-    this.errorCode = errorCode;
-  }
-}
-```
-
-`errorCode` is an i18n reason key like `login.passwordRequiresUppercase` or `login.passwordTooCommon`. Catch it in the calling API:
-
-```ts
-const [error] = await tryCatch(() => updatePasswordHash(userId, newPassword));
-if (error instanceof PasswordPolicyError) {
-  return { status: false, reason: error.errorCode };
-}
-if (error) return { status: false, reason: 'api.internalServerError' };
-return { status: true, reason: 'login.passwordChanged' };
-```
-
-## Password policy — `validatePassword(plaintext)`
-
-```ts
-validatePassword(password: string): string | null;
-```
-
-Returns `null` when the policy passes, or a reason-key on the FIRST failure. Checks run in order:
-
-| Check                | Reason key                            | Config slot                              |
-| -------------------- | ------------------------------------- | ---------------------------------------- |
-| `length < minLength` | `'login.passwordCharacterMinimum'`    | `auth.passwordPolicy.minLength`          |
-| `length > maxLength` | `'login.passwordCharacterLimit'`      | `auth.passwordPolicy.maxLength`          |
-| No `[A-Z]`           | `'login.passwordRequiresUppercase'`   | `auth.passwordPolicy.requireUppercase`   |
-| No `[a-z]`           | `'login.passwordRequiresLowercase'`   | `auth.passwordPolicy.requireLowercase`   |
-| No `\d`              | `'login.passwordRequiresNumber'`      | `auth.passwordPolicy.requireNumber`      |
-| No `[^A-Za-z0-9]`    | `'login.passwordRequiresSpecial'`     | `auth.passwordPolicy.requireSpecial`     |
-| In `COMMON_PASSWORDS` | `'login.passwordTooCommon'`          | `auth.passwordPolicy.forbidCommon`       |
-| Custom validator     | Whatever `customValidator` returns    | `auth.passwordPolicy.customValidator`    |
-
-The common-passwords blocklist lives in [`./src/data/commonPasswords.ts`](../src/data/commonPasswords.ts) — a `Set<string>` for O(1) lookup. The check is case-insensitive (`password.toLowerCase()`), so `Password123` and `password123` are both rejected if either is in the list.
-
-`customValidator` is a `(plaintext: string) => string | null` function on the project config. Use it for organization-specific policies (block-list of company-related words, NIST-style breach-database check, regex against the user's email):
-
-```ts
-registerProjectConfig({
-  auth: {
-    passwordPolicy: {
-      minLength: 12,
-      requireUppercase: true,
-      requireDigit: true,
-      customValidator: (plaintext) => {
-        if (plaintext.toLowerCase().includes('acme')) {
-          return 'login.passwordBrandWord';
-        }
-        return null;
-      },
-    },
-  },
-});
-```
-
-Reason keys returned from `customValidator` should still be i18n keys — the installer-side translator must have a matching message.
-
-## Framework-mode orchestrator — `sendPasswordResetEmail`
-
-```ts
-sendPasswordResetEmail({ email, brand? }: { email: string; brand?: string }): Promise<{ ok: boolean; reason?: string }>;
-```
-
-Full sequence in [`./src/forgotPassword.ts`](../src/forgotPassword.ts):
-
-1. **Mode gate** — `if (config.auth.forgotPassword !== 'framework') return { ok: false, reason: 'forgotPassword-not-framework' }`. Non-framework modes short-circuit here.
-2. **Brand resolution** — call-site `brand` > `config.auth.passwordResetBrand` > `'LuckyStack'`. The brand shows up in the email subject, the greeting, and the footer.
-3. **Lazy import** — `await import('@luckystack/email')`. The `// @ts-expect-error optional peer dep` suppresses the TS error when `@luckystack/email` is not installed; runtime will throw a clear `Cannot find module` if the consumer is in framework-mode without installing the peer. The lazy import means modes other than `'framework'` never touch the email package — letting consumers skip `@luckystack/email` entirely.
-4. **User lookup** — `userAdapter.findByEmail({ email, provider: 'credentials' })`. Looking up by the `'credentials'` provider scope means an OAuth-only user (no password set) cannot trigger a reset; the lookup misses, anti-enumeration kicks in.
-5. **Anti-enumeration on miss** — fires `passwordResetRequested` with `matched: false`, returns `{ ok: true }`. The caller cannot distinguish "email matched" from "email didn't match" — both look like success. Prevents attackers from harvesting valid emails by polling the reset endpoint.
-6. **Mint token** — `createPasswordResetToken(user.id)`.
-7. **Hook dispatch** — `void dispatchHook('passwordResetRequested', { email, matched: true, userId, token, ttlSeconds })`. Fire-and-forget so a slow audit-log subscriber doesn't block the email send.
-8. **Render the email** — `renderEmailLayout({ brand, title, intro, ctaLabel, ctaUrl, outro, footer })` from `@luckystack/email` produces `{ html, text }`. The reset URL is `${app.publicUrl}/reset-password?token=<urlEncodedToken>` with the trailing slash trimmed from `publicUrl`. `ttlMinutes = Math.round(ttlSeconds / 60)` so the email reads "expires in 60 minutes" without raw seconds.
-9. **Send** — `sendEmail({ to, subject, html, text, adapterHint: 'transactional' })`. The `'transactional'` hint routes through the transactional sender when consumers registered separate marketing + transactional adapters via `registerEmailSenders`. Falls back to the default sender when only one is registered. See [`/docs/ARCHITECTURE_EMAIL.md`](../../../docs/ARCHITECTURE_EMAIL.md).
-10. **Return** — `result.ok ? { ok: true } : { ok: false, reason: result.reason }`. Note that "send failure" IS surfaced via `ok: false` here — the anti-enumeration guarantee only covers the "user not found" miss, not infrastructure failure. The HTTP layer should still return a 200 to the client to preserve enumeration resistance, but log the `reason` for ops visibility.
-
-### Lazy-import implementation detail
-
-The `@ts-expect-error` is intentional and load-bearing:
-
-```ts
-const { sendEmail, renderEmailLayout } = await (
-  // @ts-expect-error optional peer dep — installed only when forgotPassword === 'framework'
-  import('@luckystack/email') as Promise<EmailModule>
-);
-```
-
-`@luckystack/email` is in `peerDependenciesMeta` as optional. Projects that pick `'custom'` or `'disabled'` mode never install the peer, and TypeScript would error on the import — the `@ts-expect-error` is the standard escape hatch for optional peers. The shape is asserted at the call site via the local `EmailModule` interface.
-
-## End-to-end reset flow
-
-The framework-mode flow has two HTTP endpoints (wired by `@luckystack/server` via the file-based router):
-
-```
-1. POST /api/reset-password/sendReset/v1   → sendPasswordResetEmail({ email })
-                                             └ token hash now in Redis; raw token is emailed
-2. POST /api/reset-password/confirmReset/v1 → consumePasswordResetToken(token)
-                                       └ updatePasswordHash(userId, newPassword)
-                                       └ revokeUserSessions(userId, currentToken?)
-                                       └ dispatchHook('passwordResetCompleted', { userId, revokedOtherSessions })
-```
-
-Both endpoints live in the `create-luckystack-app` template under `src/reset-password/_api/` so consumers can edit them. The package itself only exposes the primitives.
-
-For the in-session "change my password" flow:
-
-```
-POST /api/settings/changePassword/v1
-  1. verifyPassword(currentPassword, user.password)
-  2. updatePasswordHash(userId, newPassword)
-  3. revokeUserSessions(userId, currentToken)  // keep this session alive
-  4. dispatchHook('passwordChanged', { userId, verifiedCurrent: true, revokedOtherSessions: true })
-```
-
-## Recommended pairing: revoke other sessions
-
-After a successful reset OR change, calling `revokeUserSessions(userId, currentToken?)` ensures every other device the user was signed in on gets logged out. The recommended completion endpoint:
-
-```ts
-const userId = await consumePasswordResetToken(token);
-if (!userId) return { status: false, reason: 'login.invalidResetToken' };
-
-const [updateError] = await tryCatch(() => updatePasswordHash(userId, newPassword));
-if (updateError instanceof PasswordPolicyError) {
-  return { status: false, reason: updateError.errorCode };
-}
-if (updateError) return { status: false, reason: 'api.internalServerError' };
-
-const revoked = await revokeUserSessions(userId);
-await dispatchHook('passwordResetCompleted', { userId, revokedOtherSessions: revoked > 0 });
-
-return { status: true, reason: 'login.passwordResetSuccess' };
-```
-
-For the in-session change flow, pass the current token so the user stays signed in on the device they just changed it on:
-
-```ts
-const revoked = await revokeUserSessions(userId, currentToken);
-```
-
-The return value of `revokeUserSessions` is the number of sessions kicked, which the UI can surface as "You've been signed out of N other devices" for transparency.
-
-## Custom mode — composing the primitives
-
-When `auth.forgotPassword === 'custom'`, the consumer wires their own UI and email layer using the primitives:
-
-```ts
-// Consumer-side custom forgot-password endpoint
-import { createPasswordResetToken } from '@luckystack/login';
-import { mySmsClient } from './sms';
-
-export const sendResetSms = async ({ phone }: { phone: string }) => {
-  const user = await prisma.user.findFirst({ where: { phone, provider: 'credentials' } });
-  if (!user) return { ok: true }; // anti-enumeration
-  const token = await createPasswordResetToken(user.id);
-  await mySmsClient.send(phone, `Reset code: ${token.slice(0, 6).toUpperCase()}`);
-  return { ok: true };
-};
-```
-
-The SMS example uses the first 6 chars as a human-typeable code rather than the full 64-char hex string. The consumer-side completion endpoint then redeems by reconstructing the full token from a lookup table — or by storing a shorter token to begin with via a custom helper. The packaged primitives don't support short tokens directly; if you need them, mint + store in your own Redis namespace and skip `createPasswordResetToken` entirely.
-
-## Disabled mode
-
-`auth.forgotPassword === 'disabled'` is purely a convention — the package functions the same way as `'custom'`. The intent is for the installer-side UI to NOT render a "Forgot password?" link at all. This is appropriate for:
-
-- B2B apps where password resets go through a customer success rep, not a self-serve flow.
-- Internal tools where SSO is the only supported auth and the credentials provider is a break-glass admin-only path.
-- Apps under a regulatory regime that forbids self-service reset (rare but real).
-
-## Brand customization — `auth.passwordResetBrand`
-
-Sets the default brand label used in the framework-mode email (subject, greeting, footer). Resolution order:
-
-```ts
-const resolvedBrand = brand ?? config.auth.passwordResetBrand ?? 'LuckyStack';
-```
-
-`'LuckyStack'` is the absolute fallback so a misconfigured project still produces a coherent email. In real deployments, set `auth.passwordResetBrand` in `config.ts` (or pass `brand` at the call site for per-tenant brands in a multi-tenant deployment).
-
-## Hook flow
-
-`passwordResetRequested` fires from `sendPasswordResetEmail` — for both matched and unmatched emails (anti-enumeration). Audit handlers MUST NOT differentiate UX between matched and unmatched. See [`./hooks.md`](./hooks.md) for the full payload shape.
-
-`passwordResetCompleted` fires from the consumer-side completion endpoint AFTER the new password is written and `revokeUserSessions` runs. The package itself does NOT fire this hook — the bundled template does.
-
-`passwordChanged` fires from the in-session change-password endpoint. Same — consumer-side dispatch, not framework-side. Carries `verifiedCurrent: boolean` to distinguish "user verified their old password" from "admin reset without verification".
-
-## Config quick-reference
-
-| Slot                                  | Used by                                                        |
-| ------------------------------------- | -------------------------------------------------------------- |
-| `auth.bcryptRounds`                   | `updatePasswordHash` (salt rounds for the new hash)            |
-| `auth.passwordPolicy.minLength`       | `validatePassword` (lower bound)                               |
-| `auth.passwordPolicy.maxLength`       | `validatePassword` (upper bound — anti-DoS on bcrypt)          |
-| `auth.passwordPolicy.requireUppercase` | `validatePassword`                                            |
-| `auth.passwordPolicy.requireLowercase` | `validatePassword`                                            |
-| `auth.passwordPolicy.requireNumber`   | `validatePassword`                                             |
-| `auth.passwordPolicy.requireSpecial`  | `validatePassword`                                             |
-| `auth.passwordPolicy.forbidCommon`    | `validatePassword` (gate the common-passwords blocklist check) |
-| `auth.passwordPolicy.customValidator` | `validatePassword` (final policy gate)                         |
-| `auth.passwordResetTtlSeconds`        | `createPasswordResetToken` (Redis EX), `sendPasswordResetEmail` (TTL string in email body) |
-| `auth.passwordResetBrand`             | `sendPasswordResetEmail` (fallback brand)                      |
-| `auth.forgotPassword`                 | `sendPasswordResetEmail` (mode gate)                           |
-| `app.publicUrl`                       | `sendPasswordResetEmail` (reset link host)                     |
-
-## Why bcrypt and not argon2
-
-bcrypt was picked because:
-
-- It's been the industry standard for password hashing for two decades; bugs are well-known and patched.
-- `bcryptjs` (the pure-JS port) works in serverless / edge runtimes where native modules are awkward.
-- The cost factor (`bcryptRounds`) is tunable — set it higher on production behind sufficient CPU budget.
-
-argon2 is theoretically stronger but the pure-JS implementation is slow and the native module is a deployment headache. If you have a strong opinion, you can register a custom `UserAdapter` whose `update` does an argon2 hash before storing — but you'd also need to swap `verifyPassword` and the credentials login path, which is more friction than the marginal security gain typically justifies.
-
-If you DO want to upgrade, the recommended approach is "hash with argon2, store the result, and migrate users lazily on next login" — too disruptive to do in a one-shot rehash. Out of scope for this package.
-
-## Related
-
-- [`./credentials-auth.md`](./credentials-auth.md) — the login flow that uses `bcrypt.compare` against the same hash.
-- [`./hooks.md`](./hooks.md) — `passwordResetRequested` / `passwordResetCompleted` / `passwordChanged` payload shapes.
-- [`./user-adapter.md`](./user-adapter.md) — `updatePasswordHash` writes through `UserAdapter.update`.
-- [`./session-management.md`](./session-management.md) — `revokeUserSessions` (recommended pairing).
-- Architecture — email: [`/docs/ARCHITECTURE_EMAIL.md`](../../../docs/ARCHITECTURE_EMAIL.md).
-- Architecture — auth: [`/docs/ARCHITECTURE_AUTH.md`](../../../docs/ARCHITECTURE_AUTH.md).
+An unknown email must not produce a distinguishable user-facing response, including from audit hooks. Apply password policy when changing a password, and consider revoking existing sessions after reset; a changed hash alone does not invalidate an already-issued session. This package uses bcrypt to avoid the deployment friction of a native hashing dependency; changing the algorithm requires a coordinated login/verification and migration plan, not only a storage adapter. Source: `../src/passwordPolicy.ts`, `../src/session.ts`, `./hooks.md`.