@luckystack/login 0.10.2 → 0.12.0

package/AGENTS.md

@@ -0,0 +1,7 @@
+# @luckystack/login — design context
+
+Login handles credentials, OAuth, sessions and their lifecycle; consuming applications own identity storage and may register user/session adapters. Do not store persistent user data in sessions. Sanitize session fields before sending them to browsers; never log full tokens or return password hashes. Source: `src/sessionSanitizer.ts`, `src/session.ts`, `src/userAdapter.ts`.
+
+Keep account linking a deliberate product/security choice: changing from provider-scoped accounts to unified email accounts requires database uniqueness and verified identity assumptions (`src/accountStrategy.ts`). Password policy belongs to registration/change/reset, not failed login counting against existing passwords (`src/login.ts`, `src/passwordPolicy.ts`). Keep password-reset and email-change secrets single-use and hashed at rest (`../core/src/oneTimeToken.ts`). An unknown reset email must not change visible behavior (`src/forgotPassword.ts`).
+
+OAuth state protects the callback, and post-login redirects must be validated against trusted origins, including any return URL carried in state. Never turn an untrusted redirect into an authenticated bounce; never silently broaden CORS to make one work. Cookie sessions require CSRF and carefully scoped cross-origin rules. Source: `src/login.ts`, `src/redirectResolver.ts`, `../server/src/httpRoutes/authCallbackRoute.ts`. See `docs/redirect-validation.md`, `docs/session-management.md`, `../server/AGENTS.md`.

package/CHANGELOG.md

@@ -5,7 +5,18 @@ All notable changes to `@luckystack/login` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.12.0] - 2026-10-15
+
+### Changed
+
+- Requires Node.js 22.13 or newer (was 20). Node 20 stopped receiving security updates in April 2026, and the scaffold's lint toolchain (ESLint 10) needs 22.13.
+
+## [0.11.0] - 2026-10-14
+
+### Changed
+
+- Type declarations are emitted per source file by TypeScript 7 (`tsc -b`) instead of one bundled `.d.ts` per entry, so the framework build no longer runs package by package. The exported types are unchanged; relative imports inside the declarations carry `.js`, so `moduleResolution: "node16"`/`"nodenext"` projects resolve them as before.
+- Package design guidance now ships as `AGENTS.md`, not `CLAUDE.md`. Handwritten docs focus on rationale and safety, retaining a minimal existing-project email-code/2FA adoption checklist including persistence and encryption-key prerequisites.
 
 ## [0.10.0] - 2026-09-03
 

package/README.md

@@ -1,240 +1,12 @@
 # @luckystack/login
 
-> Authentication for [LuckyStack](https://github.com/ItsLucky23/LuckyStack-v2). Credentials + OAuth (Google, GitHub, Facebook, Discord, Microsoft), Redis-backed default sessions with a swappable session adapter, single-session enforcement, and lifecycle hooks (`preLogin`, `preRegister`, `preLogout`, `preSessionCreate`, `preSessionDelete` and their `post*` counterparts).
+Authentication and session lifecycle for LuckyStack, with credential, OAuth and adapter-backed identity options. Install with `npm install @luckystack/login socket.io`; add optional `@prisma/client` for the default user adapter and `@luckystack/email` for framework-managed email flows. Register user/session adapters before handling logins. Consult `package.json`, `src/register.ts` and `src/userAdapter.ts` for integration requirements.
 
-## Install
+Before switching an existing app to unified provider accounts: reconcile duplicate emails and dependent rows; enforce email uniqueness in the database (application checks cannot close the registration race); ensure a custom user adapter implements cross-provider email lookup; then enable the strategy. Changing cookie policy requires a CSRF/origin review. OAuth redirects must pass trusted-origin validation. Password-reset responses must not reveal whether an account exists; never expose tokens or hashes in sessions. See [design context](./AGENTS.md), [session safety](./docs/session-management.md), [redirect trust](./docs/redirect-validation.md) and [account strategy](./docs/user-adapter.md).
 
-```bash
-npm install @luckystack/login socket.io
-```
+## Existing-project email-code / 2FA adoption
 
-The default user adapter uses Prisma; install optional peer `@prisma/client` when you use it. Framework-mode email flows additionally need optional peer `@luckystack/email`. Projects with custom `UserAdapter` and `SessionAdapter` implementations can use another data layer and session store.
-
-## Quickstart
-
-```ts
-import { loginWithCredentials, getSession, logout } from '@luckystack/login';
-import { registerHook } from '@luckystack/core';
-
-// Block login for unverified users:
-registerHook('preLogin', async ({ email }) => {
-  const user = await prisma.user.findFirst({ where: { email } });
-  if (user && !user.verified) {
-    return { stop: true, errorCode: 'login.notVerified' };
-  }
-});
-
-// Inside an /auth route handler:
-const result = await loginWithCredentials({ email, password });
-// → { status: true, reason, newToken, session } on success
-// → { status: false, reason } on failure (including hook-stop with the hook's errorCode)
-```
-
-The default `redisSessionAdapter` stores sessions under `${PROJECT_NAME}-session:<token>` and applies sliding expiration (every authenticated read extends the TTL by `ProjectConfig.session.expiryDays`). Register a custom `SessionAdapter` when sessions should live in another store.
-
-## Hooks
-
-`pre*` hooks fire before the side-effect and may return a `HookStopSignal` to abort. `post*` hooks fire after success. Payload types live in `./hookPayloads.ts` and are merged into `@luckystack/core`'s `HookPayloads` via module augmentation.
-
-| Hook | Aborts | Fires from |
-| --- | --- | --- |
-| `preLogin` / `postLogin` | yes | `loginWithCredentials`, `loginCallback` |
-| `preRegister` / `postRegister` | yes | `loginWithCredentials` (register branch), `loginCallback` (new OAuth user) |
-| `preLogout` / `postLogout` | yes | `logout` |
-| `preSessionCreate` / `postSessionCreate` | yes | `saveSession({ newUser: true })` |
-| `preSessionDelete` / `postSessionDelete` | yes | `deleteSession` |
-
-## OAuth provider registry
-
-```ts
-import {
-  registerOAuthProviders,
-  googleProvider,
-  githubProvider,
-  credentialsProvider,
-} from '@luckystack/login';
-
-registerOAuthProviders([
-  credentialsProvider(),
-  googleProvider({
-    clientId: process.env.GOOGLE_CLIENT_ID,
-    clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-    callbackUrl: `http://localhost:80/auth/callback/google`,
-  }),
-  githubProvider({
-    clientId: process.env.GITHUB_CLIENT_ID,
-    clientSecret: process.env.GITHUB_CLIENT_SECRET,
-    callbackUrl: `http://localhost:80/auth/callback/github`,
-  }),
-]);
-```
-
-Built-in helpers: `googleProvider`, `githubProvider`, `discordProvider`, `facebookProvider`, `microsoftProvider`, `credentialsProvider`. Each non-credentials helper takes `{ clientId, clientSecret, callbackUrl }` and returns a fully-typed `FullOAuthProvider` with the provider's authorize/token/userinfo URLs and standard scopes prefilled. Pass anything that satisfies the `OAuthProvider` interface to register custom providers — see [`packages/login/src/oauthProviders.ts`](./src/oauthProviders.ts) for the canonical shape.
-
-### Provider options
-
-Every helper accepts the base shape plus optional overrides for self-hosted instances and provider-specific tunables.
-
-| Option | Applies to | Default | When to override |
-| --- | --- | --- | --- |
-| `clientId` | all | — | Required. The OAuth app's client identifier. |
-| `clientSecret` | all | — | Required. The OAuth app's client secret. |
-| `callbackUrl` | all | — | Required. Must match the URL registered with the provider — your BACKEND origin + `/auth/callback/<name>` (dev `http://localhost:80/auth/callback/<name>`, prod `https://your-domain.com/auth/callback/<name>`). |
-| `endpoints?.authorizationURL` | all | provider-default | GitHub Enterprise host, Microsoft custom-tenant authorize URL, internal auth proxy, etc. |
-| `endpoints?.tokenExchangeURL` | all | provider-default | Same use cases as `authorizationURL`. |
-| `endpoints?.userInfoURL` | all | provider-default | Self-hosted GitHub Enterprise / Microsoft Graph mirror, etc. |
-| `apiVersion?` | `facebookProvider`, `microsoftProvider` | facebook: `v18.0`, microsoft: `v2.0` | Pin to a known-good Graph API version when the upstream rolls out breaking changes. |
-| `tenant?` | `microsoftProvider` | `'common'` | Restrict logins to a specific Azure AD tenant ID. Use a UUID or `'organizations'` / `'consumers'`. |
-| `graphApiVersion?` | `microsoftProvider` | `'v1.0'` | Pin the Microsoft Graph version used to fetch the user profile (separate from the OAuth `apiVersion`). |
-
-Example — self-hosted GitHub Enterprise:
-
-```ts
-githubProvider({
-  clientId: process.env.GITHUB_CLIENT_ID,
-  clientSecret: process.env.GITHUB_CLIENT_SECRET,
-  callbackUrl: `http://localhost:80/auth/callback/github`,
-  endpoints: {
-    authorizationURL: 'https://github.acme.example/login/oauth/authorize',
-    tokenExchangeURL: 'https://github.acme.example/login/oauth/access_token',
-    userInfoURL: 'https://github.acme.example/api/v3/user',
-  },
-});
-```
-
-Example — single-tenant Microsoft Entra ID:
-
-```ts
-microsoftProvider({
-  clientId: process.env.MICROSOFT_CLIENT_ID,
-  clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
-  callbackUrl: `http://localhost:80/auth/callback/microsoft`,
-  tenant: process.env.MICROSOFT_TENANT_ID, // 'common' for any tenant; UUID for a single tenant.
-  apiVersion: 'v2.0',                       // OAuth endpoint version
-  graphApiVersion: 'v1.0',                  // Graph endpoint version
-});
-```
-
-## User adapter
-
-By default the package reads / writes the Prisma `User` model directly. To bind auth flows to a different table (multi-tenant, alternative ORM, soft-deleted users, etc.), register your own `UserAdapter`:
-
-```ts
-import { registerUserAdapter, defaultPrismaUserAdapter } from '@luckystack/login';
-
-registerUserAdapter({
-  ...defaultPrismaUserAdapter,
-  findByEmail: async (email) => {
-    const user = await prisma.user.findFirst({ where: { email, deletedAt: null } });
-    return user;
-  },
-});
-```
-
-## Account strategy: per-provider vs unified
-
-`auth.providerAccountStrategy` (in `registerProjectConfig`) controls how the same email address is treated across sign-in providers:
-
-| Strategy | Behavior | Schema |
-|---|---|---|
-| `'per-provider'` (default) | `sam@x.com` via Google and via GitHub are **two separate `User` rows**. Lookups are scoped to `(email, provider)`. | `@@unique([email, provider])` recommended. |
-| `'unified'` | `sam@x.com` maps to **one `User` row**; signing in via a new provider links to the existing account (credentials login, OAuth find-or-create, and register dedupe all resolve by email alone). | `email` must be `@unique`. |
-
-```ts
-registerProjectConfig({ auth: { providerAccountStrategy: 'unified' } });
-```
-
-**Migrating an existing project to `'unified'`** (the strategy reads accounts by email irrespective of provider, so the DB must enforce one row per email):
-
-1. **Dedupe existing rows.** If you previously ran `'per-provider'`, the same email may already exist under multiple providers. Merge or remove duplicates so each email appears once. (Pick the row to keep — usually the credentials account or the earliest — repoint related rows, delete the rest.)
-2. **Make `email` unique** in `prisma/schema.prisma`:
-   ```prisma
-   model User {
-     // ...
-     email    String  @unique   // was: email String  (+ optional @@unique([email, provider]))
-     provider String              // now records the ORIGINAL signup provider only
-   }
-   ```
-   Then `prisma migrate` (or `db push`). The DB constraint closes the registration race that the application-level check alone cannot.
-3. **No code change is required** beyond the config flag — the default `UserAdapter` already implements `findByEmailAnyProvider`. A **custom** `UserAdapter` must add `findByEmailAnyProvider({ email })` (resolve by email, ignoring provider); if it doesn't, the framework logs a one-time warning and falls back to provider-scoped lookup so the misconfiguration is visible rather than silent.
-
-## Post-login redirect
-
-Compute the OAuth callback destination dynamically (per-user, per-tenant, per-provider):
-
-```ts
-import { registerPostLoginRedirect } from '@luckystack/login';
-
-registerPostLoginRedirect(async ({ user, provider }) => {
-  if (user.organizationId) return `/org/${user.organizationId}`;
-  return '/welcome';
-});
-```
-
-## Password reset primitives
-
-Used by the `forgotPassword: 'framework'` mode and exported for `'custom'` consumers who want to drive their own flow:
-
-```ts
-import {
-  createPasswordResetToken,
-  consumePasswordResetToken,
-  updatePasswordHash,
-  verifyPassword,
-  sendPasswordResetEmail, // requires @luckystack/email registered
-} from '@luckystack/login';
-```
-
-`sendPasswordResetEmail` is a no-op when `@luckystack/email` has not been registered, so you can keep the import unconditionally.
-
-## Public API
-
-| Export | Purpose |
-| --- | --- |
-| `loginWithCredentials(params)` | Combined login/register dispatcher. Routes to `register*` or `login*` based on the body shape (presence of `confirmPassword`). Used by the HTTP `/auth/api/credentials` route. |
-| `registerWithCredentials({ email, password, name, confirmPassword })` | Register-only entry point. Use this when you wire a custom auth surface that bypasses the dispatcher's body-shape branching. |
-| `loginWithCredentialsCore({ email, password })` | Login-only entry point. Same idea as `registerWithCredentials`. |
-| `loginCallback(pathname, req, res)` | OAuth state-exchange handler — wired to `/auth/callback/<provider>` by `@luckystack/server`. |
-| `createOAuthState(providerName)` | Issue a CSRF state token (Redis, NX, TTL from project config). |
-| `logout({ token, socket, userId })` | End a single socket's session. |
-| `saveSession(token, user, newUser?)` | Write through the active `SessionAdapter` + broadcast to existing connections. |
-| `getSession(token)` | Read + slide expiration through the active adapter. Dispatches `preSessionRefresh` / `postSessionRefresh` around the adapter TTL refresh. |
-| `deleteSession(token)` | Hard delete + clean up active-tokens set. |
-| `getAllSessions()` | Admin utility — scans all sessions. |
-| `revokeUserSessions(userId)` | Force-logout every active session for a user. |
-| `sessionKeyFor(token)` / `activeUsersKeyFor(userId)` | Centralized Redis-key builders (`{projectName}-session:{token}` / `{projectName}-activeUsers:{userId}`). Use these when you read or scan session data from outside `@luckystack/login` so the key shape stays in lockstep. |
-| `registerOAuthProviders(list)` / `getOAuthProviders()` / `isFullOAuthProvider(p)` | OAuth registry. |
-| `googleProvider`, `githubProvider`, `discordProvider`, `facebookProvider`, `microsoftProvider`, `credentialsProvider` | Built-in provider factories. |
-| `registerUserAdapter(adapter)` / `getUserAdapter()` / `isUserAdapterRegistered()` / `defaultPrismaUserAdapter` | Pluggable user store. |
-| `registerSessionAdapter(adapter)` / `getSessionAdapter()` / `redisSessionAdapter` | Pluggable session storage; Redis is the default. |
-| `registerPostLoginRedirect(resolver)` / `getPostLoginRedirect()` | Dynamic redirect resolution. |
-| `createPasswordResetToken`, `consumePasswordResetToken`, `updatePasswordHash`, `verifyPassword`, `sendPasswordResetEmail` | Password-reset primitives. |
-
-Types: `BaseSessionLayout`, `SessionLocation`, `AuthProps` (re-exported from `@luckystack/core`); `OAuthProvider`, `CredentialsProvider`, `FullOAuthProvider`, `UserAdapter`, `UserAdapterCreateInput`, `UserRecord`, `PostLoginRedirectResolver`, `PostLoginRedirectInput`, plus all `Pre*Payload` / `Post*Payload` types.
-
-## Stored-XSS warning: OAuth `name` fields
-
-`loginCallback` reads the user's display name straight from the OAuth provider's profile response and stores it on the `User.name` column unsanitized. That is fine for plain text rendering and for the framework's avatar-fallback initials, but **becomes stored XSS the moment a consumer renders the name as raw HTML** (e.g. `dangerouslySetInnerHTML`, an HTML email body, a server-rendered widget). Two recommended mitigations on the consumer side:
-
-- Render names with React text nodes (the default; safe).
-- Strip or escape any `<` / `>` characters before injecting names into HTML emails or non-React surfaces.
-
-If your project has no such surfaces this is informational. The framework intentionally does not silently mutate the field because some apps need exact-match search across providers.
-
-## Related architecture docs
-
-- [`docs/ARCHITECTURE_AUTH.md`](../../docs/ARCHITECTURE_AUTH.md) — OAuth + credentials lifecycle, allowed-origin checks, role guards.
-- [`docs/ARCHITECTURE_SESSION.md`](../../docs/ARCHITECTURE_SESSION.md) — session adapters, default Redis layout, sliding expiration, and single-session enforcement.
-- [`docs/ARCHITECTURE_EMAIL.md`](../../docs/ARCHITECTURE_EMAIL.md) — forgot-password modes (`framework` / `custom` / `disabled`).
-
-## Dependencies
-
-- Runtime: `@luckystack/core`, `bcryptjs`, `validator`, `dotenv`
-- Required peer: `socket.io@^4.8.0`
-- Optional peers: `@prisma/client@^6.19.0` (default user adapter) and `@luckystack/email` (only when `forgotPassword: 'framework'`). The package lazy-imports optional peers; every other API works without them.
-
-When using the default Prisma `UserAdapter`, your schema must include a `User` model with at least: `id`, `email`, `provider` (enum `PROVIDERS`), `password` (nullable), `name`, `avatar`, `avatarFallback`, `admin`, `language`. See [`prisma/schema.prisma`](../../prisma/schema.prisma) for the canonical shape. A custom `UserAdapter` and `SessionAdapter` can bind auth to another data layer and session store.
-
-## License
-
-MIT — see [LICENSE](../../LICENSE).
+1. Obtain feature approval before opting into `auth.emailCodeLogin: true` and/or `auth.twoFactor: 'optional'`. Register a real email sender for email-code login and any email fallback; console delivery is not sufficient.
+2. Before 2FA enrollment, add persistence for `twoFactorEnabled` (initially false), nullable `totpSecret` and nullable `recoveryCodes` to the user store. For the default Prisma adapter the fields are `Boolean @default(false)`, `String?` and `Json?` respectively. Review/apply the database change with authorization and regenerate the client; custom adapters must support these fields in `src/userAdapter.ts`.
+3. **Set a high-entropy secret `TOTP_ENCRYPTION_KEY` before enrollment. Without it new TOTP secrets are stored unencrypted.** Keep it outside Git/logs. During rotation retain previous values in `TOTP_ENCRYPTION_LEGACY_KEYS` (a JSON array of strings) until old records are migrated; deleting them early can lock users out. See `src/twoFactor.ts` for the installed keyring contract.
+4. Run `npx luckystack update --app`, review/merge UI `.new` sidecars without overwriting consumer edits, then verify enrollment, login, recovery and rotation in an authorized environment. Schema and real secrets remain manually owned.

package/dist/accountStrategy.d.ts

@@ -0,0 +1,12 @@
+import type { UserAdapter, UserRecord } from './userAdapter.js';
+/**
+ * Resolve a user account honoring the configured `providerAccountStrategy`.
+ * Use this everywhere the login flow needs "does an account for this email
+ * exist?" — register dedupe, credentials login, and OAuth find-or-create.
+ */
+export declare const resolveUserByEmail: (adapter: UserAdapter, { email, provider }: {
+    email: string;
+    provider: string;
+}) => Promise<UserRecord | null>;
+/** Test-only: reset the one-time missing-method warning latch. */
+export declare const resetAccountStrategyWarningForTests: () => void;

package/dist/authLockout.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Whether `accountKey` is currently locked out (failed-attempt counter already
+ * at/over the cap). Non-incrementing — safe to call on every login attempt.
+ * Always `false` when the feature is disabled.
+ * Pass `requesterIp` to check the IP+account composite bucket (DD-LOGIN-F5).
+ */
+export declare const isAccountLocked: (accountKey: string, requesterIp?: string) => Promise<boolean>;
+/**
+ * Increment the failed-attempt counter for `accountKey`. Call on every failed
+ * credentials login for a known/looked-up account. No-op when disabled.
+ * Pass `requesterIp` to increment the IP+account composite bucket (DD-LOGIN-F5).
+ */
+export declare const recordAuthFailure: (accountKey: string, requesterIp?: string) => Promise<void>;
+/**
+ * Reset the failed-attempt counter for `accountKey` (call after a SUCCESSFUL
+ * login so a user who eventually gets their password right isn't penalised by
+ * earlier typos). No-op when disabled.
+ * Pass `requesterIp` to clear the IP+account composite bucket (DD-LOGIN-F5).
+ */
+export declare const clearAuthFailures: (accountKey: string, requesterIp?: string) => Promise<void>;
+/**
+ * Wire the per-account lockout into the `loginFailed` hook (F7). Subscribes once
+ * (idempotent) and increments the failed-attempt counter only on a credentials
+ * LOGIN failure that carries an email AND is a genuine wrong-password attempt
+ * (see `COUNTING_REASONS`). Registration is unconditional (cheap); the recorder
+ * itself no-ops when `rateLimiting.auth.enabled` is false, so toggling the
+ * config at runtime is honoured without re-wiring.
+ */
+export declare const registerAuthLockoutHook: () => void;

package/dist/data/commonPasswords.d.ts

@@ -0,0 +1,2 @@
+/** Frozen Set for O(1) `.has()` lookups; entries are pre-lowercased. */
+export declare const COMMON_PASSWORDS: ReadonlySet<string>;

package/dist/emailChange.d.ts

@@ -0,0 +1,21 @@
+export interface EmailChangePayload {
+    userId: string;
+    newEmail: string;
+}
+/**
+ * Create a one-time email-change token bound to a user id + the new email
+ * address. Any previously issued (but not yet consumed) token for the same
+ * user is invalidated first (LOGIN-F16) so at most one confirmation link per
+ * user is redeemable. Stored in Redis with the configured TTL — only
+ * `sha256(token)` is persisted (hash-at-rest). Returns the raw token string —
+ * caller emails the token (embedded in a URL) to the NEW address so the
+ * confirmation click proves ownership of the new mailbox.
+ */
+export declare const createEmailChangeToken: (userId: string, newEmail: string) => Promise<string>;
+/**
+ * Validate and consume an email-change token. Returns the bound
+ * `{ userId, newEmail }` on success and removes the token (one-time use, atomic
+ * GET+DEL). Returns null when the token is missing, expired, malformed, or
+ * already consumed.
+ */
+export declare const consumeEmailChangeToken: (token: string) => Promise<EmailChangePayload | null>;

package/dist/emailChangeNotification.d.ts

@@ -0,0 +1,24 @@
+interface SendEmailChangeArgs {
+    userId: string;
+    newEmail: string;
+    /** Optional display name used in the email greeting (falls back to "there"). */
+    userName?: string | null;
+    /**
+     * App-facing display name used in the email greeting + subject. Falls back
+     * to `projectConfig.auth.passwordResetBrand` (the shared brand label), then
+     * to `'LuckyStack'` as the absolute fallback.
+     */
+    brand?: string;
+}
+/**
+ * Mint a one-shot email-change token and send a confirmation email to the
+ * NEW address with the tokenized URL. Returns the send result for diagnostics
+ * + the token itself (callers can audit-log it through the
+ * `postEmailChangeRequested` hook).
+ */
+export declare const sendEmailChangeConfirmation: ({ userId, newEmail, userName, brand }: SendEmailChangeArgs) => Promise<{
+    ok: boolean;
+    reason?: string;
+    token: string;
+}>;
+export {};

package/dist/emailCodeLogin.d.ts

@@ -0,0 +1,19 @@
+import { type CredentialsLoginResult } from './login.js';
+export interface RequestEmailLoginCodeInput {
+    email: string;
+    requesterIp?: string;
+}
+export type RequestEmailLoginCodeResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare const requestEmailLoginCode: ({ email, requesterIp }: RequestEmailLoginCodeInput) => Promise<RequestEmailLoginCodeResult>;
+export interface VerifyEmailLoginCodeInput {
+    email: string;
+    code: string;
+    supersedeToken?: string;
+    requesterIp?: string;
+}
+export declare const verifyEmailLoginCode: (input: VerifyEmailLoginCodeInput) => Promise<CredentialsLoginResult>;

package/dist/emailModuleLoader.d.ts

@@ -0,0 +1,13 @@
+/** Minimal surface of `@luckystack/email` that the login orchestrators use. */
+export interface EmailModule {
+    sendEmail: (input: Record<string, unknown>) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+}
+/**
+ * Dynamically import the optional `@luckystack/email` peer. Resolves to the
+ * module, or REJECTS if the package is not installed (same as a bare
+ * `import('@luckystack/email')`). Callers decide whether to `.catch(...)`.
+ */
+export declare const loadEmailModule: () => Promise<EmailModule>;

package/dist/emailOtp.d.ts

@@ -0,0 +1,33 @@
+export type EmailOtpPurpose = 'login' | '2fa';
+export declare const generateNumericCode: (digits: number) => string;
+export interface IssueEmailCodeInput {
+    purpose: EmailOtpPurpose;
+    /** Email address (login) or userId (2fa). */
+    identity: string;
+    ttlSeconds: number;
+    digits: number;
+}
+/**
+ * Mint + store a fresh code for (purpose, identity). Any previously active
+ * code for the same slot is replaced, and its attempt counter reset. Returns
+ * the RAW code exactly once — the caller emails it; only sha256(code) is
+ * stored (hash-at-rest, ADR 0010 spirit).
+ */
+export declare const issueEmailCode: ({ purpose, identity, ttlSeconds, digits }: IssueEmailCodeInput) => Promise<string>;
+export type EmailCodeVerdict = 'valid' | 'invalid' | 'expired' | 'locked';
+export interface VerifyEmailCodeInput {
+    purpose: EmailOtpPurpose;
+    identity: string;
+    code: string;
+    /** Wrong-code attempts before the code is burned (counter is server-side). */
+    maxAttempts: number;
+}
+/**
+ * Verify + consume. Verdicts: 'valid' (code matched, slot consumed),
+ * 'invalid' (wrong code, attempt recorded), 'locked' (attempt budget spent —
+ * the active code is burned so guessing can't continue), 'expired' (no active
+ * code: TTL passed, never issued, or already consumed).
+ */
+export declare const verifyEmailCode: ({ purpose, identity, code, maxAttempts }: VerifyEmailCodeInput) => Promise<EmailCodeVerdict>;
+/** Drop any active code + counter for the slot (e.g. after a completed login). */
+export declare const clearEmailCode: (purpose: EmailOtpPurpose, identity: string) => Promise<void>;

package/dist/forgotPassword.d.ts

@@ -0,0 +1,21 @@
+interface SendResetEmailArgs {
+    email: string;
+    /**
+     * App-facing display name used in the email greeting + subject. If omitted,
+     * falls back to `projectConfig.auth.passwordResetBrand`, then to `'LuckyStack'`
+     * as the absolute fallback. Real consumers should set this on either the
+     * call site OR via `projectConfig.auth.passwordResetBrand`.
+     */
+    brand?: string;
+}
+/**
+ * Look up the user by credentials-provider email, generate a reset token,
+ * and email them a reset link. Always resolves successfully regardless of
+ * whether the email matched a user (anti-enumeration). Returns the result
+ * of the email send for diagnostics.
+ */
+export declare const sendPasswordResetEmail: ({ email, brand }: SendResetEmailArgs) => Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+export {};

package/dist/hookPayloads.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Module augmentation: extends `@luckystack/core`'s `HookPayloads` interface
+ * with auth and session lifecycle hooks owned by this package.
+ *
+ * This file is picked up by the TypeScript compiler because it is in the
+ * tsconfig `include` path. A side-effect `import './hookPayloads';` in
+ * `index.ts` makes the dependency explicit for readers even though TS would
+ * merge the declaration regardless.
+ */
+import type { BaseSessionLayout } from './sessionLayout.js';
+export interface PreLoginPayload {
+    email: string;
+    provider: string;
+}
+export interface PostLoginPayload {
+    userId: string;
+    provider: string;
+    isNewUser: boolean;
+    token: string;
+}
+export interface PreRegisterPayload {
+    email: string;
+    provider: string;
+    name?: string;
+}
+export interface PostRegisterPayload {
+    userId: string;
+    provider: string;
+}
+export interface PreLogoutPayload {
+    userId: string | null;
+    token: string | null;
+}
+export interface PostLogoutPayload {
+    userId: string | null;
+    token: string | null;
+}
+export interface PreSessionCreatePayload {
+    token: string;
+    user: BaseSessionLayout;
+    persistent: boolean;
+}
+export interface PostSessionCreatePayload {
+    token: string;
+    user: BaseSessionLayout;
+    persistent: boolean;
+}
+export interface PreSessionDeletePayload {
+    token: string;
+    userId: string | null;
+}
+export interface PostSessionDeletePayload {
+    token: string;
+    userId: string | null;
+}
+export interface PasswordResetRequestedPayload {
+    /** Email the user typed in the reset form. May or may not match a real user. */
+    email: string;
+    /** True when a matching user was found and an email is being sent. */
+    matched: boolean;
+    /** The userId, when matched. */
+    userId?: string;
+    /** Token TTL in seconds. */
+    ttlSeconds?: number;
+}
+export interface PasswordResetCompletedPayload {
+    /** User whose password was reset via the forgot-password flow. */
+    userId: string;
+    /** Whether the framework auto-revoked all other active sessions. */
+    revokedOtherSessions: boolean;
+}
+export interface PasswordChangedPayload {
+    /** User whose password was changed via the in-session change flow. */
+    userId: string;
+    /** True if the user verified their current password successfully. */
+    verifiedCurrent: boolean;
+    /** Whether sessions other than the current one were revoked. */
+    revokedOtherSessions: boolean;
+}
+export interface PrePasswordResetCompletedPayload {
+    /** User whose password is about to be reset via the forgot-password flow. */
+    userId: string;
+}
+export interface PrePasswordChangedPayload {
+    /** User whose password is about to be changed via the in-session flow. */
+    userId: string;
+    /** True if the user verified their current password successfully. */
+    verifiedCurrent: boolean;
+}
+export interface PreEmailChangePayload {
+    userId: string;
+    currentEmail: string;
+    newEmail: string;
+}
+export interface PostEmailChangeRequestedPayload {
+    userId: string;
+    currentEmail: string;
+    newEmail: string;
+    sent?: boolean;
+}
+export interface PostEmailChangedPayload {
+    userId: string;
+    oldEmail: string;
+    newEmail: string;
+}
+export interface LoginFailedPayload {
+    /** Email the attempt was for, when available. */
+    email?: string;
+    /** Resolved userId, when the attempt matched a real account. */
+    userId?: string;
+    /** Auth provider (e.g. `credentials`, `google`). */
+    provider: string;
+    /** i18n reason key describing why the attempt failed. */
+    reason: string;
+    /** Which flow the failure occurred in. */
+    stage: 'login' | 'register' | 'oauth';
+    requesterIp?: string;
+}
+export interface PreAccountDeletePayload {
+    userId: string;
+    email?: string;
+}
+export interface PostAccountDeletePayload {
+    userId: string;
+    email?: string;
+}
+declare module '@luckystack/core' {
+    interface HookPayloads {
+        preLogin: PreLoginPayload;
+        postLogin: PostLoginPayload;
+        preRegister: PreRegisterPayload;
+        postRegister: PostRegisterPayload;
+        preLogout: PreLogoutPayload;
+        postLogout: PostLogoutPayload;
+        preSessionCreate: PreSessionCreatePayload;
+        postSessionCreate: PostSessionCreatePayload;
+        preSessionDelete: PreSessionDeletePayload;
+        postSessionDelete: PostSessionDeletePayload;
+        passwordResetRequested: PasswordResetRequestedPayload;
+        prePasswordResetCompleted: PrePasswordResetCompletedPayload;
+        passwordResetCompleted: PasswordResetCompletedPayload;
+        prePasswordChanged: PrePasswordChangedPayload;
+        passwordChanged: PasswordChangedPayload;
+        preEmailChange: PreEmailChangePayload;
+        postEmailChangeRequested: PostEmailChangeRequestedPayload;
+        postEmailChanged: PostEmailChangedPayload;
+        loginFailed: LoginFailedPayload;
+        preAccountDelete: PreAccountDeletePayload;
+        postAccountDelete: PostAccountDeletePayload;
+    }
+}