@luckystack/login 0.10.1 → 0.11.0

package/dist/index.d.ts

@@ -1,951 +1,33 @@
-import { BaseSessionLayout } from '@luckystack/core';
-export { AuthProps, BaseSessionLayout, SessionLocation } from '@luckystack/core';
-import { IncomingMessage, ServerResponse } from 'node:http';
-import { Socket } from 'socket.io';
-
-/**
- * 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.
- */
-
-interface PreLoginPayload {
-    email: string;
-    provider: string;
-}
-interface PostLoginPayload {
-    userId: string;
-    provider: string;
-    isNewUser: boolean;
-    token: string;
-}
-interface PreRegisterPayload {
-    email: string;
-    provider: string;
-    name?: string;
-}
-interface PostRegisterPayload {
-    userId: string;
-    provider: string;
-}
-interface PreLogoutPayload {
-    userId: string | null;
-    token: string | null;
-}
-interface PostLogoutPayload {
-    userId: string | null;
-    token: string | null;
-}
-interface PreSessionCreatePayload {
-    token: string;
-    user: BaseSessionLayout;
-    persistent: boolean;
-}
-interface PostSessionCreatePayload {
-    token: string;
-    user: BaseSessionLayout;
-    persistent: boolean;
-}
-interface PreSessionDeletePayload {
-    token: string;
-    userId: string | null;
-}
-interface PostSessionDeletePayload {
-    token: string;
-    userId: string | null;
-}
-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;
-}
-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;
-}
-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;
-}
-interface PrePasswordResetCompletedPayload {
-    /** User whose password is about to be reset via the forgot-password flow. */
-    userId: string;
-}
-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;
-}
-interface PreEmailChangePayload {
-    userId: string;
-    currentEmail: string;
-    newEmail: string;
-}
-interface PostEmailChangeRequestedPayload {
-    userId: string;
-    currentEmail: string;
-    newEmail: string;
-    sent?: boolean;
-}
-interface PostEmailChangedPayload {
-    userId: string;
-    oldEmail: string;
-    newEmail: string;
-}
-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;
-}
-interface PreAccountDeletePayload {
-    userId: string;
-    email?: string;
-}
-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;
-    }
-}
-
-/**
- * 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: BaseSessionLayout, 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<BaseSessionLayout | 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<BaseSessionLayout[]>;
-/**
- * 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;
-
-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;
-    }[]>;
-}
-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.
- */
-declare const registerSessionAdapter: (adapter: SessionAdapter) => void;
-/** Read the currently-active session adapter (defaults to Redis). */
-declare const getSessionAdapter: () => SessionAdapter;
-
-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`.
- */
-declare const registerSessionSanitizer: (sanitizer: SessionSanitizer) => void;
-/** Read the active sanitizer (or `null` when none is registered). */
-declare const getSessionSanitizer: () => SessionSanitizer | null;
-
-interface UserAdapterCreateInput {
-    email: string;
-    provider: string;
-    name?: string | null;
-    password?: string | null;
-    avatar?: string | null;
-    avatarFallback?: string | null;
-    language?: string | null;
-}
-interface UserRecord extends BaseSessionLayout {
-    password?: string | null;
-    provider?: string | null;
-    /** Most recent successful login. Mirrors the optional `lastLogin` column on User. */
-    lastLogin?: Date | null;
-    /**
-     * 2FA (ADR 0024): whether this user enrolled a second factor. All three 2FA
-     * fields are OPTIONAL so pre-0.6 schemas/adapters keep working unchanged —
-     * an adapter that never returns them simply has no 2FA-capable users.
-     */
-    twoFactorEnabled?: boolean | null;
-    /**
-     * 2FA: the TOTP shared secret (base32; new encrypted rows use
-     * `enc:v2:<key-id>:...`, while legacy `gcm:` rows remain readable through
-     * TOTP_ENCRYPTION_LEGACY_KEYS). NEVER reaches the client — stripped by
-     * `sanitizeUserForSession` before any session persist/broadcast.
-     */
-    totpSecret?: string | null;
-    /** 2FA: sha256 hashes of the UNUSED one-time recovery codes (also stripped). */
-    recoveryCodes?: string[] | null;
-}
-interface UserAdapter {
-    findByEmail: (params: {
-        email: string;
-        provider: string;
-    }) => Promise<UserRecord | null>;
-    /**
-     * Look up a user by email IRRESPECTIVE of provider. Required only when
-     * `auth.providerAccountStrategy === 'unified'` — the framework resolves
-     * accounts by email alone so the same address maps to one User across
-     * providers. Optional so existing custom adapters keep compiling; when a
-     * project sets `'unified'` but its adapter omits this method, the framework
-     * logs a one-time warning and falls back to provider-scoped lookup.
-     */
-    findByEmailAnyProvider?: (params: {
-        email: string;
-    }) => Promise<UserRecord | null>;
-    findById: (id: string) => Promise<UserRecord | null>;
-    create: (input: UserAdapterCreateInput) => Promise<UserRecord>;
-    update: (id: string, patch: Partial<UserRecord>) => Promise<UserRecord>;
-    /**
-     * Hard-delete a user. Account-deletion flows (`deleteAccount_v1`) call this
-     * instead of reaching past the adapter to `prisma.user.delete`, so a custom
-     * adapter / non-Prisma store / soft-delete strategy stays in control. To
-     * implement a soft delete, ignore the hard delete here and instead expose it
-     * through `update({ deletedAt: new Date() })` from your route.
-     *
-     * Optional so existing custom adapters keep compiling; the default Prisma
-     * adapter implements it. Consumers calling account deletion against a custom
-     * adapter that omits `delete` get a clear "adapter does not support delete"
-     * failure rather than a silent Prisma bypass.
-     */
-    delete?: (id: string) => Promise<void>;
-}
-declare const registerUserAdapter: (adapter: UserAdapter) => UserAdapter;
-declare const isUserAdapterRegistered: () => boolean;
-declare const defaultPrismaUserAdapter: () => UserAdapter;
-declare const getUserAdapter: () => UserAdapter;
-
-interface LoginOrRegisterParams {
-    email?: string;
-    password?: string;
-    name?: string;
-    confirmPassword?: string;
-}
-type TwoFactorMethod = 'totp' | 'email-code' | 'recovery-code';
-interface CredentialsLoginSuccess {
-    status: true;
-    reason: string;
-    newToken: string;
-    session: BaseSessionLayout;
-    requiresTwoFactor?: undefined;
-}
-interface CredentialsLoginChallenge {
-    status: true;
-    reason: string;
-    requiresTwoFactor: true;
-    challengeToken: string;
-    twoFactorMethods: TwoFactorMethod[];
-    newToken?: undefined;
-    session?: undefined;
-}
-interface CredentialsLoginFailure {
-    status: false;
-    reason: string;
-    newToken?: undefined;
-    session?: undefined;
-    requiresTwoFactor?: undefined;
-}
-type CredentialsLoginResult = CredentialsLoginSuccess | CredentialsLoginChallenge | CredentialsLoginFailure;
-declare const OAUTH_STATE_COOKIE_NAME = "ls-oauth-state";
-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;
-}
-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>;
-type TwoFactorGate = (user: UserRecord, context: {
-    requesterIp?: string;
-}) => Promise<CredentialsLoginChallenge | null>;
-declare const registerTwoFactorGate: (gate: TwoFactorGate) => void;
-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>;
-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>;
-
-declare const logout: ({ token, socket, userId, skipSessionDelete }: {
-    token: string | null;
-    socket: Socket | undefined;
-    userId: string | null;
-    skipSessionDelete?: boolean;
-}) => Promise<void>;
-
-/**
- * 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).
- */
-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).
- */
-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).
- */
-declare const clearAuthFailures: (accountKey: string, requesterIp?: string) => Promise<void>;
-
-/**
- * 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).
- */
-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.
- */
-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.
- */
-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`).
- */
-declare class PasswordPolicyError extends Error {
-    readonly errorCode: string;
-    constructor(errorCode: string);
-}
-/** Verify a plaintext password against a stored bcrypt hash. */
-declare const verifyPassword: (plaintext: string, hash: string) => Promise<boolean>;
-
-/**
- * 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`.
- */
-declare const validatePassword: (password: string) => string | null;
-
-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.
- */
-declare const sendPasswordResetEmail: ({ email, brand }: SendResetEmailArgs) => Promise<{
-    ok: boolean;
-    reason?: string;
-}>;
-
-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.
- */
-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.
- */
-declare const consumeEmailChangeToken: (token: string) => Promise<EmailChangePayload | null>;
-
-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).
- */
-declare const sendEmailChangeConfirmation: ({ userId, newEmail, userName, brand }: SendEmailChangeArgs) => Promise<{
-    ok: boolean;
-    reason?: string;
-    token: string;
-}>;
-
-type OAuthUserData = Record<string, unknown>;
-declare const asOAuthUserData: (value: unknown) => OAuthUserData;
-interface CredentialsProvider {
-    name: 'credentials';
-}
-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;
-}
-type OAuthProvider = CredentialsProvider | FullOAuthProvider;
-declare const isFullOAuthProvider: (provider: OAuthProvider) => provider is FullOAuthProvider;
-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;
-}
-declare const credentialsProvider: () => CredentialsProvider;
-declare const googleProvider: (input: OAuthHelperInput) => FullOAuthProvider;
-declare const githubProvider: (input: OAuthHelperInput) => FullOAuthProvider;
-declare const discordProvider: (input: OAuthHelperInput) => FullOAuthProvider;
-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;
-}
-declare const facebookProvider: (input: FacebookProviderInput) => FullOAuthProvider;
-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;
-}
-declare const microsoftProvider: (input: MicrosoftProviderInput) => FullOAuthProvider;
-declare const getOAuthProviders: () => OAuthProvider[];
-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.
- */
-declare const registerOAuthProviderFactory: (factory: () => OAuthProvider[]) => void;
-
-declare const availableTwoFactorMethods: (user: UserRecord) => TwoFactorMethod[];
-declare const createTwoFactorChallengeIfRequired: (user: UserRecord, _context: {
-    requesterIp?: string;
-}) => Promise<CredentialsLoginChallenge | null>;
-interface VerifyTwoFactorInput {
-    challengeToken: string;
-    code: string;
-    /** Defaults to 'totp'; the client sends what the user picked. */
-    method?: TwoFactorMethod;
-    supersedeToken?: string;
-    requesterIp?: string;
-}
-declare const verifyTwoFactorChallenge: (input: VerifyTwoFactorInput) => Promise<CredentialsLoginResult>;
-declare const requestTwoFactorEmailCode: (challengeToken: string) => Promise<{
-    ok: boolean;
-    reason?: string;
-}>;
-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).
- */
-declare const beginTotpEnrollment: (user: UserRecord) => Promise<TotpEnrollmentStart>;
-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.
- */
-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.
- */
-declare const disableTwoFactor: (user: UserRecord, code: string) => Promise<{
-    ok: boolean;
-    reason?: string;
-}>;
-/** Replace the recovery-code set (requires a valid current TOTP code). */
-declare const regenerateRecoveryCodes: (user: UserRecord, code: string) => Promise<ConfirmTotpEnrollmentResult>;
-
-declare const base32Encode: (input: Buffer) => string;
-declare const base32Decode: (input: string) => Buffer | null;
-declare const hotp: (key: Buffer, counter: number, digits?: number) => string;
-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;
-}
-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;
-}
-declare const verifyTotp: ({ secret, code, window, timestampMs }: TotpVerifyInput) => TotpVerifyResult;
-/** 20 random bytes (RFC 4226 §4 minimum: 128 bits; 160 recommended), base32. */
-declare const generateTotpSecret: () => string;
-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;
-}
-declare const buildOtpauthUri: ({ secret, accountName, issuer }: OtpauthUriInput) => string;
-
-interface RequestEmailLoginCodeInput {
-    email: string;
-    requesterIp?: string;
-}
-type RequestEmailLoginCodeResult = {
-    ok: true;
-} | {
-    ok: false;
-    reason: string;
-};
-declare const requestEmailLoginCode: ({ email, requesterIp }: RequestEmailLoginCodeInput) => Promise<RequestEmailLoginCodeResult>;
-interface VerifyEmailLoginCodeInput {
-    email: string;
-    code: string;
-    supersedeToken?: string;
-    requesterIp?: string;
-}
-declare const verifyEmailLoginCode: (input: VerifyEmailLoginCodeInput) => Promise<CredentialsLoginResult>;
-
-type EmailOtpPurpose = 'login' | '2fa';
-declare const generateNumericCode: (digits: number) => string;
-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).
- */
-declare const issueEmailCode: ({ purpose, identity, ttlSeconds, digits }: IssueEmailCodeInput) => Promise<string>;
-type EmailCodeVerdict = 'valid' | 'invalid' | 'expired' | 'locked';
-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).
- */
-declare const verifyEmailCode: ({ purpose, identity, code, maxAttempts }: VerifyEmailCodeInput) => Promise<EmailCodeVerdict>;
-/** Drop any active code + counter for the slot (e.g. after a completed login). */
-declare const clearEmailCode: (purpose: EmailOtpPurpose, identity: string) => Promise<void>;
-
-interface PostLoginRedirectInput {
-    userId: string;
-    provider: string;
-    isNewUser: boolean;
-    defaultUrl: string;
-}
-type PostLoginRedirectResolver = (input: PostLoginRedirectInput) => string | Promise<string>;
-declare const registerPostLoginRedirect: (resolver: PostLoginRedirectResolver) => PostLoginRedirectResolver;
-declare const getPostLoginRedirect: () => PostLoginRedirectResolver | null;
-
-export { type ConfirmTotpEnrollmentResult, type CreateOAuthStateResult, type CredentialsLoginChallenge, type CredentialsLoginFailure, type CredentialsLoginResult, type CredentialsLoginSuccess, type CredentialsProvider, type EmailChangePayload, type EmailCodeVerdict, type EmailOtpPurpose, type FullOAuthProvider, type LoginFailedPayload, OAUTH_STATE_COOKIE_NAME, type OAuthCallbackResult, type OAuthProvider, type OAuthUserData, type PasswordChangedPayload, PasswordPolicyError, type PasswordResetCompletedPayload, type PasswordResetRequestedPayload, type PostAccountDeletePayload, type PostEmailChangeRequestedPayload, type PostEmailChangedPayload, type PostLoginPayload, type PostLoginRedirectInput, type PostLoginRedirectResolver, type PostLogoutPayload, type PostRegisterPayload, type PostSessionCreatePayload, type PostSessionDeletePayload, type PreAccountDeletePayload, type PreEmailChangePayload, type PreLoginPayload, type PreLogoutPayload, type PrePasswordChangedPayload, type PrePasswordResetCompletedPayload, type PreRegisterPayload, type PreSessionCreatePayload, type PreSessionDeletePayload, type RequestEmailLoginCodeInput, type RequestEmailLoginCodeResult, type SessionAdapter, type SessionSanitizer, type TotpEnrollmentStart, type TwoFactorGate, type TwoFactorMethod, type UserAdapter, type UserAdapterCreateInput, type UserRecord, type VerifyEmailLoginCodeInput, type VerifyTwoFactorInput, activeUsersKeyFor, asOAuthUserData, availableTwoFactorMethods, base32Decode, base32Encode, beginTotpEnrollment, buildOtpauthUri, clearAuthFailures, clearEmailCode, confirmTotpEnrollment, consumeEmailChangeToken, consumePasswordResetToken, createEmailChangeToken, createOAuthState, createPasswordResetToken, createTwoFactorChallengeIfRequired, credentialsProvider, defaultPrismaUserAdapter, deleteSession, disableTwoFactor, discordProvider, facebookProvider, finalizeLogin, generateNumericCode, generateTotpSecret, getAllSessions, getOAuthProviders, getPostLoginRedirect, getSession, getSessionAdapter, getSessionSanitizer, getUserAdapter, githubProvider, googleProvider, hotp, isAccountLocked, isFullOAuthProvider, isUserAdapterRegistered, issueEmailCode, loginCallback, loginWithCredentials, loginWithCredentialsCore, logout, microsoftProvider, recordAuthFailure, redisSessionAdapter, regenerateRecoveryCodes, registerOAuthProviderFactory, registerOAuthProviders, registerPostLoginRedirect, registerSessionAdapter, registerSessionSanitizer, registerTwoFactorGate, registerUserAdapter, registerWithCredentials, requestEmailLoginCode, requestTwoFactorEmailCode, revokeUserSessions, saveSession, sendEmailChangeConfirmation, sendPasswordResetEmail, sessionKeyFor, updatePasswordHash, validatePassword, verifyEmailCode, verifyEmailLoginCode, verifyPassword, verifyTotp, verifyTwoFactorChallenge };
+import './hookPayloads.js';
+export type { BaseSessionLayout, SessionLocation, AuthProps } from './sessionLayout.js';
+export type { PreLoginPayload, PostLoginPayload, PreRegisterPayload, PostRegisterPayload, PreLogoutPayload, PostLogoutPayload, PreSessionCreatePayload, PostSessionCreatePayload, PreSessionDeletePayload, PostSessionDeletePayload, PasswordResetRequestedPayload, PrePasswordResetCompletedPayload, PasswordResetCompletedPayload, PrePasswordChangedPayload, PasswordChangedPayload, PreEmailChangePayload, PostEmailChangeRequestedPayload, PostEmailChangedPayload, LoginFailedPayload, PreAccountDeletePayload, PostAccountDeletePayload, } from './hookPayloads.js';
+export { saveSession, getSession, deleteSession, getAllSessions, revokeUserSessions, sessionKeyFor, activeUsersKeyFor } from './session.js';
+export { registerSessionAdapter, getSessionAdapter, redisSessionAdapter } from './sessionAdapter.js';
+export type { SessionAdapter } from './sessionAdapter.js';
+export { registerSessionSanitizer, getSessionSanitizer } from './sessionSanitizer.js';
+export type { SessionSanitizer } from './sessionSanitizer.js';
+export { loginWithCredentials, loginCallback, createOAuthState, registerWithCredentials, loginWithCredentialsCore, finalizeLogin, registerTwoFactorGate } from './login.js';
+export type { CredentialsLoginResult, CredentialsLoginSuccess, CredentialsLoginChallenge, CredentialsLoginFailure, TwoFactorMethod, TwoFactorGate, OAuthCallbackResult, } from './login.js';
+export type { CreateOAuthStateResult } from './login.js';
+export { OAUTH_STATE_COOKIE_NAME } from './login.js';
+export { logout } from './logout.js';
+export { isAccountLocked, recordAuthFailure, clearAuthFailures } from './authLockout.js';
+export { createPasswordResetToken, consumePasswordResetToken, updatePasswordHash, verifyPassword, PasswordPolicyError, } from './passwordReset.js';
+export { validatePassword } from './passwordPolicy.js';
+export { sendPasswordResetEmail } from './forgotPassword.js';
+export { createEmailChangeToken, consumeEmailChangeToken, } from './emailChange.js';
+export type { EmailChangePayload } from './emailChange.js';
+export { sendEmailChangeConfirmation } from './emailChangeNotification.js';
+export { registerOAuthProviders, registerOAuthProviderFactory, getOAuthProviders, isFullOAuthProvider, asOAuthUserData, credentialsProvider, googleProvider, githubProvider, discordProvider, facebookProvider, microsoftProvider, } from './oauthProviders.js';
+export type { OAuthProvider, CredentialsProvider, FullOAuthProvider, OAuthUserData, } from './oauthProviders.js';
+export { registerUserAdapter, getUserAdapter, isUserAdapterRegistered, defaultPrismaUserAdapter, } from './userAdapter.js';
+export type { UserAdapter, UserAdapterCreateInput, UserRecord, } from './userAdapter.js';
+export { beginTotpEnrollment, confirmTotpEnrollment, disableTwoFactor, regenerateRecoveryCodes, verifyTwoFactorChallenge, requestTwoFactorEmailCode, availableTwoFactorMethods, createTwoFactorChallengeIfRequired, } from './twoFactor.js';
+export type { TotpEnrollmentStart, ConfirmTotpEnrollmentResult, VerifyTwoFactorInput } from './twoFactor.js';
+export { verifyTotp, generateTotpSecret, buildOtpauthUri, hotp, base32Encode, base32Decode } from './totp.js';
+export { requestEmailLoginCode, verifyEmailLoginCode } from './emailCodeLogin.js';
+export type { RequestEmailLoginCodeInput, RequestEmailLoginCodeResult, VerifyEmailLoginCodeInput } from './emailCodeLogin.js';
+export { issueEmailCode, verifyEmailCode, clearEmailCode, generateNumericCode } from './emailOtp.js';
+export type { EmailOtpPurpose, EmailCodeVerdict } from './emailOtp.js';
+export { registerPostLoginRedirect, getPostLoginRedirect, } from './redirectResolver.js';
+export type { PostLoginRedirectResolver, PostLoginRedirectInput, } from './redirectResolver.js';