@seams/wallet-server 0.27.0 → 0.29.0

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

@@ -1,33 +1,30 @@
 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 { normalizeOptionalTrimmedString } from "../../../../shared-ts/src/utils/normalize.js";
 import { isPlainObject, requireTrimmedString } from "../../../../shared-ts/src/utils/validation.js";
-import { buildDelegatedWalletAuthorityV1, buildFullOwnerPermissionsV1, sameDelegatedWalletAuthorityV1 } from "../../../../shared-ts/src/authorization/delegatedAuthority.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 { buildPasskeyWalletAuthAuthority, walletAuthAuthorityRef } from "../../../../shared-ts/src/utils/walletAuthAuthority.js";
-import { parseSessionOrigin, parseVerifiedOwnerProofId } from "../../../../authorization/domain.js";
-import { buildVerifiedWalletOperationEmailOtpFactorResult, buildVerifiedWalletOperationPasskeyFactorResult } from "../../../../authorization/factorEvidence.js";
-import { findRouteDefinitionById, matchesRouteDefinitionRequest } from "../../../framework/routeDefinitions.js";
-import { extractBearerCredential, resolveSourceIpFromFetchHeaders } from "../../../auth/routerApiKeyAuth.js";
+import { requireParsed } from "../../../../shared-ts/src/passkey-custody/primitives.js";
+import { computeWalletOwnerAdminChallengeDigest } from "../../../../shared-ts/src/authorization/walletOwnerOperation.js";
+import { parseDeviceId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
+import { walletAuthAuthorityRef } from "../../../../shared-ts/src/utils/walletAuthAuthority.js";
+import { parseSessionOrigin } from "../../../../authorization/domain.js";
+import { EMAIL_OTP_CHANNEL, WALLET_EMAIL_OTP_UNLOCK_OPERATION } from "../../../../shared-ts/src/utils/emailOtpDomain.js";
+import { parseWebAuthnAuthenticationCredential, unredactedWebAuthnExtensionField } from "../../../auth/webAuthnCredentialCodecs.js";
+import { emailOtpStatusCode, hashEmailOtpOperationBinding } from "../../../domains/emailOtp/emailOtpSessionRouteHelpers.js";
 import { toFetchRouteResponse } from "../../../framework/routeResponses.js";
+import { parseRecoveryBackupAcknowledgementRequest, parseRecoveryStatusRequest, requireExactObjectFields } from "./walletCustodyRequestBoundary.js";
+import { authorizeWalletOwnerOperation, completeWalletOwnerOperation } from "../walletOwnerOperationAuthorization.js";
+import { extractBearerCredential, resolveSourceIpFromFetchHeaders } from "../../../auth/routerApiKeyAuth.js";
+import { readJson } from "../../../framework/http.js";
+import { findRouteDefinitionById, matchesRouteDefinitionRequest } from "../../../framework/routeDefinitions.js";
 import { parsePasskeyCustodyEnvelopeRecord } from "../../../../shared-ts/src/passkey-custody/custodyEnvelope.js";
 import "../../../../shared-ts/src/passkey-custody/index.js";
-import { readJson } from "../../../framework/http.js";
-import { parseWebAuthnAuthenticationCredential, unredactedWebAuthnExtensionField } from "../../../auth/webAuthnCredentialCodecs.js";
-import { parseCustodyOwnerProof, parseRecoveryBackupAcknowledgementRequest, parseRecoveryStatusRequest, requireExactObjectFields } from "./walletCustodyRequestBoundary.js";
-import { isHostWithinRpId, originHostnameOrEmpty } from "../../../../core/authService/webauthnOidcHelpers.js";
+import { parseRecoveryCodeLocatorV1 } from "../../../../shared-ts/src/wallet-recovery/recoveryCodeLocator.js";
 import { parseRecoveryCodeReservationId } from "../../../../shared-ts/src/wallet-recovery/recoveryCodeReservation.js";
-import { computeWalletCustodyAdminChallengeDigest } from "../../../../shared-ts/src/authorization/walletCustodyOperation.js";
-import { parseWalletRecoveryTargetV1 } from "../../../../shared-ts/src/wallet-recovery/walletRecoveryTarget.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";
 import { parseWalletRecoveryEcdsaPossessionProofV1 } from "../../../../shared-ts/src/wallet-recovery/walletRecoveryEcdsaPossession.js";
+import { parseWalletRecoverySetRotationWireV1 } from "../../../../shared-ts/src/wallet-recovery/walletRecoveryEnvelopeSet.js";
+import { parseWalletRecoveryTargetV1 } from "../../../../shared-ts/src/wallet-recovery/walletRecoveryTarget.js";
+import { isHostWithinRpId, originHostnameOrEmpty } from "../../../../core/authService/webauthnOidcHelpers.js";
 //#region src/router/transport/fetch/routes/passkeyCustody.ts
 /**
 * The transport for custody envelope retrieval.
@@ -53,239 +50,6 @@ const RECOVERY_READ_ROUTE_ID = "wallet_recovery_codes_read";
 const RECOVERY_STATUS_ROUTE_ID = "wallet_recovery_status";
 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 hasFullOwnerAuthority(authority) {
-	return sameDelegatedWalletAuthorityV1(buildDelegatedWalletAuthorityV1({ permissions: authority.permissions }), buildDelegatedWalletAuthorityV1({ permissions: buildFullOwnerPermissionsV1() }));
-}
-function parseRequiredAuthorizationValue(parsed) {
-	if (!parsed.ok) throw new Error(parsed.error.message);
-	return parsed.value;
-}
-async function custodyDigest(domain, value) {
-	return sha256Utf8DigestB64u(`${domain}|${alphabetizeStringify(value)}`);
-}
-async function buildWalletCustodyOperation(input) {
-	const tenantId = parseRequiredAuthorizationValue(parseTenantId(input.tenantId));
-	const principalId = parseRequiredAuthorizationValue(parsePrincipalId(input.principalId));
-	const capabilityId = parseRequiredAuthorizationValue(parseCapabilityId(CUSTODY_OPERATION_CAPABILITY_ID));
-	const operationRef = buildVaultOperationRef("vault.reveal");
-	const laneDigest = await custodyDigest("seams:wallet-custody:lane:v1", {
-		capabilityId,
-		operation: input.operation,
-		operationRef
-	});
-	const challengeDigest = await computeWalletCustodyAdminChallengeDigest({
-		walletId: input.walletId,
-		operation: input.operation,
-		payload: input.payload,
-		requestOrigin: input.requestOrigin
-	});
-	const intentDigest = challengeDigest;
-	const displayDigest = await custodyDigest("seams:wallet-custody:display:v1", {
-		walletId: input.walletId,
-		operation: input.operation
-	});
-	return {
-		operation: buildCapabilityOperationEnvelope({
-			tenantId,
-			principalId,
-			capabilityId,
-			operationId: parseRequiredAuthorizationValue(parseCapabilityOperationId(`wallet-custody:${input.operation}:${intentDigest}`)),
-			operation: operationRef,
-			digests: {
-				laneDigest,
-				intentDigest,
-				displayDigest
-			}
-		}),
-		challengeDigest
-	};
-}
-async function authorizeWalletCustodyOperation(input) {
-	const requestOrigin = normalizeOptionalTrimmedString(input.ctx.request.headers.get("origin"));
-	if (!requestOrigin) return toCustodyAuthorizationFailure(400, "invalid_origin", "request Origin is required");
-	let origin;
-	let proof;
-	let walletId;
-	try {
-		origin = parseSessionOrigin(requestOrigin);
-		walletId = parseRequiredAuthorizationValue(parseWalletId(input.walletId));
-		proof = parseCustodyOwnerProof(input.factorProof);
-	} catch (error) {
-		return toCustodyAuthorizationFailure(400, "invalid_owner_proof", error instanceof Error ? error.message : "owner proof is invalid");
-	}
-	if (proof.kind === "passkey" && proof.walletId !== input.walletId) return toCustodyAuthorizationFailure(403, "scope_mismatch", "owner proof wallet differs");
-	let principalId;
-	let factor;
-	let operation;
-	let challengeDigest;
-	try {
-		principalId = proof.kind === "passkey" ? input.walletId : proof.provider_subject_id;
-		const built = await buildWalletCustodyOperation({
-			tenantId: input.ctx.service.authorizedOperations.tenantId,
-			principalId,
-			walletId: input.walletId,
-			operation: input.operation,
-			payload: input.payload,
-			requestOrigin
-		});
-		operation = built.operation;
-		challengeDigest = built.challengeDigest;
-	} catch (error) {
-		return toCustodyAuthorizationFailure(400, "invalid_owner_proof", error instanceof Error ? error.message : "owner proof binding is invalid");
-	}
-	const operationFingerprintDigest = await computeCapabilityOperationFingerprintDigest(operation);
-	const nowMs = Date.now();
-	if (proof.challenge_digest !== String(challengeDigest)) return toCustodyAuthorizationFailure(403, "scope_mismatch", "factor proof challenge does not match the requested operation");
-	if (proof.kind === "passkey") {
-		let authority;
-		try {
-			authority = buildPasskeyWalletAuthAuthority({
-				walletId,
-				rpId: proof.rpId,
-				credentialIdB64u: proof.credentialIdB64u
-			});
-		} catch (error) {
-			return toCustodyAuthorizationFailure(400, "invalid_owner_proof", error instanceof Error ? error.message : "passkey authority is invalid");
-		}
-		const active = await input.ctx.service.walletAuthMethods.resolveActivePasskeyAuthorityForVerifiedCredential({
-			walletId,
-			rpId: authority.verifier.rpId,
-			credentialIdB64u: authority.factor.credentialIdB64u
-		});
-		if (!active.ok) return toCustodyAuthorizationFailure(403, active.code, active.message);
-		if (!hasFullOwnerAuthority(active.walletAuthority)) return toCustodyAuthorizationFailure(403, "forbidden", "Full owner authority is required");
-		const credential = parseWebAuthnAuthenticationCredential(proof.webauthn_authentication);
-		if (!credential) return toCustodyAuthorizationFailure(400, "invalid_owner_proof", "passkey assertion is invalid");
-		if (String(credential.rawId || credential.id).trim() !== authority.factor.credentialIdB64u) return toCustodyAuthorizationFailure(401, "unauthorized", "passkey credential changed");
-		const verified = await input.ctx.service.webAuthn.verifyWebAuthnAuthenticationLite({
-			userId: input.walletId,
-			rpId: authority.verifier.rpId,
-			expectedChallenge: challengeDigest,
-			expected_origin: requestOrigin,
-			webauthn_authentication: credential
-		});
-		if (!verified.success || !verified.verified) return toCustodyAuthorizationFailure(401, verified.code || "not_verified", verified.message || "WebAuthn authentication verification failed");
-		factor = buildVerifiedWalletOperationPasskeyFactorResult({
-			tenantId: operation.tenantId,
-			principalId: operation.principalId,
-			walletId,
-			authorityRef: await walletAuthAuthorityRef({ authority: active.authority }),
-			requestOrigin: origin,
-			audience: origin,
-			factorId: parseRequiredAuthorizationValue(parseAuthFactorId(`passkey:${authority.factor.credentialIdB64u}`)),
-			credentialIdB64u: parseRequiredAuthorizationValue(parseWebAuthnCredentialIdB64u(authority.factor.credentialIdB64u)),
-			assertionDigest: await custodyDigest("seams:wallet-custody:assertion:v1", { credential }),
-			operation,
-			verifiedAtMs: nowMs,
-			expiresAtMs: nowMs + CUSTODY_PROOF_TTL_MS
-		});
-	} else {
-		const providerSubject = parseRequiredAuthorizationValue(parseProviderSubject(proof.provider_subject_id));
-		const orgId = parseRequiredAuthorizationValue(parseOrgId(input.ctx.service.authorizedOperations.tenantId));
-		const active = await input.ctx.service.walletAuthMethods.resolveActiveEmailOtpAuthorityForVerifiedSubject({
-			walletId: input.walletId,
-			providerUserId: proof.provider_subject_id
-		});
-		if (!active.ok) return toCustodyAuthorizationFailure(403, active.code, active.message);
-		const activeAuthorityRef = await walletAuthAuthorityRef({ authority: active.authority });
-		const ownerProofBindingDigest = await hashEmailOtpOperationBinding({
-			walletId: input.walletId,
-			providerUserId: proof.provider_subject_id,
-			orgId,
-			operation: `wallet_custody:${input.operation}`,
-			requestOrigin,
-			audience: requestOrigin,
-			authorityRef: activeAuthorityRef,
-			operationFingerprintDigest: challengeDigest
-		});
-		const verified = await input.ctx.service.emailOtp.verifyEmailOtpChallenge({
-			userId: proof.provider_subject_id,
-			walletId: input.walletId,
-			orgId,
-			challengeId: proof.challenge_id,
-			otpCode: proof.otp_code,
-			otpChannel: EMAIL_OTP_CHANNEL,
-			ownerProofBindingDigest,
-			operation: WALLET_EMAIL_OTP_UNLOCK_OPERATION
-		});
-		if (!verified.ok) return toCustodyAuthorizationFailure(verified.code === "invalid_body" ? 400 : 401, verified.code, verified.message);
-		const consumed = await input.ctx.service.emailOtp.consumeEmailOtpGrant({
-			subject: {
-				kind: "provider_identity",
-				orgId,
-				providerSubject,
-				walletId
-			},
-			loginGrant: verified.loginGrant,
-			otpChannel: EMAIL_OTP_CHANNEL
-		});
-		if (!consumed.ok) return toCustodyAuthorizationFailure(emailOtpStatusCode(consumed.code), consumed.code, consumed.message);
-		factor = buildVerifiedWalletOperationEmailOtpFactorResult({
-			tenantId: operation.tenantId,
-			principalId: operation.principalId,
-			walletId,
-			authorityRef: activeAuthorityRef,
-			requestOrigin: origin,
-			audience: origin,
-			factorId: parseRequiredAuthorizationValue(parseAuthFactorId(`email_otp:${active.authority.factor.provider}:${proof.provider_subject_id}`)),
-			operation,
-			challengeId: parseRequiredAuthorizationValue(parseEmailOtpChallengeId(consumed.challengeId)),
-			verificationReceiptDigest: await custodyDigest("seams:wallet-custody:otp-receipt:v1", {
-				challengeId: consumed.challengeId,
-				operationFingerprintDigest
-			}),
-			verifiedAtMs: nowMs,
-			expiresAtMs: Math.min(nowMs + CUSTODY_PROOF_TTL_MS, verified.grantExpiresAtMs)
-		});
-	}
-	const ownerProof = await input.ctx.service.authorizedOperations.buildVerifiedOwnerProof({
-		purpose: "operation",
-		proofId: parseVerifiedOwnerProofId(`wallet-custody:${operation.operationId}`),
-		factor
-	});
-	if (ownerProof.purpose !== "operation" || ownerProof.operation.operationFingerprintDigest !== operationFingerprintDigest) return toCustodyAuthorizationFailure(403, "owner_proof_rejected", "owner proof binding is invalid");
-	const evidenceSet = await input.ctx.service.authorizedOperations.recordVerifiedWalletOperationFactorEvidenceSet({
-		operation,
-		evidenceId: parseRequiredAuthorizationValue(parseAuthorizationEvidenceId(`wallet-custody:evidence:${operation.operationId}`)),
-		evidenceSetId: parseRequiredAuthorizationValue(parseAuthorizationEvidenceSetId(`wallet-custody:evidence-set:${operation.operationId}`)),
-		factor
-	});
-	const admission = await input.ctx.service.authorizedOperations.admitAuthorizedOperation({ operation: {
-		tenantId: operation.tenantId,
-		authorizedOperationId: parseRequiredAuthorizationValue(parseAuthorizedOperationId(`wallet-custody:authorized:${operation.operationId}`)),
-		auditEventId: parseRequiredAuthorizationValue(parseAuthorizationAuditEventId(`wallet-custody:audit:${operation.operationId}`)),
-		operation,
-		authorization: {
-			kind: "verified_step_up",
-			evidenceSetDigest: evidenceSet.evidenceSetDigest
-		},
-		quota: { kind: "quota_neutral" },
-		claimedAtMs: nowMs
-	} });
-	switch (admission.kind) {
-		case "claimed": return {
-			ok: true,
-			operation: admission.operation
-		};
-		case "replayed":
-		case "operation_in_progress": return {
-			ok: false,
-			response: authorizedOperationReplay(admission.operation)
-		};
-		case "authorization_grant_rejected":
-		case "verified_step_up_rejected":
-		case "wallet_session_quota_exhausted":
-		case "material_mismatch": return toCustodyAuthorizationFailure(403, "owner_proof_rejected", "owner proof was rejected");
-	}
-}
-function toCustodyAuthorizationFailure(status, code, message) {
-	return {
-		ok: false,
-		response: routeErrorResponse(status, code, message)
-	};
-}
 function routeErrorResponse(status, code, message) {
 	return toFetchRouteResponse({
 		status,
@@ -301,23 +65,6 @@ function matchRoute(ctx, 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({
-		operation,
-		result,
-		response: {
-			status,
-			contentType: "application/json",
-			bodyText
-		},
-		completedAtMs: Date.now()
-	});
-	return toFetchRouteResponse({
-		status,
-		body
-	});
-}
 async function handlePasskeyCustody(ctx) {
 	if (!matchRoute(ctx, ROUTE_ID)) return null;
 	const body = await readJsonObject(ctx.request);
@@ -345,8 +92,8 @@ function parseWalletCustodyEmailOtpChallengeRequest(value, actualOrigin) {
 	];
 	const withoutOptional = keys.filter((key) => key !== "requestOrigin");
 	if (withoutOptional.length !== required.length || withoutOptional.some((key, index) => key !== required.slice().sort()[index]) || keys.includes("requestOrigin") && keys.length !== expected.length) throw new Error("Email OTP custody challenge body contains unsupported fields");
-	const walletId = parseRequiredAuthorizationValue(parseWalletId(value.walletId));
-	const providerSubjectId = parseRequiredAuthorizationValue(parseProviderSubject(value.providerSubjectId));
+	const walletId = requireParsed(parseWalletId(value.walletId), "authorization");
+	const providerSubjectId = requireParsed(parseProviderSubject(value.providerSubjectId), "authorization");
 	const operation = value.operation;
 	if (operation !== "credentials_list" && operation !== "credential_label" && operation !== "recovery_rotate" && operation !== "recovery_read" && operation !== "recovery_status" && operation !== "recovery_backup_acknowledge") throw new Error("Email OTP custody challenge operation is invalid");
 	if (!isPlainObject(value.payload)) throw new Error("Email OTP custody challenge payload is invalid");
@@ -375,8 +122,8 @@ async function handleWalletCustodyEmailOtpChallenge(ctx) {
 		providerUserId: request.providerSubjectId
 	});
 	if (!active.ok) return routeErrorResponse(403, active.code, active.message);
-	const authoritativeOrgId = parseRequiredAuthorizationValue(parseOrgId(ctx.service.authorizedOperations.tenantId));
-	const challengeDigest = await computeWalletCustodyAdminChallengeDigest(request);
+	const authoritativeOrgId = requireParsed(parseOrgId(ctx.service.authorizedOperations.tenantId), "authorization");
+	const challengeDigest = await computeWalletOwnerAdminChallengeDigest(request);
 	const ownerProofBindingDigest = await hashEmailOtpOperationBinding({
 		walletId: request.walletId,
 		providerUserId: request.providerSubjectId,
@@ -424,7 +171,7 @@ async function handleWalletCustodyCredentialsList(ctx) {
 	const walletId = walletIdFromPath(route.path, ctx.pathname);
 	if (!walletId) return routeErrorResponse(400, "invalid_request", "credential list needs a wallet");
 	const body = await readJsonObject(ctx.request);
-	const authorized = await authorizeWalletCustodyOperation({
+	const authorized = await authorizeWalletOwnerOperation({
 		ctx,
 		walletId,
 		operation: "credentials_list",
@@ -435,7 +182,7 @@ async function handleWalletCustodyCredentialsList(ctx) {
 	const parsedWalletId = parseWalletId(walletId);
 	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, {
+	return await completeWalletOwnerOperation(ctx, authorized.operation, 200, {
 		ok: true,
 		credentials: result
 	});
@@ -503,7 +250,7 @@ async function handleWalletCustodyCredentialLabel(ctx) {
 	const envelopeId = normalizeOptionalTrimmedString(body?.envelopeId);
 	const label = body?.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({
+	const authorized = await authorizeWalletOwnerOperation({
 		ctx,
 		walletId,
 		operation: "credential_label",
@@ -523,26 +270,26 @@ async function handleWalletCustodyCredentialLabel(ctx) {
 		...label === void 0 ? {} : { label }
 	});
 	switch (result.kind) {
-		case "updated": return await completeWalletCustodyOperation(ctx, authorized.operation, 200, {
+		case "updated": return await completeWalletOwnerOperation(ctx, authorized.operation, 200, {
 			ok: true,
 			credential: result.projection
 		});
-		case "missing": return await completeWalletCustodyOperation(ctx, authorized.operation, 404, {
+		case "missing": return await completeWalletOwnerOperation(ctx, authorized.operation, 404, {
 			ok: false,
 			code: "credential_not_found",
 			message: "credential not found"
 		}, "failed_before_side_effect");
-		case "conflict": return await completeWalletCustodyOperation(ctx, authorized.operation, 409, {
+		case "conflict": return await completeWalletOwnerOperation(ctx, authorized.operation, 409, {
 			ok: false,
 			code: "credential_activity_conflict",
 			message: "credential changed; retry"
 		}, "failed_before_side_effect");
-		case "invalid_envelope_id": return await completeWalletCustodyOperation(ctx, authorized.operation, 400, {
+		case "invalid_envelope_id": return await completeWalletOwnerOperation(ctx, authorized.operation, 400, {
 			ok: false,
 			code: "invalid_envelope_id",
 			message: "credential envelope id is invalid"
 		}, "failed_before_side_effect");
-		case "invalid_label": return await completeWalletCustodyOperation(ctx, authorized.operation, 400, {
+		case "invalid_label": return await completeWalletOwnerOperation(ctx, authorized.operation, 400, {
 			ok: false,
 			code: "invalid_label",
 			message: result.reason
@@ -768,7 +515,7 @@ function parseWalletRecoveryOperationRequest(body, fields, label) {
 	if (!body) throw new Error(`${label} body is required`);
 	requireExactObjectFields(body, fields, label);
 	return {
-		recoveryOperationId: parseRequiredAuthorizationValue(parseWalletRecoveryOperationId(body.recoveryOperationId)),
+		recoveryOperationId: requireParsed(parseWalletRecoveryOperationId(body.recoveryOperationId), "authorization"),
 		reservationId: parseRecoveryCodeReservationId(body.reservationId)
 	};
 }
@@ -790,7 +537,7 @@ function parseWalletRecoveryEmailOtpVerifyRequest(body) {
 			"challengeId",
 			"otpCode"
 		], "wallet recovery Email OTP verification"),
-		challengeId: parseRequiredAuthorizationValue(parseEmailOtpChallengeId(body?.challengeId)),
+		challengeId: requireParsed(parseEmailOtpChallengeId(body?.challengeId), "authorization"),
 		otpCode: requireTrimmedString(body?.otpCode, "otpCode")
 	};
 }
@@ -1093,13 +840,6 @@ function parseEcdsaMaterialPossessionProofs(value) {
 		};
 	});
 }
-function authorizedOperationReplay(operation) {
-	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) {
 	if (!matchRoute(ctx, RECOVERY_ACK_ROUTE_ID)) return null;
 	let request;
@@ -1108,7 +848,7 @@ async function handleWalletRecoveryBackupAcknowledge(ctx) {
 	} catch {
 		return routeErrorResponse(400, "invalid_request", "acknowledgement body is invalid");
 	}
-	const authorized = await authorizeWalletCustodyOperation({
+	const authorized = await authorizeWalletOwnerOperation({
 		ctx,
 		walletId: request.walletId,
 		operation: "recovery_backup_acknowledge",
@@ -1124,17 +864,17 @@ async function handleWalletRecoveryBackupAcknowledge(ctx) {
 		walletId: request.walletId,
 		expectedIssuedAtMs: request.expectedIssuedAtMs
 	});
-	if (result.kind === "conflict") return await completeWalletCustodyOperation(ctx, authorized.operation, 409, {
+	if (result.kind === "conflict") return await completeWalletOwnerOperation(ctx, authorized.operation, 409, {
 		ok: false,
 		code: "recovery_set_conflict",
 		message: "the recovery set changed"
 	}, "failed_before_side_effect");
-	if (result.kind === "no_recovery_set") return await completeWalletCustodyOperation(ctx, authorized.operation, 404, {
+	if (result.kind === "no_recovery_set") return await completeWalletOwnerOperation(ctx, authorized.operation, 404, {
 		ok: false,
 		code: "no_recovery_set",
 		message: "this wallet has no issued recovery codes to acknowledge"
 	}, "failed_before_side_effect");
-	return await completeWalletCustodyOperation(ctx, authorized.operation, 200, {
+	return await completeWalletOwnerOperation(ctx, authorized.operation, 200, {
 		ok: true,
 		issuedAtMs: result.issuedAtMs
 	});
@@ -1172,7 +912,7 @@ async function handleWalletRecoveryRotate(ctx) {
 	} catch (error) {
 		return routeErrorResponse(400, "invalid_request", error instanceof Error ? error.message : "replacement recovery set is invalid");
 	}
-	const authorized = await authorizeWalletCustodyOperation({
+	const authorized = await authorizeWalletOwnerOperation({
 		ctx,
 		walletId,
 		operation: "recovery_rotate",
@@ -1193,22 +933,22 @@ async function handleWalletRecoveryRotate(ctx) {
 		expectedStoreVersion
 	});
 	switch (result.kind) {
-		case "rotated": return await completeWalletCustodyOperation(ctx, authorized.operation, 200, {
+		case "rotated": return await completeWalletOwnerOperation(ctx, authorized.operation, 200, {
 			ok: true,
 			issuedAtMs: result.issuedAtMs,
 			storeVersion: result.storeVersion
 		});
-		case "no_recovery_set": return await completeWalletCustodyOperation(ctx, authorized.operation, 404, {
+		case "no_recovery_set": return await completeWalletOwnerOperation(ctx, authorized.operation, 404, {
 			ok: false,
 			code: "no_recovery_set",
 			message: "this wallet has no codes to rotate"
 		}, "failed_before_side_effect");
-		case "conflict": return await completeWalletCustodyOperation(ctx, authorized.operation, 409, {
+		case "conflict": return await completeWalletOwnerOperation(ctx, authorized.operation, 409, {
 			ok: false,
 			code: "recovery_set_conflict",
 			message: "the recovery set changed during this rotation; try again"
 		}, "failed_before_side_effect");
-		case "rejected": return await completeWalletCustodyOperation(ctx, authorized.operation, 400, {
+		case "rejected": return await completeWalletOwnerOperation(ctx, authorized.operation, 400, {
 			ok: false,
 			code: "rotation_rejected",
 			message: result.reason
@@ -1220,7 +960,7 @@ async function handleWalletRecoveryRead(ctx) {
 	const body = await readJsonObject(ctx.request);
 	const walletId = normalizeOptionalTrimmedString(body?.walletId);
 	if (!walletId) return routeErrorResponse(400, "invalid_request", "a read needs a wallet");
-	const authorized = await authorizeWalletCustodyOperation({
+	const authorized = await authorizeWalletOwnerOperation({
 		ctx,
 		walletId,
 		operation: "recovery_read",
@@ -1229,12 +969,12 @@ async function handleWalletRecoveryRead(ctx) {
 	});
 	if (!authorized.ok) return authorized.response;
 	const result = await ctx.service.passkeyCustody.readRecoverySet({ walletId });
-	if (result.kind === "no_recovery_set") return await completeWalletCustodyOperation(ctx, authorized.operation, 404, {
+	if (result.kind === "no_recovery_set") return await completeWalletOwnerOperation(ctx, authorized.operation, 404, {
 		ok: false,
 		code: "no_recovery_set",
 		message: "this wallet has no issued recovery codes"
 	}, "failed_before_side_effect");
-	return await completeWalletCustodyOperation(ctx, authorized.operation, 200, {
+	return await completeWalletOwnerOperation(ctx, authorized.operation, 200, {
 		ok: true,
 		recoverySet: result.record,
 		storeVersion: result.storeVersion
@@ -1252,7 +992,7 @@ async function handleWalletRecoveryStatus(ctx) {
 	} catch {
 		return routeErrorResponse(400, "invalid_request", "status body is invalid");
 	}
-	const authorized = await authorizeWalletCustodyOperation({
+	const authorized = await authorizeWalletOwnerOperation({
 		ctx,
 		walletId,
 		operation: "recovery_status",
@@ -1264,12 +1004,12 @@ async function handleWalletRecoveryStatus(ctx) {
 	});
 	if (!authorized.ok) return authorized.response;
 	const result = await ctx.service.passkeyCustody.readRecoveryStatus({ walletId });
-	if (result.kind === "no_recovery_set") return await completeWalletCustodyOperation(ctx, authorized.operation, 404, {
+	if (result.kind === "no_recovery_set") return await completeWalletOwnerOperation(ctx, authorized.operation, 404, {
 		ok: false,
 		code: "no_recovery_set",
 		message: "this wallet has no recovery codes"
 	}, "failed_before_side_effect");
-	return await completeWalletCustodyOperation(ctx, authorized.operation, 200, {
+	return await completeWalletOwnerOperation(ctx, authorized.operation, 200, {
 		ok: true,
 		activeCodeCount: result.activeCodeCount,
 		totalCodeCount: result.totalCodeCount,

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

@@ -1,20 +1,20 @@
 import { parseOrgId, parseProviderSubject, parseWalletAuthMethodId, parseWalletId, parseWebAuthnCredentialIdB64u, parseWebAuthnRpId } from "../../../../shared-ts/src/utils/domainIds.js";
-import { parseMpcWalletSigningQuotaId, parseWalletSessionId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
 import { isPlainObject } from "../../../../shared-ts/src/utils/validation.js";
 import { sha256HexUtf8 } from "../../../../shared-ts/src/utils/digests.js";
 import { parseDigestB64u } from "../../../../shared-ts/src/utils/canonicalPrimitives.js";
 import { base58Encode } from "../../../../shared-ts/src/utils/base58.js";
+import { parseMpcWalletSigningQuotaId, parseWalletSessionId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
 import { routerAbMpcMaterialActivationRefToWire, sameRouterAbMpcMaterialActivationRef } from "../../../../shared-ts/src/utils/routerAbNormalSigningIdentity.js";
 import { normalizeRuntimePolicyScope } from "../../../../shared-ts/src/threshold/signingRootScope.js";
 import { walletAuthAuthorityRef } from "../../../../shared-ts/src/utils/walletAuthAuthority.js";
 import { parseRouterAbEcdsaCredentialFreeSessionActivationResponseV1, parseRouterAbEcdsaPostRegistrationSessionActivationPolicyV1, parseRouterAbEcdsaPostRegistrationSessionActivationResponseV1, sameRouterAbEcdsaDerivationPublicCapabilityV1, sameRouterAbEcdsaRegistrationActivationReceiptV1 } from "../../../../shared-ts/src/utils/routerAbEcdsaDerivation.js";
 import { parseHostedWalletSeamsSessionExchangeCode, parseHostedWalletSeamsSessionExchangeNonce, parsePrimaryWalletSessionOperationCredentialToken, parseSessionOrigin, projectExactWalletSessionAuthorizationV1 } from "../../../../authorization/domain.js";
-import { walletIdFromString } from "../../../../shared-ts/src/utils/registrationIds.js";
+import { EMAIL_OTP_CHANNEL, WALLET_EMAIL_OTP_EXPORT_OPERATION } from "../../../../shared-ts/src/utils/emailOtpDomain.js";
+import { emailOtpStatusCode, hashEmailOtpOperationBinding } from "../../../domains/emailOtp/emailOtpSessionRouteHelpers.js";
 import { extractBearerCredential, resolveSourceIpFromFetchHeaders } from "../../../auth/routerApiKeyAuth.js";
 import { json, readJson } from "../../../framework/http.js";
+import { walletIdFromString } from "../../../../shared-ts/src/utils/registrationIds.js";
 import { routerApiEmailOtpRouteService } from "../../../framework/authServicePort.js";
-import { emailOtpStatusCode, hashEmailOtpOperationBinding } from "../../../domains/emailOtp/emailOtpSessionRouteHelpers.js";
-import { EMAIL_OTP_CHANNEL, WALLET_EMAIL_OTP_EXPORT_OPERATION } from "../../../../shared-ts/src/utils/emailOtpDomain.js";
 import { emitRouterApiWebhookEvent } from "../../../framework/routerApiWebhooks.js";
 import { parseWalletEmailOtpLoginOperation } from "../../../domains/emailOtp/emailOtpRequestValidation.js";
 import { handleWalletUnlockChallengeRoute, handleWalletUnlockVerifyRoute } from "../../../domains/walletUnlock/walletUnlockRouteHandlers.js";

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

@@ -1,12 +1,12 @@
 import { parseWalletId, parseWebAuthnCredentialIdB64u, parseWebAuthnRpId } from "../../../../shared-ts/src/utils/domainIds.js";
-import { parseAuthFactorId, parsePrincipalId, parseWalletSessionMintId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
 import { alphabetizeStringify } from "../../../../shared-ts/src/utils/digests.js";
 import { sha256Utf8DigestB64u } from "../../../../shared-ts/src/utils/canonicalPrimitives.js";
+import { parseAuthFactorId, parsePrincipalId, parseWalletSessionMintId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
 import { walletAuthAuthorityRef } from "../../../../shared-ts/src/utils/walletAuthAuthority.js";
 import { parseSessionOrigin, parseVerifiedOwnerProofId } from "../../../../authorization/domain.js";
 import { buildVerifiedWalletSessionPasskeyFactorResult } from "../../../../authorization/factorEvidence.js";
-import { walletIdFromString } from "../../../../shared-ts/src/utils/registrationIds.js";
 import { json, jsonFailure, readJson } from "../../../framework/http.js";
+import { walletIdFromString } from "../../../../shared-ts/src/utils/registrationIds.js";
 import { parseSyncAccountOptionsRequest, parseSyncAccountVerifyRequest } from "../../../domains/syncAccount/syncAccountRequestValidation.js";
 import { DEFAULT_WALLET_SESSION_TTL_MS } from "../../../../shared-ts/src/threshold/sessionPolicy.js";
 import { issueSyncAccountBootstrapV1 } from "./syncAccountBootstrap.js";

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

@@ -1,6 +1,6 @@
 import { mpcMaterialActivationRefsEqual, parseWebAuthnCredentialIdB64u, parseWebAuthnRpId } from "../../../../shared-ts/src/utils/domainIds.js";
-import { parsePrincipalId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
 import { isPlainObject } from "../../../../shared-ts/src/utils/validation.js";
+import { parsePrincipalId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
 import { routerAbMpcMaterialActivationRefFromWire } from "../../../../shared-ts/src/utils/routerAbNormalSigningIdentity.js";
 import { parseRouterAbEcdsaCredentialFreeSessionActivationResponseV1, parseRouterAbEcdsaPostRegistrationSessionActivationPolicyV1 } from "../../../../shared-ts/src/utils/routerAbEcdsaDerivation.js";
 import { projectActiveWalletSession } from "../../../../authorization/domain.js";

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

@@ -1,20 +1,20 @@
 import { parseWalletId } from "../../../../shared-ts/src/utils/domainIds.js";
-import { EVM_ECDSA_MPC_OPERATION_KINDS, buildEvmEcdsaMpcOperationRef, parseAuthorizationAuditEventId, parseAuthorizationEvidenceId, parseAuthorizationEvidenceSetId, parseAuthorizedOperationId, parseCapabilityId, parseCapabilityOperationId, parseEcdsaAuthorizationSessionId, parseWalletSessionMintId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
 import { base64UrlEncode } from "../../../../shared-ts/src/utils/base64.js";
 import { parseDigestB64u } from "../../../../shared-ts/src/utils/canonicalPrimitives.js";
-import { buildCapabilityOperationEnvelope } from "../../../../shared-ts/src/authorization/operationFingerprint.js";
 import "../../../../shared-ts/src/utils/encoders.js";
+import { EVM_ECDSA_MPC_OPERATION_KINDS, buildEvmEcdsaMpcOperationRef, parseAuthorizationAuditEventId, parseAuthorizationEvidenceId, parseAuthorizationEvidenceSetId, parseAuthorizedOperationId, parseCapabilityId, parseCapabilityOperationId, parseEcdsaAuthorizationSessionId, parseWalletSessionMintId } from "../../../../shared-ts/src/authorization/capabilityKinds.js";
+import { buildCapabilityOperationEnvelope } from "../../../../shared-ts/src/authorization/operationFingerprint.js";
 import { routerAbMpcMaterialActivationRefToWire, sameRouterAbMpcMaterialActivationRef } from "../../../../shared-ts/src/utils/routerAbNormalSigningIdentity.js";
 import { walletAuthAuthorityRef } from "../../../../shared-ts/src/utils/walletAuthAuthority.js";
 import { ROUTER_AB_ECDSA_DERIVATION_EXPORT_PATH, ROUTER_AB_ECDSA_DERIVATION_NORMAL_SIGNING_STATE_KIND_V1, ROUTER_AB_ECDSA_DERIVATION_REFRESH_PATH, computeRouterAbEcdsaOperationStepUpChallengeB64u, parseRouterAbEcdsaDerivationActivationRefreshCommitRequestV1, parseRouterAbEcdsaDerivationEvmDigestSigningFinalizeRequestV1, parseRouterAbEcdsaDerivationEvmDigestSigningRequestV1, parseRouterAbEcdsaDerivationExplicitExportRequestV1, parseRouterAbEcdsaOperationStepUpAuthorizationRequestV1, parseRouterAbEcdsaPostRegistrationSessionActivationRequestV1, parseRouterAbEcdsaPrepareSourceV1, sameRouterAbEcdsaDerivationNormalSigningScopeV1, sameRouterAbEcdsaDerivationPublicCapabilityV1 } from "../../../../shared-ts/src/utils/routerAbEcdsaDerivation.js";
 import { buildWalletSessionCapabilitySubjectsV1, projectActiveWalletSession, walletSessionAuthorizationV2RecordsEqual } from "../../../../authorization/domain.js";
+import { extractBearerCredential } from "../../../auth/routerApiKeyAuth.js";
+import { json, readJson } from "../../../framework/http.js";
 import { walletIdFromString } from "../../../../shared-ts/src/utils/registrationIds.js";
 import { WALLET_SESSION_FAILURE_CODES } from "../../../../shared-ts/src/utils/walletSessionFailure.js";
-import { extractBearerCredential } from "../../../auth/routerApiKeyAuth.js";
 import { walletSessionFailure, walletSessionFailureStatus } from "../../../auth/walletSessionFailure.js";
 import { resolveWalletSessionAuthorizationV2Admission } from "../../../domains/signingOperations/walletExecutionAdmission.js";
 import { resolveWalletSessionOperationCredentialAdmission, validateEcdsaPreprocessingSession } from "../../../auth/commonRouterUtils.js";
-import { json, readJson } from "../../../framework/http.js";
 import { thresholdEcdsaStatusCode } from "../../../../threshold/statusCodes.js";
 import { signingPrepareSessionResponse } from "../../../domains/signingOperations/signingPrepareSession.js";
 import { authenticateRouterAbWalletOperationStepUpIdentity } from "../../../domains/signingOperations/routerAbOperationStepUp.js";