@seams/wallet-server 0.5.0

package/dist/esm/shared-ts/src/utils/walletAuthAuthority.js

@@ -0,0 +1,207 @@
+import { parseEmailOtpProviderUserId, parseWalletAuthMethodId, parseWalletAuthorityBindingDigest, parseWalletId, parseWebAuthnCredentialIdB64u, parseWebAuthnRpId } from "./domainIds.js";
+import { base64UrlEncode } from "./base64.js";
+import { alphabetizeStringify, sha256BytesUtf8 } from "./digests.js";
+import "./encoders.js";
+//#region ../shared-ts/src/utils/walletAuthAuthority.ts
+const WALLET_AUTHORITY_BINDING_DIGEST_DOMAIN = "seams:wallet-authority-binding:v1|";
+function isPasskeyWalletAuthAuthority(authority) {
+	return authority.factor.kind === "passkey";
+}
+function isEmailOtpWalletAuthAuthority(authority) {
+	return authority.factor.kind === "email_otp";
+}
+function walletAuthAuthoritiesMatch(left, right) {
+	if (left.walletId !== right.walletId || left.bindingId !== right.bindingId) return false;
+	if (isPasskeyWalletAuthAuthority(left)) {
+		if (!isPasskeyWalletAuthAuthority(right)) return false;
+		return left.factor.credentialIdB64u === right.factor.credentialIdB64u && left.verifier.rpId === right.verifier.rpId;
+	}
+	if (isEmailOtpWalletAuthAuthority(left)) {
+		if (!isEmailOtpWalletAuthAuthority(right)) return false;
+		return left.factor.provider === right.factor.provider && left.factor.providerUserId === right.factor.providerUserId && left.verifier.emailHashHex === right.verifier.emailHashHex;
+	}
+	return false;
+}
+function parseWalletAuthAuthorityRef(raw) {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const record = raw;
+	const fields = Object.keys(record);
+	if (fields.length !== 4 || !fields.every((field) => [
+		"kind",
+		"walletId",
+		"authorityDigest",
+		"walletAuthMethodId"
+	].includes(field)) || record.kind !== "wallet_auth_authority_ref") return null;
+	const walletId = parseWalletId(record.walletId);
+	const authorityDigest = parseWalletAuthorityBindingDigest(record.authorityDigest);
+	const walletAuthMethodId = parseWalletAuthMethodId(record.walletAuthMethodId);
+	if (!walletId.ok || !authorityDigest.ok || !walletAuthMethodId.ok) return null;
+	return {
+		kind: "wallet_auth_authority_ref",
+		walletId: walletId.value,
+		authorityDigest: authorityDigest.value,
+		walletAuthMethodId: walletAuthMethodId.value
+	};
+}
+function parseEmailOtpProvider(raw) {
+	const provider = String(raw || "").trim().toLowerCase();
+	if (provider === "google" || provider === "email") return provider;
+	return null;
+}
+function requireParsed(parsed, message) {
+	if (parsed.ok) return parsed.value;
+	throw new Error(message);
+}
+function hasOwnField(obj, field) {
+	return Object.prototype.hasOwnProperty.call(obj, field);
+}
+function hasAnyOwnField(obj, fields) {
+	for (const field of fields) if (hasOwnField(obj, field)) return true;
+	return false;
+}
+function buildPasskeyWalletAuthAuthority(args) {
+	const walletId = requireParsed(parseWalletId(args.walletId), "Passkey wallet auth authority requires walletId");
+	const rpId = requireParsed(parseWebAuthnRpId(args.rpId), "Passkey wallet auth authority requires rpId");
+	const credentialIdB64u = requireParsed(parseWebAuthnCredentialIdB64u(args.credentialIdB64u), "Passkey wallet auth authority requires credentialIdB64u");
+	const bindingId = requireParsed(parseWalletAuthMethodId(`passkey:${rpId}:${credentialIdB64u}`), "Passkey wallet auth authority requires bindingId");
+	return {
+		walletId,
+		factor: {
+			kind: "passkey",
+			credentialIdB64u
+		},
+		verifier: {
+			kind: "webauthn",
+			rpId
+		},
+		bindingId
+	};
+}
+function buildEmailOtpFactorIdentity(args) {
+	const provider = parseEmailOtpProvider(args.provider);
+	if (!provider) throw new Error("Email OTP factor identity requires provider");
+	return {
+		kind: "email_otp",
+		provider,
+		providerUserId: requireParsed(parseEmailOtpProviderUserId(args.providerUserId), "Email OTP factor identity requires providerUserId")
+	};
+}
+function buildEmailOtpWalletAuthAuthority(args) {
+	const walletId = requireParsed(parseWalletId(args.walletId), "Email OTP wallet auth authority requires walletId");
+	const factor = buildEmailOtpFactorIdentity(args);
+	const emailHashHex = String(args.emailHashHex || "").trim();
+	if (!emailHashHex) throw new Error("Email OTP wallet auth authority requires emailHashHex");
+	const bindingId = requireParsed(parseWalletAuthMethodId(`email_otp:${walletId}:${emailHashHex}`), "Email OTP wallet auth authority requires bindingId");
+	return {
+		walletId,
+		factor,
+		verifier: {
+			kind: "email_otp_wallet_auth_method",
+			emailHashHex
+		},
+		bindingId
+	};
+}
+function parsePasskeyWalletAuthAuthorityObject(obj) {
+	const factor = obj.factor;
+	if (!factor || typeof factor !== "object" || Array.isArray(factor)) return null;
+	const verifier = obj.verifier;
+	if (!verifier || typeof verifier !== "object" || Array.isArray(verifier)) return null;
+	const factorObj = factor;
+	const verifierObj = verifier;
+	const factorKind = String(factorObj.kind || "").trim().toLowerCase();
+	const verifierKind = String(verifierObj.kind || "").trim().toLowerCase();
+	if (factorKind !== "passkey" || verifierKind !== "webauthn") return null;
+	try {
+		if (hasAnyOwnField(obj, [
+			"kind",
+			"rpId",
+			"credentialIdB64u",
+			"provider",
+			"providerUserId"
+		])) return null;
+		const walletId = parseWalletId(obj.walletId);
+		const rpId = parseWebAuthnRpId(verifierObj.rpId);
+		const credentialIdB64u = parseWebAuthnCredentialIdB64u(factorObj.credentialIdB64u);
+		const bindingId = parseWalletAuthMethodId(obj.bindingId);
+		if (!walletId.ok || !rpId.ok || !credentialIdB64u.ok || !bindingId.ok) return null;
+		return {
+			walletId: walletId.value,
+			factor: {
+				kind: "passkey",
+				credentialIdB64u: credentialIdB64u.value
+			},
+			verifier: {
+				kind: "webauthn",
+				rpId: rpId.value
+			},
+			bindingId: bindingId.value
+		};
+	} catch {
+		return null;
+	}
+}
+function parseEmailOtpWalletAuthAuthorityObject(obj) {
+	const factor = obj.factor;
+	if (!factor || typeof factor !== "object" || Array.isArray(factor)) return null;
+	const verifier = obj.verifier;
+	if (!verifier || typeof verifier !== "object" || Array.isArray(verifier)) return null;
+	const factorObj = factor;
+	const verifierObj = verifier;
+	const factorKind = String(factorObj.kind || "").trim().toLowerCase();
+	const verifierKind = String(verifierObj.kind || "").trim().toLowerCase();
+	if (factorKind !== "email_otp" || verifierKind !== "email_otp_wallet_auth_method") return null;
+	try {
+		if (hasAnyOwnField(obj, [
+			"kind",
+			"rpId",
+			"credentialIdB64u",
+			"provider",
+			"providerUserId"
+		])) return null;
+		const walletId = parseWalletId(obj.walletId);
+		const provider = parseEmailOtpProvider(factorObj.provider);
+		const providerUserId = parseEmailOtpProviderUserId(factorObj.providerUserId);
+		const emailHashHex = String(verifierObj.emailHashHex || "").trim();
+		const bindingId = parseWalletAuthMethodId(obj.bindingId);
+		if (!walletId.ok || !provider || !providerUserId.ok || !emailHashHex || !bindingId.ok) return null;
+		return {
+			walletId: walletId.value,
+			factor: {
+				kind: "email_otp",
+				provider,
+				providerUserId: providerUserId.value
+			},
+			verifier: {
+				kind: "email_otp_wallet_auth_method",
+				emailHashHex
+			},
+			bindingId: bindingId.value
+		};
+	} catch {
+		return null;
+	}
+}
+function parseWalletAuthAuthority(raw) {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const obj = raw;
+	return parsePasskeyWalletAuthAuthorityObject(obj) || parseEmailOtpWalletAuthAuthorityObject(obj);
+}
+function canonicalWalletAuthorityBindingDigestInput(args) {
+	return `${WALLET_AUTHORITY_BINDING_DIGEST_DOMAIN}${alphabetizeStringify(args.authority)}`;
+}
+async function walletAuthorityBindingDigest(args) {
+	return requireParsed(parseWalletAuthorityBindingDigest(base64UrlEncode(await sha256BytesUtf8(canonicalWalletAuthorityBindingDigestInput(args)))), "Wallet authority binding digest must be non-empty");
+}
+async function walletAuthAuthorityRef(args) {
+	return {
+		kind: "wallet_auth_authority_ref",
+		walletId: args.authority.walletId,
+		authorityDigest: await walletAuthorityBindingDigest({ authority: args.authority }),
+		walletAuthMethodId: args.authority.bindingId
+	};
+}
+//#endregion
+export { buildEmailOtpWalletAuthAuthority, buildPasskeyWalletAuthAuthority, isEmailOtpWalletAuthAuthority, isPasskeyWalletAuthAuthority, parseWalletAuthAuthority, parseWalletAuthAuthorityRef, walletAuthAuthoritiesMatch, walletAuthAuthorityRef };
+
+//# sourceMappingURL=walletAuthAuthority.js.map

package/dist/esm/shared-ts/src/utils/walletSessionFailure.js

@@ -0,0 +1,15 @@
+//#region ../shared-ts/src/utils/walletSessionFailure.ts
+const WALLET_SESSION_FAILURE_CODES = {
+	missing: "wallet_session_missing",
+	signatureInvalid: "wallet_session_signature_invalid",
+	claimsInvalid: "wallet_session_claims_invalid",
+	invalid: "wallet_session_invalid",
+	expired: "wallet_session_expired",
+	scopeMismatch: "wallet_session_scope_mismatch",
+	unavailable: "wallet_session_unavailable",
+	budgetExhausted: "wallet_budget_exhausted"
+};
+//#endregion
+export { WALLET_SESSION_FAILURE_CODES };
+
+//# sourceMappingURL=walletSessionFailure.js.map

package/dist/esm/shared-ts/src/utils/webauthnDeviceInfo.js

@@ -0,0 +1,207 @@
+//#region ../shared-ts/src/utils/webauthnDeviceInfo.ts
+/** Community-documented AAGUIDs for the passkey providers that matter here.
+* Source: github.com/passkeydeveloper/passkey-authenticator-aaguids */
+const WEBAUTHN_AAGUID_PROVIDERS = {
+	"fbfc3007-154e-4ecc-8c0b-6e020557d7bd": {
+		id: "icloud-keychain",
+		label: "iCloud Keychain"
+	},
+	"dd4ec289-e01d-41c9-bb89-70fa845d4bf2": {
+		id: "icloud-keychain-managed",
+		label: "iCloud Keychain (Managed)"
+	},
+	"ea9b8d66-4d01-1d21-3ce4-b6b48cb575d4": {
+		id: "google-password-manager",
+		label: "Google Password Manager"
+	},
+	"adce0002-35bc-c60a-648b-0b25f1f05503": {
+		id: "chrome-on-mac",
+		label: "Chrome on Mac"
+	},
+	"08987058-cadc-4b81-b6e1-30de50dcbe96": {
+		id: "windows-hello",
+		label: "Windows Hello"
+	},
+	"9ddd1817-af5a-4672-a2b9-3e3dd95000a9": {
+		id: "windows-hello",
+		label: "Windows Hello"
+	},
+	"6028b017-b1d4-4c02-b4b3-afcdafc96bb2": {
+		id: "windows-hello",
+		label: "Windows Hello"
+	},
+	"bada5566-a7aa-401f-bd96-45619a55120d": {
+		id: "1password",
+		label: "1Password"
+	},
+	"d548826e-79b4-db40-a3d8-11116f7e8349": {
+		id: "bitwarden",
+		label: "Bitwarden"
+	},
+	"531126d6-e717-415c-9320-3d9aa6981239": {
+		id: "dashlane",
+		label: "Dashlane"
+	},
+	"53414d53-554e-4700-0000-000000000000": {
+		id: "samsung-pass",
+		label: "Samsung Pass"
+	},
+	"b84e4048-15dc-4dd0-8640-f4f60813c8af": {
+		id: "nordpass",
+		label: "NordPass"
+	},
+	"f3809540-7f14-49c1-a8b3-8f813b225541": {
+		id: "enpass",
+		label: "Enpass"
+	},
+	"b5397666-4885-aa6b-cebf-e52262a439a2": {
+		id: "chromium",
+		label: "Chromium Browser"
+	},
+	"771b48fd-d3d4-4f74-9232-fc157ab0507a": {
+		id: "edge-on-mac",
+		label: "Edge on Mac"
+	}
+};
+const WEBAUTHN_DEVICE_BROWSERS = [
+	"chrome",
+	"safari",
+	"firefox",
+	"edge",
+	"other"
+];
+const WEBAUTHN_DEVICE_OSES = [
+	"macos",
+	"ios",
+	"windows",
+	"android",
+	"linux",
+	"other"
+];
+const BROWSER_DISPLAY = {
+	chrome: "Chrome",
+	safari: "Safari",
+	firefox: "Firefox",
+	edge: "Edge",
+	other: "Browser"
+};
+const OS_DISPLAY = {
+	macos: "macOS",
+	ios: "iOS",
+	windows: "Windows",
+	android: "Android",
+	linux: "Linux",
+	other: ""
+};
+function webAuthnDeviceBrowserFromUserAgent(userAgent) {
+	const ua = userAgent.toLowerCase();
+	if (!ua) return "other";
+	if (ua.includes("edg/") || ua.includes("edge/") || ua.includes("edgios/")) return "edge";
+	if (ua.includes("firefox/") || ua.includes("fxios/")) return "firefox";
+	if (ua.includes("crios/") || ua.includes("chrome/") || ua.includes("chromium/")) return "chrome";
+	if (ua.includes("safari/")) return "safari";
+	return "other";
+}
+function webAuthnDeviceOsFromUserAgent(userAgent) {
+	const ua = userAgent.toLowerCase();
+	if (!ua) return "other";
+	if (ua.includes("iphone") || ua.includes("ipad") || ua.includes("ipod")) return "ios";
+	if (ua.includes("android")) return "android";
+	if (ua.includes("mac os x") || ua.includes("macintosh")) return "macos";
+	if (ua.includes("windows")) return "windows";
+	if (ua.includes("linux") || ua.includes("cros")) return "linux";
+	return "other";
+}
+function webAuthnDeviceLabel(input) {
+	const browser = BROWSER_DISPLAY[input.browser];
+	const os = OS_DISPLAY[input.os];
+	if (input.browser === "other" && input.os === "other") return input.providerLabel || "Unknown device";
+	return os ? `${browser} on ${os}` : browser;
+}
+function normalizedAaguid(aaguid) {
+	return aaguid.trim().toLowerCase();
+}
+/** True for the all-zero AAGUID some platforms report under attestation "none". */
+function isZeroAaguid(aaguid) {
+	return /^0{8}-0{4}-0{4}-0{4}-0{12}$/.test(aaguid) || aaguid === "";
+}
+function deriveWebAuthnAuthenticatorDeviceInfo(input) {
+	const userAgent = String(input.userAgent || "").trim();
+	const browser = webAuthnDeviceBrowserFromUserAgent(userAgent);
+	const os = webAuthnDeviceOsFromUserAgent(userAgent);
+	const aaguid = normalizedAaguid(String(input.aaguid || ""));
+	const providerEntry = isZeroAaguid(aaguid) ? void 0 : WEBAUTHN_AAGUID_PROVIDERS[aaguid];
+	const transports = Array.isArray(input.transports) ? input.transports.map((t) => String(t || "").trim()).filter((t) => t.length > 0) : [];
+	return {
+		label: webAuthnDeviceLabel({
+			browser,
+			os,
+			providerLabel: providerEntry?.label
+		}),
+		browser,
+		os,
+		synced: !!input.backedUp,
+		transports,
+		...providerEntry ? {
+			provider: providerEntry.id,
+			providerLabel: providerEntry.label
+		} : {}
+	};
+}
+/** Fallback for authenticator rows written before device capture existed. */
+function unknownWebAuthnAuthenticatorDeviceInfo() {
+	return {
+		label: "Unknown device",
+		browser: "other",
+		os: "other",
+		synced: false,
+		transports: []
+	};
+}
+/**
+* Boundary parse of a persisted `device_info_json` column. A row written before
+* device capture existed (empty string, `'{}'`, or an unreadable value) becomes
+* `Unknown device` rather than failing the surrounding read.
+*/
+function parseWebAuthnAuthenticatorDeviceInfoJson(raw) {
+	if (typeof raw !== "string" || !raw.trim()) return unknownWebAuthnAuthenticatorDeviceInfo();
+	try {
+		return parseWebAuthnAuthenticatorDeviceInfo(JSON.parse(raw)) ?? unknownWebAuthnAuthenticatorDeviceInfo();
+	} catch {
+		return unknownWebAuthnAuthenticatorDeviceInfo();
+	}
+}
+function isWebAuthnDeviceBrowser(value) {
+	return typeof value === "string" && WEBAUTHN_DEVICE_BROWSERS.some((browser) => browser === value);
+}
+function isWebAuthnDeviceOs(value) {
+	return typeof value === "string" && WEBAUTHN_DEVICE_OSES.some((os) => os === value);
+}
+/** Strict parse of a stored/transported device-info record; null when the
+* shape is not a valid WebAuthnAuthenticatorDeviceInfo. */
+function parseWebAuthnAuthenticatorDeviceInfo(raw) {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+	const record = raw;
+	const label = typeof record.label === "string" ? record.label.trim() : "";
+	if (!label) return null;
+	if (!isWebAuthnDeviceBrowser(record.browser)) return null;
+	if (!isWebAuthnDeviceOs(record.os)) return null;
+	if (typeof record.synced !== "boolean") return null;
+	if (!Array.isArray(record.transports)) return null;
+	const transports = record.transports.map((t) => typeof t === "string" ? t.trim() : "").filter((t) => t.length > 0);
+	const provider = typeof record.provider === "string" ? record.provider.trim() : "";
+	const providerLabel = typeof record.providerLabel === "string" ? record.providerLabel.trim() : "";
+	return {
+		label,
+		browser: record.browser,
+		os: record.os,
+		synced: record.synced,
+		transports,
+		...provider ? { provider } : {},
+		...providerLabel ? { providerLabel } : {}
+	};
+}
+//#endregion
+export { deriveWebAuthnAuthenticatorDeviceInfo, parseWebAuthnAuthenticatorDeviceInfo, parseWebAuthnAuthenticatorDeviceInfoJson, unknownWebAuthnAuthenticatorDeviceInfo };
+
+//# sourceMappingURL=webauthnDeviceInfo.js.map

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

@@ -0,0 +1,66 @@
+//#region ../shared-ts/src/wallet-recovery/backupAcknowledgement.ts
+function parseWalletRecoveryBackupAcknowledgementV1(raw, options) {
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {
+		ok: false,
+		reason: "backup acknowledgement must be an object"
+	};
+	const record = raw;
+	if (record.kind !== "wallet_recovery_backup_acknowledgement_v1") return {
+		ok: false,
+		reason: "backup acknowledgement kind is invalid"
+	};
+	const walletId = String(record.walletId || "").trim();
+	if (!walletId) return {
+		ok: false,
+		reason: "backup acknowledgement must name its wallet"
+	};
+	if (walletId !== String(options.expectedWalletId).trim()) return {
+		ok: false,
+		reason: "backup acknowledgement is outside the requested wallet"
+	};
+	const issuedAtMs = timestamp(record.issuedAtMs);
+	const acknowledgedAtMs = timestamp(record.acknowledgedAtMs);
+	if (issuedAtMs === null || acknowledgedAtMs === null) return {
+		ok: false,
+		reason: "backup acknowledgement needs valid timestamps"
+	};
+	if (acknowledgedAtMs < issuedAtMs) return {
+		ok: false,
+		reason: "backup acknowledgement predates the issuance it names"
+	};
+	return {
+		ok: true,
+		record: {
+			kind: "wallet_recovery_backup_acknowledgement_v1",
+			walletId,
+			issuedAtMs,
+			acknowledgedAtMs
+		}
+	};
+}
+/**
+* Whether the user should still be asked to save their codes.
+*
+* Takes the set's own `issuedAtMs` rather than trusting the acknowledgement
+* alone, so a rotation re-arms the prompt: the stored acknowledgement names
+* the issuance it covered, and a newer set is by definition unacknowledged.
+*/
+function walletRecoveryBackupIsOutstanding(input) {
+	if (!input.acknowledgement) return true;
+	return input.acknowledgement.issuedAtMs !== input.setIssuedAtMs;
+}
+function buildWalletRecoveryBackupAcknowledgementV1(input) {
+	return {
+		kind: "wallet_recovery_backup_acknowledgement_v1",
+		walletId: String(input.walletId).trim(),
+		issuedAtMs: input.issuedAtMs,
+		acknowledgedAtMs: input.acknowledgedAtMs
+	};
+}
+function timestamp(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : null;
+}
+//#endregion
+export { buildWalletRecoveryBackupAcknowledgementV1, parseWalletRecoveryBackupAcknowledgementV1, walletRecoveryBackupIsOutstanding };
+
+//# sourceMappingURL=backupAcknowledgement.js.map

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

@@ -0,0 +1,10 @@
+import "./recoveryCodeReservation.js";
+import "../utils/emailOtpRecoveryKey.js";
+import "./recoveryKeyId.js";
+import "./backupAcknowledgement.js";
+import "./recoveryCodes.js";
+import "./walletRecoveryEnvelopeSet.js";
+import "./recoveryCodeLocator.js";
+import "./walletRecoveryEcdsaPossession.js";
+import "./walletRecoveryRotation.js";
+import "./walletRecoveryCommittedProjection.js";

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

@@ -0,0 +1 @@
+import "../utils/emailOtpRecoveryKey.js";

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

@@ -0,0 +1,34 @@
+import { base64UrlEncode } from "../utils/base64.js";
+import { parseDigestB64u } from "../utils/canonicalPrimitives.js";
+import { sha256Bytes } from "../utils/digests.js";
+import "../utils/encoders.js";
+import "../utils/emailOtpRecoveryKey.js";
+//#region ../shared-ts/src/wallet-recovery/recoveryCodeLocator.ts
+const RECOVERY_CODE_LOCATOR_CONTEXT_V1 = "seams/wallet-recovery/code-locator/v1";
+function parseRecoveryCodeLocatorV1(value, label = "recoveryCodeLocator") {
+	try {
+		return parseDigestB64u(value);
+	} catch (error) {
+		throw new Error(`${label} ${error instanceof Error ? error.message : "must be a canonical digest"}`);
+	}
+}
+async function deriveRecoveryCodeLocatorV1FromBytes(codeBytes) {
+	if (!(codeBytes instanceof Uint8Array) || codeBytes.length !== 20) throw new Error(`recovery code bytes must be exactly 20 bytes`);
+	let tuple = null;
+	try {
+		const contextBytes = new TextEncoder().encode(RECOVERY_CODE_LOCATOR_CONTEXT_V1);
+		tuple = new Uint8Array(8 + contextBytes.length + codeBytes.length);
+		const view = new DataView(tuple.buffer);
+		view.setUint32(0, contextBytes.length, false);
+		tuple.set(contextBytes, 4);
+		view.setUint32(4 + contextBytes.length, codeBytes.length, false);
+		tuple.set(codeBytes, 8 + contextBytes.length);
+		return parseRecoveryCodeLocatorV1(base64UrlEncode(await sha256Bytes(tuple)));
+	} finally {
+		tuple?.fill(0);
+	}
+}
+//#endregion
+export { deriveRecoveryCodeLocatorV1FromBytes, parseRecoveryCodeLocatorV1 };
+
+//# sourceMappingURL=recoveryCodeLocator.js.map

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

@@ -0,0 +1,80 @@
+import { hasWhitespaceOrControlCharacters } from "../utils/domainIds.js";
+import { base64UrlEncode } from "../utils/base64.js";
+import { parseCorrelationId } from "../utils/canonicalPrimitives.js";
+import { alphabetizeStringify, sha256BytesUtf8 } from "../utils/digests.js";
+//#region ../shared-ts/src/wallet-recovery/recoveryCodeReservation.ts
+const WALLET_RECOVERY_KEY_LIFECYCLE_DOMAIN_V1 = "seams/wallet-recovery/key-lifecycle/v1";
+/** One protocol lifecycle below a wallet-scoped recovery reservation. */
+async function deriveWalletRecoveryKeyLifecycleId(input) {
+	const keySetId = String(input.keySetId || "").trim();
+	if (!/^(near_ed25519|evm_family_ecdsa):\S+$/.test(keySetId)) throw new Error("wallet recovery key-set id is invalid");
+	return parseCorrelationId(`wallet-recovery-key-v1:${base64UrlEncode(await sha256BytesUtf8(alphabetizeStringify({
+		domain: WALLET_RECOVERY_KEY_LIFECYCLE_DOMAIN_V1,
+		reservationId: input.reservationId,
+		keySetId
+	})))}`);
+}
+function parseRecoveryCodeReservationId(value) {
+	if (typeof value !== "string" || value.length === 0 || value.length > 512 || value.trim() !== value || hasWhitespaceOrControlCharacters(value)) throw new Error("recovery code reservation id must be a compact opaque identifier");
+	return value;
+}
+function reject(code, message) {
+	return {
+		ok: false,
+		code,
+		message
+	};
+}
+/**
+* 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.
+*/
+function reserveRecoveryCode(args) {
+	const { lifecycle } = args;
+	if (lifecycle.state === "consumed") return reject("already_consumed", "recovery code has already been consumed");
+	if (lifecycle.state === "revoked") return reject("revoked", "recovery code has been revoked");
+	if (args.reservationTtlMs <= 0) return reject("reservation_expired", "reservation ttl must be positive");
+	if (lifecycle.state === "reserved" && lifecycle.reservationExpiresAtMs > args.nowMs && lifecycle.reservationId !== args.reservationId) return reject("already_reserved", "recovery code is reserved by another recovery");
+	return {
+		ok: true,
+		lifecycle: {
+			state: "reserved",
+			issuedAtMs: lifecycle.issuedAtMs,
+			reservationId: args.reservationId,
+			reservedAtMs: args.nowMs,
+			reservationExpiresAtMs: args.nowMs + args.reservationTtlMs
+		}
+	};
+}
+/**
+* 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.
+*/
+function consumeReservedRecoveryCode(args) {
+	const { lifecycle } = args;
+	if (lifecycle.state === "consumed") return reject("already_consumed", "recovery code has already been consumed");
+	if (lifecycle.state === "revoked") return reject("revoked", "recovery code has been revoked");
+	if (lifecycle.state !== "reserved") return reject("not_reserved", "recovery code must be reserved before it is consumed");
+	if (lifecycle.reservationId !== args.reservationId) return reject("reservation_mismatch", "reservation id does not hold this recovery code");
+	if (lifecycle.reservationExpiresAtMs <= args.nowMs) return reject("reservation_expired", "recovery code reservation expired before commit");
+	return {
+		ok: true,
+		lifecycle: {
+			state: "consumed",
+			issuedAtMs: lifecycle.issuedAtMs,
+			reservationId: args.reservationId,
+			consumedAtMs: args.nowMs
+		}
+	};
+}
+//#endregion
+export { consumeReservedRecoveryCode, deriveWalletRecoveryKeyLifecycleId, parseRecoveryCodeReservationId, reserveRecoveryCode };
+
+//# sourceMappingURL=recoveryCodeReservation.js.map

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

@@ -0,0 +1,4 @@
+import "../utils/emailOtpRecoveryKey.js";
+import "./recoveryKeyId.js";
+import "./recoveryCodeIssuance.js";
+import "./backupAcknowledgement.js";