@seams/wallet-server 0.5.0

package/dist/esm/router/domains/emailOtp/emailOtpSessionRouteHelpers.js

@@ -0,0 +1,210 @@
+import { parseProviderSubject } from "../../../shared-ts/src/utils/domainIds.js";
+import { base64UrlEncode } from "../../../shared-ts/src/utils/base64.js";
+import { alphabetizeStringify, sha256BytesUtf8 } from "../../../shared-ts/src/utils/digests.js";
+import "../../../shared-ts/src/utils/encoders.js";
+import { normalizeOptionalTrimmedString } from "../../../shared-ts/src/utils/normalize.js";
+import { isPlainObject, toOptionalRecordString } from "../../../shared-ts/src/utils/validation.js";
+import { EMAIL_OTP_CHANNEL } from "../../../shared-ts/src/utils/emailOtpDomain.js";
+//#region src/router/domains/emailOtp/emailOtpSessionRouteHelpers.ts
+const EMAIL_OTP_RESEND_RETRY_AFTER_MS = 1e4;
+function emailOtpRouteValidationError(status, code, message) {
+	return {
+		ok: false,
+		status,
+		body: {
+			ok: false,
+			code,
+			message
+		}
+	};
+}
+function emailOtpStatusCode(code) {
+	if (code === "internal") return 500;
+	if (code === "not_configured") return 503;
+	if (code === "not_found") return 404;
+	if (code === "rate_limited") return 429;
+	if (code === "stronger_auth_required") return 403;
+	if (code === "reenrollment_required" || code === "registration_attempt_missing" || code === "registration_attempt_expired") return 409;
+	if (code === "challenge_id_mismatch" || code === "challenge_purpose_mismatch" || code === "challenge_subject_mismatch" || code === "challenge_email_mismatch" || code === "challenge_wallet_mismatch" || code === "challenge_session_mismatch" || code === "challenge_org_mismatch" || code === "challenge_channel_mismatch" || code === "registration_reroll_disallowed" || code === "challenge_expired_or_invalid" || code === "invalid_otp") return 401;
+	return 400;
+}
+function emailOtpResultStatus(result) {
+	return result.ok ? 200 : emailOtpStatusCode(result.code);
+}
+function emailOtpInternalErrorBody(error) {
+	return {
+		ok: false,
+		code: "internal",
+		message: error instanceof Error ? error.message || "Internal error" : "Internal error"
+	};
+}
+function emailOtpFailureAuditPayload(input) {
+	return {
+		source: input.source,
+		code: input.code,
+		message: input.message,
+		...input.challengeId ? { challengeId: input.challengeId } : {},
+		...input.otpChannel ? { otpChannel: input.otpChannel } : {},
+		...input.operation ? { operation: input.operation } : {},
+		...typeof input.lockedUntilMs === "number" ? { lockedUntilMs: input.lockedUntilMs } : {}
+	};
+}
+function shouldEmitEmailOtpLockedWebhook(code) {
+	return code === "otp_locked_out" || code === "otp_attempts_exhausted";
+}
+function emailOtpFailureWebhookEventDescriptors(input) {
+	const payload = emailOtpFailureAuditPayload(input);
+	const event = {
+		eventType: "wallet.email_otp.failed",
+		...input.challengeId ? { eventId: input.challengeId } : {},
+		payload
+	};
+	if (!shouldEmitEmailOtpLockedWebhook(input.code)) return [event];
+	return [event, {
+		eventType: "wallet.email_otp.locked",
+		...input.challengeId ? { eventId: input.challengeId } : {},
+		payload
+	}];
+}
+function emailOtpLoggedInWebhookEventDescriptor(input) {
+	return {
+		eventType: "wallet.email_otp.logged_in",
+		eventId: input.challengeId,
+		payload: {
+			otpChannel: input.otpChannel,
+			unlockBackend: input.unlockBackend,
+			challengeId: input.challengeId
+		}
+	};
+}
+function emailOtpEnrolledWebhookEventDescriptor(input) {
+	return {
+		eventType: "wallet.email_otp.enrolled",
+		eventId: input.challengeId,
+		payload: {
+			otpChannel: input.otpChannel,
+			enrollmentSealKeyVersion: input.enrollmentSealKeyVersion,
+			unlockKeyVersion: input.unlockKeyVersion
+		}
+	};
+}
+function validateEmailOtpJsonObjectBody(body) {
+	if (!body || typeof body !== "object" || Array.isArray(body)) return emailOtpRouteValidationError(400, "invalid_body", "Expected JSON object body");
+	return {
+		ok: true,
+		body
+	};
+}
+function validateEmailOtpWalletId(input) {
+	const walletId = normalizeOptionalTrimmedString(input.body.walletId) || "";
+	if (!walletId) return emailOtpRouteValidationError(400, "invalid_body", "walletId is required");
+	if (walletId !== getAuthenticatedWalletId(input.claims, input.userId)) return emailOtpRouteValidationError(403, "wallet_identity_mismatch", "walletId must match the authenticated wallet");
+	return {
+		ok: true,
+		walletId
+	};
+}
+function validateEmailOtpChannel(body) {
+	if ((normalizeOptionalTrimmedString(body.otpChannel)?.toLowerCase() || "") !== "email_otp") return emailOtpRouteValidationError(400, "invalid_body", "otpChannel must be email_otp");
+	return {
+		ok: true,
+		otpChannel: EMAIL_OTP_CHANNEL
+	};
+}
+function validateEmailOtpRequiredString(body, field) {
+	const value = normalizeOptionalTrimmedString(body[field]) || "";
+	if (!value) return emailOtpRouteValidationError(400, "invalid_body", `${field} is required`);
+	return {
+		ok: true,
+		value
+	};
+}
+function getAuthenticatedWalletId(claims, userId) {
+	return toOptionalRecordString(claims, "walletId") || normalizeOptionalTrimmedString(userId) || "";
+}
+function isGoogleOidcEmailOtpSession(claims) {
+	if (!isPlainObject(claims)) return false;
+	const authSource = claims.authSource;
+	if (!isPlainObject(authSource) || authSource.kind !== "oidc_provider") return false;
+	if (toOptionalRecordString(authSource, "providerId") !== "google_oidc" || toOptionalRecordString(claims, "provider") !== "oidc" || toOptionalRecordString(claims, "oidcProvider") !== "google") return false;
+	const providerSubject = toOptionalRecordString(claims, "providerSubject");
+	const authSourceProviderSubject = toOptionalRecordString(authSource, "providerSubject");
+	const parsedProviderSubject = parseProviderSubject(providerSubject);
+	return Boolean(parsedProviderSubject.ok && parsedProviderSubject.value.startsWith("google:") && authSourceProviderSubject === parsedProviderSubject.value);
+}
+function parseOidcAccountMode(raw) {
+	const value = normalizeOptionalTrimmedString(raw)?.toLowerCase() || "";
+	if (value === "register" || value === "login") return value;
+}
+async function hashEmailOtpOperationBinding(input) {
+	return base64UrlEncode(await sha256BytesUtf8(alphabetizeStringify({
+		walletId: input.walletId,
+		providerUserId: input.providerUserId,
+		orgId: input.orgId,
+		operation: input.operation,
+		requestOrigin: input.requestOrigin || "",
+		audience: input.audience || "",
+		...input.authorityRef !== void 0 ? { authorityRef: input.authorityRef } : {},
+		...input.operationFingerprintDigest ? { operationFingerprintDigest: input.operationFingerprintDigest } : {}
+	})));
+}
+function emailOtpChallengeResponseBody(result) {
+	if (!result.ok || !result.challenge) return result;
+	const challenge = result.challenge;
+	return {
+		ok: true,
+		challenge: {
+			challengeId: challenge.challengeId,
+			issuedAt: new Date(challenge.issuedAtMs).toISOString(),
+			issuedAtMs: challenge.issuedAtMs,
+			expiresAt: new Date(challenge.expiresAtMs).toISOString(),
+			expiresAtMs: challenge.expiresAtMs,
+			userId: challenge.userId,
+			walletId: challenge.walletId,
+			...challenge.orgId ? { orgId: challenge.orgId } : {},
+			ownerProofBindingDigest: challenge.ownerProofBindingDigest,
+			otpChannel: challenge.otpChannel,
+			action: challenge.action,
+			operation: challenge.operation
+		},
+		delivery: result.delivery,
+		retryAfterMs: typeof result.retryAfterMs === "number" ? result.retryAfterMs : EMAIL_OTP_RESEND_RETRY_AFTER_MS
+	};
+}
+function emailOtpServerSealResponseBody(result, walletId) {
+	if (!result.ok) return result;
+	return {
+		ok: true,
+		walletId,
+		ciphertext: result.ciphertext,
+		enrollmentSealKeyVersion: result.enrollmentSealKeyVersion
+	};
+}
+function emailOtpEnrollmentFinalizeResponseBody(result) {
+	if (!result.ok) return result;
+	return {
+		ok: true,
+		walletId: result.walletId,
+		otpChannel: result.otpChannel,
+		enrollment: {
+			createdAt: new Date(result.enrollment.createdAtMs).toISOString(),
+			updatedAt: new Date(result.enrollment.updatedAtMs).toISOString(),
+			enrollmentSealKeyVersion: result.enrollment.enrollmentSealKeyVersion,
+			unlockKeyVersion: result.enrollment.unlockKeyVersion
+		}
+	};
+}
+function emailOtpLoginVerifyResponseBody(args) {
+	return {
+		ok: true,
+		challengeId: args.result.challengeId,
+		loginGrant: args.result.loginGrant,
+		grantExpiresAt: new Date(args.result.grantExpiresAtMs).toISOString(),
+		otpChannel: args.result.otpChannel,
+		enrollmentSealKeyVersion: args.enrollment.enrollment.enrollmentSealKeyVersion
+	};
+}
+//#endregion
+export { emailOtpChallengeResponseBody, emailOtpEnrolledWebhookEventDescriptor, emailOtpEnrollmentFinalizeResponseBody, emailOtpFailureAuditPayload, emailOtpFailureWebhookEventDescriptors, emailOtpInternalErrorBody, emailOtpLoggedInWebhookEventDescriptor, emailOtpLoginVerifyResponseBody, emailOtpResultStatus, emailOtpServerSealResponseBody, emailOtpStatusCode, getAuthenticatedWalletId, hashEmailOtpOperationBinding, isGoogleOidcEmailOtpSession, parseOidcAccountMode, shouldEmitEmailOtpLockedWebhook, validateEmailOtpChannel, validateEmailOtpJsonObjectBody, validateEmailOtpRequiredString, validateEmailOtpWalletId };
+
+//# sourceMappingURL=emailOtpSessionRouteHelpers.js.map

package/dist/esm/router/domains/passkeyCustody/envelopeRevocationAdmission.js

@@ -0,0 +1,26 @@
+//#region src/router/domains/passkeyCustody/envelopeRevocationAdmission.ts
+function admitEnvelopeRevocation(input) {
+	const envelopeId = String(input.envelopeId || "").trim();
+	if (!envelopeId) return {
+		kind: "refused",
+		reason: "revocation names no envelope"
+	};
+	const target = input.envelopes.find((envelope) => String(envelope.envelopeId) === envelopeId);
+	if (!target) return {
+		kind: "refused",
+		reason: "the wallet has no such envelope"
+	};
+	if (target.lifecycle.state === "revoked") return {
+		kind: "refused",
+		reason: "envelope is already revoked"
+	};
+	if (input.envelopes.filter((envelope) => envelope.lifecycle.state === "active" && String(envelope.envelopeId) !== envelopeId).length === 0) return {
+		kind: "refused",
+		reason: "revoking the last active envelope would leave the wallet custody seed with no factor that can open it"
+	};
+	return { kind: "admitted" };
+}
+//#endregion
+export { admitEnvelopeRevocation };
+
+//# sourceMappingURL=envelopeRevocationAdmission.js.map

package/dist/esm/router/domains/passkeyCustody/passkeyCustodyEnvelopeRetrieval.js

@@ -0,0 +1,107 @@
+import { base64UrlEncode } from "../../../shared-ts/src/utils/base64.js";
+import { isPlainObject } from "../../../shared-ts/src/utils/validation.js";
+import { decodeBase64UrlOrBase64 } from "../../../core/authService/webauthnOidcHelpers.js";
+import { verifyWebAuthnAuthenticationLiteWithStore } from "../../../core/authService/webauthn.js";
+//#region src/router/domains/passkeyCustody/passkeyCustodyEnvelopeRetrieval.ts
+/**
+* Detects any surviving WebAuthn extension output on an assertion.
+*
+* This checks for extension results generally rather than a `prf` key alone: a
+* caller that forwards raw extension outputs is not honouring the redaction
+* contract, and the next extension to carry secret material would otherwise
+* pass unnoticed.
+*/
+function disclosedExtensionOutputs(credential) {
+	const top = credential.clientExtensionResults;
+	if (isPlainObject(top) && Object.keys(top).length > 0) return "webauthn_authentication.clientExtensionResults must be redacted before retrieval";
+	const response = credential.response;
+	if (isPlainObject(response)) {
+		const nested = response.clientExtensionResults;
+		if (isPlainObject(nested) && Object.keys(nested).length > 0) return "webauthn_authentication.response.clientExtensionResults must be redacted before retrieval";
+	}
+	return null;
+}
+function assertionCredentialIdB64u(credential) {
+	const raw = credential.rawId;
+	const fallback = credential.id;
+	const chosen = typeof raw === "string" && raw.trim() ? raw.trim() : typeof fallback === "string" ? fallback.trim() : "";
+	if (!chosen) return null;
+	try {
+		return base64UrlEncode(decodeBase64UrlOrBase64(chosen, "webauthn_authentication.rawId"));
+	} catch {
+		return null;
+	}
+}
+async function retrievePasskeyCustodyEnvelope(input) {
+	const { request } = input;
+	const verifyAssertion = input.verifyAssertion || verifyWebAuthnAuthenticationLiteWithStore;
+	const disclosed = disclosedExtensionOutputs(request.webauthnAuthentication);
+	if (disclosed !== null) {
+		input.logger.error("[passkey-custody] assertion carried unredacted extension output", {
+			walletId: String(request.locator.walletId),
+			rpId: String(request.rpId)
+		});
+		return {
+			kind: "prf_disclosed",
+			message: disclosed
+		};
+	}
+	if (request.locator.factor.kind !== "passkey") return {
+		kind: "assertion_rejected",
+		code: "invalid_body",
+		message: "WebAuthn retrieval serves passkey envelopes only"
+	};
+	if (String(request.locator.factor.rpId) !== String(request.rpId)) return {
+		kind: "assertion_rejected",
+		code: "rp_mismatch",
+		message: "Locator RP ID does not match the assertion RP ID"
+	};
+	const assertedCredentialId = assertionCredentialIdB64u(request.webauthnAuthentication);
+	if (assertedCredentialId === null) return {
+		kind: "assertion_rejected",
+		code: "invalid_body",
+		message: "Missing webauthn_authentication.id/rawId"
+	};
+	if (String(assertedCredentialId) !== String(request.locator.factor.credentialIdB64u)) return { kind: "credential_mismatch" };
+	const verified = await verifyAssertion({
+		userId: request.userId,
+		rpId: request.rpId,
+		expectedChallenge: request.expectedChallenge,
+		expectedOrigin: request.expectedOrigin,
+		webauthnAuthentication: request.webauthnAuthentication,
+		authenticatorStore: input.authenticatorStore,
+		logger: input.logger
+	});
+	if (!verified.success || !verified.verified) return {
+		kind: "assertion_rejected",
+		code: verified.code || "not_verified",
+		message: verified.message || "Authentication verification failed"
+	};
+	const lookup = await input.envelopeStore.lookupEnvelope(request.locator);
+	switch (lookup.kind) {
+		case "active": return {
+			kind: "active",
+			envelope: lookup.envelope,
+			storeVersion: lookup.storeVersion
+		};
+		case "retired": return {
+			kind: "retired",
+			retiredAtMs: lookup.retiredAtMs
+		};
+		case "revoked": return {
+			kind: "revoked",
+			revokedAtMs: lookup.revokedAtMs
+		};
+		case "digest_mismatch":
+			input.logger.error("[passkey-custody] stored envelope failed its ciphertext digest", {
+				walletId: String(request.locator.walletId),
+				envelopeId: String(lookup.envelopeId)
+			});
+			return { kind: "digest_mismatch" };
+		case "missing": return { kind: "missing" };
+	}
+}
+//#endregion
+export { retrievePasskeyCustodyEnvelope };
+
+//# sourceMappingURL=passkeyCustodyEnvelopeRetrieval.js.map

package/dist/esm/router/domains/passkeyCustody/passkeyCustodyEnvelopeRetrievalRoute.js

@@ -0,0 +1,45 @@
+import { retrievePasskeyCustodyEnvelope } from "./passkeyCustodyEnvelopeRetrieval.js";
+//#region src/router/domains/passkeyCustody/passkeyCustodyEnvelopeRetrievalRoute.ts
+async function handlePasskeyCustodyEnvelopeRetrieval(input) {
+	return passkeyCustodyEnvelopeRetrievalRouteResponse(await retrievePasskeyCustodyEnvelope(input));
+}
+/**
+* The wire mapping, exported because it is the part with the decisions.
+*
+* The retrieval it wraps is tested on its own; what belongs here is which
+* status each outcome earns, and that is worth reading and testing without a
+* store, an authenticator, or an assertion.
+*/
+function passkeyCustodyEnvelopeRetrievalRouteResponse(result) {
+	switch (result.kind) {
+		case "active": return {
+			status: 200,
+			body: {
+				ok: true,
+				envelope: result.envelope,
+				storeVersion: result.storeVersion
+			}
+		};
+		case "prf_disclosed": return refusal(400, "prf_disclosed", result.message);
+		case "assertion_rejected": return refusal(401, result.code, result.message);
+		case "credential_mismatch": return refusal(403, "credential_mismatch", "the assertion does not name the credential this envelope is sealed to");
+		case "retired": return refusal(409, "envelope_retired", "this envelope was superseded; unlock with the wallet current credential");
+		case "revoked": return refusal(403, "envelope_revoked", "this credential no longer opens the wallet");
+		case "missing": return refusal(404, "envelope_missing", "no custody envelope for this wallet and credential");
+		case "digest_mismatch": return refusal(500, "envelope_digest_mismatch", "stored custody envelope failed its digest");
+	}
+}
+function refusal(status, code, message) {
+	return {
+		status,
+		body: {
+			ok: false,
+			code,
+			message
+		}
+	};
+}
+//#endregion
+export { handlePasskeyCustodyEnvelopeRetrieval, passkeyCustodyEnvelopeRetrievalRouteResponse };
+
+//# sourceMappingURL=passkeyCustodyEnvelopeRetrievalRoute.js.map

package/dist/esm/router/domains/passkeyCustody/registrationCustodyOutcome.js

@@ -0,0 +1,47 @@
+import { admitWalletCustodyRegistrationCommit } from "./walletCustodyRegistrationAdmission.js";
+import { verifiedCustodyFactorFromAuthority } from "./verifiedCustodyFactor.js";
+//#region src/router/domains/passkeyCustody/registrationCustodyOutcome.ts
+async function commitRegistrationCustody(input) {
+	if (!input.payload) return { status: "not_requested" };
+	const factor = verifiedCustodyFactorFromAuthority({
+		authority: input.verifiedAuthority,
+		...input.verifiedEmailOtpEnrollment ? { emailOtpEnrollment: input.verifiedEmailOtpEnrollment } : {}
+	});
+	if (!factor.ok) return {
+		status: "rejected",
+		reason: factor.reason
+	};
+	try {
+		return toOutcome(await admitWalletCustodyRegistrationCommit({
+			payload: input.payload,
+			verifiedWalletId: input.verifiedWalletId,
+			verifiedFactor: factor.factor,
+			nowMs: input.nowMs,
+			store: input.store
+		}));
+	} catch (error) {
+		return {
+			status: "rejected",
+			reason: error instanceof Error ? error.message : "wallet custody commit failed"
+		};
+	}
+}
+function toOutcome(admitted) {
+	switch (admitted.kind) {
+		case "committed": return { status: "committed" };
+		case "no_custody_records": return {
+			status: "joined",
+			keyManifestDigestB64u: admitted.keyManifestDigestB64u
+		};
+		case "custody_already_established": return { status: "custody_already_established" };
+		case "already_exists": return { status: "committed" };
+		case "rejected": return {
+			status: "rejected",
+			reason: admitted.reason
+		};
+	}
+}
+//#endregion
+export { commitRegistrationCustody };
+
+//# sourceMappingURL=registrationCustodyOutcome.js.map

package/dist/esm/router/domains/passkeyCustody/verifiedCustodyFactor.js

@@ -0,0 +1,46 @@
+import { isEmailOtpWalletAuthAuthority, isPasskeyWalletAuthAuthority } from "../../../shared-ts/src/utils/walletAuthAuthority.js";
+import { buildEmailOtpEnvelopeFactor, buildPasskeyEnvelopeFactor } from "../../../shared-ts/src/passkey-custody/custodyEnvelope.js";
+import "../../../shared-ts/src/passkey-custody/index.js";
+//#region src/router/domains/passkeyCustody/verifiedCustodyFactor.ts
+function verifiedCustodyFactorFromAuthority(input) {
+	const { authority } = input;
+	if (isPasskeyWalletAuthAuthority(authority)) {
+		const rpId = String(authority.verifier.rpId ?? "").trim();
+		const credentialIdB64u = String(authority.factor.credentialIdB64u ?? "").trim();
+		if (!rpId || !credentialIdB64u) return {
+			ok: false,
+			reason: "verified passkey authority is missing its credential identity"
+		};
+		return {
+			ok: true,
+			factor: buildPasskeyEnvelopeFactor({
+				rpId: authority.verifier.rpId,
+				credentialIdB64u: authority.factor.credentialIdB64u
+			})
+		};
+	}
+	if (isEmailOtpWalletAuthAuthority(authority)) {
+		const enrollment = input.emailOtpEnrollment;
+		const enrollmentId = String(enrollment?.enrollmentId ?? "").trim();
+		const enrollmentSealKeyVersion = String(enrollment?.enrollmentSealKeyVersion ?? "").trim();
+		if (!enrollmentId || !enrollmentSealKeyVersion) return {
+			ok: false,
+			reason: "Email OTP custody requires the verified enrollment id and seal key version"
+		};
+		return {
+			ok: true,
+			factor: buildEmailOtpEnvelopeFactor({
+				enrollmentId,
+				enrollmentSealKeyVersion
+			})
+		};
+	}
+	return {
+		ok: false,
+		reason: "unsupported wallet auth authority for custody"
+	};
+}
+//#endregion
+export { verifiedCustodyFactorFromAuthority };
+
+//# sourceMappingURL=verifiedCustodyFactor.js.map

package/dist/esm/router/domains/passkeyCustody/walletCustodyRegistrationAdmission.js

@@ -0,0 +1,32 @@
+import { commitWalletCustodyRegistration } from "./walletCustodyRegistrationCommit.js";
+//#region src/router/domains/passkeyCustody/walletCustodyRegistrationAdmission.ts
+async function admitWalletCustodyRegistrationCommit(input) {
+	const payloadWalletId = String(input.payload.walletId ?? "").trim();
+	if (!payloadWalletId) return {
+		kind: "rejected",
+		reason: "wallet custody commit payload names no wallet"
+	};
+	if (payloadWalletId !== String(input.verifiedWalletId)) return {
+		kind: "rejected",
+		reason: "wallet custody commit payload does not name the registered wallet"
+	};
+	const digest = String(input.payload.keyManifestDigestB64u ?? "").trim();
+	if (!digest) return {
+		kind: "rejected",
+		reason: "wallet custody commit payload carries no manifest digest"
+	};
+	if (!input.payload.establishedCustody) return {
+		kind: "no_custody_records",
+		keyManifestDigestB64u: digest
+	};
+	return await commitWalletCustodyRegistration({
+		payload: input.payload,
+		factor: input.verifiedFactor,
+		nowMs: input.nowMs,
+		store: input.store
+	});
+}
+//#endregion
+export { admitWalletCustodyRegistrationCommit };
+
+//# sourceMappingURL=walletCustodyRegistrationAdmission.js.map