@cairs-npm/express-auth-2fa 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,577 @@
+import * as mongodb from 'mongodb';
+import { ObjectId, Db, MongoClient } from 'mongodb';
+import { MethodType, ErrorCode, LoginResponse, Method } from '@cairs-npm/auth-2fa-contract';
+export { ApiError, Method, Session, Tokens, User } from '@cairs-npm/auth-2fa-contract';
+import { Request, Response, NextFunction, Router } from 'express';
+import { z } from 'zod';
+
+interface CredentialDoc {
+    _id?: ObjectId;
+    userId: string;
+    passwordHash: string;
+    twoStepEnabled: boolean;
+    failedLogins: {
+        count: number;
+        windowStart: Date;
+    };
+    lockedUntil: Date | null;
+    updatedAt: Date;
+}
+type MethodStatus = "pending" | "active";
+interface MethodDoc {
+    _id?: ObjectId;
+    userId: string;
+    type: MethodType;
+    label: string;
+    isDefault: boolean;
+    status: MethodStatus;
+    /** AES-256-GCM ciphertext (TOTP secret). */
+    secretEnc?: string;
+    /** AES-256-GCM ciphertext (E.164 phone). */
+    phoneE164Enc?: string;
+    /** Last 4 digits for masking. */
+    phoneLast4?: string;
+    /** TOTP replay guard: last accepted time-step. */
+    lastUsedStep?: number;
+    /** SMS confirm-code hash while pending. */
+    pendingCodeHash?: string;
+    /** Expiry for pending methods (TTL). */
+    pendingExpiresAt?: Date;
+    /** Passkey: WebAuthn credential id (base64url). */
+    credentialId?: string;
+    /** Passkey: COSE public key (base64url). */
+    publicKey?: string;
+    /** Passkey: signature counter (clone detection). */
+    counter?: number;
+    /** Passkey: authenticator transports hint (usb, nfc, ble, internal, hybrid). */
+    transports?: string[];
+    createdAt: Date;
+    lastUsedAt: Date | null;
+}
+type ChallengePurpose = "login" | "step_up" | "enroll";
+interface ChallengeDoc {
+    _id: string;
+    userId: string;
+    purpose: ChallengePurpose;
+    methodId: string | null;
+    smsCodeHash: string | null;
+    smsSentAt: Date | null;
+    smsSendCount: number;
+    attempts: number;
+    /** WebAuthn challenge issued for this login / passkey enrollment (base64url). */
+    webauthnChallenge?: string | null;
+    expiresAt: Date;
+    createdAt: Date;
+}
+interface SessionDoc {
+    _id: string;
+    userId: string;
+    refreshTokenHash: string;
+    /** Token family for reuse detection (BR-11). */
+    familyId: string;
+    /** sid of the session this one rotated from. */
+    rotatedFrom: string | null;
+    /** Previous refresh-token hashes; reuse of any revokes the family (BR-11). */
+    usedHashes?: string[];
+    userAgent?: string;
+    ip?: string;
+    createdAt: Date;
+    expiresAt: Date;
+    revokedAt: Date | null;
+}
+interface TrustedDeviceDoc {
+    _id?: ObjectId;
+    userId: string;
+    tokenHash: string;
+    label: string;
+    createdAt: Date;
+    expiresAt: Date;
+}
+interface EventDoc {
+    _id?: ObjectId;
+    userId: string;
+    type: string;
+    ip?: string;
+    userAgent?: string;
+    at: Date;
+    meta?: Record<string, unknown>;
+}
+interface RateLimitDoc {
+    _id: string;
+    count: number;
+    expiresAt: Date;
+}
+
+interface AuthCollections {
+    credentials: mongodb.Collection<CredentialDoc>;
+    methods: mongodb.Collection<MethodDoc>;
+    challenges: mongodb.Collection<ChallengeDoc>;
+    sessions: mongodb.Collection<SessionDoc>;
+    trustedDevices: mongodb.Collection<TrustedDeviceDoc>;
+    events: mongodb.Collection<EventDoc>;
+    rateLimits: mongodb.Collection<RateLimitDoc>;
+}
+declare function getCollections(db: Db, prefix?: string): AuthCollections;
+
+/** App-owned user record shape returned by userAdapter. */
+interface AdapterUser {
+    id: string;
+    username?: string;
+    email?: string;
+    [key: string]: unknown;
+}
+interface UserAdapter {
+    findByLogin: (login: string) => Promise<AdapterUser | null>;
+    findById: (id: string) => Promise<AdapterUser | null>;
+}
+interface SmsProvider {
+    send: (phoneE164: string, message: string) => Promise<void>;
+}
+interface EmailProvider {
+    /** `message` is a ready-made plain-text body; `code` lets apps render their own template. */
+    send: (input: {
+        to: string;
+        code: string;
+        message: string;
+    }) => Promise<void>;
+}
+interface SecurityEvent {
+    userId: string;
+    type: string;
+    ip?: string;
+    userAgent?: string;
+    at: Date;
+    meta?: Record<string, unknown>;
+}
+interface Hooks {
+    onSecurityEvent?: (event: SecurityEvent) => void | Promise<void>;
+}
+type Clock = () => Date;
+interface Logger {
+    info: (obj: object, msg?: string) => void;
+    warn: (obj: object, msg?: string) => void;
+    error: (obj: object, msg?: string) => void;
+}
+declare const configSchema: z.ZodObject<{
+    db: z.ZodType<Db, z.ZodTypeDef, Db>;
+    issuer: z.ZodString;
+    /** PEM PKCS8 private key (Ed25519 or RSA). Required, min 32 bytes. */
+    jwtPrivateKey: z.ZodString;
+    /** 32-byte AES key, raw string or base64. Required. */
+    encryptionKey: z.ZodString;
+    keyId: z.ZodDefault<z.ZodString>;
+    userAdapter: z.ZodType<UserAdapter, z.ZodTypeDef, UserAdapter>;
+    smsProvider: z.ZodType<SmsProvider, z.ZodTypeDef, SmsProvider>;
+    /** Enables the always-present EMAIL method (default for new users). */
+    emailProvider: z.ZodOptional<z.ZodType<EmailProvider, z.ZodTypeDef, EmailProvider>>;
+    /** MongoClient for transactions; defaults to the client behind `db`. */
+    client: z.ZodOptional<z.ZodType<MongoClient, z.ZodTypeDef, MongoClient>>;
+    logger: z.ZodOptional<z.ZodType<Logger, z.ZodTypeDef, Logger>>;
+    hooks: z.ZodOptional<z.ZodType<Hooks, z.ZodTypeDef, Hooks>>;
+    clock: z.ZodOptional<z.ZodType<Clock, z.ZodTypeDef, Clock>>;
+    collectionPrefix: z.ZodDefault<z.ZodString>;
+    /**
+     * Passkeys (WebAuthn) as a second step. `rpID` is the site's domain (e.g. "childmatch.com",
+     * "localhost"); `origins` are the exact browser origins allowed (e.g. "https://app.childmatch.com").
+     * Omit to turn passkeys off.
+     */
+    passkeys: z.ZodOptional<z.ZodObject<{
+        rpID: z.ZodString;
+        rpName: z.ZodString;
+        origins: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        rpID: string;
+        rpName: string;
+        origins: string[];
+    }, {
+        rpID: string;
+        rpName: string;
+        origins: string[];
+    }>>;
+    /** 2-Step Verification state for users who have not chosen one yet. */
+    twoStepDefault: z.ZodDefault<z.ZodBoolean>;
+    limits: z.ZodDefault<z.ZodObject<{
+        /** Failed passwords before lockout (BR-2). */
+        loginMaxAttempts: z.ZodDefault<z.ZodNumber>;
+        /** Window for failed-login counting, minutes (BR-2). */
+        loginWindowMin: z.ZodDefault<z.ZodNumber>;
+        /** Lockout duration, minutes (BR-2, BR-9). */
+        lockMinutes: z.ZodDefault<z.ZodNumber>;
+        /** Min seconds between SMS sends on one challenge (BR-6). */
+        smsResendSec: z.ZodDefault<z.ZodNumber>;
+        /** Max SMS sends per challenge (BR-6). */
+        smsMaxPerChallenge: z.ZodDefault<z.ZodNumber>;
+        /** Max SMS sends per user per hour (BR-6). */
+        smsMaxPerUserHour: z.ZodDefault<z.ZodNumber>;
+        /** Wrong codes per challenge before lockout (BR-9). */
+        mfaMaxAttempts: z.ZodDefault<z.ZodNumber>;
+        /** Max verification methods per user (BR-16). */
+        maxMethods: z.ZodDefault<z.ZodNumber>;
+        /** Per-IP login requests per minute (NFR-B4). */
+        loginIpPerMin: z.ZodDefault<z.ZodNumber>;
+        /** Per-IP MFA verify requests per minute (NFR-B4). */
+        verifyIpPerMin: z.ZodDefault<z.ZodNumber>;
+        /** Per-IP step-up requests per minute (NFR-B4). */
+        stepUpIpPerMin: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        loginMaxAttempts: number;
+        loginWindowMin: number;
+        lockMinutes: number;
+        smsResendSec: number;
+        smsMaxPerChallenge: number;
+        smsMaxPerUserHour: number;
+        mfaMaxAttempts: number;
+        maxMethods: number;
+        loginIpPerMin: number;
+        verifyIpPerMin: number;
+        stepUpIpPerMin: number;
+    }, {
+        loginMaxAttempts?: number | undefined;
+        loginWindowMin?: number | undefined;
+        lockMinutes?: number | undefined;
+        smsResendSec?: number | undefined;
+        smsMaxPerChallenge?: number | undefined;
+        smsMaxPerUserHour?: number | undefined;
+        mfaMaxAttempts?: number | undefined;
+        maxMethods?: number | undefined;
+        loginIpPerMin?: number | undefined;
+        verifyIpPerMin?: number | undefined;
+        stepUpIpPerMin?: number | undefined;
+    }>>;
+    /**
+     * Set false to turn off every RATE_LIMITED check: the per-IP limits on login / code
+     * verify / send / step-up and the code-send cooldown and caps. Account lockouts after
+     * failed passwords or codes (LOCKED) still apply.
+     */
+    rateLimits: z.ZodDefault<z.ZodBoolean>;
+    argon2: z.ZodDefault<z.ZodObject<{
+        memoryKiB: z.ZodDefault<z.ZodNumber>;
+        iterations: z.ZodDefault<z.ZodNumber>;
+        parallelism: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        memoryKiB: number;
+        iterations: number;
+        parallelism: number;
+    }, {
+        memoryKiB?: number | undefined;
+        iterations?: number | undefined;
+        parallelism?: number | undefined;
+    }>>;
+    cookies: z.ZodDefault<z.ZodObject<{
+        secure: z.ZodDefault<z.ZodBoolean>;
+        domain: z.ZodOptional<z.ZodString>;
+        sameSite: z.ZodDefault<z.ZodEnum<["lax", "strict", "none"]>>;
+        path: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        secure: boolean;
+        sameSite: "lax" | "strict" | "none";
+        domain?: string | undefined;
+    }, {
+        path?: string | undefined;
+        secure?: boolean | undefined;
+        domain?: string | undefined;
+        sameSite?: "lax" | "strict" | "none" | undefined;
+    }>>;
+    ttl: z.ZodDefault<z.ZodObject<{
+        accessTokenSec: z.ZodDefault<z.ZodNumber>;
+        refreshTokenDays: z.ZodDefault<z.ZodNumber>;
+        trustedDeviceDays: z.ZodDefault<z.ZodNumber>;
+        challengeSec: z.ZodDefault<z.ZodNumber>;
+        stepUpSec: z.ZodDefault<z.ZodNumber>;
+        pendingMethodMin: z.ZodDefault<z.ZodNumber>;
+        auditDays: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        accessTokenSec: number;
+        refreshTokenDays: number;
+        trustedDeviceDays: number;
+        challengeSec: number;
+        stepUpSec: number;
+        pendingMethodMin: number;
+        auditDays: number;
+    }, {
+        accessTokenSec?: number | undefined;
+        refreshTokenDays?: number | undefined;
+        trustedDeviceDays?: number | undefined;
+        challengeSec?: number | undefined;
+        stepUpSec?: number | undefined;
+        pendingMethodMin?: number | undefined;
+        auditDays?: number | undefined;
+    }>>;
+    /** Serve GET /auth/openapi.json (A.7 docs). */
+    exposeDocs: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    db: Db;
+    issuer: string;
+    jwtPrivateKey: string;
+    encryptionKey: string;
+    keyId: string;
+    userAdapter: UserAdapter;
+    smsProvider: SmsProvider;
+    collectionPrefix: string;
+    twoStepDefault: boolean;
+    limits: {
+        loginMaxAttempts: number;
+        loginWindowMin: number;
+        lockMinutes: number;
+        smsResendSec: number;
+        smsMaxPerChallenge: number;
+        smsMaxPerUserHour: number;
+        mfaMaxAttempts: number;
+        maxMethods: number;
+        loginIpPerMin: number;
+        verifyIpPerMin: number;
+        stepUpIpPerMin: number;
+    };
+    rateLimits: boolean;
+    argon2: {
+        memoryKiB: number;
+        iterations: number;
+        parallelism: number;
+    };
+    cookies: {
+        path: string;
+        secure: boolean;
+        sameSite: "lax" | "strict" | "none";
+        domain?: string | undefined;
+    };
+    ttl: {
+        accessTokenSec: number;
+        refreshTokenDays: number;
+        trustedDeviceDays: number;
+        challengeSec: number;
+        stepUpSec: number;
+        pendingMethodMin: number;
+        auditDays: number;
+    };
+    exposeDocs: boolean;
+    emailProvider?: EmailProvider | undefined;
+    client?: MongoClient | undefined;
+    logger?: Logger | undefined;
+    hooks?: Hooks | undefined;
+    clock?: Clock | undefined;
+    passkeys?: {
+        rpID: string;
+        rpName: string;
+        origins: string[];
+    } | undefined;
+}, {
+    db: Db;
+    issuer: string;
+    jwtPrivateKey: string;
+    encryptionKey: string;
+    userAdapter: UserAdapter;
+    smsProvider: SmsProvider;
+    keyId?: string | undefined;
+    emailProvider?: EmailProvider | undefined;
+    client?: MongoClient | undefined;
+    logger?: Logger | undefined;
+    hooks?: Hooks | undefined;
+    clock?: Clock | undefined;
+    collectionPrefix?: string | undefined;
+    passkeys?: {
+        rpID: string;
+        rpName: string;
+        origins: string[];
+    } | undefined;
+    twoStepDefault?: boolean | undefined;
+    limits?: {
+        loginMaxAttempts?: number | undefined;
+        loginWindowMin?: number | undefined;
+        lockMinutes?: number | undefined;
+        smsResendSec?: number | undefined;
+        smsMaxPerChallenge?: number | undefined;
+        smsMaxPerUserHour?: number | undefined;
+        mfaMaxAttempts?: number | undefined;
+        maxMethods?: number | undefined;
+        loginIpPerMin?: number | undefined;
+        verifyIpPerMin?: number | undefined;
+        stepUpIpPerMin?: number | undefined;
+    } | undefined;
+    rateLimits?: boolean | undefined;
+    argon2?: {
+        memoryKiB?: number | undefined;
+        iterations?: number | undefined;
+        parallelism?: number | undefined;
+    } | undefined;
+    cookies?: {
+        path?: string | undefined;
+        secure?: boolean | undefined;
+        domain?: string | undefined;
+        sameSite?: "lax" | "strict" | "none" | undefined;
+    } | undefined;
+    ttl?: {
+        accessTokenSec?: number | undefined;
+        refreshTokenDays?: number | undefined;
+        trustedDeviceDays?: number | undefined;
+        challengeSec?: number | undefined;
+        stepUpSec?: number | undefined;
+        pendingMethodMin?: number | undefined;
+        auditDays?: number | undefined;
+    } | undefined;
+    exposeDocs?: boolean | undefined;
+}>;
+type AuthConfigInput = z.input<typeof configSchema>;
+type AuthConfig = z.output<typeof configSchema> & {
+    clock: Clock;
+};
+
+/** Dev/test provider — logs the message instead of sending a real SMS. */
+declare function consoleSms(logger?: Logger): SmsProvider;
+
+interface TwilioSmsOptions {
+    /** Account SID (AC…). */
+    sid: string;
+    /** Auth token for the account. */
+    token: string;
+    /** Sender number in E.164 (or a Messaging Service SID, MG…). */
+    from: string;
+    /** Twilio REST base URL; defaults to https://api.twilio.com/2010-04-01. */
+    baseUrl?: string;
+    /** Optional pre-built client (for tests / custom transports). */
+    client?: {
+        messages: {
+            create: (args: {
+                to: string;
+                from: string;
+                body: string;
+            }) => Promise<unknown>;
+        };
+    };
+}
+/**
+ * Twilio SMS provider over Twilio's REST API (Messages resource), so apps need no
+ * extra dependency — pass the account settings they already have.
+ */
+declare function twilioSms(opts: TwilioSmsOptions): SmsProvider;
+
+/** Dev/test provider — logs the message instead of sending a real email. */
+declare function consoleEmail(logger?: Logger): EmailProvider;
+
+declare class ApiErrorException extends Error {
+    readonly status: number;
+    readonly code: ErrorCode;
+    readonly extra?: {
+        attemptsLeft?: number;
+        retryAt?: string;
+    } | undefined;
+    constructor(status: number, code: ErrorCode, message: string, extra?: {
+        attemptsLeft?: number;
+        retryAt?: string;
+    } | undefined);
+}
+declare function apiError(status: number, code: ErrorCode, message: string, extra?: {
+    attemptsLeft?: number;
+    retryAt?: Date | string;
+}): ApiErrorException;
+declare function errorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction): void;
+
+interface TokenBundle {
+    accessToken: string;
+    expiresInSec: number;
+    refreshToken: string;
+    sessionId: string;
+}
+declare class TokenService {
+    private readonly config;
+    private readonly cols;
+    private alg;
+    private privateKeyPromise;
+    private publicKeyPromise;
+    constructor(config: AuthConfig, cols: AuthCollections);
+    signAccessToken(userId: string, sid: string, amr: string[]): Promise<string>;
+    verifyAccessToken(token: string): Promise<{
+        sub: string;
+        sid: string;
+        amr: string[];
+    }>;
+    /** Create a new session + refresh token; returns tokens for the client. */
+    issueTokens(userId: string, amr: string[], meta: {
+        userAgent?: string;
+        ip?: string;
+    }, familyId?: string): Promise<TokenBundle>;
+    /**
+     * Rotate a refresh token (BR-11). Reuse of a rotated token revokes the whole
+     * family. Old hashes are retained in `usedHashes` so reuse is detectable.
+     */
+    rotateRefreshToken(rawToken: string, meta: {
+        userAgent?: string;
+        ip?: string;
+    }): Promise<TokenBundle>;
+    revokeSession(sid: string): Promise<void>;
+    /** 5-minute step-up JWT bound to sub+sid (BR-13). */
+    signStepUpToken(userId: string, sid: string): Promise<{
+        token: string;
+        expiresInSec: number;
+    }>;
+    verifyStepUpToken(token: string, userId: string, sid: string): Promise<void>;
+}
+
+declare class AuditService {
+    private readonly config;
+    private readonly cols;
+    constructor(config: AuthConfig, cols: AuthCollections);
+    record(userId: string, type: string, meta?: {
+        ip?: string;
+        userAgent?: string;
+        meta?: Record<string, unknown>;
+    }): Promise<void>;
+}
+
+declare class AuthService {
+    private readonly config;
+    private readonly cols;
+    private readonly tokens;
+    private readonly audit;
+    constructor(config: AuthConfig, cols: AuthCollections, tokens: TokenService, audit: AuditService);
+    private getCredentials;
+    private ensureCredentials;
+    /** Set or update the password for a user (used by apps/tests; registration is app-owned). */
+    setPassword(userId: string, password: string): Promise<void>;
+    login(req: Request, res: Response, input: {
+        username: string;
+        password: string;
+        rememberMe: boolean;
+    }): Promise<LoginResponse>;
+    private registerFailedLogin;
+    private resetFailedLogins;
+    private checkTrustedDevice;
+    /** Issue tokens + set cookies (refresh cookie, CSRF cookie). */
+    authenticate(userId: string, req: Request, res: Response, amr: string[], opts?: {
+        rememberDevice?: boolean;
+        rememberMe?: boolean;
+        deviceLabel?: string;
+    }): Promise<{
+        status: "AUTHENTICATED";
+        user: {
+            id: string;
+            username?: string;
+            email?: string;
+        };
+        tokens: {
+            accessToken: string;
+            expiresInSec: number;
+        };
+    }>;
+    trustDevice(userId: string, res: Response, label: string): Promise<void>;
+    refresh(req: Request, res: Response): Promise<{
+        accessToken: string;
+        expiresInSec: number;
+    }>;
+    logout(req: Request, res: Response, sid: string): Promise<void>;
+    listActiveMethods(userId: string): Promise<Method[]>;
+}
+
+/**
+ * Create the auth collections with validators, indexes and TTLs (A.4).
+ * Idempotent — safe on every boot.
+ */
+declare function migrate(db: Db, prefix?: string, auditDays?: number): Promise<AuthCollections>;
+/**
+ * Mount API (A.3):
+ *   app.use(express.json());
+ *   app.use(createAuthRouter(config));
+ */
+declare function createAuthRouter(input: AuthConfigInput): Router;
+
+export { type AdapterUser, ApiErrorException, type AuthConfig, type AuthConfigInput, AuthService, type Clock, type EmailProvider, type Hooks, type Logger, type SecurityEvent, type SmsProvider, type UserAdapter, apiError, consoleEmail, consoleSms, createAuthRouter, errorHandler, getCollections, migrate, twilioSms };