@interop/wallet-core 0.39.0 → 0.41.0

package/dist/recovery/recoveryRecord.d.ts

@@ -1,80 +1,172 @@
-/*!
- * Copyright (c) 2026 Interop Alliance. All rights reserved.
- */
+import type { IKeyAgreementKey, IKeyResolver, IZcap } from '@interop/data-integrity-core';
+import type { AccountPointer, RecordSigner, SignedRecord } from '../keyring/record.js';
 /**
- * The recovery keyring record codec: the `{ version, encryption, 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 user key wrap (wraps live doc-and-roster only), so the record stays
- * a pure pointer.
- *
- * The wrap reuses the keyring record construction verbatim (cipher context and
- * record-own epoch alike), 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.
+ * A recovery record's account binding is absent, malformed, or does not
+ * verify under the typed code's binding MAC key. Its own class, distinct from
+ * a proof or decrypt failure: this is the refusal that says the record's
+ * `{ controller, pointer }` core was not written by a holder of this code --
+ * a forged record redirecting recovery at another account, or a record from
+ * before the account moved hosts (either way the code cannot recover here
+ * and must be re-issued).
  */
-import type { IKeyAgreementKey, IKeyResolver, IZcap } from '@interop/data-integrity-core';
-import type { CollectionEncryption } from '@interop/was-client';
-import type { AccountPointer } from '../keyring/record.js';
+export declare class RecoveryBindingError extends Error {
+    constructor(message: string);
+}
 /**
- * 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).
+ * The unwrapped contents of a recovery keyring record: the code-authenticated
+ * account binding (controller + pointer) plus the delegation and bind
+ * timestamp. `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;
+    createdAt: string;
+}
+/**
+ * A stored recovery record: the shared signed frame plus the account-binding
+ * tag the frame proof also covers.
+ */
+export interface SignedRecoveryRecord extends SignedRecord {
+    binding: string;
 }
 /**
- * Wraps the recovery record: controller, email, pointer, and the pre-minted
+ * Where a recovery record's proof stands after the unwrap: `'verified'` when
+ * the code-derived unlock key signed it (checked before decryption), or a
+ * pending marker naming the signer the caller must still check against the
+ * account's verified did:webvh document -- the re-mint case, where an enrolled
+ * client signed on the code's behalf. The pending case is a value the caller
+ * cannot ignore by accident: the shell is not trustworthy until
+ * `verifyRecordProof` is run against the document-listed keys. The account
+ * the document belongs to is the one the code-authenticated pointer names --
+ * the binding is verified either way, so the pending state defers the shell's
+ * authenticity only, never the account identity.
+ */
+export type RecoveryRecordProofState = 'verified' | {
+    pending: {
+        verificationMethod: string;
+        keyMultibase: string;
+    };
+};
+/**
+ * Computes the account-binding tag: HMAC-SHA-256 over the binding values
+ * under the code-derived binding MAC key, base64url (no pad). Issuance calls
+ * it to stamp the record; recovery recomputes it to verify.
+ *
+ * @param options {object}
+ * @param options.bindingMacKey {Uint8Array}   the code-derived MAC key
+ * @param options.controller {string}   the account did:key
+ * @param options.pointer {AccountPointer}   the account pointer
+ * @returns {string}
+ */
+export declare function computeRecoveryBinding({ bindingMacKey, controller, pointer }: {
+    bindingMacKey: Uint8Array;
+    controller: string;
+    pointer: AccountPointer;
+}): string;
+/**
+ * Reads the `binding` frame member off a stored recovery record without
+ * decrypting anything. The re-mint path uses it to carry the tag forward
+ * verbatim -- it cannot recompute the tag (no code bytes) and does not need
+ * to. Refuses a record with no binding: such a record predates the
+ * code-authenticated core and cannot be re-minted -- its code must be
+ * re-issued.
+ *
+ * @param options {object}
+ * @param options.record {unknown}   the stored record envelope
+ * @returns {string}
+ */
+export declare function recoveryRecordBinding({ record }: {
+    record: unknown;
+}): string;
+/**
+ * Wraps the recovery record: controller, pointer, and the pre-minted
  * `did.jsonl` PUT delegation, encrypted under the code's unlock KAK via the
- * keyring EDV cipher context.
+ * keyring EDV cipher context, then signed into the same frame the keyring
+ * record uses -- with the account-binding tag as one more frame member the
+ * proof covers. Issuance passes the code-derived `bindingMacKey` (the tag is
+ * computed here) and the code-derived unlock signer; the revocation cascade's
+ * re-mint path passes the standing record's `binding` verbatim and an
+ * enrolled client's account signer (see this module's header for the policy
+ * the reader applies to the two). Exactly one of the two binding inputs must
+ * be given.
  *
  * @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, encryption: CollectionEncryption,
- *   wrapped: unknown }>}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the code's unlock KAK --
+ *   its public half is all the wrap uses (sealing needs no key-agreement
+ *   secret), which is exactly what lets the re-mint path re-seal a record it
+ *   can never open
+ * @param options.signer {RecordSigner}   the signing key: the code's unlock
+ *   key at issuance, an enrolled client's account key on a re-mint
+ * @param [options.bindingMacKey] {Uint8Array}   the code-derived binding MAC
+ *   key -- the issuance path, which computes the tag
+ * @param [options.binding] {string}   the standing record's tag, carried
+ *   forward verbatim -- the re-mint path, which cannot recompute it
+ * @param [options.createdAt] {string}   the bind timestamp to stamp, as an ISO
+ *   string; defaults to now. Supplied by a caller that pins record freshness.
+ * @returns {Promise<SignedRecoveryRecord>}
  */
-export declare function wrapRecoveryRecord({ controller, email, pointer, delegation, keyAgreementKey, keyResolver }: {
+export declare function wrapRecoveryRecord({ controller, pointer, delegation, keyAgreementKey, signer, bindingMacKey, binding, createdAt }: {
     controller: string;
-    email?: string;
     pointer: AccountPointer;
     delegation: IZcap;
     keyAgreementKey: IKeyAgreementKey;
-    keyResolver: IKeyResolver;
-}): Promise<{
-    version: number;
-    encryption: CollectionEncryption;
-    wrapped: unknown;
-}>;
+    signer: RecordSigner;
+    bindingMacKey?: Uint8Array;
+    binding?: string;
+    createdAt?: string;
+}): Promise<SignedRecoveryRecord>;
 /**
  * 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.
+ * plus the required pointer, delegation, and account binding. 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.
+ *
+ * The account binding is verified before the contents are returned: the
+ * decrypted `{ controller, pointer }` must carry the tag the code-derived
+ * MAC key computes over them, or the record is refused as forged
+ * ({@link RecoveryBindingError}) -- the check that closes the host-forgery
+ * redirect, since the host never holds the MAC key. Nothing downstream may
+ * trust the pointer before this returns.
+ *
+ * Proof verification is mixed-signer and ordered deliberately. A proof by the
+ * code's own unlock key is verified BEFORE decryption -- the strong path,
+ * where the typed code alone establishes what may have signed the record. A
+ * proof by any other key can only be checked after decryption, because the
+ * re-minting client is knowable only once the code-authenticated pointer says
+ * which account this is and that account's log has been verified; the
+ * contents come back with a pending proof state naming the signer, and the
+ * caller completes the check with {@link verifyRecordProof} against the
+ * document's keys. That second phase is what makes an unexpected signer
+ * refuse: a record whose proof belongs to neither class ends in a
+ * `RecordProofError` there.
  *
  * @param options {object}
  * @param options.record {unknown}   the stored `{ version, encryption,
- *   wrapped }` envelope
+ *   wrapped, binding, proof }` envelope
  * @param options.keyAgreementKey {IKeyAgreementKey}   the code's unlock KAK
  * @param options.keyResolver {IKeyResolver}
- * @returns {Promise<RecoveryRecordContents>}
+ * @param options.expectedKeyMultibase {string}   the code-derived unlock
+ *   signing key's multibase
+ * @param options.bindingMacKey {Uint8Array}   the code-derived binding MAC
+ *   key the record's account binding must verify under
+ * @returns {Promise<{ contents: RecoveryRecordContents,
+ *   proofState: RecoveryRecordProofState }>}
  */
-export declare function unwrapRecoveryRecord({ record, keyAgreementKey, keyResolver }: {
+export declare function unwrapRecoveryRecord({ record, keyAgreementKey, keyResolver, expectedKeyMultibase, bindingMacKey }: {
     record: unknown;
     keyAgreementKey: IKeyAgreementKey;
     keyResolver: IKeyResolver;
-}): Promise<RecoveryRecordContents>;
+    expectedKeyMultibase: string;
+    bindingMacKey: Uint8Array;
+}): Promise<{
+    contents: RecoveryRecordContents;
+    proofState: RecoveryRecordProofState;
+}>;
 //# sourceMappingURL=recoveryRecord.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"recoveryRecord.d.ts","sourceRoot":"","sources":["../../src/recovery/recoveryRecord.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACN,MAAM,8BAA8B,CAAA;AACrC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAQ/D,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;;;;;;;;;;;;;;;GAeG;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;IACV,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,oBAAoB,CAAA;IAChC,OAAO,EAAE,OAAO,CAAA;CACjB,CAAC,CAsBD;AAED;;;;;;;;;;;;GAYG;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,CAyClC"}
+{"version":3,"file":"recoveryRecord.d.ts","sourceRoot":"","sources":["../../src/recovery/recoveryRecord.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACZ,KAAK,EACN,MAAM,8BAA8B,CAAA;AAcrC,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,YAAY,EACb,MAAM,sBAAsB,CAAA;AAQ7B;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,KAAK,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAqB,SAAQ,YAAY;IACxD,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,wBAAwB,GAClC,UAAU,GAAG;IAAE,OAAO,EAAE;QAAE,kBAAkB,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAAA;AAyBhF;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,EACrC,aAAa,EACb,UAAU,EACV,OAAO,EACR,EAAE;IACD,aAAa,EAAE,UAAU,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,cAAc,CAAA;CACxB,GAAG,MAAM,CAIT;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,MAAM,CAS7E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,UAAU,EACV,OAAO,EACP,UAAU,EACV,eAAe,EACf,MAAM,EACN,aAAa,EACb,OAAO,EACP,SAAS,EACV,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,EAAE,cAAc,CAAA;IACvB,UAAU,EAAE,KAAK,CAAA;IACjB,eAAe,EAAE,gBAAgB,CAAA;IACjC,MAAM,EAAE,YAAY,CAAA;IACpB,aAAa,CAAC,EAAE,UAAU,CAAA;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiChC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,MAAM,EACN,eAAe,EACf,WAAW,EACX,oBAAoB,EACpB,aAAa,EACd,EAAE;IACD,MAAM,EAAE,OAAO,CAAA;IACf,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;IACzB,oBAAoB,EAAE,MAAM,CAAA;IAC5B,aAAa,EAAE,UAAU,CAAA;CAC1B,GAAG,OAAO,CAAC;IACV,QAAQ,EAAE,sBAAsB,CAAA;IAChC,UAAU,EAAE,wBAAwB,CAAA;CACrC,CAAC,CAqFD"}

package/dist/recovery/recoveryRecord.js

@@ -1,61 +1,243 @@
-import { KEYRING_RECORD_VERSION, mintRecordEncryption, parseRecordFrame, parseRecordPointer, recordCipher } from '../keyring/record.js';
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
 /**
- * Wraps the recovery record: controller, email, pointer, and the pre-minted
+ * The recovery keyring record codec: the `{ version, encryption, wrapped,
+ * binding, proof }` envelope stored as the one resource of a recovery code's
+ * unlock Space. Its plaintext is the ordinary keyring record's (controller,
+ * 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 user key wrap (wraps live doc-and-roster
+ * only), so the record stays a pure pointer.
+ *
+ * The wrap reuses the keyring record construction (cipher context,
+ * record-own epoch, and signed frame alike), so a recovery record IS a
+ * keyring record to every generic consumer -- only the recovery flow demands
+ * the delegation and the binding.
+ *
+ * The record splits into a code-authenticated core and a re-mintable shell.
+ * The core is the account binding `{ controller, pointer }`, authenticated by
+ * the `binding` frame member: an HMAC tag under a key derived from the code
+ * bytes, computed at issuance and verified at recovery BEFORE the pointer is
+ * trusted. Only the issuer and the code holder ever hold that key -- the
+ * storage host never does -- so a host-forged record pointing recovery at
+ * another account fails the tag however it is encrypted or signed. The tag
+ * rides the frame in the clear (it reveals nothing) so the re-mint path,
+ * which cannot decrypt the record or recompute the tag, preserves it
+ * verbatim; the binding values themselves stay inside the plaintext. The
+ * consequence: a re-mint can never change the pointer, and an account that
+ * moves hosts must re-issue its codes.
+ *
+ * The shell is the delegation and the frame proof, and its signer is mixed.
+ * At issuance the record is signed by the code-derived unlock key, the one a
+ * typed code re-derives, so recovery verifies the proof before decrypting.
+ * The revocation cascade's re-mint path holds only the code's KAK public
+ * half plus an enrolled client's account key, so it re-PUTs the record
+ * signed by that client's account verification method instead. This codec is
+ * agnostic -- it signs with what it is given -- and the reader carries the
+ * policy: a proof by the expected unlock key verifies up front, and anything
+ * else comes back marked unverified, for the caller to check against the
+ * verified did:webvh document of the account the code-authenticated pointer
+ * names.
+ */
+import { base64urlnopad } from '@scure/base';
+import { equalBytes } from '@noble/ciphers/utils.js';
+import { hmac } from '@noble/hashes/hmac.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { KEYRING_RECORD_VERSION, mintRecordEncryption, parseRecordCreatedAt, parseRecordFrame, parseRecordPointer, recordCipher, recordCreatedAtStamp, recordProofKeyMultibase, recordSealCipher, signRecordFrame, verifyRecordProof } from '../keyring/record.js';
+/**
+ * The context label mixed into the binding MAC input, versioning the tag
+ * construction. Permanent -- changing it orphans every issued code.
+ */
+const RECOVERY_BINDING_CONTEXT = 'freewallet/recovery/binding/v1';
+/**
+ * A recovery record's account binding is absent, malformed, or does not
+ * verify under the typed code's binding MAC key. Its own class, distinct from
+ * a proof or decrypt failure: this is the refusal that says the record's
+ * `{ controller, pointer }` core was not written by a holder of this code --
+ * a forged record redirecting recovery at another account, or a record from
+ * before the account moved hosts (either way the code cannot recover here
+ * and must be re-issued).
+ */
+export class RecoveryBindingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RecoveryBindingError';
+    }
+}
+/**
+ * The deterministic MAC input over a record's account binding: a JSON array
+ * of the context label and the binding values, so no delimiter ambiguity can
+ * make two bindings collide.
+ */
+function bindingMacInput({ controller, pointer }) {
+    return new TextEncoder().encode(JSON.stringify([
+        RECOVERY_BINDING_CONTEXT,
+        controller,
+        pointer.did ?? '',
+        pointer.spaceId,
+        pointer.host
+    ]));
+}
+/**
+ * Computes the account-binding tag: HMAC-SHA-256 over the binding values
+ * under the code-derived binding MAC key, base64url (no pad). Issuance calls
+ * it to stamp the record; recovery recomputes it to verify.
+ *
+ * @param options {object}
+ * @param options.bindingMacKey {Uint8Array}   the code-derived MAC key
+ * @param options.controller {string}   the account did:key
+ * @param options.pointer {AccountPointer}   the account pointer
+ * @returns {string}
+ */
+export function computeRecoveryBinding({ bindingMacKey, controller, pointer }) {
+    return base64urlnopad.encode(hmac(sha256, bindingMacKey, bindingMacInput({ controller, pointer })));
+}
+/**
+ * Reads the `binding` frame member off a stored recovery record without
+ * decrypting anything. The re-mint path uses it to carry the tag forward
+ * verbatim -- it cannot recompute the tag (no code bytes) and does not need
+ * to. Refuses a record with no binding: such a record predates the
+ * code-authenticated core and cannot be re-minted -- its code must be
+ * re-issued.
+ *
+ * @param options {object}
+ * @param options.record {unknown}   the stored record envelope
+ * @returns {string}
+ */
+export function recoveryRecordBinding({ record }) {
+    const { binding } = (record ?? {});
+    if (typeof binding !== 'string' || !binding) {
+        throw new RecoveryBindingError('The recovery record carries no code-authenticated account binding; ' +
+            'the recovery code must be re-issued.');
+    }
+    return binding;
+}
+/**
+ * Wraps the recovery record: controller, pointer, and the pre-minted
  * `did.jsonl` PUT delegation, encrypted under the code's unlock KAK via the
- * keyring EDV cipher context.
+ * keyring EDV cipher context, then signed into the same frame the keyring
+ * record uses -- with the account-binding tag as one more frame member the
+ * proof covers. Issuance passes the code-derived `bindingMacKey` (the tag is
+ * computed here) and the code-derived unlock signer; the revocation cascade's
+ * re-mint path passes the standing record's `binding` verbatim and an
+ * enrolled client's account signer (see this module's header for the policy
+ * the reader applies to the two). Exactly one of the two binding inputs must
+ * be given.
  *
  * @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, encryption: CollectionEncryption,
- *   wrapped: unknown }>}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the code's unlock KAK --
+ *   its public half is all the wrap uses (sealing needs no key-agreement
+ *   secret), which is exactly what lets the re-mint path re-seal a record it
+ *   can never open
+ * @param options.signer {RecordSigner}   the signing key: the code's unlock
+ *   key at issuance, an enrolled client's account key on a re-mint
+ * @param [options.bindingMacKey] {Uint8Array}   the code-derived binding MAC
+ *   key -- the issuance path, which computes the tag
+ * @param [options.binding] {string}   the standing record's tag, carried
+ *   forward verbatim -- the re-mint path, which cannot recompute it
+ * @param [options.createdAt] {string}   the bind timestamp to stamp, as an ISO
+ *   string; defaults to now. Supplied by a caller that pins record freshness.
+ * @returns {Promise<SignedRecoveryRecord>}
  */
-export async function wrapRecoveryRecord({ controller, email, pointer, delegation, keyAgreementKey, keyResolver }) {
+export async function wrapRecoveryRecord({ controller, pointer, delegation, keyAgreementKey, signer, bindingMacKey, binding, createdAt }) {
+    if ((bindingMacKey === undefined) === (binding === undefined)) {
+        throw new Error('Exactly one of bindingMacKey (issuance) or binding (re-mint) is ' +
+            'required.');
+    }
+    const tag = bindingMacKey !== undefined
+        ? computeRecoveryBinding({ bindingMacKey, controller, pointer })
+        : binding;
     const encryption = await mintRecordEncryption({ keyAgreementKey });
-    const cipher = await recordCipher({
-        keyAgreementKey,
-        keyResolver,
-        encryption
-    });
+    const cipher = await recordSealCipher({ encryption });
     const data = {
         controller,
-        ...(email ? { email } : {}),
         pointer: {
             ...(pointer.did ? { did: pointer.did } : {}),
             spaceId: pointer.spaceId,
             host: pointer.host
         },
         delegation,
-        createdAt: new Date().toISOString()
+        createdAt: recordCreatedAtStamp({ createdAt })
     };
     const { envelope } = await cipher.encrypt({
         data: data
     });
-    return { version: KEYRING_RECORD_VERSION, encryption, wrapped: envelope };
+    return (await signRecordFrame({
+        version: KEYRING_RECORD_VERSION,
+        encryption,
+        wrapped: envelope,
+        signer,
+        members: { binding: tag }
+    }));
 }
 /**
  * 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.
+ * plus the required pointer, delegation, and account binding. 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.
+ *
+ * The account binding is verified before the contents are returned: the
+ * decrypted `{ controller, pointer }` must carry the tag the code-derived
+ * MAC key computes over them, or the record is refused as forged
+ * ({@link RecoveryBindingError}) -- the check that closes the host-forgery
+ * redirect, since the host never holds the MAC key. Nothing downstream may
+ * trust the pointer before this returns.
+ *
+ * Proof verification is mixed-signer and ordered deliberately. A proof by the
+ * code's own unlock key is verified BEFORE decryption -- the strong path,
+ * where the typed code alone establishes what may have signed the record. A
+ * proof by any other key can only be checked after decryption, because the
+ * re-minting client is knowable only once the code-authenticated pointer says
+ * which account this is and that account's log has been verified; the
+ * contents come back with a pending proof state naming the signer, and the
+ * caller completes the check with {@link verifyRecordProof} against the
+ * document's keys. That second phase is what makes an unexpected signer
+ * refuse: a record whose proof belongs to neither class ends in a
+ * `RecordProofError` there.
  *
  * @param options {object}
  * @param options.record {unknown}   the stored `{ version, encryption,
- *   wrapped }` envelope
+ *   wrapped, binding, proof }` envelope
  * @param options.keyAgreementKey {IKeyAgreementKey}   the code's unlock KAK
  * @param options.keyResolver {IKeyResolver}
- * @returns {Promise<RecoveryRecordContents>}
+ * @param options.expectedKeyMultibase {string}   the code-derived unlock
+ *   signing key's multibase
+ * @param options.bindingMacKey {Uint8Array}   the code-derived binding MAC
+ *   key the record's account binding must verify under
+ * @returns {Promise<{ contents: RecoveryRecordContents,
+ *   proofState: RecoveryRecordProofState }>}
  */
-export async function unwrapRecoveryRecord({ record, keyAgreementKey, keyResolver }) {
-    const { encryption, wrapped } = parseRecordFrame({
+export async function unwrapRecoveryRecord({ record, keyAgreementKey, keyResolver, expectedKeyMultibase, bindingMacKey }) {
+    const { encryption, wrapped, proof } = parseRecordFrame({
         record,
         label: 'recovery'
     });
+    const binding = recoveryRecordBinding({ record });
+    // `parseRecordFrame` shape-checks the proof of a current-version frame, so
+    // it is present here.
+    const verificationMethod = proof.verificationMethod;
+    const keyMultibase = recordProofKeyMultibase({
+        verificationMethod,
+        label: 'recovery'
+    });
+    let proofState = {
+        pending: { verificationMethod, keyMultibase }
+    };
+    if (keyMultibase === expectedKeyMultibase) {
+        await verifyRecordProof({
+            record,
+            allowedKeyMultibases: expectedKeyMultibase,
+            label: 'recovery'
+        });
+        proofState = 'verified';
+    }
     const cipher = await recordCipher({
         keyAgreementKey,
         keyResolver,
@@ -75,13 +257,32 @@ export async function unwrapRecoveryRecord({ record, keyAgreementKey, keyResolve
         typeof plaintext.delegation !== 'object') {
         throw new Error('Recovery record is missing its did.jsonl delegation.');
     }
+    const createdAt = parseRecordCreatedAt({
+        value: plaintext.createdAt,
+        label: 'Recovery'
+    });
+    const expectedTag = hmac(sha256, bindingMacKey, bindingMacInput({ controller: plaintext.controller, pointer }));
+    let servedTag;
+    try {
+        servedTag = base64urlnopad.decode(binding);
+    }
+    catch {
+        servedTag = null;
+    }
+    // `equalBytes` is @noble/ciphers' authentication-tag comparison (no early
+    // exit), so the check leaks nothing through timing.
+    if (servedTag === null || !equalBytes(servedTag, expectedTag)) {
+        throw new RecoveryBindingError("The recovery record's account binding does not verify under this " +
+            'code; the record is refused as forged.');
+    }
     return {
-        controller: plaintext.controller,
-        ...(typeof plaintext.email === 'string' && plaintext.email
-            ? { email: plaintext.email }
-            : {}),
-        pointer,
-        delegation: plaintext.delegation
+        contents: {
+            controller: plaintext.controller,
+            pointer,
+            delegation: plaintext.delegation,
+            createdAt
+        },
+        proofState
     };
 }
 //# sourceMappingURL=recoveryRecord.js.map

package/dist/recovery/recoveryRecord.js.map

@@ -1 +1 @@
-{"version":3,"file":"recoveryRecord.js","sourceRoot":"","sources":["../../src/recovery/recoveryRecord.ts"],"names":[],"mappings":"AAwBA,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACb,MAAM,sBAAsB,CAAA;AAgB7B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,UAAU,EACV,KAAK,EACL,OAAO,EACP,UAAU,EACV,eAAe,EACf,WAAW,EAQZ;IAKC,MAAM,UAAU,GAAG,MAAM,oBAAoB,CAAC,EAAE,eAAe,EAAE,CAAC,CAAA;IAClE,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QAChC,eAAe;QACf,WAAW;QACX,UAAU;KACX,CAAC,CAAA;IACF,MAAM,IAAI,GAAG;QACX,UAAU;QACV,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE;YACP,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5C,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,IAAI,EAAE,OAAO,CAAC,IAAI;SACnB;QACD,UAAU;QACV,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAA;IACD,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC;QACxC,IAAI,EAAE,IAA+D;KACtE,CAAC,CAAA;IACF,OAAO,EAAE,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;AAC3E,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,EACzC,MAAM,EACN,eAAe,EACf,WAAW,EAKZ;IACC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC;QAC/C,MAAM;QACN,KAAK,EAAE,UAAU;KAClB,CAAC,CAAA;IACF,MAAM,MAAM,GAAG,MAAM,YAAY,CAAC;QAChC,eAAe;QACf,WAAW;QACX,UAAU;KACX,CAAC,CAAA;IACF,MAAM,SAAS,GAAG,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC;QACtC,QAAQ,EAAE,OAAgB;KAC3B,CAAC,CAKD,CAAA;IAED,IAAI,OAAO,SAAS,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;IAC7D,CAAC;IACD,MAAM,OAAO,GAAG,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAA;IACrD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;IACpE,CAAC;IACD,IACE,SAAS,CAAC,UAAU,KAAK,IAAI;QAC7B,OAAO,SAAS,CAAC,UAAU,KAAK,QAAQ,EACxC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAA;IACzE,CAAC;IAED,OAAO;QACL,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,GAAG,CAAC,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,IAAI,SAAS,CAAC,KAAK;YACxD,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE;YAC5B,CAAC,CAAC,EAAE,CAAC;QACP,OAAO;QACP,UAAU,EAAE,SAAS,CAAC,UAAmB;KAC1C,CAAA;AACH,CAAC"}
+{"version":3,"file":"recoveryRecord.js","sourceRoot":"","sources":["../../src/recovery/recoveryRecord.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"recoveryWebvh.d.ts","sourceRoot":"","sources":["../../src/recovery/recoveryWebvh.ts"],"names":[],"mappings":"AAgDA,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;AAsDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAE3B;AA4ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAE3B;AAqED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,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;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAE5C"}
+{"version":3,"file":"recoveryWebvh.d.ts","sourceRoot":"","sources":["../../src/recovery/recoveryWebvh.ts"],"names":[],"mappings":"AAiDA,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;AAsDD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAE3B;AA+ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAE3B;AAqED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,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;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAE5C"}

package/dist/recovery/recoveryWebvh.js

@@ -34,7 +34,7 @@
  * with the same key material converges without forking the log.
  */
 import { deriveNextKeyHash, updateDID } from '@interop/did-method-webvh';
-import { assertCarryOverCommitments, MULTIKEY_VM_TYPE, publishUpdatedLog, putLogResource, readPublishedLog, relationIds, updateKeyMultibase, updateKeySigner, withLogConflictRetry } from '../webvh/didWebvh.js';
+import { assertCarryOverCommitments, markedVerificationMethodPair, MULTIKEY_VM_TYPE, publishUpdatedLog, putLogResource, readPublishedLog, relationIds, updateKeyMultibase, updateKeySigner, withLogConflictRetry } 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
@@ -150,6 +150,9 @@ async function publishRecoveryKeyOnce({ idStore, updateKeys, recovery, expectedD
     }
     await assertCarryOverCommitments({ published });
     const existingMethods = (doc.verificationMethod ?? []);
+    // Controlled by the account, deliberately unmarked: a recovery code is not
+    // a listed client, so its key-agreement method must never carry the
+    // controller marker a client listing and a revocation removal match on.
     const recoveryMethod = {
         id: vmId,
         type: MULTIKEY_VM_TYPE,
@@ -355,24 +358,27 @@ async function recoverWebvhClientOnce({ store, recovery, newClientKeys, newClien
         did,
         keyAgreementKeyMultibase: replacement.keyAgreementKeyMultibase
     });
+    // A three-way controller split. The new client's signing method and the
+    // replacement code's key-agreement method are controlled by the account;
+    // the new client's key-agreement method alone carries the controller marker
+    // (see clientKeyAgreementController) -- which is exactly what tells the two
+    // simultaneously published keyAgreement methods apart. The marked pair goes
+    // through the shared builder, which refuses a new client whose key-agreement
+    // key is not its signing key's canonical twin; the replacement code's
+    // unmarked method is appended after it.
     const addedMethods = [
-        {
-            id: vmId(newClientKeys.signingKeyMultibase),
-            publicKeyMultibase: newClientKeys.signingKeyMultibase
-        },
-        {
-            id: vmId(newClientKeys.keyAgreementKeyMultibase),
-            publicKeyMultibase: newClientKeys.keyAgreementKeyMultibase
-        },
+        ...markedVerificationMethodPair({
+            controller: did,
+            signingKeyMultibase: newClientKeys.signingKeyMultibase,
+            keyAgreementKeyMultibase: newClientKeys.keyAgreementKeyMultibase
+        }),
         {
             id: replacementVmId,
+            type: MULTIKEY_VM_TYPE,
+            controller: did,
             publicKeyMultibase: replacement.keyAgreementKeyMultibase
         }
-    ].map(method => ({
-        ...method,
-        type: MULTIKEY_VM_TYPE,
-        controller: did
-    }));
+    ];
     const existingMethods = (doc.verificationMethod ?? []);
     const verificationMethods = [
         ...existingMethods.filter(method => method.id !== spentVmId &&