@luckystack/login 0.6.7 → 0.7.0

package/dist/logout-OBO6AF4R.js

@@ -0,0 +1,7 @@
+import {
+  logout
+} from "./chunk-WFPYOCFC.js";
+export {
+  logout
+};
+//# sourceMappingURL=logout-OBO6AF4R.js.map

package/dist/register.js

@@ -9,7 +9,7 @@ import {
   microsoftProvider,
   registerOAuthProviderFactory,
   registerUserAdapter
-} from "./chunk-HJHCX2JO.js";
+} from "./chunk-L5MHCPNN.js";
 
 // src/register.ts
 import { getProjectConfig, resolveEnvKey } from "@luckystack/core";

package/dist/register.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/register.ts"],"sourcesContent":["//? Side-effect `./register` entry for @luckystack/login. Auto-imported at boot by\r\n//? @luckystack/server's `bootstrapLuckyStack` when this package is installed, so\r\n//? OAuth providers + the default user adapter wire themselves from env with NO\r\n//? consumer code edit — adding an OAuth provider is just env vars + restart.\r\n//?\r\n//? (Session-provider registration lives in this package's index module load —\r\n//? `bootstrapLuckyStack` force-loads it via `getLogin()`. This register entry\r\n//? covers the parts that USED to live in the consumer\r\n//? `luckystack/login/{oauthProviders,userAdapter}.ts` overlay.)\r\n//?\r\n//? A provider becomes active (its button shows on the login form via\r\n//? `GET /auth/providers` AND its `/auth/api/<name>` route works) as soon as BOTH\r\n//? its *_CLIENT_ID and *_CLIENT_SECRET are set for the current environment:\r\n//? `DEV_<KEY>` in dev, the unprefixed `<KEY>` in prod. The callback origin comes\r\n//? from `getProjectConfig().oauthCallbackBase` (set in the consumer's config.ts)\r\n//? — the redirect URI to register with each provider is\r\n//? `<oauthCallbackBase>/auth/callback/<provider>`.\r\n//?\r\n//? A consumer overlay (`luckystack/login/*.ts`) runs AFTER this import, so a\r\n//? hand-written `registerOAuthProviders(...)` / `registerUserAdapter(...)` still\r\n//? wins (last writer).\r\n\r\nimport { getProjectConfig, resolveEnvKey } from '@luckystack/core';\r\nimport {\r\n  registerOAuthProviderFactory,\r\n  credentialsProvider,\r\n  googleProvider,\r\n  githubProvider,\r\n  discordProvider,\r\n  facebookProvider,\r\n  microsoftProvider,\r\n  type OAuthProvider,\r\n} from './oauthProviders';\r\nimport {\r\n  registerUserAdapter,\r\n  isUserAdapterRegistered,\r\n  defaultPrismaUserAdapter,\r\n} from './userAdapter';\r\n\r\n//? Default Prisma-backed user store — guard so a consumer overlay that\r\n//? registered a custom adapter before this runs is never clobbered.\r\nif (!isUserAdapterRegistered()) {\r\n  registerUserAdapter(defaultPrismaUserAdapter());\r\n}\r\n\r\n//? LOGIN-01: all config/env reads are deferred into a factory function that\r\n//? executes at first-request time, not at module-load time. This prevents\r\n//? stale-config footguns when `getProjectConfig()` is overridden after import\r\n//? (e.g. in tests or multi-step boot sequences). Module-load side effects\r\n//? in the block below are now limited to adapter registration (which is safe\r\n//? because the adapter registry itself does not depend on project config).\r\nconst buildProviders = (): OAuthProvider[] => {\r\n  const dev = resolveEnvKey() !== 'production';\r\n\r\n  //? Reads `DEV_<key>` in dev, the unprefixed `<key>` in prod. Empty when unset.\r\n  const env = (key: string): string => (dev ? process.env[`DEV_${key}`] : process.env[key]) ?? '';\r\n\r\n  //? Backend origin for the OAuth redirect URI. Prefer the explicit\r\n  //? `oauthCallbackBase` slot; fall back to `app.publicUrl` so a consumer that\r\n  //? only set `publicUrl` still gets a usable callback.\r\n  const projectConfig = getProjectConfig();\r\n  //? Empty-string slot (the default) must fall through to publicUrl. Use an\r\n  //? explicit length check so `??` (which would keep the empty string) is wrong here.\r\n  const configuredCallbackBase = projectConfig.oauthCallbackBase ?? '';\r\n  const callbackBase = configuredCallbackBase.length > 0 ? configuredCallbackBase : projectConfig.app.publicUrl;\r\n  const callback = (name: string): string => `${callbackBase}/auth/callback/${name}`;\r\n\r\n  //? Credentials (email+password) is a registry entry too, gated by a single\r\n  //? config flag so the registry — exposed via GET /auth/providers — is the ONE\r\n  //? source the login form reads (no duplicate static `config.providers` list).\r\n  const providers: OAuthProvider[] = [];\r\n  if (projectConfig.auth.credentials) {\r\n    providers.push(credentialsProvider());\r\n  }\r\n\r\n  if (env('GOOGLE_CLIENT_ID') && env('GOOGLE_CLIENT_SECRET')) {\r\n    providers.push(googleProvider({\r\n      clientId: env('GOOGLE_CLIENT_ID'),\r\n      clientSecret: env('GOOGLE_CLIENT_SECRET'),\r\n      callbackUrl: callback('google'),\r\n    }));\r\n  }\r\n\r\n  if (env('GITHUB_CLIENT_ID') && env('GITHUB_CLIENT_SECRET')) {\r\n    providers.push(githubProvider({\r\n      clientId: env('GITHUB_CLIENT_ID'),\r\n      clientSecret: env('GITHUB_CLIENT_SECRET'),\r\n      callbackUrl: callback('github'),\r\n    }));\r\n  }\r\n\r\n  if (env('DISCORD_CLIENT_ID') && env('DISCORD_CLIENT_SECRET')) {\r\n    providers.push(discordProvider({\r\n      clientId: env('DISCORD_CLIENT_ID'),\r\n      clientSecret: env('DISCORD_CLIENT_SECRET'),\r\n      callbackUrl: callback('discord'),\r\n    }));\r\n  }\r\n\r\n  if (env('FACEBOOK_CLIENT_ID') && env('FACEBOOK_CLIENT_SECRET')) {\r\n    providers.push(facebookProvider({\r\n      clientId: env('FACEBOOK_CLIENT_ID'),\r\n      clientSecret: env('FACEBOOK_CLIENT_SECRET'),\r\n      callbackUrl: callback('facebook'),\r\n    }));\r\n  }\r\n\r\n  if (env('MICROSOFT_CLIENT_ID') && env('MICROSOFT_CLIENT_SECRET')) {\r\n    providers.push(microsoftProvider({\r\n      clientId: env('MICROSOFT_CLIENT_ID'),\r\n      clientSecret: env('MICROSOFT_CLIENT_SECRET'),\r\n      callbackUrl: callback('microsoft'),\r\n      tenant: env('MICROSOFT_TENANT_ID') || undefined,\r\n    }));\r\n  }\r\n\r\n  return providers;\r\n};\r\n\r\nregisterOAuthProviderFactory(buildProviders);\r\n"],"mappings":";;;;;;;;;;;;;;AAsBA,SAAS,kBAAkB,qBAAqB;AAmBhD,IAAI,CAAC,wBAAwB,GAAG;AAC9B,sBAAoB,yBAAyB,CAAC;AAChD;AAQA,IAAM,iBAAiB,MAAuB;AAC5C,QAAM,MAAM,cAAc,MAAM;AAGhC,QAAM,MAAM,CAAC,SAAyB,MAAM,QAAQ,IAAI,OAAO,GAAG,EAAE,IAAI,QAAQ,IAAI,GAAG,MAAM;AAK7F,QAAM,gBAAgB,iBAAiB;AAGvC,QAAM,yBAAyB,cAAc,qBAAqB;AAClE,QAAM,eAAe,uBAAuB,SAAS,IAAI,yBAAyB,cAAc,IAAI;AACpG,QAAM,WAAW,CAAC,SAAyB,GAAG,YAAY,kBAAkB,IAAI;AAKhF,QAAM,YAA6B,CAAC;AACpC,MAAI,cAAc,KAAK,aAAa;AAClC,cAAU,KAAK,oBAAoB,CAAC;AAAA,EACtC;AAEA,MAAI,IAAI,kBAAkB,KAAK,IAAI,sBAAsB,GAAG;AAC1D,cAAU,KAAK,eAAe;AAAA,MAC5B,UAAU,IAAI,kBAAkB;AAAA,MAChC,cAAc,IAAI,sBAAsB;AAAA,MACxC,aAAa,SAAS,QAAQ;AAAA,IAChC,CAAC,CAAC;AAAA,EACJ;AAEA,MAAI,IAAI,kBAAkB,KAAK,IAAI,sBAAsB,GAAG;AAC1D,cAAU,KAAK,eAAe;AAAA,MAC5B,UAAU,IAAI,kBAAkB;AAAA,MAChC,cAAc,IAAI,sBAAsB;AAAA,MACxC,aAAa,SAAS,QAAQ;AAAA,IAChC,CAAC,CAAC;AAAA,EACJ;AAEA,MAAI,IAAI,mBAAmB,KAAK,IAAI,uBAAuB,GAAG;AAC5D,cAAU,KAAK,gBAAgB;AAAA,MAC7B,UAAU,IAAI,mBAAmB;AAAA,MACjC,cAAc,IAAI,uBAAuB;AAAA,MACzC,aAAa,SAAS,SAAS;AAAA,IACjC,CAAC,CAAC;AAAA,EACJ;AAEA,MAAI,IAAI,oBAAoB,KAAK,IAAI,wBAAwB,GAAG;AAC9D,cAAU,KAAK,iBAAiB;AAAA,MAC9B,UAAU,IAAI,oBAAoB;AAAA,MAClC,cAAc,IAAI,wBAAwB;AAAA,MAC1C,aAAa,SAAS,UAAU;AAAA,IAClC,CAAC,CAAC;AAAA,EACJ;AAEA,MAAI,IAAI,qBAAqB,KAAK,IAAI,yBAAyB,GAAG;AAChE,cAAU,KAAK,kBAAkB;AAAA,MAC/B,UAAU,IAAI,qBAAqB;AAAA,MACnC,cAAc,IAAI,yBAAyB;AAAA,MAC3C,aAAa,SAAS,WAAW;AAAA,MACjC,QAAQ,IAAI,qBAAqB,KAAK;AAAA,IACxC,CAAC,CAAC;AAAA,EACJ;AAEA,SAAO;AACT;AAEA,6BAA6B,cAAc;","names":[]}
+{"version":3,"sources":["../src/register.ts"],"sourcesContent":["//? Side-effect `./register` entry for @luckystack/login. Auto-imported at boot by\n//? @luckystack/server's `bootstrapLuckyStack` when this package is installed, so\n//? OAuth providers + the default user adapter wire themselves from env with NO\n//? consumer code edit — adding an OAuth provider is just env vars + restart.\n//?\n//? (Session-provider registration lives in this package's index module load —\n//? `bootstrapLuckyStack` force-loads it via `getLogin()`. This register entry\n//? covers the parts that USED to live in the consumer\n//? `luckystack/login/{oauthProviders,userAdapter}.ts` overlay.)\n//?\n//? A provider becomes active (its button shows on the login form via\n//? `GET /auth/providers` AND its `/auth/api/<name>` route works) as soon as BOTH\n//? its *_CLIENT_ID and *_CLIENT_SECRET are set for the current environment:\n//? `DEV_<KEY>` in dev, the unprefixed `<KEY>` in prod. The callback origin comes\n//? from `getProjectConfig().oauthCallbackBase` (set in the consumer's config.ts)\n//? — the redirect URI to register with each provider is\n//? `<oauthCallbackBase>/auth/callback/<provider>`.\n//?\n//? A consumer overlay (`luckystack/login/*.ts`) runs AFTER this import, so a\n//? hand-written `registerOAuthProviders(...)` / `registerUserAdapter(...)` still\n//? wins (last writer).\n\nimport { getProjectConfig, resolveEnvKey } from '@luckystack/core';\nimport {\n  registerOAuthProviderFactory,\n  credentialsProvider,\n  googleProvider,\n  githubProvider,\n  discordProvider,\n  facebookProvider,\n  microsoftProvider,\n  type OAuthProvider,\n} from './oauthProviders';\nimport {\n  registerUserAdapter,\n  isUserAdapterRegistered,\n  defaultPrismaUserAdapter,\n} from './userAdapter';\n\n//? Default Prisma-backed user store — guard so a consumer overlay that\n//? registered a custom adapter before this runs is never clobbered.\nif (!isUserAdapterRegistered()) {\n  registerUserAdapter(defaultPrismaUserAdapter());\n}\n\n//? LOGIN-01: all config/env reads are deferred into a factory function that\n//? executes at first-request time, not at module-load time. This prevents\n//? stale-config footguns when `getProjectConfig()` is overridden after import\n//? (e.g. in tests or multi-step boot sequences). Module-load side effects\n//? in the block below are now limited to adapter registration (which is safe\n//? because the adapter registry itself does not depend on project config).\nconst buildProviders = (): OAuthProvider[] => {\n  const dev = resolveEnvKey() !== 'production';\n\n  //? Reads `DEV_<key>` in dev, the unprefixed `<key>` in prod. Empty when unset.\n  const env = (key: string): string => (dev ? process.env[`DEV_${key}`] : process.env[key]) ?? '';\n\n  //? Backend origin for the OAuth redirect URI. Prefer the explicit\n  //? `oauthCallbackBase` slot; fall back to `app.publicUrl` so a consumer that\n  //? only set `publicUrl` still gets a usable callback.\n  const projectConfig = getProjectConfig();\n  //? Empty-string slot (the default) must fall through to publicUrl. Use an\n  //? explicit length check so `??` (which would keep the empty string) is wrong here.\n  const configuredCallbackBase = projectConfig.oauthCallbackBase ?? '';\n  const callbackBase = configuredCallbackBase.length > 0 ? configuredCallbackBase : projectConfig.app.publicUrl;\n  const callback = (name: string): string => `${callbackBase}/auth/callback/${name}`;\n\n  //? Credentials (email+password) is a registry entry too, gated by a single\n  //? config flag so the registry — exposed via GET /auth/providers — is the ONE\n  //? source the login form reads (no duplicate static `config.providers` list).\n  const providers: OAuthProvider[] = [];\n  if (projectConfig.auth.credentials) {\n    providers.push(credentialsProvider());\n  }\n\n  if (env('GOOGLE_CLIENT_ID') && env('GOOGLE_CLIENT_SECRET')) {\n    providers.push(googleProvider({\n      clientId: env('GOOGLE_CLIENT_ID'),\n      clientSecret: env('GOOGLE_CLIENT_SECRET'),\n      callbackUrl: callback('google'),\n    }));\n  }\n\n  if (env('GITHUB_CLIENT_ID') && env('GITHUB_CLIENT_SECRET')) {\n    providers.push(githubProvider({\n      clientId: env('GITHUB_CLIENT_ID'),\n      clientSecret: env('GITHUB_CLIENT_SECRET'),\n      callbackUrl: callback('github'),\n    }));\n  }\n\n  if (env('DISCORD_CLIENT_ID') && env('DISCORD_CLIENT_SECRET')) {\n    providers.push(discordProvider({\n      clientId: env('DISCORD_CLIENT_ID'),\n      clientSecret: env('DISCORD_CLIENT_SECRET'),\n      callbackUrl: callback('discord'),\n    }));\n  }\n\n  if (env('FACEBOOK_CLIENT_ID') && env('FACEBOOK_CLIENT_SECRET')) {\n    providers.push(facebookProvider({\n      clientId: env('FACEBOOK_CLIENT_ID'),\n      clientSecret: env('FACEBOOK_CLIENT_SECRET'),\n      callbackUrl: callback('facebook'),\n    }));\n  }\n\n  if (env('MICROSOFT_CLIENT_ID') && env('MICROSOFT_CLIENT_SECRET')) {\n    providers.push(microsoftProvider({\n      clientId: env('MICROSOFT_CLIENT_ID'),\n      clientSecret: env('MICROSOFT_CLIENT_SECRET'),\n      callbackUrl: callback('microsoft'),\n      tenant: env('MICROSOFT_TENANT_ID') || undefined,\n    }));\n  }\n\n  return providers;\n};\n\nregisterOAuthProviderFactory(buildProviders);\n"],"mappings":";;;;;;;;;;;;;;AAsBA,SAAS,kBAAkB,qBAAqB;AAmBhD,IAAI,CAAC,wBAAwB,GAAG;AAC9B,sBAAoB,yBAAyB,CAAC;AAChD;AAQA,IAAM,iBAAiB,MAAuB;AAC5C,QAAM,MAAM,cAAc,MAAM;AAGhC,QAAM,MAAM,CAAC,SAAyB,MAAM,QAAQ,IAAI,OAAO,GAAG,EAAE,IAAI,QAAQ,IAAI,GAAG,MAAM;AAK7F,QAAM,gBAAgB,iBAAiB;AAGvC,QAAM,yBAAyB,cAAc,qBAAqB;AAClE,QAAM,eAAe,uBAAuB,SAAS,IAAI,yBAAyB,cAAc,IAAI;AACpG,QAAM,WAAW,CAAC,SAAyB,GAAG,YAAY,kBAAkB,IAAI;AAKhF,QAAM,YAA6B,CAAC;AACpC,MAAI,cAAc,KAAK,aAAa;AAClC,cAAU,KAAK,oBAAoB,CAAC;AAAA,EACtC;AAEA,MAAI,IAAI,kBAAkB,KAAK,IAAI,sBAAsB,GAAG;AAC1D,cAAU,KAAK,eAAe;AAAA,MAC5B,UAAU,IAAI,kBAAkB;AAAA,MAChC,cAAc,IAAI,sBAAsB;AAAA,MACxC,aAAa,SAAS,QAAQ;AAAA,IAChC,CAAC,CAAC;AAAA,EACJ;AAEA,MAAI,IAAI,kBAAkB,KAAK,IAAI,sBAAsB,GAAG;AAC1D,cAAU,KAAK,eAAe;AAAA,MAC5B,UAAU,IAAI,kBAAkB;AAAA,MAChC,cAAc,IAAI,sBAAsB;AAAA,MACxC,aAAa,SAAS,QAAQ;AAAA,IAChC,CAAC,CAAC;AAAA,EACJ;AAEA,MAAI,IAAI,mBAAmB,KAAK,IAAI,uBAAuB,GAAG;AAC5D,cAAU,KAAK,gBAAgB;AAAA,MAC7B,UAAU,IAAI,mBAAmB;AAAA,MACjC,cAAc,IAAI,uBAAuB;AAAA,MACzC,aAAa,SAAS,SAAS;AAAA,IACjC,CAAC,CAAC;AAAA,EACJ;AAEA,MAAI,IAAI,oBAAoB,KAAK,IAAI,wBAAwB,GAAG;AAC9D,cAAU,KAAK,iBAAiB;AAAA,MAC9B,UAAU,IAAI,oBAAoB;AAAA,MAClC,cAAc,IAAI,wBAAwB;AAAA,MAC1C,aAAa,SAAS,UAAU;AAAA,IAClC,CAAC,CAAC;AAAA,EACJ;AAEA,MAAI,IAAI,qBAAqB,KAAK,IAAI,yBAAyB,GAAG;AAChE,cAAU,KAAK,kBAAkB;AAAA,MAC/B,UAAU,IAAI,qBAAqB;AAAA,MACnC,cAAc,IAAI,yBAAyB;AAAA,MAC3C,aAAa,SAAS,WAAW;AAAA,MACjC,QAAQ,IAAI,qBAAqB,KAAK;AAAA,IACxC,CAAC,CAAC;AAAA,EACJ;AAEA,SAAO;AACT;AAEA,6BAA6B,cAAc;","names":[]}

package/docs/credentials-auth.md

@@ -1,219 +1,219 @@
-# Credentials auth
-
-Deep-dive on the email + password authentication flow exposed by `@luckystack/login`. This document covers the dispatcher contract, input normalization, validation, the underlying register / login functions, and the hooks fired along the way. All references point at the canonical implementation in [`./src/login.ts`](../src/login.ts).
-
----
-
-## The two-in-one dispatcher
-
-The HTTP `/auth/api/credentials` route — wired by `@luckystack/server` — calls a single entry point:
-
-```ts
-import { loginWithCredentials } from '@luckystack/login';
-
-const result = await loginWithCredentials({
-  email,
-  password,
-  name,            // present only when the client is registering
-  confirmPassword, // present only when the client is registering
-});
-```
-
-`loginWithCredentials` is a thin dispatcher. It inspects the shape of the body to decide whether the caller is logging in or registering:
-
-```ts
-if (creds.name && creds.confirmPassword) {
-  return registerWithCredentials({ ... });
-}
-return loginWithCredentialsCore({ ... });
-```
-
-The rule is intentionally minimal: presence of both `name` and `confirmPassword` triggers the register branch; any other shape (just `email` + `password`) triggers the login branch. There is no `mode` parameter, no second route, and no separate URL — one POST handles both flows so the front-end can ship one form component.
-
-When you wire a non-HTTP auth surface (CLI, custom socket event, an admin "impersonate" tool) and you already know which side you want, skip the dispatcher and call `loginWithCredentialsCore` or `registerWithCredentials` directly. The dispatcher is purely a convenience for the unified HTTP route.
-
-## Signatures
-
-```ts
-// Dispatcher
-const loginWithCredentials = async (params: {
-  email?: string;
-  password?: string;
-  name?: string;
-  confirmPassword?: string;
-}) => Promise<
-  | { status: true;  reason: string; newToken?: string; session: SessionLayout }
-  | { status: false; reason: string }
->;
-
-// Login-only entry point
-const loginWithCredentialsCore = async (input: {
-  email: string;
-  password: string;
-}) => Promise<
-  | { status: true;  reason: 'login.loggedIn'; newToken: string; session: SessionLayout }
-  | { status: false; reason: string }
->;
-
-// Register-only entry point
-const registerWithCredentials = async (input: {
-  email: string;
-  password: string;
-  name: string;
-  confirmPassword: string;
-}) => Promise<
-  | { status: true;  reason: 'login.userCreated'; session: SessionLayout }
-  | { status: false; reason: string }
->;
-```
-
-`reason` is always an i18n key — the installer-side translator turns it into a human-readable message. Never render it raw. See [`docs/ARCHITECTURE_AUTH.md`](../../../docs/ARCHITECTURE_AUTH.md) for the full list of canonical reason keys.
-
-## Input normalization
-
-`normalizeCredentials(params)` runs first, producing a `NormalizedCredentials` object that the rest of the flow consumes. Each transformation exists for a specific reason:
-
-| Field             | Transformation                              | Why                                                                                                                                       |
-| ----------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `email`           | `trim().toLowerCase()`                      | Case-insensitive lookup; trailing/leading whitespace stripped so a copy-paste from a chat client doesn't break the find.                  |
-| `password`        | Left raw                                    | Bcrypt operates on bytes. The password never reaches HTML, JSON-as-HTML, or a SQL string interpolation, so HTML-escaping it is harmful.   |
-| `name`            | `validator.escape(name)` when present       | The name IS surfaced to the UI as text. Pre-escape `<`, `>`, `&`, `"`, `'` to neutralize stored XSS in any consumer that renders it raw.  |
-| `confirmPassword` | Left raw                                    | Must be byte-identical to `password` for the `password !== confirmPassword` equality check. Escaping only one half breaks special chars.  |
-
-The "escape `confirmPassword` too" mistake is the subject of a long-standing comment in `normalizeCredentials` — that bug previously made any password containing `&`, `<`, `>`, `"`, or `'` fail registration silently. Don't reintroduce it.
-
-## Shape validation
-
-`validateCredentialsShape(creds)` is the next gate. It returns `{ status: false, reason }` on the first failure, or `null` when every check passes:
-
-1. **Empty check** — `email` and `password` must both be non-empty. Reason: `login.empty`.
-2. **Email length** — capped at `auth.emailMaxLength`. Reason: `login.emailCharacterLimit`.
-3. **Name length** — only checked when `name` is present (register branch). Capped at `auth.nameMaxLength`. Reason: `login.nameCharacterLimit`.
-4. **Email format** — `validator.isEmail(email)` after normalization. Reason: `login.invalidEmailFormat`.
-5. **Password policy** — `validatePassword(password)` from [`./src/passwordPolicy.ts`](../src/passwordPolicy.ts). Returns a reason key (`login.passwordCharacterMinimum`, `login.passwordRequiresUppercase`, `login.passwordTooCommon`, etc.) or `null`.
-
-Length limits live in `ProjectConfig.auth` and are resolved at call time, so consumers can override them through `registerProjectConfig` without restarting the framework.
-
-## Register flow
-
-`registerWithCredentials` is the canonical "new user" path:
-
-1. **Confirm-password match** — `password !== confirmPassword` fails with `login.passwordNotMatch`.
-2. **`preRegister` hook** — fires with `{ email, provider: 'credentials', name }`. A handler can return a `HookStopSignal` (`{ stop: true, errorCode: '...' }`) to abort; the signal's `errorCode` becomes the `reason`.
-3. **Duplicate-email guard** — `userAdapter.findByEmail({ email, provider: 'credentials' })`. A match returns `login.emailExists`.
-4. **Hash the password** — `bcrypt.genSalt(auth.bcryptRounds)` → `bcrypt.hash(plaintext, salt)`. The default `bcryptRounds` is 10; tighten it on production deployments behind a sufficient CPU budget.
-5. **Create the user** — `userAdapter.create({...})` with the assembled record. `avatarFallback` is a random hex color so the avatar component has something to render until the user uploads an image.
-6. **`postRegister` hook** — fires with `{ userId, provider: 'credentials' }`.
-7. **Return** — `{ status: true, reason: 'login.userCreated', session: sanitizeUserForSession(user) }`.
-
-Note that registration does NOT auto-login. The dispatcher returns the sanitized user record so the front-end can show a "welcome" screen, but `newToken` is undefined — the user follows the register response with an explicit login (or the front-end posts the same credentials through the login branch). Auto-login on register is something a consumer can layer on top by chaining the two calls.
-
-## Login flow
-
-`loginWithCredentialsCore` is the "existing user" path:
-
-1. **`preLogin` hook** — fires with `{ email, provider: 'credentials' }`. Same stop-signal contract as `preRegister`.
-2. **User lookup** — `userAdapter.findByEmail({ email, provider: 'credentials' })`. Missing user returns `login.userNotFound`.
-3. **Password check** — `bcrypt.compare(plaintext, user.password)`. Mismatch returns `login.wrongPassword`. (We do not differentiate "no user" from "wrong password" in production — see [`docs/ARCHITECTURE_AUTH.md`](../../../docs/ARCHITECTURE_AUTH.md) for the anti-enumeration design. The two reason keys exist for dev-mode diagnostics only.)
-4. **Mint token** — 32 random bytes, hex-encoded, 64 chars total.
-5. **Best-effort `lastLogin` update** — `userAdapter.update(id, { lastLogin: new Date() })` wrapped in `tryCatch`. Silently no-ops if the column doesn't exist on the consumer's schema.
-6. **Build the session** — `sanitizeUserForSession(user)` strips the password hash, then `token`, `lastLogin`, `previousLogin` are layered on. The avatar resolution step below is run before saving.
-7. **Avatar resolution** — if `<uploadsDir>/<userId>.webp` exists, set `session.avatar = '<userId>.webp'`. The path is resolved at call time via `getUploadsDir()` so consumer overrides win.
-8. **Save the session** — `saveSession(token, user, true)`. The `true` flag triggers `preSessionCreate` / `postSessionCreate`, runs single-session enforcement, mints a CSRF token, and broadcasts the new session over Socket.io.
-9. **`postLogin` hook** — `{ userId, provider: 'credentials', isNewUser: false, token }`.
-10. **Return** — `{ status: true, reason: 'login.loggedIn', newToken, session }`.
-
-`isNewUser` is always `false` for credentials login. It exists in the payload because `loginCallback` (OAuth) shares the same `postLogin` hook and DOES distinguish first-time-vs-returning, and we want a single audit hook to handle both.
-
-## Session sanitization
-
-`sanitizeUserForSession<T extends { password?: unknown }>(user)` strips the `password` key via destructuring:
-
-```ts
-const sanitizeUserForSession = <T extends { password?: unknown }>(user: T): Omit<T, 'password'> => {
-  const { password: _password, ...safeUser } = user;
-  return safeUser;
-};
-```
-
-The bcrypt hash should never leave the server. The session is broadcast to clients (`socketEventNames.updateSession`), so a `password` field on it would be a stored-credential leak. Every login path runs through this helper before `saveSession`.
-
-## `lastLogin` and `previousLogin`
-
-Both fields are surfaced on the session layout so the UI can show "Last signed in 3 days ago" without an extra round-trip:
-
-- `previousLogin` — the value of `user.lastLogin` BEFORE we update it. Equals `null` for the very first login.
-- `lastLogin` — the timestamp we just wrote.
-
-Both are best-effort. The framework wraps the adapter update in `tryCatch` so older schemas missing the column won't break login. If your `User` model doesn't have a `lastLogin` column, the fields will be `undefined` on the session and the UI should treat them as optional.
-
-## Reason-key reference (credentials only)
-
-| Reason key                          | Meaning                                                              |
-| ----------------------------------- | -------------------------------------------------------------------- |
-| `login.empty`                       | Email or password was blank after normalization.                     |
-| `login.invalidEmailFormat`          | `validator.isEmail` rejected the address.                            |
-| `login.emailCharacterLimit`         | Email exceeded `auth.emailMaxLength`.                                |
-| `login.nameCharacterLimit`          | Name exceeded `auth.nameMaxLength`.                                  |
-| `login.passwordCharacterMinimum`    | Password shorter than `auth.passwordPolicy.minLength`.               |
-| `login.passwordCharacterLimit`      | Password longer than `auth.passwordPolicy.maxLength`.                |
-| `login.passwordRequiresUppercase`   | Policy requires `[A-Z]`.                                             |
-| `login.passwordRequiresLowercase`   | Policy requires `[a-z]`.                                             |
-| `login.passwordRequiresNumber`      | Policy requires `\d`.                                                |
-| `login.passwordRequiresSpecial`     | Policy requires a non-alphanumeric character.                        |
-| `login.passwordTooCommon`           | Plaintext appears in the bundled common-passwords blocklist.         |
-| `login.passwordNotMatch`            | Register branch only — `password !== confirmPassword`.               |
-| `login.emailExists`                 | Register branch — `findByEmail` returned an existing user.           |
-| `login.createUserFailed`            | Adapter `create` resolved without throwing but returned falsy.       |
-| `login.userNotFound`                | Login branch — no user for `{ email, provider: 'credentials' }`.     |
-| `login.wrongPassword`               | Login branch — bcrypt compare returned false.                        |
-| `login.loggedIn`                    | Success — login.                                                     |
-| `login.userCreated`                 | Success — register.                                                  |
-| `api.internalServerError`           | Adapter threw or another infrastructure error bubbled up.            |
-
-Custom reason keys can be returned by `preLogin` / `preRegister` handlers via the stop-signal contract.
-
-## When to call `loginWithCredentialsCore` / `registerWithCredentials` directly
-
-The dispatcher only exists because the HTTP route is a single POST endpoint that wants one entry point. Prefer the direct functions whenever you control the call site:
-
-- **Custom CLI** — `lucky user create --email ...` wires `registerWithCredentials` directly. No body-shape inspection needed.
-- **Admin "create user" panel** — `registerWithCredentials` from the admin endpoint, gated by an admin guard.
-- **Programmatic test setup** — your integration tests likely seed users via `registerWithCredentials` because they know the user doesn't exist yet.
-- **Auto-login after register** — call `registerWithCredentials` then `loginWithCredentialsCore` in sequence.
-
-The dispatcher is safe to use from anywhere — it just adds an unnecessary `if/else` when you already know the branch.
-
-## Hook recipes
-
-```ts
-// Block unverified users
-registerHook('preLogin', async ({ email, provider }) => {
-  if (provider !== 'credentials') return;
-  const user = await prisma.user.findFirst({ where: { email } });
-  if (user && !user.verified) {
-    return { stop: true, errorCode: 'login.notVerified' };
-  }
-});
-
-// Notify on every new registration
-registerHook('postRegister', async ({ userId, provider }) => {
-  await sendInternalNotification(`new ${provider} user: ${userId}`);
-});
-
-// Defer creating ancillary records until after the user is created
-registerHook('postRegister', async ({ userId }) => {
-  await prisma.userPreferences.create({ data: { userId, theme: 'dark' } });
-});
-```
-
-See [`./hooks.md`](./hooks.md) for the full hook reference and the stop-signal contract.
-
-## Related
-
-- [`./password-reset.md`](./password-reset.md) — forgot-password + in-session password change.
-- [`./user-adapter.md`](./user-adapter.md) — replacing the Prisma-backed user store.
-- [`./hooks.md`](./hooks.md) — `preLogin` / `postLogin` / `preRegister` / `postRegister` payload reference.
-- [`./session-management.md`](./session-management.md) — what `saveSession(token, user, true)` does after a successful login.
-- [`./oauth-providers.md`](./oauth-providers.md) — the OAuth alternative to credentials auth.
-- Architecture: [`/docs/ARCHITECTURE_AUTH.md`](../../../docs/ARCHITECTURE_AUTH.md).
+# Credentials auth
+
+Deep-dive on the email + password authentication flow exposed by `@luckystack/login`. This document covers the dispatcher contract, input normalization, validation, the underlying register / login functions, and the hooks fired along the way. All references point at the canonical implementation in [`./src/login.ts`](../src/login.ts).
+
+---
+
+## The two-in-one dispatcher
+
+The HTTP `/auth/api/credentials` route — wired by `@luckystack/server` — calls a single entry point:
+
+```ts
+import { loginWithCredentials } from '@luckystack/login';
+
+const result = await loginWithCredentials({
+  email,
+  password,
+  name,            // present only when the client is registering
+  confirmPassword, // present only when the client is registering
+});
+```
+
+`loginWithCredentials` is a thin dispatcher. It inspects the shape of the body to decide whether the caller is logging in or registering:
+
+```ts
+if (creds.name && creds.confirmPassword) {
+  return registerWithCredentials({ ... });
+}
+return loginWithCredentialsCore({ ... });
+```
+
+The rule is intentionally minimal: presence of both `name` and `confirmPassword` triggers the register branch; any other shape (just `email` + `password`) triggers the login branch. There is no `mode` parameter, no second route, and no separate URL — one POST handles both flows so the front-end can ship one form component.
+
+When you wire a non-HTTP auth surface (CLI, custom socket event, an admin "impersonate" tool) and you already know which side you want, skip the dispatcher and call `loginWithCredentialsCore` or `registerWithCredentials` directly. The dispatcher is purely a convenience for the unified HTTP route.
+
+## Signatures
+
+```ts
+// Dispatcher
+const loginWithCredentials = async (params: {
+  email?: string;
+  password?: string;
+  name?: string;
+  confirmPassword?: string;
+}) => Promise<
+  | { status: true;  reason: string; newToken?: string; session: SessionLayout }
+  | { status: false; reason: string }
+>;
+
+// Login-only entry point
+const loginWithCredentialsCore = async (input: {
+  email: string;
+  password: string;
+}) => Promise<
+  | { status: true;  reason: 'login.loggedIn'; newToken: string; session: SessionLayout }
+  | { status: false; reason: string }
+>;
+
+// Register-only entry point
+const registerWithCredentials = async (input: {
+  email: string;
+  password: string;
+  name: string;
+  confirmPassword: string;
+}) => Promise<
+  | { status: true;  reason: 'login.userCreated'; session: SessionLayout }
+  | { status: false; reason: string }
+>;
+```
+
+`reason` is always an i18n key — the installer-side translator turns it into a human-readable message. Never render it raw. See [`docs/ARCHITECTURE_AUTH.md`](../../../docs/ARCHITECTURE_AUTH.md) for the full list of canonical reason keys.
+
+## Input normalization
+
+`normalizeCredentials(params)` runs first, producing a `NormalizedCredentials` object that the rest of the flow consumes. Each transformation exists for a specific reason:
+
+| Field             | Transformation                              | Why                                                                                                                                       |
+| ----------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `email`           | `trim().toLowerCase()`                      | Case-insensitive lookup; trailing/leading whitespace stripped so a copy-paste from a chat client doesn't break the find.                  |
+| `password`        | Left raw                                    | Bcrypt operates on bytes. The password never reaches HTML, JSON-as-HTML, or a SQL string interpolation, so HTML-escaping it is harmful.   |
+| `name`            | `validator.escape(name)` when present       | The name IS surfaced to the UI as text. Pre-escape `<`, `>`, `&`, `"`, `'` to neutralize stored XSS in any consumer that renders it raw.  |
+| `confirmPassword` | Left raw                                    | Must be byte-identical to `password` for the `password !== confirmPassword` equality check. Escaping only one half breaks special chars.  |
+
+The "escape `confirmPassword` too" mistake is the subject of a long-standing comment in `normalizeCredentials` — that bug previously made any password containing `&`, `<`, `>`, `"`, or `'` fail registration silently. Don't reintroduce it.
+
+## Shape validation
+
+`validateCredentialsShape(creds)` is the next gate. It returns `{ status: false, reason }` on the first failure, or `null` when every check passes:
+
+1. **Empty check** — `email` and `password` must both be non-empty. Reason: `login.empty`.
+2. **Email length** — capped at `auth.emailMaxLength`. Reason: `login.emailCharacterLimit`.
+3. **Name length** — only checked when `name` is present (register branch). Capped at `auth.nameMaxLength`. Reason: `login.nameCharacterLimit`.
+4. **Email format** — `validator.isEmail(email)` after normalization. Reason: `login.invalidEmailFormat`.
+5. **Password policy** — `validatePassword(password)` from [`./src/passwordPolicy.ts`](../src/passwordPolicy.ts). Returns a reason key (`login.passwordCharacterMinimum`, `login.passwordRequiresUppercase`, `login.passwordTooCommon`, etc.) or `null`.
+
+Length limits live in `ProjectConfig.auth` and are resolved at call time, so consumers can override them through `registerProjectConfig` without restarting the framework.
+
+## Register flow
+
+`registerWithCredentials` is the canonical "new user" path:
+
+1. **Confirm-password match** — `password !== confirmPassword` fails with `login.passwordNotMatch`.
+2. **`preRegister` hook** — fires with `{ email, provider: 'credentials', name }`. A handler can return a `HookStopSignal` (`{ stop: true, errorCode: '...' }`) to abort; the signal's `errorCode` becomes the `reason`.
+3. **Duplicate-email guard** — `userAdapter.findByEmail({ email, provider: 'credentials' })`. A match returns `login.emailExists`.
+4. **Hash the password** — `bcrypt.genSalt(auth.bcryptRounds)` → `bcrypt.hash(plaintext, salt)`. The default `bcryptRounds` is 10; tighten it on production deployments behind a sufficient CPU budget.
+5. **Create the user** — `userAdapter.create({...})` with the assembled record. `avatarFallback` is a random hex color so the avatar component has something to render until the user uploads an image.
+6. **`postRegister` hook** — fires with `{ userId, provider: 'credentials' }`.
+7. **Return** — `{ status: true, reason: 'login.userCreated', session: sanitizeUserForSession(user) }`.
+
+Note that registration does NOT auto-login. The dispatcher returns the sanitized user record so the front-end can show a "welcome" screen, but `newToken` is undefined — the user follows the register response with an explicit login (or the front-end posts the same credentials through the login branch). Auto-login on register is something a consumer can layer on top by chaining the two calls.
+
+## Login flow
+
+`loginWithCredentialsCore` is the "existing user" path:
+
+1. **`preLogin` hook** — fires with `{ email, provider: 'credentials' }`. Same stop-signal contract as `preRegister`.
+2. **User lookup** — `userAdapter.findByEmail({ email, provider: 'credentials' })`. Missing user returns `login.userNotFound`.
+3. **Password check** — `bcrypt.compare(plaintext, user.password)`. Mismatch returns `login.wrongPassword`. (We do not differentiate "no user" from "wrong password" in production — see [`docs/ARCHITECTURE_AUTH.md`](../../../docs/ARCHITECTURE_AUTH.md) for the anti-enumeration design. The two reason keys exist for dev-mode diagnostics only.)
+4. **Mint token** — 32 random bytes, hex-encoded, 64 chars total.
+5. **Best-effort `lastLogin` update** — `userAdapter.update(id, { lastLogin: new Date() })` wrapped in `tryCatch`. Silently no-ops if the column doesn't exist on the consumer's schema.
+6. **Build the session** — `sanitizeUserForSession(user)` strips the password hash, then `token`, `lastLogin`, `previousLogin` are layered on. The avatar resolution step below is run before saving.
+7. **Avatar resolution** — if `<uploadsDir>/<userId>.webp` exists, set `session.avatar = '<userId>.webp'`. The path is resolved at call time via `getUploadsDir()` so consumer overrides win.
+8. **Save the session** — `saveSession(token, user, true)`. The `true` flag triggers `preSessionCreate` / `postSessionCreate`, runs single-session enforcement, mints a CSRF token, and broadcasts the new session over Socket.io.
+9. **`postLogin` hook** — `{ userId, provider: 'credentials', isNewUser: false, token }`.
+10. **Return** — `{ status: true, reason: 'login.loggedIn', newToken, session }`.
+
+`isNewUser` is always `false` for credentials login. It exists in the payload because `loginCallback` (OAuth) shares the same `postLogin` hook and DOES distinguish first-time-vs-returning, and we want a single audit hook to handle both.
+
+## Session sanitization
+
+`sanitizeUserForSession<T extends { password?: unknown }>(user)` strips the `password` key via destructuring:
+
+```ts
+const sanitizeUserForSession = <T extends { password?: unknown }>(user: T): Omit<T, 'password'> => {
+  const { password: _password, ...safeUser } = user;
+  return safeUser;
+};
+```
+
+The bcrypt hash should never leave the server. The session is broadcast to clients (`socketEventNames.updateSession`), so a `password` field on it would be a stored-credential leak. Every login path runs through this helper before `saveSession`.
+
+## `lastLogin` and `previousLogin`
+
+Both fields are surfaced on the session layout so the UI can show "Last signed in 3 days ago" without an extra round-trip:
+
+- `previousLogin` — the value of `user.lastLogin` BEFORE we update it. Equals `null` for the very first login.
+- `lastLogin` — the timestamp we just wrote.
+
+Both are best-effort. The framework wraps the adapter update in `tryCatch` so older schemas missing the column won't break login. If your `User` model doesn't have a `lastLogin` column, the fields will be `undefined` on the session and the UI should treat them as optional.
+
+## Reason-key reference (credentials only)
+
+| Reason key                          | Meaning                                                              |
+| ----------------------------------- | -------------------------------------------------------------------- |
+| `login.empty`                       | Email or password was blank after normalization.                     |
+| `login.invalidEmailFormat`          | `validator.isEmail` rejected the address.                            |
+| `login.emailCharacterLimit`         | Email exceeded `auth.emailMaxLength`.                                |
+| `login.nameCharacterLimit`          | Name exceeded `auth.nameMaxLength`.                                  |
+| `login.passwordCharacterMinimum`    | Password shorter than `auth.passwordPolicy.minLength`.               |
+| `login.passwordCharacterLimit`      | Password longer than `auth.passwordPolicy.maxLength`.                |
+| `login.passwordRequiresUppercase`   | Policy requires `[A-Z]`.                                             |
+| `login.passwordRequiresLowercase`   | Policy requires `[a-z]`.                                             |
+| `login.passwordRequiresNumber`      | Policy requires `\d`.                                                |
+| `login.passwordRequiresSpecial`     | Policy requires a non-alphanumeric character.                        |
+| `login.passwordTooCommon`           | Plaintext appears in the bundled common-passwords blocklist.         |
+| `login.passwordNotMatch`            | Register branch only — `password !== confirmPassword`.               |
+| `login.emailExists`                 | Register branch — `findByEmail` returned an existing user.           |
+| `login.createUserFailed`            | Adapter `create` resolved without throwing but returned falsy.       |
+| `login.userNotFound`                | Login branch — no user for `{ email, provider: 'credentials' }`.     |
+| `login.wrongPassword`               | Login branch — bcrypt compare returned false.                        |
+| `login.loggedIn`                    | Success — login.                                                     |
+| `login.userCreated`                 | Success — register.                                                  |
+| `api.internalServerError`           | Adapter threw or another infrastructure error bubbled up.            |
+
+Custom reason keys can be returned by `preLogin` / `preRegister` handlers via the stop-signal contract.
+
+## When to call `loginWithCredentialsCore` / `registerWithCredentials` directly
+
+The dispatcher only exists because the HTTP route is a single POST endpoint that wants one entry point. Prefer the direct functions whenever you control the call site:
+
+- **Custom CLI** — `lucky user create --email ...` wires `registerWithCredentials` directly. No body-shape inspection needed.
+- **Admin "create user" panel** — `registerWithCredentials` from the admin endpoint, gated by an admin guard.
+- **Programmatic test setup** — your integration tests likely seed users via `registerWithCredentials` because they know the user doesn't exist yet.
+- **Auto-login after register** — call `registerWithCredentials` then `loginWithCredentialsCore` in sequence.
+
+The dispatcher is safe to use from anywhere — it just adds an unnecessary `if/else` when you already know the branch.
+
+## Hook recipes
+
+```ts
+// Block unverified users
+registerHook('preLogin', async ({ email, provider }) => {
+  if (provider !== 'credentials') return;
+  const user = await prisma.user.findFirst({ where: { email } });
+  if (user && !user.verified) {
+    return { stop: true, errorCode: 'login.notVerified' };
+  }
+});
+
+// Notify on every new registration
+registerHook('postRegister', async ({ userId, provider }) => {
+  await sendInternalNotification(`new ${provider} user: ${userId}`);
+});
+
+// Defer creating ancillary records until after the user is created
+registerHook('postRegister', async ({ userId }) => {
+  await prisma.userPreferences.create({ data: { userId, theme: 'dark' } });
+});
+```
+
+See [`./hooks.md`](./hooks.md) for the full hook reference and the stop-signal contract.
+
+## Related
+
+- [`./password-reset.md`](./password-reset.md) — forgot-password + in-session password change.
+- [`./user-adapter.md`](./user-adapter.md) — replacing the Prisma-backed user store.
+- [`./hooks.md`](./hooks.md) — `preLogin` / `postLogin` / `preRegister` / `postRegister` payload reference.
+- [`./session-management.md`](./session-management.md) — what `saveSession(token, user, true)` does after a successful login.
+- [`./oauth-providers.md`](./oauth-providers.md) — the OAuth alternative to credentials auth.
+- Architecture: [`/docs/ARCHITECTURE_AUTH.md`](../../../docs/ARCHITECTURE_AUTH.md).