@luckystack/login 0.1.9 → 0.2.1

package/dist/index.d.ts

@@ -102,12 +102,34 @@ interface PreEmailChangePayload {
 interface PostEmailChangeRequestedPayload {
     userId: 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;
@@ -128,6 +150,9 @@ declare module '@luckystack/core' {
         preEmailChange: PreEmailChangePayload;
         postEmailChangeRequested: PostEmailChangeRequestedPayload;
         postEmailChanged: PostEmailChangedPayload;
+        loginFailed: LoginFailedPayload;
+        preAccountDelete: PreAccountDeletePayload;
+        postAccountDelete: PostAccountDeletePayload;
     }
 }
 
@@ -155,9 +180,15 @@ declare const saveSession: (token: string, data: BaseSessionLayout, newUser?: bo
  * 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) => Promise<BaseSessionLayout | null>;
+declare const getSession: (token: string | null, options?: {
+    refresh?: boolean;
+}) => Promise<BaseSessionLayout | null>;
 /**
  * Delete a user session through the active adapter and notify connected
  * clients.
@@ -221,10 +252,25 @@ interface SessionAdapter {
     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;
@@ -249,101 +295,74 @@ declare const registerSessionAdapter: (adapter: SessionAdapter) => void;
 /** Read the currently-active session adapter (defaults to Redis). */
 declare const getSessionAdapter: () => SessionAdapter;
 
-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;
-}
-interface UserAdapter {
-    findByEmail: (params: {
-        email: string;
-        provider: string;
-    }) => Promise<UserRecord | null>;
-    findById: (id: string) => Promise<UserRecord | null>;
-    create: (input: UserAdapterCreateInput) => Promise<UserRecord>;
-    update: (id: string, patch: Partial<UserRecord>) => Promise<UserRecord>;
-}
-declare const registerUserAdapter: (adapter: UserAdapter) => UserAdapter;
-declare const isUserAdapterRegistered: () => boolean;
-declare const defaultPrismaUserAdapter: () => UserAdapter;
-declare const getUserAdapter: () => UserAdapter;
+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 paramsType {
+interface LoginOrRegisterParams {
     email?: string;
     password?: string;
     name?: string;
     confirmPassword?: string;
 }
-declare const createOAuthState: (providerName: string) => Promise<string | null>;
+interface CredentialsLoginSuccess {
+    status: true;
+    reason: string;
+    newToken: string;
+    session: BaseSessionLayout;
+}
+interface CredentialsLoginFailure {
+    status: false;
+    reason: string;
+}
+type CredentialsLoginResult = CredentialsLoginSuccess | 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;
-}) => Promise<{
-    status: boolean;
-    reason: string;
-    session?: undefined;
-} | {
-    status: boolean;
-    reason: string;
-    session: Omit<UserRecord, "password">;
-}>;
+}, options?: {
+    supersedeToken?: string;
+}) => Promise<CredentialsLoginResult>;
 declare const loginWithCredentialsCore: ({ email, password }: {
     email: string;
     password: string;
 }, options?: {
     supersedeToken?: string;
-}) => Promise<{
-    status: boolean;
-    reason: string;
-    newToken?: undefined;
-    session?: undefined;
-} | {
-    status: boolean;
-    reason: Error;
-    newToken?: undefined;
-    session?: undefined;
-} | {
-    status: boolean;
-    reason: string;
-    newToken: string;
-    session: BaseSessionLayout;
-}>;
-declare const loginWithCredentials: (params: paramsType, options?: {
+    requesterIp?: string;
+}) => Promise<CredentialsLoginResult>;
+declare const loginWithCredentials: (params: LoginOrRegisterParams, options?: {
     supersedeToken?: string;
-}) => Promise<{
-    status: false;
-    reason: string;
-} | {
-    status: boolean;
-    reason: string;
-    session?: undefined;
-} | {
-    status: boolean;
-    reason: string;
-    session: Omit<UserRecord, "password">;
-} | {
-    status: boolean;
-    reason: Error;
-    newToken?: undefined;
-    session?: undefined;
-} | {
-    status: boolean;
-    reason: string;
-    newToken: string;
-    session: BaseSessionLayout;
-}>;
+    requesterIp?: string;
+}) => Promise<CredentialsLoginResult>;
 interface OAuthCallbackResult {
     token: string;
     redirectUrl: string;
@@ -364,15 +383,38 @@ declare const logout: ({ token, socket, userId, skipSessionDelete }: {
 }) => Promise<void>;
 
 /**
- * Create a one-time password-reset token bound to a user id. Stored in Redis
- * with the configured TTL. Returns the token string — caller emails it to
- * the user (typically embedded in a URL).
+ * 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). Returns null when the token
- * is missing, expired, or malformed.
+ * 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>;
 /**
@@ -382,6 +424,20 @@ declare const consumePasswordResetToken: (token: string) => Promise<string | nul
  * (`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>;
 /**
@@ -432,15 +488,19 @@ interface EmailChangePayload {
 }
 /**
  * Create a one-time email-change token bound to a user id + the new email
- * address. Stored in Redis with the configured TTL. Returns the token string
- * — caller emails the token (embedded in a URL) to the NEW address so the
+ * 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).
- * Returns null when the token is missing, expired, or malformed.
+ * `{ 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>;
 
@@ -469,6 +529,7 @@ declare const sendEmailChangeConfirmation: ({ userId, newEmail, userName, brand
 }>;
 
 type OAuthUserData = Record<string, unknown>;
+declare const asOAuthUserData: (value: unknown) => OAuthUserData;
 interface CredentialsProvider {
     name: 'credentials';
 }
@@ -495,6 +556,15 @@ interface FullOAuthProvider {
     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;
     avatarKey?: string;
     avatarCodeKey: string;
     getEmail?: (accessToken: string) => Promise<string | false | undefined>;
@@ -525,6 +595,25 @@ interface FullOAuthProvider {
         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;
@@ -554,6 +643,13 @@ interface OAuthHelperInput {
      * 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;
@@ -571,10 +667,81 @@ interface MicrosoftProviderInput extends OAuthHelperInput {
     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;
+
+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;
+}
+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 PostLoginRedirectInput {
     userId: string;
@@ -586,4 +753,4 @@ type PostLoginRedirectResolver = (input: PostLoginRedirectInput) => string | Pro
 declare const registerPostLoginRedirect: (resolver: PostLoginRedirectResolver) => PostLoginRedirectResolver;
 declare const getPostLoginRedirect: () => PostLoginRedirectResolver | null;
 
-export { type CredentialsProvider, type EmailChangePayload, type FullOAuthProvider, type OAuthProvider, PasswordPolicyError, type PostEmailChangeRequestedPayload, type PostEmailChangedPayload, type PostLoginPayload, type PostLoginRedirectInput, type PostLoginRedirectResolver, type PostLogoutPayload, type PostRegisterPayload, type PostSessionCreatePayload, type PostSessionDeletePayload, type PreEmailChangePayload, type PreLoginPayload, type PreLogoutPayload, type PreRegisterPayload, type PreSessionCreatePayload, type PreSessionDeletePayload, type SessionAdapter, type UserAdapter, type UserAdapterCreateInput, type UserRecord, activeUsersKeyFor, consumeEmailChangeToken, consumePasswordResetToken, createEmailChangeToken, createOAuthState, createPasswordResetToken, credentialsProvider, defaultPrismaUserAdapter, deleteSession, discordProvider, facebookProvider, getAllSessions, getOAuthProviders, getPostLoginRedirect, getSession, getSessionAdapter, getUserAdapter, githubProvider, googleProvider, isFullOAuthProvider, isUserAdapterRegistered, loginCallback, loginWithCredentials, loginWithCredentialsCore, logout, microsoftProvider, redisSessionAdapter, registerOAuthProviders, registerPostLoginRedirect, registerSessionAdapter, registerUserAdapter, registerWithCredentials, revokeUserSessions, saveSession, sendEmailChangeConfirmation, sendPasswordResetEmail, sessionKeyFor, updatePasswordHash, validatePassword, verifyPassword };
+export { type CreateOAuthStateResult, type CredentialsLoginFailure, type CredentialsLoginResult, type CredentialsLoginSuccess, type CredentialsProvider, type EmailChangePayload, type FullOAuthProvider, type LoginFailedPayload, OAUTH_STATE_COOKIE_NAME, type OAuthCallbackResult, type OAuthProvider, type OAuthUserData, PasswordPolicyError, 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 PreRegisterPayload, type PreSessionCreatePayload, type PreSessionDeletePayload, type SessionAdapter, type SessionSanitizer, type UserAdapter, type UserAdapterCreateInput, type UserRecord, activeUsersKeyFor, asOAuthUserData, clearAuthFailures, consumeEmailChangeToken, consumePasswordResetToken, createEmailChangeToken, createOAuthState, createPasswordResetToken, credentialsProvider, defaultPrismaUserAdapter, deleteSession, discordProvider, facebookProvider, getAllSessions, getOAuthProviders, getPostLoginRedirect, getSession, getSessionAdapter, getSessionSanitizer, getUserAdapter, githubProvider, googleProvider, isAccountLocked, isFullOAuthProvider, isUserAdapterRegistered, loginCallback, loginWithCredentials, loginWithCredentialsCore, logout, microsoftProvider, recordAuthFailure, redisSessionAdapter, registerOAuthProviderFactory, registerOAuthProviders, registerPostLoginRedirect, registerSessionAdapter, registerSessionSanitizer, registerUserAdapter, registerWithCredentials, revokeUserSessions, saveSession, sendEmailChangeConfirmation, sendPasswordResetEmail, sessionKeyFor, updatePasswordHash, validatePassword, verifyPassword };