@interop/did-cli 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,163 @@
 # History
 
+## 0.10.0 - 2026-06-25
+
+### Added
+
+- `did show` now resolves a `did:webvh` DID from its stored history log
+  (`<did>.jsonl`) -- the source of truth -- rather than printing the saved
+  document snapshot, so the output reflects every appended log entry. With
+  `--meta` it also reports the parameters resolved from the log: version id,
+  last-updated time, portability, pre-rotation, deactivation status, and the
+  count of update keys, witnesses, and watchers (also included in
+  `--meta --json`). A `did:webvh` DID with no stored log still falls back to the
+  saved snapshot.
+- Add `did add-service <did>` and `did remove-service <did>`, which add or
+  remove a [service](https://www.w3.org/TR/did-core/#services) entry on a stored
+  `did:web` or `did:webvh` DID (the DID may be given as a metadata handle).
+  `--id` accepts a bare fragment (expanded to `<did>#fragment`) or a full id;
+  the type comes from `--type` (repeatable) and the endpoint from either
+  `--endpoint` (repeatable) or `--endpoint-json` (a raw JSON value). For
+  `did:web` this edits the stored document in place; for `did:webvh` it appends
+  a sparse log entry that carries the update keys and document verification
+  methods forward unchanged -- except that, when pre-rotation is armed, the
+  update-key ratchet is advanced as part of the change (the staged key signs the
+  entry), with `--keep-old-key` and `-y` / `--yes` honored as in
+  `webvh rotate-keys`.
+- Add richer create-time options to `did create webvh`, each declared in the
+  signed `did.jsonl` log `parameters`: `--portable` / `--no-portable` (portable
+  is the default -- a portable DID can later be moved to another domain),
+  `--witness <did...>` (repeatable; declare witness `did:key` DIDs authorized to
+  co-sign log entries) with `--witness-threshold <n>` (defaults to the number of
+  witnesses; requires `--witness`), and `--watcher <url...>` (repeatable;
+  `https://` or `http://localhost`). Witnesses are **declaration only** for now
+  -- generating witness proofs / a `did-witness.json` sidecar remains out of
+  scope.
+- Add key **pre-rotation** to `did:webvh`. `did create webvh` now arms
+  pre-rotation by default: the DID commits, in advance, to the hash of the key
+  allowed to perform the next update, so a compromise of the active update key
+  cannot seize the DID. Update keys are now **decoupled** from the document's
+  verification key -- `create` generates an active update key A, a staged next
+  update key B (whose hash is committed as `nextKeyHashes`), and a separate
+  document key V (wired into the verification relationships as before). On
+  `--save`, V is stored in `<did>.keys.json` (keyed by its document
+  verification-method id, so it can be selected for signing) and A+B in a new
+  `<did>.update-keys.json` sidecar. Pass `--no-prerotation` to create without a
+  staged key. Requires `@interop/did-method-webvh` >= 3.2.0 (for the exported
+  `deriveNextKeyHash`).
+- Add `did webvh rotate-keys <did>`, which rotates a stored `did:webvh` DID's
+  update (authorization) key and never touches the document's verification
+  methods. With no flags it advances the pre-rotation ratchet in one step --
+  revealing and activating the staged key, then staging a fresh one -- and
+  deletes the retired key's secret by default. Flags: `--stop-prerotation` (turn
+  pre-rotation off), `--enable-prerotation` (turn it on for a DID without it;
+  alone, stage only), `--update-key <multibase...>` (rotate to specific key(s)
+  in ordinary mode; rejected while pre-rotation is armed), `--keep-old-key`
+  (retain the retired secret), and `-y, --yes` (skip the confirmation prompt).
+- Add `was space meta <space>`, which updates a registered space's local
+  registry metadata (`--handle` and/or `--description`) only, leaving the
+  server-side space untouched. At least one of the two flags is required;
+  passing an empty string (e.g. `--handle ''`) clears that field.
+
+- Implement `did create webvh`, which creates a real did:webvh DID via the
+  `@interop/did-method-webvh` library (Ed25519 / `eddsa-jcs-2022` only for now;
+  `--type ecdsa` is rejected). Requires `--url` (passed as the DID's `address`)
+  and supports the same `--with-seed` / `--save` / `--handle` / `--description`
+  flags as the other methods. did:webvh is a two-part DID: on `--save`, the
+  resolved DID document, keys, and metadata are written as usual under
+  `dids/webvh/`, plus the signed `did.jsonl` history log as a raw
+  newline-delimited `<did>.jsonl` file alongside them; `did remove` deletes the
+  log too. The generated DID is portable, and its single Ed25519 key is wired
+  into the same verification relationships as did:web (`authentication`,
+  `assertionMethod`, `capabilityDelegation`, `capabilityInvocation`; not
+  `keyAgreement`). Requires `@interop/did-method-webvh` >= 3.1.0. Resolving a
+  stored webvh DID, witnesses, and the parallel did:web alias are deferred.
+  (Update-key rotation and pre-rotation are implemented separately below.)
+- Support `did get`/`did resolve` for `did:webvh` DIDs. A `did:webvh` driver
+  (`src/keys/webvh-driver.ts`) wraps `resolveDID` from
+  `@interop/did-method-webvh` -- fetching and verifying the DID's history log --
+  and is registered onto the security document loader's resolver via the new
+  injectable `securityLoader({ didResolver })` seam, so the `did:webvh`
+  dependency stays out of the shared loader. A bare DID resolves to its DID
+  document; a `did#fragment` URL is dereferenced to its verification method.
+  Requires `@interop/security-document-loader` >= 9.4.0.
+
+### Changed
+
+- Update to `@interop/did-method-webvh` >= 3.3.0. `updateDID` now performs a
+  sparse update -- it carries the prior DID document state forward and overlays
+  only the fields an update actually supplies -- so `did webvh rotate-keys` no
+  longer reconstructs and re-supplies the document's verification methods to
+  keep them unchanged; the key-only rotation simply omits all document
+  directives.
+
+## 0.9.0 - 2026-06-14
+
+### Added
+
+- Implement `did get <did>` (alias: `resolve`), which resolves a DID to its DID
+  document through `@interop/security-document-loader`'s document loader
+  (did:key offline, did:web fetched). A DID URL (a `did#fragment` key id)
+  dereferences straight to its verification method. Unlike `did show`, which
+  reads local storage, `did get` resolves live.
+- Add an `edv` command group with `encrypt` and `decrypt` subcommands
+  (Layer 1: raw JWE). `edv encrypt [file]` encrypts stdin or a file to one or
+  more X25519 recipients and emits a single flattened JWE (the `jwe` field of
+  an EDV Document) to stdout or an `-o` file (convention `*.jwe.json`);
+  `edv decrypt [file]` reverses it. Encryption is public-key (key-agreement)
+  only, via `@interop/minimal-cipher` with its default algorithm
+  (`ECDH-ES+A256KW` key wrap, `XC20P` content encryption). A recipient
+  (`-r/--recipient`, repeatable) is a raw X25519 `publicKeyMultibase`, a wallet
+  key fingerprint/handle, or a DID / DID URL (its `keyAgreement` key, typed
+  either `X25519KeyAgreementKey2020` or `Multikey`); `--recipient-file` reads a
+  key-document JSON. `--json` switches both commands
+  to object semantics. On decrypt, the secret key is given with `-k/--key` or
+  auto-selected from the wallet by matching a recipient `kid`; a non-recipient
+  key exits non-zero with a clear error. The full EDV Document envelope,
+  chunked streams, and HMAC-blinded indexing are deferred to Layer 2.
+- Add EDV Document support to `edv` (Layer 2, Phase 1). `edv encrypt --document`
+  wraps the JWE in a full EDV Document envelope `{ id, sequence, indexed, jwe }`
+  (convention `*.edvdoc.json`), encrypting the input as the document `content`
+  with an optional `--meta <json>` object alongside it (both encrypted inside the
+  `jwe`); `id` is a fresh identity-multihash multibase value and `sequence`
+  starts at `0`, byte-faithful to `@interop/edv-client`'s `EdvClientCore` without
+  taking that dependency. `--update <file>` versions an existing document
+  (reusing its `id`, incrementing `sequence`, and merging its recipients).
+  `edv decrypt` detects an envelope automatically and emits its decrypted
+  `content` (reporting `meta`/`stream` on stderr); `--document` requires one.
+  Chunked streams and HMAC-blinded indexing remain deferred to later phases.
+- Add chunked-stream support to `edv` (Layer 2, Phase 2). `edv encrypt --stream`
+  encrypts the input as a sequence of fixed-size chunks (`--chunk-size <bytes>`,
+  default 1 MiB) and writes a bundle directory (convention `*.edvdoc/`, so `-o`
+  is required): a `document.json` EDV Document carrying a cleartext
+  `stream: { sequence, chunks }` descriptor, plus one `chunks/<index>.jwe.json`
+  per chunk (`{ sequence, index, offset, jwe }`), mirroring how an EDV / WAS
+  server stores stream bytes separately from the document. `--meta` and
+  `--update` (a file or bundle) work as for `--document`. `edv decrypt`
+  recognizes a bundle directory, reassembles the chunks in order, and writes the
+  original bytes to `-o`/stdout (reporting `content`/`meta`/`stream` on stderr).
+  HMAC-blinded indexing remains deferred to Layer 2, Phase 3.
+- Add HMAC-blinded indexing to `edv` (Layer 2, Phase 3). In
+  `--document`/`--stream` mode, `--index <attribute>` (repeatable; a dotted path
+  into `content`/`meta`) populates the envelope's `indexed` array with entries
+  whose attribute names and values are HMAC-blinded, so a document is searchable
+  the way an EDV / WAS server indexes it without the server learning the
+  cleartext. `--unique` marks every `--index` attribute unique; `--hmac <ref>`
+  selects the blinding key (auto-selected when the wallet holds exactly one). The
+  same key over the same value yields a stable blinded entry, matchable across
+  documents. The EDV Document envelope and its blinded `indexed` array are now
+  assembled and unwrapped by `@interop/edv-client`'s `EdvClientCore` (a new
+  dependency), converging on the reference implementation rather than the
+  hand-rolled envelope used in Phases 1-2.
+- Add `key create --type hmac`, generating a `Sha256HmacKey2019` HMAC key (a
+  32-byte symmetric secret used to blind EDV index attributes) via
+  `@interop/data-integrity-core`'s `SHA256HMACKey`. The key has no public half;
+  it is serialized with its secret as an `oct` JWK and identified by a random
+  `urn:uuid:` id. HMAC keys list with an `hmac` type label, and `key show`
+  prints only their `id`/`type` (never the secret). Like ecdsa/x25519, HMAC
+  generation is non-deterministic, so `--with-seed` / `SECRET_KEY_SEED` are not
+  supported.
+
 ## 0.8.0 - 2026-06-13
 
 ### Added

package/README.md

@@ -81,7 +81,7 @@ SECRET_KEY_SEED=z1AXVyT6G1Qk3E9cMPkDYY6wVRpZjVGWAZ3TfrAgFZkX6bv ./di key create
 ```
 
 Specify an explicit key type with `--type` (defaults to `ed25519`; supported:
-`ed25519`, `ecdsa`, `x25519`):
+`ed25519`, `ecdsa`, `x25519`, `hmac`):
 
 ```
 SECRET_KEY_SEED=z1Aaj5A4UCsd... ./di key create --type ed25519
@@ -132,6 +132,28 @@ private key in multibase encoding:
 Like ECDSA, X25519 key generation is non-deterministic, so `--with-seed` and
 `SECRET_KEY_SEED` are not supported with `--type x25519`.
 
+Generate a `Sha256HmacKey2019` HMAC key -- a 32-byte symmetric secret used to
+HMAC-blind EDV index attributes (see [Blinded indexing](#blinded-indexing---index))
+-- with `--type hmac`:
+
+```
+./di key create --type hmac
+```
+
+It is serialized with the secret carried as an `oct` JWK (it has no public
+half), identified by a random `urn:uuid:` id:
+
+```json
+{
+  "id": "urn:uuid:...",
+  "type": "Sha256HmacKey2019",
+  "secretKeyJwk": { "kty": "oct", "alg": "HS256", "k": "..." }
+}
+```
+
+HMAC key generation is non-deterministic, so `--with-seed` and `SECRET_KEY_SEED`
+are not supported with `--type hmac`.
+
 Save the key to local wallet storage (`~/.config/did-cli-wallet/keys/` by default, or
 `$WALLET_DIR/keys/` if set) with `--save`. A `.meta.json` metadata sidecar is
 written next to the key, recording the creation timestamp; `--handle` (a short
@@ -431,6 +453,164 @@ seed-derivable, so `--with-seed` is not supported with `--type ecdsa` or
 ./di did add-key did:web:example.com --with-seed
 ```
 
+#### Create a did:webvh DID
+
+Generate a `did:webvh` DID. Like `did:web` it is tied to a domain, so `--url`
+(the HTTPS url that will host the DID's history log) is required:
+
+```
+./di did create webvh --url https://example.com
+{
+  "id": "did:webvh:Qm...:example.com",
+  "didDocument": { ... }
+}
+```
+
+`did:webvh` separates two key roles: an **update (authorization) key** that
+signs entries in the DID's append-only history log, and the **document
+verification key** wired into the `authentication`, `assertionMethod`,
+`capabilityDelegation`, and `capabilityInvocation` relationships. They are
+distinct keys, so the update key can be rotated without ever disturbing the
+document.
+
+By default `did:webvh` arms **key pre-rotation**: the DID commits, in advance,
+to the *hash* of the key allowed to perform the next update. A compromise of the
+currently active update key cannot be used to seize the DID, because the
+attacker still does not hold the pre-committed next key. So `create` generates
+three keys: the active update key, a staged next update key (whose hash is
+committed as `nextKeyHashes`), and the document key. Pass `--no-prerotation` to
+create the DID without pre-rotation (no next key is staged):
+
+```
+./di did create webvh --url https://example.com --no-prerotation
+```
+
+Save the DID document, history log, and key material to local storage with
+`--save` (written to `~/.config/did-cli-wallet/dids/webvh/` by default, or
+`$DIDS_DIR` if set). The document key is stored in `<did>.keys.json`; the update
+keys (active, and the staged next key when pre-rotation is on) are stored in a
+separate `<did>.update-keys.json` sidecar, and the signed history log in
+`<did>.jsonl`:
+
+```
+./di did create webvh --url https://example.com --save
+DID saved to /home/user/.config/did-cli-wallet/dids/webvh/did:webvh:Qm...:example.com.json
+DID history log saved to /home/user/.config/did-cli-wallet/dids/webvh/did:webvh:Qm...:example.com.jsonl
+Update keys saved to /home/user/.config/did-cli-wallet/dids/webvh/did:webvh:Qm...:example.com.update-keys.json
+{
+  "id": "did:webvh:Qm...:example.com",
+  "didDocument": { ... }
+}
+```
+
+Only Ed25519 update keys are supported (the `eddsa-jcs-2022` cryptosuite the
+method uses requires them), so `--type ecdsa` is rejected.
+
+A few more create-time options are recorded in the signed history-log
+`parameters`:
+
+- `--portable` / `--no-portable` -- a **portable** DID (the default) can later
+  be moved to a different domain; `--no-portable` pins it to its origin.
+- `--witness <did...>` -- declare one or more **witness** `did:key` DIDs
+  authorized to co-sign the DID's log entries (repeatable). `--witness-threshold
+  <n>` sets how many witness approvals are required (defaults to the number of
+  witnesses; it requires `--witness`). This only *declares* the witnesses;
+  actually generating witness proofs is not yet supported.
+- `--watcher <url...>` -- declare one or more **watcher** URLs that monitor the
+  DID's log (repeatable; `https://`, or `http://localhost` for local testing).
+
+```
+./di did create webvh --url https://example.com \
+  --witness did:key:z6Mk... --witness did:key:z6Mk... --witness-threshold 1 \
+  --watcher https://watcher.example.com --save
+```
+
+#### Rotate a did:webvh update key
+
+Rotate the update (authorization) key of a locally stored `did:webvh` DID with
+`did webvh rotate-keys`. This appends a new entry to the DID's history log and
+**never touches the document's verification methods** (those are separate keys).
+
+With no flags it advances the pre-rotation ratchet in one step: it reveals and
+activates the previously staged next key (signing the new entry with it), and
+stages a fresh next key for the following rotation. The retired update key's
+secret is deleted by default -- a retired key is only ever needed to *verify*
+historic log entries, which uses the public key from the log, not the secret:
+
+```
+./di did webvh rotate-keys did:webvh:Qm...:example.com
+DID document saved to /home/user/.config/did-cli-wallet/dids/webvh/did:webvh:Qm...:example.com.json
+DID history log saved to /home/user/.config/did-cli-wallet/dids/webvh/did:webvh:Qm...:example.com.jsonl
+Update keys saved to /home/user/.config/did-cli-wallet/dids/webvh/did:webvh:Qm...:example.com.update-keys.json
+Pre-rotation is armed: a next update key is staged.
+{
+  "id": "did:webvh:Qm...:example.com",
+  "didDocument": { ... }
+}
+```
+
+Pre-rotation requires the staged key to sign its own activation, so the staged
+secret in `<did>.update-keys.json` is what makes the next rotation possible --
+losing it means the DID can never be updated again. Keep that sidecar backed up.
+
+Flags:
+
+- `--stop-prerotation` -- rotate but commit no next-key hash; pre-rotation turns
+  **off** after this entry.
+- `--enable-prerotation` -- for a DID with pre-rotation currently off, turn it
+  **on** by staging a next key. Alone it stages only (the active key is
+  unchanged, signed by the current key).
+- `--update-key <multibase...>` -- in ordinary (non-pre-rotation) mode, rotate
+  to specific update key(s) by public key instead of generating a fresh one.
+  Rejected while pre-rotation is armed, where the next keys are fixed by the
+  prior commitment.
+- `--keep-old-key` -- retain the retired update key's secret in the sidecar
+  instead of dropping it.
+- `-y`, `--yes` -- skip the confirmation prompt (rotation is hard to undo).
+
+#### Add or remove a service entry
+
+Add or remove a [service](https://www.w3.org/TR/did-core/#services) entry on a
+locally stored `did:web` or `did:webvh` DID. The DID may be given as a full DID
+or a metadata handle. For `did:web` this edits the stored document in place; for
+`did:webvh` it appends a new entry to the history log.
+
+```
+./di did add-service did:web:example.com \
+  --id files --type LinkedDomains --endpoint https://example.com
+{
+  "id": "did:web:example.com",
+  "didDocument": { ..., "service": [ ... ] }
+}
+```
+
+`--id` accepts a bare fragment (`files`), which is expanded to `<did>#files`, or
+a full service id. The service type comes from `--type` (repeat for multiple
+types). The endpoint comes from either `--endpoint` (repeat for multiple values;
+a single value stays a string, several become an array) or `--endpoint-json` (a
+raw JSON value, e.g. an object); exactly one of the two is required.
+
+```
+./di did add-service did:web:example.com \
+  --id dwn --type DecentralizedWebNode \
+  --endpoint-json '{"nodes":["https://dwn.example"]}'
+```
+
+Remove a service by its id (a bare fragment is expanded the same way):
+
+```
+./di did remove-service did:web:example.com --id files
+```
+
+For `did:webvh`, both commands sign and append a log entry (and so accept `-y` /
+`--yes` to skip the confirmation prompt). The update keys and document
+verification methods are carried forward unchanged -- with one exception: when
+pre-rotation is armed the library requires the staged key to sign the entry, so
+the update-key ratchet is **advanced** as part of the change (the staged key is
+revealed and activated, and a fresh next key is staged), exactly as in
+`webvh rotate-keys`. Pass `--keep-old-key` to retain the retired update key's
+secret in that case.
+
 #### List DIDs
 
 List the DIDs saved in local storage (via `did create --save`) as a table of
@@ -466,6 +646,34 @@ did:key:z6Mkr...
 did:key:z6Mks...
 ```
 
+#### Resolve a DID
+
+Resolve a DID to its DID document through the security document loader. Unlike
+`did show` (which reads local storage), `did get` resolves live: did:key is
+resolved offline, did:web is fetched over HTTPS, and did:webvh is resolved by
+fetching and verifying its history log over HTTPS. Pass a DID URL (a
+`did#fragment` key id) to dereference straight to its verification method:
+
+```
+./di did get did:key:z6Mkr...
+{
+  "@context": [ ... ],
+  "id": "did:key:z6Mkr...",
+  "verificationMethod": [ ... ],
+  ...
+}
+
+./di did get did:key:z6Mkr...#z6Mkr...
+{
+  "id": "did:key:z6Mkr...#z6Mkr...",
+  "type": "Ed25519VerificationKey2020",
+  "controller": "did:key:z6Mkr...",
+  "publicKeyMultibase": "z6Mkr..."
+}
+```
+
+Alias: `resolve`.
+
 #### Show a DID
 
 Display the DID document saved in local storage (via `did create --save`),
@@ -485,6 +693,11 @@ printed as-is:
 
 Aliases: `view`, `cat`.
 
+For a `did:webvh` DID the document is **resolved from its stored history log**
+(`<did>.jsonl`) -- the source of truth -- rather than the saved snapshot, so the
+output reflects every appended log entry. If no log is stored the saved snapshot
+is shown instead.
+
 Pass `--meta` to show the DID's metadata instead of the DID document:
 
 ```
@@ -499,7 +712,29 @@ Description
 Keys         1
 ```
 
-`--meta --json` prints the same metadata as a JSON object.
+For a `did:webvh` DID, `--meta` also reports the parameters resolved from the
+log -- the current version id, last-updated time, portability, pre-rotation,
+deactivation status, and the number of update keys, witnesses, and watchers:
+
+```
+./di did show my-webvh --meta
+FIELD        VALUE
+-----------  ----------------------------------------------
+DID          did:webvh:Qm...:example.com
+Method       webvh
+...
+Version      1-Qm...
+Updated      2026-06-10T17:22:31Z
+Portable     yes
+Prerotation  yes
+Deactivated  no
+Update keys  1
+Witnesses    0
+Watchers     0
+```
+
+`--meta --json` prints the same metadata as a JSON object (the `did:webvh`
+fields are included there too).
 
 #### Edit DID metadata
 
@@ -1097,8 +1332,10 @@ the server, or the local registry record with `--meta`:
 `was space update` (alias: `configure`) upserts description fields
 (`--name`), also refreshing the registry entry. `was space add` registers an
 *existing* remote space (a full space URL, or a bare id plus `--server`) in
-the local registry, verifying it with a describe first. The local/remote
-delete pair:
+the local registry, verifying it with a describe first. `was space meta
+<space>` updates only a registered space's local metadata (`--handle` and/or
+`--description`); the server-side space is untouched, and passing an empty
+string (`--handle ''`) clears that field. The local/remote delete pair:
 
 - `was space delete <space>` (alias: `rm`) deletes the space **on the
   server** (idempotent) and removes the registry entry;
@@ -1428,6 +1665,151 @@ unless `WAS_TEST_SERVER_URL` points at a running server:
 WAS_TEST_SERVER_URL=http://localhost:3002 npm run test:node
 ```
 
+### Encrypted Data (EDV)
+
+The `edv` commands encrypt an object or file to one or more X25519 recipients
+and decrypt the result, using the EDV / [minimal-cipher](https://www.npmjs.com/package/@interop/minimal-cipher)
+serialization. The output is a single raw **JWE** (the `jwe` field of an EDV
+Document), written to stdout or an `-o` file -- by convention `*.jwe.json`.
+Encryption is public-key (key-agreement) only: there is no password mode. The
+algorithm is the library default, `ECDH-ES+A256KW` key wrap with `XC20P`
+(XChaCha20Poly1305) content encryption.
+
+#### Encrypt
+
+A recipient (`-r/--recipient`, repeatable, at least one required) is an X25519
+public key given as a raw `publicKeyMultibase` (starts `z6LS`), a wallet key
+fingerprint or handle, or a DID / DID URL (the DID's `keyAgreement` key; a DID
+with several keyAgreement keys needs the `did#fragment` form). A
+`--recipient-file <path>` is a key-document JSON file holding an X25519 public
+key.
+
+Encrypt a JSON object (with `--json`, the input is parsed and encrypted as an
+object) to a stored x25519 key:
+
+```
+./di key create --type x25519 --save --handle alice-kak
+echo '{"hello": "world"}' | ./di edv encrypt --json -r alice-kak -o secret.jwe.json
+```
+
+Without `--json` the raw input bytes are encrypted. Encrypt to several
+recipients by repeating `-r`:
+
+```
+./di edv encrypt photo.png -r alice-kak -r z6LSr... -o photo.jwe.json
+```
+
+#### Decrypt
+
+`-k/--key` is the X25519 secret key (fingerprint or handle) to decrypt with;
+when omitted, the matching stored key is auto-selected from the wallet. Use
+`--json` to pretty-print the decrypted object, and `-o` to write to a file.
+Only plaintext is ever written; secret key material stays in the key store.
+
+```
+./di edv decrypt secret.jwe.json --json
+{
+  "hello": "world"
+}
+
+./di edv decrypt photo.jwe.json -k alice-kak -o photo.png
+```
+
+Decryption with a key that is not a recipient exits non-zero with a clear
+error rather than emitting garbage.
+
+#### EDV Documents (`--document`)
+
+By default `edv encrypt` emits a bare JWE. With `-d/--document` it wraps that JWE
+in a full **EDV Document** envelope -- `{ id, sequence, indexed, jwe }`, the
+shape an EDV / WAS server stores -- written by convention to `*.edvdoc.json`. The
+input is encrypted as the document's `content`; an optional `--meta <json>`
+object is encrypted alongside it (both live inside the `jwe`, so only `id`,
+`sequence`, and `indexed` stay in cleartext). The `id` is a fresh
+identity-multihash multibase value and `sequence` starts at `0`. Index entries
+(`indexed`) are always `[]` for now; HMAC-blinded indexing and chunked streams
+are later phases.
+
+```
+echo '{"name": "alice"}' | \
+  ./di edv encrypt --document -r alice-kak --meta '{"tag":"demo"}' -o doc.edvdoc.json
+```
+
+`--update <file>` versions an existing document: it reuses that document's `id`,
+increments its `sequence`, and merges its recipients (so you can add a recipient
+without re-listing the existing ones) before re-encrypting the new content.
+
+```
+echo '{"name": "alice", "v": 2}' | \
+  ./di edv encrypt --document -r bob-kak --update doc.edvdoc.json -o doc.v2.edvdoc.json
+```
+
+`edv decrypt` detects an EDV Document automatically and prints its decrypted
+`content` (any `meta`/`stream` is reported on stderr); pass `-d/--document` to
+require an envelope and reject a bare JWE.
+
+```
+./di edv decrypt doc.edvdoc.json
+{
+  "name": "alice"
+}
+```
+
+#### Chunked streams (`--stream`)
+
+For large inputs, `-s/--stream` encrypts the bytes as a sequence of fixed-size
+chunks rather than one JWE. The output is a **bundle directory** (convention
+`*.edvdoc/`, so `-o` is required) holding `document.json` -- an EDV Document whose
+cleartext `stream: { sequence, chunks }` descriptor records the chunk count -- and
+one `chunks/<index>.jwe.json` per chunk. This mirrors how an EDV / WAS server
+stores stream bytes as resources separate from the document. `--chunk-size
+<bytes>` sets the chunk size (default 1 MiB); `--meta` and `--update` work as for
+`--document`.
+
+```
+./di edv encrypt photo.png --stream -r alice-kak --chunk-size 1048576 -o photo.edvdoc/
+```
+
+`edv decrypt` recognizes a bundle directory, reassembles the chunks in order, and
+writes the original bytes to `-o`/stdout (the document's `content`/`meta`/`stream`
+are reported on stderr).
+
+```
+./di edv decrypt photo.edvdoc/ -o photo.png
+```
+
+#### Blinded indexing (`--index`)
+
+In `--document`/`--stream` mode, `--index <attribute>` populates the envelope's
+`indexed` array so a document is searchable the way an EDV / WAS server indexes
+it -- without the server learning the cleartext. The attribute name and value
+are **HMAC-blinded**: a `Sha256HmacKey2019` key signs them, so the same key over
+the same value always yields the same opaque entry (matchable across documents),
+but the cleartext never leaves the client.
+
+First create an HMAC key in the wallet (a 32-byte secret, no public half):
+
+```
+./di key create --type hmac --save --handle vault-index
+```
+
+Then declare one or more indexable attribute paths (dotted paths into `content`
+or `meta`). The HMAC key is auto-selected when the wallet holds exactly one;
+otherwise pass `--hmac <id|handle>`. `--unique` marks every `--index` attribute
+as unique.
+
+```
+echo '{"type":"Person","name":"alice"}' | \
+  ./di edv encrypt --document --json -r alice-kak \
+    --index content.type --index content.name --hmac vault-index -o doc.edvdoc.json
+```
+
+The resulting envelope carries `indexed: [{ hmac: { id, type }, sequence,
+attributes: [{ name, value, unique? }] }]`, where each `name`/`value` is the
+blinded (opaque) form. The envelope and its blinded entries are assembled by
+[`@interop/edv-client`](https://www.npmjs.com/package/@interop/edv-client)'s
+`EdvClientCore`, so they match what an EDV server expects byte-for-byte.
+
 ## Contribute
 
 PRs accepted. Please follow the code-style and contribution conventions in

package/dist/commands/did.d.ts

@@ -1,3 +1,12 @@
 import { Command } from 'commander';
+import { type DIDLog } from '@interop/did-method-webvh';
+/**
+ * Parse a raw did:webvh history log (newline-delimited JSON) into the entry
+ * array the library's resolver/updater expect, ignoring blank lines.
+ *
+ * @param logText {string}
+ * @returns {DIDLog}
+ */
+export declare function parseDidLog(logText: string): DIDLog;
 export declare function makeDidCommand(): Command;
 //# sourceMappingURL=did.d.ts.map

package/dist/commands/did.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"did.d.ts","sourceRoot":"","sources":["../../src/commands/did.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAgFnC,wBAAgB,cAAc,IAAI,OAAO,CA4tBxC"}
+{"version":3,"file":"did.d.ts","sourceRoot":"","sources":["../../src/commands/did.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAOnC,OAAO,EAIL,KAAK,MAAM,EAEZ,MAAM,2BAA2B,CAAA;AA2FlC;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKnD;AA6qBD,wBAAgB,cAAc,IAAI,OAAO,CA41CxC"}