@didis/client 0.1.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

@@ -33,6 +33,13 @@ for await (const ev of didis.stream("did:web:identity.foundation")) {
 
 // Credentials: VC DM 2.0 / 1.1 with Data Integrity (eddsa-jcs-2022, ecdsa-jcs-2019) or VC-JOSE/VC-JWT.
 // RDFC suites, ecdsa-sd-2023 and bbs-2023 are reported as UNSUPPORTED, never as valid.
+const credential = {
+  "@context": ["https://www.w3.org/ns/credentials/v2"],
+  type: ["VerifiableCredential"],
+  issuer: "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
+  validFrom: "2026-01-01T00:00:00Z",
+  credentialSubject: { id: "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLdmQR63zLFKfvUwi3" },
+};
 const vc = await didis.verifyCredential(credential);
 console.log(vc.status, vc.headline);
 
@@ -44,6 +51,7 @@ const { evaluation } = await didis.evaluatePolicy("did:web:example.com", {
 // Agents.
 const mcp = await didis.inspectMcp("https://mcp.example.com/mcp");
 const card = await didis.inspectA2a("https://agent.example.com");
+const chain: string[] = []; // delegation receipt JWS strings, root first
 const { authorization } = await didis.authorize(chain, "payments.refund", { trustedRoots: ["did:web:example.com"] });
 
 try {
@@ -55,9 +63,62 @@ try {
 
 Identifiers are percent-encoded exactly once by the client. Non-2xx responses throw `DidisError` with the RFC 9457 problem body (including the resolution `trace` where available).
 
+## Guard agent tools
+
+Wrap a tool handler so it runs only when (1) the tool definition the agent received still matches the one you approved and (2) DID.is says the agent's registered delegation grants the tool. Every failure throws `DidisGuardError` and the handler does not run (fail-closed).
+
+```ts
+import { DidisClient, createDidisGuard, pinToolDefinitions } from "@didis/client";
+
+const didis = new DidisClient();
+// Once, after reviewing the server's tools/list: store these pins in your config.
+const pins = await pinToolDefinitions(reviewedTools);
+
+const guard = createDidisGuard({
+  client: didis,
+  agent: process.env.AGENT_DID!, // from configuration, never from model output
+  root: process.env.ROOT_DID,    // require this delegation root
+  pins,
+  requirePins: true,
+});
+
+const createIssue = guard.wrap(
+  {
+    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, 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
 
-Monitoring routes require an admin token (`new DidisClient({ adminToken })`) and must only be used server-side. Deliveries are signed:
+Console project monitor events use `verifyCustomerMonitorSignature`:
+
+```ts
+import { verifyCustomerMonitorSignature } from "@didis/client";
+
+const ok = await verifyCustomerMonitorSignature(
+  secret,
+  rawBody,
+  req.headers["x-didis-signature"],
+  { tenantId, projectId, eventId: req.headers["x-didis-event-id"] },
+);
+```
+
+For self-hosted admin daemon monitoring deliveries, use `verifyWebhookSignature`:
 
 ```ts
 import { verifyWebhookSignature } from "@didis/client";

package/dist/guard.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Fail-closed pre-execution guard for agent tools.
+ *
+ * Before a wrapped tool handler runs, the guard checks:
+ *  1. Definition pin (local, no network): the tool definition the agent actually received
+ *     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'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
+ * asks DID.is to fetch a public MCP server and compares its hashes with your pins; do not call
+ * it per tool call (it makes an outbound request and is rate limited).
+ */
+import type { DidisClient, McpInspection } from "./index.js";
+export type DidisGuardErrorCode = "TOOL_DRIFT" | "TOOL_DEFINITION_MISSING" | "TOOL_NOT_AUTHORIZED" | "GUARD_UNAVAILABLE" | "GUARD_MISCONFIGURED";
+export declare class DidisGuardError extends Error {
+    readonly code: DidisGuardErrorCode;
+    readonly tool: string;
+    readonly detail?: Record<string, unknown>;
+    constructor(code: DidisGuardErrorCode, tool: string, message: string, detail?: Record<string, unknown>);
+}
+/** RFC 8785 (JCS) canonical JSON, matching the DID.is server's `rfc8785-binary64-v1` profile. */
+export declare function canonicalJson(value: unknown): string;
+/** SHA-256 of a tool definition exactly as an MCP server returned it in `tools/list`. */
+export declare function toolDefinitionSha256(definition: unknown): Promise<string>;
+/** Inventory hash of a `tools/list` result, identical to DID.is `inventoryHash`. */
+export declare function mcpInventoryHash(tools: {
+    name?: unknown;
+}[]): Promise<string>;
+/** Builds `{ toolName: definitionSha256 }` pins from a `tools/list` result you have reviewed. */
+export declare function pinToolDefinitions(tools: {
+    name?: unknown;
+}[]): Promise<Record<string, string>>;
+type Definition = unknown | (() => unknown | Promise<unknown>);
+export interface DidisGuardOptions {
+    client: DidisClient;
+    /** The agent DID from your runtime configuration. Never take it from model output. */
+    agent: string;
+    /** Require the delegation chain to start at this root DID. Strongly recommended. */
+    root?: string;
+    /** Approved `{ toolName: definitionSha256 }`. A pinned tool must be given its definition. */
+    pins?: Record<string, string>;
+    /** Refuse tools that have no pin. Default `false`. */
+    requirePins?: boolean;
+    /** How long an ALLOW is reused (ms). Default 30 s; 0 disables. Capped by the delegation expiry. */
+    allowCacheMs?: number;
+    /** Called after every decision (for audit logs). Must not throw. */
+    onDecision?: (event: {
+        tool: string;
+        capability: string;
+        allowed: boolean;
+        code?: DidisGuardErrorCode;
+        reason: string;
+        cached: boolean;
+    }) => void;
+}
+export interface GuardCallOptions {
+    /** 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;
+}
+export interface DidisGuard {
+    /** Throws `DidisGuardError` unless the call may proceed. */
+    check(call: GuardCallOptions): Promise<void>;
+    /** Wraps a handler so it only runs after `check` passes. */
+    wrap<A extends unknown[], R>(call: GuardCallOptions, handler: (...args: A) => R | Promise<R>): (...args: A) => Promise<Awaited<R>>;
+    /** Drops cached ALLOW decisions (e.g. after revoking a delegation). */
+    clearCache(): void;
+}
+export declare function createDidisGuard(options: DidisGuardOptions): DidisGuard;
+/**
+ * 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 & {
+    pin?: string;
+}): (...args: A) => Promise<Awaited<R>>;
+export interface McpAttestation {
+    ok: boolean;
+    inventoryHash: string;
+    /** Pinned tools whose DID.is-observed hash differs, or that DID.is did not see. */
+    mismatched: {
+        tool: string;
+        expected: string;
+        observed?: string;
+    }[];
+    /** Tools DID.is saw that you have not pinned. */
+    unpinned: string[];
+    status: McpInspection["status"];
+}
+/**
+ * Optional startup check: asks DID.is to inspect a public MCP endpoint and compares the observed
+ * `definitionSha256` values with your pins. Use at deploy/startup, never per tool call.
+ * `AUTH_REQUIRED` or any non-INSPECTED status returns `ok: false`.
+ */
+export declare function attestMcpPins(client: DidisClient, endpoint: string, pins: Record<string, string>): Promise<McpAttestation>;
+export {};

package/dist/guard.js

@@ -0,0 +1,218 @@
+import { subtle } from "./webcrypto.js";
+export class DidisGuardError extends Error {
+    code;
+    tool;
+    detail;
+    constructor(code, tool, message, detail) {
+        super(`${code}: ${message}`);
+        this.name = "DidisGuardError";
+        this.code = code;
+        this.tool = tool;
+        this.detail = detail;
+    }
+}
+/** RFC 8785 (JCS) canonical JSON, matching the DID.is server's `rfc8785-binary64-v1` profile. */
+export function canonicalJson(value) {
+    if (value === null)
+        return "null";
+    switch (typeof value) {
+        case "boolean":
+            return value ? "true" : "false";
+        case "number":
+            if (!Number.isFinite(value))
+                throw new TypeError("JCS: non-finite numbers are not JSON");
+            return Object.is(value, -0) ? "0" : String(value);
+        case "string":
+            return JSON.stringify(value);
+        case "object": {
+            if (Array.isArray(value))
+                return `[${value.map((v) => canonicalJson(v === undefined ? null : v)).join(",")}]`;
+            const obj = value;
+            const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort(); // UTF-16 code unit order
+            return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+        }
+        default:
+            throw new TypeError(`JCS: unsupported value of type ${typeof value}`);
+    }
+}
+async function sha256Hex(text) {
+    const digest = new Uint8Array(await (await subtle()).digest("SHA-256", new TextEncoder().encode(text)));
+    return Array.from(digest, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** SHA-256 of a tool definition exactly as an MCP server returned it in `tools/list`. */
+export function toolDefinitionSha256(definition) {
+    return sha256Hex(canonicalJson(definition));
+}
+function byteCompare(a, b) {
+    const x = new TextEncoder().encode(a);
+    const y = new TextEncoder().encode(b);
+    for (let i = 0; i < Math.min(x.length, y.length); i++)
+        if (x[i] !== y[i])
+            return x[i] - y[i];
+    return x.length - y.length;
+}
+/** Inventory hash of a `tools/list` result, identical to DID.is `inventoryHash`. */
+export async function mcpInventoryHash(tools) {
+    const pairs = await Promise.all(tools.map(async (t) => [typeof t.name === "string" ? t.name : "", await toolDefinitionSha256(t)]));
+    pairs.sort((a, b) => byteCompare(a[0], b[0]));
+    return sha256Hex(canonicalJson(pairs));
+}
+/** Builds `{ toolName: definitionSha256 }` pins from a `tools/list` result you have reviewed. */
+export async function pinToolDefinitions(tools) {
+    const pins = {};
+    for (const t of tools) {
+        if (typeof t.name !== "string" || !t.name)
+            throw new TypeError("every tool needs a string name");
+        if (t.name in pins)
+            throw new TypeError(`duplicate tool name '${t.name}'`);
+        pins[t.name] = await toolDefinitionSha256(t);
+    }
+    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;
+    if (!client || typeof client.verifyTool !== "function")
+        throw new DidisGuardError("GUARD_MISCONFIGURED", "", "a DidisClient is required");
+    if (typeof agent !== "string" || !DID.test(agent))
+        throw new DidisGuardError("GUARD_MISCONFIGURED", "", "agent must be a DID");
+    if (root !== undefined && (typeof root !== "string" || !DID.test(root)))
+        throw new DidisGuardError("GUARD_MISCONFIGURED", "", "root must be a DID");
+    if (!Number.isFinite(allowCacheMs) || allowCacheMs < 0)
+        throw new DidisGuardError("GUARD_MISCONFIGURED", "", "allowCacheMs must be >= 0");
+    for (const [name, pin] of Object.entries(pins)) {
+        if (!/^[0-9a-f]{64}$/.test(pin))
+            throw new DidisGuardError("GUARD_MISCONFIGURED", name, "pins must be lowercase hex SHA-256");
+    }
+    const pinFor = (tool) => (Object.prototype.hasOwnProperty.call(pins, tool) ? pins[tool] : undefined);
+    const allowed = new Map();
+    const report = (tool, capability, ok, reason, cached, code) => {
+        try {
+            onDecision?.({ tool, capability, allowed: ok, code, reason, cached });
+        }
+        catch {
+            /* audit hooks must not change the decision */
+        }
+    };
+    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, capability, definition) {
+        const pin = pinFor(tool);
+        if (pin === undefined) {
+            if (requirePins)
+                fail("TOOL_DEFINITION_MISSING", tool, capability, `no pinned definition for '${tool}'`);
+            return;
+        }
+        let def;
+        try {
+            def = typeof definition === "function" ? await definition() : definition;
+        }
+        catch {
+            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, capability, `'${tool}' is pinned but no definition was supplied`);
+        let actual;
+        try {
+            actual = await toolDefinitionSha256(def);
+        }
+        catch {
+            return fail("TOOL_DRIFT", tool, capability, `the definition of '${tool}' is not valid JSON`);
+        }
+        if (def.name !== tool)
+            fail("TOOL_DRIFT", tool, capability, `definition name does not match '${tool}'`, { expected: pin, actual });
+        if (actual !== pin)
+            fail("TOOL_DRIFT", tool, capability, `definition of '${tool}' changed since it was approved`, { expected: pin, actual });
+    }
+    async function checkDelegation(tool, capability) {
+        const now = Date.now();
+        const until = allowed.get(capability);
+        if (until !== undefined && until > now) {
+            report(tool, capability, true, "cached ALLOW", true);
+            return;
+        }
+        allowed.delete(capability);
+        let auth;
+        try {
+            auth = await client.verifyTool(agent, capability, root);
+        }
+        catch (e) {
+            const status = e.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 === capability;
+        if (!exact) {
+            if (auth && (auth.decision === "DENY" || auth.authorized === false)) {
+                fail("TOOL_NOT_AUTHORIZED", tool, capability, auth.reason || "delegation does not grant this capability", { matchedCapability: auth.matchedCapability });
+            }
+            fail("GUARD_UNAVAILABLE", tool, capability, "DID.is returned an unexpected authorization answer");
+        }
+        if (root !== undefined && auth.root !== 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(capability, until2);
+        }
+        report(tool, capability, true, auth.reason, false);
+    }
+    async function check({ tool, capability, definition }) {
+        if (typeof tool !== "string" || !tool.trim() || tool !== tool.trim())
+            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,
+        wrap(call, handler) {
+            if (typeof handler !== "function")
+                throw new DidisGuardError("GUARD_MISCONFIGURED", call?.tool ?? "", "handler must be a function");
+            return async (...args) => {
+                await check(call);
+                return await handler(...args);
+            };
+        },
+        clearCache() {
+            allowed.clear();
+        },
+    };
+}
+/**
+ * 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, capability, definition, pin, ...rest } = options;
+    const guard = createDidisGuard({ ...rest, pins: pin ? { [tool]: pin } : undefined });
+    return guard.wrap({ tool, capability, definition }, handler);
+}
+/**
+ * Optional startup check: asks DID.is to inspect a public MCP endpoint and compares the observed
+ * `definitionSha256` values with your pins. Use at deploy/startup, never per tool call.
+ * `AUTH_REQUIRED` or any non-INSPECTED status returns `ok: false`.
+ */
+export async function attestMcpPins(client, endpoint, pins) {
+    const inspection = await client.inspectMcp(endpoint);
+    const seen = new Map(inspection.tools.map((t) => [t.name, t.definitionSha256]));
+    const mismatched = Object.entries(pins)
+        .filter(([tool, expected]) => seen.get(tool) !== expected)
+        .map(([tool, expected]) => ({ tool, expected, observed: seen.get(tool) }));
+    const unpinned = [...seen.keys()].filter((t) => !Object.prototype.hasOwnProperty.call(pins, t));
+    return {
+        ok: inspection.status === "INSPECTED" && mismatched.length === 0,
+        inventoryHash: inspection.inventoryHash,
+        mismatched,
+        unpinned,
+        status: inspection.status,
+    };
+}

package/dist/index.d.ts

@@ -226,6 +226,35 @@ export interface Check {
     status: "PASS" | "FAIL" | "WARN" | "SKIP" | "UNSUPPORTED" | "INDETERMINATE" | string;
     detail: string;
 }
+export interface IssuerTrust {
+    anchor: "DID" | "X509_CERTIFICATE" | "ISSUER_METADATA" | "NONE";
+    result: "NOT_APPLICABLE" | "NOT_ESTABLISHED" | "CALLER_ANCHORED" | "CHAIN_INVALID";
+    trustedListChecked: false;
+    chain?: {
+        sha256: string;
+        subjectCn?: string;
+        issuerCn?: string;
+        notAfter?: string;
+    }[];
+    metadataUrl?: string;
+    proves: string;
+    doesNotProve: string;
+}
+export interface SdJwtEvidence {
+    sdAlg: string;
+    disclosures: number;
+    decoyDigests: number;
+    registeredClaims: Record<string, unknown>;
+    keyBinding: "VERIFIED" | "ABSENT" | "INVALID" | "UNSUPPORTED" | "INDETERMINATE";
+}
+export interface CredentialVerifyOptions {
+    /** JWT `aud` / SD-JWT Key Binding `aud` constraint. */
+    expectedAudience?: string;
+    /** SD-JWT Key Binding `nonce` constraint; without it replay is not excluded. */
+    expectedNonce?: string;
+    /** Caller-chosen X.509 anchors (PEM or base64 DER) for SD-JWT VC `x5c`. Without them `x5c` is never VALID. */
+    trustedIssuerCertificates?: string[];
+}
 export interface CredentialVerification {
     status: string;
     headline: string;
@@ -271,6 +300,11 @@ export interface CredentialVerification {
         domainBinding?: string;
         detail: string;
     };
+    /** SD-JWT VC only. Categorical, never a score; EU trusted lists are never checked. */
+    issuerTrust?: IssuerTrust;
+    /** SD-JWT VC only. No disclosed claim values are ever returned. */
+    sdJwt?: SdJwtEvidence;
+    /** For SD-JWT VC: disclosed claim paths and digests only, never values. */
     claims: unknown;
     credential: unknown;
     limitations: string[];
@@ -629,9 +663,7 @@ export declare class DidisClient {
     diff(did: string, from?: string, to?: string): Promise<SemanticDiff>;
     graph(did: string): Promise<GraphResponse>;
     /** Audience is checked only when an expected recipient is supplied. Pass raw JSON as a string to preserve member identity. */
-    verifyCredential(credential: unknown, options?: {
-        expectedAudience?: string;
-    }): Promise<CredentialVerification>;
+    verifyCredential(credential: unknown, options?: CredentialVerifyOptions): Promise<CredentialVerification>;
     evaluatePolicy(did: string, policy: {
         name?: string;
         rules: PolicyRules;
@@ -674,3 +706,4 @@ export declare function verifyCustomerMonitorSignature(secret: string, body: str
     projectId: string;
     eventId: string;
 }, maxAgeSeconds?: number): Promise<boolean>;
+export * from "./guard.js";

package/dist/index.js

@@ -1,9 +1,4 @@
-/**
- * DID.is client SDK (TypeScript — Node 18+, Deno, Bun, browsers, edge runtimes).
- *
- * Every identifier is percent-encoded exactly once; the resolver decodes it exactly once.
- * Errors are thrown as `DidisError`, carrying the RFC 9457 problem object returned by the API.
- */
+import { subtle } from "./webcrypto.js";
 // ---------------------------------------------------------------------------------------------
 // Client
 // ---------------------------------------------------------------------------------------------
@@ -137,7 +132,12 @@ export class DidisClient {
     }
     /** Audience is checked only when an expected recipient is supplied. Pass raw JSON as a string to preserve member identity. */
     verifyCredential(credential, options = {}) {
-        return this.request("POST", "/v1/credentials/verify", { credential, expectedAudience: options.expectedAudience });
+        return this.request("POST", "/v1/credentials/verify", {
+            credential,
+            expectedAudience: options.expectedAudience,
+            expectedNonce: options.expectedNonce,
+            trustedIssuerCertificates: options.trustedIssuerCertificates,
+        });
     }
     evaluatePolicy(did, policy, credential) {
         return this.request("POST", "/v1/policies/evaluate", { did, policy, credential });
@@ -187,8 +187,8 @@ export async function verifyWebhookSignature(secret, timestamp, body, signatureH
     if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > toleranceSeconds)
         return false;
     const te = new TextEncoder();
-    const key = await crypto.subtle.importKey("raw", te.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, te.encode(`${timestamp}.${body}`)));
+    const key = await (await subtle()).importKey("raw", te.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await (await subtle()).sign("HMAC", key, te.encode(`${timestamp}.${body}`)));
     const expected = `sha256=${Array.from(mac, (b) => b.toString(16).padStart(2, "0")).join("")}`;
     if (expected.length !== signatureHeader.length)
         return false;
@@ -209,9 +209,9 @@ export async function verifyCustomerMonitorSignature(secret, body, signature, ex
     if (!match || !Number.isSafeInteger(timestamp) || !Number.isInteger(maxAgeSeconds) || maxAgeSeconds < 1 || maxAgeSeconds > 30 * 86400 || timestamp > now + 60 || now - timestamp >= maxAgeSeconds || bytes.length > 300 * 1024 || !secret)
         return false;
     try {
-        const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+        const key = await (await subtle()).importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
         const mac = Uint8Array.from(match[2].match(/../g), value => parseInt(value, 16));
-        if (!await crypto.subtle.verify("HMAC", key, mac, new TextEncoder().encode(`${match[1]}.${body}`)))
+        if (!await (await subtle()).verify("HMAC", key, mac, new TextEncoder().encode(`${match[1]}.${body}`)))
             return false;
         const event = JSON.parse(body);
         return event.specVersion === "didis.customer-monitor.v1" && event.createdAt === timestamp
@@ -223,3 +223,4 @@ export async function verifyCustomerMonitorSignature(secret, body, signature, ex
         return false;
     }
 }
+export * from "./guard.js";

package/dist/webcrypto.d.ts

@@ -0,0 +1 @@
+export declare function subtle(): Promise<SubtleCrypto>;

package/dist/webcrypto.js

@@ -0,0 +1,16 @@
+/** WebCrypto: global in Node 19+, browsers, Deno, Bun and edge; Node 18 needs `node:crypto`. */
+let cached;
+export function subtle() {
+    if (!cached) {
+        const g = globalThis.crypto;
+        cached = g?.subtle
+            ? Promise.resolve(g.subtle)
+            : import("node:crypto").then((m) => {
+                if (!m.webcrypto?.subtle)
+                    throw new Error("WebCrypto is not available in this runtime");
+                return m.webcrypto.subtle;
+            });
+        cached.catch(() => { cached = undefined; });
+    }
+    return cached;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@didis/client",
-  "version": "0.1.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": {