@seams/wallet-server 0.5.0

package/dist/esm/shared-ts/src/wallet-recovery/recoveryKeyId.js

@@ -0,0 +1,53 @@
+import { base64UrlEncode } from "../utils/base64.js";
+import "../utils/encoders.js";
+import { encodeSigningSessionHkdfTuple } from "../utils/signingSessionSeal.js";
+import "../utils/emailOtpRecoveryKey.js";
+//#region ../shared-ts/src/wallet-recovery/recoveryKeyId.ts
+const WALLET_RECOVERY_KEY_ID_PREFIX_V1 = "wallet-rkid-v1-";
+const WALLET_RECOVERY_KEY_ID_CONTEXT_V1 = "seams/wallet-recovery/recovery-key-id/v1";
+const WALLET_RECOVERY_ENVELOPE_SET_VERSION_V1 = "wallet_recovery_envelope_set_v1";
+/** The prefix plus unpadded base64url over one SHA-256 digest. */
+const DERIVED_WALLET_RECOVERY_KEY_ID_PATTERN = /^wallet-rkid-v1-[A-Za-z0-9_-]{43}$/;
+function parseDerivedWalletRecoveryKeyId(value, label = "recoveryKeyId") {
+	if (typeof value !== "string" || !DERIVED_WALLET_RECOVERY_KEY_ID_PATTERN.test(value)) throw new Error(`${label} must be a derived wallet recovery key id`);
+	return value;
+}
+/**
+* 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.
+*/
+async function deriveWalletRecoveryKeyIdFromBytes(args) {
+	const walletId = String(args.walletId || "").trim();
+	if (!walletId) throw new Error("walletId is required to derive a wallet recovery key id");
+	const codeBytes = args.codeBytes;
+	if (!codeBytes?.length) throw new Error("recovery code bytes are required to derive a wallet recovery key id");
+	let tuple = null;
+	try {
+		tuple = encodeSigningSessionHkdfTuple([
+			WALLET_RECOVERY_KEY_ID_CONTEXT_V1,
+			base64UrlEncode(codeBytes),
+			walletId,
+			args.setVersion ?? WALLET_RECOVERY_ENVELOPE_SET_VERSION_V1
+		]);
+		return `${WALLET_RECOVERY_KEY_ID_PREFIX_V1}${base64UrlEncode(await sha256Bytes(tuple))}`;
+	} finally {
+		zeroize(tuple);
+	}
+}
+async function sha256Bytes(input) {
+	const subtle = globalThis.crypto?.subtle;
+	if (!subtle) throw new Error("WebCrypto is unavailable for wallet recovery key id derivation");
+	const buffer = new ArrayBuffer(input.byteLength);
+	new Uint8Array(buffer).set(input);
+	return new Uint8Array(await subtle.digest("SHA-256", buffer));
+}
+function zeroize(value) {
+	if (value) value.fill(0);
+}
+//#endregion
+export { WALLET_RECOVERY_KEY_ID_PREFIX_V1, deriveWalletRecoveryKeyIdFromBytes, parseDerivedWalletRecoveryKeyId };
+
+//# sourceMappingURL=recoveryKeyId.js.map

package/dist/esm/shared-ts/src/wallet-recovery/walletRecoveryCommittedProjection.js

@@ -0,0 +1,108 @@
+import "../authorization/capabilityKinds.js";
+import "../authorization/walletAuthority.js";
+import "../utils/registrationIntent.js";
+//#region ../shared-ts/src/wallet-recovery/walletRecoveryCommittedProjection.ts
+function buildWalletRecoveryCommittedProjectionV1(input) {
+	if (input.kind === "passkey") return buildPasskeyProjection(input);
+	return buildGoogleEmailOtpProjection(input);
+}
+function buildPasskeyProjection(input) {
+	const projection = {
+		version: "wallet_recovery_committed_projection_v1",
+		storeVersion: requireNonEmptyString(input.storeVersion, "storeVersion"),
+		walletId: input.walletId,
+		recoveryOperationId: input.recoveryOperationId,
+		targetDeviceId: input.targetDeviceId,
+		targetAuthorityId: input.targetAuthorityId,
+		targetWalletAuthMethodId: input.targetWalletAuthMethodId,
+		authority: input.authority,
+		kind: "passkey",
+		authMethod: input.authMethod,
+		target: {
+			kind: "passkey",
+			rpId: input.authMethod.rpId,
+			credentialIdB64u: input.authMethod.credentialIdB64u
+		}
+	};
+	assertProjectionShape(projection);
+	return projection;
+}
+function buildGoogleEmailOtpProjection(input) {
+	const projection = {
+		version: "wallet_recovery_committed_projection_v1",
+		storeVersion: requireNonEmptyString(input.storeVersion, "storeVersion"),
+		walletId: input.walletId,
+		recoveryOperationId: input.recoveryOperationId,
+		targetDeviceId: input.targetDeviceId,
+		targetAuthorityId: input.targetAuthorityId,
+		targetWalletAuthMethodId: input.targetWalletAuthMethodId,
+		authority: input.authority,
+		kind: "google_email_otp",
+		authMethod: input.authMethod,
+		target: {
+			kind: "google_email_otp",
+			provider: "google",
+			providerSubject: input.providerSubject,
+			emailHashHex: requireEmailHash(input.emailHashHex),
+			registrationAuthorityId: requireNonEmptyString(input.registrationAuthorityId, "registrationAuthorityId"),
+			enrollment: buildEnrollmentReference(input.enrollment)
+		}
+	};
+	assertProjectionShape(projection);
+	return projection;
+}
+function parseEnrollmentReference(raw) {
+	const record = parseWalletRecoveryEmailOtpEnrollmentWireV1(raw);
+	if (record.kind !== "email_otp_enrollment_reference_v1") throw new Error("wallet recovery Email OTP enrollment is invalid");
+	return {
+		kind: "email_otp_enrollment_reference_v1",
+		enrollmentId: requireNonEmptyString(record.enrollmentId, "enrollment.enrollmentId"),
+		enrollmentSealKeyVersion: requireNonEmptyString(record.enrollmentSealKeyVersion, "enrollment.enrollmentSealKeyVersion")
+	};
+}
+function buildEnrollmentReference(value) {
+	return parseEnrollmentReference(value);
+}
+function assertProjectionShape(projection) {
+	if (projection.authority.walletId !== projection.walletId || projection.authority.authorityId !== projection.targetAuthorityId || projection.authority.principal.deviceId !== projection.targetDeviceId || projection.authority.provenance.kind !== "wallet_recovery" || projection.authority.provenance.recoveryOperationId !== projection.recoveryOperationId || projection.authority.provenance.continuityAuthorityId === projection.targetAuthorityId || projection.authMethod.walletId !== projection.walletId || projection.authMethod.walletAuthorityId !== projection.targetAuthorityId || projection.authMethod.walletAuthMethodId !== projection.targetWalletAuthMethodId || projection.authMethod.status !== "active") throw new Error("wallet recovery committed projection relations are invalid");
+	if (projection.kind === "passkey") {
+		if (projection.authMethod.kind !== "passkey" || projection.target.rpId !== projection.authMethod.rpId || projection.target.credentialIdB64u !== projection.authMethod.credentialIdB64u) throw new Error("wallet recovery passkey projection relations are invalid");
+		return;
+	}
+	if (projection.authMethod.kind !== "email_otp" || projection.target.emailHashHex !== projection.authMethod.emailHashHex || projection.target.registrationAuthorityId !== projection.authMethod.registrationAuthorityId) throw new Error("wallet recovery Google Email OTP projection relations are invalid");
+}
+function parseWalletRecoveryEmailOtpEnrollmentWireV1(value) {
+	const record = inspectRawObject(value);
+	if (record === null) throw new Error("wallet recovery Email OTP enrollment must be an object");
+	requireExactFields(record, [
+		"kind",
+		"enrollmentId",
+		"enrollmentSealKeyVersion"
+	], "wallet recovery Email OTP enrollment");
+	return {
+		kind: Reflect.get(record, "kind"),
+		enrollmentId: Reflect.get(record, "enrollmentId"),
+		enrollmentSealKeyVersion: Reflect.get(record, "enrollmentSealKeyVersion")
+	};
+}
+function inspectRawObject(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function requireExactFields(record, expected, label) {
+	const expectedSet = new Set(expected);
+	const actual = Object.keys(record);
+	if (actual.length !== expected.length || actual.some((field) => !expectedSet.has(field))) throw new Error(`${label} contains unexpected fields`);
+}
+function requireNonEmptyString(value, label) {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(`${label} is invalid`);
+	return value.trim();
+}
+function requireEmailHash(value) {
+	const hash = requireNonEmptyString(value, "emailHashHex");
+	if (!/^[0-9a-f]{64}$/.test(hash)) throw new Error("emailHashHex is invalid");
+	return hash;
+}
+//#endregion
+export { buildWalletRecoveryCommittedProjectionV1 };
+
+//# sourceMappingURL=walletRecoveryCommittedProjection.js.map

package/dist/esm/shared-ts/src/wallet-recovery/walletRecoveryEcdsaPossession.js

@@ -0,0 +1,157 @@
+import { base64UrlDecode, base64UrlEncode } from "../utils/base64.js";
+import { parseDigestB64u } from "../utils/canonicalPrimitives.js";
+import { sha256Bytes } from "../utils/digests.js";
+//#region ../shared-ts/src/wallet-recovery/walletRecoveryEcdsaPossession.ts
+const POSSESSION_CHALLENGE_DOMAIN_V1 = "seams/wallet-recovery/ecdsa-existing-material-possession/v1";
+const POSSESSION_PROOF_SCHEME_V1 = "secp256k1_bip340_sha256_v1";
+function requireRecord(value, label) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+	return value;
+}
+function requireExactKeys(record, label, keys) {
+	const allowed = new Set(keys);
+	for (const key of Object.keys(record)) if (!allowed.has(key)) throw new Error(`${label}.${key} is not a supported field`);
+	for (const key of keys) if (!Object.hasOwn(record, key)) throw new Error(`${label}.${key} is required`);
+}
+function requireVisibleIdentifier(value, label) {
+	if (typeof value !== "string" || value.length === 0 || value.trim() !== value) throw new Error(`${label} must be a non-empty canonical identifier`);
+	for (let index = 0; index < value.length; index += 1) {
+		const code = value.charCodeAt(index);
+		if (code < 33 || code > 126) throw new Error(`${label} must contain visible ASCII bytes`);
+	}
+	return value;
+}
+function isEcdsaKeySetId(value) {
+	return value.startsWith("evm_family_ecdsa:") && value.length > 17;
+}
+function requireEcdsaKeySetId(value, label) {
+	const keySetId = requireVisibleIdentifier(value, label);
+	if (!isEcdsaKeySetId(keySetId)) throw new Error(`${label} must identify an ECDSA key set`);
+	return keySetId;
+}
+function requireDigest(value, label) {
+	try {
+		return parseDigestB64u(value);
+	} catch {
+		throw new Error(`${label} must be canonical base64url for 32 bytes`);
+	}
+}
+function requireCompressedPublicKey(value, label) {
+	if (typeof value !== "string" || !/^[A-Za-z0-9_-]+$/.test(value)) throw new Error(`${label} must be canonical base64url`);
+	let bytes;
+	try {
+		bytes = base64UrlDecode(value);
+	} catch {
+		throw new Error(`${label} must be valid base64url`);
+	}
+	if (bytes.length !== 33 || bytes[0] !== 2 && bytes[0] !== 3 || base64UrlEncode(bytes) !== value) throw new Error(`${label} must be canonical compressed secp256k1 public key bytes`);
+	return value;
+}
+function requirePositiveSafeInteger(value, label) {
+	if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) throw new Error(`${label} must be a positive safe integer`);
+	return value;
+}
+function requireSignature64(value, label) {
+	if (typeof value !== "string" || !/^[A-Za-z0-9_-]+$/.test(value)) throw new Error(`${label} must be canonical base64url`);
+	let bytes;
+	try {
+		bytes = base64UrlDecode(value);
+	} catch {
+		throw new Error(`${label} must be valid base64url`);
+	}
+	if (bytes.length !== 64 || base64UrlEncode(bytes) !== value) throw new Error(`${label} must be canonical base64url for 64 bytes`);
+	return value;
+}
+function parseWalletRecoveryEcdsaPossessionChallengeV1(value) {
+	const record = requireRecord(value, "walletRecoveryEcdsaPossessionChallenge");
+	requireExactKeys(record, "walletRecoveryEcdsaPossessionChallenge", [
+		"kind",
+		"walletId",
+		"reservationId",
+		"replacementId",
+		"keySetId",
+		"keyHandle",
+		"recordedKeyManifestDigestB64u",
+		"publicCapabilityDigestB64u",
+		"authorityRefDigestB64u",
+		"derivationClientSharePublicKey33B64u",
+		"expectedServerGeneration",
+		"expiresAtMs",
+		"serverNonceB64u"
+	]);
+	if (record.kind !== "wallet_recovery_ecdsa_possession_challenge_v1") throw new Error("walletRecoveryEcdsaPossessionChallenge.kind is invalid");
+	const keySetId = requireEcdsaKeySetId(record.keySetId, "walletRecoveryEcdsaPossessionChallenge.keySetId");
+	return {
+		kind: "wallet_recovery_ecdsa_possession_challenge_v1",
+		walletId: requireVisibleIdentifier(record.walletId, "walletRecoveryEcdsaPossessionChallenge.walletId"),
+		reservationId: requireVisibleIdentifier(record.reservationId, "walletRecoveryEcdsaPossessionChallenge.reservationId"),
+		replacementId: requireVisibleIdentifier(record.replacementId, "walletRecoveryEcdsaPossessionChallenge.replacementId"),
+		keySetId,
+		keyHandle: requireVisibleIdentifier(record.keyHandle, "walletRecoveryEcdsaPossessionChallenge.keyHandle"),
+		recordedKeyManifestDigestB64u: requireDigest(record.recordedKeyManifestDigestB64u, "walletRecoveryEcdsaPossessionChallenge.recordedKeyManifestDigestB64u"),
+		publicCapabilityDigestB64u: requireDigest(record.publicCapabilityDigestB64u, "walletRecoveryEcdsaPossessionChallenge.publicCapabilityDigestB64u"),
+		authorityRefDigestB64u: requireDigest(record.authorityRefDigestB64u, "walletRecoveryEcdsaPossessionChallenge.authorityRefDigestB64u"),
+		derivationClientSharePublicKey33B64u: requireCompressedPublicKey(record.derivationClientSharePublicKey33B64u, "walletRecoveryEcdsaPossessionChallenge.derivationClientSharePublicKey33B64u"),
+		expectedServerGeneration: requireVisibleIdentifier(record.expectedServerGeneration, "walletRecoveryEcdsaPossessionChallenge.expectedServerGeneration"),
+		expiresAtMs: requirePositiveSafeInteger(record.expiresAtMs, "walletRecoveryEcdsaPossessionChallenge.expiresAtMs"),
+		serverNonceB64u: requireDigest(record.serverNonceB64u, "walletRecoveryEcdsaPossessionChallenge.serverNonceB64u")
+	};
+}
+function parseWalletRecoveryEcdsaPossessionProofV1(value) {
+	const record = requireRecord(value, "walletRecoveryEcdsaPossessionProof");
+	requireExactKeys(record, "walletRecoveryEcdsaPossessionProof", [
+		"kind",
+		"scheme",
+		"signature64B64u"
+	]);
+	if (record.kind !== "wallet_recovery_ecdsa_possession_proof_v1") throw new Error("walletRecoveryEcdsaPossessionProof.kind is invalid");
+	if (record.scheme !== POSSESSION_PROOF_SCHEME_V1) throw new Error("walletRecoveryEcdsaPossessionProof.scheme is invalid");
+	return {
+		kind: "wallet_recovery_ecdsa_possession_proof_v1",
+		scheme: POSSESSION_PROOF_SCHEME_V1,
+		signature64B64u: requireSignature64(record.signature64B64u, "walletRecoveryEcdsaPossessionProof.signature64B64u")
+	};
+}
+function walletRecoveryEcdsaPossessionChallengeCanonicalBytesV1(challenge) {
+	const parsed = parseWalletRecoveryEcdsaPossessionChallengeV1(challenge);
+	const fields = [
+		POSSESSION_CHALLENGE_DOMAIN_V1,
+		POSSESSION_PROOF_SCHEME_V1,
+		parsed.walletId,
+		parsed.reservationId,
+		parsed.replacementId,
+		parsed.keySetId,
+		parsed.keyHandle,
+		base64UrlDecode(parsed.recordedKeyManifestDigestB64u),
+		base64UrlDecode(parsed.publicCapabilityDigestB64u),
+		base64UrlDecode(parsed.authorityRefDigestB64u),
+		base64UrlDecode(parsed.derivationClientSharePublicKey33B64u),
+		parsed.expectedServerGeneration,
+		base64UrlDecode(parsed.serverNonceB64u),
+		expiryBytes(parsed.expiresAtMs)
+	];
+	const output = [];
+	for (const field of fields) {
+		const bytes = typeof field === "string" ? new TextEncoder().encode(field) : field;
+		const length = bytes.length;
+		if (length > 4294967295) throw new Error("wallet recovery possession field is too large");
+		output.push(length >>> 24 & 255, length >>> 16 & 255, length >>> 8 & 255, length & 255, ...bytes);
+	}
+	return Uint8Array.from(output);
+}
+function expiryBytes(value) {
+	let remaining = BigInt(value);
+	const bytes = new Uint8Array(8);
+	for (let index = bytes.length - 1; index >= 0; index -= 1) {
+		bytes[index] = Number(remaining & 255n);
+		remaining >>= 8n;
+	}
+	return bytes;
+}
+async function walletRecoveryEcdsaPossessionChallengeDigestB64uV1(challenge) {
+	return parseDigestB64u(base64UrlEncode(await sha256Bytes(walletRecoveryEcdsaPossessionChallengeCanonicalBytesV1(challenge))));
+}
+//#endregion
+export { parseWalletRecoveryEcdsaPossessionChallengeV1, parseWalletRecoveryEcdsaPossessionProofV1, walletRecoveryEcdsaPossessionChallengeCanonicalBytesV1, walletRecoveryEcdsaPossessionChallengeDigestB64uV1 };
+
+//# sourceMappingURL=walletRecoveryEcdsaPossession.js.map

package/dist/esm/shared-ts/src/wallet-recovery/walletRecoveryEnvelopeSet.js

@@ -0,0 +1,233 @@
+import { parseWalletId } from "../utils/domainIds.js";
+import { parseDigestField, parseEnvelopeCiphertextB64u, parseEnvelopeNonceB64u, parseUnixMs, rejectUnknownFields, requireRecord } from "../passkey-custody/primitives.js";
+import "../passkey-custody/index.js";
+import { parseRecoveryCodeReservationId } from "./recoveryCodeReservation.js";
+import { parseDerivedWalletRecoveryKeyId } from "./recoveryKeyId.js";
+import "./recoveryCodes.js";
+//#region ../shared-ts/src/wallet-recovery/walletRecoveryEnvelopeSet.ts
+function buildWalletCustodySeedRecoveryEntry(args) {
+	return {
+		custodySecretKind: "wallet_custody_seed_v1",
+		nonceB64u: args.nonceB64u,
+		wrappedCustodySecretB64u: args.wrappedCustodySecretB64u,
+		aadHashB64u: args.aadHashB64u
+	};
+}
+function buildWalletRecoveryManifestKekWrap(args) {
+	return {
+		recoveryKeyId: args.recoveryKeyId,
+		nonceB64u: args.nonceB64u,
+		wrappedManifestKekB64u: args.wrappedManifestKekB64u,
+		aadHashB64u: args.aadHashB64u,
+		lifecycle: args.lifecycle
+	};
+}
+function buildWalletRecoveryEnvelopeSetRecord(args) {
+	return {
+		kind: "wallet_recovery_envelope_set_v1",
+		walletId: args.walletId,
+		manifestKekWraps: args.manifestKekWraps,
+		entries: args.entries,
+		issuedAtMs: args.issuedAtMs,
+		updatedAtMs: args.updatedAtMs
+	};
+}
+/**
+* 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.
+*/
+function parseWalletRecoverySetRotationWireV1(raw, options) {
+	const label = options.label || "walletRecoverySetRotation";
+	const record = requireRecord(raw, label);
+	rejectUnknownFields(record, ROTATION_SET_FIELDS, label);
+	const walletId = parseWalletId(record.walletId);
+	if (!walletId.ok) throw new Error(`${label}.walletId ${walletId.error.message}`);
+	if (String(walletId.value) !== String(options.expectedWalletId)) throw new Error(`${label}.walletId is outside the authenticated wallet`);
+	if (!Array.isArray(record.manifestKekWraps)) throw new Error(`${label}.manifestKekWraps must be an array`);
+	if (record.manifestKekWraps.length !== 10) throw new Error(`${label}.manifestKekWraps must carry exactly 10 recovery-code wraps`);
+	const manifestKekWraps = record.manifestKekWraps.map((rawWrap, index) => {
+		const wrap = requireRecord(rawWrap, `${label}.manifestKekWraps[${index}]`);
+		rejectUnknownFields(wrap, ROTATION_WRAP_FIELDS, `${label}.manifestKekWraps[${index}]`);
+		return {
+			recoveryKeyId: parseDerivedWalletRecoveryKeyId(wrap.recoveryKeyId, `${label}.manifestKekWraps[${index}].recoveryKeyId`),
+			nonceB64u: parseEnvelopeNonceB64u(wrap.nonceB64u, `${label}.manifestKekWraps[${index}].nonceB64u`),
+			ciphertextB64u: parseEnvelopeCiphertextB64u(wrap.ciphertextB64u, `${label}.manifestKekWraps[${index}].ciphertextB64u`),
+			aadHashB64u: parseDigestField(wrap.aadHashB64u, `${label}.manifestKekWraps[${index}].aadHashB64u`)
+		};
+	});
+	const seen = /* @__PURE__ */ new Set();
+	for (const wrap of manifestKekWraps) {
+		const id = String(wrap.recoveryKeyId);
+		if (!seen.add(id)) throw new Error(`${label} contains duplicate recovery key ids`);
+	}
+	if (!Array.isArray(record.entries) || record.entries.length !== 1) throw new Error(`${label}.entries must carry exactly one wallet custody seed entry`);
+	const entry = parseWalletRecoveryEnvelopeEntry(record.entries[0], `${label}.entries[0]`);
+	return {
+		walletId: walletId.value,
+		manifestKekWraps,
+		entry
+	};
+}
+function parseRecoveryCodeLifecycleState(raw, label) {
+	const record = requireRecord(raw, label);
+	rejectUnknownFields(record, RECOVERY_LIFECYCLE_FIELDS, label);
+	const issuedAtMs = parseUnixMs(record.issuedAtMs, `${label}.issuedAtMs`);
+	switch (record.state) {
+		case "active":
+			if (record.consumedAtMs !== void 0 || record.revokedAtMs !== void 0) throw new Error(`${label} cannot be active and carry a consumed or revoked timestamp`);
+			if (record.reservationId !== void 0) throw new Error(`${label} cannot be active and hold a reservation`);
+			return {
+				state: "active",
+				issuedAtMs
+			};
+		case "reserved": {
+			if (record.consumedAtMs !== void 0 || record.revokedAtMs !== void 0) throw new Error(`${label} cannot be reserved and carry a consumed or revoked timestamp`);
+			if (typeof record.reservationId !== "string" || !record.reservationId) throw new Error(`${label}.reservationId is required while reserved`);
+			const reservedAtMs = parseUnixMs(record.reservedAtMs, `${label}.reservedAtMs`);
+			const reservationExpiresAtMs = parseUnixMs(record.reservationExpiresAtMs, `${label}.reservationExpiresAtMs`);
+			if (reservedAtMs < issuedAtMs) throw new Error(`${label}.reservedAtMs cannot precede issuance`);
+			if (reservationExpiresAtMs <= reservedAtMs) throw new Error(`${label}.reservationExpiresAtMs must follow reservedAtMs`);
+			return {
+				state: "reserved",
+				issuedAtMs,
+				reservationId: parseRecoveryCodeReservationId(record.reservationId),
+				reservedAtMs,
+				reservationExpiresAtMs
+			};
+		}
+		case "consumed": {
+			if (record.revokedAtMs !== void 0) throw new Error(`${label} cannot be consumed and carry a revoked timestamp`);
+			if (typeof record.reservationId !== "string" || !record.reservationId) throw new Error(`${label}.reservationId is required after consumption`);
+			const consumedAtMs = parseUnixMs(record.consumedAtMs, `${label}.consumedAtMs`);
+			if (consumedAtMs < issuedAtMs) throw new Error(`${label}.consumedAtMs cannot precede issuance`);
+			return {
+				state: "consumed",
+				issuedAtMs,
+				reservationId: parseRecoveryCodeReservationId(record.reservationId),
+				consumedAtMs
+			};
+		}
+		case "revoked": {
+			if (record.consumedAtMs !== void 0) throw new Error(`${label} cannot be revoked and carry a consumed timestamp`);
+			const revokedAtMs = parseUnixMs(record.revokedAtMs, `${label}.revokedAtMs`);
+			if (revokedAtMs < issuedAtMs) throw new Error(`${label}.revokedAtMs cannot precede issuance`);
+			return {
+				state: "revoked",
+				issuedAtMs,
+				revokedAtMs
+			};
+		}
+		default: throw new Error(`${label}.state must be active, reserved, consumed, or revoked`);
+	}
+}
+const RECOVERY_ENTRY_FIELDS = [
+	"custodySecretKind",
+	"nonceB64u",
+	"wrappedCustodySecretB64u",
+	"aadHashB64u"
+];
+const ROTATION_WRAP_FIELDS = [
+	"recoveryKeyId",
+	"nonceB64u",
+	"ciphertextB64u",
+	"aadHashB64u"
+];
+const ROTATION_SET_FIELDS = [
+	"walletId",
+	"manifestKekWraps",
+	"entries"
+];
+const MANIFEST_KEK_WRAP_FIELDS = [
+	"recoveryKeyId",
+	"nonceB64u",
+	"wrappedManifestKekB64u",
+	"aadHashB64u",
+	"lifecycle"
+];
+const RECOVERY_SET_FIELDS = [
+	"kind",
+	"walletId",
+	"manifestKekWraps",
+	"entries",
+	"issuedAtMs",
+	"updatedAtMs"
+];
+const RECOVERY_LIFECYCLE_FIELDS = [
+	"state",
+	"issuedAtMs",
+	"reservationId",
+	"reservedAtMs",
+	"reservationExpiresAtMs",
+	"consumedAtMs",
+	"revokedAtMs"
+];
+function parseWalletRecoveryEnvelopeEntry(raw, label) {
+	const record = requireRecord(raw, label);
+	rejectUnknownFields(record, RECOVERY_ENTRY_FIELDS, label);
+	if (record.custodySecretKind !== "wallet_custody_seed_v1") throw new Error(`${label}.custodySecretKind must be wallet_custody_seed_v1; lane holder shares are reprovisioned, not recovered`);
+	return buildWalletCustodySeedRecoveryEntry({
+		nonceB64u: parseEnvelopeNonceB64u(record.nonceB64u, `${label}.nonceB64u`),
+		wrappedCustodySecretB64u: parseEnvelopeCiphertextB64u(record.wrappedCustodySecretB64u, `${label}.wrappedCustodySecretB64u`),
+		aadHashB64u: parseDigestField(record.aadHashB64u, `${label}.aadHashB64u`)
+	});
+}
+function parseWalletRecoveryManifestKekWrap(raw, label) {
+	const record = requireRecord(raw, label);
+	rejectUnknownFields(record, MANIFEST_KEK_WRAP_FIELDS, label);
+	return buildWalletRecoveryManifestKekWrap({
+		recoveryKeyId: parseDerivedWalletRecoveryKeyId(record.recoveryKeyId, `${label}.recoveryKeyId`),
+		nonceB64u: parseEnvelopeNonceB64u(record.nonceB64u, `${label}.nonceB64u`),
+		wrappedManifestKekB64u: parseEnvelopeCiphertextB64u(record.wrappedManifestKekB64u, `${label}.wrappedManifestKekB64u`),
+		aadHashB64u: parseDigestField(record.aadHashB64u, `${label}.aadHashB64u`),
+		lifecycle: parseRecoveryCodeLifecycleState(record.lifecycle, `${label}.lifecycle`)
+	});
+}
+/**
+* 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.
+*/
+function parseWalletRecoveryEnvelopeSetRecord(raw, options) {
+	const label = options.label || "walletRecoveryEnvelopeSet";
+	const record = requireRecord(raw, label);
+	if (record.kind !== "wallet_recovery_envelope_set_v1") throw new Error(`${label}.kind must be wallet_recovery_envelope_set_v1`);
+	rejectUnknownFields(record, RECOVERY_SET_FIELDS, label);
+	const walletId = parseWalletId(record.walletId);
+	if (!walletId.ok) throw new Error(`${label}.walletId ${walletId.error.message}`);
+	if (String(walletId.value) !== String(options.expectedWalletId)) throw new Error(`${label}.walletId is outside the authenticated wallet`);
+	if (!Array.isArray(record.manifestKekWraps)) throw new Error(`${label}.manifestKekWraps must be an array`);
+	if (record.manifestKekWraps.length !== 10) throw new Error(`${label}.manifestKekWraps must carry exactly 10 recovery-code wraps`);
+	const manifestKekWraps = record.manifestKekWraps.map((wrap, index) => parseWalletRecoveryManifestKekWrap(wrap, `${label}.manifestKekWraps[${index}]`));
+	const seenRecoveryKeyIds = /* @__PURE__ */ new Set();
+	for (const wrap of manifestKekWraps) {
+		const recoveryKeyId = String(wrap.recoveryKeyId);
+		if (seenRecoveryKeyIds.has(recoveryKeyId)) throw new Error(`${label}.manifestKekWraps has duplicate recoveryKeyId ${recoveryKeyId}`);
+		seenRecoveryKeyIds.add(recoveryKeyId);
+	}
+	if (!Array.isArray(record.entries)) throw new Error(`${label}.entries must be an array`);
+	if (record.entries.length === 0) throw new Error(`${label}.entries must cover at least one wallet key`);
+	const entries = record.entries.map((entry, index) => parseWalletRecoveryEnvelopeEntry(entry, `${label}.entries[${index}]`));
+	if (entries.length !== 1) throw new Error(`${label}.entries must contain exactly one wallet_custody_seed_v1 entry, found ${entries.length}`);
+	const issuedAtMs = parseUnixMs(record.issuedAtMs, `${label}.issuedAtMs`);
+	const updatedAtMs = parseUnixMs(record.updatedAtMs, `${label}.updatedAtMs`);
+	if (updatedAtMs < issuedAtMs) throw new Error(`${label}.updatedAtMs cannot precede issuedAtMs`);
+	return buildWalletRecoveryEnvelopeSetRecord({
+		walletId: walletId.value,
+		manifestKekWraps,
+		entries,
+		issuedAtMs,
+		updatedAtMs
+	});
+}
+//#endregion
+export { buildWalletCustodySeedRecoveryEntry, buildWalletRecoveryEnvelopeSetRecord, buildWalletRecoveryManifestKekWrap, parseWalletRecoveryEnvelopeEntry, parseWalletRecoveryEnvelopeSetRecord, parseWalletRecoverySetRotationWireV1 };
+
+//# sourceMappingURL=walletRecoveryEnvelopeSet.js.map

package/dist/esm/shared-ts/src/wallet-recovery/walletRecoveryRotation.js

@@ -0,0 +1,3 @@
+import "../passkey-custody/index.js";
+import "./recoveryCodes.js";
+import "./walletRecoveryEnvelopeSet.js";

package/dist/esm/shared-ts/src/wallet-recovery/walletRecoveryTarget.js

@@ -0,0 +1,29 @@
+import { parseWebAuthnRpId } from "../utils/domainIds.js";
+//#region ../shared-ts/src/wallet-recovery/walletRecoveryTarget.ts
+function parseWalletRecoveryTargetV1(raw) {
+	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) throw new Error("wallet recovery target must be an object");
+	const record = raw;
+	const fields = Object.keys(record);
+	switch (record.kind) {
+		case "passkey": {
+			if (fields.length !== 2 || !fields.includes("rpId")) throw new Error("Passkey recovery target fields are invalid");
+			const rpId = parseWebAuthnRpId(record.rpId);
+			if (!rpId.ok) throw new Error("Passkey recovery target RP ID is invalid");
+			return {
+				kind: "passkey",
+				rpId: rpId.value
+			};
+		}
+		case "google_email_otp":
+			if (fields.length !== 2 || !fields.includes("googleProvider") || record.googleProvider !== "google") throw new Error("Google Email OTP recovery target fields are invalid");
+			return {
+				kind: "google_email_otp",
+				googleProvider: "google"
+			};
+		default: throw new Error("wallet recovery target kind is unsupported");
+	}
+}
+//#endregion
+export { parseWalletRecoveryTargetV1 };
+
+//# sourceMappingURL=walletRecoveryTarget.js.map

package/dist/esm/storage/d1Sql.js

@@ -0,0 +1,85 @@
+//#region src/storage/d1Sql.ts
+function d1DatabaseProbe(value) {
+	if (!value || typeof value !== "object") return null;
+	return value;
+}
+function collapseD1SchemaWhitespace(statement) {
+	let output = "";
+	let inSingleQuote = false;
+	let pendingSpace = false;
+	for (let index = 0; index < statement.length; index += 1) {
+		const char = statement[index];
+		if (char === "'") {
+			if (pendingSpace && output) output += " ";
+			pendingSpace = false;
+			output += char;
+			if (inSingleQuote && statement[index + 1] === "'") {
+				output += "'";
+				index += 1;
+			} else inSingleQuote = !inSingleQuote;
+			continue;
+		}
+		if (!inSingleQuote && /\s/.test(char)) {
+			pendingSpace = Boolean(output);
+			continue;
+		}
+		if (pendingSpace && output) output += " ";
+		pendingSpace = false;
+		output += char;
+	}
+	return output.trim();
+}
+function formatD1ExecStatement(statement) {
+	const sql = collapseD1SchemaWhitespace(statement);
+	if (!sql) throw new Error("D1 exec statement must be non-empty");
+	return sql.endsWith(";") ? sql : `${sql};`;
+}
+async function queryD1One(database, text, values) {
+	return await database.prepare(text).bind(...values).first();
+}
+async function queryD1All(database, text, values) {
+	return (await database.prepare(text).bind(...values).all()).results || [];
+}
+function d1ChangedRows(result) {
+	const changes = Number(result.meta?.changes ?? result.meta?.rows_written ?? 0);
+	return Number.isFinite(changes) ? Math.max(0, Math.trunc(changes)) : 0;
+}
+function d1Number(value, fallback = 0) {
+	const parsed = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(parsed) ? parsed : fallback;
+}
+function d1Integer(value, fallback = 0) {
+	const parsed = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(parsed) ? Math.trunc(parsed) : fallback;
+}
+function parseD1JsonColumn(value) {
+	if (typeof value !== "string") return value;
+	try {
+		return JSON.parse(value);
+	} catch {
+		return null;
+	}
+}
+function parseD1JsonArrayColumn(value) {
+	const parsed = parseD1JsonColumn(value);
+	return Array.isArray(parsed) ? parsed : [];
+}
+function parseD1JsonObjectColumn(value) {
+	const parsed = parseD1JsonColumn(value);
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+	return { ...parsed };
+}
+function isD1DatabaseLike(value) {
+	const probe = d1DatabaseProbe(value);
+	return Boolean(probe && typeof probe.prepare === "function" && typeof probe.batch === "function" && typeof probe.exec === "function");
+}
+function resolveD1DatabaseFromConfig(config) {
+	if (isD1DatabaseLike(config.database)) return config.database;
+	if (isD1DatabaseLike(config.metadataDatabase)) return config.metadataDatabase;
+	if (isD1DatabaseLike(config.SIGNER_DB)) return config.SIGNER_DB;
+	return null;
+}
+//#endregion
+export { d1ChangedRows, d1Integer, d1Number, formatD1ExecStatement, isD1DatabaseLike, parseD1JsonArrayColumn, parseD1JsonColumn, parseD1JsonObjectColumn, queryD1All, queryD1One, resolveD1DatabaseFromConfig };
+
+//# sourceMappingURL=d1Sql.js.map