@interop/did-cli 0.13.0 → 0.15.0

package/dist/was/request-grant.js

@@ -0,0 +1,256 @@
+/**
+ * The requesting half of capability delegation (`was request-grant`), the
+ * inverse of `was grant`. Instead of signing a capability for someone else,
+ * this asks a user's wallet to sign one for us: it builds a zcap-only
+ * Verifiable Presentation Request (VPR), opens an ephemeral exchange on the
+ * WAS server to carry it, and waits for the wallet to post back a response
+ * presentation holding the delegated capabilities.
+ *
+ * Nothing here is signed. The exchange routes are unauthenticated by design --
+ * the exchange URL is itself the secret, and it travels point-to-point to the
+ * user (today as a printed interaction URL). Both the exchange transport and
+ * the zcap-only VPR composition come from `@interop/wallet-request`; what
+ * is owned here is the CLI's own request shape (the public-collection
+ * descriptor and the action normalization) and the response parsing.
+ */
+import { composeCapabilityRequest, createEphemeralExchange, pollEphemeralExchange, EPHEMERAL_EXCHANGE_TTL_MS } from '@interop/wallet-request';
+/**
+ * The wallet-defined descriptor for a world-readable collection under the
+ * user's own Space. Naming a descriptor rather than a URL is what lets the
+ * request be written before the Space exists: the wallet resolves it to one of
+ * its own collections at consent time.
+ */
+export const PUBLIC_COLLECTION_TYPE = 'https://w3id.org/byoe#public-collection';
+/** The collection the request names when `--collection` is not given. */
+export const DEFAULT_COLLECTION = 'web';
+/** The actions the request asks for when `--action` is not given. */
+export const DEFAULT_ACTIONS = ['GET', 'HEAD', 'PUT', 'POST'];
+/**
+ * The actions a capability request may name. A superset of the verbs
+ * `was grant` signs (it adds `HEAD`), because the wallet -- not this CLI -- is
+ * the authority on what it is willing to delegate.
+ */
+const REQUESTABLE_ACTIONS = ['GET', 'HEAD', 'PUT', 'POST', 'DELETE'];
+/**
+ * How long to wait for the user to approve before giving up: the server's
+ * exchange TTL, since past it the exchange is gone and no approval can arrive.
+ */
+export const DEFAULT_TIMEOUT_MS = EPHEMERAL_EXCHANGE_TTL_MS;
+/**
+ * The largest wait the poll's deadline accepts (a `setTimeout` delay, which is
+ * truncated to a signed 32-bit value and would otherwise fire at once).
+ * Anything past this is rejected as bad input rather than left to fail deep
+ * inside the poll.
+ */
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+/**
+ * Raised when the exchange itself ran but produced no grant: the user declined,
+ * let it expire, or approved a request the wallet could not satisfy. These are
+ * operation failures rather than bad input, and the command reports them as
+ * such. Internal to this package; nothing dispatches on the name across a
+ * package boundary.
+ */
+export class GrantRequestError extends Error {
+}
+let exchangeFetch;
+/**
+ * Replaces the `fetch` the exchange helpers transport over (a test-only seam,
+ * mirroring `setWasClientFactory`). Call with no argument to restore the
+ * global `fetch`.
+ *
+ * @param [fetchImpl] {FetchLike}
+ * @returns {void}
+ */
+export function setExchangeFetch(fetchImpl) {
+    exchangeFetch = fetchImpl;
+}
+/**
+ * Normalizes requested action verbs to their canonical uppercase form,
+ * rejecting anything that is not an HTTP verb a WAS server matches against.
+ *
+ * @param actions {string[]}
+ * @returns {string[]}
+ */
+function normalizeRequestedActions(actions) {
+    return actions.map(action => {
+        const verb = action.toUpperCase();
+        if (!REQUESTABLE_ACTIONS.includes(verb)) {
+            throw new Error(`Unknown action "${action}" (supported: ` +
+                `${REQUESTABLE_ACTIONS.join(', ')}).`);
+        }
+        return verb;
+    });
+}
+/**
+ * Builds the zcap-only VPR this command sends: one capability query naming the
+ * agent as the capability `controller` and a public-collection descriptor as
+ * the target, plus an optional root `agent` member naming what the agent
+ * calls itself, composed by wallet-core. There is deliberately no
+ * `DIDAuthentication` query and no `domain` -- the agent is asking for
+ * authority, not proving who it is to a verifier, and a CLI has no attested
+ * origin for a wallet to check a domain against (one sent anyway is enforced,
+ * and fails).
+ *
+ * @param options {object}
+ * @param options.controller {string}   The agent's did:key (the grantee).
+ * @param [options.collection] {string}   The collection name to request.
+ * @param [options.actions] {string[]}   The actions to request.
+ * @param [options.reason] {string}   Human-readable text shown at consent.
+ * @param [options.name] {string}   The agent's self-declared display name,
+ *   shown at consent as what it calls itself.
+ * @returns {IVPRDetails}
+ */
+export function buildCapabilityRequest({ controller, collection = DEFAULT_COLLECTION, actions = DEFAULT_ACTIONS, reason, name }) {
+    const capabilityQuery = {
+        ...(reason !== undefined && { reason }),
+        allowedAction: normalizeRequestedActions(actions),
+        controller,
+        invocationTarget: {
+            type: PUBLIC_COLLECTION_TYPE,
+            name: collection
+        }
+    };
+    return composeCapabilityRequest({
+        capabilityQueries: [capabilityQuery],
+        ...(name !== undefined && { agent: { name } })
+    });
+}
+/**
+ * The wallet route an outside request is handed to. Requests arriving from
+ * outside the app land under `/external/`; `/wallet/*` stays CHAPI-handler
+ * only. The wallet routes on the URL fragment, so the route (and the query it
+ * carries) lives after `#`.
+ */
+const WALLET_REQUEST_ROUTE = '/external/request';
+/**
+ * Resolves a wallet base URL to its external-request route, rejecting anything
+ * that is not an absolute http(s) URL. Kept separate from the link itself so a
+ * bad `--wallet` is caught before an exchange is opened for it.
+ *
+ * @param options {object}
+ * @param options.wallet {string}   The wallet's base URL.
+ * @returns {URL}   The base URL with the route as its fragment.
+ */
+export function walletRequestRoute({ wallet }) {
+    let base;
+    try {
+        base = new URL(wallet);
+    }
+    catch (err) {
+        throw new Error(`Invalid wallet URL "${wallet}": expected an absolute http(s) URL.`, { cause: err });
+    }
+    if (base.protocol !== 'https:' && base.protocol !== 'http:') {
+        throw new Error(`Invalid wallet URL "${wallet}": expected an http(s) URL, got ` +
+            `"${base.protocol}".`);
+    }
+    // Keep the base path (a wallet deployed under a sub-path keeps its prefix)
+    // and hang the route off it as the fragment.
+    const path = base.pathname.endsWith('/') ? base.pathname : `${base.pathname}/`;
+    const route = new URL(path, base);
+    route.hash = WALLET_REQUEST_ROUTE;
+    return route;
+}
+/**
+ * Builds the link that opens a wallet straight onto the approval page for an
+ * exchange, for the case where the user is already at a browser: the wallet's
+ * external-request route carrying the interaction URL as a percent-encoded
+ * `url` parameter. The parameter goes inside the fragment, after the route,
+ * because that is the only part of the URL a fragment-routed wallet reads.
+ * The interaction URL alone stays the fallback, since it is what a wallet on
+ * another device can be pointed at.
+ *
+ * @param options {object}
+ * @param options.route {URL}   The wallet's external-request route.
+ * @param options.interactionUrl {string}   The exchange's interaction URL.
+ * @returns {string}
+ */
+export function buildWalletDeepLink({ route, interactionUrl }) {
+    const link = new URL(route);
+    const params = new URLSearchParams({ url: interactionUrl });
+    link.hash = `${route.hash.slice(1)}?${params.toString()}`;
+    return link.toString();
+}
+/**
+ * Opens an ephemeral exchange on the WAS server carrying the request, and
+ * returns both the URL to poll and the interaction URL to hand the user.
+ *
+ * @param options {object}
+ * @param options.exchange {string}   Base URL of the WAS server hosting the
+ *   exchange.
+ * @param options.request {IVPRDetails}   The VPR to store on the exchange.
+ * @returns {Promise<{exchangeUrl: string, interactionUrl: string}>}
+ */
+export async function openGrantExchange({ exchange, request }) {
+    return createEphemeralExchange({
+        serverUrl: exchange,
+        request,
+        ...(exchangeFetch && { fetch: exchangeFetch })
+    });
+}
+/**
+ * Pulls the delegated capabilities out of a completed exchange response. The
+ * wallet posts `{ verifiablePresentation }`, and the zcaps ride inside that
+ * presentation as its `zcap` member.
+ *
+ * @param response {unknown}   The exchange's `response` member.
+ * @returns {IZcap[]}
+ */
+export function extractCapabilities(response) {
+    const presentation = response?.verifiablePresentation;
+    if (!presentation) {
+        throw new GrantRequestError('The wallet response contained no verifiablePresentation.');
+    }
+    const { zcap } = presentation;
+    const zcaps = zcap === undefined ? [] : Array.isArray(zcap) ? zcap : [zcap];
+    for (const capability of zcaps) {
+        if (typeof capability.id !== 'string' || capability.id === '') {
+            throw new GrantRequestError('The wallet returned a capability with no id, which cannot be filed ' +
+                'in the zcap store or named by a later --capability.');
+        }
+    }
+    if (zcaps.length === 0) {
+        throw new GrantRequestError('The wallet returned a presentation with no capabilities: the request ' +
+            'was declined, or the collection could not be granted (a public ' +
+            'collection is only ever created public, never converted from an ' +
+            'existing private one).');
+    }
+    return zcaps;
+}
+/**
+ * Waits for the user's wallet to complete the exchange, and returns the
+ * capabilities it delegated. Gives up at `timeoutMs`, and distinguishes an
+ * exchange the server has already dropped from one still waiting on the user.
+ *
+ * @param options {object}
+ * @param options.exchangeUrl {string}
+ * @param [options.timeoutMs] {number}
+ * @param [options.intervalMs] {number}   How often to poll.
+ * @returns {Promise<IZcap[]>}
+ */
+export async function awaitGrantedCapabilities({ exchangeUrl, timeoutMs = DEFAULT_TIMEOUT_MS, intervalMs }) {
+    let response;
+    try {
+        response = await pollEphemeralExchange({
+            exchangeUrl,
+            timeoutMs,
+            ...(intervalMs !== undefined && { intervalMs }),
+            ...(exchangeFetch && { fetch: exchangeFetch })
+        });
+    }
+    catch (err) {
+        // The transport is injected and may resolve to a different copy of
+        // wallet-core, so the error name is the stable contract here.
+        if (err.name === 'EphemeralExchangeGoneError') {
+            throw new GrantRequestError('The request expired before it was approved (the server keeps an ' +
+                'exchange for ten minutes). Run the command again for a fresh link.', { cause: err });
+        }
+        if (err.name === 'EphemeralExchangeTimeoutError') {
+            throw new GrantRequestError(`Gave up waiting for approval after ${Math.round(timeoutMs / 1000)}s. ` +
+                'The request may still be approvable; raise --timeout, or run the ' +
+                'command again for a fresh link.', { cause: err });
+        }
+        throw err;
+    }
+    return extractCapabilities(response);
+}
+//# sourceMappingURL=request-grant.js.map

package/dist/was/request-grant.js.map

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

package/dist/zcap/create.d.ts

@@ -8,7 +8,7 @@ import type { IRootZcap } from '@interop/data-integrity-core/zcap';
  * @param options.url {string}   The resource URI the capability targets (the
  *   `invocationTarget`).
  * @returns {{rootCapability: IRootZcap, encoded: string}}   The root capability
- *   and its multibase (base58btc) encoding.
+ *   and its multibase (base64url) encoding.
  */
 export declare function createCapability({ controller, url }: {
     controller: string;

package/dist/zcap/create.js

@@ -17,7 +17,7 @@ import { encodeCapability } from './encoding.js';
  * @param options.url {string}   The resource URI the capability targets (the
  *   `invocationTarget`).
  * @returns {{rootCapability: IRootZcap, encoded: string}}   The root capability
- *   and its multibase (base58btc) encoding.
+ *   and its multibase (base64url) encoding.
  */
 export function createCapability({ controller, url }) {
     const rootCapability = createRootCapability({

package/dist/zcap/delegate.d.ts

@@ -25,7 +25,7 @@ import type { IDelegatedZcap, IZcap } from '@interop/data-integrity-core/zcap';
  * @param [options.expires] {string}   Explicit ISO 8601 expiration (overrides
  *   `ttl`).
  * @returns {Promise<{delegatedCapability: IDelegatedZcap, encoded: string}>}
- *   The signed delegated capability and its multibase (base58btc) encoding.
+ *   The signed delegated capability and its multibase (base64url) encoding.
  */
 export declare function delegateCapability({ did, controller, delegatee, url, capability, invocationTarget, allow, ttl, expires }: {
     did?: string;

package/dist/zcap/delegate.js

@@ -46,7 +46,7 @@ import { loadDelegationSigner } from './signer.js';
  * @param [options.expires] {string}   Explicit ISO 8601 expiration (overrides
  *   `ttl`).
  * @returns {Promise<{delegatedCapability: IDelegatedZcap, encoded: string}>}
- *   The signed delegated capability and its multibase (base58btc) encoding.
+ *   The signed delegated capability and its multibase (base64url) encoding.
  */
 export async function delegateCapability({ did, controller, delegatee, url, capability, invocationTarget, allow, ttl = '1y', expires }) {
     const delegationSigner = await loadDelegationSigner({ did, controller });

package/dist/zcap/encoding.d.ts

@@ -1,16 +1,28 @@
 import type { IZcap } from '@interop/data-integrity-core/zcap';
 /**
- * Encodes a capability as a multibase (base58btc) string.
+ * Encodes a capability as a multibase (base64url, no padding) string.
  *
  * @param capability {IZcap}   The root or delegated capability to encode.
- * @returns {string}   The capability JSON, base58btc-encoded with a leading `z`.
+ * @returns {string}   The capability JSON, base64url-encoded with a leading
+ *   `u`.
  */
 export declare function encodeCapability(capability: IZcap): string;
 /**
- * Decodes a multibase (base58btc) capability string back into a capability.
+ * Tells whether a `--capability` value is an encoded capability rather than a
+ * file path or a stored id/handle. The `u` form is base64url of JSON that
+ * always opens with `{"`, so it always begins `ueyJ`; checking that prefix is
+ * what keeps a `urn:` capability id (which also begins with `u`) out of the
+ * decoder.
  *
- * @param encoded {string}   A `z`-prefixed base58btc string from
- *   `encodeCapability`.
+ * @param value {string}
+ * @returns {boolean}
+ */
+export declare function isEncodedCapability(value: string): boolean;
+/**
+ * Decodes a multibase (base64url, `u` prefix) capability string back into a
+ * capability.
+ *
+ * @param encoded {string}   A `u`-prefixed multibase string.
  * @returns {IZcap}   The decoded root or delegated capability.
  */
 export declare function decodeCapability(encoded: string): IZcap;

package/dist/zcap/encoding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/zcap/encoding.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAA;AAE9D;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,KAAK,GAAG,MAAM,CAG1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAQvD"}
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/zcap/encoding.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAA;AAE9D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,KAAK,GAAG,MAAM,CAG1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAQvD"}

package/dist/zcap/encoding.js

@@ -1,37 +1,51 @@
 /**
- * Multibase (base58btc) encoding for Authorization Capabilities (zcaps).
+ * Multibase encoding for Authorization Capabilities (zcaps).
  *
  * The CLI prints an `encoded` form alongside each capability: the capability's
- * JSON serialized to UTF-8 bytes, base58btc-encoded, with a leading `z`
- * multibase prefix (matching the legacy did-cli output). `decodeCapability`
- * reverses this so a delegated capability can be passed back in via
- * `zcap delegate --capability`. Uses `@scure/base`'s `base58` (the same base58
- * implementation used by `@interop/ed25519-verification-key`), which operates on
- * raw base58 without a multibase prefix, so the `z` is added/stripped here.
+ * JSON serialized to UTF-8 bytes, base64url-encoded without padding, with a
+ * leading `u` multibase prefix. `decodeCapability` reverses this so a
+ * delegated capability can be passed back in via `--capability`. base64url
+ * rather than base58btc because a delegated capability embeds its whole
+ * chain, and base58 is quadratic in the input size, so `@scure/base` refuses
+ * it past 2048 bytes -- smaller than a two-hop chain a wallet delegates.
  */
-import { base58 } from '@scure/base';
+import { base64urlnopad } from '@scure/base';
 /**
- * Encodes a capability as a multibase (base58btc) string.
+ * Encodes a capability as a multibase (base64url, no padding) string.
  *
  * @param capability {IZcap}   The root or delegated capability to encode.
- * @returns {string}   The capability JSON, base58btc-encoded with a leading `z`.
+ * @returns {string}   The capability JSON, base64url-encoded with a leading
+ *   `u`.
  */
 export function encodeCapability(capability) {
     const bytes = new TextEncoder().encode(JSON.stringify(capability));
-    return `z${base58.encode(bytes)}`;
+    return `u${base64urlnopad.encode(bytes)}`;
 }
 /**
- * Decodes a multibase (base58btc) capability string back into a capability.
+ * Tells whether a `--capability` value is an encoded capability rather than a
+ * file path or a stored id/handle. The `u` form is base64url of JSON that
+ * always opens with `{"`, so it always begins `ueyJ`; checking that prefix is
+ * what keeps a `urn:` capability id (which also begins with `u`) out of the
+ * decoder.
  *
- * @param encoded {string}   A `z`-prefixed base58btc string from
- *   `encodeCapability`.
+ * @param value {string}
+ * @returns {boolean}
+ */
+export function isEncodedCapability(value) {
+    return /^ueyJ[A-Za-z0-9_-]*$/.test(value);
+}
+/**
+ * Decodes a multibase (base64url, `u` prefix) capability string back into a
+ * capability.
+ *
+ * @param encoded {string}   A `u`-prefixed multibase string.
  * @returns {IZcap}   The decoded root or delegated capability.
  */
 export function decodeCapability(encoded) {
-    if (!encoded.startsWith('z')) {
-        throw new Error('Encoded capability must be a multibase base58btc string (leading "z").');
+    if (!encoded.startsWith('u')) {
+        throw new Error('Encoded capability must be a multibase base64url string (leading "u").');
     }
-    const bytes = base58.decode(encoded.slice(1));
+    const bytes = base64urlnopad.decode(encoded.slice(1));
     return JSON.parse(new TextDecoder().decode(bytes));
 }
 //# sourceMappingURL=encoding.js.map

package/dist/zcap/encoding.js.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/zcap/encoding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAGpC;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAiB;IAChD,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAA;IAClE,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IAC7C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAU,CAAA;AAC7D,CAAC"}
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/zcap/encoding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAG5C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAiB;IAChD,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAA;IAClE,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;AAC3C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAO,sBAAsB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,wEAAwE,CACzE,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACrD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAU,CAAA;AAC7D,CAAC"}

package/dist/zcap/resolve.d.ts

@@ -1,9 +1,22 @@
 import type { IZcap } from '@interop/data-integrity-core/zcap';
 /**
- * Resolves a `--capability` reference to a capability object. A value
- * beginning with `z` is decoded as a multibase capability string; a path to
- * an existing file is parsed as capability JSON; anything else is looked up
- * in the local zcap store by capability id or metadata handle.
+ * Reads a capability given directly rather than by stored reference: a value
+ * that `isEncodedCapability` recognizes is decoded as a multibase capability
+ * string, and a path to an existing file is parsed as capability JSON. Returns
+ * undefined when the value is neither.
+ *
+ * @param options {object}
+ * @param options.ref {string}
+ * @returns {Promise<IZcap | undefined>}
+ */
+export declare function readCapabilityInput({ ref }: {
+    ref: string;
+}): Promise<IZcap | undefined>;
+/**
+ * Resolves a `--capability` reference to a capability object. An encoded
+ * capability string or a capability JSON file is read by
+ * `readCapabilityInput`; anything else is looked up in the local zcap store by
+ * capability id or metadata handle.
  *
  * @param options {object}
  * @param options.ref {string}

package/dist/zcap/resolve.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/zcap/resolve.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAA;AAmB9D;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,GAAG,EACJ,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,OAAO,CAAC,KAAK,CAAC,CAuBjB"}
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/zcap/resolve.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mCAAmC,CAAA;AAmB9D;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,GAAG,EACJ,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAgB7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,GAAG,EACJ,EAAE;IACD,GAAG,EAAE,MAAM,CAAA;CACZ,GAAG,OAAO,CAAC,KAAK,CAAC,CAajB"}

package/dist/zcap/resolve.js

@@ -6,7 +6,7 @@
  */
 import { access, readFile } from 'node:fs/promises';
 import { resolveZcapRef } from '../meta.js';
-import { decodeCapability } from './encoding.js';
+import { decodeCapability, isEncodedCapability } from './encoding.js';
 /**
  * Returns true when the path exists on disk.
  *
@@ -23,17 +23,17 @@ async function fileExists(filePath) {
     }
 }
 /**
- * Resolves a `--capability` reference to a capability object. A value
- * beginning with `z` is decoded as a multibase capability string; a path to
- * an existing file is parsed as capability JSON; anything else is looked up
- * in the local zcap store by capability id or metadata handle.
+ * Reads a capability given directly rather than by stored reference: a value
+ * that `isEncodedCapability` recognizes is decoded as a multibase capability
+ * string, and a path to an existing file is parsed as capability JSON. Returns
+ * undefined when the value is neither.
  *
  * @param options {object}
  * @param options.ref {string}
- * @returns {Promise<IZcap>}
+ * @returns {Promise<IZcap | undefined>}
  */
-export async function resolveCapabilityInput({ ref }) {
-    if (ref.startsWith('z')) {
+export async function readCapabilityInput({ ref }) {
+    if (isEncodedCapability(ref)) {
         return decodeCapability(ref);
     }
     if (await fileExists(ref)) {
@@ -45,6 +45,23 @@ export async function resolveCapabilityInput({ ref }) {
                 `${err instanceof Error ? err.message : String(err)}`, { cause: err });
         }
     }
+    return undefined;
+}
+/**
+ * Resolves a `--capability` reference to a capability object. An encoded
+ * capability string or a capability JSON file is read by
+ * `readCapabilityInput`; anything else is looked up in the local zcap store by
+ * capability id or metadata handle.
+ *
+ * @param options {object}
+ * @param options.ref {string}
+ * @returns {Promise<IZcap>}
+ */
+export async function resolveCapabilityInput({ ref }) {
+    const direct = await readCapabilityInput({ ref });
+    if (direct) {
+        return direct;
+    }
     const stored = await resolveZcapRef({ ref });
     if (!stored) {
         throw new Error(`No capability found for "${ref}" (not an encoded string, a file, ` +

package/dist/zcap/resolve.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/zcap/resolve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAEhD;;;;;GAKG;AACH,KAAK,UAAU,UAAU,CAAC,QAAgB;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAA;QACtB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAC3C,GAAG,EAGJ;IACC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAA;IAC9B,CAAC;IACD,IAAI,MAAM,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAU,CAAA;QACzD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,qCAAqC;gBACzC,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EACvD,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAA;QACH,CAAC;IACH,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,GAAG,EAAE,CAAC,CAAA;IAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,4BAA4B,GAAG,oCAAoC;YACjE,8BAA8B,CACjC,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAa,CAAA;AAC7B,CAAC"}
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/zcap/resolve.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAErE;;;;;GAKG;AACH,KAAK,UAAU,UAAU,CAAC,QAAgB;IACxC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAA;QACtB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,EACxC,GAAG,EAGJ;IACC,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,gBAAgB,CAAC,GAAG,CAAC,CAAA;IAC9B,CAAC;IACD,IAAI,MAAM,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAU,CAAA;QACzD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,qCAAqC;gBACzC,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EACvD,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAA;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,EAC3C,GAAG,EAGJ;IACC,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,EAAE,GAAG,EAAE,CAAC,CAAA;IACjD,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,MAAM,CAAA;IACf,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,GAAG,EAAE,CAAC,CAAA;IAC5C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CACb,4BAA4B,GAAG,oCAAoC;YACjE,8BAA8B,CACjC,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,IAAa,CAAA;AAC7B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interop/did-cli",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "DID CLI tool for DIDs, Verifiable Credentials, key pairs, and zcaps",
   "type": "module",
   "main": "dist/index.js",
@@ -26,25 +26,27 @@
   "dependencies": {
     "@digitalcredentials/bnid": "^5.0.0",
     "@digitalcredentials/issuer-registry-client": "^4.0.0",
-    "@interop/data-integrity-core": "^8.2.0",
-    "@interop/data-integrity-proof": "^3.4.1",
-    "@interop/did-io": "^4.0.6",
-    "@interop/did-method-key": "^7.3.3",
-    "@interop/did-method-webvh": "^3.7.0",
-    "@interop/did-web-resolver": "^6.2.3",
-    "@interop/ecdsa-multikey": "^2.3.2",
-    "@interop/ecdsa-signature": "2.0.4",
-    "@interop/ed25519-signature": "^7.1.3",
-    "@interop/ed25519-verification-key": "^8.0.2",
-    "@interop/edv-client": "^17.6.1",
-    "@interop/ezcap": "^7.3.2",
-    "@interop/minimal-cipher": "^7.6.1",
-    "@interop/security-document-loader": "^9.4.1",
-    "@interop/vc": "^11.0.5",
-    "@interop/verifier-core": "^3.3.1",
-    "@interop/was-client": "^0.14.5",
-    "@interop/x25519-key-agreement-key": "^5.2.0",
-    "@interop/zcap": "^11.0.4",
+    "@interop/data-integrity-core": "^8.7.1",
+    "@interop/data-integrity-proof": "^3.4.5",
+    "@interop/did-io": "^4.1.1",
+    "@interop/did-method-key": "^7.4.2",
+    "@interop/did-method-webvh": "^5.9.0",
+    "@interop/did-web-resolver": "^6.3.3",
+    "@interop/ecdsa-multikey": "^2.4.0",
+    "@interop/ecdsa-signature": "2.0.7",
+    "@interop/ed25519-signature": "^7.2.2",
+    "@interop/ed25519-verification-key": "^8.2.0",
+    "@interop/edv-client": "^17.8.4",
+    "@interop/ezcap": "^7.4.8",
+    "@interop/minimal-cipher": "^7.10.2",
+    "@interop/security-document-loader": "^10.1.2",
+    "@interop/vc": "^11.0.9",
+    "@interop/verifier-core": "^3.5.8",
+    "@interop/wallet-core": "^0.78.0",
+    "@interop/wallet-request": "^0.3.1",
+    "@interop/was-client": "^0.64.0",
+    "@interop/x25519-key-agreement-key": "^5.4.0",
+    "@interop/zcap": "^11.3.0",
     "@scure/base": "^2.2.0",
     "commander": "^15.0.0"
   },