@intutic/shared-types 2.1.0 → 2.3.0

package/dist/mcpBudgets.d.ts

@@ -0,0 +1,191 @@
+/**
+ * MCP call budgets — how many MCP tool calls a workspace allows per hour or
+ * per day, per server, per member, per tool, or per member on one server.
+ *
+ * An MCP tool call has no price of its own: the protocol's `tools/call` result
+ * carries content, structured content, an error flag and `_meta`, and nothing
+ * that reports cost (the only cost-shaped field in the specification,
+ * `costPriority`, is a client's model preference for sampling). So a budget
+ * counts calls.
+ *
+ * The workspace setting `mcpBudgets` holds the budgets. The control plane
+ * validates it with {@link McpBudgetSettingsSchema} when an owner or admin
+ * writes it, delivers it to every MCP proxy with the rest of the MCP policy,
+ * and the proxy reads it with {@link parseMcpBudgetPolicy} and enforces it
+ * against counters in Valkey before each call
+ * (`packages/mcp-proxy/src/budget.ts`).
+ *
+ * @module
+ */
+import { z } from 'zod';
+/**
+ * What a budget counts:
+ * - `server`        every call to one server;
+ * - `tool`          every call to one tool on one server;
+ * - `member`        each member's calls across every server;
+ * - `member_server` each member's calls to one server.
+ *
+ * A `member` or `member_server` budget names one member, or none to give
+ * every member their own allowance of the same size.
+ */
+export type McpBudgetScope = 'server' | 'tool' | 'member' | 'member_server';
+/** A budget's period. Periods are fixed UTC windows: an hour starts on the hour, a day at 00:00 UTC. */
+export type McpBudgetPeriod = 'hour' | 'day';
+export interface McpBudget {
+    /** Stable id, so a counter survives an edit to the limit. Named in refusals and alerts. */
+    id: string;
+    scope: McpBudgetScope;
+    /** The server, for `server`, `tool` and `member_server`. */
+    server?: string;
+    /** The tool, for `tool`. */
+    tool?: string;
+    /** One member, for `member` and `member_server`; absent means each member separately. */
+    memberId?: string;
+    period: McpBudgetPeriod;
+    /** Calls allowed per period. */
+    limit: number;
+}
+export interface McpBudgetPolicy {
+    budgets: McpBudget[];
+    /** A budget warns once per period when its calls reach this percentage of the limit. */
+    warnAtPct: number;
+}
+/** The LLM budget alert's default threshold, used here too so both kinds of budget warn alike. */
+export declare const MCP_BUDGET_DEFAULT_WARN_PCT = 80;
+export declare const MAX_MCP_BUDGETS = 200;
+export declare const MAX_MCP_BUDGET_LIMIT = 1000000;
+export declare const MCP_BUDGET_SCOPES: readonly McpBudgetScope[];
+export declare const MCP_BUDGET_PERIODS: readonly McpBudgetPeriod[];
+/**
+ * The `mcpBudgets` workspace setting as an owner or admin writes it. Budget
+ * ids are unique within a workspace: the id is part of the counter's key.
+ */
+export declare const McpBudgetSettingsSchema: z.ZodEffects<z.ZodObject<{
+    budgets: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        id: z.ZodString;
+        scope: z.ZodEnum<["server", "tool", "member", "member_server"]>;
+        server: z.ZodOptional<z.ZodString>;
+        tool: z.ZodOptional<z.ZodString>;
+        memberId: z.ZodOptional<z.ZodString>;
+        period: z.ZodEnum<["hour", "day"]>;
+        limit: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        limit: number;
+        scope: "server" | "tool" | "member" | "member_server";
+        id: string;
+        period: "hour" | "day";
+        server?: string | undefined;
+        tool?: string | undefined;
+        memberId?: string | undefined;
+    }, {
+        limit: number;
+        scope: "server" | "tool" | "member" | "member_server";
+        id: string;
+        period: "hour" | "day";
+        server?: string | undefined;
+        tool?: string | undefined;
+        memberId?: string | undefined;
+    }>, {
+        limit: number;
+        scope: "server" | "tool" | "member" | "member_server";
+        id: string;
+        period: "hour" | "day";
+        server?: string | undefined;
+        tool?: string | undefined;
+        memberId?: string | undefined;
+    }, {
+        limit: number;
+        scope: "server" | "tool" | "member" | "member_server";
+        id: string;
+        period: "hour" | "day";
+        server?: string | undefined;
+        tool?: string | undefined;
+        memberId?: string | undefined;
+    }>, "many">;
+    warnAtPct: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    budgets: {
+        limit: number;
+        scope: "server" | "tool" | "member" | "member_server";
+        id: string;
+        period: "hour" | "day";
+        server?: string | undefined;
+        tool?: string | undefined;
+        memberId?: string | undefined;
+    }[];
+    warnAtPct?: number | undefined;
+}, {
+    budgets: {
+        limit: number;
+        scope: "server" | "tool" | "member" | "member_server";
+        id: string;
+        period: "hour" | "day";
+        server?: string | undefined;
+        tool?: string | undefined;
+        memberId?: string | undefined;
+    }[];
+    warnAtPct?: number | undefined;
+}>, {
+    budgets: {
+        limit: number;
+        scope: "server" | "tool" | "member" | "member_server";
+        id: string;
+        period: "hour" | "day";
+        server?: string | undefined;
+        tool?: string | undefined;
+        memberId?: string | undefined;
+    }[];
+    warnAtPct?: number | undefined;
+}, {
+    budgets: {
+        limit: number;
+        scope: "server" | "tool" | "member" | "member_server";
+        id: string;
+        period: "hour" | "day";
+        server?: string | undefined;
+        tool?: string | undefined;
+        memberId?: string | undefined;
+    }[];
+    warnAtPct?: number | undefined;
+}>;
+export type McpBudgetSettings = z.infer<typeof McpBudgetSettingsSchema>;
+/**
+ * Reads `mcpBudgets` as the control plane delivered it. Every budget is
+ * checked on its own and a malformed one is dropped, so one bad entry never
+ * lifts the others; anything that is not a settings object reads as no
+ * budgets at all.
+ */
+export declare function parseMcpBudgetPolicy(value: unknown): McpBudgetPolicy;
+/** One tool call, as far as budgets are concerned. */
+export interface McpBudgetCall {
+    server: string;
+    tool: string;
+    /** The member the proxy's API key resolves to, when the control plane said. */
+    memberId: string | null;
+    /**
+     * Who to count a per-member budget against when no member is known — the
+     * API key's prefix, say. Callers nobody can identify share one allowance.
+     */
+    fallbackCaller: string;
+}
+/** A budget that applies to a call, and whose allowance the call draws on. */
+export interface McpBudgetCharge {
+    budget: McpBudget;
+    /** Distinguishes allowances within one budget: the member, for an each-member budget. */
+    subject: string;
+}
+/**
+ * The budgets a call counts against, in the order they were configured. A
+ * call draws on every one of them, and is refused when any is used up.
+ */
+export declare function budgetsForCall(policy: McpBudgetPolicy, call: McpBudgetCall): McpBudgetCharge[];
+/** The fixed window a moment falls in: when it began and when it resets. */
+export declare function budgetWindow(period: McpBudgetPeriod, nowMs: number): {
+    startMs: number;
+    resetAtMs: number;
+};
+/** The call count at which a budget warns: `warnAtPct` of the limit, rounded up, at least one call. */
+export declare function budgetWarnAt(limit: number, warnAtPct: number): number;
+/** A budget in words, for refusals, alerts and the dashboard: what it counts, and how many per period. */
+export declare function describeMcpBudget(budget: McpBudget, memberLabel?: string): string;
+//# sourceMappingURL=mcpBudgets.d.ts.map

package/dist/mcpBudgets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpBudgets.d.ts","sourceRoot":"","sources":["../src/mcpBudgets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,eAAe,CAAA;AAE3E,wGAAwG;AACxG,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,KAAK,CAAA;AAE5C,MAAM,WAAW,SAAS;IACxB,2FAA2F;IAC3F,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,cAAc,CAAA;IACrB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4BAA4B;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,eAAe,CAAA;IACvB,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,SAAS,EAAE,CAAA;IACpB,wFAAwF;IACxF,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,kGAAkG;AAClG,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAC7C,eAAO,MAAM,eAAe,MAAM,CAAA;AAClC,eAAO,MAAM,oBAAoB,UAAY,CAAA;AAE7C,eAAO,MAAM,iBAAiB,EAAE,SAAS,cAAc,EAAkD,CAAA;AACzG,eAAO,MAAM,kBAAkB,EAAE,SAAS,eAAe,EAAoB,CAAA;AAyB7E;;;GAGG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAYhC,CAAA;AAEJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAA;AAEvE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAepE;AAED,sDAAsD;AACtD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAA;CACvB;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,CAAA;IACjB,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,GAAG,eAAe,EAAE,CAW9F;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAI3G;AAED,uGAAuG;AACvG,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAErE;AAED,0GAA0G;AAC1G,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAWjF"}

package/dist/mcpBudgets.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * MCP call budgets — how many MCP tool calls a workspace allows per hour or
+ * per day, per server, per member, per tool, or per member on one server.
+ *
+ * An MCP tool call has no price of its own: the protocol's `tools/call` result
+ * carries content, structured content, an error flag and `_meta`, and nothing
+ * that reports cost (the only cost-shaped field in the specification,
+ * `costPriority`, is a client's model preference for sampling). So a budget
+ * counts calls.
+ *
+ * The workspace setting `mcpBudgets` holds the budgets. The control plane
+ * validates it with {@link McpBudgetSettingsSchema} when an owner or admin
+ * writes it, delivers it to every MCP proxy with the rest of the MCP policy,
+ * and the proxy reads it with {@link parseMcpBudgetPolicy} and enforces it
+ * against counters in Valkey before each call
+ * (`packages/mcp-proxy/src/budget.ts`).
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpBudgetSettingsSchema = exports.MCP_BUDGET_PERIODS = exports.MCP_BUDGET_SCOPES = exports.MAX_MCP_BUDGET_LIMIT = exports.MAX_MCP_BUDGETS = exports.MCP_BUDGET_DEFAULT_WARN_PCT = void 0;
+exports.parseMcpBudgetPolicy = parseMcpBudgetPolicy;
+exports.budgetsForCall = budgetsForCall;
+exports.budgetWindow = budgetWindow;
+exports.budgetWarnAt = budgetWarnAt;
+exports.describeMcpBudget = describeMcpBudget;
+const zod_1 = require("zod");
+/** The LLM budget alert's default threshold, used here too so both kinds of budget warn alike. */
+exports.MCP_BUDGET_DEFAULT_WARN_PCT = 80;
+exports.MAX_MCP_BUDGETS = 200;
+exports.MAX_MCP_BUDGET_LIMIT = 1_000_000;
+exports.MCP_BUDGET_SCOPES = ['server', 'tool', 'member', 'member_server'];
+exports.MCP_BUDGET_PERIODS = ['hour', 'day'];
+const PERIOD_MS = { hour: 3_600_000, day: 86_400_000 };
+const BudgetSchema = zod_1.z
+    .object({
+    id: zod_1.z.string().regex(/^[A-Za-z0-9_-]{1,40}$/, 'letters, digits, - and _, at most 40'),
+    scope: zod_1.z.enum(['server', 'tool', 'member', 'member_server']),
+    server: zod_1.z.string().min(1).max(256).optional(),
+    tool: zod_1.z.string().min(1).max(256).optional(),
+    memberId: zod_1.z.string().min(1).max(64).optional(),
+    period: zod_1.z.enum(['hour', 'day']),
+    limit: zod_1.z.number().int().min(1).max(exports.MAX_MCP_BUDGET_LIMIT),
+})
+    .strict()
+    .superRefine((b, ctx) => {
+    const needsServer = b.scope !== 'member';
+    if (needsServer && !b.server)
+        ctx.addIssue({ code: 'custom', path: ['server'], message: `a ${b.scope} budget names a server` });
+    if (!needsServer && b.server)
+        ctx.addIssue({ code: 'custom', path: ['server'], message: 'a member budget covers every server' });
+    if (b.scope === 'tool' && !b.tool)
+        ctx.addIssue({ code: 'custom', path: ['tool'], message: 'a tool budget names a tool' });
+    if (b.scope !== 'tool' && b.tool)
+        ctx.addIssue({ code: 'custom', path: ['tool'], message: 'only a tool budget names a tool' });
+    const perMember = b.scope === 'member' || b.scope === 'member_server';
+    if (!perMember && b.memberId)
+        ctx.addIssue({ code: 'custom', path: ['memberId'], message: 'only a member budget names a member' });
+});
+/**
+ * The `mcpBudgets` workspace setting as an owner or admin writes it. Budget
+ * ids are unique within a workspace: the id is part of the counter's key.
+ */
+exports.McpBudgetSettingsSchema = zod_1.z
+    .object({
+    budgets: zod_1.z.array(BudgetSchema).max(exports.MAX_MCP_BUDGETS),
+    warnAtPct: zod_1.z.number().int().min(1).max(99).optional(),
+})
+    .strict()
+    .superRefine((s, ctx) => {
+    const seen = new Set();
+    s.budgets.forEach((b, i) => {
+        if (seen.has(b.id))
+            ctx.addIssue({ code: 'custom', path: ['budgets', i, 'id'], message: `duplicate budget id "${b.id}"` });
+        seen.add(b.id);
+    });
+});
+/**
+ * Reads `mcpBudgets` as the control plane delivered it. Every budget is
+ * checked on its own and a malformed one is dropped, so one bad entry never
+ * lifts the others; anything that is not a settings object reads as no
+ * budgets at all.
+ */
+function parseMcpBudgetPolicy(value) {
+    const empty = { budgets: [], warnAtPct: exports.MCP_BUDGET_DEFAULT_WARN_PCT };
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return empty;
+    const raw = value;
+    const budgets = [];
+    const seen = new Set();
+    for (const entry of Array.isArray(raw['budgets']) ? raw['budgets'] : []) {
+        const parsed = BudgetSchema.safeParse(entry);
+        if (!parsed.success || seen.has(parsed.data.id))
+            continue;
+        seen.add(parsed.data.id);
+        budgets.push(parsed.data);
+    }
+    const pct = raw['warnAtPct'];
+    const warnAtPct = typeof pct === 'number' && Number.isInteger(pct) && pct >= 1 && pct <= 99 ? pct : exports.MCP_BUDGET_DEFAULT_WARN_PCT;
+    return { budgets, warnAtPct };
+}
+/**
+ * The budgets a call counts against, in the order they were configured. A
+ * call draws on every one of them, and is refused when any is used up.
+ */
+function budgetsForCall(policy, call) {
+    const caller = call.memberId ?? call.fallbackCaller;
+    const charges = [];
+    for (const budget of policy.budgets) {
+        if (budget.server !== undefined && budget.server !== call.server)
+            continue;
+        if (budget.tool !== undefined && budget.tool !== call.tool)
+            continue;
+        if (budget.memberId !== undefined && budget.memberId !== call.memberId)
+            continue;
+        const perMember = budget.scope === 'member' || budget.scope === 'member_server';
+        charges.push({ budget, subject: perMember ? caller : '' });
+    }
+    return charges;
+}
+/** The fixed window a moment falls in: when it began and when it resets. */
+function budgetWindow(period, nowMs) {
+    const size = PERIOD_MS[period];
+    const startMs = Math.floor(nowMs / size) * size;
+    return { startMs, resetAtMs: startMs + size };
+}
+/** The call count at which a budget warns: `warnAtPct` of the limit, rounded up, at least one call. */
+function budgetWarnAt(limit, warnAtPct) {
+    return Math.max(1, Math.ceil((limit * warnAtPct) / 100));
+}
+/** A budget in words, for refusals, alerts and the dashboard: what it counts, and how many per period. */
+function describeMcpBudget(budget, memberLabel) {
+    const who = budget.memberId ? (memberLabel ?? `member ${budget.memberId}`) : 'each member';
+    const what = budget.scope === 'server'
+        ? `calls to ${budget.server}`
+        : budget.scope === 'tool'
+            ? `calls to ${budget.server} › ${budget.tool}`
+            : budget.scope === 'member'
+                ? `MCP calls by ${who}`
+                : `calls to ${budget.server} by ${who}`;
+    return `${what}: ${budget.limit} per ${budget.period}`;
+}
+//# sourceMappingURL=mcpBudgets.js.map

package/dist/mcpBudgets.js.map

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

package/dist/mcpRegistryRecord.d.ts

@@ -0,0 +1,143 @@
+/**
+ * The workspace's MCP server registry decisions, as the gates apply them.
+ *
+ * An owner or admin approves or blocks each MCP server on the MCP Servers
+ * page, disables tools within one, and sets what happens to a server nobody
+ * has decided on (`mcpDefaultPolicy`); a high-risk tool-set change can send a
+ * server back to the queue. The control plane serves those decisions as
+ * `mcpRegistry` on `GET /api/v1/policy/resolve`. The MCP proxy applies them to
+ * the servers it fronts; the sync daemon writes them into the policy snapshot
+ * as an `@mcp_registry` record so the harness hook gates apply them to every
+ * `mcp__<server>__<tool>` call, the servers no proxy fronts included.
+ *
+ * {@link evaluateMcpRegistry} is the one decision. The MCP proxy and the
+ * control plane's hook gate call it, the JavaScript hook gates embed its
+ * source ({@link MCP_REGISTRY_JS_SOURCE}), `@intutic/gate` carries a
+ * byte-identical copy of this file, and the bash gates and `intutic-clawde`
+ * run its Python transliteration (`intutic_clawde/gate/mcp_registry.py`);
+ * `fixtures/mcp-registry-vectors.json` holds all of them to the same codes,
+ * rule ids and reasons.
+ *
+ * The workspace's `mcpAllowedServers` list rides beside it as an
+ * `@mcp_allowlist` record ({@link evaluateMcpAllowlist}). Both records sit
+ * inside the snapshot's digest, and a gate that finds the snapshot unverified
+ * (its digest broken or missing, or another workspace's) trusts neither: it
+ * refuses every MCP call with {@link mcpSnapshotUnverifiedRefusal}, at `block`
+ * even in an observe-only workspace. An edit that widens either record, or
+ * deletes one, therefore admits nothing. A policy activates only when it
+ * verifies; the sync daemon restores the last snapshot it verified.
+ *
+ * Self-contained (no imports) so `@intutic/gate`, which has no workspace
+ * dependencies, can carry the copy.
+ *
+ * @module
+ */
+/** What the registry decides, per workspace. The MCP proxy's `McpRegistryPolicy` has the same shape. */
+export interface McpRegistryRecord {
+    defaultPolicy: 'allow' | 'deny';
+    approvedServers: string[];
+    blockedServers: string[];
+    /** Servers a high-risk tool change returned to the approval queue; refused under either default. */
+    heldServers: string[];
+    /** Server name → tool names disabled within it. */
+    disabledTools: Record<string, string[]>;
+}
+/** A registry refusal: the code every MCP surface uses, the deciding rule, and why. */
+export interface McpRegistryRefusal {
+    code: 'SERVER_BLOCKED' | 'SERVER_HELD' | 'SERVER_NOT_APPROVED' | 'TOOL_DISABLED';
+    ruleId: string;
+    reason: string;
+}
+/**
+ * Decides one MCP tool call against the registry: a blocked server, then a
+ * held one, then — under `deny` — one not approved, then a disabled tool.
+ * Null lets the call continue.
+ *
+ * Self-contained (no imports, no module state) because the JavaScript hook
+ * gates run it as emitted source.
+ */
+export declare function evaluateMcpRegistry(registry: McpRegistryRecord, serverName: string, toolName: string): McpRegistryRefusal | null;
+/** {@link evaluateMcpRegistry} as source, for the JavaScript hook gates. */
+export declare const MCP_REGISTRY_JS_SOURCE: string;
+/**
+ * Reads `mcpRegistry` as the control plane sends it. Null for anything that is
+ * not a registry object; wrong-typed lists read as empty, and any default but
+ * `deny` reads as `allow`, the control plane's own reading of the setting.
+ */
+export declare function parseMcpRegistryRecord(value: unknown): McpRegistryRecord | null;
+/** Whether a registry refuses nothing: no snapshot record is written for one. */
+export declare function isUnrestrictedMcpRegistry(registry: McpRegistryRecord): boolean;
+/**
+ * First column of the record's line in `policy-snapshot.rules`. A data line,
+ * like `@sso_groups`, so the digest every gate recomputes covers it; two
+ * columns, so every rule parser (which needs six) skips it.
+ */
+export declare const MCP_REGISTRY_RECORD_TAG = "@mcp_registry";
+/** The record as one `.rules` line: the tag, a tab, base64 of its JSON. */
+export declare function encodeMcpRegistryRecord(registry: McpRegistryRecord): string;
+/** Reads a record line back; null for any other line or a damaged one. */
+export declare function decodeMcpRegistryRecord(line: string): McpRegistryRecord | null;
+/**
+ * The workspace's `mcpAllowedServers` list as the gates apply it: only the
+ * listed servers may be called, and under `shadow` (an observe-only
+ * workspace) a call to another is recorded instead of refused. A workspace
+ * with no list has no record.
+ */
+export interface McpAllowlistRecord {
+    severity: 'block' | 'shadow';
+    servers: string[];
+}
+/** An allowlist refusal, shaped like {@link McpRegistryRefusal}. */
+export interface McpAllowlistRefusal {
+    code: 'SERVER_NOT_ALLOWED';
+    ruleId: 'mcp_allowlist';
+    reason: string;
+}
+/**
+ * Decides one MCP call's server against the allowlist. Null lets the call
+ * continue; a refusal under `shadow` is recorded, not enforced, by the caller.
+ *
+ * Self-contained, like {@link evaluateMcpRegistry}, because the JavaScript
+ * hook gates run it as emitted source.
+ */
+export declare function evaluateMcpAllowlist(allowlist: McpAllowlistRecord, serverName: string): McpAllowlistRefusal | null;
+/** {@link evaluateMcpAllowlist} as source, for the JavaScript hook gates. */
+export declare const MCP_ALLOWLIST_JS_SOURCE: string;
+/** The refusal of an MCP call on a snapshot that failed its integrity check. */
+export interface McpSnapshotUnverifiedRefusal {
+    code: 'POLICY_SNAPSHOT_UNVERIFIED';
+    ruleId: 'policy_snapshot';
+    reason: string;
+}
+/**
+ * Refuses one MCP call because the policy snapshot failed its digest or
+ * workspace check. Neither the registry's approvals nor the allowlist's
+ * servers can be vouched for then, and a deleted record is indistinguishable
+ * from one the workspace never set, so the snapshot admits no MCP server at
+ * all. Every gate that reads the snapshot refuses with this, at `block`.
+ *
+ * Self-contained, like {@link evaluateMcpRegistry}, because the JavaScript
+ * hook gates run it as emitted source.
+ */
+export declare function mcpSnapshotUnverifiedRefusal(serverName: string): McpSnapshotUnverifiedRefusal;
+/** {@link mcpSnapshotUnverifiedRefusal} as source, for the JavaScript hook gates. */
+export declare const MCP_SNAPSHOT_UNVERIFIED_JS_SOURCE: string;
+/**
+ * First column of the allowlist's line in `policy-snapshot.rules`. A data
+ * line, so the digest covers it and a server added to the list by hand fails
+ * the check; three columns, so every rule parser skips it.
+ */
+export declare const MCP_ALLOWLIST_RECORD_TAG = "@mcp_allowlist";
+/**
+ * The allowlist as one `.rules` line: the tag, the severity and the server
+ * names joined by commas, tab-separated. Plain text, so the bash gates read
+ * it with parameter expansion; the snapshot writer drops a name holding
+ * whitespace or a comma.
+ */
+export declare function encodeMcpAllowlistRecord(allowlist: McpAllowlistRecord): string;
+/**
+ * Reads an allowlist line back; null for any other line. A severity other
+ * than `shadow` reads as `block`, so a damaged one refuses.
+ */
+export declare function decodeMcpAllowlistRecord(line: string): McpAllowlistRecord | null;
+//# sourceMappingURL=mcpRegistryRecord.d.ts.map

package/dist/mcpRegistryRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcpRegistryRecord.d.ts","sourceRoot":"","sources":["../src/mcpRegistryRecord.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,wGAAwG;AACxG,MAAM,WAAW,iBAAiB;IAChC,aAAa,EAAE,OAAO,GAAG,MAAM,CAAA;IAC/B,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,oGAAoG;IACpG,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;CACxC;AAED,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,GAAG,aAAa,GAAG,qBAAqB,GAAG,eAAe,CAAA;IAChF,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,iBAAiB,EAC3B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,kBAAkB,GAAG,IAAI,CA2C3B;AAED,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,QAAiC,CAAA;AAUpE;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAgB/E;AAED,iFAAiF;AACjF,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAO9E;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,kBAAkB,CAAA;AAYtD,2EAA2E;AAC3E,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAE3E;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAQ9E;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,GAAG,QAAQ,CAAA;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAA;CAClB;AAED,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,oBAAoB,CAAA;IAC1B,MAAM,EAAE,eAAe,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,mBAAmB,GAAG,IAAI,CAOlH;AAED,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,QAAkC,CAAA;AAEtE,gFAAgF;AAChF,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,4BAA4B,CAAA;IAClC,MAAM,EAAE,iBAAiB,CAAA;IACzB,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,4BAA4B,CAS7F;AAED,qFAAqF;AACrF,eAAO,MAAM,iCAAiC,QAA0C,CAAA;AAExF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,mBAAmB,CAAA;AAExD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,kBAAkB,GAAG,MAAM,CAE9E;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAIhF"}