@interop/did-cli 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,165 @@
 # History
 
+## 0.15.0 - 2026-09-14
+
+### Added
+
+- `was request-grant` accepts an explicit `--save` (the default), so the
+  documented `--save --handle agent` invocation no longer fails with
+  "unknown option".
+- An integration test for `was request-grant` against the WAS server's
+  ephemeral-exchange facet, with a scripted wallet that opens the interaction
+  URL, delegates the public collection from the space controller's key, and
+  posts the response presentation back. It then publishes `index.html`
+  through the stored handle and fetches it anonymously as `text/html`.
+- `zcap import <capability>` validates a capability received outside the CLI
+  (a multibase `u...` string or a JSON file) and stores it, with optional
+  `--handle` / `--description`, so `--capability <handle>` can name it. It
+  refuses a capability whose id is already stored or a handle already in use.
+
+### Fixed
+
+- The `--wallet` deep link now carries the route and the `url` parameter in
+  the URL fragment (`<wallet>/#/external/request?url=<interaction url>`).
+  Freewallet routes on the fragment, so the earlier path form opened the
+  landing page instead of the approval page.
+
+### Changed
+
+- `@interop/zcap` is at `^11.3.0`, which exports the `checkCapability`
+  validator used by `zcap import`.
+- BREAKING: `was request-grant` takes the exchange host as `--exchange <url>`
+  instead of `--server <url>`. The flag only names the WAS server that hosts
+  the ephemeral exchange; the granted capability targets whichever space the
+  wallet picks. `WAS_SERVER_URL` remains the fallback.
+- BREAKING: the `encoded` form of a capability (printed by `zcap create`,
+  `zcap delegate`, `was grant`, and `was request-grant`) is now multibase
+  base64url (`u...`) instead of base58btc (`z...`); the `z` form is no longer
+  accepted by `--capability`. base58 is quadratic in the input size and
+  `@scure/base` refuses it past 2048 bytes, which a wallet-delegated
+  capability exceeds once it embeds its chain; `was request-grant` failed
+  after saving such a grant.
+- The `was` commands run was-client's service discovery against a space-owned
+  URL (the capability's invocation target, or the addressed space) instead of
+  the server origin, so a deployment whose origin serves a static page with
+  no service link (such as freewallet.cloud) still resolves.
+- Bumped `@interop/was-client` to `^0.64.0`. The Space root capability id is
+  now the canonical trailing-slash container URL and signed requests run
+  service discovery first, which was-teaching-server 0.33 and later require;
+  against those servers the previous client's delegated invocations were
+  refused as 404.
+
+## 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
@@ -82,7 +242,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
 
@@ -121,7 +281,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
@@ -457,7 +617,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
@@ -494,7 +654,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
@@ -534,8 +694,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
@@ -91,6 +91,7 @@ di vc remove|delete|rm <id>     remove a stored credential
 
 di zcap create                  create a root capability
 di zcap delegate                delegate (attenuate) a capability
+di zcap import <capability>     validate and store a received capability
 di zcap list                    list stored capabilities
 di zcap show|view|cat <id>      show a stored capability
 di zcap meta <id>               show/edit a capability's local metadata
@@ -109,6 +110,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,14 +120,33 @@ 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`.                                   |
 | `WAS_DID`                  | `was`                      | Default signing DID (or stored-DID handle) when `--did` is omitted.                                                                                  |
-| `WAS_SERVER_URL`           | `was`                      | Default WAS server base URL when `--server` is omitted.                                                                                              |
+| `WAS_SERVER_URL`           | `was`                      | Default WAS server base URL when `--server` (or `--exchange` for `request-grant`) 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
@@ -594,7 +615,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
@@ -633,8 +654,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).
@@ -654,7 +675,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:
 
 ```
@@ -693,6 +714,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
 
@@ -1046,7 +1069,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:
 
 ```
@@ -1178,7 +1201,7 @@ handed down a chain of signed _delegated_ capabilities, each one optionally
 narrowing the allowed actions or the target.
 
 Both commands print the capability as JSON together with an `encoded` field --
-the capability serialized and `base58btc`-encoded with a multibase `z` prefix --
+the capability serialized and base64url-encoded with a multibase `u` prefix --
 which is the compact form you pass to `zcap delegate --capability` to delegate
 it
 further. Pass `--save` to also write the capability to local wallet storage
@@ -1207,7 +1230,7 @@ Root capabilities are unsigned, so no key is needed:
     "controller": "did:key:z6Mkfeco2NSEPeFV3DkjNSabaCza1EoS3CmqLb1eJ5BriiaR",
     "invocationTarget": "https://example.com/api"
   },
-  "encoded": "z3g9TJBrQTdKemE9BC43N9WsT8snKvQzwCpCWs8o..."
+  "encoded": "ueyJAY29udGV4dCI6Imh0dHBzOi8vdzNpZC5vcmcvemNhcC92MSIsImlkIjoi..."
 }
 ```
 
@@ -1217,7 +1240,7 @@ and a root capability grants all actions (it has no `allowedAction`).
 
 #### Note about the `encoded` field
 
-The multibase- (that's the `z` prefix) and base58btc-encoded JSON of the zcap
+The multibase- (that's the `u` prefix) and base64url-encoded JSON of the zcap
 is returned, for convenience, in the `encoded` field.
 
 This is done for easier "double-click to copy" and pasting into other tools,
@@ -1265,7 +1288,7 @@ To delegate from the root capability for a target, pass `--url` (the same
       "proofValue": "z5tuwwdJE6VXLhf1v8SNAquBmMcJCD7zJ4bXDi6rh1Fk..."
     }
   },
-  "encoded": "zkL8vet8M2mn7akSpHEVvgFUCTVq4VSGs1s8Zsq9bYba..."
+  "encoded": "ueyJAY29udGV4dCI6WyJodHRwczovL3czaWQub3JnL3pjYXAvdjEi..."
 }
 ```
 
@@ -1290,7 +1313,7 @@ metadata handle of a zcap saved in local wallet storage. Use
 ./di zcap delegate \
   --did did:key:z6MknBxr... \
   --delegatee did:key:z6Mks... \
-  --capability zkL8vet8M2mn7akSpHEVvgFUCTVq4VSGs1s8Zsq9bYba... \
+  --capability ueyJAY29udGV4dCI6WyJodHRwczovL3czaWQub3JnL3pjYXAvdjEi... \
   --invocation-target https://example.com/documents/reports \
   --allow read
 ```
@@ -1419,7 +1442,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).
@@ -1498,7 +1521,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
@@ -1689,12 +1712,114 @@ the zcap store (`~/.config/did-cli-wallet/zcaps/`):
     "expires": "2027-06-11T17:30:00Z",
     "proof": { ... }
   },
-  "encoded": "zkL8vet8M2mn..."
+  "encoded": "ueyJAY29udGV4dCI6..."
 }
 ```
 
 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 --exchange https://freewallet.cloud/spaces/ \
+  --reason "Publish a demo page" --name "demo-publisher"
+Requesting "web" access for did:key:z6MkAgent...
+
+Open this in your wallet to approve:
+
+  https://freewallet.cloud/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 --exchange https://freewallet.cloud/spaces/ --wallet https://freewallet.me
+...
+Or open your wallet directly:
+
+  https://freewallet.me/#/external/request?url=https%3A%2F%2Ffreewallet.cloud%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 `u...` 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
+ueyJAY29udGV4dCI6...
+```
+
+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
+`--exchange <url>` (or `WAS_SERVER_URL`).
+
+`--exchange` names the WAS server that hosts the ephemeral exchange carrying
+the request. It is only the meeting point between this command and the wallet.
+The grant itself names its own target, whichever space the user's wallet picks,
+so the two servers need not be the same.
+
+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
@@ -1706,21 +1831,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
@@ -1733,7 +1869,7 @@ Bob's machine he can pass the encoded string or a JSON file directly):
 
 # Bob, with the encoded string he received out-of-band -- this reads the
 # resource the capability targets (home/credentials/vc-1):
-./di was get --capability zkL8vet8M2mn...
+./di was get --capability ueyJAY29udGV4dCI6...
 {
   "name": "Alice"
 }
@@ -1747,7 +1883,17 @@ 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...
+./di was ls --capability ueyJAY29udGV4dCI6...
+
+# ...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 ueyJAY29udGV4dCI6... \
+  --resource index.html --content-type text/html
+./di was get --capability ueyJAY29udGV4dCI6... --resource index.html
+
+# ...and the same flag deletes that one resource, rather than the whole
+# collection the capability targets:
+./di was rm --capability ueyJAY29udGV4dCI6... --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.