@seams/wallet-server 0.5.0

package/dist/types/wallet-server/src/router/domains/ed25519Yao/session/routerAbEd25519YaoWalletSession.d.ts

@@ -0,0 +1,178 @@
+import type { RuntimePolicyScope } from '../../../../../../shared-ts/src/threshold/signingRootScope';
+import type { RouterAbEd25519NormalSigningState } from '../../../../../../shared-ts/src/utils/signingSessionSeal';
+import type { PasskeyWalletAuthAuthority, WalletAuthAuthority, WalletAuthAuthorityRef } from '../../../../../../shared-ts/src/utils/walletAuthAuthority';
+import type { WebAuthnAuthenticationCredential } from '../../../../core/types';
+import { thresholdEd25519AuthorityScopeFromWalletAuthAuthority } from '../../../../core/ThresholdService/validation';
+import type { WalletRegistrationEd25519YaoBootstrapSession } from '../../../../core/registrationContracts';
+import type { RouterAbEd25519YaoActiveCapabilityDescriptorV1 } from '../recovery/routerAbEd25519YaoRecovery';
+import type { MpcWalletSigningQuotaId, WalletSessionMintId, WalletSessionAuthorizationId, WalletSessionId } from '../../../../../../shared-ts/src/authorization/capabilityKinds';
+import type { WalletSessionOperationCredentialV1 } from '../../../../../../shared-ts/src/device-linking';
+import type { ThresholdEd25519SessionId, WalletAuthMethodId, WalletAuthorityId, WalletId } from '../../../../../../shared-ts/src/utils/domainIds';
+import type { VerifiedOwnerProof } from '../../../../authorization/factorEvidence';
+export type RouterAbEd25519YaoSessionPolicyV1 = {
+    readonly version: 'threshold_session_v1';
+    readonly nearAccountId: string;
+    readonly nearEd25519SigningKeyId: string;
+    readonly authority: WalletAuthAuthority;
+    readonly relayerKeyId: string;
+    readonly thresholdSessionId: ThresholdEd25519SessionId;
+    readonly runtimePolicyScope: RuntimePolicyScope;
+    readonly routerAbNormalSigning: RouterAbEd25519NormalSigningState;
+    readonly participantIds: readonly [number, number];
+    readonly ttlMs: number;
+    readonly remainingUses: number;
+};
+export type RouterAbEd25519YaoSessionRouteCommandV1 = {
+    readonly relayerKeyId: string;
+    readonly sessionPolicy: RouterAbEd25519YaoSessionPolicyV1;
+    readonly projectEnvironmentId?: string;
+    readonly routeAuth: {
+        readonly kind: 'passkey';
+        readonly webauthnAuthentication: WebAuthnAuthenticationCredential;
+    };
+    readonly walletSessionTarget: {
+        readonly kind: 'new_wallet_session';
+    };
+    readonly sessionKind: 'opaque';
+};
+export type RouterAbEd25519YaoOperationStepUpMaterialRecoveryRequest = {
+    readonly kind: 'not_requested';
+} | {
+    readonly kind: 'email_otp_factor_release_v1';
+    readonly workerEphemeralPublicKey65B64u: string;
+};
+export type RouterAbEd25519YaoOperationStepUpMaterialRecoveryResponse = {
+    readonly kind: 'not_requested';
+} | {
+    readonly kind: 'email_otp_factor_release_v1';
+    readonly challengeId: string;
+    readonly enrollmentId: string;
+    readonly enrollmentSealKeyVersion: string;
+    readonly serverEphemeralPublicKey65B64u: string;
+    readonly nonce12B64u: string;
+    readonly ciphertextB64u: string;
+};
+type RouterAbEd25519YaoOperationStepUpGrantCommandBase = {
+    readonly kind: 'router_ab_ed25519_yao_operation_step_up_grant_v1';
+    readonly normalSigningRequest: Record<string, unknown>;
+    readonly displayDigest: string;
+};
+export type RouterAbEd25519YaoOperationStepUpGrantCommandV1 = RouterAbEd25519YaoOperationStepUpGrantCommandBase & ({
+    readonly proof: {
+        readonly kind: 'passkey';
+        readonly authority: PasskeyWalletAuthAuthority;
+        readonly webauthnAuthentication: WebAuthnAuthenticationCredential;
+        readonly challengeId?: never;
+        readonly otpCode?: never;
+    };
+    readonly materialRecovery: Extract<RouterAbEd25519YaoOperationStepUpMaterialRecoveryRequest, {
+        kind: 'not_requested';
+    }>;
+} | {
+    readonly proof: {
+        readonly kind: 'email_otp';
+        readonly authorityRef: WalletAuthAuthorityRef;
+        readonly providerSubjectId: string;
+        readonly challengeId: string;
+        readonly otpCode: string;
+        readonly webauthnAuthentication?: never;
+        readonly authority?: never;
+    };
+    readonly materialRecovery: RouterAbEd25519YaoOperationStepUpMaterialRecoveryRequest;
+});
+export type RouterAbEd25519YaoBudgetRefreshAuthorizationV1 = {
+    readonly kind: 'verified_passkey_assertion_router_ab_ed25519_yao_budget_refresh_v1';
+    readonly authority: PasskeyWalletAuthAuthority;
+    readonly proof: Extract<VerifiedOwnerProof, {
+        readonly purpose: 'wallet_session';
+    }>;
+    readonly verifiedChallengeId: string;
+};
+export type RouterAbEd25519YaoBudgetRefreshRequestV1 = {
+    readonly kind: 'router_ab_ed25519_yao_budget_refresh_v1';
+    readonly sessionPolicy: RouterAbEd25519YaoSessionPolicyV1;
+    readonly authorization: RouterAbEd25519YaoBudgetRefreshAuthorizationV1;
+};
+/**
+ * The committed identity of one Wallet Session issuance attempt whose
+ * credential is unreachable. It is credential-free by construction: a replay
+ * reads a committed digest, and no digest reproduces plaintext.
+ */
+export type RouterAbEd25519YaoCommittedWalletSessionV1 = {
+    readonly kind: 'already_committed_wallet_session_v1';
+    readonly walletId: WalletId;
+    readonly authorityId: WalletAuthorityId;
+    readonly walletAuthMethodId: WalletAuthMethodId;
+    readonly mintId: WalletSessionMintId;
+    readonly authorizationId: WalletSessionAuthorizationId;
+    readonly walletSessionId: WalletSessionId;
+    readonly quotaId: MpcWalletSigningQuotaId;
+};
+export type RouterAbEd25519YaoAlreadyCommittedResponseV1 = {
+    readonly ok: false;
+    readonly code: 'already_committed';
+    readonly message: string;
+    readonly next: 'unlock_exact_method';
+    readonly committed: RouterAbEd25519YaoCommittedWalletSessionV1;
+};
+export type RouterAbEd25519YaoWalletSessionRejectionV1 = {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+    readonly next?: never;
+    readonly committed?: never;
+};
+type RouterAbEd25519YaoBudgetRefreshSessionV1 = {
+    readonly ok: true;
+    readonly walletId: string;
+    readonly nearAccountId: string;
+    readonly nearEd25519SigningKeyId: string;
+    readonly authorityScope: ReturnType<typeof thresholdEd25519AuthorityScopeFromWalletAuthAuthority>;
+    readonly thresholdSessionId: string;
+    readonly authorizationId: WalletSessionAuthorizationId;
+    readonly walletSessionId: WalletSessionId;
+    readonly quotaId: MpcWalletSigningQuotaId;
+    readonly expiresAtMs: number;
+    readonly expiresAt: string;
+    readonly participantIds: readonly [number, number];
+    readonly remainingUses: number;
+    readonly runtimePolicyScope: RuntimePolicyScope;
+    readonly routerAbNormalSigning: RouterAbEd25519NormalSigningState;
+};
+export type RouterAbEd25519YaoBudgetRefreshResponseV1 = (RouterAbEd25519YaoBudgetRefreshSessionV1 & {
+    readonly sessionKind: 'issued_exact_wallet_session';
+    readonly operationCredential: WalletSessionOperationCredentialV1;
+}) | (RouterAbEd25519YaoBudgetRefreshSessionV1 & {
+    readonly sessionKind: 'already_committed_exact_wallet_session';
+    readonly operationCredential?: never;
+}) | RouterAbEd25519YaoAlreadyCommittedResponseV1 | RouterAbEd25519YaoWalletSessionRejectionV1;
+type RouterAbEd25519YaoVerifiedWalletUnlockRequestBaseV1 = {
+    readonly walletId: string;
+    readonly signerSlot: number;
+    readonly remainingUses: number;
+    readonly verifiedChallengeId: string;
+    readonly authority: WalletAuthAuthority;
+    readonly proof: Extract<VerifiedOwnerProof, {
+        readonly purpose: 'wallet_session';
+    }>;
+};
+export type RouterAbEd25519YaoWalletSessionIdentityV1 = {
+    readonly kind: 'new_wallet_session';
+} | {
+    readonly kind: 'reuse_wallet_session_v2';
+    readonly authorizationId: WalletSessionAuthorizationId;
+    readonly walletSessionId: WalletSessionId;
+    readonly quotaId: MpcWalletSigningQuotaId;
+    readonly expiresAtMs: number;
+    readonly remainingUses: number;
+};
+export type RouterAbEd25519YaoVerifiedWalletUnlockRequestV1 = RouterAbEd25519YaoVerifiedWalletUnlockRequestBaseV1 & {
+    readonly walletSessionIdentity: RouterAbEd25519YaoWalletSessionIdentityV1;
+};
+export type RouterAbEd25519YaoVerifiedWalletUnlockResponseV1 = {
+    readonly ok: true;
+    readonly session: WalletRegistrationEd25519YaoBootstrapSession;
+    readonly capability: RouterAbEd25519YaoActiveCapabilityDescriptorV1;
+} | RouterAbEd25519YaoAlreadyCommittedResponseV1 | RouterAbEd25519YaoWalletSessionRejectionV1;
+export {};
+//# sourceMappingURL=routerAbEd25519YaoWalletSession.d.ts.map

package/dist/types/wallet-server/src/router/domains/ed25519Yao/session/routerAbEd25519YaoWalletSession.typecheck.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=routerAbEd25519YaoWalletSession.typecheck.d.ts.map

package/dist/types/wallet-server/src/router/domains/ed25519Yao/session/thresholdEd25519RequestValidation.d.ts

@@ -0,0 +1,19 @@
+import type { RouterAbEd25519YaoOperationStepUpGrantCommandV1, RouterAbEd25519YaoSessionPolicyV1, RouterAbEd25519YaoSessionRouteCommandV1 } from './routerAbEd25519YaoWalletSession';
+export type ThresholdEd25519RouteErrorBody = {
+    ok: false;
+    code: 'invalid_body';
+    message: string;
+};
+type ThresholdEd25519RouteParseError = {
+    ok: false;
+    body: ThresholdEd25519RouteErrorBody;
+};
+export type ThresholdEd25519RouteParseResult<T> = {
+    ok: true;
+    request: T;
+} | ThresholdEd25519RouteParseError;
+export declare function parseRouterAbEd25519YaoSessionPolicyV1(raw: unknown): ThresholdEd25519RouteParseResult<RouterAbEd25519YaoSessionPolicyV1>;
+export declare function parseThresholdEd25519SessionRouteRequest(raw: unknown): ThresholdEd25519RouteParseResult<RouterAbEd25519YaoSessionRouteCommandV1>;
+export declare function parseThresholdEd25519OperationStepUpGrantRequest(raw: unknown): ThresholdEd25519RouteParseResult<RouterAbEd25519YaoOperationStepUpGrantCommandV1>;
+export {};
+//# sourceMappingURL=thresholdEd25519RequestValidation.d.ts.map

package/dist/types/wallet-server/src/router/domains/emailOtp/emailOtpExportPolicy.d.ts

@@ -0,0 +1,32 @@
+import type { RouterApiEmailOtpExportPolicyDecision, RouterApiEmailOtpExportPolicyInput, RouterApiOptions } from '../../framework/routerApi';
+export type ResolvedEmailOtpExportPolicyDecision = RouterApiEmailOtpExportPolicyDecision & {
+    policySource: 'adapter' | 'default_allow';
+};
+export declare function authorizeEmailOtpExportPolicy(opts: RouterApiOptions, input: RouterApiEmailOtpExportPolicyInput): Promise<ResolvedEmailOtpExportPolicyDecision>;
+export declare function emailOtpExportPolicyAuditPayload(input: {
+    source: 'login_challenge' | 'login_verify' | 'signing_session_challenge' | 'signing_session_verify';
+    decision: ResolvedEmailOtpExportPolicyDecision;
+    challengeId?: string;
+    otpChannel?: string;
+}): Record<string, unknown>;
+export declare function emailOtpExportPolicyWebhookEventDescriptor(input: {
+    eventType: 'wallet.email_otp.export_denied' | 'wallet.email_otp.export_challenge_issued' | 'wallet.email_otp.export_approved';
+    source: 'login_challenge' | 'login_verify' | 'signing_session_challenge' | 'signing_session_verify';
+    decision: ResolvedEmailOtpExportPolicyDecision;
+    challengeId?: string;
+    otpChannel?: string;
+    code?: string;
+    message?: string;
+}): {
+    eventType: string;
+    eventId?: string;
+    payload: Record<string, unknown>;
+};
+export declare function emailOtpExportDeniedDecisionFromResult(input: {
+    code: string;
+    message: string;
+    policySource: ResolvedEmailOtpExportPolicyDecision['policySource'];
+    policyId?: string;
+    approvalId?: string;
+}): ResolvedEmailOtpExportPolicyDecision;
+//# sourceMappingURL=emailOtpExportPolicy.d.ts.map

package/dist/types/wallet-server/src/router/domains/emailOtp/emailOtpRequestValidation.d.ts

@@ -0,0 +1,13 @@
+import { type WalletEmailOtpChannel, type WalletEmailOtpLoginOperation, type WalletUnlockBackend } from '../../../../../shared-ts/src/utils/emailOtpDomain';
+export type { WalletEmailOtpChannel } from '../../../../../shared-ts/src/utils/emailOtpDomain';
+export declare function parseWalletUnlockBackend(raw: unknown): WalletUnlockBackend | null;
+export declare function parseWalletEmailOtpChannel(raw: unknown): WalletEmailOtpChannel | null;
+export declare function parseWalletEmailOtpLoginOperation(raw: unknown): {
+    ok: true;
+    operation: WalletEmailOtpLoginOperation;
+} | {
+    ok: false;
+    code: 'invalid_body';
+    message: string;
+};
+//# sourceMappingURL=emailOtpRequestValidation.d.ts.map

package/dist/types/wallet-server/src/router/domains/emailOtp/emailOtpRouteHandlers.d.ts

@@ -0,0 +1,35 @@
+import type { RouterApiEmailOtpRouteService } from '../../framework/authServicePort';
+export type EmailOtpRouteResponse = {
+    status: number;
+    body: Record<string, unknown>;
+};
+export declare function sealEmailOtpFactorSecretForWorker(input: {
+    readonly factorSecret32B64u: string;
+    readonly workerEphemeralPublicKey65B64u: string;
+    readonly walletId: string;
+    readonly enrollmentId: string;
+    readonly enrollmentSealKeyVersion: string;
+    readonly challengeId: string;
+}): Promise<{
+    readonly ok: true;
+    readonly serverEphemeralPublicKey65B64u: string;
+    readonly nonce12B64u: string;
+    readonly ciphertextB64u: string;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+}>;
+export declare function handleEmailOtpDevCleanupGoogleRegistrationRoute(input: {
+    body: unknown;
+    service: RouterApiEmailOtpRouteService;
+}): Promise<EmailOtpRouteResponse>;
+export declare function handleEmailOtpRegistrationSealRoute(input: {
+    body: unknown;
+    service: RouterApiEmailOtpRouteService;
+}): Promise<EmailOtpRouteResponse>;
+export declare function handleEmailOtpDevOutboxRoute(input: {
+    body: unknown;
+    service: RouterApiEmailOtpRouteService;
+}): Promise<EmailOtpRouteResponse>;
+//# sourceMappingURL=emailOtpRouteHandlers.d.ts.map

package/dist/types/wallet-server/src/router/domains/emailOtp/emailOtpSessionRouteHelpers.d.ts

@@ -0,0 +1,134 @@
+import { type WalletEmailOtpChannel } from '../../../../../shared-ts/src/utils/emailOtpDomain';
+import type { EmailOtpChallengeDelivery } from '../../framework/authServicePort';
+export type OidcAccountMode = 'register' | 'login';
+export type EmailOtpFailureAuditInput = {
+    source: 'registration_finalize' | 'login_challenge' | 'login_verify' | 'unlock_verify' | 'signing_session_challenge' | 'signing_session_verify';
+    code: string;
+    message: string;
+    challengeId?: string;
+    otpChannel?: WalletEmailOtpChannel;
+    operation?: string;
+    lockedUntilMs?: number;
+};
+export type EmailOtpWebhookEventDescriptor = {
+    eventType: string;
+    eventId?: string;
+    payload: Record<string, unknown>;
+};
+export type EmailOtpRouteValidationError = {
+    ok: false;
+    status: number;
+    body: Record<string, unknown>;
+};
+export type EmailOtpRouteValidationResult<T> = ({
+    ok: true;
+} & T) | EmailOtpRouteValidationError;
+export declare function emailOtpStatusCode(code: string | undefined): number;
+export declare function emailOtpResultStatus(result: {
+    ok: boolean;
+    code?: string;
+}): number;
+export declare function emailOtpInternalErrorBody(error: unknown): {
+    ok: false;
+    code: 'internal';
+    message: string;
+};
+export declare function emailOtpFailureAuditPayload(input: EmailOtpFailureAuditInput): Record<string, unknown>;
+export declare function shouldEmitEmailOtpLockedWebhook(code: string): boolean;
+export declare function emailOtpFailureWebhookEventDescriptors(input: EmailOtpFailureAuditInput): EmailOtpWebhookEventDescriptor[];
+export declare function emailOtpLoggedInWebhookEventDescriptor(input: {
+    challengeId: string;
+    otpChannel: WalletEmailOtpChannel;
+    unlockBackend: string;
+}): EmailOtpWebhookEventDescriptor;
+export declare function emailOtpEnrolledWebhookEventDescriptor(input: {
+    challengeId: string;
+    otpChannel: WalletEmailOtpChannel;
+    enrollmentSealKeyVersion: string;
+    unlockKeyVersion?: string;
+}): EmailOtpWebhookEventDescriptor;
+export declare function validateEmailOtpJsonObjectBody(body: unknown): EmailOtpRouteValidationResult<{
+    body: Record<string, unknown>;
+}>;
+export declare function validateEmailOtpWalletId(input: {
+    body: Record<string, unknown>;
+    claims: unknown;
+    userId: string;
+}): EmailOtpRouteValidationResult<{
+    walletId: string;
+}>;
+export declare function validateEmailOtpChannel(body: Record<string, unknown>): EmailOtpRouteValidationResult<{
+    otpChannel: WalletEmailOtpChannel;
+}>;
+export declare function validateEmailOtpRequiredString(body: Record<string, unknown>, field: string): EmailOtpRouteValidationResult<{
+    value: string;
+}>;
+export declare function getAuthenticatedWalletId(claims: unknown, userId: string): string;
+export declare function isGoogleOidcEmailOtpSession(claims: unknown): boolean;
+export declare function parseOidcAccountMode(raw: unknown): OidcAccountMode | undefined;
+export declare function hashEmailOtpOperationBinding(input: {
+    walletId: string;
+    providerUserId: string;
+    orgId: string;
+    operation: string;
+    requestOrigin: string | null;
+    audience: string | null;
+    authorityRef?: unknown;
+    operationFingerprintDigest?: string;
+}): Promise<string>;
+export declare function emailOtpChallengeResponseBody(result: {
+    ok: boolean;
+    challenge?: {
+        challengeId: string;
+        issuedAtMs: number;
+        expiresAtMs: number;
+        userId: string;
+        walletId: string;
+        orgId?: string;
+        ownerProofBindingDigest: string;
+        otpChannel: string;
+        action: string;
+        operation: string;
+    };
+    delivery?: EmailOtpChallengeDelivery;
+    retryAfterMs?: number;
+}): Record<string, unknown>;
+export declare function emailOtpServerSealResponseBody(result: {
+    ok: true;
+    ciphertext: string;
+    enrollmentSealKeyVersion: string;
+} | ({
+    ok: false;
+    code: string;
+    message: string;
+} & Record<string, unknown>), walletId: string): Record<string, unknown>;
+export declare function emailOtpEnrollmentFinalizeResponseBody(result: {
+    ok: true;
+    walletId: string;
+    otpChannel: string;
+    enrollment: {
+        createdAtMs: number;
+        updatedAtMs: number;
+        enrollmentSealKeyVersion: string;
+        unlockKeyVersion?: string;
+    };
+} | ({
+    ok: false;
+    code: string;
+    message: string;
+} & Record<string, unknown>)): Record<string, unknown>;
+export declare function emailOtpLoginVerifyResponseBody(args: {
+    result: {
+        ok: true;
+        challengeId: string;
+        loginGrant: string;
+        grantExpiresAtMs: number;
+        otpChannel: string;
+    };
+    enrollment: {
+        enrollment: {
+            enrollmentSealKeyVersion?: unknown;
+        };
+    };
+}): Record<string, unknown>;
+//# sourceMappingURL=emailOtpSessionRouteHelpers.d.ts.map

package/dist/types/wallet-server/src/router/domains/passkeyCustody/envelopeRevocationAdmission.d.ts

@@ -0,0 +1,31 @@
+import type { PasskeyCustodyEnvelopeRecord } from '../../../../../shared-ts/src/passkey-custody';
+/**
+ * Whether one custody envelope may be revoked.
+ *
+ * **The rule that needs a list, not a lookup.** Revoking an envelope removes
+ * one factor's way into the wallet's custody seed. Doing that to the *last*
+ * active envelope leaves a wallet whose seed no factor can open — recoverable
+ * only by a recovery code, and only if the owner still has one. That is a
+ * support incident, not an error the user sees at the time, because revocation
+ * would appear to succeed.
+ *
+ * So the decision is a function of the wallet's whole envelope set, which is
+ * why `listWalletEnvelopes` exists. A per-envelope lookup cannot answer it.
+ *
+ * Removing a synced passkey is the case this is written for: the same custody
+ * secret is protected by another active envelope, so the lane stays open and
+ * the removal is safe.
+ */
+export type EnvelopeRevocationAdmission = {
+    readonly kind: 'admitted';
+} | {
+    readonly kind: 'refused';
+    readonly reason: string;
+};
+export declare function admitEnvelopeRevocation(input: {
+    /** The wallet's envelopes, as stored. */
+    readonly envelopes: readonly PasskeyCustodyEnvelopeRecord[];
+    /** The envelope the caller wants revoked. */
+    readonly envelopeId: string;
+}): EnvelopeRevocationAdmission;
+//# sourceMappingURL=envelopeRevocationAdmission.d.ts.map

package/dist/types/wallet-server/src/router/domains/passkeyCustody/passkeyCustodyEnvelopeRetrieval.d.ts

@@ -0,0 +1,85 @@
+import type { PasskeyCustodyEnvelopeRecord } from '../../../../../shared-ts/src/passkey-custody';
+import type { WebAuthnRpId } from '../../../../../shared-ts/src/utils/domainIds';
+import { verifyWebAuthnAuthenticationLiteWithStore } from '../../../core/authService/webauthn';
+import type { WebAuthnAuthenticatorStore } from '../../../core/WebAuthnAuthenticatorStore';
+import type { WebAuthnAuthenticationCredential } from '../../../core/types';
+import type { NormalizedLogger } from '../../../core/logger';
+import type { CloudflareD1PasskeyCustodyEnvelopeStore, PasskeyCustodyEnvelopeLocator, WalletCustodyFactorRef } from '../../cloudflare/d1/passkeyCustody/d1PasskeyCustodyEnvelopeStore';
+/**
+ * A locator narrowed to the passkey factor. Email OTP envelopes are
+ * unrepresentable in this request type: their factor secret is not a
+ * credential, so a WebAuthn assertion is never evidence for them.
+ */
+export type PasskeyEnvelopeRetrievalLocator = Omit<PasskeyCustodyEnvelopeLocator, 'factor'> & {
+    readonly factor: Extract<WalletCustodyFactorRef, {
+        kind: 'passkey';
+    }>;
+};
+/**
+ * Authenticated retrieval of one server-held passkey custody envelope.
+ *
+ * This path serves passkey-factor envelopes only: it is gated on a WebAuthn
+ * assertion, which an Email OTP envelope has no counterpart for. Email OTP
+ * envelopes are retrieved through the Email OTP admission boundary instead.
+ *
+ * Retrieval requires a server-verified assertion for the exact wallet, RP ID,
+ * credential ID, and operation challenge. The response carries ciphertext and
+ * public binding only: the KEK is derived from the PRF result, which never
+ * leaves the browser's secure worker, so this path cannot open what it returns.
+ */
+export type PasskeyCustodyEnvelopeRetrievalRequest = {
+    readonly locator: PasskeyEnvelopeRetrievalLocator;
+    readonly rpId: WebAuthnRpId;
+    readonly userId: string;
+    readonly expectedChallenge: string;
+    readonly expectedOrigin: string;
+    /**
+     * The assertion with its extension outputs already removed. The PRF result
+     * must be stripped in the worker before the assertion crosses this boundary.
+     */
+    readonly webauthnAuthentication: WebAuthnAuthenticationCredential;
+};
+export type PasskeyCustodyEnvelopeRetrievalResult = {
+    readonly kind: 'active';
+    readonly envelope: PasskeyCustodyEnvelopeRecord;
+    readonly storeVersion: string;
+}
+/**
+ * The assertion still carried WebAuthn extension output. A PRF result that
+ * reaches the server has already escaped the worker, so the request fails
+ * loudly instead of being silently sanitized and served.
+ */
+ | {
+    readonly kind: 'prf_disclosed';
+    readonly message: string;
+} | {
+    readonly kind: 'assertion_rejected';
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly kind: 'credential_mismatch';
+} | {
+    readonly kind: 'retired';
+    readonly retiredAtMs: number;
+} | {
+    readonly kind: 'revoked';
+    readonly revokedAtMs: number;
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'digest_mismatch';
+};
+/**
+ * The assertion verifier this retrieval depends on. It is injectable so the
+ * lifecycle mapping below can be tested against a verified assertion without
+ * forging authenticator signatures; production callers take the default.
+ */
+export type PasskeyCustodyAssertionVerifier = typeof verifyWebAuthnAuthenticationLiteWithStore;
+export declare function retrievePasskeyCustodyEnvelope(input: {
+    readonly request: PasskeyCustodyEnvelopeRetrievalRequest;
+    readonly envelopeStore: CloudflareD1PasskeyCustodyEnvelopeStore;
+    readonly authenticatorStore: WebAuthnAuthenticatorStore;
+    readonly logger: NormalizedLogger;
+    readonly verifyAssertion?: PasskeyCustodyAssertionVerifier;
+}): Promise<PasskeyCustodyEnvelopeRetrievalResult>;
+//# sourceMappingURL=passkeyCustodyEnvelopeRetrieval.d.ts.map

package/dist/types/wallet-server/src/router/domains/passkeyCustody/passkeyCustodyEnvelopeRetrievalRoute.d.ts

@@ -0,0 +1,42 @@
+import { type PasskeyCustodyEnvelopeRetrievalRequest, type PasskeyCustodyEnvelopeRetrievalResult } from './passkeyCustodyEnvelopeRetrieval';
+import type { CloudflareD1PasskeyCustodyEnvelopeStore } from '../../cloudflare/d1/passkeyCustody/d1PasskeyCustodyEnvelopeStore';
+import type { WebAuthnAuthenticatorStore } from '../../../core/WebAuthnAuthenticatorStore';
+import type { NormalizedLogger } from '../../../core/logger';
+/**
+ * The route a browser with empty IndexedDB uses to fetch its wallet's custody
+ * envelope.
+ *
+ * Synced cold unlock needs it: the same passkey is available on the new device,
+ * but the envelope is server-held and nothing local has it. The retrieval
+ * itself was already written and gated; what was missing was any way to reach
+ * it over the wire, which is what made cold unlock unimplementable end to end.
+ *
+ * **The response carries ciphertext and public binding only.** The KEK derives
+ * from the PRF result, which never leaves the browser's secure worker — so this
+ * route cannot open what it returns, and a compromised server learns no custody
+ * secret by answering.
+ *
+ * Every failure is a distinct status rather than one generic refusal. A client
+ * must be able to tell "your credential is no longer active" from "this wallet
+ * has no envelope" from "the stored record is corrupt": the first two are
+ * things a user can act on, and the third is an incident.
+ */
+export type PasskeyCustodyEnvelopeRetrievalRouteResponse = {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+};
+export declare function handlePasskeyCustodyEnvelopeRetrieval(input: {
+    readonly request: PasskeyCustodyEnvelopeRetrievalRequest;
+    readonly envelopeStore: CloudflareD1PasskeyCustodyEnvelopeStore;
+    readonly authenticatorStore: WebAuthnAuthenticatorStore;
+    readonly logger: NormalizedLogger;
+}): Promise<PasskeyCustodyEnvelopeRetrievalRouteResponse>;
+/**
+ * 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.
+ */
+export declare function passkeyCustodyEnvelopeRetrievalRouteResponse(result: PasskeyCustodyEnvelopeRetrievalResult): PasskeyCustodyEnvelopeRetrievalRouteResponse;
+//# sourceMappingURL=passkeyCustodyEnvelopeRetrievalRoute.d.ts.map

package/dist/types/wallet-server/src/router/domains/passkeyCustody/registrationCustodyOutcome.d.ts

@@ -0,0 +1,38 @@
+import type { WalletCustodyRegistrationOutcome } from '../../../../../shared-ts/src/passkey-custody';
+import type { WalletAuthAuthority } from '../../../../../shared-ts/src/utils/walletAuthAuthority';
+import type { WalletId } from '../../../../../shared-ts/src/utils/domainIds';
+import type { WalletCustodyCeremonyCommitPayload } from './walletCustodyRegistrationCommit';
+import { type VerifiedEmailOtpEnrollmentFacts } from './verifiedCustodyFactor';
+import type { CloudflareD1WalletCustodyCommitStore } from '../../cloudflare/d1/passkeyCustody/d1WalletCustodyCommitStore';
+/**
+ * The whole custody side-effect of one registration leg, in one call: resolve
+ * the factor from the authority the leg verified, then admit the payload
+ * against the wallet the leg registered.
+ *
+ * **Activation never fails because of custody.** The wallet's registration is
+ * already committed by the time this runs, and the seed exists only in the
+ * client's worker — so the client is the one party that can retry, re-enter as
+ * a join, or abandon the run. Failing activation here would leave the server
+ * registered, the response an error, and the client with no instruction; the
+ * client cannot be told what happened by an exception it never sees the body
+ * of. So every outcome is reported, and the caller decides.
+ *
+ * That is a deliberate default, not a claim that a wallet without custody is
+ * fine — it is not, and a client that sees anything but `committed` or
+ * `not_requested` must act on it rather than treat registration as done.
+ *
+ * The outcome shape itself is the wire contract, and lives in shared beside the
+ * payload it answers.
+ */
+export type RegistrationCustodyOutcome = WalletCustodyRegistrationOutcome;
+export declare function commitRegistrationCustody(input: {
+    /** Absent when the client did not run a custody ceremony for this leg. */
+    readonly payload?: WalletCustodyCeremonyCommitPayload;
+    readonly verifiedWalletId: WalletId;
+    readonly verifiedAuthority: WalletAuthAuthority;
+    /** Required when the verified authority is Email OTP. */
+    readonly verifiedEmailOtpEnrollment?: VerifiedEmailOtpEnrollmentFacts;
+    readonly nowMs: number;
+    readonly store: CloudflareD1WalletCustodyCommitStore;
+}): Promise<RegistrationCustodyOutcome>;
+//# sourceMappingURL=registrationCustodyOutcome.d.ts.map

package/dist/types/wallet-server/src/router/domains/passkeyCustody/verifiedCustodyFactor.d.ts

@@ -0,0 +1,35 @@
+import { type WalletCustodyEnvelopeFactor } from '../../../../../shared-ts/src/passkey-custody';
+import { type WalletAuthAuthority } from '../../../../../shared-ts/src/utils/walletAuthAuthority';
+/**
+ * The custody factor for an envelope, resolved from the authority the
+ * registration leg actually verified.
+ *
+ * This exists so a route never reads the factor off the ceremony payload. The
+ * factor is what the envelope's AAD binds the seed to, so a payload-supplied
+ * one would let a caller address a wallet's custody to a credential its owner
+ * does not control. Taking it from `WalletAuthAuthority` means the envelope can
+ * only ever name the credential this server just proved.
+ *
+ * A passkey authority carries everything the factor needs. An Email OTP
+ * authority does not: the custody factor names the *enrollment* — its id and
+ * seal key version — which live on the enrollment material the same leg
+ * finalizes, not on the authority. So the OTP arm takes them explicitly, and
+ * the caller must pass the enrollment it verified rather than one it looked up.
+ */
+export type VerifiedCustodyFactorResult = {
+    readonly ok: true;
+    readonly factor: WalletCustodyEnvelopeFactor;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export type VerifiedEmailOtpEnrollmentFacts = {
+    readonly enrollmentId: string;
+    readonly enrollmentSealKeyVersion: string;
+};
+export declare function verifiedCustodyFactorFromAuthority(input: {
+    readonly authority: WalletAuthAuthority;
+    /** Required exactly when the authority is Email OTP. */
+    readonly emailOtpEnrollment?: VerifiedEmailOtpEnrollmentFacts;
+}): VerifiedCustodyFactorResult;
+//# sourceMappingURL=verifiedCustodyFactor.d.ts.map