@interop/did-cli 0.8.0 → 0.10.0

package/dist/edv/document.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared EDV Document types and the envelope detector for the `edv` command.
+ *
+ * The `{ id, sequence, indexed, jwe }` envelope -- the document the EDV / WAS
+ * data model stores -- is assembled and unwrapped by `@interop/edv-client`'s
+ * `EdvClientCore` (see `./core.ts`); Phases 1-2's hand-rolled assembly was
+ * retired in Phase 3 in favor of that reference implementation. This module
+ * keeps only what the command layer needs alongside it: the decrypted payload
+ * shape and the `isEncryptedDocument` discriminator that tells an EDV Document
+ * envelope apart from a bare Layer 1 JWE on read.
+ */
+import type { IEDVDocument, IEncryptedDocument } from '@interop/data-integrity-core';
+/** Filename convention for a serialized EDV Document. */
+export declare const EDV_DOCUMENT_FILE_SUFFIX = ".edvdoc.json";
+/** The decrypted payload an EDV Document's JWE protects. */
+export type DocumentPayload = Pick<IEDVDocument, 'content' | 'meta' | 'stream'>;
+/**
+ * True when a parsed value is an encrypted EDV Document envelope (it carries a
+ * string `id` and an object `jwe`), as opposed to a bare Layer 1 JWE.
+ *
+ * @param value {unknown}
+ * @returns {boolean}
+ */
+export declare function isEncryptedDocument(value: unknown): value is IEncryptedDocument;
+//# sourceMappingURL=document.d.ts.map

package/dist/edv/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/edv/document.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EACnB,MAAM,8BAA8B,CAAA;AAErC,yDAAyD;AACzD,eAAO,MAAM,wBAAwB,iBAAiB,CAAA;AAEtD,4DAA4D;AAC5D,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAA;AAE/E;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,kBAAkB,CAU7B"}

package/dist/edv/document.js

@@ -0,0 +1,19 @@
+/** Filename convention for a serialized EDV Document. */
+export const EDV_DOCUMENT_FILE_SUFFIX = '.edvdoc.json';
+/**
+ * True when a parsed value is an encrypted EDV Document envelope (it carries a
+ * string `id` and an object `jwe`), as opposed to a bare Layer 1 JWE.
+ *
+ * @param value {unknown}
+ * @returns {boolean}
+ */
+export function isEncryptedDocument(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (typeof candidate.id === 'string' &&
+        typeof candidate.jwe === 'object' &&
+        candidate.jwe !== null);
+}
+//# sourceMappingURL=document.js.map

package/dist/edv/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/edv/document.ts"],"names":[],"mappings":"AAgBA,yDAAyD;AACzD,MAAM,CAAC,MAAM,wBAAwB,GAAG,cAAc,CAAA;AAKtD;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAc;IAEd,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,SAAS,GAAG,KAAgC,CAAA;IAClD,OAAO,CACL,OAAO,SAAS,CAAC,EAAE,KAAK,QAAQ;QAChC,OAAO,SAAS,CAAC,GAAG,KAAK,QAAQ;QACjC,SAAS,CAAC,GAAG,KAAK,IAAI,CACvB,CAAA;AACH,CAAC"}

package/dist/edv/hmac.d.ts

@@ -0,0 +1,26 @@
+/**
+ * HMAC key (`SHA256HMACKey`) resolution for EDV index blinding. The
+ * concrete key implementation -- the reference `IHMAC` impl -- lives in
+ * `@interop/data-integrity-core`; this module only adapts it to the CLI's
+ * wallet storage: it finds the blinding key the `edv encrypt --index` flow
+ * should use (by id, handle, or storage id, or by auto-selecting the lone HMAC
+ * key) and reconstructs it from its persisted JWK secret.
+ */
+import { SHA256HMACKey } from '@interop/data-integrity-core';
+/** The stored `type` value of an HMAC blinding key (the EDV protocol string). */
+export declare const HMAC_KEY_TYPE = "Sha256HmacKey2019";
+/**
+ * Resolve the HMAC blinding key for index operations. With `ref`, match a
+ * stored HMAC key by its id, its storage id, or its metadata handle; without
+ * `ref`, auto-select when the wallet holds exactly one HMAC key. Throws with a
+ * clear message when nothing matches, the handle/ref is ambiguous, or no HMAC
+ * key exists yet.
+ *
+ * @param options {object}
+ * @param [options.ref] {string}   The `--hmac` value; auto-select when omitted.
+ * @returns {Promise<SHA256HMACKey>}
+ */
+export declare function resolveHmac({ ref }: {
+    ref?: string;
+}): Promise<SHA256HMACKey>;
+//# sourceMappingURL=hmac.d.ts.map

package/dist/edv/hmac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.d.ts","sourceRoot":"","sources":["../../src/edv/hmac.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,aAAa,EAEd,MAAM,8BAA8B,CAAA;AAOrC,iFAAiF;AACjF,eAAO,MAAM,aAAa,sBAAsB,CAAA;AAyBhD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,EAChC,GAAG,EACJ,EAAE;IACD,GAAG,CAAC,EAAE,MAAM,CAAA;CACb,GAAG,OAAO,CAAC,aAAa,CAAC,CA+CzB"}

package/dist/edv/hmac.js

@@ -0,0 +1,67 @@
+/**
+ * HMAC key (`SHA256HMACKey`) resolution for EDV index blinding. The
+ * concrete key implementation -- the reference `IHMAC` impl -- lives in
+ * `@interop/data-integrity-core`; this module only adapts it to the CLI's
+ * wallet storage: it finds the blinding key the `edv encrypt --index` flow
+ * should use (by id, handle, or storage id, or by auto-selecting the lone HMAC
+ * key) and reconstructs it from its persisted JWK secret.
+ */
+import { SHA256HMACKey } from '@interop/data-integrity-core';
+import { listCollection, loadFromCollection, loadMetaFromCollection } from '../storage.js';
+/** The stored `type` value of an HMAC blinding key (the EDV protocol string). */
+export const HMAC_KEY_TYPE = 'Sha256HmacKey2019';
+/**
+ * Collect every `SHA256HMACKey` stored in the wallet keys collection.
+ *
+ * @returns {Promise<StoredHmac[]>}
+ */
+async function listStoredHmacs() {
+    const storageIds = await listCollection('keys');
+    const stored = await Promise.all(storageIds.map(storageId => loadFromCollection('keys', storageId)));
+    return storageIds
+        .map((storageId, index) => ({ storageId, stored: stored[index] }))
+        .filter(({ stored }) => stored.type === HMAC_KEY_TYPE);
+}
+/**
+ * Resolve the HMAC blinding key for index operations. With `ref`, match a
+ * stored HMAC key by its id, its storage id, or its metadata handle; without
+ * `ref`, auto-select when the wallet holds exactly one HMAC key. Throws with a
+ * clear message when nothing matches, the handle/ref is ambiguous, or no HMAC
+ * key exists yet.
+ *
+ * @param options {object}
+ * @param [options.ref] {string}   The `--hmac` value; auto-select when omitted.
+ * @returns {Promise<SHA256HMACKey>}
+ */
+export async function resolveHmac({ ref }) {
+    const candidates = await listStoredHmacs();
+    if (candidates.length === 0) {
+        throw new Error('No HMAC key found in the wallet; create one with ' +
+            '`di key create --type hmac --save`.');
+    }
+    if (ref === undefined) {
+        if (candidates.length > 1) {
+            throw new Error(`The wallet has ${candidates.length} HMAC keys; ` +
+                'pass --hmac to choose one.');
+        }
+        return SHA256HMACKey.from(candidates[0].stored);
+    }
+    const direct = candidates.find(candidate => candidate.stored.id === ref || candidate.storageId === ref);
+    if (direct) {
+        return SHA256HMACKey.from(direct.stored);
+    }
+    const metas = await Promise.all(candidates.map(candidate => loadMetaFromCollection({
+        collection: 'keys',
+        storageId: candidate.storageId
+    })));
+    const byHandle = candidates.filter((_candidate, index) => metas[index]?.handle === ref);
+    if (byHandle.length === 0) {
+        throw new Error(`No HMAC key found for "${ref}".`);
+    }
+    if (byHandle.length > 1) {
+        throw new Error(`Handle "${ref}" matches ${byHandle.length} HMAC keys; ` +
+            'use the key id instead.');
+    }
+    return SHA256HMACKey.from(byHandle[0].stored);
+}
+//# sourceMappingURL=hmac.js.map

package/dist/edv/hmac.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmac.js","sourceRoot":"","sources":["../../src/edv/hmac.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,aAAa,EAEd,MAAM,8BAA8B,CAAA;AACrC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,eAAe,CAAA;AAEtB,iFAAiF;AACjF,MAAM,CAAC,MAAM,aAAa,GAAG,mBAAmB,CAAA;AAQhD;;;;GAIG;AACH,KAAK,UAAU,eAAe;IAC5B,MAAM,UAAU,GAAG,MAAM,cAAc,CAAC,MAAM,CAAC,CAAA;IAC/C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAC9B,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CACzB,kBAAkB,CAAiB,MAAM,EAAE,SAAS,CAAC,CACtD,CACF,CAAA;IACD,OAAO,UAAU;SACd,GAAG,CAAC,CAAC,SAAS,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;SACjE,MAAM,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,aAAa,CAAC,CAAA;AAC1D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAChC,GAAG,EAGJ;IACC,MAAM,UAAU,GAAG,MAAM,eAAe,EAAE,CAAA;IAC1C,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,mDAAmD;YACjD,qCAAqC,CACxC,CAAA;IACH,CAAC;IAED,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CACb,kBAAkB,UAAU,CAAC,MAAM,cAAc;gBAC/C,4BAA4B,CAC/B,CAAA;QACH,CAAC;QACD,OAAO,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;IACjD,CAAC;IAED,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAC5B,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,KAAK,GAAG,IAAI,SAAS,CAAC,SAAS,KAAK,GAAG,CACxE,CAAA;IACD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;IAC1C,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CACzB,sBAAsB,CAAC;QACrB,UAAU,EAAE,MAAM;QAClB,SAAS,EAAE,SAAS,CAAC,SAAS;KAC/B,CAAC,CACH,CACF,CAAA;IACD,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAChC,CAAC,UAAU,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,KAAK,GAAG,CACpD,CAAA;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAAA;IACpD,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,WAAW,GAAG,aAAa,QAAQ,CAAC,MAAM,cAAc;YACtD,yBAAyB,CAC5B,CAAA;IACH,CAAC;IACD,OAAO,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AAC/C,CAAC"}

package/dist/edv/recipients.d.ts

@@ -0,0 +1,65 @@
+import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
+/** The X25519 key-agreement verification-method type minimal-cipher expects. */
+export declare const KEY_AGREEMENT_TYPE = "X25519KeyAgreementKey2020";
+/**
+ * An X25519 key-agreement key instance with its `.id` (`kid`) populated. Used
+ * both as a resolved recipient (encrypt reads `id` + `publicKeyMultibase`) and
+ * as the decryption key (decrypt reads `id` + `deriveSecret`).
+ */
+export type KeyAgreementKey = InstanceType<typeof X25519KeyAgreementKey2020> & {
+    id: string;
+};
+/**
+ * Resolve one `--recipient` value to a recipient key. Resolution order: a raw
+ * X25519 `publicKeyMultibase` (starts `z6LS`), then a DID / DID URL, then a
+ * wallet key fingerprint or handle.
+ *
+ * @param options {object}
+ * @param options.ref {string}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+export declare function resolveRecipient({ ref }: {
+    ref: string;
+}): Promise<KeyAgreementKey>;
+/**
+ * Load and validate a key-document JSON file holding an X25519 public key, and
+ * construct its key-agreement key.
+ *
+ * @param options {object}
+ * @param options.path {string}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+export declare function resolveRecipientFile({ path }: {
+    path: string;
+}): Promise<KeyAgreementKey>;
+/**
+ * Resolve a `--key` reference (fingerprint or handle) to a reconstructed
+ * X25519 key-agreement key. The referenced key must be a stored X25519 key
+ * with its secret half.
+ *
+ * @param options {object}
+ * @param options.ref {string}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+export declare function loadKeyAgreementKey({ ref }: {
+    ref: string;
+}): Promise<KeyAgreementKey>;
+/**
+ * Auto-select the decryption key when `--key` is omitted: scan the stored
+ * X25519 secret keys and return the one whose `id` (`kid`) matches a recipient
+ * of the JWE. Throws when none match or more than one does.
+ *
+ * @param options {object}
+ * @param options.jwe {{recipients?: {header?: {kid?: string}}[]}}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+export declare function autoSelectKeyAgreementKey({ jwe }: {
+    jwe: {
+        recipients?: {
+            header?: {
+                kid?: string;
+            };
+        }[];
+    };
+}): Promise<KeyAgreementKey>;
+//# sourceMappingURL=recipients.d.ts.map

package/dist/edv/recipients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipients.d.ts","sourceRoot":"","sources":["../../src/edv/recipients.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAI7E,gFAAgF;AAChF,eAAO,MAAM,kBAAkB,8BAA8B,CAAA;AAW7D;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,OAAO,yBAAyB,CAAC,GAAG;IAC7E,EAAE,EAAE,MAAM,CAAA;CACX,CAAA;AAqKD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,GAAG,EACJ,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,OAAO,CAAC,eAAe,CAAC,CAmB3B;AAED;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,IAAI,EACL,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;CACb,GAAG,OAAO,CAAC,eAAe,CAAC,CAa3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,GAAG,EACJ,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,OAAO,CAAC,eAAe,CAAC,CAa3B;AAED;;;;;;;;GAQG;AACH,wBAAsB,yBAAyB,CAAC,EAC9C,GAAG,EACJ,EAAE;IACD,GAAG,EAAE;QAAE,UAAU,CAAC,EAAE;YAAE,MAAM,CAAC,EAAE;gBAAE,GAAG,CAAC,EAAE,MAAM,CAAA;aAAE,CAAA;SAAE,EAAE,CAAA;KAAE,CAAA;CACtD,GAAG,OAAO,CAAC,eAAe,CAAC,CAsC3B"}

package/dist/edv/recipients.js

@@ -0,0 +1,253 @@
+/**
+ * Recipient and key-agreement resolution for the `edv encrypt`/`edv decrypt`
+ * commands. Normalizes the several recipient reference forms (a raw X25519
+ * `publicKeyMultibase`, a wallet key fingerprint or handle, a DID or DID URL,
+ * and a key-document JSON file) into `X25519KeyAgreementKey2020` instances --
+ * the shape `@interop/minimal-cipher`'s `keyResolver` returns (the cipher reads
+ * `id` and `publicKeyMultibase` from a recipient on encrypt, and `id` and
+ * `deriveSecret` from the key on decrypt, all of which an instance provides).
+ * Builds the recipients array plus that resolver, and reconstructs stored keys
+ * for decrypt.
+ */
+import { readFile } from 'node:fs/promises';
+import { securityLoader } from '@interop/security-document-loader';
+import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
+import { listCollection, loadFromCollection } from '../storage.js';
+import { resolveKeyRef } from '../meta.js';
+/** The X25519 key-agreement verification-method type minimal-cipher expects. */
+export const KEY_AGREEMENT_TYPE = 'X25519KeyAgreementKey2020';
+/**
+ * Document loader for DID-URL recipient resolution: resolves a bare DID to its
+ * DID document and dereferences a `did#fragment` URL straight to its
+ * verification-method node, for both did:key (offline) and did:web (fetched).
+ * Built once and reused. (Per project convention, DID/JSON-LD resolution goes
+ * through `@interop/security-document-loader`, never a hand-rolled loader.)
+ */
+const documentLoader = securityLoader().build();
+/**
+ * Construct an X25519 key-agreement key from a verification method or stored
+ * key pair. `didKey: true` defaults a source with no `controller`/`id` to its
+ * `did:key` form, so the key class derives `.id` as `did:key:<mb>#<mb>` -- the
+ * `kid` encrypt and decrypt both match on -- while a source that already
+ * carries an `id`/`controller` (e.g. a DID verification method) keeps it. A
+ * `type: 'Multikey'` source is normalized via `fromMultikey`. The constructor
+ * validates the multibase header bytes.
+ *
+ * @param source {Record<string, any>}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+async function keyAgreementKeyFrom(source) {
+    const key = await X25519KeyAgreementKey2020.from({ didKey: true, ...source });
+    return key;
+}
+/**
+ * Split a DID URL into its base DID and `#fragment` (undefined when absent).
+ *
+ * @param options {object}
+ * @param options.ref {string}
+ * @returns {{did: string, fragment?: string}}
+ */
+function splitFragment({ ref }) {
+    const hash = ref.indexOf('#');
+    if (hash === -1) {
+        return { did: ref };
+    }
+    return { did: ref.slice(0, hash), fragment: ref.slice(hash + 1) };
+}
+/**
+ * Resolve a DID URL through the security document loader. A bare DID resolves
+ * to its DID document; a `did#fragment` URL is dereferenced straight to its
+ * verification-method node.
+ *
+ * @param options {object}
+ * @param options.url {string}
+ * @returns {Promise<Record<string, any>>}
+ */
+async function resolveDidUrl({ url }) {
+    const { document } = (await documentLoader(url));
+    return document;
+}
+/**
+ * True when a `publicKeyMultibase` carries the X25519 multicodec header. This
+ * is the type-agnostic discriminator for a usable key-agreement key: it accepts
+ * both an `X25519KeyAgreementKey2020` and a `Multikey` whose key is X25519,
+ * while rejecting an Ed25519/other key, regardless of the `type` string a DID
+ * document happens to use.
+ *
+ * @param publicKeyMultibase {string | undefined}
+ * @returns {boolean}
+ */
+function isX25519PublicKey(publicKeyMultibase) {
+    if (!publicKeyMultibase) {
+        return false;
+    }
+    try {
+        // The constructor validates the X25519 header bytes and throws otherwise.
+        X25519KeyAgreementKey2020.fromFingerprint({
+            fingerprint: publicKeyMultibase
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate that a verification method is a usable X25519 key-agreement key
+ * (an `X25519KeyAgreementKey2020` or a `Multikey` whose public key is X25519)
+ * and construct it.
+ *
+ * @param options {object}
+ * @param options.method {Record<string, any>}
+ * @param options.ref {string}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+async function toKeyAgreementKey({ method, ref }) {
+    if (!isX25519PublicKey(method.publicKeyMultibase)) {
+        throw new Error(`Recipient "${ref}" is not an ${KEY_AGREEMENT_TYPE} key.`);
+    }
+    return keyAgreementKeyFrom(method);
+}
+/**
+ * Resolve a DID or DID URL recipient to its X25519 key-agreement key. A bare
+ * DID with a single keyAgreement key uses that key; one with several requires
+ * the `#fragment` form to disambiguate.
+ *
+ * @param options {object}
+ * @param options.ref {string}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+async function resolveDidRecipient({ ref }) {
+    const { did, fragment } = splitFragment({ ref });
+    // A fragment URL dereferences straight to its verification-method node.
+    if (fragment !== undefined) {
+        return toKeyAgreementKey({ method: await resolveDidUrl({ url: ref }), ref });
+    }
+    // A bare DID: pick the single keyAgreement key, dereferencing any entries
+    // that are id references rather than embedded verification methods.
+    const didDocument = await resolveDidUrl({ url: did });
+    const entries = (didDocument.keyAgreement ?? []);
+    const methods = [];
+    for (const entry of entries) {
+        methods.push(typeof entry === 'string' ? await resolveDidUrl({ url: entry }) : entry);
+    }
+    const usable = methods.filter(method => method.type === KEY_AGREEMENT_TYPE && method.publicKeyMultibase);
+    if (usable.length === 0) {
+        throw new Error(`DID ${did} has no ${KEY_AGREEMENT_TYPE} keyAgreement key.`);
+    }
+    if (usable.length > 1) {
+        throw new Error(`DID ${did} has ${usable.length} keyAgreement keys; ` +
+            'use the did#fragment form to choose one.');
+    }
+    return toKeyAgreementKey({ method: usable[0], ref });
+}
+/**
+ * Resolve one `--recipient` value to a recipient key. Resolution order: a raw
+ * X25519 `publicKeyMultibase` (starts `z6LS`), then a DID / DID URL, then a
+ * wallet key fingerprint or handle.
+ *
+ * @param options {object}
+ * @param options.ref {string}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+export async function resolveRecipient({ ref }) {
+    if (ref.startsWith('z6LS')) {
+        return toKeyAgreementKey({
+            method: { type: KEY_AGREEMENT_TYPE, publicKeyMultibase: ref },
+            ref
+        });
+    }
+    if (ref.startsWith('did:')) {
+        return resolveDidRecipient({ ref });
+    }
+    const resolved = await resolveKeyRef({ ref });
+    if (!resolved?.key.publicKeyMultibase) {
+        throw new Error(`Could not resolve recipient "${ref}".`);
+    }
+    const stored = resolved.key;
+    if (stored.type !== KEY_AGREEMENT_TYPE) {
+        throw new Error(`Wallet key "${ref}" is not an ${KEY_AGREEMENT_TYPE} key.`);
+    }
+    return keyAgreementKeyFrom(stored);
+}
+/**
+ * Load and validate a key-document JSON file holding an X25519 public key, and
+ * construct its key-agreement key.
+ *
+ * @param options {object}
+ * @param options.path {string}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+export async function resolveRecipientFile({ path }) {
+    let method;
+    try {
+        method = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`Could not read key document "${path}": ${err.message}`, {
+            cause: err
+        });
+    }
+    return toKeyAgreementKey({ method, ref: path });
+}
+/**
+ * Resolve a `--key` reference (fingerprint or handle) to a reconstructed
+ * X25519 key-agreement key. The referenced key must be a stored X25519 key
+ * with its secret half.
+ *
+ * @param options {object}
+ * @param options.ref {string}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+export async function loadKeyAgreementKey({ ref }) {
+    const resolved = await resolveKeyRef({ ref });
+    if (!resolved) {
+        throw new Error(`No locally stored key found for "${ref}".`);
+    }
+    const stored = resolved.key;
+    if (stored.type !== KEY_AGREEMENT_TYPE) {
+        throw new Error(`Wallet key "${ref}" is not an ${KEY_AGREEMENT_TYPE} key.`);
+    }
+    if (!stored.privateKeyMultibase) {
+        throw new Error(`Wallet key "${ref}" has no secret key to decrypt with.`);
+    }
+    return keyAgreementKeyFrom(stored);
+}
+/**
+ * Auto-select the decryption key when `--key` is omitted: scan the stored
+ * X25519 secret keys and return the one whose `id` (`kid`) matches a recipient
+ * of the JWE. Throws when none match or more than one does.
+ *
+ * @param options {object}
+ * @param options.jwe {{recipients?: {header?: {kid?: string}}[]}}
+ * @returns {Promise<KeyAgreementKey>}
+ */
+export async function autoSelectKeyAgreementKey({ jwe }) {
+    const kids = new Set((jwe.recipients ?? [])
+        .map(recipient => recipient?.header?.kid)
+        .filter((kid) => typeof kid === 'string'));
+    const storageIds = await listCollection('keys');
+    const matches = [];
+    for (const storageId of storageIds) {
+        const stored = await loadFromCollection('keys', storageId);
+        if (stored.type !== KEY_AGREEMENT_TYPE ||
+            !stored.privateKeyMultibase ||
+            !stored.publicKeyMultibase) {
+            continue;
+        }
+        const key = await keyAgreementKeyFrom(stored);
+        if (kids.has(key.id)) {
+            matches.push(key);
+        }
+    }
+    if (matches.length === 0) {
+        throw new Error('No stored X25519 key matches any recipient of this JWE; ' +
+            'pass --key to choose one.');
+    }
+    if (matches.length > 1) {
+        throw new Error(`${matches.length} stored X25519 keys match this JWE; ` +
+            'pass --key to choose one.');
+    }
+    return matches[0];
+}
+//# sourceMappingURL=recipients.js.map

package/dist/edv/recipients.js.map

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

package/dist/edv/stream.d.ts

@@ -0,0 +1,69 @@
+import type { Cipher } from '@interop/minimal-cipher';
+import type { IEDVChunk, IEncryptedDocument, IKeyResolver, IRecipientTemplate } from '@interop/data-integrity-core';
+import type { KeyAgreementKey } from './recipients.js';
+/**
+ * Encrypt `data` as a stream of chunks for the given recipients, stamping the
+ * document `sequence` onto each chunk (as `EdvClientCore._updateStream` does).
+ *
+ * @param options {object}
+ * @param options.cipher {Cipher}
+ * @param options.data {Uint8Array}
+ * @param options.recipients {IRecipientTemplate[]}
+ * @param options.keyResolver {IKeyResolver}
+ * @param [options.chunkSize] {number}   Bytes per chunk (cipher default 1 MiB).
+ * @param options.sequence {number}   The owning document's sequence.
+ * @returns {Promise<IEDVChunk[]>}
+ */
+export declare function encryptToChunks({ cipher, data, recipients, keyResolver, chunkSize, sequence }: {
+    cipher: Cipher;
+    data: Uint8Array;
+    recipients: IRecipientTemplate[];
+    keyResolver: IKeyResolver;
+    chunkSize?: number;
+    sequence: number;
+}): Promise<IEDVChunk[]>;
+/**
+ * Decrypt a document's chunks (in `index` order) back into the original bytes.
+ * A wrong key surfaces as a thrown `DataError` from the decrypt transformer.
+ *
+ * @param options {object}
+ * @param options.cipher {Cipher}
+ * @param options.chunks {IEDVChunk[]}
+ * @param options.keyAgreementKey {KeyAgreementKey}
+ * @returns {Promise<Uint8Array>}
+ */
+export declare function decryptChunks({ cipher, chunks, keyAgreementKey }: {
+    cipher: Cipher;
+    chunks: IEDVChunk[];
+    keyAgreementKey: KeyAgreementKey;
+}): Promise<Uint8Array>;
+/**
+ * Write a streamed EDV Document as a bundle directory: `document.json` plus
+ * `chunks/<index>.jwe.json` for each chunk.
+ *
+ * @param options {object}
+ * @param options.dir {string}   The bundle directory path.
+ * @param options.document {IEncryptedDocument}
+ * @param options.chunks {IEDVChunk[]}
+ * @returns {Promise<void>}
+ */
+export declare function writeDocumentBundle({ dir, document, chunks }: {
+    dir: string;
+    document: IEncryptedDocument;
+    chunks: IEDVChunk[];
+}): Promise<void>;
+/**
+ * Read a bundle directory back into its document envelope and chunks (sorted by
+ * `index`).
+ *
+ * @param options {object}
+ * @param options.dir {string}   The bundle directory path.
+ * @returns {Promise<{document: IEncryptedDocument, chunks: IEDVChunk[]}>}
+ */
+export declare function readDocumentBundle({ dir }: {
+    dir: string;
+}): Promise<{
+    document: IEncryptedDocument;
+    chunks: IEDVChunk[];
+}>;
+//# sourceMappingURL=stream.d.ts.map

package/dist/edv/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/edv/stream.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,KAAK,EACV,SAAS,EACT,kBAAkB,EAElB,YAAY,EACZ,kBAAkB,EACnB,MAAM,8BAA8B,CAAA;AAErC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AA6DtD;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,EACpC,MAAM,EACN,IAAI,EACJ,UAAU,EACV,WAAW,EACX,SAAS,EACT,QAAQ,EACT,EAAE;IACD,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,UAAU,CAAA;IAChB,UAAU,EAAE,kBAAkB,EAAE,CAAA;IAChC,WAAW,EAAE,YAAY,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAgBvB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,EAClC,MAAM,EACN,MAAM,EACN,eAAe,EAChB,EAAE;IACD,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,SAAS,EAAE,CAAA;IACnB,eAAe,EAAE,eAAe,CAAA;CACjC,GAAG,OAAO,CAAC,UAAU,CAAC,CAUtB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,GAAG,EACH,QAAQ,EACR,MAAM,EACP,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAehB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,EAAE,GAAG,EAAE,EAAE;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC;IAC1E,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB,CAAC,CA0BD"}