@luckystack/login 0.5.1 → 0.6.1

package/dist/index.d.ts

@@ -305,23 +305,104 @@ 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; `gcm:`-prefixed when encrypted at
+     * rest via TOTP_ENCRYPTION_KEY). 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 | CredentialsLoginFailure;
+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. */
@@ -351,6 +432,16 @@ declare const registerWithCredentials: ({ email, password, name, confirmPassword
 }, 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;
@@ -698,58 +789,153 @@ declare const registerOAuthProviders: (providers: OAuthProvider[]) => OAuthProvi
  */
 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;
+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;
 }
-interface UserAdapter {
-    findByEmail: (params: {
-        email: string;
-        provider: string;
-    }) => Promise<UserRecord | null>;
+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;
     /**
-     * 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.
+     * 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).
      */
-    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>;
+    window?: number;
+    /** Injection point for tests; defaults to the real clock. */
+    timestampMs?: number;
+}
+interface TotpVerifyResult {
+    valid: boolean;
     /**
-     * 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.
+     * 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).
      */
-    delete?: (id: string) => Promise<void>;
+    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;
 }
-declare const registerUserAdapter: (adapter: UserAdapter) => UserAdapter;
-declare const isUserAdapterRegistered: () => boolean;
-declare const defaultPrismaUserAdapter: () => UserAdapter;
-declare const getUserAdapter: () => UserAdapter;
+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;
@@ -761,4 +947,4 @@ type PostLoginRedirectResolver = (input: PostLoginRedirectInput) => string | Pro
 declare const registerPostLoginRedirect: (resolver: PostLoginRedirectResolver) => PostLoginRedirectResolver;
 declare const getPostLoginRedirect: () => PostLoginRedirectResolver | null;
 
-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, 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 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 };
+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 };