@interop/did-cli 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,130 @@
 # History
 
+## 0.14.0 - 2026-09-14
+
+### Added
+
+- `was request-grant` -- the requesting side of capability delegation, the
+  inverse of `was grant`. It mints an Ed25519 `did:key` for itself, asks a
+  user's wallet for a capability on one of its public collections, prints an
+  approval link for the user to open, waits for their answer, and files the
+  received capability in the zcap store. The grantee key is minted by the
+  command rather than passed in, so a caller driving the CLI never handles key
+  material: stdout carries the capability (or, with `--json`, one object holding
+  the DID, the handle, the link, and the capability), and the approval link and
+  progress notes go to stderr. The key is written only once the grant arrives,
+  and a handle already taken by a stored DID or capability is refused up front,
+  so handle lookups stay unambiguous across runs. Options are
+  `--collection` (default `web`), `--action` (default `GET HEAD PUT POST`),
+  `--reason`, `--timeout` (default 600 seconds, the server's exchange
+  lifetime), `--handle` (default `agent`), `--description`, `--no-save`,
+  `--json`, and `--server`. Persistence is on by default because
+  `--capability` resolves its signer out of the local DID store, so a key held
+  only for the run cannot sign the write that follows; `--no-save` prints the
+  capability without keeping either half. The request carries a single
+  `AuthorizationCapabilityQuery` naming a public-collection descriptor, with no
+  `DIDAuthentication` query and no `domain`.
+
+- `was request-grant --name <name>` sends the agent's self-declared display
+  name (the VPR's root `agent: { name }` member, wallet-core 0.53.0), shown on
+  the wallet consent screen as what the agent calls itself; at most 64
+  characters, no control characters.
+
+- `was request-grant --wallet <url>` also prints a link that opens the given
+  wallet straight onto its approval page for the exchange
+  (`<wallet>/external/request?url=<interaction url>`). The interaction URL is
+  still printed, for a wallet on another device. The wallet URL must be
+  absolute http(s), and a bad one is refused before any exchange is opened.
+
+- `--resource <id>` on `was get`, `was put`, `was meta get`, `was meta put`,
+  and `was rm`: names one resource beneath a collection-scoped
+  `--capability`, so a grant issued on a whole collection can read, write,
+  and delete at a caller-chosen id. `resource add` also takes a collection
+  capability, but the server picks the id there. The resource handle inherits
+  the collection's bound capability, so the request stays an invocation of
+  the received grant. `--resource` without a capability, or alongside a
+  capability that already targets a resource, is an input error.
+- A `publish-page` Claude Code skill (`.claude/skills/publish-page/`) and the
+  agent storage demo it scripts (`demo/agent-storage/README.md`): an LLM agent
+  drafts an `index.html`, asks the user's wallet for a grant on a public
+  collection with `was request-grant`, and publishes the page through the
+  delegated capability. The skill is model-invoked, states that `--save` is
+  required (a key held only for the run cannot sign the write that follows),
+  keeps the agent away from key material, and sends a user with no wallet
+  account to `<wallet>/signup` before resuming.
+
+- `was shell` -- an interactive REPL over the `was` command tree. Start it with
+  `di was shell [path]` (`--server`/`--did` seed the session defaults), then run
+  any `was` subcommand without re-typing space handles or re-paying the
+  cold-start cost. A "current directory" (`cd`/`use`, with `..`, `/`, relative
+  paths, and full space URLs) makes every command's path relative to it, and
+  `pwd`, `connect <url>`, `did <ref>`, `help`, and `exit`/`quit` round out the
+  builtins. Tab completion covers builtins, subcommands, and registered space
+  handles. The prompt and diagnostics go to stderr while command data stays on
+  stdout, so `di was shell < script` keeps a pipe-clean stdout.
+
+### Changed
+
+- Update to latest d-i-core, verifier-core, was-client and didwebvh deps.
+- Added `@interop/wallet-request` as a dependency, for the ephemeral-exchange
+  create and poll helpers `was request-grant` transports over, and for the
+  zcap-only presentation-request composer it sends (moved there from
+  wallet-core's `request` subpath).
+- `did webvh rotate-keys` and `did service add|remove` now pass the
+  already-resolved log state to `updateDID` as `priorMeta`, so each update
+  verifies the history log once instead of twice. The pairing between the log
+  and its resolved metadata is now asserted (O(1)) before signing.
+- `did webvh rotate-keys` edits the authorized `updateKeys` set instead of
+  rebuilding it from the single local key: a stage-only `--enable-prerotation`
+  leaves the set unchanged, and an ordinary rotation replaces only the retired
+  key, so co-authorized update keys are no longer silently revoked.
+- `rotate-keys --update-key` now authorizes every supplied key instead of
+  silently dropping all but the first.
+- did:webvh updates persist crash-safely: the update-keys sidecar (including
+  the superseded secret) is written before the log that authorizes the new
+  key, and the signer loaders can recover from a rotation interrupted between
+  the two writes.
+- Stored artifacts (DID documents, history logs, sidecars, wallet items) are
+  written atomically (temp file + rename), so an interrupted write can no
+  longer leave a truncated file.
+- Stored artifacts are now written with mode `0600` (owner read/write only)
+  instead of the ambient umask default, since keys are held as plaintext
+  Multikey documents. Wallet and DID directories are created with mode `0700`,
+  since a DID document is named after its DID. Existing files are not
+  migrated.
+- The atomic-write temp file is unlinked and reopened with `wx` rather than
+  chmod-ed after the write, so a temp file left behind by an interrupted run
+  cannot receive a secret at its own wider mode.
+- Confirmation prompts no longer auto-confirm when stdin is not interactive;
+  non-interactive runs must pass `--yes`, and a declined confirmation now
+  exits 1.
+- An empty `SECRET_KEY_SEED` env var is treated as unset, and an invalid one
+  is reported as a one-line error; seed derivation is shared across
+  `key create`, `did create`, and `rotate-keys`.
+- Command errors that escape a runner are reported as one-line messages with
+  exit 1 instead of surfacing as unhandled rejections; a corrupt update-keys
+  sidecar reports its file path.
+- `did add-service` validates `--endpoint`/`--endpoint-json` arguments before
+  resolving (and re-verifying) a did:webvh history log; `rotate-keys` likewise
+  checks flag conflicts before resolution.
+- Bumped `@interop/ed25519-verification-key` to `^8.2.0` and switched the
+  did:webvh entry signer to its new `didKeySigner()` method, so the caller no
+  longer mutates `keyPair.id` before signing.
+
+## 0.13.0 - 2026-07-12
+
+### Added
+
+- `key create --type aes256` generates a symmetric AES-256 key-encryption key
+  (KEK): 32 random bytes carried as a `Multikey` `secretKeyMultibase` (the
+  AES-256 multicodec header `0xa2 0x01` followed by the raw key bytes),
+  identified by a `urn:kek:sha256:` id derived from the SHA-256 digest of the
+  raw key bytes. This is the form Wallet Attached Storage servers accept for
+  their at-rest key-encryption-key configuration. Generation is always fresh and
+  random, so `--with-seed` and `SECRET_KEY_SEED` are not supported for this
+  type. `key show` prints only the safe `id` and `type` for a saved KEK, never
+  the secret material.
+
 ## 0.12.0 - 2026-07-09
 
 ### Changed
@@ -68,7 +193,7 @@
 - `vc issue --did` now accepts a metadata handle (not just a full DID id),
   resolving it via the same lookup used by the other DID-referencing commands.
   Previously passing a handle failed with a confusing `The "path" argument must
-  be of type string. Received undefined` error.
+be of type string. Received undefined` error.
 
 ### Changed
 
@@ -107,7 +232,7 @@
   field); `loadFromCollection` / `saveToCollection` take an options object like
   the rest of the storage helpers; `vc/issue` and `vc/verify` replace their
   `as never` casts with typed ones; `edv/recipients` replaces `Record<string,
-  any>` with a named `VerificationMethodNode` type; `edv`'s encrypt functions
+any>` with a named `VerificationMethodNode` type; `edv`'s encrypt functions
   share an `EnvelopeOptions` type and a `resolveEncryptContextOrReport` wrapper;
   and the `z6Mk` / `z6LS` multibase prefixes are named constants. Added the
   file-level JSDoc header to `key.ts` and moved the `zcap revoke` stub message to
@@ -443,7 +568,7 @@
     `--handle` / `--description` tag it (exit `1` without `--save`).
   - Add `vc list` (`--json` / `--plain`) to render a metadata table of the
     stored credentials (`HANDLE | TYPE | ISSUER | CREATED | ID |
-    DESCRIPTION`), `vc show <id>` (aliases: `view`, `cat`; `--meta` for the
+DESCRIPTION`), `vc show <id>` (aliases: `view`, `cat`; `--meta` for the
     metadata, `--meta --json` for it as JSON), `vc meta <id>` to edit the
     metadata sidecar, and `vc remove <id>` (aliases: `delete`, `rm`). All
     accept a credential id, a storage id (for id-less credentials), or a
@@ -480,7 +605,7 @@
   `did create --save` and `did add-key`).
 - Add metadata support for locally stored keys and DIDs, persisted as
   `.meta.json` sidecar files next to the stored item (`~/.wallet/keys/
-  <storageId>.meta.json` and `~/.dids/<method>/<did>.meta.json`, following the
+<storageId>.meta.json` and `~/.dids/<method>/<did>.meta.json`, following the
   existing `.keys.json` sidecar pattern). Metadata fields: `created` (ISO 8601
   timestamp written at `--save` time), `handle` (a short user-defined tag),
   `description` (longer free text), and -- for keys -- `dids`, a cache of the
@@ -520,8 +645,8 @@
   the new `--plain` flag for the previous one-item-per-line output.
 - **BREAKING**: `key list --json` and `did list --json` now output an array of
   objects with metadata (`{fingerprint, storageId, type, curve?, created?,
-  handle?, description?, dids}` for keys; `{did, method, created?, handle?,
-  description?}` for DIDs) instead of an array of plain strings.
+handle?, description?, dids}` for keys; `{did, method, created?, handle?,
+description?}` for DIDs) instead of an array of plain strings.
 
 ## 0.4.0 - 2026-06-09
 

package/README.md

@@ -25,7 +25,7 @@ cryptographic key pairs that underpin them.
 It lets you generate and manage these objects locally -- minting DIDs, issuing
 and verifying credentials, delegating capabilities, and encrypting data -- and
 interact with remote
-[Wallet Attached Storage](https://digitalcredentials.github.io/wallet-attached-storage-spec/)
+[Wallet Attached Storage](https://w3c-ccg.github.io/wallet-attached-storage-spec/)
 servers, all from the terminal and backed by a local file-based wallet.
 
 ### Features
@@ -109,6 +109,7 @@ di was ls|get|put|rm [path]     depth-dispatching shorthands
 di was policy <show|set|clear>  manage access-control policies
 di was publish|unpublish <path> toggle world-readable access
 di was grant <path>             delegate access via a signed capability
+di was request-grant            ask a wallet for a capability on a collection
 ```
 
 ### Environment Variables
@@ -118,7 +119,7 @@ or secret-key seeds for individual commands. Each is also documented inline in
 the relevant command section below.
 
 | Variable                   | Used by                    | Purpose                                                                                                                                              |
-|----------------------------|----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| -------------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `WALLET_DIR`               | all                        | Wallet collections directory (`keys/`, `zcaps/`, `credentials/`, `was-spaces/`). Defaults to `~/.config/did-cli-wallet/` (honors `XDG_CONFIG_HOME`). |
 | `DIDS_DIR`                 | `did`                      | DID-documents directory. Defaults to `<WALLET_DIR>/dids/`.                                                                                           |
 | `SECRET_KEY_SEED`          | `key create`, `did create` | Multibase-encoded seed for deterministic key/DID generation. Not supported with `--type ecdsa` or `--type x25519`.                                   |
@@ -126,6 +127,25 @@ the relevant command section below.
 | `WAS_SERVER_URL`           | `was`                      | Default WAS server base URL when `--server` is omitted.                                                                                              |
 | `ZCAP_CONTROLLER_KEY_SEED` | `zcap`                     | Controller signing-key seed for delegating capabilities.                                                                                             |
 
+### File Permissions
+
+Everything written under `WALLET_DIR` and `DIDS_DIR` -- keys, zcaps,
+credentials, space records, DID documents, sidecars, and history logs -- is
+created with mode `0600`, owner read/write only. Directories are created with
+mode `0700`, since a DID document is named after its DID and the file names
+alone reveal what you hold. Secret key material is stored as plaintext Multikey
+documents, so the file mode is what keeps it off other local accounts.
+
+Files written before this became the default are not migrated. To tighten an
+existing wallet directory:
+
+```
+chmod -R u=rwX,go= ~/.config/did-cli-wallet
+```
+
+The capital `X` matters -- a plain `chmod -R 600` would clear the traverse bit
+on the directories and leave the wallet unreadable to you as well.
+
 ### Key Management
 
 #### Create a key pair
@@ -166,7 +186,7 @@ SECRET_KEY_SEED=z1AXVyT6G1Qk3E9cMPkDYY6wVRpZjVGWAZ3TfrAgFZkX6bv ./di key create
 ```
 
 Specify an explicit key type with `--type` (defaults to `ed25519`; supported:
-`ed25519`, `ecdsa`, `x25519`, `hmac`):
+`ed25519`, `ecdsa`, `x25519`, `hmac`, `aes256`):
 
 ```
 SECRET_KEY_SEED=z1Aaj5A4UCsd... ./di key create --type ed25519
@@ -244,6 +264,32 @@ half), identified by a random `urn:uuid:` id:
 HMAC key generation is non-deterministic, so `--with-seed` and `SECRET_KEY_SEED`
 are not supported with `--type hmac`.
 
+Generate a symmetric AES-256 key-encryption key (KEK) -- 32 random bytes carried
+as a Multikey `secretKeyMultibase` -- with `--type aes256`:
+
+```
+./di key create --type aes256
+```
+
+It is serialized as a `Multikey` with the secret carried as a base58btc
+`secretKeyMultibase` (the AES-256 multicodec header `0xa2 0x01` followed by the
+32 raw key bytes, no public half), identified by a `urn:kek:sha256:` id derived
+from the SHA-256 digest of the raw key bytes:
+
+```json
+{
+  "id": "urn:kek:sha256:...",
+  "type": "Multikey",
+  "secretKeyMultibase": "z..."
+}
+```
+
+This is the form Wallet Attached Storage servers accept for their at-rest
+key-encryption-key configuration (`KMS_RECORD_KEK` / `KMS_RECORD_KEKS`), where
+each KEK is identified by the same derived `urn:kek:sha256:` id. Generation is
+always fresh and random, so `--with-seed` and `SECRET_KEY_SEED` are not
+supported with `--type aes256`.
+
 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
@@ -568,7 +614,7 @@ 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
+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
@@ -607,8 +653,8 @@ A few more create-time options are recorded in the signed history-log
   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;
+<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).
@@ -628,7 +674,7 @@ Rotate the update (authorization) key of a locally stored `did:webvh` DID with
 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*
+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:
 
 ```
@@ -667,6 +713,8 @@ Flags:
   new key (a bare `--stop-prerotation` reveal, or rotating to an external
   `--update-key`).
 - `-y`, `--yes` -- skip the confirmation prompt (rotation is hard to undo).
+  Required when stdin is not interactive (scripts, cron), where the prompt
+  cannot be asked.
 
 #### Add or remove a service entry
 
@@ -1020,7 +1068,7 @@ Store an existing Verifiable Credential in local wallet storage with
 `vc import`. The credential is read from a file argument, an http(s) URL, or,
 if neither is given, from stdin. The input must structurally look like a
 credential (its `type` must include `VerifiableCredential`); it is stored
-as-is and is *not* verified on import (run `vc verify` for that). `--handle` /
+as-is and is _not_ verified on import (run `vc verify` for that). `--handle` /
 `--description` tag the saved credential:
 
 ```
@@ -1393,7 +1441,7 @@ valid until it expires (see `--ttl` / `--expires`).
 ### Wallet Attached Storage (WAS)
 
 The `was` command group is a client for
-[Wallet Attached Storage](https://digitalcredentials.github.io/wallet-attached-storage-spec/)
+[Wallet Attached Storage](https://w3c-ccg.github.io/wallet-attached-storage-spec/)
 servers, which organize content as `Space > Collection > Resource` behind
 zcap-authorized HTTP. Every request is signed with a `did:key` DID stored in
 the local wallet (saved with `did create --save`; Ed25519 keys only for now).
@@ -1472,7 +1520,7 @@ 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
+_existing_ remote space (a full space URL, or a bare id plus `--server`) in
 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
@@ -1669,6 +1717,103 @@ the zcap store (`~/.config/did-cli-wallet/zcaps/`):
 
 Hand the `encoded` string (or the JSON) to the delegatee out-of-band.
 
+#### Request a grant
+
+`was request-grant` is the inverse of `was grant`, for the case where you are
+the one who needs access. It asks a user's wallet to delegate a capability on
+one of its public collections, and is what lets a program publish into someone
+else's storage without ever logging into their wallet.
+
+The grantee key is minted by the command rather than passed in, so a script (or
+an LLM agent) driving the CLI never handles key material: the secret goes
+straight into local DID storage, and stdout carries only the capability. The
+approval link and the progress notes go to stderr; `--json` puts the DID, the
+handle, the link, and the capability into one object on stdout instead.
+
+```
+./di was request-grant --server https://was.example \
+  --reason "Publish a demo page" --name "demo-publisher"
+Requesting "web" access for did:key:z6MkAgent...
+
+Open this in your wallet to approve:
+
+  https://was.example/workflows/ephemeral/exchanges/abc-123/protocols?iuv=1
+
+Waiting for approval...
+```
+
+If you know which wallet the user runs, `--wallet <url>` also prints a link
+that opens it straight onto the approval page for this request:
+
+```
+./di was request-grant --server https://was.example --wallet https://wallet.example
+...
+Or open your wallet directly:
+
+  https://wallet.example/external/request?url=https%3A%2F%2Fwas.example%2F...
+```
+
+The interaction URL is still printed beside it, since that is what a wallet on
+another device can be pointed at.
+
+The user opens that link in their wallet and approves. The command then prints
+the capability it received (the same `z...` form `--capability` accepts) and
+files it in the zcap store under `--handle` (default `agent`), together with the
+minted key:
+
+```
+Capability saved to ~/.config/did-cli-wallet/zcaps/urn_uuid_....json
+Granted. Use it with --capability agent, for example:
+  di was put ./index.html --capability agent --did agent --resource index.html --content-type text/html
+zkL8vet8M2mn...
+```
+
+Saving is what makes the grant usable: `--capability` resolves its signing key
+out of the local DID store, so a key held only for the run cannot sign the write
+that follows. `--no-save` prints the capability without keeping either half, for
+inspecting a grant you do not intend to use.
+
+The signing DID is taken from `--did` first, then `WAS_DID`, and only then the
+capability's own `controller`. Naming the minted key explicitly
+(`--did agent`, matching the handle the grant was filed under) is therefore
+worth doing whenever `WAS_DID` is set in the environment, or the write is signed
+by your own DID and the server rejects it.
+
+A run files the minted key and the received capability under the same handle, so
+a handle already taken by a stored DID or capability is refused before anything
+is minted; pass a different `--handle` for a second grant. Nothing is written
+until the grant arrives -- a request that is declined, expires, or times out
+leaves no key behind.
+
+Options are `--collection <name>` (default `web`), `--action <verb...>` (default
+`GET HEAD PUT POST`), `--reason <text>` (shown to the user at the consent step),
+`--name <name>` (what the agent calls itself, shown to the user beside its
+key), `--wallet <url>` (a wallet base URL to print an approval deep link for),
+`--timeout <seconds>` (default 600, matching the server's exchange
+lifetime), `--handle` / `--description`, `--no-save`, `--json`, and `--server`
+(or `WAS_SERVER_URL`).
+
+The end-to-end flow this command exists for -- an LLM agent drafting a page and
+publishing it to the user's own storage -- is scripted in
+[demo/agent-storage](demo/agent-storage/README.md), with the agent-facing
+version in the `publish-page` skill under `.claude/skills/`.
+
+`--name` is self-declared, not verified: the wallet shows it as what the agent
+calls itself, next to the grantee key, so the user should still compare the
+key rather than trust the name alone. It is at most 64 characters and cannot
+contain control characters.
+
+Two things the wallet decides, not this command:
+
+- A public collection is only ever created public. If the named collection
+  already exists and is not world-readable, the wallet cannot satisfy the
+  request, and the approval comes back granting nothing.
+- The actions you ask for are a request, not an instruction. The wallet caps
+  them by what the collection allows, and may grant fewer than you asked for.
+
+The exchange lives on the server for ten minutes. After that the link is dead
+and the command reports it; run it again for a fresh one.
+
 #### Use a received capability
 
 On the receiving side, `ls` / `get` / `put` / `rm` (and `resource
@@ -1680,21 +1825,32 @@ of:
 - the capability id or metadata **handle of a zcap** stored in
   `~/.config/did-cli-wallet/zcaps/`.
 
-Note that a `--capability` reference is *not* a WAS path -- no space,
+Note that a `--capability` reference is _not_ a WAS path -- no space,
 collection, or resource address is given (or needed). The capability itself
 records what it grants access to in its `invocationTarget`, and that is what
 the command operates on:
 
-- a capability granted on a **resource** drives `get` / `put` / `rm`;
+- a capability granted on a **resource** drives `get` / `put` / `rm` and
+  `meta get` / `meta put`;
 - one granted on a **collection** drives `ls`, `resource add`, and `rm`;
 - one granted on a whole **space** drives `ls` and `rm`.
 
-A depth mismatch (e.g. `get` with a collection-scoped capability) is an
-input error. The server URL is taken from the invocation target's origin,
-and the signing DID defaults to the capability's controller (the delegatee)
-when that DID is stored locally -- so usually no flags are needed at all.
-
-In the examples below, `bob-share` is the metadata handle of a *stored zcap*
+A collection-scoped capability also reaches one resource inside it, named
+with `--resource <id>`: `get`, `put`, `meta get`, `meta put`, and `rm` then
+act on that id beneath the capability's collection (without the flag, `rm`
+deletes the collection itself). This is how a grant issued on a whole
+collection writes at an id you choose (`resource add` also takes a collection
+capability, but the server picks the id, so it cannot produce `index.html`).
+The resource handle inherits the collection's capability, so the request is
+still an invocation of the grant you received.
+
+Any other depth mismatch (e.g. `get` with a space-scoped capability) is an
+input error, as is `--resource` without a capability to anchor it. The
+server URL is taken from the invocation target's origin, and the signing DID
+defaults to the capability's controller (the delegatee) when that DID is
+stored locally -- so usually no flags are needed at all.
+
+In the examples below, `bob-share` is the metadata handle of a _stored zcap_
 (not a space or collection handle): say Alice granted Bob `GET`/`PUT` on the
 single resource `home/credentials/vc-1`, and the capability was saved with
 `--save --handle bob-share` (on Alice's machine via `was grant --save`; on
@@ -1722,6 +1878,16 @@ Bob's machine he can pass the encoded string or a JSON file directly):
 # Had the grant been on the whole collection (home/credentials), ls would
 # list it and `resource add` could post new resources into it:
 ./di was ls --capability zkL8vet8M2mn...
+
+# ...and --resource picks one id inside that collection, so the write lands
+# at a name you choose rather than a server-generated one:
+./di was put ./index.html --capability zkL8vet8M2mn... \
+  --resource index.html --content-type text/html
+./di was get --capability zkL8vet8M2mn... --resource index.html
+
+# ...and the same flag deletes that one resource, rather than the whole
+# collection the capability targets:
+./di was rm --capability zkL8vet8M2mn... --resource index.html
 ```
 
 #### Policies and public sharing

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

@@ -4,6 +4,28 @@
  * `add-key` default purpose set (described in its help text).
  */
 export declare const DEFAULT_VERIFICATION_PURPOSES: readonly ["authentication", "assertionMethod", "capabilityDelegation", "capabilityInvocation"];
+/**
+ * Save the artifacts of a newly created DID: the DID document, its keys file,
+ * a metadata sidecar (creation timestamp plus the handle and description when
+ * given), and the key-to-DID association cache of any matching wallet keys.
+ *
+ * @param options {object}
+ * @param options.method {string}
+ * @param options.didDocument {object}
+ * @param options.exportedKeys {object}
+ * @param options.fingerprints {(string | undefined)[]}
+ * @param [options.handle] {string}
+ * @param [options.description] {string}
+ * @returns {Promise<void>}
+ */
+export declare function saveDidArtifacts({ method, didDocument, exportedKeys, fingerprints, handle, description }: {
+    method: string;
+    didDocument: object;
+    exportedKeys: object;
+    fingerprints: (string | undefined)[];
+    handle?: string;
+    description?: string;
+}): Promise<void>;
 /**
  * Create a new DID of the given method (key, web, or webvh), optionally saving
  * its document, keys, and metadata to local storage, and print it to stdout.

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

@@ -1 +1 @@
-{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/did/create.ts"],"names":[],"mappings":"AAsCA;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,gGAKhC,CAAA;AAuJV;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2XlB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsIlB"}
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../../src/commands/did/create.ts"],"names":[],"mappings":"AAmCA;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,gGAKhC,CAAA;AAEV;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,MAAM,EACN,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,WAAW,EACZ,EAAE;IACD,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,CAAC,MAAM,GAAG,SAAS,CAAC,EAAE,CAAA;IACpC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkBhB;AA8ED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GAAG,OAAO,CAAC,MAAM,CAAC,CA2XlB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsIlB"}

package/dist/commands/did/create.js

@@ -1,11 +1,10 @@
 /**
  * DID creation and key addition: `runCreate` (key, web, webvh) and `runAddKey`
- * (add a verification key to a stored did:web). Both share the seed-derivation,
- * ECDSA-curve, non-deterministic-seed-guard, and output helpers at the top of
- * this module; the webvh signer/sidecar plumbing is reused from
- * `./webvh-update.js`.
+ * (add a verification key to a stored did:web). Both share the ECDSA-curve,
+ * non-deterministic-seed-guard, and output helpers at the top of this module;
+ * seed derivation comes from `../../keys/seed.js` and the webvh signer/sidecar
+ * plumbing is reused from `./webvh-update.js`.
  */
-import { decodeSecretKeySeed, generateSecretKeySeed } from '@digitalcredentials/bnid';
 import { driver } from '@interop/did-method-key';
 import * as didWeb from '@interop/did-web-resolver';
 import { createDID } from '@interop/did-method-webvh';
@@ -15,6 +14,7 @@ import { X25519KeyAgreementKey2020 } from '@interop/x25519-key-agreement-key';
 import { loadDidDocument, loadDidKeys, saveDidLog, saveDidMeta, saveToDids } from '../../storage.js';
 import { recordKeyDidAssociation } from '../../meta.js';
 import { normalizeEcdsaCurve, SUPPORTED_ECDSA_CURVES, warnIfNotVcIssuanceCapable } from '../../keys/ecdsa.js';
+import { deriveSeed } from '../../keys/seed.js';
 import { exportUpdateKey, generateStagedKey } from '../../keys/webvh-update.js';
 import { requireSaveForMetaFlags } from '../collection-command.js';
 import { makeWebvhEntrySigner, persistUpdateKeysSidecar } from './webvh-update.js';
@@ -43,7 +43,7 @@ export const DEFAULT_VERIFICATION_PURPOSES = [
  * @param [options.description] {string}
  * @returns {Promise<void>}
  */
-async function saveDidArtifacts({ method, didDocument, exportedKeys, fingerprints, handle, description }) {
+export async function saveDidArtifacts({ method, didDocument, exportedKeys, fingerprints, handle, description }) {
     const did = didDocument.id;
     const docPath = await saveToDids({ method, did, data: didDocument });
     await saveToDids({ method, did, suffix: 'keys', data: exportedKeys });
@@ -62,27 +62,6 @@ async function saveDidArtifacts({ method, didDocument, exportedKeys, fingerprint
     }
     console.error(`DID saved to ${docPath}`);
 }
-/**
- * Resolve the secret key seed for a deterministic (Ed25519) key. With
- * `--with-seed`, an existing `SECRET_KEY_SEED` env var is honored or a fresh
- * seed generated; without it, only an explicitly set env seed is used. Returns
- * the encoded seed (echoed back to the user) and its decoded bytes (for key
- * generation).
- *
- * @param options {object}
- * @param [options.withSeed] {boolean}
- * @returns {Promise<{ secretKeySeed?: string, seedBytes?: Uint8Array }>}
- */
-async function deriveSeed({ withSeed }) {
-    const envSeed = process.env.SECRET_KEY_SEED;
-    const secretKeySeed = withSeed
-        ? (envSeed ?? (await generateSecretKeySeed()))
-        : envSeed;
-    const seedBytes = secretKeySeed
-        ? decodeSecretKeySeed({ secretKeySeed })
-        : undefined;
-    return { secretKeySeed, seedBytes };
-}
 /**
  * Guard a non-deterministic key type against `--with-seed`: ECDSA and X25519
  * keys are generated non-deterministically and cannot be derived from a seed.