@seams/wallet-server 0.5.0

package/dist/types/shared-ts/src/wallet-recovery/recoveryCodeAttempt.d.ts

@@ -0,0 +1,59 @@
+import { type RecoveryCodeReservationId, type RecoveryCodeTransitionRejection } from './recoveryCodeReservation';
+import type { RecoveryCodeLifecycleState } from './recoveryEnvelopes';
+/**
+ * One recovery attempt, with the code's lifecycle bound to its outcome.
+ *
+ * **A code is consumed only when the activation commits.** The three
+ * transitions that enforce that already exist; what did not was anything
+ * making the ordering structural. Spelling it out at each call site is a rule
+ * that holds until someone adds an early return — and the failure is silent
+ * and expensive: a code burned by a recovery that then failed leaves the user
+ * one code poorer with nothing recovered.
+ *
+ * So the attempt owns the order. The caller supplies the work; this reserves
+ * before it runs, consumes only if it reports a commit, and releases on every
+ * other path including a throw.
+ *
+ * Nothing here persists. Each transition returns the next lifecycle for the
+ * caller to write — this composes the decisions, it does not own the record.
+ */
+export type WalletRecoveryAttemptOutcome<T> = {
+    readonly kind: 'committed';
+    readonly value: T;
+    /** Consumed. Write this before reporting success. */
+    readonly lifecycle: RecoveryCodeLifecycleState;
+} | {
+    readonly kind: 'released';
+    /** Back in the active pool: the attempt did not commit. */
+    readonly lifecycle: RecoveryCodeLifecycleState;
+    readonly reason: string;
+} | {
+    readonly kind: 'refused';
+    /** Unchanged: the code was never held by this attempt. */
+    readonly lifecycle: RecoveryCodeLifecycleState;
+    readonly code: RecoveryCodeTransitionRejection;
+    readonly reason: string;
+};
+/**
+ * What the caller's activation work reports.
+ *
+ * `committed` is a claim that every required receipt verified — it is the
+ * only thing that burns the code, so it must not be returned optimistically.
+ */
+export type WalletRecoveryActivationResult<T> = {
+    readonly kind: 'committed';
+    readonly value: T;
+} | {
+    readonly kind: 'not_committed';
+    readonly reason: string;
+};
+export declare function runWalletRecoveryWithCode<T>(args: {
+    readonly lifecycle: RecoveryCodeLifecycleState;
+    readonly reservationId: RecoveryCodeReservationId;
+    readonly nowMs: number;
+    readonly reservationTtlMs: number;
+    /** Reads the clock again at commit time: activation is not instantaneous. */
+    readonly clockMs?: () => number;
+    readonly activate: () => Promise<WalletRecoveryActivationResult<T>>;
+}): Promise<WalletRecoveryAttemptOutcome<T>>;
+//# sourceMappingURL=recoveryCodeAttempt.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/recoveryCodeIssuance.d.ts

@@ -0,0 +1,37 @@
+import { type EmailOtpRecoveryCode as WalletRecoveryCode } from '../utils/emailOtpRecoveryKey';
+/**
+ * Issues the ten recovery codes that establishing custody requires.
+ *
+ * **This is Phase 2 work, not Phase 4's.** A ceremony that establishes custody
+ * must issue its recovery set in the same act — the ceremony refuses to seal a
+ * seed without ten codes, because an envelope with no recovery set is a working
+ * wallet whose owner believes they hold codes that were never stored. Phase 4
+ * owns what happens to codes afterwards: backup acknowledgement, rotation,
+ * status, and the recovery UX.
+ *
+ * The codes are the only copy. Nothing here persists them, and the wraps the
+ * ceremony seals are one-way — so a caller that discards this result without
+ * showing it to the user has issued ten codes nobody can ever produce.
+ */
+export type IssuedWalletRecoveryCodes = {
+    /** Formatted for display, in issue order. Show these once. */
+    readonly codes: readonly WalletRecoveryCode[];
+    /**
+     * The same codes as bytes, in the same order, for the ceremony to wrap.
+     *
+     * Held separately rather than re-decoded at the seal site so the two can
+     * never disagree about which code a wrap belongs to.
+     */
+    readonly codeBytes: readonly Uint8Array[];
+};
+/**
+ * Mints ten codes from the platform CSPRNG.
+ *
+ * No id is derived here. The ceremony derives each code's id from the wallet
+ * and the code bytes as it seals the wrap, so there is exactly one definition
+ * of what an id is and a caller cannot supply one that names the wrong wrap.
+ */
+export declare function issueWalletRecoveryCodes(): IssuedWalletRecoveryCodes;
+/** Zeroizes the issued byte copies once the ceremony has wrapped them. */
+export declare function zeroizeIssuedWalletRecoveryCodes(issued: IssuedWalletRecoveryCodes): void;
+//# sourceMappingURL=recoveryCodeIssuance.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/recoveryCodeLocator.d.ts

@@ -0,0 +1,22 @@
+import { type DigestB64u } from '../utils/canonicalPrimitives';
+import type { DerivedWalletRecoveryKeyId } from './recoveryKeyId';
+/** The code-only digest used to locate a wallet recovery set. */
+export type RecoveryCodeLocatorV1 = DigestB64u;
+export type WalletRecoveryCodeLocatorRecordV1 = {
+    readonly locatorB64u: RecoveryCodeLocatorV1;
+    readonly recoveryKeyId: DerivedWalletRecoveryKeyId;
+};
+export declare function parseRecoveryCodeLocatorV1(value: unknown, label?: string): RecoveryCodeLocatorV1;
+/**
+ * Derives the code-only locator from the normalized recovery code.
+ *
+ * The locator identifies a set for lookup. It never replaces the existing
+ * wallet-bound recovery-key derivation that authenticates a wrap.
+ */
+export declare function deriveRecoveryCodeLocatorV1(recoveryCode: string): Promise<RecoveryCodeLocatorV1>;
+export declare function deriveRecoveryCodeLocatorV1FromBytes(codeBytes: Uint8Array): Promise<RecoveryCodeLocatorV1>;
+export declare function deriveRecoveryCodeLocatorRecordsV1(inputs: readonly {
+    readonly codeBytes: Uint8Array;
+    readonly recoveryKeyId: DerivedWalletRecoveryKeyId;
+}[]): Promise<readonly WalletRecoveryCodeLocatorRecordV1[]>;
+//# sourceMappingURL=recoveryCodeLocator.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/recoveryCodeReservation.d.ts

@@ -0,0 +1,79 @@
+import type { RecoveryCodeLifecycleState } from './recoveryEnvelopes';
+import { type CorrelationId } from '../utils/canonicalPrimitives';
+/**
+ * Recovery-code reservation lifecycle.
+ *
+ * A code is held while a recovery runs and is consumed only once the complete
+ * replacement-credential activation commits. That ordering is the point: a code
+ * burned at the start of a recovery that then fails would leave the user one
+ * code poorer with nothing recovered.
+ *
+ * Reservations expire so an abandoned recovery cannot strand a code forever.
+ * Expiry is evaluated against the caller's clock at transition time rather than
+ * swept in the background, so a stale hold never blocks a fresh attempt.
+ */
+export type RecoveryCodeReservationId = string & {
+    readonly __recoveryCodeReservationIdBrand: 'RecoveryCodeReservationId';
+};
+export type WalletRecoveryKeySetId = `near_ed25519:${string}` | `evm_family_ecdsa:${string}`;
+/** One protocol lifecycle below a wallet-scoped recovery reservation. */
+export declare function deriveWalletRecoveryKeyLifecycleId(input: {
+    readonly reservationId: RecoveryCodeReservationId;
+    readonly keySetId: WalletRecoveryKeySetId;
+}): Promise<CorrelationId>;
+export type RecoveryCodeTransitionResult = {
+    ok: true;
+    lifecycle: RecoveryCodeLifecycleState;
+} | {
+    ok: false;
+    code: RecoveryCodeTransitionRejection;
+    message: string;
+};
+export type RecoveryCodeTransitionRejection = 'already_consumed' | 'revoked' | 'already_reserved' | 'not_reserved' | 'reservation_expired' | 'reservation_mismatch';
+export declare function parseRecoveryCodeReservationId(value: unknown): RecoveryCodeReservationId;
+/**
+ * Places a hold on an active code.
+ *
+ * A reservation that has already expired is treated as absent, so an abandoned
+ * attempt does not block a later one. A live reservation held by a different
+ * recovery is refused: two concurrent recoveries must not share one code.
+ */
+export declare function reserveRecoveryCode(args: {
+    lifecycle: RecoveryCodeLifecycleState;
+    reservationId: RecoveryCodeReservationId;
+    nowMs: number;
+    reservationTtlMs: number;
+}): RecoveryCodeTransitionResult;
+/**
+ * Releases a hold after a failed pre-commit recovery, returning the code to the
+ * active pool. Releasing a consumed code is refused: consumption is terminal
+ * and a post-commit failure must not hand the code back.
+ */
+export declare function releaseRecoveryCodeReservation(args: {
+    lifecycle: RecoveryCodeLifecycleState;
+    reservationId: RecoveryCodeReservationId;
+}): RecoveryCodeTransitionResult;
+/**
+ * Consumes a reserved code once every required activation receipt has verified.
+ *
+ * The reservation must still be live and held by this exact recovery. An
+ * expired hold cannot be consumed: the code may have been re-reserved by
+ * another attempt in the meantime, and consuming it here would burn a code that
+ * a different recovery is relying on.
+ */
+export declare function consumeReservedRecoveryCode(args: {
+    lifecycle: RecoveryCodeLifecycleState;
+    reservationId: RecoveryCodeReservationId;
+    nowMs: number;
+}): RecoveryCodeTransitionResult;
+/** Revocation is terminal from every state except consumption. */
+export declare function revokeRecoveryCode(args: {
+    lifecycle: RecoveryCodeLifecycleState;
+    nowMs: number;
+}): RecoveryCodeTransitionResult;
+/**
+ * Whether a code can back a new recovery attempt right now. An expired
+ * reservation counts as available, matching `reserveRecoveryCode`.
+ */
+export declare function isRecoveryCodeAvailable(lifecycle: RecoveryCodeLifecycleState, nowMs: number): boolean;
+//# sourceMappingURL=recoveryCodeReservation.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/recoveryCodes.d.ts

@@ -0,0 +1,11 @@
+export { EMAIL_OTP_RECOVERY_KEY_ALPHABET as WALLET_RECOVERY_CODE_ALPHABET, EMAIL_OTP_RECOVERY_KEY_BYTE_LENGTH as WALLET_RECOVERY_CODE_BYTE_LENGTH, EMAIL_OTP_RECOVERY_KEY_CHAR_LENGTH as WALLET_RECOVERY_CODE_CHAR_LENGTH, EMAIL_OTP_RECOVERY_KEY_COUNT as WALLET_RECOVERY_CODE_COUNT, EMAIL_OTP_RECOVERY_KEY_GROUP_COUNT as WALLET_RECOVERY_CODE_GROUP_COUNT, EMAIL_OTP_RECOVERY_KEY_GROUP_LENGTH as WALLET_RECOVERY_CODE_GROUP_LENGTH, buildEmailOtpRecoveryCodeSet as buildWalletRecoveryCodeSet, decodeEmailOtpRecoveryKey as decodeWalletRecoveryCode, formatEmailOtpRecoveryKey as formatWalletRecoveryCode, normalizeEmailOtpRecoveryKey as normalizeWalletRecoveryCode, } from '../utils/emailOtpRecoveryKey';
+export type { EmailOtpRecoveryCode as WalletRecoveryCode, EmailOtpRecoveryCodeSet as WalletRecoveryCodeSet, } from '../utils/emailOtpRecoveryKey';
+export { deriveWalletRecoveryKeyId, deriveWalletRecoveryKeyIdFromBytes, isDerivedWalletRecoveryKeyId, parseDerivedWalletRecoveryKeyId, WALLET_RECOVERY_KEY_ID_PREFIX_V1, } from './recoveryKeyId';
+export type { DerivedWalletRecoveryKeyId } from './recoveryKeyId';
+export { issueWalletRecoveryCodes, zeroizeIssuedWalletRecoveryCodes } from './recoveryCodeIssuance';
+export type { IssuedWalletRecoveryCodes } from './recoveryCodeIssuance';
+export { runWalletRecoveryWithCode } from './recoveryCodeAttempt';
+export type { WalletRecoveryActivationResult, WalletRecoveryAttemptOutcome, } from './recoveryCodeAttempt';
+export { buildWalletRecoveryBackupAcknowledgementV1, parseWalletRecoveryBackupAcknowledgementV1, walletRecoveryBackupIsOutstanding, } from './backupAcknowledgement';
+export type { WalletRecoveryBackupAcknowledgementV1 } from './backupAcknowledgement';
+//# sourceMappingURL=recoveryCodes.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/recoveryEnvelopes.d.ts

@@ -0,0 +1,42 @@
+import type { RecoveryCodeReservationId } from './recoveryCodeReservation';
+/**
+ * Lifecycle of one recovery code.
+ *
+ * `reserved` is a transient hold taken while a recovery runs; consumption
+ * commits only after the replacement credential activates. See
+ * `recoveryCodeReservation.ts` for the transitions between these states.
+ */
+export type RecoveryCodeLifecycleState = {
+    state: 'active';
+    issuedAtMs: number;
+    reservationId?: never;
+    reservedAtMs?: never;
+    reservationExpiresAtMs?: never;
+    consumedAtMs?: never;
+    revokedAtMs?: never;
+} | {
+    state: 'reserved';
+    issuedAtMs: number;
+    reservationId: RecoveryCodeReservationId;
+    reservedAtMs: number;
+    reservationExpiresAtMs: number;
+    consumedAtMs?: never;
+    revokedAtMs?: never;
+} | {
+    state: 'consumed';
+    issuedAtMs: number;
+    reservationId: RecoveryCodeReservationId;
+    consumedAtMs: number;
+    reservedAtMs?: never;
+    reservationExpiresAtMs?: never;
+    revokedAtMs?: never;
+} | {
+    state: 'revoked';
+    issuedAtMs: number;
+    revokedAtMs: number;
+    reservationId?: never;
+    reservedAtMs?: never;
+    reservationExpiresAtMs?: never;
+    consumedAtMs?: never;
+};
+//# sourceMappingURL=recoveryEnvelopes.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/recoveryKekContext.d.ts

@@ -0,0 +1,37 @@
+import type { WalletId } from '../utils/domainIds';
+import type { DerivedWalletRecoveryKeyId } from './recoveryCodes';
+import type { WalletRecoveryEnvelopeEntry } from './walletRecoveryEnvelopeSet';
+/**
+ * Frozen two-level recovery wrap:
+ *
+ *   recovery code --HKDF--> code KEK --opens--> manifest KEK
+ *   manifest KEK --HKDF--> entry KEK --opens--> one custody secret
+ *
+ * A recovery code never wraps a custody entry directly, so rotating codes
+ * rewraps only the 32-byte manifest KEK and never re-opens plaintext roots.
+ */
+/** KEK inputs for one recovery code's wrap of the manifest KEK. */
+export type WalletRecoveryCodeKekDerivationContext = {
+    kind: 'wallet_recovery_code_kek_derivation_context_v1';
+    walletId: WalletId;
+    recoveryKeyId: DerivedWalletRecoveryKeyId;
+    purpose: 'wallet_recovery_manifest_kek';
+};
+/**
+ * KEK inputs for the seed entry's wrap under the manifest KEK.
+ *
+ * A recovery set carries one entry — the wallet custody seed — so the purpose
+ * is fixed. It is still encoded rather than assumed, so adding a second entry
+ * kind later cannot silently reuse this context.
+ */
+export type WalletRecoveryEntryKekDerivationContext = {
+    kind: 'wallet_recovery_entry_kek_derivation_context_v1';
+    walletId: WalletId;
+    purpose: 'wallet_custody_seed_v1';
+};
+/** Derives the entry-level KEK context from a parsed set entry. */
+export declare function buildWalletRecoveryEntryKekDerivationContext(args: {
+    walletId: WalletId;
+    entry: WalletRecoveryEnvelopeEntry;
+}): WalletRecoveryEntryKekDerivationContext;
+//# sourceMappingURL=recoveryKekContext.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/recoveryKeyId.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The identity of one recovery code inside a wallet's custody set.
+ *
+ * **Wallet-scoped, and factor-neutral on purpose.** The Email OTP id it
+ * replaces (`deriveEmailOtpRecoveryKeyId`) puts `enrollmentVersion` and
+ * `enrollmentSealKeyVersion` in its tuple, so it cannot mint an id for a
+ * passkey wallet — which has no enrollment at all. A wallet custody recovery
+ * set belongs to the wallet, not to whichever factor happened to establish it,
+ * exactly as the seed and the continuity cache do.
+ *
+ * The code-wrap crypto around it is already wallet-scoped and unchanged:
+ * `WalletRecoveryCodeScopeV1` is `{ wallet_id, recovery_key_id }`, and
+ * `encode_recovery_manifest_aad_v1` binds a wrap to the set version, wrap
+ * algorithm, wallet id, this id, and the manifest-KEK purpose. This module adds
+ * only the id those bindings name.
+ *
+ * The id is a *label*, not key material. It exists so a stored wrap can be
+ * found by the code the user typed without revealing which code it is: the
+ * digest is one-way, so a stored id identifies a wrap while telling a reader
+ * with the record nothing about the code that opens it.
+ */
+declare const walletRecoveryKeyIdBrand: unique symbol;
+export type DerivedWalletRecoveryKeyId = string & {
+    readonly [walletRecoveryKeyIdBrand]: 'DerivedWalletRecoveryKeyId';
+};
+export declare const WALLET_RECOVERY_KEY_ID_PREFIX_V1: "wallet-rkid-v1-";
+export declare function parseDerivedWalletRecoveryKeyId(value: unknown, label?: string): DerivedWalletRecoveryKeyId;
+export declare function isDerivedWalletRecoveryKeyId(value: unknown): value is DerivedWalletRecoveryKeyId;
+/**
+ * Derives one code's id within a wallet's recovery set.
+ *
+ * Bound to the wallet and the set version, so the same code typed against a
+ * different wallet produces a different id and finds no wrap. Length-delimited
+ * fields under a fixed context, so no two inputs encode alike.
+ *
+ * The decoded code bytes are zeroized before returning, including on failure —
+ * the code is the factor that opens the seed, and it must not outlive this
+ * call in a buffer the caller cannot see.
+ */
+export declare function deriveWalletRecoveryKeyId(args: {
+    readonly recoveryCode: string;
+    readonly walletId: string;
+    readonly setVersion?: string;
+}): Promise<DerivedWalletRecoveryKeyId>;
+/**
+ * The same derivation from decoded bytes.
+ *
+ * Separate entry point because the ceremony seals wraps from bytes it already
+ * holds, while a user typing a code arrives as a string. Both must reach one
+ * id, so both go through this.
+ */
+export declare function deriveWalletRecoveryKeyIdFromBytes(args: {
+    readonly codeBytes: Uint8Array;
+    readonly walletId: string;
+    readonly setVersion?: string;
+}): Promise<DerivedWalletRecoveryKeyId>;
+export {};
+//# sourceMappingURL=recoveryKeyId.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/walletRecovery.typecheck.d.ts

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

package/dist/types/shared-ts/src/wallet-recovery/walletRecoveryCommittedProjection.d.ts

@@ -0,0 +1,110 @@
+import { type ActiveRecoveredWalletAuthorityV1 } from '../authorization/walletAuthority';
+import { type DeviceId } from '../authorization/capabilityKinds';
+import { type EmailOtpProviderUserId, type WalletAuthMethodId, type WalletAuthorityId, type WalletId, type WalletRecoveryOperationId, type WebAuthnCredentialIdB64u, type WebAuthnRpId } from '../utils/domainIds';
+import { type WalletAuthMethodRecordV2 } from '../utils/registrationIntent';
+export type WalletRecoveryEmailOtpEnrollmentReferenceV1 = {
+    readonly kind: 'email_otp_enrollment_reference_v1';
+    readonly enrollmentId: string;
+    readonly enrollmentSealKeyVersion: string;
+};
+type WalletRecoveryCommittedProjectionCommonV1 = {
+    readonly version: 'wallet_recovery_committed_projection_v1';
+    readonly storeVersion: string;
+    readonly walletId: WalletId;
+    readonly recoveryOperationId: WalletRecoveryOperationId;
+    readonly targetDeviceId: DeviceId;
+    readonly targetAuthorityId: WalletAuthorityId;
+    readonly targetWalletAuthMethodId: WalletAuthMethodId;
+    readonly authority: ActiveRecoveredWalletAuthorityV1;
+};
+export type WalletRecoveryCommittedProjectionV1 = (WalletRecoveryCommittedProjectionCommonV1 & {
+    readonly kind: 'passkey';
+    readonly authMethod: Extract<WalletAuthMethodRecordV2, {
+        readonly kind: 'passkey';
+        readonly status: 'active';
+    }>;
+    readonly target: {
+        readonly kind: 'passkey';
+        readonly rpId: WebAuthnRpId;
+        readonly credentialIdB64u: WebAuthnCredentialIdB64u;
+    };
+}) | (WalletRecoveryCommittedProjectionCommonV1 & {
+    readonly kind: 'google_email_otp';
+    readonly authMethod: Extract<WalletAuthMethodRecordV2, {
+        readonly kind: 'email_otp';
+        readonly status: 'active';
+    }>;
+    readonly target: {
+        readonly kind: 'google_email_otp';
+        readonly provider: 'google';
+        readonly providerSubject: EmailOtpProviderUserId;
+        readonly emailHashHex: string;
+        readonly registrationAuthorityId: string;
+        readonly enrollment: WalletRecoveryEmailOtpEnrollmentReferenceV1;
+    };
+});
+export type WalletRecoveryCommittedProjectionExpectationV1 = {
+    readonly kind: 'passkey';
+    readonly walletId: WalletId;
+    readonly recoveryOperationId: WalletRecoveryOperationId;
+    readonly targetDeviceId: DeviceId;
+    readonly targetAuthorityId: WalletAuthorityId;
+    readonly targetWalletAuthMethodId: WalletAuthMethodId;
+    readonly rpId: WebAuthnRpId;
+    readonly credentialIdB64u: WebAuthnCredentialIdB64u;
+} | {
+    readonly kind: 'google_email_otp';
+    readonly walletId: WalletId;
+    readonly recoveryOperationId: WalletRecoveryOperationId;
+    readonly targetDeviceId: DeviceId;
+    readonly targetAuthorityId: WalletAuthorityId;
+    readonly targetWalletAuthMethodId: WalletAuthMethodId;
+    readonly providerSubject: EmailOtpProviderUserId;
+    readonly emailHashHex: string;
+    readonly registrationAuthorityId: string;
+    readonly enrollment: WalletRecoveryEmailOtpEnrollmentReferenceV1;
+};
+export type WalletRecoveryCommittedProjectionBuilderInputV1 = {
+    readonly kind: 'passkey';
+    readonly storeVersion: string;
+    readonly walletId: WalletId;
+    readonly recoveryOperationId: WalletRecoveryOperationId;
+    readonly targetDeviceId: DeviceId;
+    readonly targetAuthorityId: WalletAuthorityId;
+    readonly targetWalletAuthMethodId: WalletAuthMethodId;
+    readonly authority: ActiveRecoveredWalletAuthorityV1;
+    readonly authMethod: Extract<WalletAuthMethodRecordV2, {
+        readonly kind: 'passkey';
+        readonly status: 'active';
+    }>;
+} | {
+    readonly kind: 'google_email_otp';
+    readonly storeVersion: string;
+    readonly walletId: WalletId;
+    readonly recoveryOperationId: WalletRecoveryOperationId;
+    readonly targetDeviceId: DeviceId;
+    readonly targetAuthorityId: WalletAuthorityId;
+    readonly targetWalletAuthMethodId: WalletAuthMethodId;
+    readonly authority: ActiveRecoveredWalletAuthorityV1;
+    readonly authMethod: Extract<WalletAuthMethodRecordV2, {
+        readonly kind: 'email_otp';
+        readonly status: 'active';
+    }>;
+    readonly providerSubject: EmailOtpProviderUserId;
+    readonly emailHashHex: string;
+    readonly registrationAuthorityId: string;
+    readonly enrollment: WalletRecoveryEmailOtpEnrollmentReferenceV1;
+};
+export declare function buildWalletRecoveryCommittedProjectionV1(input: Extract<WalletRecoveryCommittedProjectionBuilderInputV1, {
+    readonly kind: 'passkey';
+}>): Extract<WalletRecoveryCommittedProjectionV1, {
+    readonly kind: 'passkey';
+}>;
+export declare function buildWalletRecoveryCommittedProjectionV1(input: Extract<WalletRecoveryCommittedProjectionBuilderInputV1, {
+    readonly kind: 'google_email_otp';
+}>): Extract<WalletRecoveryCommittedProjectionV1, {
+    readonly kind: 'google_email_otp';
+}>;
+export declare function parseWalletRecoveryCommittedProjectionV1(raw: unknown, expected: WalletRecoveryCommittedProjectionExpectationV1): Promise<WalletRecoveryCommittedProjectionV1>;
+export {};
+//# sourceMappingURL=walletRecoveryCommittedProjection.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/walletRecoveryEcdsaPossession.d.ts

@@ -0,0 +1,29 @@
+import { type DigestB64u } from '../utils/canonicalPrimitives';
+declare const POSSESSION_PROOF_SCHEME_V1 = "secp256k1_bip340_sha256_v1";
+export type WalletRecoveryEcdsaPossessionChallengeV1 = {
+    readonly kind: 'wallet_recovery_ecdsa_possession_challenge_v1';
+    readonly walletId: string;
+    readonly reservationId: string;
+    readonly replacementId: string;
+    readonly keySetId: `evm_family_ecdsa:${string}`;
+    readonly keyHandle: string;
+    readonly recordedKeyManifestDigestB64u: DigestB64u;
+    readonly publicCapabilityDigestB64u: DigestB64u;
+    readonly authorityRefDigestB64u: DigestB64u;
+    readonly derivationClientSharePublicKey33B64u: string;
+    readonly expectedServerGeneration: string;
+    readonly expiresAtMs: number;
+    readonly serverNonceB64u: DigestB64u;
+};
+export type WalletRecoveryEcdsaPossessionProofV1 = {
+    readonly kind: 'wallet_recovery_ecdsa_possession_proof_v1';
+    readonly scheme: typeof POSSESSION_PROOF_SCHEME_V1;
+    readonly signature64B64u: string;
+};
+export declare function parseWalletRecoveryEcdsaPossessionChallengeV1(value: unknown): WalletRecoveryEcdsaPossessionChallengeV1;
+export declare function parseWalletRecoveryEcdsaPossessionProofV1(value: unknown): WalletRecoveryEcdsaPossessionProofV1;
+export declare function walletRecoveryEcdsaPossessionChallengeCanonicalBytesV1(challenge: WalletRecoveryEcdsaPossessionChallengeV1): Uint8Array;
+export declare function walletRecoveryEcdsaPossessionChallengeDigestB64uV1(challenge: WalletRecoveryEcdsaPossessionChallengeV1): Promise<DigestB64u>;
+export declare const WALLET_RECOVERY_ECDSA_POSSESSION_PROOF_SCHEME_V1 = "secp256k1_bip340_sha256_v1";
+export {};
+//# sourceMappingURL=walletRecoveryEcdsaPossession.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/walletRecoveryEnvelopeSet.d.ts

@@ -0,0 +1,115 @@
+import type { WalletId } from '../utils/domainIds';
+import type { DigestB64u } from '../utils/canonicalPrimitives';
+import type { EnvelopeCiphertextB64u, EnvelopeNonceB64u } from '../passkey-custody';
+import type { DerivedWalletRecoveryKeyId } from './recoveryCodes';
+import type { RecoveryCodeLifecycleState } from './recoveryEnvelopes';
+/**
+ * The recovery-wrapped wallet custody seed, sealed under a key derived from the
+ * set's manifest KEK (frozen design: a recovery code wraps a random manifest
+ * KEK; it never wraps entries directly). One seed covers every owner key, so a
+ * partial recovery can never promote a replacement credential.
+ *
+ * Lane holder shares are deliberately absent. A linked device's share is sealed
+ * under that device's own factor, so it never depended on the owner credential
+ * and survives owner recovery untouched; including it here would instead let an
+ * owner recovery code reconstruct that device's material. A lost lane is
+ * revoked and reprovisioned through Refactor 102, not recovered.
+ */
+export type WalletRecoveryEnvelopeEntry = {
+    custodySecretKind: 'wallet_custody_seed_v1';
+    nonceB64u: EnvelopeNonceB64u;
+    wrappedCustodySecretB64u: EnvelopeCiphertextB64u;
+    aadHashB64u: DigestB64u;
+};
+/**
+ * One recovery code's wrap of the set's manifest KEK. Ten of these are issued
+ * with the set; consuming or revoking a code touches only its wrap, never the
+ * entry ciphertexts. The wrapped payload is a 32-byte KEK, never custody
+ * material, a recovery code, or a code digest.
+ */
+export type WalletRecoveryManifestKekWrap = {
+    recoveryKeyId: DerivedWalletRecoveryKeyId;
+    nonceB64u: EnvelopeNonceB64u;
+    wrappedManifestKekB64u: EnvelopeCiphertextB64u;
+    aadHashB64u: DigestB64u;
+    lifecycle: RecoveryCodeLifecycleState;
+};
+export type WalletRecoveryEnvelopeSetRecord = {
+    kind: 'wallet_recovery_envelope_set_v1';
+    walletId: WalletId;
+    /**
+     * No key manifest digest. A set wraps the wallet's seed, and key sets are
+     * provisioned independently with their own manifests, so there is no
+     * wallet-level manifest for a set to name. Rotating one key set no longer
+     * invalidates the seed the set wraps.
+     */
+    manifestKekWraps: readonly WalletRecoveryManifestKekWrap[];
+    entries: readonly WalletRecoveryEnvelopeEntry[];
+    issuedAtMs: number;
+    updatedAtMs: number;
+};
+/** Opaque records emitted by the custody worker for an active-factor rotation.
+ *
+ * Lifecycle timestamps are assigned by the server at the CAS boundary. The
+ * browser therefore cannot carry forward a consumed/reserved code or forge an
+ * issuance timestamp while still returning the exact ciphertext set produced
+ * by WASM.
+ */
+export type WalletRecoverySetRotationWireV1 = {
+    walletId: WalletId;
+    manifestKekWraps: readonly {
+        recoveryKeyId: DerivedWalletRecoveryKeyId;
+        nonceB64u: EnvelopeNonceB64u;
+        ciphertextB64u: EnvelopeCiphertextB64u;
+        aadHashB64u: DigestB64u;
+    }[];
+    entry: WalletRecoveryEnvelopeEntry;
+};
+export declare function buildWalletCustodySeedRecoveryEntry(args: {
+    nonceB64u: EnvelopeNonceB64u;
+    wrappedCustodySecretB64u: EnvelopeCiphertextB64u;
+    aadHashB64u: DigestB64u;
+}): WalletRecoveryEnvelopeEntry;
+export declare function buildWalletRecoveryManifestKekWrap(args: {
+    recoveryKeyId: DerivedWalletRecoveryKeyId;
+    nonceB64u: EnvelopeNonceB64u;
+    wrappedManifestKekB64u: EnvelopeCiphertextB64u;
+    aadHashB64u: DigestB64u;
+    lifecycle: RecoveryCodeLifecycleState;
+}): WalletRecoveryManifestKekWrap;
+export declare function buildWalletRecoveryEnvelopeSetRecord(args: {
+    walletId: WalletId;
+    manifestKekWraps: readonly WalletRecoveryManifestKekWrap[];
+    entries: readonly WalletRecoveryEnvelopeEntry[];
+    issuedAtMs: number;
+    updatedAtMs: number;
+}): WalletRecoveryEnvelopeSetRecord;
+/**
+ * Parses the worker's factor-neutral rotation projection at the request
+ * boundary. It deliberately accepts no lifecycle or timestamp fields; those
+ * are server-owned and are added only while replacing the durable set.
+ */
+export declare function parseWalletRecoverySetRotationWireV1(raw: unknown, options: {
+    expectedWalletId: WalletId;
+    label?: string;
+}): WalletRecoverySetRotationWireV1;
+export declare function parseWalletRecoveryEnvelopeEntry(raw: unknown, label: string): WalletRecoveryEnvelopeEntry;
+/**
+ * Parses one recovery envelope set against the authenticated wallet.
+ *
+ * `expectedWalletId` is required: a recovery set is only meaningful inside the
+ * wallet whose recovery request is being served.
+ *
+ * Owner coverage is no longer a per-key list. Under single-seed custody the
+ * owner entry is one seed covering every owner key, so completeness is the
+ * exactly-one-seed rule below. The key manifest that pins which keys the seed
+ * must reproduce lives on each key set's own registration state and is
+ * verified where the roots are derived — it is deliberately not a field here.
+ */
+export declare function parseWalletRecoveryEnvelopeSetRecord(raw: unknown, options: {
+    expectedWalletId: WalletId;
+    label?: string;
+}): WalletRecoveryEnvelopeSetRecord;
+/** A set is openable while at least one recovery-code wrap remains active. */
+export declare function hasOpenableRecoveryCodeWrap(set: WalletRecoveryEnvelopeSetRecord): boolean;
+//# sourceMappingURL=walletRecoveryEnvelopeSet.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/walletRecoveryRotation.d.ts

@@ -0,0 +1,18 @@
+import type { WalletRecoverySetRotationWireV1 } from './walletRecoveryEnvelopeSet';
+/** Opaque result emitted by the custody WASM after an active factor opens it. */
+export type WalletRecoverySetRotationWorkerResultV1 = {
+    readonly walletId: string;
+    readonly recoveryManifestKekWraps: readonly {
+        readonly recoveryKeyId: string;
+        readonly nonceB64u: string;
+        readonly ciphertextB64u: string;
+        readonly aadHashB64u: string;
+    }[];
+    readonly recoveryEntryNonceB64u: string;
+    readonly recoveryEntryCiphertextB64u: string;
+    readonly recoveryEntryAadHashB64u: string;
+};
+export declare function parseWalletRecoverySetRotationWorkerResultV1(value: unknown): WalletRecoverySetRotationWorkerResultV1;
+/** Projects the Rust/WASM result into the server's full-set wire shape. */
+export declare function walletRecoverySetRotationWireFromWorkerResultV1(value: unknown): WalletRecoverySetRotationWireV1;
+//# sourceMappingURL=walletRecoveryRotation.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/walletRecoveryTarget.d.ts

@@ -0,0 +1,12 @@
+import { type WebAuthnRpId } from '../utils/domainIds';
+export type WalletRecoveryTargetV1 = {
+    readonly kind: 'passkey';
+    readonly rpId: WebAuthnRpId;
+    readonly googleProvider?: never;
+} | {
+    readonly kind: 'google_email_otp';
+    readonly googleProvider: 'google';
+    readonly rpId?: never;
+};
+export declare function parseWalletRecoveryTargetV1(raw: unknown): WalletRecoveryTargetV1;
+//# sourceMappingURL=walletRecoveryTarget.d.ts.map

package/dist/types/shared-ts/src/wallet-recovery/walletRecoveryTarget.typecheck.d.ts

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