@interop/wallet-core 0.6.0 → 0.7.0

package/dist/recovery/index.js

@@ -0,0 +1,28 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/recovery` subpath: recovery codes on the roster
+ * identity model -- a code as a minimal always-enrolled wallet client.
+ *
+ * - `generateRecoveryCode` / `formatRecoveryCode` / `normalizeRecoveryCode` /
+ *   `decodeRecoveryCode` / `RECOVERY_KDF` -- the format layer and the code's
+ *   own unlock-derivation parameter set (its salt distinct from every other
+ *   unlock method's).
+ * - `recoveryClientFromCode` -- the deterministic client key set:
+ *   unlock identity, client seed (signing + key-agreement pair), and the
+ *   single did:webvh update key whose hash stands pre-committed.
+ * - `wrapRecoveryRecord` / `unwrapRecoveryRecord` -- the keyring-record
+ *   sibling carrying the account pointer plus the pre-minted
+ *   PUT-on-`did.jsonl` delegation (never a seed, never a PUK wrap).
+ * - `publishRecoveryKey` / `removeRecoveryKey` / `recoverWebvhClient` -- the
+ *   document half: issuance's split posture, revocation's removal, and the
+ *   self-enrolling recovery continuation.
+ *
+ * Kept out of the root export: this subpath pulls the webkms-client / ezcap /
+ * was-client dependency graph (the same isolation pattern as `./keyring`).
+ */
+export { decodeRecoveryCode, formatRecoveryCode, generateRecoveryCode, normalizeRecoveryCode, RECOVERY_CODE_BYTES, RECOVERY_KDF, RecoveryCodeInvalidError, recoveryClientFromCode } from './recoveryCode.js';
+export { unwrapRecoveryRecord, wrapRecoveryRecord } from './recoveryRecord.js';
+export { publishRecoveryKey, recoverWebvhClient, RecoveryKeyNotCommittedError, recoveryVmId, removeRecoveryKey } from './recoveryWebvh.js';
+//# sourceMappingURL=index.js.map

package/dist/recovery/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/recovery/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAG9E,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,YAAY,EACZ,iBAAiB,EAClB,MAAM,oBAAoB,CAAA"}

package/dist/recovery/recoveryCode.d.ts

@@ -0,0 +1,105 @@
+import type { ProfileAgents } from '../identity/agents.js';
+import type { UnlockKdf } from '../keyring/kdf.js';
+/**
+ * The byte length of a recovery code: 16 random bytes is ~128 bits, enough
+ * that the unlock derivation is a single expansion rather than a stretched
+ * KDF (there is nothing to stretch -- the code is already uniform).
+ */
+export declare const RECOVERY_CODE_BYTES = 16;
+/**
+ * HKDF parameters for the recovery-code unlock derivation
+ * (`unlockSeed = HKDF(codeBytes)`). The salt differs from every other unlock
+ * method's salt, so a code and a passphrase that stringify alike can never
+ * derive the same unlock Space; as with the other unlock KDFs, `version` pins
+ * the parameter set and the salt is permanent.
+ */
+export declare const RECOVERY_KDF: UnlockKdf;
+/**
+ * Thrown for text that is not a well-formed recovery code (characters outside
+ * the base58 alphabet, or the wrong decoded length). Deliberately distinct
+ * from "no account found for this code" -- a malformed code was mistyped; a
+ * well-formed code that resolves to nothing was never issued or has been
+ * revoked.
+ */
+export declare class RecoveryCodeInvalidError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Generates a fresh recovery code: 16 random bytes, base58-encoded.
+ *
+ * @returns {string}
+ */
+export declare function generateRecoveryCode(): string;
+/**
+ * Renders a recovery code in dash-separated groups of four for display
+ * ("6yCL-Ho5s-..."). Purely cosmetic; `normalizeRecoveryCode` strips the
+ * grouping back out on entry.
+ *
+ * @param options {object}
+ * @param options.code {string}
+ * @returns {string}
+ */
+export declare function formatRecoveryCode({ code }: {
+    code: string;
+}): string;
+/**
+ * Normalizes user-entered recovery code text: strips whitespace and the
+ * display dashes. Base58 is case-sensitive, so casing is preserved.
+ *
+ * @param options {object}
+ * @param options.input {string}
+ * @returns {string}
+ */
+export declare function normalizeRecoveryCode({ input }: {
+    input: string;
+}): string;
+/**
+ * Decodes a (possibly formatted) recovery code back to its 16 bytes,
+ * throwing `RecoveryCodeInvalidError` on anything malformed.
+ *
+ * @param options {object}
+ * @param options.code {string}   the user-entered code (grouping tolerated)
+ * @returns {Uint8Array}
+ */
+export declare function decodeRecoveryCode({ code }: {
+    code: string;
+}): Uint8Array;
+/**
+ * The code's full client identity, derived deterministically from
+ * its bytes: the 32-byte client seed (behind the code's Ed25519 signing pair
+ * and X25519 key-agreement twin), the single did:webvh update-key seed (one
+ * key, no staged pair -- a code is spent on use, so it never self-rotates;
+ * its recovery continuation commits whatever it needs next), the derived
+ * agents, and the public multibases / ids the issuance and recovery flows
+ * publish and look up.
+ */
+export interface RecoveryClient {
+    codeBytes: Uint8Array;
+    clientSeed: Uint8Array;
+    updateSeed: Uint8Array;
+    agents: ProfileAgents;
+    clientDid: string;
+    signingKeyMultibase: string;
+    keyAgreementKeyMultibase: string;
+    updateKeyMultibase: string;
+    /**
+     * The kid of the code's PUK-roster entry -- its key-agreement key's id
+     * exactly as `agentsFromSeed` derives it (`did:key:<ed>#<x>`), so the wrap
+     * minted at issuance is the one the recovery flow's roster read looks for.
+     */
+    recipientKid: string;
+}
+/**
+ * Derives the code's whole client identity from a (possibly formatted) code.
+ * Deterministic: the same code always yields the same key set. Throws
+ * `RecoveryCodeInvalidError` on malformed text; whether the derived identity
+ * actually unlocks anything is the caller's question.
+ *
+ * @param options {object}
+ * @param options.code {string}   the recovery code (grouping tolerated)
+ * @returns {Promise<RecoveryClient>}
+ */
+export declare function recoveryClientFromCode({ code }: {
+    code: string;
+}): Promise<RecoveryClient>;
+//# sourceMappingURL=recoveryCode.d.ts.map

package/dist/recovery/recoveryCode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoveryCode.d.ts","sourceRoot":"","sources":["../../src/recovery/recoveryCode.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAGlD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAE,SAM1B,CAAA;AAWD;;;;;;GAMG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,SAAuC;CAI3D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAI7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAErE;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,KAAK,EAAE,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE1E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAazE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,UAAU,CAAA;IACrB,UAAU,EAAE,UAAU,CAAA;IACtB,UAAU,EAAE,UAAU,CAAA;IACtB,MAAM,EAAE,aAAa,CAAA;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,mBAAmB,EAAE,MAAM,CAAA;IAC3B,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,EAAE,MAAM,CAAA;IAC1B;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,IAAI,EACL,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;CACb,GAAG,OAAO,CAAC,cAAc,CAAC,CAmC1B"}

package/dist/recovery/recoveryCode.js

@@ -0,0 +1,155 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The recovery-code format layer and its deterministic derivations. A recovery
+ * code is 16 random bytes rendered as base58 (Bitcoin alphabet), shown to the
+ * user exactly once at issuance. Under the roster identity model the code is a
+ * **minimal always-enrolled wallet client**: everything the code needs to
+ * act -- the unlock identity that locates its keyring record, the client
+ * key set behind its `keyAgreement` verification method and PUK-roster wrap,
+ * and the did:webvh update key whose hash stands pre-committed in
+ * `nextKeyHashes` -- derives deterministically from the code's bytes, so the
+ * key material exists nowhere until the code is typed.
+ *
+ * The derivations are wire-level: two wallet apps must produce byte-identical
+ * output for the same code, or a code issued in one could not recover in the
+ * other. Every salt below is therefore permanent -- changing one orphans every
+ * issued code.
+ */
+import { base58 } from '@scure/base';
+import { hkdf } from '@noble/hashes/hkdf.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { agentsFromSeed } from '../identity/agents.js';
+import { updateKeyMultibase } from '../webvh/didWebvh.js';
+/**
+ * The byte length of a recovery code: 16 random bytes is ~128 bits, enough
+ * that the unlock derivation is a single expansion rather than a stretched
+ * KDF (there is nothing to stretch -- the code is already uniform).
+ */
+export const RECOVERY_CODE_BYTES = 16;
+/**
+ * HKDF parameters for the recovery-code unlock derivation
+ * (`unlockSeed = HKDF(codeBytes)`). The salt differs from every other unlock
+ * method's salt, so a code and a passphrase that stringify alike can never
+ * derive the same unlock Space; as with the other unlock KDFs, `version` pins
+ * the parameter set and the salt is permanent.
+ */
+export const RECOVERY_KDF = {
+    version: 1,
+    algorithm: 'HKDF',
+    hash: 'SHA-256',
+    salt: 'freewallet/keyring/recovery-code/v1',
+    info: 'freewallet/unlock-seed'
+};
+/**
+ * The HKDF salt for the code's client-side key set (distinct from the unlock
+ * salt above, so the unlock identity and the client identity can never
+ * collide), and the per-key expansion labels. All permanent.
+ */
+const RECOVERY_CLIENT_SALT = 'freewallet/recovery/client-keys/v1';
+const RECOVERY_CLIENT_SEED_INFO = 'client-seed';
+const RECOVERY_UPDATE_SEED_INFO = 'update-key';
+/**
+ * Thrown for text that is not a well-formed recovery code (characters outside
+ * the base58 alphabet, or the wrong decoded length). Deliberately distinct
+ * from "no account found for this code" -- a malformed code was mistyped; a
+ * well-formed code that resolves to nothing was never issued or has been
+ * revoked.
+ */
+export class RecoveryCodeInvalidError extends Error {
+    constructor(message = 'This is not a valid recovery code.') {
+        super(message);
+        this.name = 'RecoveryCodeInvalidError';
+    }
+}
+/**
+ * Generates a fresh recovery code: 16 random bytes, base58-encoded.
+ *
+ * @returns {string}
+ */
+export function generateRecoveryCode() {
+    const bytes = new Uint8Array(RECOVERY_CODE_BYTES);
+    crypto.getRandomValues(bytes);
+    return base58.encode(bytes);
+}
+/**
+ * Renders a recovery code in dash-separated groups of four for display
+ * ("6yCL-Ho5s-..."). Purely cosmetic; `normalizeRecoveryCode` strips the
+ * grouping back out on entry.
+ *
+ * @param options {object}
+ * @param options.code {string}
+ * @returns {string}
+ */
+export function formatRecoveryCode({ code }) {
+    return code.replace(/(.{4})(?=.)/g, '$1-');
+}
+/**
+ * Normalizes user-entered recovery code text: strips whitespace and the
+ * display dashes. Base58 is case-sensitive, so casing is preserved.
+ *
+ * @param options {object}
+ * @param options.input {string}
+ * @returns {string}
+ */
+export function normalizeRecoveryCode({ input }) {
+    return input.replace(/[\s-]+/g, '');
+}
+/**
+ * Decodes a (possibly formatted) recovery code back to its 16 bytes,
+ * throwing `RecoveryCodeInvalidError` on anything malformed.
+ *
+ * @param options {object}
+ * @param options.code {string}   the user-entered code (grouping tolerated)
+ * @returns {Uint8Array}
+ */
+export function decodeRecoveryCode({ code }) {
+    const normalized = normalizeRecoveryCode({ input: code });
+    let bytes;
+    try {
+        // Throws on characters outside the base58 alphabet.
+        bytes = base58.decode(normalized);
+    }
+    catch {
+        throw new RecoveryCodeInvalidError();
+    }
+    if (bytes.length !== RECOVERY_CODE_BYTES) {
+        throw new RecoveryCodeInvalidError();
+    }
+    return bytes;
+}
+/**
+ * Derives the code's whole client identity from a (possibly formatted) code.
+ * Deterministic: the same code always yields the same key set. Throws
+ * `RecoveryCodeInvalidError` on malformed text; whether the derived identity
+ * actually unlocks anything is the caller's question.
+ *
+ * @param options {object}
+ * @param options.code {string}   the recovery code (grouping tolerated)
+ * @returns {Promise<RecoveryClient>}
+ */
+export async function recoveryClientFromCode({ code }) {
+    const codeBytes = decodeRecoveryCode({ code });
+    const salt = new TextEncoder().encode(RECOVERY_CLIENT_SALT);
+    const clientSeed = hkdf(sha256, codeBytes, salt, new TextEncoder().encode(RECOVERY_CLIENT_SEED_INFO), 32);
+    const updateSeed = hkdf(sha256, codeBytes, salt, new TextEncoder().encode(RECOVERY_UPDATE_SEED_INFO), 32);
+    const agents = await agentsFromSeed({ seed: clientSeed });
+    const { publicKeyMultibase: keyAgreementKeyMultibase } = agents.keyAgreementKey;
+    if (!keyAgreementKeyMultibase) {
+        throw new Error('The derived key-agreement key has no public multibase.');
+    }
+    const [, , signingKeyMultibase] = agents.keyAgent.id.split(':');
+    return {
+        codeBytes,
+        clientSeed,
+        updateSeed,
+        agents,
+        clientDid: agents.keyAgent.id,
+        signingKeyMultibase: signingKeyMultibase,
+        keyAgreementKeyMultibase,
+        updateKeyMultibase: await updateKeyMultibase({ seed: updateSeed }),
+        recipientKid: `${agents.keyAgent.id}#${keyAgreementKeyMultibase}`
+    };
+}
+//# sourceMappingURL=recoveryCode.js.map

package/dist/recovery/recoveryCode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoveryCode.js","sourceRoot":"","sources":["../../src/recovery/recoveryCode.ts"],"names":[],"mappings":"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"}

package/dist/recovery/recoveryRecord.d.ts

@@ -0,0 +1,75 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The recovery keyring record codec: the `{ version, wrapped }` envelope
+ * stored as the one resource of a recovery code's unlock Space. Its plaintext
+ * is the ordinary keyring record's (controller, email, account pointer) PLUS
+ * the pre-minted PUT-on-`did.jsonl` delegation -- the narrow zcap bridge that
+ * lets the code-derived client write its self-enrolling log continuation. It
+ * carries **no key material of any kind**: never a seed, never a PUK wrap
+ * (wraps live doc-and-roster only), so the record stays a pure pointer.
+ *
+ * The wrap reuses the keyring cipher context verbatim, so a recovery record
+ * IS a keyring record to every generic consumer (an ordinary
+ * `unwrapKeyringRecord` recovers its pointer and ignores the extra member) --
+ * only the recovery flow demands the delegation.
+ */
+import type { IKeyAgreementKey, IKeyResolver, IZcap } from '@interop/data-integrity-core';
+import type { AccountPointer } from '../keyring/record.js';
+/**
+ * The unwrapped contents of a recovery keyring record: the ordinary record
+ * members plus the required delegation. `pointer` is required -- a recovery
+ * record exists only on WAS deployments (there is nothing to recover toward
+ * without a Space).
+ */
+export interface RecoveryRecordContents {
+    controller: string;
+    email?: string;
+    pointer: AccountPointer;
+    delegation: IZcap;
+}
+/**
+ * Wraps the recovery record: controller, email, pointer, and the pre-minted
+ * `did.jsonl` PUT delegation, encrypted under the code's unlock KAK via the
+ * keyring EDV cipher context.
+ *
+ * @param options {object}
+ * @param options.controller {string}   the account did:key
+ * @param [options.email] {string}   the account email, when known
+ * @param options.pointer {AccountPointer}   the account pointer
+ * @param options.delegation {IZcap}   the PUT-on-`did.jsonl` delegation to the
+ *   code-derived signing DID
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the code's unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @returns {Promise<{ version: number, wrapped: unknown }>}
+ */
+export declare function wrapRecoveryRecord({ controller, email, pointer, delegation, keyAgreementKey, keyResolver }: {
+    controller: string;
+    email?: string;
+    pointer: AccountPointer;
+    delegation: IZcap;
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+}): Promise<{
+    version: number;
+    wrapped: unknown;
+}>;
+/**
+ * Unwraps and validates a recovery record: the ordinary keyring-record checks
+ * plus the required pointer and delegation. A record without a delegation is
+ * not a recovery record (an ordinary keyring record found under a code's
+ * unlock Space would mean a corrupted issuance) and is refused.
+ *
+ * @param options {object}
+ * @param options.record {unknown}   the stored `{ version, wrapped }` envelope
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the code's unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @returns {Promise<RecoveryRecordContents>}
+ */
+export declare function unwrapRecoveryRecord({ record, keyAgreementKey, keyResolver }: {
+    record: unknown;
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+}): Promise<RecoveryRecordContents>;
+//# sourceMappingURL=recoveryRecord.d.ts.map

package/dist/recovery/recoveryRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoveryRecord.d.ts","sourceRoot":"","sources":["../../src/recovery/recoveryRecord.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACN,MAAM,8BAA8B,CAAA;AAOrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,KAAK,CAAA;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,UAAU,EACV,KAAK,EACL,OAAO,EACP,UAAU,EACV,eAAe,EACf,WAAW,EACZ,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,KAAK,CAAA;IACjB,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAqBjD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,MAAM,EACN,eAAe,EACf,WAAW,EACZ,EAAE;IACD,MAAM,EAAE,OAAO,CAAA;IACf,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA+ClC"}

package/dist/recovery/recoveryRecord.js

@@ -0,0 +1,89 @@
+import { createEdvDocCipher } from '@interop/was-client/edv';
+import { KEYRING_COLLECTION } from '../space/collections.js';
+import { KEYRING_RECORD_VERSION, parseRecordPointer } from '../keyring/record.js';
+/**
+ * Wraps the recovery record: controller, email, pointer, and the pre-minted
+ * `did.jsonl` PUT delegation, encrypted under the code's unlock KAK via the
+ * keyring EDV cipher context.
+ *
+ * @param options {object}
+ * @param options.controller {string}   the account did:key
+ * @param [options.email] {string}   the account email, when known
+ * @param options.pointer {AccountPointer}   the account pointer
+ * @param options.delegation {IZcap}   the PUT-on-`did.jsonl` delegation to the
+ *   code-derived signing DID
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the code's unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @returns {Promise<{ version: number, wrapped: unknown }>}
+ */
+export async function wrapRecoveryRecord({ controller, email, pointer, delegation, keyAgreementKey, keyResolver }) {
+    const cipher = await createEdvDocCipher({
+        keyAgreementKey,
+        keyResolver,
+        collectionId: KEYRING_COLLECTION.id
+    });
+    const data = {
+        controller,
+        ...(email ? { email } : {}),
+        pointer: {
+            ...(pointer.did ? { did: pointer.did } : {}),
+            spaceId: pointer.spaceId,
+            host: pointer.host
+        },
+        delegation,
+        createdAt: new Date().toISOString()
+    };
+    const { envelope } = await cipher.encrypt({
+        data: data
+    });
+    return { version: KEYRING_RECORD_VERSION, wrapped: envelope };
+}
+/**
+ * Unwraps and validates a recovery record: the ordinary keyring-record checks
+ * plus the required pointer and delegation. A record without a delegation is
+ * not a recovery record (an ordinary keyring record found under a code's
+ * unlock Space would mean a corrupted issuance) and is refused.
+ *
+ * @param options {object}
+ * @param options.record {unknown}   the stored `{ version, wrapped }` envelope
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the code's unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @returns {Promise<RecoveryRecordContents>}
+ */
+export async function unwrapRecoveryRecord({ record, keyAgreementKey, keyResolver }) {
+    if (record === null || typeof record !== 'object') {
+        throw new Error('Malformed recovery record.');
+    }
+    const { version, wrapped } = record;
+    if (version !== KEYRING_RECORD_VERSION) {
+        throw new Error(`Unsupported recovery record version "${String(version)}".`);
+    }
+    const cipher = await createEdvDocCipher({
+        keyAgreementKey,
+        keyResolver,
+        collectionId: KEYRING_COLLECTION.id
+    });
+    const plaintext = (await cipher.decrypt({
+        envelope: wrapped
+    }));
+    if (typeof plaintext.controller !== 'string' || !plaintext.controller) {
+        throw new Error('Recovery record is missing a controller.');
+    }
+    const pointer = parseRecordPointer(plaintext.pointer);
+    if (!pointer) {
+        throw new Error('Recovery record is missing its account pointer.');
+    }
+    if (plaintext.delegation === null ||
+        typeof plaintext.delegation !== 'object') {
+        throw new Error('Recovery record is missing its did.jsonl delegation.');
+    }
+    return {
+        controller: plaintext.controller,
+        ...(typeof plaintext.email === 'string' && plaintext.email
+            ? { email: plaintext.email }
+            : {}),
+        pointer,
+        delegation: plaintext.delegation
+    };
+}
+//# sourceMappingURL=recoveryRecord.js.map

package/dist/recovery/recoveryRecord.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoveryRecord.js","sourceRoot":"","sources":["../../src/recovery/recoveryRecord.ts"],"names":[],"mappings":"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"}

package/dist/recovery/recoveryWebvh.d.ts

@@ -0,0 +1,126 @@
+import type { ClientWebvhUpdateKeys, WebvhEnrollmentKeys, WebvhIdStore } from '../webvh/didWebvh.js';
+/**
+ * The verification-method id a code's key-agreement key publishes under --
+ * the ordinary `<did>#<multibase>` form, indistinguishable by id from any
+ * other keyAgreement entry. Consumers that must exclude recovery entries do
+ * it structurally (an enrolled client is a `capabilityInvocation` entry; a
+ * recovery key never has one) or by the registry's recorded multibase.
+ *
+ * @param options {object}
+ * @param options.did {string}   the account's did:webvh
+ * @param options.keyAgreementKeyMultibase {string}
+ * @returns {string}
+ */
+export declare function recoveryVmId({ did, keyAgreementKeyMultibase }: {
+    did: string;
+    keyAgreementKeyMultibase: string;
+}): string;
+/**
+ * The public halves of a recovery code as the document and log carry them:
+ * the X25519 key-agreement key published as the recovery VM, and the update
+ * key whose hash stands in `nextKeyHashes`.
+ */
+export interface RecoveryPublicKeys {
+    keyAgreementKeyMultibase: string;
+    updateKeyMultibase: string;
+}
+/**
+ * Thrown by the recovery continuation when the log carries neither the code's
+ * update key nor its committed hash -- the code was revoked (or never
+ * issued), so no continuation can verify.
+ */
+export declare class RecoveryKeyNotCommittedError extends Error {
+    constructor(message?: string);
+}
+/**
+ * The narrow store seam the recovery continuation writes through: a public
+ * read of the log and the delegated `did.jsonl` PUT. A subset of
+ * {@link WebvhIdStore}, so an app's remote-store class satisfies it too.
+ */
+export type RecoveryLogStore = Pick<WebvhIdStore, 'getIdResourceRaw' | 'putIdResource'>;
+/**
+ * ISSUANCE (run by an enrolled client, root authority): publishes a recovery
+ * code's split posture into the document -- one entry adding the code's
+ * `keyAgreement` verification method (an ordinary, unmarked Multikey entry)
+ * and committing its update-key hash in `nextKeyHashes`. The code's update
+ * key joins `updateKeys` nowhere. Idempotent: a posture already published is
+ * a no-op, so re-running a torn issuance converges.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   the ISSUING client's
+ *   own did:webvh update-key seeds
+ * @param options.recovery {RecoveryPublicKeys}   the code's public halves
+ * @returns {Promise<{ did: string }>}
+ */
+export declare function publishRecoveryKey({ idStore, updateKeys, recovery }: {
+    idStore: WebvhIdStore;
+    updateKeys: ClientWebvhUpdateKeys;
+    recovery: RecoveryPublicKeys;
+}): Promise<{
+    did: string;
+}>;
+/**
+ * REVOCATION (run by an enrolled client, root authority): removes a recovery
+ * code's posture from the document -- its `keyAgreement` verification method
+ * and its committed update-key hash -- in one entry. Idempotent. The
+ * roster-side half (rotating the PUK epoch off the code's wrap) is the
+ * caller's, and runs after this so the resolver's document no longer backs
+ * the removed entry.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   the REVOKING client's
+ *   own did:webvh update-key seeds
+ * @param options.recovery {RecoveryPublicKeys}   the code's public halves
+ * @returns {Promise<{ did: string }>}
+ */
+export declare function removeRecoveryKey({ idStore, updateKeys, recovery }: {
+    idStore: WebvhIdStore;
+    updateKeys: ClientWebvhUpdateKeys;
+    recovery: RecoveryPublicKeys;
+}): Promise<{
+    did: string;
+}>;
+/**
+ * RECOVERY (run by the code-derived client through the delegated `did.jsonl`
+ * PUT): writes the self-enrolling continuation described in the module doc --
+ * the reveal-and-commit entry signed by the code's pre-committed update key,
+ * then the add-and-retire entry signed by the new ordinary client's update
+ * key. Resumable from durable state alone: a completed continuation is
+ * detected by the new client's update key already being authorized (no-op),
+ * a torn one by the standing commitments (the commit step re-runs
+ * convergently -- the spent code's hash is deliberately carried through the
+ * commit entry, so a resumed commit can re-state the revealed key).
+ *
+ * @param options {object}
+ * @param options.store {RecoveryLogStore}   public log read + delegated PUT
+ * @param options.recovery {object}   the spent code's update seed and public
+ *   halves
+ * @param options.recovery.updateSeed {Uint8Array}
+ * @param options.recovery.keyAgreementKeyMultibase {string}
+ * @param options.recovery.updateKeyMultibase {string}
+ * @param options.newClientKeys {WebvhEnrollmentKeys}   the new ordinary
+ *   client's public halves
+ * @param options.newClientUpdateSeeds {ClientWebvhUpdateKeys}   the new
+ *   client's update-key seeds (minted by the recovery flow, which therefore
+ *   holds them and can sign the add entry)
+ * @param options.replacement {RecoveryPublicKeys}   the replacement code's
+ *   public halves, committed and published in the same continuation
+ * @returns {Promise<{ did: string, webDoc?: object }>}   the account DID and,
+ *   when the add entry ran here, the final `did.json` projection for the
+ *   recovered session to republish
+ */
+export declare function recoverWebvhClient({ store, recovery, newClientKeys, newClientUpdateSeeds, replacement }: {
+    store: RecoveryLogStore;
+    recovery: RecoveryPublicKeys & {
+        updateSeed: Uint8Array;
+    };
+    newClientKeys: WebvhEnrollmentKeys;
+    newClientUpdateSeeds: ClientWebvhUpdateKeys;
+    replacement: RecoveryPublicKeys;
+}): Promise<{
+    did: string;
+    webDoc?: object;
+}>;
+//# sourceMappingURL=recoveryWebvh.d.ts.map

package/dist/recovery/recoveryWebvh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recoveryWebvh.d.ts","sourceRoot":"","sources":["../../src/recovery/recoveryWebvh.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EACV,qBAAqB,EAErB,mBAAmB,EACnB,YAAY,EACb,MAAM,sBAAsB,CAAA;AAE7B;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,EAC3B,GAAG,EACH,wBAAwB,EACzB,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;IACX,wBAAwB,EAAE,MAAM,CAAA;CACjC,GAAG,MAAM,CAET;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB,EAAE,MAAM,CAAA;IAChC,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;gBAEnD,OAAO,SACuC;CAKjD;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,YAAY,EACZ,kBAAkB,GAAG,eAAe,CACrC,CAAA;AA0ED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,OAAO,EACP,UAAU,EACV,QAAQ,EACT,EAAE;IACD,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,QAAQ,EAAE,kBAAkB,CAAA;CAC7B,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAyD3B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,OAAO,EACP,UAAU,EACV,QAAQ,EACT,EAAE;IACD,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,QAAQ,EAAE,kBAAkB,CAAA;CAC7B,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAkD3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,KAAK,EACL,QAAQ,EACR,aAAa,EACb,oBAAoB,EACpB,WAAW,EACZ,EAAE;IACD,KAAK,EAAE,gBAAgB,CAAA;IACvB,QAAQ,EAAE,kBAAkB,GAAG;QAAE,UAAU,EAAE,UAAU,CAAA;KAAE,CAAA;IACzD,aAAa,EAAE,mBAAmB,CAAA;IAClC,oBAAoB,EAAE,qBAAqB,CAAA;IAC3C,WAAW,EAAE,kBAAkB,CAAA;CAChC,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsI5C"}