@luckystack/login 0.10.2 → 0.11.0

package/dist/login.d.ts

@@ -0,0 +1,96 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+import type { BaseSessionLayout as SessionLayout } from './sessionLayout.js';
+import { type UserRecord } from './userAdapter.js';
+interface LoginOrRegisterParams {
+    email?: string;
+    password?: string;
+    name?: string;
+    confirmPassword?: string;
+}
+export type TwoFactorMethod = 'totp' | 'email-code' | 'recovery-code';
+export interface CredentialsLoginSuccess {
+    status: true;
+    reason: string;
+    newToken: string;
+    session: SessionLayout;
+    requiresTwoFactor?: undefined;
+}
+export interface CredentialsLoginChallenge {
+    status: true;
+    reason: string;
+    requiresTwoFactor: true;
+    challengeToken: string;
+    twoFactorMethods: TwoFactorMethod[];
+    newToken?: undefined;
+    session?: undefined;
+}
+export interface CredentialsLoginFailure {
+    status: false;
+    reason: string;
+    newToken?: undefined;
+    session?: undefined;
+    requiresTwoFactor?: undefined;
+}
+export type CredentialsLoginResult = CredentialsLoginSuccess | CredentialsLoginChallenge | CredentialsLoginFailure;
+export declare const OAUTH_STATE_COOKIE_NAME = "ls-oauth-state";
+export interface CreateOAuthStateResult {
+    /** Opaque `state` param put on the authorize URL + echoed back on callback. */
+    state: string;
+    /**
+     * Random nonce the server must set as the value of the {@link OAUTH_STATE_COOKIE_NAME}
+     * cookie (HttpOnly, SameSite=Lax, short TTL) at the authorize redirect. The
+     * callback requires this back to accept the flow (browser-binding, F1).
+     */
+    stateCookie: string;
+    /**
+     * PKCE `code_challenge` (S256) when the provider opted into PKCE — the server
+     * appends `code_challenge=<value>&code_challenge_method=S256` to the authorize
+     * URL. `undefined` for non-PKCE providers (default).
+     */
+    codeChallenge?: string;
+}
+export declare const createOAuthState: (providerName: string, options?: {
+    usePkce?: boolean;
+    returnUrl?: string;
+}) => Promise<CreateOAuthStateResult | null>;
+declare const registerWithCredentials: ({ email, password, name, confirmPassword, }: {
+    email: string;
+    password: string;
+    name: string;
+    confirmPassword: string;
+}, options?: {
+    supersedeToken?: string;
+}) => Promise<CredentialsLoginResult>;
+export type TwoFactorGate = (user: UserRecord, context: {
+    requesterIp?: string;
+}) => Promise<CredentialsLoginChallenge | null>;
+export declare const registerTwoFactorGate: (gate: TwoFactorGate) => void;
+export declare const finalizeLogin: (user: UserRecord, options: {
+    provider: string;
+    email?: string;
+    supersedeToken?: string;
+    requesterIp?: string;
+}) => Promise<CredentialsLoginResult>;
+declare const loginWithCredentialsCore: ({ email, password }: {
+    email: string;
+    password: string;
+}, options?: {
+    supersedeToken?: string;
+    requesterIp?: string;
+}) => Promise<CredentialsLoginResult>;
+declare const loginWithCredentials: (params: LoginOrRegisterParams, options?: {
+    supersedeToken?: string;
+    requesterIp?: string;
+}) => Promise<CredentialsLoginResult>;
+export interface OAuthCallbackResult {
+    token: string;
+    redirectUrl: string;
+    userId: string;
+    provider: string;
+    isNewUser: boolean;
+}
+declare const loginCallback: (pathname: string, req: IncomingMessage, _res: ServerResponse, options?: {
+    defaultRedirectUrl?: string;
+    supersedeToken?: string;
+}) => Promise<OAuthCallbackResult | false>;
+export { loginWithCredentials, loginCallback, registerWithCredentials, loginWithCredentialsCore };

package/dist/logout.d.ts

@@ -0,0 +1,7 @@
+import { Socket } from "socket.io";
+export declare const logout: ({ token, socket, userId, skipSessionDelete }: {
+    token: string | null;
+    socket: Socket | undefined;
+    userId: string | null;
+    skipSessionDelete?: boolean;
+}) => Promise<void>;

package/dist/oauthProviders.d.ts

@@ -0,0 +1,171 @@
+export type OAuthUserData = Record<string, unknown>;
+export declare const asOAuthUserData: (value: unknown) => OAuthUserData;
+export interface CredentialsProvider {
+    name: 'credentials';
+}
+export interface FullOAuthProvider {
+    name: string;
+    clientID: string;
+    clientSecret: string;
+    callbackURL: string;
+    authorizationURL: string;
+    tokenExchangeURL: string;
+    tokenExchangeMethod: 'json' | 'form';
+    userInfoURL: string;
+    /**
+     * OAuth scopes requested at the authorization step. Consumers can extend
+     * a built-in provider's defaults to request additional permissions:
+     *
+     *   ```ts
+     *   const customGoogle = googleProvider({...});
+     *   customGoogle.scope.push('https://www.googleapis.com/auth/calendar.readonly');
+     *   ```
+     *
+     * Or pass `extraScopes` to the built-in factory (see `OAuthHelperInput`).
+     */
+    scope: string[];
+    nameKey: string;
+    emailKey: string;
+    /**
+     * Optional key on the userInfo response holding a provider "email verified"
+     * boolean. When set AND the field is present-and-falsy, the framework rejects
+     * the profile rather than trusting an unverified address — defense-in-depth
+     * against account-linking takeover under the `'unified'` strategy (SEC-21).
+     * A missing field (provider doesn't report it) is treated as "trusted",
+     * preserving behaviour for providers that don't expose the flag.
+     */
+    emailVerifiedKey?: string;
+    /**
+     * Set `true` for a provider whose userinfo ONLY returns an email once the
+     * address is confirmed with the provider (e.g. Facebook Graph `/me` omits
+     * unconfirmed emails). Such a provider exposes no separate verified flag, so
+     * the mere PRESENCE of the email is the verified signal — this opts it in so
+     * both first-login CREATION and cross-provider LINK treat it as verified.
+     * Mutually exclusive in practice with `emailVerifiedKey`.
+     */
+    emailImpliesVerified?: boolean;
+    avatarKey?: string;
+    avatarCodeKey: string;
+    getEmail?: (accessToken: string) => Promise<string | false | undefined>;
+    getAvatar?: (params: {
+        userData: OAuthUserData;
+        avatarId?: string;
+        accessToken: string;
+    }) => string | undefined | Promise<string | undefined>;
+    /**
+     * Optional per-provider hook to attach extra runtime-only data to the
+     * session (NOT to the User row). Return key/value pairs that get merged
+     * into `BaseSessionLayout` before `saveSession`. To get strict typing
+     * downstream, extend `BaseSessionLayout` via module augmentation:
+     *
+     *   ```ts
+     *   declare module '@luckystack/core' {
+     *     interface BaseSessionLayout {
+     *       googleCalendarToken?: string;
+     *     }
+     *   }
+     *   ```
+     *
+     * Data lives on the session in Redis and disappears on logout — no Prisma
+     * schema change required. Don't store secrets you wouldn't want surfaced
+     * to a user inspecting their own session.
+     */
+    extraSessionFields?: (params: {
+        userData: OAuthUserData;
+        accessToken: string;
+    }) => Promise<Record<string, unknown>> | Record<string, unknown>;
+    /**
+     * Extra query params appended to the authorization-redirect URL (CFG-21).
+     * Lets a provider request e.g. `access_type=offline`, `login_hint=...`, or
+     * override the framework's default `prompt=select_account`. The server's
+     * authorize route merges these over the built-in params (a key present here
+     * wins). Reserved OAuth params (`client_id`, `redirect_uri`, `scope`,
+     * `response_type`, `state`, `code_challenge`, `code_challenge_method`) should
+     * NOT be set here — they are framework-owned. Default unset.
+     */
+    extraAuthorizationParams?: Record<string, string>;
+    /**
+     * Opt this provider into PKCE (RFC 7636, S256) (F11). When `true`, the
+     * framework generates a `code_verifier` at flow start, stores it server-side
+     * with the OAuth state, sends `code_challenge`/`code_challenge_method=S256` on
+     * the authorize redirect, and replays the verifier at token exchange. Required
+     * by OAuth 2.1 / PKCE-mandating providers (X/Twitter, some Okta/Auth0
+     * policies). Default `false` (no PKCE — existing flows are byte-identical).
+     */
+    usePkce?: boolean;
+}
+export type OAuthProvider = CredentialsProvider | FullOAuthProvider;
+export declare const isFullOAuthProvider: (provider: OAuthProvider) => provider is FullOAuthProvider;
+export interface OAuthEndpointOverrides {
+    /** Override the provider's authorization URL (e.g. GitHub Enterprise host, Microsoft custom tenant). */
+    authorizationURL?: string;
+    /** Override the token exchange URL. */
+    tokenExchangeURL?: string;
+    /** Override the userInfo URL. */
+    userInfoURL?: string;
+}
+interface OAuthHelperInput {
+    clientId: string | undefined;
+    clientSecret: string | undefined;
+    callbackUrl: string;
+    /** Optional URL overrides for self-hosted / custom-tenant deployments. */
+    endpoints?: OAuthEndpointOverrides;
+    /**
+     * Additional OAuth scopes to request alongside the built-in defaults. Use
+     * for "give me access to the user's calendar / drive / repos" flows.
+     * Merged with the helper's default scopes; duplicates are deduplicated.
+     */
+    extraScopes?: string[];
+    /**
+     * Per-provider hook for attaching runtime-only fields to the session.
+     * See `FullOAuthProvider.extraSessionFields` for usage + module-augmentation
+     * pattern.
+     */
+    extraSessionFields?: FullOAuthProvider['extraSessionFields'];
+    /**
+     * Extra query params for the authorize redirect (CFG-21). See
+     * `FullOAuthProvider.extraAuthorizationParams`.
+     */
+    extraAuthorizationParams?: Record<string, string>;
+    /** Opt this provider into PKCE (S256) (F11). See `FullOAuthProvider.usePkce`. */
+    usePkce?: boolean;
+}
+export declare const credentialsProvider: () => CredentialsProvider;
+export declare const googleProvider: (input: OAuthHelperInput) => FullOAuthProvider;
+export declare const githubProvider: (input: OAuthHelperInput) => FullOAuthProvider;
+export declare const discordProvider: (input: OAuthHelperInput) => FullOAuthProvider;
+export interface FacebookProviderInput extends OAuthHelperInput {
+    /** Graph API version segment used in the URLs. Default `'v18.0'` (current as of 2026 — bump as Meta deprecates older versions). */
+    apiVersion?: string;
+}
+export declare const facebookProvider: (input: FacebookProviderInput) => FullOAuthProvider;
+export interface MicrosoftProviderInput extends OAuthHelperInput {
+    /** Tenant id segment in the authorize/token URLs. Default `'common'`. */
+    tenant?: string;
+    /** OAuth API version segment. Default `'v2.0'`. */
+    apiVersion?: string;
+    /** Graph API version segment for /me. Default `'v1.0'`. */
+    graphApiVersion?: string;
+    /**
+     * Allow falling back to `userPrincipalName` as the account email when Graph
+     * `/me.mail` is empty (SEC-11). A UPN is NOT guaranteed routable or verified;
+     * under the `'unified'` account strategy a UPN equal to a victim's email would
+     * link accounts, and it commonly mis-keys an account on a non-deliverable
+     * address (reset emails never arrive). Default `false` — only enable when the
+     * tenant guarantees UPN == primary SMTP. When `false` and `.mail` is empty the
+     * provider reports "no email" and the login is rejected rather than linked.
+     */
+    allowUpnFallback?: boolean;
+}
+export declare const microsoftProvider: (input: MicrosoftProviderInput) => FullOAuthProvider;
+export declare const getOAuthProviders: () => OAuthProvider[];
+export declare const registerOAuthProviders: (providers: OAuthProvider[]) => OAuthProvider[];
+/**
+ * Register a factory function that builds the provider list on first use.
+ * Prefer this over `registerOAuthProviders` from the package `register` side-
+ * effect so config/env reads are deferred to request time and survive any
+ * `registerProjectConfig` call that happens after package import.
+ * A subsequent `registerOAuthProviders` call replaces the factory.
+ */
+export declare const registerOAuthProviderFactory: (factory: () => OAuthProvider[]) => void;
+export {};

package/dist/passwordPolicy.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Validate `password` against the active project's password policy.
+ * Returns null on success, a string reason-key on the first failure.
+ *
+ * The policy lives in `projectConfig.auth.passwordPolicy` and is read at
+ * call time, so consumers can override defaults via `registerProjectConfig`.
+ */
+export declare const validatePassword: (password: string) => string | null;

package/dist/passwordReset.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Create a one-time password-reset token bound to a user id. Any previously
+ * issued (but not yet consumed) token for the same user is invalidated first
+ * (LOGIN-F16). Stored in Redis with the configured TTL — only `sha256(token)`
+ * is persisted (hash-at-rest). Returns the raw token string — caller emails it
+ * to the user (typically embedded in a URL).
+ */
+export declare const createPasswordResetToken: (userId: string) => Promise<string>;
+/**
+ * Validate and consume a password-reset token. Returns the bound userId 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 consumePasswordResetToken: (token: string) => Promise<string | null>;
+/**
+ * Bcrypt-hash a plaintext password and write it to the user record via the
+ * registered user adapter. Used by the reset flow and by the settings
+ * password-change flow. Validates against the active password policy
+ * (`projectConfig.auth.passwordPolicy`) before hashing — throws a `PasswordPolicyError`
+ * when the plaintext fails policy. Catch and surface the error code to the
+ * client; framework-mode reset/change flows already do this.
+ *
+ * ADR — DD-LOGIN-F17: this primitive intentionally does NOT revoke sessions.
+ * Session revocation is the responsibility of each calling route because the
+ * right behaviour differs per use-case:
+ *   - `reset-password/confirmReset_v1` revokes ALL sessions (`revokeUserSessions(userId, null)`)
+ *     because a forgot-password reset means the old credential is compromised.
+ *   - `settings/changePassword_v1` revokes every OTHER session but keeps the
+ *     current one active (`revokeUserSessions(userId, user.token)`) so the
+ *     user is not kicked from the device they changed the password on.
+ *   - Custom consumers may want a third behaviour (e.g. re-use the existing
+ *     token after an admin password-force) — keeping the primitive pure lets
+ *     them compose it freely.
+ * If you call this function directly, YOU must call `revokeUserSessions`
+ * afterwards unless you have a deliberate reason not to.
+ */
+export declare const updatePasswordHash: (userId: string, plaintext: string) => Promise<void>;
+/**
+ * Thrown by `updatePasswordHash` when the supplied plaintext violates the
+ * active password policy. `errorCode` matches the i18n reason key the rest
+ * of the login flow uses (e.g. `login.passwordRequiresUppercase`).
+ */
+export declare class PasswordPolicyError extends Error {
+    readonly errorCode: string;
+    constructor(errorCode: string);
+}
+/** Verify a plaintext password against a stored bcrypt hash. */
+export declare const verifyPassword: (plaintext: string, hash: string) => Promise<boolean>;

package/dist/redirectResolver.d.ts

@@ -0,0 +1,19 @@
+export interface PostLoginRedirectInput {
+    userId: string;
+    provider: string;
+    isNewUser: boolean;
+    defaultUrl: string;
+}
+export type PostLoginRedirectResolver = (input: PostLoginRedirectInput) => string | Promise<string>;
+export declare const registerPostLoginRedirect: (resolver: PostLoginRedirectResolver) => PostLoginRedirectResolver;
+export declare const getPostLoginRedirect: () => PostLoginRedirectResolver | null;
+/**
+ * Resolve a valid relative post-login result against the trusted absolute
+ * default URL supplied by the HTTP callback layer. OAuth callbacks commonly
+ * live on a separate backend origin; returning `/dashboard` unchanged would
+ * make the browser resolve it against that backend instead of the frontend.
+ *
+ * Absolute candidates and callers that supplied only a relative default stay
+ * byte-identical. Origin allowlisting happens in login.ts BEFORE this helper.
+ */
+export declare const resolvePostLoginRedirectAgainstDefault: (candidate: string, defaultUrl: string) => string;

package/dist/register.d.ts

@@ -1,2 +1 @@
-
-export {  }
+export {};

package/dist/session.d.ts

@@ -0,0 +1,73 @@
+import type { BaseSessionLayout as SessionLayout } from "./sessionLayout.js";
+/**
+ * Save or update a user session through the active session adapter.
+ *
+ * @param token - The session token (unique identifier)
+ * @param data - The session data to store
+ * @param newUser - If true, this is a new login (triggers single-session enforcement)
+ * @param options.supersedeToken - A token belonging to the SAME browser that is
+ *   being replaced by this login (e.g. re-login while already signed in). It is
+ *   excluded from single-session enforcement so the user's current device is not
+ *   kicked by its own new session. The caller is responsible for deleting it
+ *   afterwards (use `deleteSession(supersedeToken, { skipSocketLogout: true })`).
+ */
+declare const saveSession: (token: string, data: SessionLayout, newUser?: boolean, options?: {
+    supersedeToken?: string;
+}) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    errorCode: string;
+}>;
+/**
+ * Retrieve a user session through the active session adapter.
+ *
+ * @param token - The session token
+ * @param options.refresh - When false, skip the sliding-expiration TTL
+ *   extension. Defaults to true. Pass false for read-only probes (e.g. a
+ *   background audit, an admin lookup) where a stolen token should NOT earn
+ *   extra lifetime just because the server touched it (LOGIN-F9).
+ * @returns The session data or null if not found
+ */
+declare const getSession: (token: string | null, options?: {
+    refresh?: boolean;
+}) => Promise<SessionLayout | null>;
+/**
+ * Delete a user session through the active adapter and notify connected
+ * clients.
+ *
+ * @param token - The session token to delete
+ * @param options.skipSocketLogout - When true, the session data + active-token
+ *   tracking are cleaned up and the pre/post delete hooks still fire, but NO
+ *   `logout` is emitted to sockets in the token's room. Use this when the SAME
+ *   browser is replacing its session (re-login): emitting a logout would bounce
+ *   that browser to the login page and null its brand-new session.
+ * @returns true if successful
+ */
+declare const deleteSession: (token: string, options?: {
+    skipSocketLogout?: boolean;
+}) => Promise<boolean>;
+/**
+ * Get all active sessions (admin utility). Returns empty when the active
+ * adapter doesn't implement enumeration (signed-JWT-stateless, log-only).
+ *
+ * @returns Array of all session data
+ */
+declare const getAllSessions: () => Promise<SessionLayout[]>;
+/**
+ * Revoke every active session for a user, optionally keeping one alive.
+ *
+ * @param userId - The user whose sessions to revoke
+ * @param exceptToken - If provided, this session is left untouched. Pass the
+ *   caller's own token when revoking after a password change so the user
+ *   isn't logged out of the device they just changed it from. Pass null/omit
+ *   to revoke everything (account deletion, "sign out everywhere", etc.).
+ *
+ * Each revocation goes through `deleteSession`, so connected sockets are
+ * told to log out via the same flow as a normal logout. Returns the number
+ * of sessions actually revoked.
+ */
+declare const revokeUserSessions: (userId: string, exceptToken?: string | null) => Promise<number>;
+declare const sessionKeyFor: (token: string) => string;
+declare const activeUsersKeyFor: (userId: string) => string;
+export { saveSession, getSession, deleteSession, getAllSessions, revokeUserSessions, sessionKeyFor, activeUsersKeyFor };

package/dist/sessionAdapter.d.ts

@@ -0,0 +1,66 @@
+export interface SessionAdapter {
+    /** Human-readable identifier (used in logs/diagnostics). */
+    name: string;
+    /** Read the raw stored session string for `token`. Null when missing. */
+    getRaw(token: string): Promise<string | null>;
+    /**
+     * Write the raw session string for `token` with a TTL. Implementations
+     * MUST honour the TTL — sessions without one would never expire.
+     */
+    setRaw(token: string, value: string, ttlSeconds: number): Promise<void>;
+    /** Delete the session record for `token`. Idempotent. */
+    delete(token: string): Promise<void>;
+    /**
+     * Refresh the TTL on an existing session record (sliding-window
+     * expiration). Returns true when the underlying record existed and the
+     * TTL was applied, false otherwise. Implementations must not create a
+     * record on miss.
+     */
+    expire(token: string, ttlSeconds: number): Promise<boolean>;
+    /** Remaining TTL in seconds (or null when the record is missing). */
+    ttl(token: string): Promise<number | null>;
+    trackActive(userId: string, token: string, ttlSeconds: number): Promise<void>;
+    untrackActive(userId: string, token: string): Promise<void>;
+    listActive(userId: string): Promise<string[]>;
+    /**
+     * Refresh the TTL on the active-tokens-per-user record WITHOUT adding a
+     * token (sliding-window expiration parity with the session key). Called on
+     * an authenticated read so a session kept alive purely by reads does not
+     * outlive its activeUsers entry — which would otherwise let a stolen token
+     * survive a sign-out-everywhere / password reset. Optional: backends whose
+     * active-set entries do not expire independently (or that have no TTL
+     * concept) can omit it. Must not create a record on miss.
+     */
+    touchActive?(userId: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Admin walk: yield every active session record. Optional because
+     * non-scannable backends (signed-JWT-stateless, log-only) cannot
+     * enumerate. Callers fall back to a per-user listActive when omitted.
+     *
+     * **Dev/admin-only (LOGIN-F14).** Implementations scan the full keyspace and
+     * load every session into memory in one call — O(all sessions) in both Redis
+     * round-trips and memory. Do NOT call on the hot request path or from any
+     * user-facing API. Use `listActive(userId)` for per-user lookups.
+     */
+    listAll?(): Promise<{
+        token: string;
+        raw: string;
+    }[]>;
+}
+export declare const redisSessionAdapter: SessionAdapter;
+/**
+ * Replace the active session storage backend. Call once at boot from
+ * `luckystack/server/index.ts`, BEFORE the first login request. Common
+ * use cases:
+ *
+ *  - DynamoDB / Cosmos DB for serverless / edge deployments
+ *  - Postgres `sessions` table when you already operate Postgres
+ *  - signed-JWT-stateless (the adapter writes nothing, reads from the
+ *    JWT, and stores activeUsers per token in a small Redis hash)
+ *  - in-memory mock for integration tests
+ *
+ * Last-write-wins: subsequent calls overwrite the active adapter.
+ */
+export declare const registerSessionAdapter: (adapter: SessionAdapter) => void;
+/** Read the currently-active session adapter (defaults to Redis). */
+export declare const getSessionAdapter: () => SessionAdapter;

package/dist/sessionLayout.d.ts

@@ -0,0 +1 @@
+export type { BaseSessionLayout, SessionLocation, AuthProps } from '@luckystack/core';

package/dist/sessionSanitizer.d.ts

@@ -0,0 +1,19 @@
+import type { BaseSessionLayout } from './sessionLayout.js';
+export type SessionSanitizer = (session: BaseSessionLayout) => BaseSessionLayout;
+/**
+ * Register a redactor applied to the session record before it is persisted to
+ * the store and broadcast to connected clients. Call once at boot. Last write
+ * wins. Pass a function that returns a shallow copy with sensitive fields
+ * stripped, e.g. `({ totpSecret, stripeCustomerId, ...safe }) => safe`.
+ */
+export declare const registerSessionSanitizer: (sanitizer: SessionSanitizer) => void;
+/** Read the active sanitizer (or `null` when none is registered). */
+export declare const getSessionSanitizer: () => SessionSanitizer | null;
+/**
+ * Apply the registered sanitizer (no-op identity when none registered). Used by
+ * `saveSession`. Defensive: a throwing sanitizer must not break login, so the
+ * caller falls back to the un-sanitized record on error (logged by the caller).
+ */
+export declare const applySessionSanitizer: (session: BaseSessionLayout) => BaseSessionLayout;
+/** Test-only: clear the registered sanitizer between scenarios. */
+export declare const resetSessionSanitizerForTests: () => void;

package/dist/totp.d.ts

@@ -0,0 +1,38 @@
+export declare const base32Encode: (input: Buffer) => string;
+export declare const base32Decode: (input: string) => Buffer | null;
+export declare const hotp: (key: Buffer, counter: number, digits?: number) => string;
+export interface TotpVerifyInput {
+    /** base32-encoded shared secret (as provisioned to the authenticator app). */
+    secret: string;
+    /** The user-entered code (digits; surrounding whitespace tolerated). */
+    code: string;
+    /**
+     * Accepted clock drift in 30s steps on EITHER side of "now" (default 1 —
+     * i.e. the previous, current and next code are accepted; RFC 6238 §5.2
+     * recommends at most one backward step).
+     */
+    window?: number;
+    /** Injection point for tests; defaults to the real clock. */
+    timestampMs?: number;
+}
+export interface TotpVerifyResult {
+    valid: boolean;
+    /**
+     * The timestep the code matched (only when valid). Persist the highest
+     * accepted value per user and refuse `timestep <= lastAccepted` to make
+     * every code single-use (replay protection across the drift window).
+     */
+    timestep: number | null;
+}
+export declare const verifyTotp: ({ secret, code, window, timestampMs }: TotpVerifyInput) => TotpVerifyResult;
+/** 20 random bytes (RFC 4226 §4 minimum: 128 bits; 160 recommended), base32. */
+export declare const generateTotpSecret: () => string;
+export interface OtpauthUriInput {
+    /** base32 secret from generateTotpSecret(). */
+    secret: string;
+    /** What the authenticator app shows as the account (usually the user's email). */
+    accountName: string;
+    /** App/brand name shown above the account (defaults to the project title). */
+    issuer: string;
+}
+export declare const buildOtpauthUri: ({ secret, accountName, issuer }: OtpauthUriInput) => string;

package/dist/twoFactor.d.ts

@@ -0,0 +1,60 @@
+import { type UserRecord } from './userAdapter.js';
+import { type CredentialsLoginChallenge, type CredentialsLoginResult, type TwoFactorMethod } from './login.js';
+export declare const encryptTotpSecret: (secret: string) => string;
+export declare const decryptTotpSecret: (stored: string) => string | null;
+export declare const availableTwoFactorMethods: (user: UserRecord) => TwoFactorMethod[];
+export declare const createTwoFactorChallengeIfRequired: (user: UserRecord, _context: {
+    requesterIp?: string;
+}) => Promise<CredentialsLoginChallenge | null>;
+export interface VerifyTwoFactorInput {
+    challengeToken: string;
+    code: string;
+    /** Defaults to 'totp'; the client sends what the user picked. */
+    method?: TwoFactorMethod;
+    supersedeToken?: string;
+    requesterIp?: string;
+}
+export declare const verifyTwoFactorChallenge: (input: VerifyTwoFactorInput) => Promise<CredentialsLoginResult>;
+export declare const requestTwoFactorEmailCode: (challengeToken: string) => Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+export declare const sendCodeEmail: (to: string, code: string, subject: string, intro: string) => Promise<boolean>;
+export type TotpEnrollmentStart = {
+    ok: true;
+    secret: string;
+    otpauthUri: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Step 1: mint a secret and park it as PENDING (Redis, 10 min) — the user
+ * record is untouched until the user proves the app works via
+ * `confirmTotpEnrollment`. Re-calling replaces the pending secret. Refused for
+ * an already-enrolled user / a disabled feature (see enrollmentBlockedReason).
+ */
+export declare const beginTotpEnrollment: (user: UserRecord) => Promise<TotpEnrollmentStart>;
+export type ConfirmTotpEnrollmentResult = {
+    ok: true;
+    recoveryCodes: string[];
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Step 2: the user enters the first code from their app. On success the
+ * secret + recovery-code hashes land on the user record and 2FA is ON.
+ * The RAW recovery codes are returned exactly once — show + let them save.
+ */
+export declare const confirmTotpEnrollment: (user: UserRecord, code: string) => Promise<ConfirmTotpEnrollmentResult>;
+/**
+ * Disable 2FA. Requires a currently-valid TOTP code OR an unused recovery
+ * code, so a hijacked (but 2FA-less) session can't silently strip the factor.
+ */
+export declare const disableTwoFactor: (user: UserRecord, code: string) => Promise<{
+    ok: boolean;
+    reason?: string;
+}>;
+/** Replace the recovery-code set (requires a valid current TOTP code). */
+export declare const regenerateRecoveryCodes: (user: UserRecord, code: string) => Promise<ConfirmTotpEnrollmentResult>;