@trusty-squire/mcp 1.1.13-rc.9 → 1.1.13

package/dist/tools/audit-log.js

@@ -1,26 +1,59 @@
 import { z } from "zod";
 import { assertApi } from "./index.js";
 import { ALWAYS_LOAD_META } from "./always-load.js";
+import { anomalyReason, buildEgressRollups, buildGrantTotals, decodeRollupId, describeStatuses, formatBytes, grantLabels, isEgressCall, normalizeAuditType, } from "./audit-rollup.js";
 // The who-touched-my-keys ledger. Every vault action — stored / retrieved /
 // rotated / deleted / proxy_executed / proxy_rejected — newest first, keyset-
 // paginated by the `before` cursor. Payloads carry NO secret values; this is
 // strictly less than what list_credentials already exposes, so the account's
 // own agent can read it (same account boundary as the human's web UI).
+//
+// Read-side shaping (see audit-rollup.ts): the default `ledger` view keeps the
+// security-relevant lifecycle events as rows, collapses routine egress traffic
+// into per (credential x host x burst) rollups, and pulls anomalies back out of
+// those rollups so a 429 or a rejected call is never hidden. `view: "raw"` is
+// the unaggregated escape hatch and returns exactly the server's page.
 const inputSchema = z.object({
     limit: z.number().int().min(1).max(200).optional(),
     before: z.string().min(1).optional(),
     type: z.string().min(1).optional(),
     reference: z.string().min(1).optional(),
+    // "ledger" (default) groups; "raw" is the flat per-request stream.
+    view: z.enum(["ledger", "raw"]).optional(),
+    // How many raw events the ledger view reads before shaping them. The point
+    // of the rollup is to see past a page of near-identical egress calls, so the
+    // scan is deliberately deeper than `limit`.
+    scan: z.number().int().min(1).max(2000).optional(),
+    // Gap that splits one egress burst from the next, in minutes.
+    window_minutes: z.number().int().min(1).max(1440).optional(),
+    // A rollup `id` from a ledger response — returns that rollup's individual calls.
+    expand: z.string().min(1).optional(),
 });
+const DEFAULT_LIMIT = 50;
+const DEFAULT_SCAN = 500;
+const DEFAULT_WINDOW_MINUTES = 60;
+const API_PAGE_MAX = 200;
 const DESCRIPTION = `Read the vault audit ledger — "show me everything that touched my keys."
-Returns account-scoped events newest-first: stored / retrieved / rotated /
-deleted / proxy_executed / proxy_rejected, each with a timestamp, the credential
-reference, requester, and outcome. NO secret values are ever included.
+Account-scoped, newest-first, NO secret values ever.
 
-Filter with \`type\` (an event kind) or \`reference\` (a single credential), cap with
-\`limit\` (default 50, max 200), and page older with \`before\` (pass the prior
-response's \`next_before\` cursor; null means no more pages). Use this to answer
-"what used my Stripe key in the last N days" or to investigate a suspected leak.`;
+By default (\`view:"ledger"\`) the response is SHAPED so it is readable:
+- \`events\` — the security ledger: credential stored / rotated / deleted /
+  edited, grants minted / revoked, payments, plus every ANOMALY
+  (\`anomaly:true\` with an \`anomaly_reason\` — non-2xx, 429, proxy error,
+  rejected call). Routine successful egress is NOT listed here.
+- \`egress.rollups\` — routine proxied calls collapsed per credential x target
+  host x burst: count, status breakdown, total bytes, first/last timestamp,
+  and the grants covering that window. Pass a rollup's \`id\` back as
+  \`expand\` to see its individual calls.
+- \`grant_totals\` — per egress grant: cumulative calls, bytes, last used.
+- \`summary\` — one human-readable line per rollup / headline.
+
+Escape hatches and filters: \`view:"raw"\` returns the flat unaggregated page
+(the original shape). \`type\` (an event kind), \`reference\` (a single
+credential), \`limit\` (rows, default ${DEFAULT_LIMIT}, max 200), \`before\`
+(keyset cursor from \`next_before\`), \`scan\` (raw events read before shaping,
+default ${DEFAULT_SCAN}, max 2000) and \`window_minutes\` (burst gap, default
+${DEFAULT_WINDOW_MINUTES}) all still apply.`;
 export const auditLogTool = {
     name: "audit_log",
     description: DESCRIPTION,
@@ -32,18 +65,195 @@ export const auditLogTool = {
             before: { type: "string" },
             type: { type: "string" },
             reference: { type: "string" },
+            view: { type: "string", enum: ["ledger", "raw"] },
+            scan: { type: "number" },
+            window_minutes: { type: "number" },
+            expand: { type: "string" },
         },
     },
     annotations: { readOnlyHint: true },
     meta: ALWAYS_LOAD_META,
     async handler(args, api) {
         assertApi(api);
-        return api.listAudit({
-            ...(args.limit !== undefined ? { limit: args.limit } : {}),
-            ...(args.before !== undefined ? { before: args.before } : {}),
-            ...(args.type !== undefined ? { type: args.type } : {}),
-            ...(args.reference !== undefined ? { reference: args.reference } : {}),
-        });
+        if (args.expand !== undefined)
+            return expandRollup(api, args, args.expand);
+        if (args.view === "raw") {
+            const page = await api.listAudit(passthroughFilters(args));
+            return { view: "raw", ...page };
+        }
+        return buildLedgerView(api, args);
     },
 };
+function passthroughFilters(args) {
+    return {
+        ...(args.limit !== undefined ? { limit: args.limit } : {}),
+        ...(args.before !== undefined ? { before: args.before } : {}),
+        ...(args.type !== undefined ? { type: args.type } : {}),
+        ...(args.reference !== undefined ? { reference: args.reference } : {}),
+    };
+}
+// Page the server's keyset cursor until `scan` events are read or the trail
+// ends. Returns the cursor to continue from, so a caller can keep walking back.
+async function scanEvents(api, filters, scan, 
+// Stop paging once the trail is older than this (epoch ms). The drill-down
+// knows its window's lower bound, so it should not walk a credential's whole
+// history to rebuild one burst.
+until) {
+    const events = [];
+    let cursor = filters.before ?? null;
+    for (;;) {
+        const page = await api.listAudit({
+            limit: Math.min(API_PAGE_MAX, scan - events.length),
+            ...(cursor !== null ? { before: cursor } : {}),
+            ...(filters.type !== undefined ? { type: filters.type } : {}),
+            ...(filters.reference !== undefined ? { reference: filters.reference } : {}),
+        });
+        events.push(...page.events);
+        cursor = page.next_before;
+        if (cursor === null || page.events.length === 0 || events.length >= scan)
+            break;
+        if (until !== undefined && Date.parse(cursor) < until)
+            break;
+    }
+    return { events, next_before: cursor };
+}
+// Egress grants give the rollups their "which standing access spent this key"
+// context. Best-effort: an account with no egress at all should not pay for the
+// extra call, and a failure here must not sink the whole ledger read.
+async function loadGrants(api, needed) {
+    if (!needed)
+        return [];
+    try {
+        const { grants } = await api.listEgressGrants();
+        return grants.map((g) => ({
+            grant_id: g.grant_id,
+            credential_ref: g.credential_ref,
+            created_at: g.created_at,
+            revoked_at: g.revoked_at,
+            rate_limit_per_hour: g.rate_limit_per_hour,
+            spend_cap_usd: g.spend_cap_usd,
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+async function buildLedgerView(api, args) {
+    const limit = args.limit ?? DEFAULT_LIMIT;
+    const scan = Math.max(args.scan ?? DEFAULT_SCAN, limit);
+    const windowMinutes = args.window_minutes ?? DEFAULT_WINDOW_MINUTES;
+    const { events, next_before } = await scanEvents(api, {
+        ...(args.before !== undefined ? { before: args.before } : {}),
+        ...(args.type !== undefined ? { type: args.type } : {}),
+        ...(args.reference !== undefined ? { reference: args.reference } : {}),
+    }, scan);
+    const egressCalls = events.filter(isEgressCall);
+    const grants = await loadGrants(api, egressCalls.length > 0);
+    // Ledger rows: everything that is not routine egress. An egress call that
+    // failed, was rate-limited, or errored is pulled back out of the aggregate
+    // and marked, so the actionable rows are visible without expanding anything.
+    const ledgerRows = [];
+    let anomalyCount = 0;
+    for (const event of events) {
+        const reason = anomalyReason(event);
+        if (reason !== null)
+            anomalyCount += 1;
+        if (isEgressCall(event) && reason === null)
+            continue;
+        ledgerRows.push(reason === null ? event : { ...event, anomaly: true, anomaly_reason: reason });
+    }
+    const labels = grantLabels(events);
+    const rollups = buildEgressRollups(events, {
+        windowMinutes,
+        ...(grants !== null ? { grants } : {}),
+        labels,
+    });
+    const grantTotals = grants === null ? [] : buildGrantTotals(events, grants);
+    const oldest = events[events.length - 1];
+    const newest = events[0];
+    return {
+        view: "ledger",
+        window: {
+            from: oldest?.emitted_at ?? null,
+            to: newest?.emitted_at ?? null,
+        },
+        scanned: events.length,
+        // More history exists past the scan — page it with `before: next_before`.
+        truncated: next_before !== null,
+        next_before,
+        events: ledgerRows.slice(0, limit),
+        events_total: ledgerRows.length,
+        events_truncated: ledgerRows.length > limit,
+        anomaly_count: anomalyCount,
+        egress: {
+            calls: egressCalls.length,
+            rolled_up_into: rollups.length,
+            window_minutes: windowMinutes,
+            rollups,
+            ...(rollups.length > 0
+                ? {
+                    hint: 'Pass a rollup\'s `id` as `expand` to list its individual calls, or view:"raw" for the flat stream.',
+                }
+                : {}),
+        },
+        grant_totals: grantTotals,
+        // Honest about what read-side attribution can and cannot know: the write
+        // side records no grant id on a proxied call, so these totals count egress
+        // on the grant's credential during its lifetime and include any direct
+        // use_credential traffic on that same credential.
+        attribution: grants === null
+            ? "grants_unavailable"
+            : "by_credential_reference_within_grant_lifetime (may include direct use_credential calls; per-event grant attribution is a planned follow-up)",
+        summary: summarize(ledgerRows.length, anomalyCount, rollups, egressCalls.length),
+    };
+}
+function summarize(ledgerRows, anomalies, rollups, egressCalls) {
+    const lines = [
+        `${ledgerRows} ledger event(s), ${anomalies} anomaly(ies), ${egressCalls} egress call(s) in ${rollups.length} rollup(s)`,
+    ];
+    for (const r of rollups.slice(0, 20)) {
+        const marker = r.anomaly_count > 0 ? ` [${r.anomaly_count} anomaly]` : "";
+        lines.push(`${r.target_host} via ${r.reference}: ${r.count} call(s) (${describeStatuses(r.status_breakdown)}), ${formatBytes(r.total_bytes)}, ${r.from} → ${r.to}${marker}`);
+    }
+    return lines;
+}
+// Drill-down: the individual calls behind one rollup id. Stateless — the id
+// carries (reference, host, window), so no server-side rollup state is needed.
+async function expandRollup(api, args, expand) {
+    const key = decodeRollupId(expand);
+    if (key === null) {
+        throw new Error("audit_log expand expects a rollup `id` from a ledger response (rollup_…). Call audit_log with no expand first.");
+    }
+    const limit = args.limit ?? DEFAULT_LIMIT;
+    const scan = Math.max(args.scan ?? DEFAULT_SCAN, limit);
+    const from = Date.parse(key.from);
+    const to = Date.parse(key.to);
+    // `before` is exclusive on the server; nudge past the newest member so the
+    // rollup's own upper bound is included.
+    const cursor = Number.isNaN(to) ? undefined : new Date(to + 1).toISOString();
+    const { events } = await scanEvents(api, { reference: key.reference, ...(cursor !== undefined ? { before: cursor } : {}) }, scan, Number.isNaN(from) ? undefined : from);
+    const calls = events.filter((event) => {
+        if (!isEgressCall(event))
+            return false;
+        if (event.target_host !== key.target_host)
+            return false;
+        const at = Date.parse(event.emitted_at);
+        return !Number.isNaN(at) && at >= from && at <= to;
+    });
+    return {
+        view: "expand",
+        rollup: { id: expand, ...key },
+        calls: calls.slice(0, limit).map((event) => {
+            const reason = anomalyReason(event);
+            return reason === null ? event : { ...event, anomaly: true, anomaly_reason: reason };
+        }),
+        calls_total: calls.length,
+        calls_truncated: calls.length > limit,
+        // Raise `limit` (max 200) or narrow `window_minutes` on the ledger call to
+        // see the rest of a very large burst.
+        scanned: events.length,
+    };
+}
+// Re-exported for the web/CLI surfaces and tests that shape the same trail.
+export { normalizeAuditType };
 //# sourceMappingURL=audit-log.js.map

package/dist/tools/audit-log.js.map

@@ -1 +1 @@
-{"version":3,"file":"audit-log.js","sourceRoot":"","sources":["../../src/tools/audit-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,uEAAuE;AACvE,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAClD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG;;;;;;;;iFAQ6D,CAAC;AAElF,MAAM,CAAC,MAAM,YAAY,GAAsC;IAC7D,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,WAAW;IACxB,WAAW;IACX,eAAe,EAAE;QACf,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACzB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACxB,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC9B;KACF;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;IACnC,IAAI,EAAE,gBAAgB;IACtB,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG;QACrB,SAAS,CAAC,GAAG,CAAC,CAAC;QACf,OAAO,GAAG,CAAC,SAAS,CAAC;YACnB,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACvD,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACvE,CAAC,CAAC;IACL,CAAC;CACF,CAAC"}
+{"version":3,"file":"audit-log.js","sourceRoot":"","sources":["../../src/tools/audit-log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,SAAS,EAAa,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,OAAO,EACL,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,YAAY,EACZ,kBAAkB,GAGnB,MAAM,mBAAmB,CAAC;AAE3B,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,uEAAuE;AACvE,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,gFAAgF;AAChF,8EAA8E;AAC9E,uEAAuE;AACvE,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAClD,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACpC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAClC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACvC,mEAAmE;IACnE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC1C,2EAA2E;IAC3E,6EAA6E;IAC7E,4CAA4C;IAC5C,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAClD,8DAA8D;IAC9D,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAC5D,iFAAiF;IACjF,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAIH,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,MAAM,YAAY,GAAG,GAAG,CAAC;AACzB,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAClC,MAAM,YAAY,GAAG,GAAG,CAAC;AAEzB,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;wCAiBoB,aAAa;;UAE3C,YAAY;EACpB,sBAAsB,oBAAoB,CAAC;AAE7C,MAAM,CAAC,MAAM,YAAY,GAAuB;IAC9C,IAAI,EAAE,WAAW;IACjB,WAAW,EAAE,WAAW;IACxB,WAAW;IACX,eAAe,EAAE;QACf,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACzB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC1B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACxB,SAAS,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAC7B,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,EAAE;YACjD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YACxB,cAAc,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;YAClC,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;SAC3B;KACF;IACD,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,EAAE;IACnC,IAAI,EAAE,gBAAgB;IACtB,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG;QACrB,SAAS,CAAC,GAAG,CAAC,CAAC;QACf,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,OAAO,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3E,IAAI,IAAI,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;YAC3D,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,CAAC;QAClC,CAAC;QACD,OAAO,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;CACF,CAAC;AAEF,SAAS,kBAAkB,CAAC,IAAkB;IAM5C,OAAO;QACL,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,gFAAgF;AAChF,KAAK,UAAU,UAAU,CACvB,GAAc,EACd,OAA+D,EAC/D,IAAY;AACZ,2EAA2E;AAC3E,6EAA6E;AAC7E,gCAAgC;AAChC,KAAc;IAEd,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC;IACpC,SAAS,CAAC;QACR,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,SAAS,CAAC;YAC/B,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC;YACnD,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9C,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7D,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7E,CAAC,CAAC;QACH,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;QAC5B,MAAM,GAAG,IAAI,CAAC,WAAW,CAAC;QAC1B,IAAI,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,IAAI;YAAE,MAAM;QAChF,IAAI,KAAK,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,KAAK;YAAE,MAAM;IAC/D,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC;AAED,8EAA8E;AAC9E,gFAAgF;AAChF,sEAAsE;AACtE,KAAK,UAAU,UAAU,CAAC,GAAc,EAAE,MAAe;IACvD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,gBAAgB,EAAE,CAAC;QAChD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACxB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,cAAc,EAAE,CAAC,CAAC,cAAc;YAChC,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,UAAU,EAAE,CAAC,CAAC,UAAU;YACxB,mBAAmB,EAAE,CAAC,CAAC,mBAAmB;YAC1C,aAAa,EAAE,CAAC,CAAC,aAAa;SAC/B,CAAC,CAAC,CAAC;IACN,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,KAAK,UAAU,eAAe,CAC5B,GAAc,EACd,IAAkB;IAElB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,YAAY,EAAE,KAAK,CAAC,CAAC;IACxD,MAAM,aAAa,GAAG,IAAI,CAAC,cAAc,IAAI,sBAAsB,CAAC;IAEpE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,UAAU,CAC9C,GAAG,EACH;QACE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvE,EACD,IAAI,CACL,CAAC;IACF,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,GAAG,EAAE,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE7D,0EAA0E;IAC1E,2EAA2E;IAC3E,6EAA6E;IAC7E,MAAM,UAAU,GAAiB,EAAE,CAAC;IACpC,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACpC,IAAI,MAAM,KAAK,IAAI;YAAE,YAAY,IAAI,CAAC,CAAC;QACvC,IAAI,YAAY,CAAC,KAAK,CAAC,IAAI,MAAM,KAAK,IAAI;YAAE,SAAS;QACrD,UAAU,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,CAAC;IACjG,CAAC;IAED,MAAM,MAAM,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,EAAE;QACzC,aAAa;QACb,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,MAAM;KACP,CAAC,CAAC;IACH,MAAM,WAAW,GAAG,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE5E,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IACzB,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE;YACN,IAAI,EAAE,MAAM,EAAE,UAAU,IAAI,IAAI;YAChC,EAAE,EAAE,MAAM,EAAE,UAAU,IAAI,IAAI;SAC/B;QACD,OAAO,EAAE,MAAM,CAAC,MAAM;QACtB,0EAA0E;QAC1E,SAAS,EAAE,WAAW,KAAK,IAAI;QAC/B,WAAW;QACX,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;QAClC,YAAY,EAAE,UAAU,CAAC,MAAM;QAC/B,gBAAgB,EAAE,UAAU,CAAC,MAAM,GAAG,KAAK;QAC3C,aAAa,EAAE,YAAY;QAC3B,MAAM,EAAE;YACN,KAAK,EAAE,WAAW,CAAC,MAAM;YACzB,cAAc,EAAE,OAAO,CAAC,MAAM;YAC9B,cAAc,EAAE,aAAa;YAC7B,OAAO;YACP,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC;gBACpB,CAAC,CAAC;oBACE,IAAI,EAAE,oGAAoG;iBAC3G;gBACH,CAAC,CAAC,EAAE,CAAC;SACR;QACD,YAAY,EAAE,WAAW;QACzB,yEAAyE;QACzE,2EAA2E;QAC3E,uEAAuE;QACvE,kDAAkD;QAClD,WAAW,EACT,MAAM,KAAK,IAAI;YACb,CAAC,CAAC,oBAAoB;YACtB,CAAC,CAAC,6IAA6I;QACnJ,OAAO,EAAE,SAAS,CAAC,UAAU,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC;KACjF,CAAC;AACJ,CAAC;AAED,SAAS,SAAS,CAChB,UAAkB,EAClB,SAAiB,EACjB,OAA8C,EAC9C,WAAmB;IAEnB,MAAM,KAAK,GAAG;QACZ,GAAG,UAAU,qBAAqB,SAAS,kBAAkB,WAAW,sBAAsB,OAAO,CAAC,MAAM,YAAY;KACzH,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,CAAC,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,aAAa,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,KAAK,CAAC,IAAI,CACR,GAAG,CAAC,CAAC,WAAW,QAAQ,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,KAAK,aAAa,gBAAgB,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,CACjK,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,4EAA4E;AAC5E,+EAA+E;AAC/E,KAAK,UAAU,YAAY,CACzB,GAAc,EACd,IAAkB,EAClB,MAAc;IAEd,MAAM,GAAG,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;IACnC,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,gHAAgH,CACjH,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,YAAY,EAAE,KAAK,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC9B,2EAA2E;IAC3E,wCAAwC;IACxC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IAE7E,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,UAAU,CACjC,GAAG,EACH,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EACjF,IAAI,EACJ,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CACtC,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QACpC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,IAAI,KAAK,CAAC,WAAW,KAAK,GAAG,CAAC,WAAW;YAAE,OAAO,KAAK,CAAC;QACxD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACxC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC;IACrD,CAAC,CAAC,CAAC;IACH,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,GAAG,EAAE;QAC9B,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACzC,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YACpC,OAAO,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC;QACvF,CAAC,CAAC;QACF,WAAW,EAAE,KAAK,CAAC,MAAM;QACzB,eAAe,EAAE,KAAK,CAAC,MAAM,GAAG,KAAK;QACrC,2EAA2E;QAC3E,sCAAsC;QACtC,OAAO,EAAE,MAAM,CAAC,MAAM;KACvB,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/tools/audit-rollup.d.ts

@@ -0,0 +1,80 @@
+export interface AuditEvent {
+    id: string;
+    type: string;
+    emitted_at: string;
+    [key: string]: unknown;
+}
+export interface EgressGrantSummary {
+    grant_id: string;
+    credential_ref: string;
+    created_at: string;
+    revoked_at: string | null;
+    rate_limit_per_hour?: number | null;
+    spend_cap_usd?: number | null;
+}
+export interface RollupKey {
+    reference: string;
+    target_host: string;
+    from: string;
+    to: string;
+}
+export interface EgressRollup extends RollupKey {
+    id: string;
+    count: number;
+    status_breakdown: Record<string, number>;
+    error_count: number;
+    anomaly_count: number;
+    total_bytes: number;
+    grants: Array<{
+        grant_id: string;
+        label?: string;
+    }>;
+}
+export interface GrantTotals {
+    grant_id: string;
+    credential_ref: string;
+    calls: number;
+    total_bytes: number;
+    last_used_at: string | null;
+    status_breakdown: Record<string, number>;
+    anomaly_count: number;
+    revoked_at: string | null;
+    rate_limit_per_hour?: number | null;
+    spend_cap_usd?: number | null;
+}
+export declare function normalizeAuditType(type: string): string;
+/** Why this row is actionable, or null when it is routine. */
+export declare function anomalyReason(event: AuditEvent): string | null;
+/** proxy_executed rows are the high-volume class the rollups collapse. */
+export declare function isEgressCall(event: AuditEvent): boolean;
+export declare function encodeRollupId(key: RollupKey): string;
+export declare function decodeRollupId(id: string): RollupKey | null;
+/**
+ * Cluster egress calls by (reference x target host), splitting a cluster
+ * whenever the gap between adjacent calls exceeds `windowMinutes`. A burst
+ * stays one row; a call an hour later starts a new one, so the window a rollup
+ * reports is a real burst rather than an arbitrary clock bucket.
+ *
+ * `events` is newest-first (the ledger's own order); the returned rollups keep
+ * that order.
+ */
+export declare function buildEgressRollups(events: readonly AuditEvent[], options: {
+    windowMinutes: number;
+    grants?: readonly EgressGrantSummary[];
+    labels?: Map<string, string>;
+}): EgressRollup[];
+/**
+ * Rolling per-grant totals so a human never sums rows by hand.
+ *
+ * Attribution caveat (see the module header): `vault.proxy_executed` carries no
+ * grant id, so a grant's calls are the egress calls on its credential inside
+ * its lifetime. Direct `use_credential` traffic on the same credential is
+ * indistinguishable and lands here too — an upper bound, flagged in the
+ * response's `attribution` field.
+ */
+export declare function buildGrantTotals(events: readonly AuditEvent[], grants: readonly EgressGrantSummary[]): GrantTotals[];
+/** Grant labels recorded on the grant_minted lifecycle event, when in scan. */
+export declare function grantLabels(events: readonly AuditEvent[]): Map<string, string>;
+export declare function formatBytes(bytes: number): string;
+export declare function describeStatuses(breakdown: Record<string, number>): string;
+//# sourceMappingURL=audit-rollup.d.ts.map

package/dist/tools/audit-rollup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-rollup.d.ts","sourceRoot":"","sources":["../../src/tools/audit-rollup.ts"],"names":[],"mappings":"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"}

package/dist/tools/audit-rollup.js.map

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

package/dist/tools/fetch-credential.d.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { type Tool } from "./index.js";
+declare const inputSchema: z.ZodUnion<[z.ZodEffects<z.ZodObject<{
+    reference: z.ZodOptional<z.ZodString>;
+    service: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    field: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    reference?: string | undefined;
+    name?: string | undefined;
+    field?: string | undefined;
+    service?: string | undefined;
+}, {
+    reference?: string | undefined;
+    name?: string | undefined;
+    field?: string | undefined;
+    service?: string | undefined;
+}>, {
+    reference?: string | undefined;
+    name?: string | undefined;
+    field?: string | undefined;
+    service?: string | undefined;
+}, {
+    reference?: string | undefined;
+    name?: string | undefined;
+    field?: string | undefined;
+    service?: string | undefined;
+}>, z.ZodObject<{
+    approval_id: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    approval_id: string;
+}, {
+    approval_id: string;
+}>]>;
+export declare const fetchCredentialTool: Tool<z.infer<typeof inputSchema>>;
+export {};
+//# sourceMappingURL=fetch-credential.d.ts.map

package/dist/tools/fetch-credential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-credential.d.ts","sourceRoot":"","sources":["../../src/tools/fetch-credential.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAa,KAAK,IAAI,EAAE,MAAM,YAAY,CAAC;AAgBlD,QAAA,MAAM,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAA2B,CAAC;AAoF7C,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAwDjE,CAAC"}

package/dist/tools/fetch-credential.js

@@ -0,0 +1,153 @@
+import { z } from "zod";
+import { ApiCallError } from "../api-client.js";
+import { ALWAYS_LOAD_META } from "./always-load.js";
+import { assertApi } from "./index.js";
+const start = z
+    .object({
+    reference: z.string().min(1).max(400).optional(),
+    service: z.string().min(1).max(120).optional(),
+    name: z.string().min(1).max(60).optional(),
+    field: z.string().min(1).max(120).optional(),
+})
+    .strict()
+    .refine((value) => value.reference !== undefined || value.service !== undefined || value.name !== undefined, { message: "one of reference, service, or name is required" });
+const resume = z.object({ approval_id: z.string().min(1).max(64) }).strict();
+const inputSchema = z.union([start, resume]);
+// The description is the only thing standing between a model and a needless
+// plaintext secret in its own transcript, so it leads with the cheaper route
+// and states the cost of this one in the first two sentences.
+const DESCRIPTION = `Return a vaulted credential's RAW value to you, in clear, after an explicit
+human passkey approval. Use it ONLY when unavoidable: the value lands in your
+context and therefore in the conversation transcript and any logs of it, which
+no later step can undo.
+
+Prefer \`use_credential\` whenever the task is "call an API with this key" — the
+server injects the secret into the HTTP request and returns only the upstream
+response, so the key never reaches you at all. Prefer an egress grant
+(\`grant_app_access\`) when a deployed app needs standing access. Reach for
+\`fetch_credential\` only when the raw key must physically land somewhere YOU
+control and no server-side injection path exists — writing it into a
+GitHub Actions secret, a .env file, or a config file. If you can accomplish
+the task without the plaintext, do that instead.
+
+Every fetch requires an explicit human passkey approval; there is no way to
+skip it. The first call resolves the credential and returns approval_pending
+with an approval_url — NO value. The user opens that link and signs with their
+passkey. Then call fetch_credential again with ONLY that approval_id to receive
+the value. Delivery is single-use: the same approval_id will not return the
+value twice, so store it where it needs to go on first receipt. A denied or
+expired approval returns a refusal and no value. Pass \`field\` to name one
+field of a multi-field credential (required when the credential has more than
+one — call list_credentials for its field names).`;
+function refusal(reason, approval) {
+    return {
+        status: "credential_fetch_refused",
+        reason,
+        approval_id: approval.approval_id,
+        credential: approval.credential,
+        field: approval.field,
+    };
+}
+function toolResult(approval) {
+    if (approval.status === "consumed" && approval.fields !== undefined) {
+        return {
+            status: "credential_fetched",
+            credential: approval.credential,
+            field: approval.field,
+            fields: approval.fields,
+            approval_id: approval.approval_id,
+            fetched_at: approval.fetched_at,
+            reminder: "This value is now in your context. Write it only where the user asked, " +
+                "and do not repeat it back in your reply.",
+        };
+    }
+    if (approval.status === "pending") {
+        return {
+            status: "approval_pending",
+            approval_id: approval.approval_id,
+            approval_url: approval.approval_url,
+            expires_at: approval.expires_at,
+            credential: approval.credential,
+            field: approval.field,
+            field_names: approval.field_names,
+            next: { tool: "fetch_credential", approval_id: approval.approval_id },
+        };
+    }
+    return refusal(approval.error ?? `approval_${approval.status}`, approval);
+}
+// A refused fetch comes back as a non-2xx carrying the same approval shape.
+// Rendering it as a typed refusal — rather than letting the HTTP error escape —
+// is what tells the agent to stop instead of retrying the approval loop.
+function refusalFromError(error) {
+    if (!(error instanceof ApiCallError))
+        return null;
+    if (!error.code.startsWith("credential_fetch_"))
+        return null;
+    const body = error.body;
+    return {
+        status: "credential_fetch_refused",
+        reason: error.code,
+        ...(body?.approval_id !== undefined ? { approval_id: body.approval_id } : {}),
+        ...(body?.credential !== undefined ? { credential: body.credential } : {}),
+        ...(body?.field !== undefined ? { field: body.field } : {}),
+    };
+}
+export const fetchCredentialTool = {
+    name: "fetch_credential",
+    description: DESCRIPTION,
+    inputSchema,
+    jsonInputSchema: {
+        type: "object",
+        oneOf: [
+            {
+                type: "object",
+                properties: {
+                    reference: { type: "string" },
+                    service: { type: "string" },
+                    name: { type: "string" },
+                    field: { type: "string" },
+                },
+                additionalProperties: false,
+            },
+            {
+                type: "object",
+                required: ["approval_id"],
+                properties: { approval_id: { type: "string" } },
+                additionalProperties: false,
+            },
+        ],
+    },
+    // Not read-only: a fetch discloses a secret and burns a single-use approval.
+    annotations: { destructiveHint: true, idempotentHint: false },
+    meta: ALWAYS_LOAD_META,
+    async handler(args, api) {
+        assertApi(api);
+        try {
+            const approval = "approval_id" in args
+                ? await api.getCredentialFetchApproval(args.approval_id)
+                : await api.createCredentialFetchApproval({
+                    ...(args.reference !== undefined ? { reference: args.reference } : {}),
+                    ...(args.service !== undefined ? { service: args.service } : {}),
+                    ...(args.name !== undefined ? { name: args.name } : {}),
+                    ...(args.field !== undefined ? { field: args.field } : {}),
+                });
+            return toolResult(approval);
+        }
+        catch (error) {
+            const refused = refusalFromError(error);
+            if (refused !== null)
+                return refused;
+            if (error instanceof ApiCallError && error.code === "ambiguous_credential_field") {
+                const names = error.body?.field_names;
+                return {
+                    status: "credential_fetch_refused",
+                    reason: "ambiguous_credential_field",
+                    field_names: Array.isArray(names) ? names : [],
+                    remedy: "Retry fetch_credential with `field` set to one of field_names.",
+                };
+            }
+            throw error;
+        }
+    },
+};
+//# sourceMappingURL=fetch-credential.js.map

package/dist/tools/fetch-credential.js.map

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

package/dist/tools/index.d.ts

@@ -9,6 +9,7 @@ import { revokeAppAccessTool, listAppAccessTool } from "./revoke-app-access.js";
 import { auditLogTool } from "./audit-log.js";
 import { listPaymentCardsTool, operatePayTool, operatePaymentStatusTool } from "./operate-pay.js";
 import { deleteCredentialTool, editCredentialTool } from "./credential-mutations.js";
+import { fetchCredentialTool } from "./fetch-credential.js";
 export interface Tool<TArgs extends Record<string, unknown> = Record<string, unknown>> {
     name: string;
     description: string;
@@ -21,6 +22,7 @@ export interface Tool<TArgs extends Record<string, unknown> = Record<string, unk
 }
 export interface ToolContext {
     notifyUser: (message: string, data?: Record<string, unknown>) => Promise<void>;
+    paymentApprovalWaitMs?: number;
 }
 export { ALWAYS_LOAD_META } from "./always-load.js";
 export declare function assertApi(api: ApiClient | null): asserts api is ApiClient;
@@ -28,5 +30,5 @@ export declare function buildToolRegistry(env?: NodeJS.ProcessEnv): Tool[];
 export declare const TOOLS: Tool[];
 export declare function findTool(name: string, tools?: readonly Tool[]): Tool | null;
 export { z };
-export { listCredentialsTool, storeCredentialTool, editCredentialTool, deleteCredentialTool, useCredentialTool, grantAppAccessTool, listAppAccessTool, revokeAppAccessTool, auditLogTool, listExtractFailuresTool, getExtractFailureTool, listPaymentCardsTool, operatePayTool, operatePaymentStatusTool, };
+export { listCredentialsTool, storeCredentialTool, editCredentialTool, deleteCredentialTool, useCredentialTool, fetchCredentialTool, grantAppAccessTool, listAppAccessTool, revokeAppAccessTool, auditLogTool, listExtractFailuresTool, getExtractFailureTool, listPaymentCardsTool, operatePayTool, operatePaymentStatusTool, };
 //# sourceMappingURL=index.d.ts.map