@puzzle-ui/auth 0.0.0-stage → 0.5.0

package/dist/types/auth-manager.types.d.cts

@@ -0,0 +1,106 @@
+import { PasswordHasher, RateLimitProvider } from "../providers/provider.types.cjs";
+import { AuthMfaEnrollmentPendingResult, AuthMfaGateway, AuthMfaPendingResult } from "./mfa.types.cjs";
+import { AuthState } from "./state.types.cjs";
+import { AuthUser } from "./user.types.cjs";
+import { StorageAdapter } from "@puzzle-ui/storage";
+import { SessionManager } from "@puzzle-ui/session";
+export type AuthRateLimitRule = {
+  readonly limit: number;
+  readonly windowSeconds: number;
+};
+export type AuthRateLimitScopePolicy = {
+  readonly email: AuthRateLimitRule;
+  readonly ip: AuthRateLimitRule;
+};
+export type AuthRateLimitPolicies = {
+  readonly registration: AuthRateLimitScopePolicy;
+  readonly signIn: AuthRateLimitScopePolicy;
+};
+/**
+ * Determines which users must authenticate with MFA.
+ *
+ * When required is true, MFA is required for every user.
+ * requiredFor can additionally enforce MFA for selected users.
+ *
+ * When neither option is configured, MFA remains optional for
+ * users without enrolled factors. Existing enrolled factors are
+ * still challenged during sign-in.
+ */
+export type AuthMfaPolicy = {
+  readonly required?: boolean;
+  readonly requiredFor?: (user: AuthUser) => boolean | Promise<boolean>;
+};
+export type AuthManagerOptions = {
+  readonly rateLimitKeySecret: string;
+  readonly usersCollection?: string;
+  readonly credentialsCollection?: string;
+  readonly auditCollection?: string;
+  readonly minimumPasswordLength?: number;
+  readonly maximumPasswordLength?: number;
+  readonly requireVerifiedEmail?: boolean;
+  readonly mfaPolicy?: AuthMfaPolicy;
+  readonly rateLimits?: {
+    readonly registration?: Partial<AuthRateLimitScopePolicy>;
+    readonly signIn?: Partial<AuthRateLimitScopePolicy>;
+  };
+  readonly clock?: () => Date;
+};
+export type AuthManagerDependencies = {
+  readonly storage: StorageAdapter;
+  readonly passwordHasher: PasswordHasher;
+  readonly rateLimitProvider: RateLimitProvider;
+  readonly sessions: SessionManager;
+  readonly mfa?: AuthMfaGateway;
+};
+export type AuthSession = {
+  readonly id: string;
+  readonly userId: string;
+  readonly kind: "authenticated";
+  readonly createdAt: Date;
+  readonly lastSeenAt: Date;
+  readonly expiresAt: Date;
+  readonly revokedAt: Date | null;
+};
+export type AuthResult = {
+  readonly user: AuthUser;
+  readonly session: AuthSession;
+  /** Server-only. Deliver exclusively through a secure HttpOnly cookie. */
+  readonly token: string;
+};
+/**
+ * Registration can complete immediately when MFA is optional.
+ *
+ * When MFA is required, registration creates the account but returns
+ * an enrollment challenge instead of an authenticated session.
+ */
+export type AuthRegisterResult = AuthResult | AuthMfaEnrollmentPendingResult;
+/**
+ * A successful password check can result in:
+ *
+ * 1. A fully authenticated session.
+ * 2. An MFA sign-in challenge.
+ * 3. A mandatory first-factor enrollment challenge.
+ */
+export type AuthSignInResult = AuthResult | AuthMfaPendingResult | AuthMfaEnrollmentPendingResult;
+export type AuthRegisterInput = {
+  readonly email: string;
+  readonly password: string;
+  readonly name?: string | null;
+  readonly ipAddress: string;
+  readonly sessionMetadata?: Readonly<Record<string, unknown>>;
+};
+export type AuthSignInInput = {
+  readonly email: string;
+  readonly password: string;
+  readonly ipAddress: string;
+  readonly sessionMetadata?: Readonly<Record<string, unknown>>;
+};
+export interface AuthManager {
+  initialize(): Promise<void>;
+  register(input: AuthRegisterInput): Promise<AuthRegisterResult>;
+  signIn(input: AuthSignInInput): Promise<AuthSignInResult>;
+  getCurrentUser(token: string): Promise<AuthUser | null>;
+  getAuthState(token: string): Promise<AuthState>;
+  signOut(token: string): Promise<void>;
+  signOutEverywhere(userId: string): Promise<void>;
+}

package/dist/types/auth-manager.types.d.ts

@@ -0,0 +1,106 @@
+import { PasswordHasher, RateLimitProvider } from "../providers/provider.types.js";
+import { AuthMfaEnrollmentPendingResult, AuthMfaGateway, AuthMfaPendingResult } from "./mfa.types.js";
+import { AuthState } from "./state.types.js";
+import { AuthUser } from "./user.types.js";
+import { StorageAdapter } from "@puzzle-ui/storage";
+import { SessionManager } from "@puzzle-ui/session";
+export type AuthRateLimitRule = {
+  readonly limit: number;
+  readonly windowSeconds: number;
+};
+export type AuthRateLimitScopePolicy = {
+  readonly email: AuthRateLimitRule;
+  readonly ip: AuthRateLimitRule;
+};
+export type AuthRateLimitPolicies = {
+  readonly registration: AuthRateLimitScopePolicy;
+  readonly signIn: AuthRateLimitScopePolicy;
+};
+/**
+ * Determines which users must authenticate with MFA.
+ *
+ * When required is true, MFA is required for every user.
+ * requiredFor can additionally enforce MFA for selected users.
+ *
+ * When neither option is configured, MFA remains optional for
+ * users without enrolled factors. Existing enrolled factors are
+ * still challenged during sign-in.
+ */
+export type AuthMfaPolicy = {
+  readonly required?: boolean;
+  readonly requiredFor?: (user: AuthUser) => boolean | Promise<boolean>;
+};
+export type AuthManagerOptions = {
+  readonly rateLimitKeySecret: string;
+  readonly usersCollection?: string;
+  readonly credentialsCollection?: string;
+  readonly auditCollection?: string;
+  readonly minimumPasswordLength?: number;
+  readonly maximumPasswordLength?: number;
+  readonly requireVerifiedEmail?: boolean;
+  readonly mfaPolicy?: AuthMfaPolicy;
+  readonly rateLimits?: {
+    readonly registration?: Partial<AuthRateLimitScopePolicy>;
+    readonly signIn?: Partial<AuthRateLimitScopePolicy>;
+  };
+  readonly clock?: () => Date;
+};
+export type AuthManagerDependencies = {
+  readonly storage: StorageAdapter;
+  readonly passwordHasher: PasswordHasher;
+  readonly rateLimitProvider: RateLimitProvider;
+  readonly sessions: SessionManager;
+  readonly mfa?: AuthMfaGateway;
+};
+export type AuthSession = {
+  readonly id: string;
+  readonly userId: string;
+  readonly kind: "authenticated";
+  readonly createdAt: Date;
+  readonly lastSeenAt: Date;
+  readonly expiresAt: Date;
+  readonly revokedAt: Date | null;
+};
+export type AuthResult = {
+  readonly user: AuthUser;
+  readonly session: AuthSession;
+  /** Server-only. Deliver exclusively through a secure HttpOnly cookie. */
+  readonly token: string;
+};
+/**
+ * Registration can complete immediately when MFA is optional.
+ *
+ * When MFA is required, registration creates the account but returns
+ * an enrollment challenge instead of an authenticated session.
+ */
+export type AuthRegisterResult = AuthResult | AuthMfaEnrollmentPendingResult;
+/**
+ * A successful password check can result in:
+ *
+ * 1. A fully authenticated session.
+ * 2. An MFA sign-in challenge.
+ * 3. A mandatory first-factor enrollment challenge.
+ */
+export type AuthSignInResult = AuthResult | AuthMfaPendingResult | AuthMfaEnrollmentPendingResult;
+export type AuthRegisterInput = {
+  readonly email: string;
+  readonly password: string;
+  readonly name?: string | null;
+  readonly ipAddress: string;
+  readonly sessionMetadata?: Readonly<Record<string, unknown>>;
+};
+export type AuthSignInInput = {
+  readonly email: string;
+  readonly password: string;
+  readonly ipAddress: string;
+  readonly sessionMetadata?: Readonly<Record<string, unknown>>;
+};
+export interface AuthManager {
+  initialize(): Promise<void>;
+  register(input: AuthRegisterInput): Promise<AuthRegisterResult>;
+  signIn(input: AuthSignInInput): Promise<AuthSignInResult>;
+  getCurrentUser(token: string): Promise<AuthUser | null>;
+  getAuthState(token: string): Promise<AuthState>;
+  signOut(token: string): Promise<void>;
+  signOutEverywhere(userId: string): Promise<void>;
+}

package/dist/types/credential.types.d.cts

@@ -0,0 +1,9 @@
+import { PasswordHash } from "../providers/provider.types.cjs";
+import { StorageRecord } from "@puzzle-ui/storage";
+export type PasswordCredentialStorageRecord = StorageRecord & {
+  readonly userId: string;
+  readonly kind: "password";
+  readonly passwordHash: PasswordHash;
+  readonly passwordUpdatedAt: Date;
+  readonly revokedAt: Date | null;
+};

package/dist/types/credential.types.d.ts

@@ -0,0 +1,9 @@
+import { PasswordHash } from "../providers/provider.types.js";
+import { StorageRecord } from "@puzzle-ui/storage";
+export type PasswordCredentialStorageRecord = StorageRecord & {
+  readonly userId: string;
+  readonly kind: "password";
+  readonly passwordHash: PasswordHash;
+  readonly passwordUpdatedAt: Date;
+  readonly revokedAt: Date | null;
+};

package/dist/types/mfa.types.d.cts

@@ -0,0 +1,244 @@
+import { AuthResult } from "./auth-manager.types.cjs";
+import { ProtectedAuthSecret } from "../providers/mfa-provider.types.cjs";
+import { AuthState } from "./state.types.cjs";
+import { StorageRecord } from "@puzzle-ui/storage";
+export type AuthMfaFactorType = "totp" | "passkey";
+export type AuthMfaFactorStatus = "pending" | "active";
+export type AuthMfaAvailableFactor = "totp" | "passkey" | "recovery-code";
+export type AuthMfaEnrollmentFactor = "totp" | "passkey";
+export type AuthMfaEnrollmentPendingResult = {
+  readonly status: "mfa-enrollment-pending";
+  readonly challengeId: string;
+  /**
+   * Server-only temporary credential.
+   *
+   * Deliver exclusively through a short-lived HttpOnly cookie.
+   * Never serialize this token into browser JSON or browser storage.
+   */
+  readonly challengeToken: string;
+  readonly expiresAt: Date;
+  readonly availableFactors: readonly AuthMfaEnrollmentFactor[];
+};
+export type AuthMfaEnrollmentCompleted = {
+  /**
+   * The authenticated result is only created after the first factor
+   * has been successfully verified and the enrollment transaction commits.
+   */
+  readonly auth: AuthResult;
+  readonly factor: AuthMfaFactor;
+  readonly recoveryCodes: readonly string[];
+};
+export type BeginRequiredMfaEnrollmentInput = {
+  readonly challengeToken: string;
+  readonly ipAddress: string;
+  readonly label?: string;
+};
+export type VerifyRequiredTotpEnrollmentInput = {
+  readonly challengeToken: string;
+  readonly factorId: string;
+  readonly code: string;
+  readonly ipAddress: string;
+};
+export type FinishRequiredPasskeyEnrollmentInput = {
+  readonly challengeToken: string;
+  readonly response: unknown;
+  readonly ipAddress: string;
+};
+export type AuthMfaFactor = {
+  readonly id: string;
+  readonly type: AuthMfaFactorType;
+  readonly status: AuthMfaFactorStatus;
+  readonly label: string;
+  readonly createdAt: Date;
+  readonly lastUsedAt: Date | null;
+};
+export type AuthMfaFactorStorageRecord = StorageRecord & {
+  readonly userId: string;
+  /**
+   * Globally unique key.
+   * TOTP: totp:<factor-id>
+   * Passkey: passkey:<credential-id>
+   */
+  readonly factorKey: string;
+  readonly type: AuthMfaFactorType;
+  readonly status: AuthMfaFactorStatus;
+  readonly label: string;
+  /** Encrypted TOTP secret; never populated for passkeys. */
+  readonly secret: ProtectedAuthSecret | null;
+  /** WebAuthn credential data; never populated for TOTP. */
+  readonly credentialId: string | null;
+  readonly publicKey: string | null;
+  readonly counter: number;
+  readonly transports: readonly string[];
+  /** Prevents reuse of an accepted TOTP time step. */
+  readonly lastUsedStep: number | null;
+  readonly lastUsedAt: Date | null;
+  /** Pending enrollments expire automatically at the domain level. */
+  readonly expiresAt: Date | null;
+};
+export type AuthMfaChallengePurpose = "sign-in" | "enrollment" | "passkey-registration" | "passkey-sign-in";
+export type AuthMfaChallengeStorageRecord = StorageRecord & {
+  readonly purpose: AuthMfaChallengePurpose;
+  /** SHA-256 hash of the temporary challenge token. */
+  readonly tokenHash: string;
+  /** Null for discoverable passkey sign-in. */
+  readonly userId: string | null;
+  /** Factors accepted by the current MFA challenge. */
+  readonly factorIds: readonly string[];
+  /** Passkeys allowed for an in-progress WebAuthn ceremony. */
+  readonly webAuthnFactorIds: readonly string[];
+  /** WebAuthn challenge, bound to this temporary record. */
+  readonly webAuthnChallenge: string | null;
+  /** Label selected when a passkey registration was initiated. */
+  readonly factorLabel: string | null;
+  /**
+   * Account-state snapshot for password-backed sign-in challenges.
+   * A challenge becomes invalid if either record changes.
+   */
+  readonly userRevision: number | null;
+  readonly credentialRevision: number | null;
+  readonly attemptCount: number;
+  readonly maximumAttempts: number;
+  readonly expiresAt: Date;
+  readonly consumedAt: Date | null;
+};
+export type AuthRecoveryCodeStorageRecord = StorageRecord & {
+  readonly userId: string;
+  readonly factorId: string;
+  readonly codeHash: string;
+  readonly consumedAt: Date | null;
+};
+export type AuthMfaPendingResult = {
+  readonly status: "mfa-pending";
+  readonly challengeId: string;
+  /**
+   * Server-only temporary credential.
+   *
+   * Deliver this through a short-lived HttpOnly cookie.
+   * Never serialize it into browser JSON or browser storage.
+   */
+  readonly challengeToken: string;
+  readonly expiresAt: Date;
+  readonly availableFactors: readonly AuthMfaAvailableFactor[];
+};
+export type AuthMfaGateway = {
+  initialize(): Promise<void>;
+  createSignInChallenge(input: {
+    readonly userId: string;
+    readonly ipAddress: string;
+  }): Promise<AuthMfaPendingResult | null>;
+  createEnrollmentChallenge(input: {
+    readonly userId: string;
+    readonly ipAddress: string;
+  }): Promise<AuthMfaEnrollmentPendingResult>;
+  /**
+   * Returns whether the user currently has at least one active MFA factor.
+   * Used by AuthManager to enforce policy against existing sessions.
+   */
+  hasActiveFactor(userId: string): Promise<boolean>;
+  getPendingAuthState(token: string): Promise<AuthState | null>;
+  revokeChallenges(userId: string): Promise<void>;
+};
+export type AuthMfaTotpOptions = {
+  readonly digits: number;
+  readonly periodSeconds: number;
+  /** Number of adjacent time steps accepted on either side. */
+  readonly window: number;
+};
+export type AuthMfaWebAuthnOptions = {
+  readonly rpId: string;
+  readonly rpName: string;
+  /** Exact expected browser origin, including scheme and port. */
+  readonly origin: string;
+};
+export type AuthMfaManagerOptions = {
+  readonly rateLimitKeySecret: string;
+  readonly usersCollection?: string;
+  readonly credentialsCollection?: string;
+  readonly auditCollection?: string;
+  readonly factorsCollection?: string;
+  readonly challengesCollection?: string;
+  readonly recoveryCodesCollection?: string;
+  readonly challengeLifetimeSeconds?: number;
+  readonly recoveryCodeCount?: number;
+  readonly issuer?: string;
+  readonly totp?: Partial<AuthMfaTotpOptions>;
+  readonly webAuthn?: AuthMfaWebAuthnOptions;
+  /** Keep this aligned with AuthManagerOptions.requireVerifiedEmail. */
+  readonly requireVerifiedEmail?: boolean;
+  readonly clock?: () => Date;
+};
+export type BeginTotpEnrollmentInput = {
+  readonly sessionToken: string;
+  readonly currentPassword: string;
+  readonly ipAddress: string;
+  readonly label?: string;
+};
+export type TotpEnrollmentStarted = {
+  readonly factorId: string;
+  readonly secret: string;
+  readonly otpauthUrl: string;
+  readonly expiresAt: Date;
+};
+export type VerifyTotpEnrollmentInput = {
+  readonly sessionToken: string;
+  readonly factorId: string;
+  readonly code: string;
+  readonly ipAddress: string;
+};
+export type MfaEnrollmentCompleted = {
+  readonly factor: AuthMfaFactor;
+  readonly recoveryCodes: readonly string[];
+};
+export type BeginPasskeyRegistrationInput = {
+  readonly sessionToken: string;
+  readonly currentPassword: string;
+  readonly ipAddress: string;
+  readonly label?: string;
+};
+export type PasskeyRegistrationStarted = {
+  readonly challengeId: string;
+  readonly challengeToken: string;
+  readonly options: Readonly<Record<string, unknown>>;
+  readonly expiresAt: Date;
+};
+export type FinishPasskeyRegistrationInput = {
+  readonly sessionToken: string;
+  readonly challengeToken: string;
+  readonly response: unknown;
+  readonly ipAddress: string;
+};
+export type BeginPasskeySignInInput = {
+  readonly ipAddress: string;
+};
+export type PasskeySignInStarted = {
+  readonly challengeId: string;
+  readonly challengeToken: string;
+  readonly options: Readonly<Record<string, unknown>>;
+  readonly expiresAt: Date;
+};
+export type CompleteMfaSignInInput = {
+  readonly challengeToken: string;
+  readonly code: string;
+  readonly ipAddress: string;
+};
+export type PasskeyMfaStarted = {
+  readonly options: Readonly<Record<string, unknown>>;
+  readonly expiresAt: Date;
+};
+export type PasskeyMfaCompletedInput = {
+  readonly challengeToken: string;
+  readonly response: unknown;
+  readonly ipAddress: string;
+};
+export type RemoveMfaFactorInput = {
+  readonly sessionToken: string;
+  readonly factorId: string;
+  readonly currentPassword: string;
+  readonly ipAddress: string;
+};
+export type RegenerateRecoveryCodesInput = {
+  readonly sessionToken: string;
+  readonly currentPassword: string;
+  readonly ipAddress: string;
+};