@estifanos-sh/convex-auth 0.0.1-preview.0

package/dist/server/webauthn.js

@@ -0,0 +1,699 @@
+import { LOG_LEVELS } from "../shared/log.js";
+import { ErrorCode } from "../shared/codes.js";
+import { getAuthenticatedUserIdOrNull } from "./identity/claims.js";
+import { requireEnv } from "./env.js";
+import { appUrlFromEnv } from "./url.js";
+import { queueAuthEvent } from "./events.js";
+import { log } from "./log.js";
+import { encodeRefreshToken, refreshTokenExpirationTime } from "./token/refresh.js";
+import { setActiveSpanAttributes } from "./utils/span.js";
+import { buildSessionIdentity, finalizeSessionIssuance, getAuthSessionId, sessionExpirationTime } from "./session/lifecycle.js";
+import { authFlowError } from "../shared/errors.js";
+import { toConvexError } from "./errors.js";
+import { buildKnownSignInIdentityAttributes } from "./telemetry.js";
+import { consumeVerifierById, mutatePasskeyBeginAssertion, mutatePasskeyBeginRegistration, mutatePasskeyBeginSignIn, mutatePasskeyCompleteAssertion, mutatePasskeyCompleteRegistration } from "./component/factor/db.js";
+import { MAX_WEBAUTHN_CREDENTIALS_PER_USER, MAX_WEBAUTHN_CREDENTIAL_ID_LENGTH } from "../shared/webauthn.js";
+import { ConvexError } from "convex/values";
+import { sha256 } from "@oslojs/crypto/sha2";
+import { decodeBase64urlIgnorePadding, encodeBase64urlNoPadding } from "@oslojs/encoding";
+import { decodePKIXECDSASignature, decodeSEC1PublicKey, p256, verifyECDSASignature } from "@oslojs/crypto/ecdsa";
+import { RSAPublicKey, decodePKCS1RSAPublicKey, sha256ObjectIdentifier, verifyRSASSAPKCS1v15Signature } from "@oslojs/crypto/rsa";
+import { decodeCBORToNativeValueNoLeftoverBytes } from "@oslojs/cbor";
+import { COSEKeyType, ClientDataType, coseAlgorithmES256, coseAlgorithmRS256, createAssertionSignatureMessage, parseAttestationObject, parseAuthenticatorData, parseClientDataJSON } from "@oslojs/webauthn";
+
+//#region src/server/webauthn.ts
+/**
+* Server-side WebAuthn ceremony logic.
+*
+* Handles the four phases of the WebAuthn flow:
+* 1. registerOptions — generate PublicKeyCredentialCreationOptions
+* 2. registerVerify — verify attestation and store credential
+* 3. authOptions — generate PublicKeyCredentialRequestOptions
+* 4. authVerify — verify assertion signature and sign in
+*
+* Uses `@oslojs/webauthn` for attestation/assertion parsing and
+* `@oslojs/crypto` for signature verification.
+*
+* @module
+*/
+/**
+* The WebAuthn provider has three single-word flows:
+*
+* - `register` — issue a WebAuthn registration challenge (phase 1).
+* - `signIn`   — issue a WebAuthn authentication challenge (phase 1).
+* - `verify`   — consume the WebAuthn response (phase 2). The server
+*                auto-detects whether this completes a registration
+*                (`attestationObject` present) or a sign-in
+*                (`signature` + `credentialId` present).
+*/
+const WEBAUTHN_FLOWS = [
+	"register",
+	"signIn",
+	"verify"
+];
+const requireStringParam = (value, name) => {
+	if (typeof value !== "string") throw convexError(ErrorCode.INVALID_PARAMETERS, `Missing \`${name}\` parameter.`);
+	return value;
+};
+const convexError = (code, message) => toConvexError(authFlowError(code, message));
+const asConvexError = (error, code, message) => error instanceof ConvexError ? error : error instanceof Error ? toConvexError(authFlowError(code, error.message || message)) : convexError(code, message);
+const logPasskeyError = (err) => log(LOG_LEVELS.ERROR, "passkey error:", err instanceof Error ? err.message : String(err));
+function resolveRpOptions(provider) {
+	try {
+		let appUrl;
+		if (provider.options.rpId === void 0 || provider.options.origin === void 0) try {
+			appUrl = appUrlFromEnv();
+		} catch {
+			throw convexError(ErrorCode.PASSKEY_MISSING_CONFIG, "Passkey provider requires APP_URL env var (your frontend URL) or explicit rpId and origin in the provider config. CONVEX_SITE_URL cannot be used because WebAuthn RP ID must match the frontend domain.");
+		}
+		const appHostname = appUrl ? new URL(appUrl).hostname : void 0;
+		return {
+			rpName: provider.options.rpName ?? appHostname ?? provider.options.rpId ?? "localhost",
+			rpId: provider.options.rpId ?? appHostname ?? "localhost",
+			origin: provider.options.origin ?? appUrl ?? "http://localhost",
+			challengeExpirationMs: provider.options.challengeExpirationMs ?? 3e5,
+			registration: {
+				userVerification: provider.options.registration.userVerification ?? "required",
+				residentKey: provider.options.registration.residentKey ?? "preferred",
+				algorithms: provider.options.registration.algorithms ?? [coseAlgorithmES256, coseAlgorithmRS256],
+				...provider.options.registration.authenticatorAttachment ? { authenticatorAttachment: provider.options.registration.authenticatorAttachment } : {},
+				...provider.options.registration.hints ? { hints: provider.options.registration.hints } : {},
+				...provider.options.registration.attestation ? { attestation: provider.options.registration.attestation } : {}
+			},
+			authentication: {
+				userVerification: provider.options.authentication.userVerification ?? "required",
+				...provider.options.authentication.hints ? { hints: provider.options.authentication.hints } : {}
+			}
+		};
+	} catch (error) {
+		throw asConvexError(error, ErrorCode.PASSKEY_MISSING_CONFIG, "Passkey relying party configuration is invalid.");
+	}
+}
+function verifySameOrigin(clientData) {
+	if (clientData.crossOrigin === true) throw convexError(ErrorCode.PASSKEY_INVALID_CLIENT_DATA, "Cross-origin WebAuthn ceremonies are not supported.");
+	return clientData;
+}
+function verifyClientDataType(clientData, expectedType, label) {
+	if (clientData.type !== expectedType) throw convexError(ErrorCode.PASSKEY_INVALID_CLIENT_DATA, `Invalid client data type: expected ${label}`);
+	return clientData;
+}
+function verifyOrigin(clientData, rp) {
+	const allowed = Array.isArray(rp.origin) ? rp.origin : [rp.origin];
+	if (!allowed.includes(clientData.origin)) throw convexError(ErrorCode.PASSKEY_INVALID_ORIGIN, `Invalid origin: ${clientData.origin}, expected one of: ${allowed.join(", ")}`);
+	return clientData;
+}
+async function verifyAndConsumeChallenge(clientData, ctx, verifierValue) {
+	const challengeHash = encodeBase64urlNoPadding(new Uint8Array(sha256(clientData.challenge)));
+	let doc;
+	try {
+		doc = await consumeVerifierById(ctx, verifierValue, challengeHash);
+	} catch (err) {
+		console.error("[auth] passkey error:", err);
+		throw convexError(ErrorCode.PASSKEY_INVALID_CHALLENGE, "Invalid or expired passkey challenge.");
+	}
+	if (!doc) throw convexError(ErrorCode.PASSKEY_INVALID_CHALLENGE, "Invalid or expired passkey challenge.");
+	return clientData;
+}
+function verifyRpId(authData, rpId) {
+	if (!authData.verifyRelyingPartyIdHash(rpId)) throw convexError(ErrorCode.PASSKEY_RP_MISMATCH, "Relying party ID mismatch.");
+	return authData;
+}
+function verifyUserFlags(authData, userVerification) {
+	if (!authData.userPresent) throw convexError(ErrorCode.PASSKEY_USER_PRESENCE, "User presence flag not set.");
+	if (userVerification === "required" && !authData.userVerified) throw convexError(ErrorCode.PASSKEY_USER_VERIFICATION, "User verification required but not performed.");
+	return authData;
+}
+/** @internal */
+function parseBackupState(authenticatorData) {
+	if (authenticatorData.byteLength < 33) throw convexError(ErrorCode.PASSKEY_INVALID_CLIENT_DATA, "Authenticator data is too short.");
+	const flags = authenticatorData[32];
+	const backupEligible = (flags & 8) !== 0;
+	const backedUp = (flags & 16) !== 0;
+	if (backedUp && !backupEligible) throw convexError(ErrorCode.PASSKEY_INVALID_CLIENT_DATA, "Authenticator backup state is invalid.");
+	return {
+		deviceType: backupEligible ? "multiDevice" : "singleDevice",
+		backedUp
+	};
+}
+function extractAttestationAuthenticatorData(attestationObject) {
+	try {
+		const decoded = decodeCBORToNativeValueNoLeftoverBytes(attestationObject, 4);
+		if (typeof decoded !== "object" || decoded === null || !("authData" in decoded) || !(decoded.authData instanceof Uint8Array)) throw new Error("Invalid or missing authData");
+		return decoded.authData;
+	} catch (error) {
+		throw asConvexError(error, ErrorCode.PASSKEY_INVALID_CLIENT_DATA, "Invalid attestation authenticator data.");
+	}
+}
+/** @internal */
+function validateCredentialAlgorithm(algorithm, configuredAlgorithms) {
+	if (!configuredAlgorithms.includes(algorithm)) throw convexError(ErrorCode.PASSKEY_UNSUPPORTED_ALGORITHM, `Credential algorithm ${algorithm} was not offered by the server.`);
+}
+function resolveWebAuthnDispatch(params) {
+	const flow = params.flow;
+	if (typeof flow === "string" && WEBAUTHN_FLOWS.includes(flow)) return { flow };
+	throw convexError(ErrorCode.PASSKEY_MISSING_FLOW, "Missing `flow` parameter. Expected one of: " + WEBAUTHN_FLOWS.join(", "));
+}
+function requirePasskeyVerifier(verifier) {
+	if (verifier != null) return verifier;
+	throw convexError(ErrorCode.PASSKEY_MISSING_VERIFIER, "Missing verifier for passkey operation.");
+}
+async function requireAuthenticatedUserId(ctx) {
+	try {
+		const userId = await getAuthenticatedUserIdOrNull(ctx);
+		if (userId === null) throw convexError(ErrorCode.PASSKEY_AUTH_REQUIRED, "Sign in first, then add a passkey to your account.");
+		return userId;
+	} catch (err) {
+		console.error("[auth] passkey error:", err);
+		throw convexError(ErrorCode.PASSKEY_AUTH_REQUIRED, "Sign in first, then add a passkey to your account.");
+	}
+}
+function resolveRegistrationPublicKeyBytes(publicKey, algorithm) {
+	if (algorithm === coseAlgorithmES256) {
+		const ec2 = publicKey.ec2();
+		const xBytes = new Uint8Array(32);
+		let vx = ec2.x;
+		for (let i = 31; i >= 0; i--) {
+			xBytes[i] = Number(vx & 255n);
+			vx >>= 8n;
+		}
+		const yBytes = new Uint8Array(32);
+		let vy = ec2.y;
+		for (let i = 31; i >= 0; i--) {
+			yBytes[i] = Number(vy & 255n);
+			vy >>= 8n;
+		}
+		const bytes = new Uint8Array(65);
+		bytes[0] = 4;
+		bytes.set(xBytes, 1);
+		bytes.set(yBytes, 33);
+		return bytes;
+	}
+	if (algorithm === coseAlgorithmRS256) {
+		const rsa = publicKey.rsa();
+		return new RSAPublicKey(rsa.n, rsa.e).encodePKCS1();
+	}
+	throw convexError(ErrorCode.PASSKEY_UNSUPPORTED_ALGORITHM, `Unsupported algorithm: ${algorithm}`);
+}
+function verifyAssertionSignature(passkey, signature, messageHash) {
+	try {
+		if (passkey.algorithm === coseAlgorithmES256) {
+			if (!verifyECDSASignature(decodeSEC1PublicKey(p256, new Uint8Array(passkey.publicKey)), messageHash, decodePKIXECDSASignature(signature))) throw convexError(ErrorCode.PASSKEY_INVALID_SIGNATURE, "Invalid passkey signature.");
+			return;
+		}
+		if (passkey.algorithm === coseAlgorithmRS256) {
+			if (!verifyRSASSAPKCS1v15Signature(decodePKCS1RSAPublicKey(new Uint8Array(passkey.publicKey)), sha256ObjectIdentifier, messageHash, signature)) throw convexError(ErrorCode.PASSKEY_INVALID_SIGNATURE, "Invalid passkey signature.");
+			return;
+		}
+		throw convexError(ErrorCode.PASSKEY_UNSUPPORTED_ALGORITHM, `Unsupported algorithm: ${passkey.algorithm}`);
+	} catch (error) {
+		if (error instanceof ConvexError) throw error;
+		throw convexError(ErrorCode.PASSKEY_INVALID_SIGNATURE, "Invalid passkey signature.");
+	}
+}
+const DUMMY_ES256_PUBLIC_KEY = decodeBase64urlIgnorePadding("BGsX0fLhLEJH-Lzm5WOkQPJ3A32BLeszoPShOUXYmMKWT-NC4v4af5uO5-tKfA-eFivOM1drMV7Oy7ZAaDe_UfU");
+const DUMMY_RS256_PUBLIC_KEY = decodeBase64urlIgnorePadding("MIIBCgKCAQEAxumpcTeR9zlJNbNZinnjj_eb75YcIeNHf92QdRZ86g_wGzz6WW4VmpRSrkMJC1u3EYdN7rRSw1tveNaw7g6NTfaLjJdyrxkpNdx6niAXq8dMHGe5-Y9MyoGNwP0T_c6PrBdu_M-xGEtpDIG9GwNCM9RHsOxcf7PxVaHBZqR_BoWWLTHrVw6weXBYALsp3iz-jFDl5mG7JW9G_sKVr9dV0BAzeNMAKJEAoEO4swJB4qWGhHaSzCyy8YMngsuQrO9L5L_m8dG0GjYjjkV1G2aoRIl8VR7nnJdGFaAlSgqO_icJN6QY3WS2aalDEr1yRx2mjJPRUIr6rZMCfsuyjq1NZwIDAQAB");
+function copyArrayBuffer(bytes) {
+	return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+function signatureIsValid(credential, signature, messageHash) {
+	try {
+		verifyAssertionSignature(credential, signature, messageHash);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/**
+* Perform both supported verification algorithms for real and unknown IDs so
+* the selected algorithm is not a credential-existence timing oracle.
+*/
+function verifyAssertionSignatureUniformly(passkey, signature, messageHash) {
+	const es256Valid = signatureIsValid(passkey?.algorithm === coseAlgorithmES256 ? passkey : {
+		algorithm: coseAlgorithmES256,
+		publicKey: copyArrayBuffer(DUMMY_ES256_PUBLIC_KEY)
+	}, signature, messageHash);
+	const rs256Valid = signatureIsValid(passkey?.algorithm === coseAlgorithmRS256 ? passkey : {
+		algorithm: coseAlgorithmRS256,
+		publicKey: copyArrayBuffer(DUMMY_RS256_PUBLIC_KEY)
+	}, signature, messageHash);
+	if (!(passkey?.algorithm === coseAlgorithmES256 ? es256Valid : passkey?.algorithm === coseAlgorithmRS256 ? rs256Valid : false)) throw convexError(ErrorCode.PASSKEY_INVALID_SIGNATURE, "Invalid passkey signature.");
+}
+/** @internal */
+function validateBackupEligibility(storedDeviceType, assertionDeviceType) {
+	if (storedDeviceType !== assertionDeviceType) throw convexError(ErrorCode.PASSKEY_INVALID_CLIENT_DATA, "Authenticator backup eligibility changed for an existing credential.");
+}
+/** @internal */
+async function assertStoredAttestationTrusted(policy, evidence) {
+	if (!evidence) throw convexError(ErrorCode.PASSKEY_UNTRUSTED_ATTESTATION, "This credential predates the current attestation policy and must be registered again.");
+	try {
+		await policy.verifier.assertTrusted(evidence);
+	} catch (error) {
+		throw asConvexError(error, ErrorCode.PASSKEY_UNTRUSTED_ATTESTATION, "Authenticator attestation is no longer trusted.");
+	}
+}
+const EMAIL_ALLOW_REAL_CREDENTIALS = 32 / 2;
+const MAX_EMAIL_LENGTH = 254;
+async function keyedDigest(key, value) {
+	const encoder = new TextEncoder();
+	return new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(value)));
+}
+async function keyedBytes(key, domain, length) {
+	const blocks = await Promise.all(Array.from({ length: Math.ceil(length / 32) }, (_, block) => keyedDigest(key, `${domain}:block:${block}`)));
+	const bytes = new Uint8Array(length);
+	for (let offset = 0; offset < length; offset += 32) bytes.set(blocks[offset / 32].subarray(0, Math.min(32, length - offset)), offset);
+	return bytes;
+}
+function normalizeEmail(value) {
+	const email = requireStringParam(value, "email").trim().toLowerCase();
+	if (email.length === 0 || email.length > MAX_EMAIL_LENGTH) throw convexError(ErrorCode.INVALID_PARAMETERS, "Email must be between 1 and 254 characters.");
+	return email;
+}
+async function deriveEmailAllowCredentials(normalizedEmail, rpId, realCredentialIds) {
+	const secret = requireEnv("JWT_PRIVATE_KEY");
+	const emailSeed = encodeBase64urlNoPadding(new Uint8Array(sha256(new TextEncoder().encode(normalizedEmail))));
+	const realIds = realCredentialIds.flatMap((id) => {
+		try {
+			const byteLength = decodeBase64urlIgnorePadding(id).byteLength;
+			return byteLength >= 1 && byteLength <= MAX_WEBAUTHN_CREDENTIAL_ID_LENGTH ? [{
+				id,
+				byteLength
+			}] : [];
+		} catch {
+			return [];
+		}
+	}).slice(0, EMAIL_ALLOW_REAL_CREDENTIALS);
+	const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), {
+		name: "HMAC",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+	const makeCredential = async (id, discriminator) => ({
+		type: "public-key",
+		id,
+		order: encodeBase64urlNoPadding(await keyedDigest(key, `convex-auth:webauthn-order:v2:${rpId}:${emailSeed}:${discriminator}:${id}`))
+	});
+	const lengthSeed = await keyedDigest(key, `convex-auth:webauthn-lengths:v2:${rpId}:${emailSeed}`);
+	const credentials = (await Promise.all(Array.from({ length: EMAIL_ALLOW_REAL_CREDENTIALS }, async (_, pairIndex) => {
+		const real = realIds[pairIndex];
+		const derivedLength = 1 + (lengthSeed[pairIndex * 2] << 8 | lengthSeed[pairIndex * 2 + 1]) % MAX_WEBAUTHN_CREDENTIAL_ID_LENGTH;
+		const byteLength = real?.byteLength ?? derivedLength;
+		return [real ? await makeCredential(real.id, `real:${pairIndex}`) : await keyedBytes(key, `convex-auth:webauthn-decoy:v2:${rpId}:${emailSeed}:pair:${pairIndex}:first`, byteLength).then((bytes) => makeCredential(encodeBase64urlNoPadding(bytes), `pair:${pairIndex}:first`)), await keyedBytes(key, `convex-auth:webauthn-decoy:v2:${rpId}:${emailSeed}:pair:${pairIndex}:companion`, byteLength).then((bytes) => makeCredential(encodeBase64urlNoPadding(bytes), `pair:${pairIndex}:companion`))];
+	}))).flat();
+	credentials.sort((a, b) => a.order.localeCompare(b.order));
+	return credentials.map(({ type, id }) => ({
+		type,
+		id
+	}));
+}
+/**
+* Drive the passkey provider's `register` / `signIn` / `verify` flow.
+*
+* Dispatches on `args.params.flow`; for `verify` it auto-detects whether the
+* response completes a registration or a sign-in (see {@link WEBAUTHN_FLOWS}).
+*
+* @param ctx - Auth-enriched action context.
+* @param provider - The resolved WebAuthn provider config.
+* @param args - The flow params and, for `verify`, the issued challenge verifier.
+* @returns A WebAuthn challenge (`webauthnOptions`) or a signed-in session.
+*/
+async function handleWebAuthn(ctx, provider, args) {
+	const params = args.params ?? {};
+	const dispatch = resolveWebAuthnDispatch(params);
+	const handleRegisterVerify = async () => {
+		const userId = await requireAuthenticatedUserId(ctx);
+		const rp = resolveRpOptions(provider);
+		const verifier = requirePasskeyVerifier(args.verifier);
+		const encodedClientDataJSON = requireStringParam(params.clientDataJSON, "clientDataJSON");
+		const clientData = parseClientDataJSON(decodeBase64urlIgnorePadding(encodedClientDataJSON));
+		verifyClientDataType(clientData, ClientDataType.Create, "webauthn.create");
+		verifySameOrigin(clientData);
+		verifyOrigin(clientData, rp);
+		await verifyAndConsumeChallenge(clientData, ctx, verifier);
+		const encodedAttestationObject = requireStringParam(params.attestationObject, "attestationObject");
+		const attestationObjectBytes = decodeBase64urlIgnorePadding(encodedAttestationObject);
+		const rawAuthenticatorData = extractAttestationAuthenticatorData(attestationObjectBytes);
+		const authData = parseAttestationObject(attestationObjectBytes).authenticatorData;
+		verifyRpId(authData, rp.rpId);
+		verifyUserFlags(authData, rp.registration.userVerification);
+		if (authData.credential == null) throw convexError(ErrorCode.PASSKEY_NO_CREDENTIAL, "No credential in attestation.");
+		const credential = authData.credential;
+		if (credential.id.byteLength < 1 || credential.id.byteLength > MAX_WEBAUTHN_CREDENTIAL_ID_LENGTH) throw convexError(ErrorCode.PASSKEY_INVALID_CLIENT_DATA, `Credential ID must be between 1 and ${MAX_WEBAUTHN_CREDENTIAL_ID_LENGTH} bytes.`);
+		const credentialId = encodeBase64urlNoPadding(credential.id);
+		const publicKey = credential.publicKey;
+		const algorithm = publicKey.isAlgorithmDefined() ? publicKey.algorithm() : publicKey.type() === COSEKeyType.EC2 ? coseAlgorithmES256 : publicKey.type() === COSEKeyType.RSA ? coseAlgorithmRS256 : coseAlgorithmES256;
+		validateCredentialAlgorithm(algorithm, rp.registration.algorithms);
+		const publicKeyBytes = resolveRegistrationPublicKeyBytes(publicKey, algorithm);
+		const backupState = parseBackupState(rawAuthenticatorData);
+		let attestationEvidence;
+		if (rp.registration.attestation) {
+			const { verifier: attestationVerifier } = rp.registration.attestation;
+			try {
+				attestationEvidence = {
+					...await attestationVerifier.verify({
+						clientDataJSON: encodedClientDataJSON,
+						attestationObject: encodedAttestationObject,
+						credentialId,
+						transports: params.transports,
+						expectedChallenge: encodeBase64urlNoPadding(clientData.challenge),
+						expectedOrigin: rp.origin,
+						expectedRpId: rp.rpId,
+						requireUserVerification: rp.registration.userVerification === "required",
+						supportedAlgorithms: rp.registration.algorithms
+					}),
+					verifier: attestationVerifier.id,
+					verifiedAt: Date.now(),
+					status: "trusted"
+				};
+			} catch (error) {
+				throw asConvexError(error, ErrorCode.PASSKEY_UNTRUSTED_ATTESTATION, "Authenticator attestation is not trusted.");
+			}
+		}
+		const replaceSessionId = await getAuthSessionId(ctx) ?? void 0;
+		let completed;
+		try {
+			completed = await mutatePasskeyCompleteRegistration(ctx, {
+				userId,
+				credentialId,
+				publicKey: publicKeyBytes.buffer.slice(publicKeyBytes.byteOffset, publicKeyBytes.byteOffset + publicKeyBytes.byteLength),
+				algorithm,
+				counter: authData.signatureCounter,
+				transports: params.transports,
+				deviceType: backupState.deviceType,
+				backedUp: backupState.backedUp,
+				name: params.passkeyName,
+				...attestationEvidence ? { attestation: attestationEvidence } : {},
+				createdAt: Date.now(),
+				replaceSessionId,
+				sessionExpirationTime: sessionExpirationTime(ctx.auth.config),
+				refreshTokenExpirationTime: refreshTokenExpirationTime(ctx.auth.config)
+			});
+			const passkeyId = completed.passkeyId;
+			await queueAuthEvent(ctx, ctx.auth.config, {
+				kind: "passkey.added",
+				actor: {
+					type: "user",
+					id: userId
+				},
+				subject: {
+					type: "passkey",
+					id: passkeyId
+				},
+				targets: [{
+					kind: "user",
+					id: userId
+				}],
+				outcome: "success",
+				data: {
+					passkeyId,
+					credentialId
+				}
+			});
+		} catch (err) {
+			logPasskeyError(err);
+			if (err instanceof ConvexError) throw err;
+			throw convexError(ErrorCode.INTERNAL_ERROR, "An unexpected error occurred.");
+		}
+		const signedInUserId = userId;
+		const sessionId = completed.sessionId;
+		setActiveSpanAttributes({
+			"auth.signin.result": "success",
+			...buildKnownSignInIdentityAttributes(ctx.auth.config, {
+				userId: signedInUserId,
+				sessionId
+			}, completed.user.email)
+		});
+		if (completed.replacedSessionId !== void 0) {
+			const replacedSessionId = completed.replacedSessionId;
+			await queueAuthEvent(ctx, ctx.auth.config, {
+				kind: "session.invalidated",
+				actor: { type: "system" },
+				subject: {
+					type: "session",
+					id: replacedSessionId
+				},
+				targets: [{
+					kind: "user",
+					id: signedInUserId
+				}, {
+					kind: "session",
+					id: replacedSessionId
+				}],
+				outcome: "success",
+				data: {
+					userId: signedInUserId,
+					reason: "replaced"
+				}
+			});
+		}
+		await queueAuthEvent(ctx, ctx.auth.config, {
+			kind: "session.signed_in",
+			actor: {
+				type: "user",
+				id: signedInUserId
+			},
+			subject: {
+				type: "session",
+				id: sessionId
+			},
+			targets: [{
+				kind: "user",
+				id: signedInUserId
+			}, {
+				kind: "session",
+				id: sessionId
+			}],
+			outcome: "success",
+			data: { provider: "session" }
+		});
+		return {
+			kind: "signedIn",
+			session: await finalizeSessionIssuance(ctx.auth.config, {
+				userId: signedInUserId,
+				sessionId,
+				identity: buildSessionIdentity(signedInUserId, sessionId, completed.user),
+				refreshToken: encodeRefreshToken(completed.refreshTokenId, sessionId)
+			})
+		};
+	};
+	const handleAuthVerify = async () => {
+		const rp = resolveRpOptions(provider);
+		const verifier = requirePasskeyVerifier(args.verifier);
+		const clientDataJSON = decodeBase64urlIgnorePadding(requireStringParam(params.clientDataJSON, "clientDataJSON"));
+		const clientData = parseClientDataJSON(clientDataJSON);
+		verifyClientDataType(clientData, ClientDataType.Get, "webauthn.get");
+		verifySameOrigin(clientData);
+		verifyOrigin(clientData, rp);
+		const credentialId = requireStringParam(params.credentialId, "credentialId");
+		const challengeHash = encodeBase64urlNoPadding(new Uint8Array(sha256(clientData.challenge)));
+		let assertion;
+		try {
+			assertion = await mutatePasskeyBeginAssertion(ctx, {
+				verifierId: verifier,
+				expectedChallenge: challengeHash,
+				credentialId
+			});
+		} catch (error) {
+			logPasskeyError(error);
+			throw convexError(ErrorCode.PASSKEY_INVALID_CHALLENGE, "Invalid or expired passkey challenge.");
+		}
+		if (!assertion.verifierAccepted) throw convexError(ErrorCode.PASSKEY_INVALID_CHALLENGE, "Invalid or expired passkey challenge.");
+		const authenticatorDataBytes = decodeBase64urlIgnorePadding(requireStringParam(params.authenticatorData, "authenticatorData"));
+		const authenticatorData = parseAuthenticatorData(authenticatorDataBytes);
+		const backupState = parseBackupState(authenticatorDataBytes);
+		const signatureBytes = decodeBase64urlIgnorePadding(requireStringParam(params.signature, "signature"));
+		const messageHash = sha256(createAssertionSignatureMessage(authenticatorDataBytes, clientDataJSON));
+		verifyRpId(authenticatorData, rp.rpId);
+		verifyUserFlags(authenticatorData, rp.authentication.userVerification);
+		const passkey = assertion.passkey;
+		verifyAssertionSignatureUniformly(passkey, signatureBytes, messageHash);
+		validateBackupEligibility(passkey.deviceType, backupState.deviceType);
+		if (rp.registration.attestation) await assertStoredAttestationTrusted(rp.registration.attestation, passkey.attestation);
+		if ((passkey.counter !== 0 || authenticatorData.signatureCounter !== 0) && authenticatorData.signatureCounter <= passkey.counter) throw convexError(ErrorCode.PASSKEY_COUNTER_ERROR, "Authenticator counter did not increase — possible credential cloning detected.");
+		const replaceSessionId = await getAuthSessionId(ctx) ?? void 0;
+		let completed;
+		try {
+			completed = await mutatePasskeyCompleteAssertion(ctx, {
+				id: passkey._id,
+				counter: authenticatorData.signatureCounter,
+				lastUsedAt: Date.now(),
+				backedUp: backupState.backedUp,
+				replaceSessionId,
+				sessionExpirationTime: sessionExpirationTime(ctx.auth.config),
+				refreshTokenExpirationTime: refreshTokenExpirationTime(ctx.auth.config)
+			});
+		} catch (error) {
+			throw asConvexError(error, ErrorCode.INTERNAL_ERROR, "Failed to finalize passkey sign-in.");
+		}
+		if (completed.status === "rejected") throw convexError(ErrorCode.PASSKEY_COUNTER_ERROR, "Authenticator counter did not increase — possible credential cloning detected.");
+		const userId = completed.user._id;
+		const sessionId = completed.sessionId;
+		setActiveSpanAttributes({
+			"auth.signin.result": "success",
+			...buildKnownSignInIdentityAttributes(ctx.auth.config, {
+				userId,
+				sessionId
+			}, completed.user.email)
+		});
+		if (completed.replacedSessionId !== void 0) {
+			const replacedSessionId = completed.replacedSessionId;
+			await queueAuthEvent(ctx, ctx.auth.config, {
+				kind: "session.invalidated",
+				actor: { type: "system" },
+				subject: {
+					type: "session",
+					id: replacedSessionId
+				},
+				targets: [{
+					kind: "user",
+					id: userId
+				}, {
+					kind: "session",
+					id: replacedSessionId
+				}],
+				outcome: "success",
+				data: {
+					userId,
+					reason: "replaced"
+				}
+			});
+		}
+		await queueAuthEvent(ctx, ctx.auth.config, {
+			kind: "session.signed_in",
+			actor: {
+				type: "user",
+				id: userId
+			},
+			subject: {
+				type: "session",
+				id: sessionId
+			},
+			targets: [{
+				kind: "user",
+				id: userId
+			}, {
+				kind: "session",
+				id: sessionId
+			}],
+			outcome: "success",
+			data: { provider: "session" }
+		});
+		return {
+			kind: "signedIn",
+			session: await finalizeSessionIssuance(ctx.auth.config, {
+				userId,
+				sessionId,
+				identity: buildSessionIdentity(userId, sessionId, completed.user),
+				refreshToken: encodeRefreshToken(completed.refreshTokenId, sessionId)
+			})
+		};
+	};
+	const handler = {
+		register: async () => {
+			const userId = await requireAuthenticatedUserId(ctx);
+			const rp = resolveRpOptions(provider);
+			const challenge = new Uint8Array(32);
+			crypto.getRandomValues(challenge);
+			const challengeHash = encodeBase64urlNoPadding(new Uint8Array(sha256(challenge)));
+			const sessionId = await getAuthSessionId(ctx) ?? void 0;
+			let registration;
+			try {
+				registration = await mutatePasskeyBeginRegistration(ctx, {
+					userId,
+					sessionId,
+					signature: challengeHash,
+					expirationTime: Date.now() + rp.challengeExpirationMs
+				});
+			} catch (err) {
+				logPasskeyError(err);
+				throw convexError(ErrorCode.INTERNAL_ERROR, "An unexpected error occurred.");
+			}
+			const user = registration.user;
+			const userName = params.userName ?? user?.email ?? "user";
+			const userDisplayName = params.userDisplayName ?? user?.name ?? userName;
+			const existing = registration.credentials;
+			if (existing.length >= MAX_WEBAUTHN_CREDENTIALS_PER_USER) throw convexError(ErrorCode.INVALID_PARAMETERS, `A user can register at most ${MAX_WEBAUTHN_CREDENTIALS_PER_USER} WebAuthn credentials.`);
+			const excludeCredentials = existing.map((credential) => ({
+				id: credential.id,
+				transports: credential.transports
+			}));
+			const userHandle = encodeBase64urlNoPadding(new TextEncoder().encode(userId));
+			return {
+				kind: "webauthnOptions",
+				options: {
+					rp: {
+						name: rp.rpName,
+						id: rp.rpId
+					},
+					user: {
+						id: userHandle,
+						name: userName,
+						displayName: userDisplayName
+					},
+					challenge: encodeBase64urlNoPadding(challenge),
+					pubKeyCredParams: rp.registration.algorithms.map((alg) => ({
+						type: "public-key",
+						alg
+					})),
+					timeout: rp.challengeExpirationMs,
+					...rp.registration.hints ? { hints: rp.registration.hints } : {},
+					attestation: rp.registration.attestation?.conveyance ?? "none",
+					authenticatorSelection: {
+						residentKey: rp.registration.residentKey,
+						requireResidentKey: rp.registration.residentKey === "required",
+						userVerification: rp.registration.userVerification,
+						...rp.registration.authenticatorAttachment ? { authenticatorAttachment: rp.registration.authenticatorAttachment } : {}
+					},
+					excludeCredentials
+				},
+				verifier: registration.verifierId
+			};
+		},
+		signIn: async () => {
+			const rp = resolveRpOptions(provider);
+			const challenge = new Uint8Array(32);
+			crypto.getRandomValues(challenge);
+			const challengeHash = encodeBase64urlNoPadding(new Uint8Array(sha256(challenge)));
+			let allowCredentials;
+			const email = params.email === void 0 ? void 0 : normalizeEmail(params.email);
+			const sessionId = await getAuthSessionId(ctx) ?? void 0;
+			let signIn;
+			try {
+				signIn = await mutatePasskeyBeginSignIn(ctx, {
+					sessionId,
+					signature: challengeHash,
+					expirationTime: Date.now() + rp.challengeExpirationMs,
+					...email === void 0 ? {} : { verifiedEmail: email }
+				});
+			} catch (err) {
+				logPasskeyError(err);
+				throw convexError(ErrorCode.INTERNAL_ERROR, "An unexpected error occurred.");
+			}
+			if (email !== void 0) allowCredentials = await deriveEmailAllowCredentials(email, rp.rpId, signIn.credentialIds);
+			const options = {
+				challenge: encodeBase64urlNoPadding(challenge),
+				timeout: rp.challengeExpirationMs,
+				rpId: rp.rpId,
+				userVerification: rp.authentication.userVerification,
+				...rp.authentication.hints ? { hints: rp.authentication.hints } : {}
+			};
+			if (allowCredentials) options.allowCredentials = allowCredentials;
+			return {
+				kind: "webauthnOptions",
+				options,
+				verifier: signIn.verifierId
+			};
+		},
+		verify: async () => {
+			const isRegistration = typeof params.attestationObject === "string" && params.attestationObject.length > 0;
+			const isAuthentication = typeof params.signature === "string" && params.signature.length > 0;
+			if (isRegistration && !isAuthentication) return await handleRegisterVerify();
+			if (isAuthentication && !isRegistration) return await handleAuthVerify();
+			throw convexError(ErrorCode.PASSKEY_INVALID_VERIFY, "`verify` flow requires either `attestationObject` (to complete a `register`) or `signature` + `credentialId` (to complete a `signIn`).");
+		}
+	}[dispatch.flow];
+	if (!handler) throw convexError(ErrorCode.PASSKEY_MISSING_FLOW, `Unknown passkey flow: ${dispatch.flow}`);
+	return handler();
+}
+
+//#endregion
+export { handleWebAuthn };
+//# sourceMappingURL=webauthn.js.map