@puzzle-ui/auth 0.0.0-stage → 0.5.1

package/dist/auth.step-up.manager.cjs

@@ -0,0 +1,269 @@
+const require_auth_errors = require("./errors/auth.errors.cjs");
+const require_auth_crypto_utils = require("./utils/auth-crypto.utils.cjs");
+let _puzzle_ui_storage = require("@puzzle-ui/storage");
+// src/auth.step-up.manager.ts
+const AUTH_MFA_STEP_UP_COLLECTION = "auth_mfa_step_up_challenges";
+const stepUpCollection = {
+	name: AUTH_MFA_STEP_UP_COLLECTION,
+	indexes: [
+		{
+			name: "step_up_token_hash_unique",
+			fields: ["tokenHash"],
+			unique: true
+		},
+		{
+			name: "step_up_session_expiration",
+			fields: ["sessionId", "expiresAt"]
+		},
+		{
+			name: "step_up_user_expiration",
+			fields: ["userId", "expiresAt"]
+		}
+	]
+};
+const toPublicSession = (session) => {
+	if (session.kind !== "authenticated" || !session.userId) throw new require_auth_errors.AuthSessionError("A step-up session must be authenticated.");
+	return {
+		id: session.id,
+		userId: session.userId,
+		kind: "authenticated",
+		createdAt: session.createdAt,
+		lastSeenAt: session.lastSeenAt,
+		expiresAt: session.expiresAt,
+		revokedAt: session.revokedAt
+	};
+};
+var StorageAuthStepUpManager = class {
+	storage;
+	sessions;
+	mfa;
+	collectionName;
+	clock;
+	initialized = false;
+	initializationPromise = null;
+	constructor(dependencies, options = {}) {
+		this.storage = dependencies.storage;
+		this.sessions = dependencies.sessions;
+		this.mfa = dependencies.mfa;
+		this.collectionName = options.collectionName ?? "auth_mfa_step_up_challenges";
+		this.clock = options.clock ?? (() => /* @__PURE__ */ new Date());
+		if (!this.collectionName || this.collectionName.trim().length === 0) throw new require_auth_errors.AuthConfigurationError("A valid MFA step-up collection name is required.");
+	}
+	async initialize() {
+		if (!this.initializationPromise) {
+			const initialization = (async () => {
+				if (!this.storage.capabilities.uniqueConstraints || !this.storage.capabilities.conditionalWrites || !this.storage.capabilities.atomicBatch) throw new require_auth_errors.AuthConfigurationError("MFA step-up requires unique constraints, conditional writes and atomic batches.");
+				await this.storage.registerCollection({
+					...stepUpCollection,
+					name: this.collectionName
+				});
+				this.initialized = true;
+			})();
+			this.initializationPromise = initialization.catch((error) => {
+				this.initializationPromise = null;
+				this.initialized = false;
+				throw error;
+			});
+		}
+		return this.initializationPromise;
+	}
+	assertInitialized() {
+		if (!this.initialized) throw new require_auth_errors.AuthConfigurationError("The MFA step-up manager must be initialized before use.");
+	}
+	now() {
+		const value = this.clock();
+		if (!(value instanceof Date) || !Number.isFinite(value.getTime())) throw new require_auth_errors.AuthConfigurationError("The configured step-up clock returned an invalid date.");
+		return value;
+	}
+	async getAuthenticatedSession(sessionToken) {
+		if (typeof sessionToken !== "string" || sessionToken.length === 0) throw new require_auth_errors.AuthSessionError("An authenticated session is required.");
+		let session;
+		try {
+			session = await this.sessions.validate(sessionToken);
+		} catch (error) {
+			throw new require_auth_errors.AuthSessionError("Could not validate the step-up session.", { cause: error });
+		}
+		if (!session || session.kind !== "authenticated" || !session.userId || session.revokedAt !== null || session.expiresAt.getTime() <= this.now().getTime()) throw new require_auth_errors.AuthSessionError("An authenticated session is required.");
+		return session;
+	}
+	async findChallenge(challengeToken) {
+		if (typeof challengeToken !== "string" || !/^[a-f0-9]{64}$/i.test(challengeToken)) return null;
+		const tokenHash = await require_auth_crypto_utils.hashAuthToken(challengeToken);
+		return this.storage.findOne(this.collectionName, { where: { tokenHash: {
+			operator: "eq",
+			value: tokenHash
+		} } });
+	}
+	async getPendingContext(challengeToken, sessionToken) {
+		const challenge = await this.findChallenge(challengeToken);
+		if (!challenge || challenge.consumedAt !== null || challenge.expiresAt.getTime() <= this.now().getTime()) throw new require_auth_errors.AuthMfaChallengeError();
+		const session = await this.getAuthenticatedSession(sessionToken);
+		if (session.id !== challenge.sessionId || session.userId !== challenge.userId) throw new require_auth_errors.AuthMfaChallengeError();
+		return {
+			challenge,
+			session
+		};
+	}
+	async beginStepUp(input) {
+		this.assertInitialized();
+		const session = await this.getAuthenticatedSession(input.sessionToken);
+		const challenge = await this.mfa.createSignInChallenge({
+			userId: session.userId,
+			ipAddress: input.ipAddress
+		});
+		if (!challenge) throw new require_auth_errors.AuthMfaFactorError("An active MFA factor is required for step-up authentication.");
+		const now = this.now();
+		const record = {
+			id: require_auth_crypto_utils.generateAuthId("mfa-step-up"),
+			challengeId: challenge.challengeId,
+			tokenHash: await require_auth_crypto_utils.hashAuthToken(challenge.challengeToken),
+			userId: session.userId,
+			sessionId: session.id,
+			expiresAt: challenge.expiresAt,
+			consumedAt: null,
+			createdAt: now,
+			updatedAt: now,
+			revision: 1
+		};
+		try {
+			await this.storage.insert(this.collectionName, record);
+		} catch (error) {
+			throw new require_auth_errors.AuthProviderError("Could not persist the step-up challenge.", { cause: error });
+		}
+		return challenge;
+	}
+	async getPendingAuthState(challengeToken, sessionToken) {
+		this.assertInitialized();
+		const challenge = await this.findChallenge(challengeToken);
+		if (!challenge || challenge.consumedAt !== null || challenge.expiresAt.getTime() <= this.now().getTime()) return null;
+		let session;
+		try {
+			session = await this.getAuthenticatedSession(sessionToken);
+		} catch {
+			return null;
+		}
+		if (session.id !== challenge.sessionId || session.userId !== challenge.userId) return null;
+		const mfaState = await this.mfa.getPendingAuthState(challengeToken);
+		if (!mfaState || mfaState.status !== "mfa-pending" || mfaState.challengeId !== challenge.challengeId) return null;
+		return {
+			status: "step-up-pending",
+			challengeId: challenge.challengeId,
+			expiresAt: challenge.expiresAt
+		};
+	}
+	async beginPasskey(input) {
+		this.assertInitialized();
+		await this.getPendingContext(input.challengeToken, input.sessionToken);
+		return this.mfa.beginPasskeyMfa(input.challengeToken, input.ipAddress);
+	}
+	async consumeChallenge(challenge) {
+		const now = this.now();
+		try {
+			if (!await this.storage.update(this.collectionName, challenge.id, {
+				consumedAt: now,
+				updatedAt: now
+			}, { expectedRevision: challenge.revision })) throw new _puzzle_ui_storage.StorageConflictError("The step-up challenge was already consumed.");
+		} catch (error) {
+			throw new require_auth_errors.AuthMfaChallengeError({ cause: error });
+		}
+	}
+	async revokeTemporarySession(sessionId) {
+		try {
+			await this.sessions.revoke(sessionId);
+		} catch (error) {
+			throw new require_auth_errors.AuthSessionError("Could not revoke the temporary MFA verification session.", { cause: error });
+		}
+	}
+	async completeStepUp(input, verify) {
+		this.assertInitialized();
+		const context = await this.getPendingContext(input.challengeToken, input.sessionToken);
+		const verified = await verify(input.challengeToken);
+		if (verified.user.id !== context.challenge.userId) {
+			await this.revokeTemporarySession(verified.session.id);
+			throw new require_auth_errors.AuthMfaChallengeError();
+		}
+		try {
+			await this.consumeChallenge(context.challenge);
+		} catch (error) {
+			try {
+				await this.revokeTemporarySession(verified.session.id);
+			} catch (revokeError) {
+				throw new require_auth_errors.AuthSessionError("The step-up challenge failed and its temporary session could not be revoked.", { cause: revokeError });
+			}
+			throw error;
+		}
+		const now = this.now();
+		let replacement;
+		try {
+			replacement = await this.sessions.rotate({
+				sessionId: context.session.id,
+				metadata: {
+					...context.session.metadata ?? {},
+					authenticationMethod: input.method,
+					mfaVerifiedAt: now.toISOString(),
+					stepUpVerifiedAt: now.toISOString(),
+					stepUpOfSessionId: context.session.id
+				}
+			});
+		} catch (error) {
+			try {
+				await this.revokeTemporarySession(verified.session.id);
+			} catch (revokeError) {
+				throw new require_auth_errors.AuthSessionError("Session rotation failed and the temporary MFA session could not be revoked.", { cause: revokeError });
+			}
+			throw new require_auth_errors.AuthSessionError("Could not atomically rotate the session after step-up verification.", { cause: error });
+		}
+		try {
+			await this.revokeTemporarySession(verified.session.id);
+		} catch (error) {
+			try {
+				await this.sessions.revoke(replacement.session.id);
+			} catch (revokeError) {
+				throw new require_auth_errors.AuthSessionError("Could not revoke the replacement session after temporary-session cleanup failed.", { cause: revokeError });
+			}
+			throw error;
+		}
+		return {
+			user: verified.user,
+			session: toPublicSession(replacement.session),
+			token: replacement.token
+		};
+	}
+	async verifyTotp(input) {
+		return this.completeStepUp({
+			...input,
+			method: "totp"
+		}, (challengeToken) => this.mfa.verifySignInTotp({
+			challengeToken,
+			code: input.code,
+			ipAddress: input.ipAddress
+		}));
+	}
+	async verifyRecoveryCode(input) {
+		return this.completeStepUp({
+			...input,
+			method: "recovery-code"
+		}, (challengeToken) => this.mfa.verifySignInRecoveryCode({
+			challengeToken,
+			code: input.code,
+			ipAddress: input.ipAddress
+		}));
+	}
+	async finishPasskey(input) {
+		await this.getPendingContext(input.challengeToken, input.sessionToken);
+		return this.completeStepUp({
+			challengeToken: input.challengeToken,
+			sessionToken: input.sessionToken,
+			ipAddress: input.ipAddress,
+			method: "passkey"
+		}, (challengeToken) => this.mfa.finishPasskeyMfa({
+			challengeToken,
+			response: input.response,
+			ipAddress: input.ipAddress
+		}));
+	}
+};
+exports.AUTH_MFA_STEP_UP_COLLECTION = AUTH_MFA_STEP_UP_COLLECTION;
+exports.StorageAuthStepUpManager = StorageAuthStepUpManager;
+
+//# sourceMappingURL=auth.step-up.manager.cjs.map

package/dist/auth.step-up.manager.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.step-up.manager.cjs","names":["AuthSessionError","AuthConfigurationError","hashAuthToken","AuthMfaChallengeError","AuthMfaFactorError","generateAuthId","AuthProviderError","StorageConflictError"],"sources":["../src/auth.step-up.manager.ts"],"sourcesContent":["import {\n  StorageConflictError,\n  type StorageAdapter,\n  type StorageCollection,\n  type StorageRecord,\n} from \"@puzzle-ui/storage\";\n\nimport type { SessionManager, SessionRecord } from \"@puzzle-ui/session\";\n\nimport {\n  AuthConfigurationError,\n  AuthMfaChallengeError,\n  AuthMfaFactorError,\n  AuthProviderError,\n  AuthSessionError,\n} from \"./errors/auth.errors\";\n\nimport type { AuthResult, AuthSession } from \"./types/auth-manager.types\";\n\nimport type {\n  AuthMfaPendingResult,\n  PasskeyMfaStarted,\n} from \"./types/mfa.types\";\n\nimport { generateAuthId, hashAuthToken } from \"./utils/auth-crypto.utils\";\n\nimport type { StorageAuthMfaManager } from \"./auth.mfa.manager\";\n\nexport const AUTH_MFA_STEP_UP_COLLECTION = \"auth_mfa_step_up_challenges\";\n\nexport type AuthStepUpChallengeStorageRecord = StorageRecord & {\n  readonly challengeId: string;\n  readonly tokenHash: string;\n  readonly userId: string;\n  readonly sessionId: string;\n  readonly expiresAt: Date;\n  readonly consumedAt: Date | null;\n};\n\nexport type AuthStepUpManagerOptions = {\n  readonly collectionName?: string;\n  readonly clock?: () => Date;\n};\n\nexport type StorageAuthStepUpManagerDependencies = {\n  readonly storage: StorageAdapter;\n  readonly sessions: SessionManager;\n  readonly mfa: StorageAuthMfaManager;\n};\n\nexport type BeginStepUpInput = {\n  readonly sessionToken: string;\n  readonly ipAddress: string;\n};\n\nexport type CompleteStepUpInput = {\n  readonly challengeToken: string;\n  readonly sessionToken: string;\n  readonly code: string;\n  readonly ipAddress: string;\n};\n\nexport type BeginStepUpPasskeyInput = {\n  readonly challengeToken: string;\n  readonly sessionToken: string;\n  readonly ipAddress: string;\n};\n\nexport type FinishStepUpPasskeyInput = {\n  readonly challengeToken: string;\n  readonly sessionToken: string;\n  readonly response: unknown;\n  readonly ipAddress: string;\n};\n\nexport type AuthStepUpPendingState = {\n  readonly status: \"step-up-pending\";\n  readonly challengeId: string;\n  readonly expiresAt: Date;\n};\n\ntype PendingContext = {\n  readonly challenge: AuthStepUpChallengeStorageRecord;\n  readonly session: SessionRecord;\n};\n\ntype MfaVerification = (challengeToken: string) => Promise<AuthResult>;\n\nconst stepUpCollection: StorageCollection<AuthStepUpChallengeStorageRecord> = {\n  name: AUTH_MFA_STEP_UP_COLLECTION,\n  indexes: [\n    {\n      name: \"step_up_token_hash_unique\",\n      fields: [\"tokenHash\"],\n      unique: true,\n    },\n    {\n      name: \"step_up_session_expiration\",\n      fields: [\"sessionId\", \"expiresAt\"],\n    },\n    {\n      name: \"step_up_user_expiration\",\n      fields: [\"userId\", \"expiresAt\"],\n    },\n  ],\n};\n\nconst toPublicSession = (session: SessionRecord): AuthSession => {\n  if (session.kind !== \"authenticated\" || !session.userId) {\n    throw new AuthSessionError(\"A step-up session must be authenticated.\");\n  }\n\n  return {\n    id: session.id,\n    userId: session.userId,\n    kind: \"authenticated\",\n    createdAt: session.createdAt,\n    lastSeenAt: session.lastSeenAt,\n    expiresAt: session.expiresAt,\n    revokedAt: session.revokedAt,\n  };\n};\n\nexport class StorageAuthStepUpManager {\n  private readonly storage: StorageAdapter;\n  private readonly sessions: SessionManager;\n  private readonly mfa: StorageAuthMfaManager;\n\n  private readonly collectionName: string;\n  private readonly clock: () => Date;\n\n  private initialized = false;\n  private initializationPromise: Promise<void> | null = null;\n\n  constructor(\n    dependencies: StorageAuthStepUpManagerDependencies,\n    options: AuthStepUpManagerOptions = {},\n  ) {\n    this.storage = dependencies.storage;\n    this.sessions = dependencies.sessions;\n    this.mfa = dependencies.mfa;\n\n    this.collectionName = options.collectionName ?? AUTH_MFA_STEP_UP_COLLECTION;\n\n    this.clock = options.clock ?? (() => new Date());\n\n    if (!this.collectionName || this.collectionName.trim().length === 0) {\n      throw new AuthConfigurationError(\n        \"A valid MFA step-up collection name is required.\",\n      );\n    }\n  }\n\n  async initialize(): Promise<void> {\n    if (!this.initializationPromise) {\n      const initialization = (async () => {\n        if (\n          !this.storage.capabilities.uniqueConstraints ||\n          !this.storage.capabilities.conditionalWrites ||\n          !this.storage.capabilities.atomicBatch\n        ) {\n          throw new AuthConfigurationError(\n            \"MFA step-up requires unique constraints, conditional writes and atomic batches.\",\n          );\n        }\n\n        await this.storage.registerCollection({\n          ...stepUpCollection,\n          name: this.collectionName,\n        });\n\n        this.initialized = true;\n      })();\n\n      this.initializationPromise = initialization.catch((error) => {\n        this.initializationPromise = null;\n        this.initialized = false;\n        throw error;\n      });\n    }\n\n    return this.initializationPromise;\n  }\n\n  private assertInitialized(): void {\n    if (!this.initialized) {\n      throw new AuthConfigurationError(\n        \"The MFA step-up manager must be initialized before use.\",\n      );\n    }\n  }\n\n  private now(): Date {\n    const value = this.clock();\n\n    if (!(value instanceof Date) || !Number.isFinite(value.getTime())) {\n      throw new AuthConfigurationError(\n        \"The configured step-up clock returned an invalid date.\",\n      );\n    }\n\n    return value;\n  }\n\n  private async getAuthenticatedSession(\n    sessionToken: string,\n  ): Promise<SessionRecord> {\n    if (typeof sessionToken !== \"string\" || sessionToken.length === 0) {\n      throw new AuthSessionError(\"An authenticated session is required.\");\n    }\n\n    let session: SessionRecord | null;\n\n    try {\n      session = await this.sessions.validate(sessionToken);\n    } catch (error) {\n      throw new AuthSessionError(\"Could not validate the step-up session.\", {\n        cause: error,\n      });\n    }\n\n    if (\n      !session ||\n      session.kind !== \"authenticated\" ||\n      !session.userId ||\n      session.revokedAt !== null ||\n      session.expiresAt.getTime() <= this.now().getTime()\n    ) {\n      throw new AuthSessionError(\"An authenticated session is required.\");\n    }\n\n    return session;\n  }\n\n  private async findChallenge(\n    challengeToken: string,\n  ): Promise<AuthStepUpChallengeStorageRecord | null> {\n    if (\n      typeof challengeToken !== \"string\" ||\n      !/^[a-f0-9]{64}$/i.test(challengeToken)\n    ) {\n      return null;\n    }\n\n    const tokenHash = await hashAuthToken(challengeToken);\n\n    return this.storage.findOne<AuthStepUpChallengeStorageRecord>(\n      this.collectionName,\n      {\n        where: {\n          tokenHash: {\n            operator: \"eq\",\n            value: tokenHash,\n          },\n        },\n      },\n    );\n  }\n\n  private async getPendingContext(\n    challengeToken: string,\n    sessionToken: string,\n  ): Promise<PendingContext> {\n    const challenge = await this.findChallenge(challengeToken);\n\n    if (\n      !challenge ||\n      challenge.consumedAt !== null ||\n      challenge.expiresAt.getTime() <= this.now().getTime()\n    ) {\n      throw new AuthMfaChallengeError();\n    }\n\n    const session = await this.getAuthenticatedSession(sessionToken);\n\n    if (\n      session.id !== challenge.sessionId ||\n      session.userId !== challenge.userId\n    ) {\n      throw new AuthMfaChallengeError();\n    }\n\n    return {\n      challenge,\n      session,\n    };\n  }\n\n  async beginStepUp(input: BeginStepUpInput): Promise<AuthMfaPendingResult> {\n    this.assertInitialized();\n\n    const session = await this.getAuthenticatedSession(input.sessionToken);\n\n    const challenge = await this.mfa.createSignInChallenge({\n      userId: session.userId!,\n      ipAddress: input.ipAddress,\n    });\n\n    if (!challenge) {\n      throw new AuthMfaFactorError(\n        \"An active MFA factor is required for step-up authentication.\",\n      );\n    }\n\n    const now = this.now();\n\n    const record: AuthStepUpChallengeStorageRecord = {\n      id: generateAuthId(\"mfa-step-up\"),\n      challengeId: challenge.challengeId,\n      tokenHash: await hashAuthToken(challenge.challengeToken),\n      userId: session.userId!,\n      sessionId: session.id,\n      expiresAt: challenge.expiresAt,\n      consumedAt: null,\n      createdAt: now,\n      updatedAt: now,\n      revision: 1,\n    };\n\n    try {\n      await this.storage.insert<AuthStepUpChallengeStorageRecord>(\n        this.collectionName,\n        record,\n      );\n    } catch (error) {\n      throw new AuthProviderError(\"Could not persist the step-up challenge.\", {\n        cause: error,\n      });\n    }\n\n    return challenge;\n  }\n\n  async getPendingAuthState(\n    challengeToken: string,\n    sessionToken: string,\n  ): Promise<AuthStepUpPendingState | null> {\n    this.assertInitialized();\n\n    const challenge = await this.findChallenge(challengeToken);\n\n    if (\n      !challenge ||\n      challenge.consumedAt !== null ||\n      challenge.expiresAt.getTime() <= this.now().getTime()\n    ) {\n      return null;\n    }\n\n    let session: SessionRecord;\n\n    try {\n      session = await this.getAuthenticatedSession(sessionToken);\n    } catch {\n      return null;\n    }\n\n    if (\n      session.id !== challenge.sessionId ||\n      session.userId !== challenge.userId\n    ) {\n      return null;\n    }\n\n    const mfaState = await this.mfa.getPendingAuthState(challengeToken);\n\n    if (\n      !mfaState ||\n      mfaState.status !== \"mfa-pending\" ||\n      mfaState.challengeId !== challenge.challengeId\n    ) {\n      return null;\n    }\n\n    return {\n      status: \"step-up-pending\",\n      challengeId: challenge.challengeId,\n      expiresAt: challenge.expiresAt,\n    };\n  }\n\n  async beginPasskey(\n    input: BeginStepUpPasskeyInput,\n  ): Promise<PasskeyMfaStarted> {\n    this.assertInitialized();\n\n    await this.getPendingContext(input.challengeToken, input.sessionToken);\n\n    return this.mfa.beginPasskeyMfa(input.challengeToken, input.ipAddress);\n  }\n\n  private async consumeChallenge(\n    challenge: AuthStepUpChallengeStorageRecord,\n  ): Promise<void> {\n    const now = this.now();\n\n    try {\n      const consumed =\n        await this.storage.update<AuthStepUpChallengeStorageRecord>(\n          this.collectionName,\n          challenge.id,\n          {\n            consumedAt: now,\n            updatedAt: now,\n          },\n          {\n            expectedRevision: challenge.revision,\n          },\n        );\n\n      if (!consumed) {\n        throw new StorageConflictError(\n          \"The step-up challenge was already consumed.\",\n        );\n      }\n    } catch (error) {\n      throw new AuthMfaChallengeError({ cause: error });\n    }\n  }\n\n  private async revokeTemporarySession(sessionId: string): Promise<void> {\n    try {\n      await this.sessions.revoke(sessionId);\n    } catch (error) {\n      throw new AuthSessionError(\n        \"Could not revoke the temporary MFA verification session.\",\n        { cause: error },\n      );\n    }\n  }\n\n  private async completeStepUp(\n    input: {\n      readonly challengeToken: string;\n      readonly sessionToken: string;\n      readonly method: string;\n      readonly ipAddress: string;\n    },\n    verify: MfaVerification,\n  ): Promise<AuthResult> {\n    this.assertInitialized();\n\n    const context = await this.getPendingContext(\n      input.challengeToken,\n      input.sessionToken,\n    );\n\n    // The MFA manager consumes its own challenge and creates a short-lived\n    // internal session after successful factor verification. That token is\n    // never returned to the caller.\n    const verified = await verify(input.challengeToken);\n\n    if (verified.user.id !== context.challenge.userId) {\n      await this.revokeTemporarySession(verified.session.id);\n      throw new AuthMfaChallengeError();\n    }\n\n    // Consume the step-up wrapper challenge before rotating the original\n    // session. Conditional revision checking ensures that concurrent\n    // requests cannot both proceed to session rotation.\n    try {\n      await this.consumeChallenge(context.challenge);\n    } catch (error) {\n      try {\n        await this.revokeTemporarySession(verified.session.id);\n      } catch (revokeError) {\n        throw new AuthSessionError(\n          \"The step-up challenge failed and its temporary session could not be revoked.\",\n          { cause: revokeError },\n        );\n      }\n\n      throw error;\n    }\n\n    const now = this.now();\n\n    let replacement: Awaited<ReturnType<SessionManager[\"rotate\"]>>;\n\n    try {\n      // SessionManager.rotate() atomically inserts the replacement session\n      // and revokes the original session in a single storage batch.\n      replacement = await this.sessions.rotate({\n        sessionId: context.session.id,\n        metadata: {\n          ...(context.session.metadata ?? {}),\n          authenticationMethod: input.method,\n          mfaVerifiedAt: now.toISOString(),\n          stepUpVerifiedAt: now.toISOString(),\n          stepUpOfSessionId: context.session.id,\n        },\n      });\n    } catch (error) {\n      try {\n        await this.revokeTemporarySession(verified.session.id);\n      } catch (revokeError) {\n        throw new AuthSessionError(\n          \"Session rotation failed and the temporary MFA session could not be revoked.\",\n          { cause: revokeError },\n        );\n      }\n\n      throw new AuthSessionError(\n        \"Could not atomically rotate the session after step-up verification.\",\n        { cause: error },\n      );\n    }\n\n    // The temporary session created by the MFA manager is not the session\n    // returned to the application. Revoke it after the original session has\n    // been atomically rotated.\n    try {\n      await this.revokeTemporarySession(verified.session.id);\n    } catch (error) {\n      try {\n        await this.sessions.revoke(replacement.session.id);\n      } catch (revokeError) {\n        throw new AuthSessionError(\n          \"Could not revoke the replacement session after temporary-session cleanup failed.\",\n          { cause: revokeError },\n        );\n      }\n\n      throw error;\n    }\n\n    return {\n      user: verified.user,\n      session: toPublicSession(replacement.session),\n      token: replacement.token,\n    };\n  }\n\n  async verifyTotp(input: CompleteStepUpInput): Promise<AuthResult> {\n    return this.completeStepUp(\n      {\n        ...input,\n        method: \"totp\",\n      },\n      (challengeToken) =>\n        this.mfa.verifySignInTotp({\n          challengeToken,\n          code: input.code,\n          ipAddress: input.ipAddress,\n        }),\n    );\n  }\n\n  async verifyRecoveryCode(input: CompleteStepUpInput): Promise<AuthResult> {\n    return this.completeStepUp(\n      {\n        ...input,\n        method: \"recovery-code\",\n      },\n      (challengeToken) =>\n        this.mfa.verifySignInRecoveryCode({\n          challengeToken,\n          code: input.code,\n          ipAddress: input.ipAddress,\n        }),\n    );\n  }\n\n  async finishPasskey(input: FinishStepUpPasskeyInput): Promise<AuthResult> {\n    await this.getPendingContext(input.challengeToken, input.sessionToken);\n\n    return this.completeStepUp(\n      {\n        challengeToken: input.challengeToken,\n        sessionToken: input.sessionToken,\n        ipAddress: input.ipAddress,\n        method: \"passkey\",\n      },\n      (challengeToken) =>\n        this.mfa.finishPasskeyMfa({\n          challengeToken,\n          response: input.response,\n          ipAddress: input.ipAddress,\n        }),\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/auth.step-up.manager.d.cts

@@ -0,0 +1,74 @@
+import { AuthResult } from "./types/auth-manager.types.cjs";
+import { AuthMfaPendingResult, PasskeyMfaStarted } from "./types/mfa.types.cjs";
+import { StorageAuthMfaManager } from "./auth.mfa.manager.cjs";
+import { StorageAdapter, StorageRecord } from "@puzzle-ui/storage";
+import { SessionManager } from "@puzzle-ui/session";
+export declare const AUTH_MFA_STEP_UP_COLLECTION = "auth_mfa_step_up_challenges";
+export type AuthStepUpChallengeStorageRecord = StorageRecord & {
+  readonly challengeId: string;
+  readonly tokenHash: string;
+  readonly userId: string;
+  readonly sessionId: string;
+  readonly expiresAt: Date;
+  readonly consumedAt: Date | null;
+};
+export type AuthStepUpManagerOptions = {
+  readonly collectionName?: string;
+  readonly clock?: () => Date;
+};
+export type StorageAuthStepUpManagerDependencies = {
+  readonly storage: StorageAdapter;
+  readonly sessions: SessionManager;
+  readonly mfa: StorageAuthMfaManager;
+};
+export type BeginStepUpInput = {
+  readonly sessionToken: string;
+  readonly ipAddress: string;
+};
+export type CompleteStepUpInput = {
+  readonly challengeToken: string;
+  readonly sessionToken: string;
+  readonly code: string;
+  readonly ipAddress: string;
+};
+export type BeginStepUpPasskeyInput = {
+  readonly challengeToken: string;
+  readonly sessionToken: string;
+  readonly ipAddress: string;
+};
+export type FinishStepUpPasskeyInput = {
+  readonly challengeToken: string;
+  readonly sessionToken: string;
+  readonly response: unknown;
+  readonly ipAddress: string;
+};
+export type AuthStepUpPendingState = {
+  readonly status: "step-up-pending";
+  readonly challengeId: string;
+  readonly expiresAt: Date;
+};
+export declare class StorageAuthStepUpManager {
+  private readonly storage;
+  private readonly sessions;
+  private readonly mfa;
+  private readonly collectionName;
+  private readonly clock;
+  private initialized;
+  private initializationPromise;
+  constructor(dependencies: StorageAuthStepUpManagerDependencies, options?: AuthStepUpManagerOptions);
+  initialize(): Promise<void>;
+  private assertInitialized;
+  private now;
+  private getAuthenticatedSession;
+  private findChallenge;
+  private getPendingContext;
+  beginStepUp(input: BeginStepUpInput): Promise<AuthMfaPendingResult>;
+  getPendingAuthState(challengeToken: string, sessionToken: string): Promise<AuthStepUpPendingState | null>;
+  beginPasskey(input: BeginStepUpPasskeyInput): Promise<PasskeyMfaStarted>;
+  private consumeChallenge;
+  private revokeTemporarySession;
+  private completeStepUp;
+  verifyTotp(input: CompleteStepUpInput): Promise<AuthResult>;
+  verifyRecoveryCode(input: CompleteStepUpInput): Promise<AuthResult>;
+  finishPasskey(input: FinishStepUpPasskeyInput): Promise<AuthResult>;
+}

package/dist/auth.step-up.manager.d.ts

@@ -0,0 +1,74 @@
+import { AuthResult } from "./types/auth-manager.types.js";
+import { AuthMfaPendingResult, PasskeyMfaStarted } from "./types/mfa.types.js";
+import { StorageAuthMfaManager } from "./auth.mfa.manager.js";
+import { StorageAdapter, StorageRecord } from "@puzzle-ui/storage";
+import { SessionManager } from "@puzzle-ui/session";
+export declare const AUTH_MFA_STEP_UP_COLLECTION = "auth_mfa_step_up_challenges";
+export type AuthStepUpChallengeStorageRecord = StorageRecord & {
+  readonly challengeId: string;
+  readonly tokenHash: string;
+  readonly userId: string;
+  readonly sessionId: string;
+  readonly expiresAt: Date;
+  readonly consumedAt: Date | null;
+};
+export type AuthStepUpManagerOptions = {
+  readonly collectionName?: string;
+  readonly clock?: () => Date;
+};
+export type StorageAuthStepUpManagerDependencies = {
+  readonly storage: StorageAdapter;
+  readonly sessions: SessionManager;
+  readonly mfa: StorageAuthMfaManager;
+};
+export type BeginStepUpInput = {
+  readonly sessionToken: string;
+  readonly ipAddress: string;
+};
+export type CompleteStepUpInput = {
+  readonly challengeToken: string;
+  readonly sessionToken: string;
+  readonly code: string;
+  readonly ipAddress: string;
+};
+export type BeginStepUpPasskeyInput = {
+  readonly challengeToken: string;
+  readonly sessionToken: string;
+  readonly ipAddress: string;
+};
+export type FinishStepUpPasskeyInput = {
+  readonly challengeToken: string;
+  readonly sessionToken: string;
+  readonly response: unknown;
+  readonly ipAddress: string;
+};
+export type AuthStepUpPendingState = {
+  readonly status: "step-up-pending";
+  readonly challengeId: string;
+  readonly expiresAt: Date;
+};
+export declare class StorageAuthStepUpManager {
+  private readonly storage;
+  private readonly sessions;
+  private readonly mfa;
+  private readonly collectionName;
+  private readonly clock;
+  private initialized;
+  private initializationPromise;
+  constructor(dependencies: StorageAuthStepUpManagerDependencies, options?: AuthStepUpManagerOptions);
+  initialize(): Promise<void>;
+  private assertInitialized;
+  private now;
+  private getAuthenticatedSession;
+  private findChallenge;
+  private getPendingContext;
+  beginStepUp(input: BeginStepUpInput): Promise<AuthMfaPendingResult>;
+  getPendingAuthState(challengeToken: string, sessionToken: string): Promise<AuthStepUpPendingState | null>;
+  beginPasskey(input: BeginStepUpPasskeyInput): Promise<PasskeyMfaStarted>;
+  private consumeChallenge;
+  private revokeTemporarySession;
+  private completeStepUp;
+  verifyTotp(input: CompleteStepUpInput): Promise<AuthResult>;
+  verifyRecoveryCode(input: CompleteStepUpInput): Promise<AuthResult>;
+  finishPasskey(input: FinishStepUpPasskeyInput): Promise<AuthResult>;
+}