@interop/did-cli 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,96 @@
 # 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

package/README.md

@@ -453,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
@@ -492,7 +650,8 @@ did:key:z6Mks...
 
 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. Pass a DID URL (a
+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:
 
 ```
@@ -534,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:
 
 ```
@@ -548,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
 
@@ -1146,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;

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;AA0FnC,wBAAgB,cAAc,IAAI,OAAO,CA0uBxC"}
+{"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"}