@seams/wallet-server 0.6.2 → 0.7.3

package/dist/esm/router/transport/fetch/routes/passkeyCustody.js

@@ -1,10 +1,11 @@
 import { parseEmailOtpChallengeId, parseOrgId, parseProviderSubject, parseWalletAuthMethodId, parseWalletAuthorityId, parseWalletId, parseWalletRecoveryOperationId, parseWebAuthnCredentialIdB64u, parseWebAuthnRpId } from "../../../../shared-ts/src/utils/domainIds.js";
 import { buildVaultOperationRef, parseAuthFactorId, parseAuthorizationAuditEventId, parseAuthorizationEvidenceId, parseAuthorizationEvidenceSetId, parseAuthorizedOperationId, parseCapabilityId, parseCapabilityOperationId, parseDeviceId, parsePrincipalId, parseTenantId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
-import { base64UrlDecode, base64UrlEncode } from "../../../../shared-ts/src/utils/base64.js";
-import { parseDigestB64u } from "../../../../shared-ts/src/utils/canonicalPrimitives.js";
-import { alphabetizeStringify, sha256BytesUtf8 } from "../../../../shared-ts/src/utils/digests.js";
+import { base64UrlDecode } from "../../../../shared-ts/src/utils/base64.js";
+import { alphabetizeStringify } from "../../../../shared-ts/src/utils/digests.js";
+import { sha256Utf8DigestB64u } from "../../../../shared-ts/src/utils/canonicalPrimitives.js";
 import { buildCapabilityOperationEnvelope, computeCapabilityOperationFingerprintDigest } from "../../../../shared-ts/src/authorization/operationFingerprint.js";
-import "../../../../shared-ts/src/utils/encoders.js";
+import { normalizeOptionalTrimmedString } from "../../../../shared-ts/src/utils/normalize.js";
+import { isPlainObject, requireTrimmedString } from "../../../../shared-ts/src/utils/validation.js";
 import { buildPasskeyWalletAuthAuthority, walletAuthAuthorityRef } from "../../../../shared-ts/src/utils/walletAuthAuthority.js";
 import { parseSessionOrigin, parseVerifiedOwnerProofId } from "../../../../authorization/domain.js";
 import { buildVerifiedWalletOperationEmailOtpFactorResult, buildVerifiedWalletOperationPasskeyFactorResult } from "../../../../authorization/factorEvidence.js";
@@ -19,8 +20,8 @@ import { parseRecoveryCodeReservationId } from "../../../../shared-ts/src/wallet
 import { computeWalletCustodyAdminChallengeDigest } from "../../../../shared-ts/src/authorization/walletCustodyOperation.js";
 import { parseWalletRecoveryTargetV1 } from "../../../../shared-ts/src/wallet-recovery/walletRecoveryTarget.js";
 import { parseWebAuthnAuthenticationCredential } from "../../../auth/webAuthnCredentialCodecs.js";
-import { EMAIL_OTP_CHANNEL, WALLET_EMAIL_OTP_UNLOCK_OPERATION } from "../../../../shared-ts/src/utils/emailOtpDomain.js";
 import { emailOtpStatusCode, hashEmailOtpOperationBinding } from "../../../domains/emailOtp/emailOtpSessionRouteHelpers.js";
+import { EMAIL_OTP_CHANNEL, WALLET_EMAIL_OTP_UNLOCK_OPERATION } from "../../../../shared-ts/src/utils/emailOtpDomain.js";
 import { parseDerivedWalletRecoveryKeyId } from "../../../../shared-ts/src/wallet-recovery/recoveryKeyId.js";
 import { parseWalletRecoverySetRotationWireV1 } from "../../../../shared-ts/src/wallet-recovery/walletRecoveryEnvelopeSet.js";
 import { parseRecoveryCodeLocatorV1 } from "../../../../shared-ts/src/wallet-recovery/recoveryCodeLocator.js";
@@ -52,18 +53,14 @@ const EMAIL_OTP_CHALLENGE_ROUTE_ID = "wallet_custody_email_otp_challenge";
 const ENVELOPE_OWNERSHIP_UPGRADE_ROUTE_ID = "wallet_custody_envelope_ownership_upgrade";
 const CUSTODY_OPERATION_CAPABILITY_ID = "wallet-custody-admin";
 const CUSTODY_PROOF_TTL_MS = 6e4;
-function parseRequiredString(value, field) {
-	if (typeof value !== "string" || !value.trim()) throw new Error(`${field} is required`);
-	return value.trim();
-}
 function requireExactObjectFields(value, fields, label) {
 	const keys = Object.keys(value).sort();
 	const expected = [...fields].sort();
 	if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) throw new Error(`${label} contains unsupported fields`);
 }
 function parseCustodyOwnerProof(value) {
-	if (!isObject(value)) throw new Error("factorProof is required");
-	const kind = trimmed(value.kind);
+	if (!isPlainObject(value)) throw new Error("factorProof is required");
+	const kind = normalizeOptionalTrimmedString(value.kind);
 	if (kind === "passkey") {
 		requireExactObjectFields(value, [
 			"kind",
@@ -77,10 +74,10 @@ function parseCustodyOwnerProof(value) {
 		if (!webauthnAuthentication) throw new Error("factorProof.webauthn_authentication is invalid");
 		return {
 			kind,
-			walletId: parseRequiredString(value.walletId, "factorProof.walletId"),
-			rpId: parseRequiredString(value.rpId, "factorProof.rpId"),
-			credentialIdB64u: parseRequiredString(value.credentialIdB64u, "factorProof.credentialIdB64u"),
-			challenge_digest: parseRequiredString(value.challenge_digest, "factorProof.challenge_digest"),
+			walletId: requireTrimmedString(value.walletId, "factorProof.walletId"),
+			rpId: requireTrimmedString(value.rpId, "factorProof.rpId"),
+			credentialIdB64u: requireTrimmedString(value.credentialIdB64u, "factorProof.credentialIdB64u"),
+			challenge_digest: requireTrimmedString(value.challenge_digest, "factorProof.challenge_digest"),
 			webauthn_authentication: webauthnAuthentication
 		};
 	}
@@ -94,10 +91,10 @@ function parseCustodyOwnerProof(value) {
 		], "factorProof");
 		return {
 			kind,
-			provider_subject_id: parseRequiredString(value.provider_subject_id, "factorProof.provider_subject_id"),
-			challenge_id: parseRequiredString(value.challenge_id, "factorProof.challenge_id"),
-			otp_code: parseRequiredString(value.otp_code, "factorProof.otp_code"),
-			challenge_digest: parseRequiredString(value.challenge_digest, "factorProof.challenge_digest")
+			provider_subject_id: requireTrimmedString(value.provider_subject_id, "factorProof.provider_subject_id"),
+			challenge_id: requireTrimmedString(value.challenge_id, "factorProof.challenge_id"),
+			otp_code: requireTrimmedString(value.otp_code, "factorProof.otp_code"),
+			challenge_digest: requireTrimmedString(value.challenge_digest, "factorProof.challenge_digest")
 		};
 	}
 	throw new Error("factorProof.kind must be passkey or email_otp");
@@ -107,7 +104,7 @@ function parseRequiredAuthorizationValue(parsed) {
 	return parsed.value;
 }
 async function custodyDigest(domain, value) {
-	return parseDigestB64u(base64UrlEncode(await sha256BytesUtf8(`${domain}|${alphabetizeStringify(value)}`)));
+	return sha256Utf8DigestB64u(`${domain}|${alphabetizeStringify(value)}`);
 }
 async function buildWalletCustodyOperation(input) {
 	const tenantId = parseRequiredAuthorizationValue(parseTenantId(input.tenantId));
@@ -147,7 +144,7 @@ async function buildWalletCustodyOperation(input) {
 	};
 }
 async function authorizeWalletCustodyOperation(input) {
-	const requestOrigin = trimmed(input.ctx.request.headers.get("origin"));
+	const requestOrigin = normalizeOptionalTrimmedString(input.ctx.request.headers.get("origin"));
 	if (!requestOrigin) return toCustodyAuthorizationFailure(400, "invalid_origin", "request Origin is required");
 	let origin;
 	let proof;
@@ -322,16 +319,24 @@ async function authorizeWalletCustodyOperation(input) {
 function toCustodyAuthorizationFailure(status, code, message) {
 	return {
 		ok: false,
-		response: toFetchRouteResponse({
-			status,
-			body: {
-				ok: false,
-				code,
-				message
-			}
-		})
+		response: routeErrorResponse(status, code, message)
 	};
 }
+function routeErrorResponse(status, code, message) {
+	return toFetchRouteResponse({
+		status,
+		body: {
+			ok: false,
+			code,
+			message
+		}
+	});
+}
+function matchRoute(ctx, routeId) {
+	const route = findRouteDefinitionById(ctx.routeDefinitions, routeId);
+	if (!route) throw new Error(`Missing route definition for ${routeId}`);
+	return matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname) ? route : null;
+}
 async function completeWalletCustodyOperation(ctx, operation, status, body, result = "succeeded") {
 	const bodyText = JSON.stringify(body);
 	await ctx.service.authorizedOperations.completeAuthorizedOperation({
@@ -350,22 +355,13 @@ async function completeWalletCustodyOperation(ctx, operation, status, body, resu
 	});
 }
 async function handlePasskeyCustody(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, ROUTE_ID)) return null;
 	const request = parseWireRequest(await readJsonObject(ctx.request), ctx.request.headers.get("origin"));
-	if (!request) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "custody retrieval needs a locator, a challenge id, and an assertion"
-		}
-	});
+	if (!request) return routeErrorResponse(400, "invalid_request", "custody retrieval needs a locator, a challenge id, and an assertion");
 	return toFetchRouteResponse(await ctx.service.passkeyCustody.retrieveEnvelope(request));
 }
 function parseWalletCustodyEmailOtpChallengeRequest(value, actualOrigin) {
-	if (!isObject(value)) throw new Error("Email OTP custody challenge body must be an object");
+	if (!isPlainObject(value)) throw new Error("Email OTP custody challenge body must be an object");
 	const keys = Object.keys(value).sort();
 	const expected = [
 		"operation",
@@ -386,7 +382,7 @@ function parseWalletCustodyEmailOtpChallengeRequest(value, actualOrigin) {
 	const providerSubjectId = parseRequiredAuthorizationValue(parseProviderSubject(value.providerSubjectId));
 	const operation = value.operation;
 	if (operation !== "credentials_list" && operation !== "credential_label" && operation !== "recovery_rotate" && operation !== "recovery_read") throw new Error("Email OTP custody challenge operation is invalid");
-	if (!isObject(value.payload)) throw new Error("Email OTP custody challenge payload is invalid");
+	if (!isPlainObject(value.payload)) throw new Error("Email OTP custody challenge payload is invalid");
 	if (value.requestOrigin !== void 0 && value.requestOrigin !== actualOrigin) throw new Error("Email OTP custody challenge requestOrigin does not match Origin");
 	return {
 		walletId,
@@ -398,36 +394,20 @@ function parseWalletCustodyEmailOtpChallengeRequest(value, actualOrigin) {
 }
 /** Issues one operation-bound Email OTP challenge without exposing authority metadata. */
 async function handleWalletCustodyEmailOtpChallenge(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, EMAIL_OTP_CHALLENGE_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${EMAIL_OTP_CHALLENGE_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
-	const originHeader = trimmed(ctx.request.headers.get("origin"));
+	if (!matchRoute(ctx, EMAIL_OTP_CHALLENGE_ROUTE_ID)) return null;
+	const originHeader = normalizeOptionalTrimmedString(ctx.request.headers.get("origin"));
 	let request;
 	try {
 		const origin = parseSessionOrigin(originHeader);
 		request = parseWalletCustodyEmailOtpChallengeRequest(await readJson(ctx.request), origin);
 	} catch (error) {
-		return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "invalid_request",
-				message: error instanceof Error ? error.message : "Email OTP custody challenge is invalid"
-			}
-		});
+		return routeErrorResponse(400, "invalid_request", error instanceof Error ? error.message : "Email OTP custody challenge is invalid");
 	}
 	const active = await ctx.service.walletAuthMethods.resolveActiveEmailOtpAuthorityForVerifiedSubject({
 		walletId: request.walletId,
 		providerUserId: request.providerSubjectId
 	});
-	if (!active.ok) return toFetchRouteResponse({
-		status: 403,
-		body: {
-			ok: false,
-			code: active.code,
-			message: active.message
-		}
-	});
+	if (!active.ok) return routeErrorResponse(403, active.code, active.message);
 	const authoritativeOrgId = parseRequiredAuthorizationValue(parseOrgId(ctx.service.authorizedOperations.tenantId));
 	const challengeDigest = await computeWalletCustodyAdminChallengeDigest(request);
 	const ownerProofBindingDigest = await hashEmailOtpOperationBinding({
@@ -472,18 +452,10 @@ async function handleWalletCustodyEmailOtpChallenge(ctx) {
 }
 /** Lists public passkey envelope identities with their sibling activity rows. */
 async function handleWalletCustodyCredentialsList(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, CREDENTIALS_LIST_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${CREDENTIALS_LIST_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	const route = matchRoute(ctx, CREDENTIALS_LIST_ROUTE_ID);
+	if (!route) return null;
 	const walletId = walletIdFromPath(route.path, ctx.pathname);
-	if (!walletId) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "credential list needs a wallet"
-		}
-	});
+	if (!walletId) return routeErrorResponse(400, "invalid_request", "credential list needs a wallet");
 	const body = await readJsonObject(ctx.request);
 	const authorized = await authorizeWalletCustodyOperation({
 		ctx,
@@ -494,14 +466,7 @@ async function handleWalletCustodyCredentialsList(ctx) {
 	});
 	if (!authorized.ok) return authorized.response;
 	const parsedWalletId = parseWalletId(walletId);
-	if (!parsedWalletId.ok) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "wallet id is invalid"
-		}
-	});
+	if (!parsedWalletId.ok) return routeErrorResponse(400, "invalid_request", "wallet id is invalid");
 	const result = await ctx.service.passkeyCustody.listWalletCredentials({ walletId: parsedWalletId.value });
 	return await completeWalletCustodyOperation(ctx, authorized.operation, 200, {
 		ok: true,
@@ -509,61 +474,32 @@ async function handleWalletCustodyCredentialsList(ctx) {
 	});
 }
 /**
-* Refactor 109C: binds a pre-109C custody envelope to the method that opened it.
+* Binds an unbound custody envelope to the method that opened it.
 *
 * The exact operation credential names the auth method that opened the
 * envelope. Unlock already proved that method, so finishing the ownership
 * upgrade requires no second user assertion.
 */
 async function handleWalletCustodyEnvelopeOwnershipUpgrade(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, ENVELOPE_OWNERSHIP_UPGRADE_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${ENVELOPE_OWNERSHIP_UPGRADE_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	const route = matchRoute(ctx, ENVELOPE_OWNERSHIP_UPGRADE_ROUTE_ID);
+	if (!route) return null;
 	const parsedWalletId = parseWalletId(walletIdFromPath(route.path, ctx.pathname));
-	if (!parsedWalletId.ok) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "wallet id is invalid"
-		}
-	});
+	if (!parsedWalletId.ok) return routeErrorResponse(400, "invalid_request", "wallet id is invalid");
 	const token = extractBearerCredential(ctx.request.headers);
-	if (!token) return toFetchRouteResponse({
-		status: 401,
-		body: {
-			ok: false,
-			code: "unauthorized",
-			message: "No valid Wallet Session"
-		}
-	});
+	if (!token) return routeErrorResponse(401, "unauthorized", "No valid Wallet Session");
 	const exact = await ctx.service.authorizationSessions.readWalletSessionAuthorizationV2ByOperationCredential({
 		tenantId: ctx.service.authorizationSessions.tenantId,
 		token,
 		nowMs: Date.now()
 	});
-	if (!exact || String(exact.authorization.session.walletId) !== String(parsedWalletId.value)) return toFetchRouteResponse({
-		status: 401,
-		body: {
-			ok: false,
-			code: "unauthorized",
-			message: "No valid Wallet Session"
-		}
-	});
+	if (!exact || String(exact.authorization.session.walletId) !== String(parsedWalletId.value)) return routeErrorResponse(401, "unauthorized", "No valid Wallet Session");
 	const walletAuthMethodId = exact.authMethod.walletAuthMethodId;
 	const body = await readJsonObject(ctx.request);
 	let envelope;
 	try {
 		envelope = parsePasskeyCustodyEnvelopeRecord(body?.envelope);
 	} catch (error) {
-		return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "invalid_request",
-				message: error instanceof Error ? error.message : "custody envelope is invalid"
-			}
-		});
+		return routeErrorResponse(400, "invalid_request", error instanceof Error ? error.message : "custody envelope is invalid");
 	}
 	const result = await ctx.service.passkeyCustody.upgradeEnvelopeOwnership({
 		walletId: parsedWalletId.value,
@@ -586,49 +522,20 @@ async function handleWalletCustodyEnvelopeOwnershipUpgrade(ctx) {
 				upgraded: false
 			}
 		});
-		case "not_found": return toFetchRouteResponse({
-			status: 404,
-			body: {
-				ok: false,
-				code: "not_found",
-				message: "no custody envelope to upgrade"
-			}
-		});
-		case "conflict": return toFetchRouteResponse({
-			status: 409,
-			body: {
-				ok: false,
-				code: "conflict",
-				message: result.reason
-			}
-		});
-		case "refused": return toFetchRouteResponse({
-			status: 403,
-			body: {
-				ok: false,
-				code: "forbidden",
-				message: result.reason
-			}
-		});
+		case "not_found": return routeErrorResponse(404, "not_found", "no custody envelope to upgrade");
+		case "conflict": return routeErrorResponse(409, "conflict", result.reason);
+		case "refused": return routeErrorResponse(403, "forbidden", result.reason);
 	}
 }
 /** Renames one passkey credential; the label is metadata and never AAD. */
 async function handleWalletCustodyCredentialLabel(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, CREDENTIAL_LABEL_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${CREDENTIAL_LABEL_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	const route = matchRoute(ctx, CREDENTIAL_LABEL_ROUTE_ID);
+	if (!route) return null;
 	const walletId = walletIdFromPath(route.path, ctx.pathname);
 	const body = await readJsonObject(ctx.request);
-	const envelopeId = trimmed(body?.envelopeId);
+	const envelopeId = normalizeOptionalTrimmedString(body?.envelopeId);
 	const label = body?.label;
-	if (!walletId || !envelopeId || label !== void 0 && typeof label !== "string") return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "credential rename needs a wallet, envelope, and optional label"
-		}
-	});
+	if (!walletId || !envelopeId || label !== void 0 && typeof label !== "string") return routeErrorResponse(400, "invalid_request", "credential rename needs a wallet, envelope, and optional label");
 	const authorized = await authorizeWalletCustodyOperation({
 		ctx,
 		walletId,
@@ -642,14 +549,7 @@ async function handleWalletCustodyCredentialLabel(ctx) {
 	});
 	if (!authorized.ok) return authorized.response;
 	const parsedWalletId = parseWalletId(walletId);
-	if (!parsedWalletId.ok) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "wallet id is invalid"
-		}
-	});
+	if (!parsedWalletId.ok) return routeErrorResponse(400, "invalid_request", "wallet id is invalid");
 	const result = await ctx.service.passkeyCustody.renameWalletCredential({
 		walletId: parsedWalletId.value,
 		envelopeId,
@@ -691,9 +591,7 @@ async function handleWalletCustodyCredentialLabel(ctx) {
 * this must not helpfully re-separate them on the way out.
 */
 async function handleWalletRecoveryPrepare(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_PREPARE_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_PREPARE_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_PREPARE_ROUTE_ID)) return null;
 	const body = await readJsonObject(ctx.request);
 	let parsed;
 	try {
@@ -704,7 +602,7 @@ async function handleWalletRecoveryPrepare(ctx) {
 			"reservationId"
 		], "wallet recovery preparation");
 		const target = parseWalletRecoveryTargetV1(body.target);
-		const recoveryCodeB64u = parseRequiredString(body.recoveryCodeB64u, "recoveryCodeB64u");
+		const recoveryCodeB64u = requireTrimmedString(body.recoveryCodeB64u, "recoveryCodeB64u");
 		if (!/^[A-Za-z0-9_-]+$/.test(recoveryCodeB64u)) throw new Error("wallet recovery preparation is invalid");
 		parsed = {
 			target,
@@ -712,24 +610,10 @@ async function handleWalletRecoveryPrepare(ctx) {
 			reservationId: parseRecoveryCodeReservationId(body.reservationId)
 		};
 	} catch {
-		return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "invalid_request",
-				message: "wallet recovery preparation is invalid"
-			}
-		});
+		return routeErrorResponse(400, "invalid_request", "wallet recovery preparation is invalid");
 	}
-	const origin = trimmed(ctx.request.headers.get("origin"));
-	if (!origin || parsed.target.kind === "passkey" && !isHostWithinRpId(originHostnameOrEmpty(origin), parsed.target.rpId)) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_origin",
-			message: "wallet recovery origin does not match the relying party"
-		}
-	});
+	const origin = normalizeOptionalTrimmedString(ctx.request.headers.get("origin"));
+	if (!origin || parsed.target.kind === "passkey" && !isHostWithinRpId(originHostnameOrEmpty(origin), parsed.target.rpId)) return routeErrorResponse(400, "invalid_origin", "wallet recovery origin does not match the relying party");
 	let recoveryCodeBytes;
 	try {
 		recoveryCodeBytes = base64UrlDecode(parsed.recoveryCodeB64u);
@@ -764,57 +648,27 @@ async function handleWalletRecoveryPrepare(ctx) {
 					storeVersion: result.storeVersion
 				}
 			});
-			case "conflict": return toFetchRouteResponse({
-				status: 409,
-				body: {
-					ok: false,
-					code: "recovery_set_conflict",
-					message: "the recovery set changed during this attempt"
-				}
-			});
+			case "conflict": return routeErrorResponse(409, "recovery_set_conflict", "the recovery set changed during this attempt");
 			case "refused": return toFetchRouteResponse(refusedSpend());
 			case "reserved":
-			case "consumed": return toFetchRouteResponse({
-				status: 401,
-				body: {
-					ok: false,
-					code: "recovery_code_used",
-					message: "that recovery code has already been used"
-				}
-			});
+			case "consumed": return routeErrorResponse(401, "recovery_code_used", "that recovery code has already been used");
 			case "manifest_unavailable":
-			case "registration_unavailable": return toFetchRouteResponse({
-				status: 409,
-				body: {
-					ok: false,
-					code: "recovery_preparation_conflict",
-					message: "wallet recovery could not be prepared"
-				}
-			});
+			case "registration_unavailable": return routeErrorResponse(409, "recovery_preparation_conflict", "wallet recovery could not be prepared");
 		}
 	} finally {
 		recoveryCodeBytes.fill(0);
 	}
 }
 async function handleWalletRecoveryGoogleVerify(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_GOOGLE_VERIFY_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_GOOGLE_VERIFY_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_GOOGLE_VERIFY_ROUTE_ID)) return null;
 	let request;
 	try {
 		request = parseWalletRecoveryGoogleVerifyRequest(await readJsonObject(ctx.request));
 	} catch {
 		return walletRecoveryRequestError();
 	}
-	const requestOrigin = trimmed(ctx.request.headers.get("origin"));
-	if (!requestOrigin) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_origin",
-			message: "wallet recovery origin is required"
-		}
-	});
+	const requestOrigin = normalizeOptionalTrimmedString(ctx.request.headers.get("origin"));
+	if (!requestOrigin) return routeErrorResponse(400, "invalid_origin", "wallet recovery origin is required");
 	try {
 		const result = await ctx.service.passkeyCustody.verifyGoogleRecovery({
 			recoveryOperationId: request.recoveryOperationId,
@@ -840,9 +694,7 @@ async function handleWalletRecoveryGoogleVerify(ctx) {
 	}
 }
 async function handleWalletRecoveryEmailOtpVerify(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_EMAIL_OTP_VERIFY_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_EMAIL_OTP_VERIFY_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_EMAIL_OTP_VERIFY_ROUTE_ID)) return null;
 	let request;
 	try {
 		request = parseWalletRecoveryEmailOtpVerifyRequest(await readJsonObject(ctx.request));
@@ -872,9 +724,7 @@ async function handleWalletRecoveryEmailOtpVerify(ctx) {
 	}
 }
 async function handleWalletRecoveryEmailOtpRelease(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_EMAIL_OTP_RELEASE_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_EMAIL_OTP_RELEASE_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_EMAIL_OTP_RELEASE_ROUTE_ID)) return null;
 	let request;
 	try {
 		request = parseWalletRecoveryEmailOtpReleaseRequest(await readJsonObject(ctx.request));
@@ -931,9 +781,7 @@ async function handleWalletRecoveryEmailOtpRelease(ctx) {
 * server-side; the body can add only a new-enrollment material bundle.
 */
 async function handleWalletRecoveryGoogleEmailOtpFinalize(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_GOOGLE_EMAIL_OTP_FINALIZE_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_GOOGLE_EMAIL_OTP_FINALIZE_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_GOOGLE_EMAIL_OTP_FINALIZE_ROUTE_ID)) return null;
 	let request;
 	try {
 		request = parseWalletRecoveryGoogleEmailOtpFinalizeRequest(await readJson(ctx.request));
@@ -941,43 +789,9 @@ async function handleWalletRecoveryGoogleEmailOtpFinalize(ctx) {
 		return walletRecoveryRequestError();
 	}
 	const finalizer = ctx.service.passkeyCustody.finalizeGoogleEmailOtpRecovery;
-	if (!finalizer) return toFetchRouteResponse({
-		status: 503,
-		body: {
-			ok: false,
-			code: "not_configured",
-			message: "Google Email OTP recovery is not configured"
-		}
-	});
+	if (!finalizer) return routeErrorResponse(503, "not_configured", "Google Email OTP recovery is not configured");
 	try {
-		const result = await finalizer(request);
-		switch (result.kind) {
-			case "promoted": return toFetchRouteResponse({
-				status: 200,
-				body: {
-					ok: true,
-					projection: result.projection
-				}
-			});
-			case "conflict": return toFetchRouteResponse({
-				status: 409,
-				body: {
-					ok: false,
-					code: "recovery_conflict",
-					message: "wallet recovery conflicted"
-				}
-			});
-			case "refused":
-			case "envelope_rejected":
-			case "enrollment_rejected": return toFetchRouteResponse({
-				status: 400,
-				body: {
-					ok: false,
-					code: "recovery_rejected",
-					message: "wallet recovery was rejected"
-				}
-			});
-		}
+		return walletRecoveryFinalizationResponse(await finalizer(request));
 	} catch {
 		return walletRecoveryInternalError();
 	}
@@ -997,7 +811,7 @@ function parseWalletRecoveryGoogleVerifyRequest(body) {
 			"reservationId",
 			"idToken"
 		], "wallet recovery Google verification"),
-		idToken: parseRequiredString(body?.idToken, "idToken")
+		idToken: requireTrimmedString(body?.idToken, "idToken")
 	};
 }
 function parseWalletRecoveryEmailOtpVerifyRequest(body) {
@@ -1009,7 +823,7 @@ function parseWalletRecoveryEmailOtpVerifyRequest(body) {
 			"otpCode"
 		], "wallet recovery Email OTP verification"),
 		challengeId: parseRequiredAuthorizationValue(parseEmailOtpChallengeId(body?.challengeId)),
-		otpCode: parseRequiredString(body?.otpCode, "otpCode")
+		otpCode: requireTrimmedString(body?.otpCode, "otpCode")
 	};
 }
 function parseWalletRecoveryEmailOtpReleaseRequest(body) {
@@ -1019,11 +833,11 @@ function parseWalletRecoveryEmailOtpReleaseRequest(body) {
 			"reservationId",
 			"workerEphemeralPublicKey65B64u"
 		], "wallet recovery Email OTP factor release"),
-		workerEphemeralPublicKey65B64u: parseRequiredString(body?.workerEphemeralPublicKey65B64u, "workerEphemeralPublicKey65B64u")
+		workerEphemeralPublicKey65B64u: requireTrimmedString(body?.workerEphemeralPublicKey65B64u, "workerEphemeralPublicKey65B64u")
 	};
 }
 function parseWalletRecoveryGoogleEmailOtpFinalizeRequest(value) {
-	if (!isObject(value)) throw new Error("wallet recovery Google Email OTP finalization body must be an object");
+	if (!isPlainObject(value)) throw new Error("wallet recovery Google Email OTP finalization body must be an object");
 	const recoveryOperationId = parseWalletRecoveryOperationId(value.recoveryOperationId);
 	if (!recoveryOperationId.ok) throw new Error("wallet recovery Google Email OTP finalization operation is invalid");
 	const reservationId = parseRecoveryCodeReservationId(value.reservationId);
@@ -1062,9 +876,9 @@ function parseWalletRecoveryGoogleEmailOtpFinalizeRequest(value) {
 	};
 }
 function parseWalletRecoveryGoogleEmailOtpCreateEnrollment(value) {
-	if (!isObject(value)) throw new Error("new recovery Email enrollment is invalid");
+	if (!isPlainObject(value)) throw new Error("new recovery Email enrollment is invalid");
 	requireExactObjectFields(value, ["kind", "material"], "new recovery Email enrollment");
-	if (value.kind !== "create" || !isObject(value.material)) throw new Error("new recovery Email enrollment is invalid");
+	if (value.kind !== "create" || !isPlainObject(value.material)) throw new Error("new recovery Email enrollment is invalid");
 	const material = value.material;
 	requireExactObjectFields(material, [
 		"enrollmentSealKeyVersion",
@@ -1075,42 +889,37 @@ function parseWalletRecoveryGoogleEmailOtpCreateEnrollment(value) {
 	return {
 		kind: "create",
 		material: {
-			enrollmentSealKeyVersion: parseRequiredString(material.enrollmentSealKeyVersion, "enrollmentSealKeyVersion"),
-			clientUnlockPublicKeyB64u: parseRequiredString(material.clientUnlockPublicKeyB64u, "clientUnlockPublicKeyB64u"),
-			unlockKeyVersion: parseRequiredString(material.unlockKeyVersion, "unlockKeyVersion"),
-			serverSealedFactorCiphertextB64u: parseRequiredString(material.serverSealedFactorCiphertextB64u, "serverSealedFactorCiphertextB64u")
+			enrollmentSealKeyVersion: requireTrimmedString(material.enrollmentSealKeyVersion, "enrollmentSealKeyVersion"),
+			clientUnlockPublicKeyB64u: requireTrimmedString(material.clientUnlockPublicKeyB64u, "clientUnlockPublicKeyB64u"),
+			unlockKeyVersion: requireTrimmedString(material.unlockKeyVersion, "unlockKeyVersion"),
+			serverSealedFactorCiphertextB64u: requireTrimmedString(material.serverSealedFactorCiphertextB64u, "serverSealedFactorCiphertextB64u")
 		}
 	};
 }
+function walletRecoveryFinalizationResponse(result) {
+	switch (result.kind) {
+		case "promoted": return toFetchRouteResponse({
+			status: 200,
+			body: {
+				ok: true,
+				projection: result.projection
+			}
+		});
+		case "conflict": return routeErrorResponse(409, "recovery_conflict", "wallet recovery conflicted");
+		case "refused":
+		case "envelope_rejected":
+		case "registration_rejected":
+		case "enrollment_rejected": return routeErrorResponse(400, "recovery_rejected", "wallet recovery was rejected");
+	}
+}
 function walletRecoveryRequestError() {
-	return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_body",
-			message: "wallet recovery request is invalid"
-		}
-	});
+	return routeErrorResponse(400, "invalid_body", "wallet recovery request is invalid");
 }
 function walletRecoveryInternalError() {
-	return toFetchRouteResponse({
-		status: 500,
-		body: {
-			ok: false,
-			code: "internal",
-			message: "wallet recovery could not continue"
-		}
-	});
+	return routeErrorResponse(500, "internal", "wallet recovery could not continue");
 }
 function walletRecoveryGoogleFailureResponse(result) {
-	return toFetchRouteResponse({
-		status: walletRecoveryGoogleStatusCode(result.code),
-		body: {
-			ok: false,
-			code: result.code,
-			message: "wallet recovery could not continue"
-		}
-	});
+	return routeErrorResponse(walletRecoveryGoogleStatusCode(result.code), result.code, "wallet recovery could not continue");
 }
 function walletRecoveryGoogleStatusCode(code) {
 	if (code === "internal") return 500;
@@ -1132,11 +941,11 @@ function refusedSpend() {
 }
 function parseWireRequest(body, originHeader) {
 	if (!body || typeof body !== "object") return null;
-	const challengeId = trimmed(body.challengeId);
+	const challengeId = normalizeOptionalTrimmedString(body.challengeId);
 	const locator = parseEnvelopeRetrievalLocator(body.locator);
 	const webauthnAuthentication = parseWebAuthnAuthenticationCredential(body.webauthnAuthentication);
 	if (!challengeId || !locator || !webauthnAuthentication) return null;
-	const expectedOrigin = trimmed(originHeader);
+	const expectedOrigin = normalizeOptionalTrimmedString(originHeader);
 	if (!expectedOrigin) return null;
 	return {
 		challengeId,
@@ -1146,7 +955,7 @@ function parseWireRequest(body, originHeader) {
 	};
 }
 function parseEnvelopeRetrievalLocator(value) {
-	if (!isObject(value) || !isObject(value.factor)) return null;
+	if (!isPlainObject(value) || !isPlainObject(value.factor)) return null;
 	try {
 		requireExactObjectFields(value, ["walletId", "factor"], "custody locator");
 		requireExactObjectFields(value.factor, [
@@ -1171,15 +980,9 @@ function parseEnvelopeRetrievalLocator(value) {
 		}
 	};
 }
-function trimmed(value) {
-	return typeof value === "string" ? value.trim() : "";
-}
 async function readJsonObject(request) {
 	const value = await readJson(request);
-	return isObject(value) ? value : null;
-}
-function isObject(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+	return isPlainObject(value) ? value : null;
 }
 function parseRecoveryCodeLocatorRecords(values, walletId, recoveryKeyIds) {
 	if (values.length !== recoveryKeyIds.length) throw new Error("recovery code locators do not match the recovery wraps");
@@ -1206,33 +1009,17 @@ function parseRecoveryCodeLocatorRecords(values, walletId, recoveryKeyIds) {
 * comes from its signer registry and durable activation receipts.
 */
 async function handleWalletRecoveryFinalize(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_FINALIZE_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_FINALIZE_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_FINALIZE_ROUTE_ID)) return null;
 	let requestBody;
 	try {
 		requestBody = parseWalletRecoveryFinalizeBody(await readJson(ctx.request));
 	} catch {
-		return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "invalid_request",
-				message: "wallet recovery finalization is invalid"
-			}
-		});
+		return routeErrorResponse(400, "invalid_request", "wallet recovery finalization is invalid");
 	}
 	let serviceRequest;
 	if (requestBody.kind === "finalize") {
-		const expectedOrigin = trimmed(ctx.request.headers.get("origin"));
-		if (!expectedOrigin) return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "invalid_origin",
-				message: "wallet recovery finalization requires the request Origin header"
-			}
-		});
+		const expectedOrigin = normalizeOptionalTrimmedString(ctx.request.headers.get("origin"));
+		if (!expectedOrigin) return routeErrorResponse(400, "invalid_origin", "wallet recovery finalization requires the request Origin header");
 		serviceRequest = {
 			kind: "finalize",
 			walletId: requestBody.walletId,
@@ -1259,37 +1046,10 @@ async function handleWalletRecoveryFinalize(ctx) {
 		replacementId: requestBody.replacementId,
 		replacementEnvelope: requestBody.replacementEnvelope
 	};
-	const result = await ctx.service.passkeyCustody.finalizeRecovery(serviceRequest);
-	switch (result.kind) {
-		case "promoted": return toFetchRouteResponse({
-			status: 200,
-			body: {
-				ok: true,
-				projection: result.projection
-			}
-		});
-		case "conflict": return toFetchRouteResponse({
-			status: 409,
-			body: {
-				ok: false,
-				code: "recovery_conflict",
-				message: "wallet recovery conflicted"
-			}
-		});
-		case "refused":
-		case "envelope_rejected":
-		case "registration_rejected": return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "recovery_rejected",
-				message: "wallet recovery was rejected"
-			}
-		});
-	}
+	return walletRecoveryFinalizationResponse(await ctx.service.passkeyCustody.finalizeRecovery(serviceRequest));
 }
 function parseWalletRecoveryFinalizeBody(value) {
-	if (!isObject(value)) throw new Error("wallet recovery finalization body must be an object");
+	if (!isPlainObject(value)) throw new Error("wallet recovery finalization body must be an object");
 	const walletId = parseWalletId(value.walletId);
 	const recoveryOperationId = parseWalletRecoveryOperationId(value.recoveryOperationId);
 	const targetDeviceId = parseDeviceId(value.targetDeviceId);
@@ -1303,7 +1063,7 @@ function parseWalletRecoveryFinalizeBody(value) {
 		targetDeviceId: targetDeviceId.value,
 		targetAuthorityId: targetAuthorityId.value,
 		targetWalletAuthMethodId: targetWalletAuthMethodId.value,
-		replacementId: parseRequiredString(value.replacementId, "replacementId"),
+		replacementId: requireTrimmedString(value.replacementId, "replacementId"),
 		replacementEnvelope: parsePasskeyCustodyEnvelopeRecord(value.replacementEnvelope, "walletRecoveryFinalize.replacementEnvelope")
 	};
 	if (value.kind === "replay") {
@@ -1338,11 +1098,11 @@ function parseWalletRecoveryFinalizeBody(value) {
 		"replacementEnvelope",
 		"ecdsaMaterialPossessionProofs"
 	], "wallet recovery finalization");
-	if (!isObject(value.webauthnRegistration)) throw new Error("wallet recovery finalization registration is invalid");
+	if (!isPlainObject(value.webauthnRegistration)) throw new Error("wallet recovery finalization registration is invalid");
 	return {
 		kind: "finalize",
 		...identity,
-		challengeId: parseRequiredString(value.challengeId, "challengeId"),
+		challengeId: requireTrimmedString(value.challengeId, "challengeId"),
 		webauthnRegistration: value.webauthnRegistration,
 		ecdsaMaterialPossessionProofs: parseEcdsaMaterialPossessionProofs(value.ecdsaMaterialPossessionProofs)
 	};
@@ -1351,9 +1111,9 @@ function parseEcdsaMaterialPossessionProofs(value) {
 	if (!Array.isArray(value)) throw new Error("wallet recovery finalization ECDSA proofs must be an array");
 	const seen = /* @__PURE__ */ new Set();
 	return value.map((item, index) => {
-		if (!isObject(item)) throw new Error(`wallet recovery finalization ECDSA proof ${index} is invalid`);
+		if (!isPlainObject(item)) throw new Error(`wallet recovery finalization ECDSA proof ${index} is invalid`);
 		requireExactObjectFields(item, ["keySetId", "proof"], `ECDSA proof ${index}`);
-		const keySetId = trimmed(item.keySetId);
+		const keySetId = normalizeOptionalTrimmedString(item.keySetId);
 		if (!/^evm_family_ecdsa:\S+$/.test(keySetId)) throw new Error(`wallet recovery finalization ECDSA proof ${index} is invalid`);
 		if (seen.has(keySetId)) throw new Error(`wallet recovery finalization ECDSA proof ${index} is duplicated`);
 		seen.add(keySetId);
@@ -1364,48 +1124,25 @@ function parseEcdsaMaterialPossessionProofs(value) {
 	});
 }
 function authorizedOperationReplay(operation) {
-	if (operation.lifecycle !== "completed") return toFetchRouteResponse({
-		status: 409,
-		body: {
-			ok: false,
-			code: "recovery_in_progress",
-			message: "wallet recovery is still in progress"
-		}
-	});
+	if (operation.lifecycle !== "completed") return routeErrorResponse(409, "recovery_in_progress", "wallet recovery is still in progress");
 	return new Response(operation.response.bodyText, {
 		status: operation.response.status,
 		headers: { "content-type": operation.response.contentType }
 	});
 }
 async function handleWalletRecoveryBackupAcknowledge(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_ACK_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_ACK_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_ACK_ROUTE_ID)) return null;
 	const body = await readJsonObject(ctx.request);
 	let walletId = "";
 	try {
 		if (!body) throw new Error("acknowledgement body is required");
 		requireExactObjectFields(body, ["walletId"], "recovery backup acknowledgement");
-		walletId = parseRequiredString(body.walletId, "walletId");
+		walletId = requireTrimmedString(body.walletId, "walletId");
 	} catch {
-		return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "invalid_request",
-				message: "an acknowledgement needs a wallet"
-			}
-		});
+		return routeErrorResponse(400, "invalid_request", "an acknowledgement needs a wallet");
 	}
 	const result = await ctx.service.passkeyCustody.acknowledgeRecoveryBackup({ walletId });
-	if (result.kind === "no_recovery_set") return toFetchRouteResponse({
-		status: 404,
-		body: {
-			ok: false,
-			code: "no_recovery_set",
-			message: "this wallet has no issued recovery codes to acknowledge"
-		}
-	});
+	if (result.kind === "no_recovery_set") return routeErrorResponse(404, "no_recovery_set", "this wallet has no issued recovery codes to acknowledge");
 	return toFetchRouteResponse({
 		status: 200,
 		body: {
@@ -1424,33 +1161,17 @@ async function handleWalletRecoveryBackupAcknowledge(ctx) {
 * owner wrote down, and nothing surfaces that until someone counts.
 */
 async function handleWalletRecoveryRotate(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_ROTATE_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_ROTATE_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_ROTATE_ROUTE_ID)) return null;
 	const body = await readJsonObject(ctx.request);
-	const walletId = trimmed(body?.walletId);
-	const expectedStoreVersion = trimmed(body?.expectedStoreVersion);
-	const manifestKekWraps = Array.isArray(body?.manifestKekWraps) ? body.manifestKekWraps.filter(isObject) : [];
-	const entries = Array.isArray(body?.entries) ? body.entries.filter(isObject) : [];
+	const walletId = normalizeOptionalTrimmedString(body?.walletId);
+	const expectedStoreVersion = normalizeOptionalTrimmedString(body?.expectedStoreVersion);
+	const manifestKekWraps = Array.isArray(body?.manifestKekWraps) ? body.manifestKekWraps.filter(isPlainObject) : [];
+	const entries = Array.isArray(body?.entries) ? body.entries.filter(isPlainObject) : [];
 	const rawRecoveryCodeLocators = Array.isArray(body?.recoveryCodeLocators) ? body.recoveryCodeLocators : [];
-	const recoveryCodeLocators = rawRecoveryCodeLocators.filter(isObject);
-	if (!walletId || !expectedStoreVersion || manifestKekWraps.length === 0 || entries.length !== 1 || recoveryCodeLocators.length !== rawRecoveryCodeLocators.length || recoveryCodeLocators.length !== manifestKekWraps.length) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "a rotation needs a wallet and its complete replacement recovery set"
-		}
-	});
+	const recoveryCodeLocators = rawRecoveryCodeLocators.filter(isPlainObject);
+	if (!walletId || !expectedStoreVersion || manifestKekWraps.length === 0 || entries.length !== 1 || recoveryCodeLocators.length !== rawRecoveryCodeLocators.length || recoveryCodeLocators.length !== manifestKekWraps.length) return routeErrorResponse(400, "invalid_request", "a rotation needs a wallet and its complete replacement recovery set");
 	const parsedWalletId = parseWalletId(walletId);
-	if (!parsedWalletId.ok) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "wallet id is invalid"
-		}
-	});
+	if (!parsedWalletId.ok) return routeErrorResponse(400, "invalid_request", "wallet id is invalid");
 	let replacement;
 	let parsedRecoveryCodeLocators;
 	try {
@@ -1461,14 +1182,7 @@ async function handleWalletRecoveryRotate(ctx) {
 		}, { expectedWalletId: parsedWalletId.value });
 		parsedRecoveryCodeLocators = parseRecoveryCodeLocatorRecords(recoveryCodeLocators, parsedWalletId.value, replacement.manifestKekWraps.map((wrap) => wrap.recoveryKeyId));
 	} catch (error) {
-		return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "invalid_request",
-				message: error instanceof Error ? error.message : "replacement recovery set is invalid"
-			}
-		});
+		return routeErrorResponse(400, "invalid_request", error instanceof Error ? error.message : "replacement recovery set is invalid");
 	}
 	const authorized = await authorizeWalletCustodyOperation({
 		ctx,
@@ -1514,19 +1228,10 @@ async function handleWalletRecoveryRotate(ctx) {
 	}
 }
 async function handleWalletRecoveryRead(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_READ_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_READ_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	if (!matchRoute(ctx, RECOVERY_READ_ROUTE_ID)) return null;
 	const body = await readJsonObject(ctx.request);
-	const walletId = trimmed(body?.walletId);
-	if (!walletId) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "a read needs a wallet"
-		}
-	});
+	const walletId = normalizeOptionalTrimmedString(body?.walletId);
+	if (!walletId) return routeErrorResponse(400, "invalid_request", "a read needs a wallet");
 	const authorized = await authorizeWalletCustodyOperation({
 		ctx,
 		walletId,
@@ -1558,40 +1263,18 @@ async function handleWalletRecoveryRead(ctx) {
 * useful to someone else.
 */
 async function handleWalletRecoveryStatus(ctx) {
-	const route = findRouteDefinitionById(ctx.routeDefinitions, RECOVERY_STATUS_ROUTE_ID);
-	if (!route) throw new Error(`Missing route definition for ${RECOVERY_STATUS_ROUTE_ID}`);
-	if (!matchesRouteDefinitionRequest(route, ctx.method, ctx.pathname)) return null;
+	const route = matchRoute(ctx, RECOVERY_STATUS_ROUTE_ID);
+	if (!route) return null;
 	const walletId = walletIdFromPath(route.path, ctx.pathname);
-	if (!walletId) return toFetchRouteResponse({
-		status: 400,
-		body: {
-			ok: false,
-			code: "invalid_request",
-			message: "status needs a wallet"
-		}
-	});
-	const origin = trimmed(ctx.request.headers.get("origin"));
+	if (!walletId) return routeErrorResponse(400, "invalid_request", "status needs a wallet");
+	const origin = normalizeOptionalTrimmedString(ctx.request.headers.get("origin"));
 	try {
 		parseSessionOrigin(origin);
 	} catch {
-		return toFetchRouteResponse({
-			status: 400,
-			body: {
-				ok: false,
-				code: "invalid_origin",
-				message: "request Origin is invalid"
-			}
-		});
+		return routeErrorResponse(400, "invalid_origin", "request Origin is invalid");
 	}
 	const result = await ctx.service.passkeyCustody.readRecoveryStatus({ walletId });
-	if (result.kind === "no_recovery_set") return toFetchRouteResponse({
-		status: 404,
-		body: {
-			ok: false,
-			code: "no_recovery_set",
-			message: "this wallet has no recovery codes"
-		}
-	});
+	if (result.kind === "no_recovery_set") return routeErrorResponse(404, "no_recovery_set", "this wallet has no recovery codes");
 	return toFetchRouteResponse({
 		status: 200,
 		body: {