@didis/client 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to `@didis/client` are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the package uses [Semantic Versioning](https://semver.org/). Before 1.0.0, a minor version (0.x.0) may add features; breaking changes are called out under **Changed** with a migration note.
+
+## [Unreleased]
+
+## [0.2.1] - 2026-10-14
+
+### Added
+
+- Guard option `capability` (on `check`, `wrap` and `withDidisGuard`): the DID.is capability a tool needs when it differs from the tool name. MCP and OpenAI tool names cannot contain `:`, so use `{ tool: "weather_forecast", capability: "weather:forecast" }`. Pins stay keyed by the tool name; DID.is is asked about the capability; the ALLOW cache is keyed by capability. Without `capability`, behaviour is unchanged (the tool name is the capability).
+- `onDecision` events and `DidisGuardError.detail` now include `capability`.
+- Examples for the MCP TypeScript SDK (`mcp-client.mjs`), LangChain (`langchain-tool.mjs`) and the OpenAI Agents SDK (`openai-agents-tool.mjs`).
+
+### Changed
+
+- A capability containing `*`, empty segments or whitespace is refused with `GUARD_MISCONFIGURED` before any network call. Wildcards belong in delegations, not in tool calls.
+
+## [0.2.0] - 2026-10-13
+
+### Added
+
+- Fail-closed tool guard: `createDidisGuard`, `withDidisGuard` and `DidisGuardError`. A guarded handler runs only when the tool definition still matches its pin and DID.is `verifyTool` answers `ALLOW` for the configured agent (and root, if set). Drift, `DENY`, network errors, `429` and unexpected answers all throw, and the handler does not run. See [Guard agent tools](https://docs.did.is/build/guard-tools/).
+- Tool definition pinning: `canonicalJson` (RFC 8785 JCS), `toolDefinitionSha256`, `mcpInventoryHash` and `pinToolDefinitions`. Hashes are identical to the `definitionSha256` and `inventoryHash` values DID.is reports.
+- `attestMcpPins(client, endpoint, pins)` compares a public MCP server, as observed by DID.is, with your pins.
+- `verifyCredential` options `expectedNonce` and `trustedIssuerCertificates` (SD-JWT VC key binding and caller-chosen X.509 anchors), with the `CredentialVerifyOptions` type.
+- Response types `IssuerTrust` and `SdJwtEvidence`, and the optional `issuerTrust` and `sdJwt` fields on `CredentialVerification`.
+
+### Fixed
+
+- Node 18: WebCrypto is loaded from `node:crypto` when there is no global `crypto`. Before this, `verifyWebhookSignature` and `verifyCustomerMonitorSignature` failed on Node 18 with `crypto is not defined`.
+
+## [0.1.0] - 2026-10-05
+
+### Added
+
+- First public release as `@didis/client`. Zero dependencies, ESM, Node 18+, Deno, Bun, browsers and edge runtimes.
+- `DidisClient` for the DID.is public API (default base URL `https://did.is/api`): `health`, `resolve`, `resolveW3c`, `dereference`, `stream` (server-sent events), `history`, `diff`, `graph`, `verifyCredential`, `evaluatePolicy`, `inspectMcp`, `inspectA2a`, `verifyDelegation`, `authorize`, `verifyTool`, `fastVerifyDid` and `fastVerifyJws`.
+- Self-hosted monitoring methods that need an admin token: `watch`, `watches`, `unwatch` and `events`.
+- `DidisError` carrying the RFC 9457 problem body and `Retry-After`.
+- Webhook helpers `verifyWebhookSignature` and `verifyCustomerMonitorSignature`.
+
+[Unreleased]: https://github.com/did-is/didis-js/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/did-is/didis-js/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/did-is/didis-js/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/did-is/didis-js/releases/tag/v0.1.0

package/README.md

@@ -83,15 +83,24 @@ const guard = createDidisGuard({
 });
 
 const createIssue = guard.wrap(
-  { tool: "github:create_issue", definition: () => currentTools.get("github:create_issue") },
+  {
+    tool: "github_create_issue",          // the name in tools/list (pin key)
+    capability: "github:create_issue",    // what the delegation must grant
+    definition: () => currentTools.get("github_create_issue"),
+  },
   async (args) => github.createIssue(args),
 );
 ```
 
+**Tool name vs capability.** MCP and OpenAI tool names may only contain letters, digits, `_`, `-` and `.`, so a tool cannot be called `github:create_issue`. DID.is capabilities use `:` namespaces so that `github:*` can grant a whole group. Pass both: `tool` is used for the pin and error messages, `capability` is what DID.is is asked about. Without `capability`, the tool name is used. A capability must be exact (no `*`, no empty segments, no spaces); an invalid one throws `GUARD_MISCONFIGURED` before any network call. Since 0.2.1.
+
+Guarding MCP clients, LangChain and the OpenAI Agents SDK: see [`examples/`](examples/) and [Guard agent tools](https://docs.did.is/build/guard-tools/#use-with-mcp-and-agent-frameworks).
+
 - The definition check is local (RFC 8785 JCS + SHA-256, the same `definitionSha256` DID.is reports) and makes no network call.
 - The delegation check calls `verifyTool`. An ALLOW is reused for 30 s by default (`allowCacheMs`), never past the delegation expiry; DENY and errors are never cached.
 - Error codes: `TOOL_DRIFT`, `TOOL_DEFINITION_MISSING`, `TOOL_NOT_AUTHORIZED`, `GUARD_UNAVAILABLE`, `GUARD_MISCONFIGURED`.
-- One tool only: `withDidisGuard(handler, { client, agent, root, tool, pin, definition })`.
+- One tool only: `withDidisGuard(handler, { client, agent, root, tool, capability, pin, definition })`.
+- `onDecision` and `DidisGuardError.detail` include both `tool` and `capability`.
 - `attestMcpPins(client, endpoint, pins)` asks DID.is to inspect a public MCP server and compares its hashes with your pins. Run it at startup or deploy time, not per call: it is an outbound, rate-limited request, and servers that need login or run on a private network cannot be inspected.
 
 ## Webhooks

package/dist/guard.d.ts

@@ -6,8 +6,14 @@
  *     hashes to the SHA-256 you approved (same RFC 8785 JCS hash DID.is reports as
  *     `definitionSha256`). Catches MCP "rug-pull" drift, including servers DID.is cannot reach.
  *  2. Delegation (DID.is `verify-tool`): the configured agent DID holds a registered, VALID
- *     delegation whose leaf capabilities grant the tool. ALLOW is cached briefly; DENY and
- *     errors are never cached.
+ *     delegation whose leaf capabilities grant the tool's capability. ALLOW is cached briefly;
+ *     DENY and errors are never cached.
+ *
+ * Tool name vs capability: MCP tool names may only use `A-Z a-z 0-9 _ - .` (SEP-986), while
+ * DID.is capabilities are namespaced with `:` (e.g. `weather:forecast`). Pass both when they
+ * differ: `{ tool: "weather_forecast", capability: "weather:forecast" }`. Pins are keyed by the
+ * tool name (what `tools/list` returns); DID.is is asked about the capability. When
+ * `capability` is omitted, the tool name is used as the capability.
  *
  * Any failure (drift, DENY, network error, 429, malformed answer) throws `DidisGuardError`
  * and the handler is not called. `attestMcpPins` is an optional, separate startup check that
@@ -50,6 +56,7 @@ export interface DidisGuardOptions {
     /** Called after every decision (for audit logs). Must not throw. */
     onDecision?: (event: {
         tool: string;
+        capability: string;
         allowed: boolean;
         code?: DidisGuardErrorCode;
         reason: string;
@@ -57,8 +64,13 @@ export interface DidisGuardOptions {
     }) => void;
 }
 export interface GuardCallOptions {
-    /** The tool name as granted by capabilities, e.g. `github:create_issue`. */
+    /** The tool name the agent sees (MCP `tools/list` name, pin key), e.g. `github_create_issue`. */
     tool: string;
+    /**
+     * The DID.is capability this tool needs, e.g. `github:create_issue`. Defaults to `tool`.
+     * Must be an exact capability (no `*`): wildcards belong in delegations, not in tool calls.
+     */
+    capability?: string;
     /** The definition the agent received, or a function returning the current one. */
     definition?: Definition;
 }
@@ -72,7 +84,7 @@ export interface DidisGuard {
 }
 export declare function createDidisGuard(options: DidisGuardOptions): DidisGuard;
 /**
- * One-line form: `withDidisGuard(handler, { client, agent, root, tool, pin, definition })`.
+ * One-line form: `withDidisGuard(handler, { client, agent, root, tool, capability, pin, definition })`.
  * For several tools, create one guard with `createDidisGuard` so the ALLOW cache is shared.
  */
 export declare function withDidisGuard<A extends unknown[], R>(handler: (...args: A) => R | Promise<R>, options: Omit<DidisGuardOptions, "pins"> & GuardCallOptions & {

package/dist/guard.js

@@ -70,6 +70,8 @@ export async function pinToolDefinitions(tools) {
     return pins;
 }
 const DID = /^did:[a-z0-9]+:\S+$/;
+/** An exact DID.is capability: `:`-separated non-empty segments, no whitespace, no `*`. */
+const CAPABILITY = /^[^\s:*]+(?::[^\s:*]+)*$/;
 export function createDidisGuard(options) {
     const { client, agent, root, pins = {}, requirePins = false, onDecision } = options;
     const allowCacheMs = options.allowCacheMs ?? 30_000;
@@ -87,23 +89,23 @@ export function createDidisGuard(options) {
     }
     const pinFor = (tool) => (Object.prototype.hasOwnProperty.call(pins, tool) ? pins[tool] : undefined);
     const allowed = new Map();
-    const report = (tool, ok, reason, cached, code) => {
+    const report = (tool, capability, ok, reason, cached, code) => {
         try {
-            onDecision?.({ tool, allowed: ok, code, reason, cached });
+            onDecision?.({ tool, capability, allowed: ok, code, reason, cached });
         }
         catch {
             /* audit hooks must not change the decision */
         }
     };
-    const fail = (code, tool, reason, detail) => {
-        report(tool, false, reason, false, code);
-        throw new DidisGuardError(code, tool, reason, detail);
+    const fail = (code, tool, capability, reason, detail) => {
+        report(tool, capability, false, reason, false, code);
+        throw new DidisGuardError(code, tool, reason, { ...detail, capability });
     };
-    async function checkDefinition(tool, definition) {
+    async function checkDefinition(tool, capability, definition) {
         const pin = pinFor(tool);
         if (pin === undefined) {
             if (requirePins)
-                fail("TOOL_DEFINITION_MISSING", tool, `no pinned definition for '${tool}'`);
+                fail("TOOL_DEFINITION_MISSING", tool, capability, `no pinned definition for '${tool}'`);
             return;
         }
         let def;
@@ -111,60 +113,64 @@ export function createDidisGuard(options) {
             def = typeof definition === "function" ? await definition() : definition;
         }
         catch {
-            return fail("TOOL_DEFINITION_MISSING", tool, `could not read the current definition of '${tool}'`);
+            return fail("TOOL_DEFINITION_MISSING", tool, capability, `could not read the current definition of '${tool}'`);
         }
         if (def === undefined || def === null)
-            fail("TOOL_DEFINITION_MISSING", tool, `'${tool}' is pinned but no definition was supplied`);
+            fail("TOOL_DEFINITION_MISSING", tool, capability, `'${tool}' is pinned but no definition was supplied`);
         let actual;
         try {
             actual = await toolDefinitionSha256(def);
         }
         catch {
-            return fail("TOOL_DRIFT", tool, `the definition of '${tool}' is not valid JSON`);
+            return fail("TOOL_DRIFT", tool, capability, `the definition of '${tool}' is not valid JSON`);
         }
         if (def.name !== tool)
-            fail("TOOL_DRIFT", tool, `definition name does not match '${tool}'`, { expected: pin, actual });
+            fail("TOOL_DRIFT", tool, capability, `definition name does not match '${tool}'`, { expected: pin, actual });
         if (actual !== pin)
-            fail("TOOL_DRIFT", tool, `definition of '${tool}' changed since it was approved`, { expected: pin, actual });
+            fail("TOOL_DRIFT", tool, capability, `definition of '${tool}' changed since it was approved`, { expected: pin, actual });
     }
-    async function checkDelegation(tool) {
+    async function checkDelegation(tool, capability) {
         const now = Date.now();
-        const until = allowed.get(tool);
+        const until = allowed.get(capability);
         if (until !== undefined && until > now) {
-            report(tool, true, "cached ALLOW", true);
+            report(tool, capability, true, "cached ALLOW", true);
             return;
         }
-        allowed.delete(tool);
+        allowed.delete(capability);
         let auth;
         try {
-            auth = await client.verifyTool(agent, tool, root);
+            auth = await client.verifyTool(agent, capability, root);
         }
         catch (e) {
             const status = e.status;
-            return fail("GUARD_UNAVAILABLE", tool, `DID.is verify-tool failed${status ? ` (HTTP ${status})` : ""}`, { status });
+            return fail("GUARD_UNAVAILABLE", tool, capability, `DID.is verify-tool failed${status ? ` (HTTP ${status})` : ""}`, { status });
         }
-        const exact = auth && auth.decision === "ALLOW" && auth.authorized === true && auth.agent === agent && auth.tool === tool;
+        const exact = auth && auth.decision === "ALLOW" && auth.authorized === true && auth.agent === agent && auth.tool === capability;
         if (!exact) {
             if (auth && (auth.decision === "DENY" || auth.authorized === false)) {
-                fail("TOOL_NOT_AUTHORIZED", tool, auth.reason || "delegation does not grant this tool", { matchedCapability: auth.matchedCapability });
+                fail("TOOL_NOT_AUTHORIZED", tool, capability, auth.reason || "delegation does not grant this capability", { matchedCapability: auth.matchedCapability });
             }
-            fail("GUARD_UNAVAILABLE", tool, "DID.is returned an unexpected authorization answer");
+            fail("GUARD_UNAVAILABLE", tool, capability, "DID.is returned an unexpected authorization answer");
         }
         if (root !== undefined && auth.root !== root)
-            fail("TOOL_NOT_AUTHORIZED", tool, "delegation root does not match the configured root");
+            fail("TOOL_NOT_AUTHORIZED", tool, capability, "delegation root does not match the configured root");
         if (allowCacheMs > 0) {
             const expires = auth.expires ? Date.parse(auth.expires) : NaN;
             const until2 = Math.min(now + allowCacheMs, Number.isFinite(expires) ? expires : now + allowCacheMs);
             if (until2 > now)
-                allowed.set(tool, until2);
+                allowed.set(capability, until2);
         }
-        report(tool, true, auth.reason, false);
+        report(tool, capability, true, auth.reason, false);
     }
-    async function check({ tool, definition }) {
+    async function check({ tool, capability, definition }) {
         if (typeof tool !== "string" || !tool.trim() || tool !== tool.trim())
-            fail("GUARD_MISCONFIGURED", String(tool), "tool must be a non-empty, trimmed name");
-        await checkDefinition(tool, definition);
-        await checkDelegation(tool);
+            fail("GUARD_MISCONFIGURED", String(tool), String(capability ?? tool), "tool must be a non-empty, trimmed name");
+        const cap = capability === undefined ? tool : capability;
+        if (typeof cap !== "string" || !CAPABILITY.test(cap)) {
+            fail("GUARD_MISCONFIGURED", tool, String(cap), "capability must be exact: ':'-separated non-empty segments, no spaces, no '*'");
+        }
+        await checkDefinition(tool, cap, definition);
+        await checkDelegation(tool, cap);
     }
     return {
         check,
@@ -182,13 +188,13 @@ export function createDidisGuard(options) {
     };
 }
 /**
- * One-line form: `withDidisGuard(handler, { client, agent, root, tool, pin, definition })`.
+ * One-line form: `withDidisGuard(handler, { client, agent, root, tool, capability, pin, definition })`.
  * For several tools, create one guard with `createDidisGuard` so the ALLOW cache is shared.
  */
 export function withDidisGuard(handler, options) {
-    const { tool, definition, pin, ...rest } = options;
+    const { tool, capability, definition, pin, ...rest } = options;
     const guard = createDidisGuard({ ...rest, pins: pin ? { [tool]: pin } : undefined });
-    return guard.wrap({ tool, definition }, handler);
+    return guard.wrap({ tool, capability, definition }, handler);
 }
 /**
  * Optional startup check: asks DID.is to inspect a public MCP endpoint and compares the observed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@didis/client",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Official TypeScript/JavaScript SDK for the DID.is public API: DID resolution with evidence, credentials, policies and agent trust",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "sideEffects": false,
   "engines": {