@cybedefend/vibedefend 1.5.0 → 1.7.0

package/dist/mcp/verify/backend.js

@@ -0,0 +1,143 @@
+/**
+ * Which CybeDefend backend this machine talks to, with what — and AS WHICH
+ * ORGANIZATION.
+ *
+ * The region lives in `~/.cybedefend/runtime-config.json`, written by
+ * `vibedefend install`. A machine that has never been installed has no
+ * region, no token, and therefore no verification — which is a supported
+ * state, not a failure: the proxy still forwards everything, and the log says
+ * why nothing was verified.
+ *
+ * The organization lives in the same file (`organization`), selected at
+ * `vibedefend login`, with `vibedefend org`, or here, lazily: the verification
+ * routes are org-scoped, most accounts belong to exactly one organization,
+ * and asking those users to pick would be a prompt with one answer. An
+ * account that belongs to several must choose explicitly, and until it does
+ * there is no backend to talk to — unverified, never an allow.
+ *
+ * `VIBEDEFEND_MCP_API_BASE` overrides the region's `apiBase`. It is how the
+ * tests point the proxy at a local mock, and it goes through the same origin
+ * allowlist as everything else in `api.ts` — a URL that is not trusted is
+ * refused before any request leaves, the organization listing included.
+ */
+import { listOrganizations } from '../../api/projects.js';
+import { REGIONS } from '../../config.js';
+import { loadRuntimeConfig, saveRuntimeOrganization } from '../../hooks/runtime/config.js';
+import { isTrustedApiBase } from '../../hooks/runtime/trusted-api-base.js';
+import { PROXY_ENV_PREFIX } from '../proxy/paths.js';
+import { resolveVerifyToken } from './token.js';
+import { resolveVerifyTokenWithRefresh } from './token-refresh.js';
+/** The region the installer recorded, or the EU default. */
+export function activeRegion(deps = {}) {
+    try {
+        const runtime = (deps.loadRuntimeConfigFn ?? loadRuntimeConfig)();
+        const id = runtime?.region?.id;
+        const found = id ? REGIONS.find((region) => region.id === id) : undefined;
+        if (found)
+            return found;
+        // A custom region carries its own apiBase; it is honoured as it stands.
+        const custom = runtime?.region;
+        if (custom?.apiBase && custom.mcpName)
+            return custom;
+    }
+    catch {
+        /* no runtime config: fall through to the default */
+    }
+    return REGIONS[0];
+}
+/** The organization on file, without any network call. */
+export function persistedOrganization(deps = {}) {
+    try {
+        const runtime = (deps.loadRuntimeConfigFn ?? loadRuntimeConfig)();
+        const organization = runtime?.organization;
+        if (organization && typeof organization.id === 'string' && organization.id !== '') {
+            return { id: organization.id, name: typeof organization.name === 'string' ? organization.name : '' };
+        }
+    }
+    catch {
+        /* no runtime config, or an unreadable one */
+    }
+    return null;
+}
+/**
+ * Everything the verifier needs to reach the backend, or `null` when there is
+ * nothing to reach it with — no token, or no organization to speak for.
+ */
+export async function resolveBackendConfig(deps = {}) {
+    const env = deps.env ?? process.env;
+    const region = activeRegion(deps);
+    const apiBase = env[`${PROXY_ENV_PREFIX}API_BASE`]?.trim() || region.apiBase;
+    // Renewed if it expired: a human is waiting for this answer, and a stale
+    // token here turned a whole scan `unverified` (2026-09-16).
+    const token = await (deps.resolveTokenFn ?? resolveVerifyTokenWithRefresh)(region.mcpName, { env });
+    if (!token)
+        return null;
+    const organizationId = await resolveOrganizationId(apiBase, token, deps);
+    if (!organizationId)
+        return null;
+    return { apiBase, mcpName: region.mcpName, token, organizationId };
+}
+/**
+ * What the PROXY builds its verifier with — synchronously, and without a
+ * single network call.
+ *
+ * Section 0: nothing reaches CybeDefend before `initialize` is answered, and
+ * the verifier is wired before the proxy starts. So when no organization is
+ * persisted, the id is left to `resolveOrganizationId`, a thunk the verifier
+ * runs at its FIRST backend call — after `initialize`, on the `tools/list`
+ * path, where a network call already belongs. `scan`, `connect` and `org`
+ * are typed by a human and use `resolveBackendConfig` instead, which resolves
+ * up front.
+ */
+export function resolveBackendAccess(deps = {}) {
+    const env = deps.env ?? process.env;
+    const region = activeRegion(deps);
+    const apiBase = env[`${PROXY_ENV_PREFIX}API_BASE`]?.trim() || region.apiBase;
+    const token = resolveVerifyToken(region.mcpName, { env });
+    if (!token)
+        return null;
+    const persisted = persistedOrganization(deps);
+    return {
+        apiBase,
+        mcpName: region.mcpName,
+        token,
+        ...(persisted
+            ? { organizationId: persisted.id }
+            : { resolveOrganizationId: () => resolveOrganizationId(apiBase, token, deps) }),
+    };
+}
+/**
+ * The persisted organization, or the account's only one — persisted on the
+ * way. Several, none, or an answer that could not be obtained: `null`, with
+ * one line naming the count, and nothing else. A guess here would be a
+ * verification under the wrong organization's policy.
+ */
+export async function resolveOrganizationId(apiBase, token, deps) {
+    const persisted = persistedOrganization(deps);
+    if (persisted)
+        return persisted.id;
+    const warn = deps.warn ?? (() => undefined);
+    if (!isTrustedApiBase(apiBase)) {
+        warn('verify: apiBase is not a trusted origin — the organization was not resolved, nothing was sent');
+        return null;
+    }
+    const organizations = await (deps.listOrganizationsFn ?? listOrganizations)(apiBase, token);
+    if (organizations === null) {
+        warn('verify: could not list the organizations, no backend for this session');
+        return null;
+    }
+    if (organizations.length !== 1) {
+        warn('verify: no organization selected and the account belongs to several (or none); ' +
+            'run `vibedefend org <id>` — no backend for this session', { organizations: organizations.length });
+        return null;
+    }
+    const only = organizations[0];
+    try {
+        (deps.saveOrganizationFn ?? saveRuntimeOrganization)(only);
+    }
+    catch {
+        /* remembered for this session at least; the next one resolves it again */
+    }
+    return only.id;
+}
+//# sourceMappingURL=backend.js.map

package/dist/mcp/verify/backend.js.map

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

package/dist/mcp/verify/cache.js

@@ -0,0 +1,200 @@
+/**
+ * What we already know about a server and its tools, on this machine.
+ *
+ * One JSON file per server under `~/.cybedefend/mcp/cache/`. One file, not
+ * one database, for a reason the plan states: the agent spawns one proxy per
+ * MCP server and they all start at once, so a shared file would be five
+ * processes writing the same document within the same second. Per-server
+ * files never collide, and the interface below is narrow enough that moving
+ * to SQLite later is a swap rather than a rewrite.
+ *
+ * ─── The two rules that matter ──────────────────────────────────────────────
+ *
+ *  - `ok` expires after seven days. A tool that was clean last week is
+ *    probably still clean, and re-asking a backend about it on every session
+ *    would make the common case the expensive one. Seven days bounds how
+ *    stale that assumption can get.
+ *  - `malicious` NEVER expires. Nothing about the passage of time makes a
+ *    known-bad tool good again, and an expiry would silently reopen a server
+ *    the user was protected from. Only an explicit `vibedefend allow` clears
+ *    it.
+ *
+ * Overrides live in the same file as the verdicts they override, so a server
+ * the user allowed cannot end up half-allowed because two files disagreed.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeFileAtomic } from '../config/atomicWrite.js';
+import { mcpCacheDir } from '../proxy/paths.js';
+import { serverIdFileName } from './identity.js';
+import { isServerAction } from './policy.js';
+/** Seven days on `ok`; `malicious` never expires. */
+export const OK_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+export function sameStamp(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    return a.mtimeMs === b.mtimeMs && a.size === b.size;
+}
+export function emptyCacheFile(serverId, now) {
+    const stamp = now.toISOString();
+    return {
+        version: 1,
+        serverId,
+        server: { firstSeen: stamp, lastSeen: stamp, verdict: 'unknown' },
+        tools: {},
+    };
+}
+export function createJsonVerifyCache(options = {}) {
+    const dir = options.dir ?? mcpCacheDir(options.env ?? process.env);
+    const pathFor = (serverId) => join(dir, serverIdFileName(serverId));
+    return {
+        read(serverId) {
+            let text;
+            try {
+                text = readFileSync(pathFor(serverId), 'utf8');
+            }
+            catch {
+                return null;
+            }
+            return parseCacheFile(text, serverId);
+        },
+        write(file) {
+            // 0600: a `reason` may quote a tool description, which is the content
+            // of a server the user has not decided to trust yet.
+            writeFileAtomic(pathFor(file.serverId), `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+        },
+        stat(serverId) {
+            const stats = statSync(pathFor(serverId), { throwIfNoEntry: false });
+            return stats ? { mtimeMs: stats.mtimeMs, size: stats.size } : null;
+        },
+        list() {
+            if (!existsSync(dir))
+                return [];
+            const files = [];
+            for (const name of readdirSync(dir)) {
+                if (!name.endsWith('.json'))
+                    continue;
+                try {
+                    const parsed = parseCacheFile(readFileSync(join(dir, name), 'utf8'), '');
+                    if (parsed)
+                        files.push(parsed);
+                }
+                catch {
+                    /* a corrupt file is one server we cannot report, not a failure */
+                }
+            }
+            return files;
+        },
+    };
+}
+/**
+ * Reads a cache file, or `null`.
+ *
+ * A cache is a performance aid, never a source of truth for something we
+ * could not otherwise obtain, so a corrupt one reads as "nothing known" and
+ * the next verification rewrites it. The one thing NOT dropped on the way is
+ * a `malicious` verdict: see `mergeVerdict`.
+ */
+export function parseCacheFile(text, serverId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const typed = parsed;
+    if (typed.version !== 1 || typeof typed.server !== 'object' || !typed.server)
+        return null;
+    const tools = {};
+    for (const [digest, record] of Object.entries(typed.tools ?? {})) {
+        if (typeof record !== 'object' || record === null)
+            continue;
+        const entry = record;
+        if (!isVerdict(entry.verdict))
+            continue;
+        // An action this binary cannot read is no action: the verdict decides.
+        if (entry.action !== undefined && !isServerAction(entry.action))
+            delete entry.action;
+        tools[digest] = entry;
+    }
+    return {
+        version: 1,
+        serverId: typed.serverId || serverId,
+        server: {
+            firstSeen: typed.server.firstSeen ?? new Date(0).toISOString(),
+            lastSeen: typed.server.lastSeen ?? new Date(0).toISOString(),
+            verdict: isVerdict(typed.server.verdict) ? typed.server.verdict : 'unknown',
+            reason: typed.server.reason,
+            verdictAt: typed.server.verdictAt,
+            action: isServerAction(typed.server.action) ? typed.server.action : undefined,
+            override: typed.server.override === 'allow' || typed.server.override === 'deny' ? typed.server.override : undefined,
+            overrideAt: typed.server.overrideAt,
+            organizationBlock: parseOrganizationBlock(typed.server.organizationBlock),
+            advisoryIds: parseAdvisoryIds(typed.server.advisoryIds),
+            toolDigests: Array.isArray(typed.server.toolDigests)
+                ? typed.server.toolDigests.filter((digest) => typeof digest === 'string')
+                : undefined,
+        },
+        tools,
+    };
+}
+function parseOrganizationBlock(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const at = value.confirmedAt;
+    return typeof at === 'string' && !Number.isNaN(Date.parse(at)) ? { confirmedAt: at } : undefined;
+}
+/** Closed shape of an advisory id; also the bound of a report (`advisoryIds`). */
+export const ADVISORY_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
+export const MAX_ADVISORY_IDS = 10;
+function parseAdvisoryIds(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value
+        .filter((id) => typeof id === 'string' && ADVISORY_ID_PATTERN.test(id))
+        .slice(0, MAX_ADVISORY_IDS);
+}
+function isVerdict(value) {
+    return value === 'ok' || value === 'suspicious' || value === 'malicious' || value === 'pending' || value === 'unknown';
+}
+/** Has this record aged out? `malicious` never does. */
+export function isExpired(record, now, ttlMs = OK_TTL_MS) {
+    if (record.verdict === 'malicious')
+        return false;
+    if (record.verdict !== 'ok')
+        return true;
+    if (!record.verdictAt)
+        return true;
+    const at = Date.parse(record.verdictAt);
+    return Number.isNaN(at) || now.getTime() - at > ttlMs;
+}
+/**
+ * Combines what we knew with what we just learned.
+ *
+ * The rule the previous generation arrived at and this keeps: a FRESH answer
+ * that says "not known" never overwrites a fact we already have, and a fresh
+ * answer that DOES know always wins. Without the first half, one backend
+ * outage would quietly clear every `malicious` on the machine; without the
+ * second, a tool that has just been reclassified would stay wrong for a week.
+ */
+export function mergeVerdict(previous, next) {
+    if (!previous)
+        return next;
+    // The submission mark is a fact about what WE did, not a verdict: it
+    // survives whatever the fresh answer says, or the same digest would be
+    // bought again after every lookup that still came back "unknown".
+    const submittedAt = next.submittedAt ?? previous.submittedAt;
+    const marked = (record) => (submittedAt ? { ...record, submittedAt } : record);
+    if (next.verdict === 'unknown' || next.verdict === 'pending') {
+        return previous.verdict === 'unknown' || previous.verdict === 'pending' ? marked(next) : marked(previous);
+    }
+    return marked(next);
+}
+export function ensureCacheDir(options = {}) {
+    const dir = options.dir ?? mcpCacheDir(options.env ?? process.env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+//# sourceMappingURL=cache.js.map

package/dist/mcp/verify/cache.js.map

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

package/dist/mcp/verify/contract-errors.js

@@ -0,0 +1,198 @@
+/**
+ * What the backend refused, and since when.
+ *
+ * ── TWO FAMILIES OF FAILURE, AND ONLY ONE OF THEM IS FAIL-OPEN ──────────────
+ *
+ * A network error, a timeout or a 5xx means the backend could not answer. The
+ * proxy forwards the tool list, records `pending`, and says nothing to the
+ * agent: an outage must not turn every MCP server off, and the user cannot do
+ * anything about it anyway.
+ *
+ * A 400, 409 or 422 means the backend answered, and refused what we sent. That
+ * is not an outage, it is a DISAGREEMENT ABOUT THE CONTRACT — our request is
+ * malformed, or our digest formula is not one this server can compute. Filing
+ * it as `pending` would be a lie in the one direction that matters: `pending`
+ * says "we will retry and it will work", and retrying cannot help. Worse, it
+ * is indistinguishable from an ordinary outage, so a client that has stopped
+ * being able to verify ANYTHING looks exactly like a client waiting on a slow
+ * backend — for as long as nobody looks.
+ *
+ * ── WHY ITS OWN FILE, AND NOT THE PER-SERVER CACHE ─────────────────────────
+ *
+ * A contract error is not a property of the MCP server we happened to be
+ * asking about when it happened: it is a property of the client ↔ backend
+ * pair. A `409 DIGEST_VERSION_UNSUPPORTED` hits EVERY server, and writing it
+ * into the cache of whichever one we were looking at would draw a false map —
+ * one server "at fault", the others "clean", when in fact nothing is being
+ * verified anywhere.
+ *
+ * ── WHY SESSIONS AND NOT OCCURRENCES ───────────────────────────────────────
+ *
+ * The alert threshold is "it survived a restart". Counting occurrences would
+ * fire on a single session that listed three servers; counting distinct
+ * sessions asks the only question worth asking — did restarting fix it. Only
+ * the LAST session id is kept, not the set: the count is the answer, the list
+ * would only grow.
+ */
+import { mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeFileAtomic } from '../config/atomicWrite.js';
+import { sanitise } from '../proxy/inject.js';
+import { mcpHomeDir } from '../proxy/paths.js';
+/**
+ * The statuses that mean "your request is the problem".
+ *
+ * `400` malformed, `422` unprocessable, `409` a state disagreement — which is
+ * what an unsupported digest version is. `403` and `404` joined them with the
+ * org-scoped routes: the organization is in the PATH, and "not a member" or
+ * "no such organization" is an answer about what this machine selected, not
+ * about the backend's health — retrying with the same organization cannot
+ * help. Everything else, 429 and 5xx included, describes something that
+ * happened to the BACKEND and stays fail-open.
+ */
+export const CONTRACT_ERROR_STATUSES = [400, 403, 404, 409, 422];
+export function isContractErrorStatus(status) {
+    return CONTRACT_ERROR_STATUSES.includes(status);
+}
+/**
+ * ── `code` AND `supported` COME OFF THE WIRE ────────────────────────────────
+ *
+ * They are fields of an HTTP response. They are written to disk here, and
+ * rendered into the user's terminal by `vibedefend status`. This repository
+ * already has a doctrine for that — every string that came from a server goes
+ * through `sanitise` before it reaches a reader — and this path had missed it
+ * because the fields look like metadata rather than prose.
+ *
+ * What it costs if forgotten: an ESC[2J clears the screen, a carriage return
+ * rewrites the line above, a newline forges a second status line. `apiBase`
+ * is gated by the origin allowlist, true — but "the source is trusted" is
+ * exactly the reasoning that cost the two defects found in the Phase 4
+ * end-of-session review.
+ *
+ * The bounds are the other half: the SENDER, not us, would otherwise choose
+ * how much we write to the user's disk on every single occurrence.
+ */
+export const MAX_CONTRACT_CODE_CHARS = 64;
+export const MAX_SUPPORTED_VERSIONS = 8;
+export const MAX_SUPPORTED_VERSION_CHARS = 16;
+/** One code, safe to store and to print. */
+function safeCode(code) {
+    if (code === undefined)
+        return undefined;
+    const clean = sanitise(code, MAX_CONTRACT_CODE_CHARS);
+    return clean.length > 0 ? clean : undefined;
+}
+/** The supported-version list, bounded in both directions and sanitised. */
+function safeSupported(supported) {
+    if (supported === undefined)
+        return undefined;
+    const clean = supported
+        .slice(0, MAX_SUPPORTED_VERSIONS)
+        .map((value) => sanitise(value, MAX_SUPPORTED_VERSION_CHARS))
+        .filter((value) => value.length > 0);
+    return clean.length > 0 ? clean : undefined;
+}
+/** Distinct sessions before the agent is told. See the header. */
+export const PERSISTENT_AFTER_SESSIONS = 2;
+export function contractErrorsFile(env = process.env) {
+    return join(mcpHomeDir(env), 'contract-errors.json');
+}
+/**
+ * The key of a record. Route + status + code, so an unsupported digest version
+ * and a malformed body on the same route stay two separate lines — they have
+ * two separate fixes.
+ */
+function keyOf(input) {
+    return `${input.route}|${input.status}|${input.code ?? ''}`;
+}
+/**
+ * Reads the file, or an empty one.
+ *
+ * A malformed file reads as empty rather than throwing. Several proxies write
+ * this concurrently (one process per MCP server), and this is a JOURNAL: a
+ * corrupt journal must never be the reason a verification fails.
+ */
+function read(env) {
+    try {
+        const parsed = JSON.parse(readFileSync(contractErrorsFile(env), 'utf8'));
+        if (!parsed || typeof parsed !== 'object')
+            return { version: 1, errors: {} };
+        const file = parsed;
+        if (!file.errors || typeof file.errors !== 'object')
+            return { version: 1, errors: {} };
+        return { version: 1, errors: file.errors };
+    }
+    catch {
+        return { version: 1, errors: {} };
+    }
+}
+/** Every contract error on file, worst-persisting first. */
+export function listContractErrors(env = process.env) {
+    return Object.values(read(env).errors)
+        .map(({ lastSessionId: _ignored, ...record }) => record)
+        .sort((left, right) => right.sessions - left.sessions || left.route.localeCompare(right.route));
+}
+/** The ones that survived a restart — the threshold for telling the agent. */
+export function persistentContractErrors(env = process.env) {
+    return listContractErrors(env).filter((record) => record.sessions >= PERSISTENT_AFTER_SESSIONS);
+}
+/**
+ * Files one occurrence.
+ *
+ * Best-effort by design: a failure to write must not take down the
+ * verification that was already failing. The caller is in a `catch`.
+ */
+export function recordContractError(input, deps = {}) {
+    const env = deps.env ?? process.env;
+    const at = (deps.now ?? new Date()).toISOString();
+    // Sanitised HERE, at the one place wire data enters the record, rather than
+    // at each of the two places it leaves it. A guard on the way out is a guard
+    // the third reader forgets.
+    const code = safeCode(input.code);
+    const supported = safeSupported(input.supported);
+    try {
+        const file = read(env);
+        const key = keyOf({ ...input, code });
+        const existing = file.errors[key];
+        file.errors[key] = existing
+            ? {
+                ...existing,
+                // The code and the supported list can only get MORE precise: a
+                // backend that starts naming its refusal should not be ignored
+                // because the first occurrence was anonymous.
+                code: code ?? existing.code,
+                supported: supported ?? existing.supported,
+                lastSeenAt: at,
+                // Only a NEW session id advances the count. Three refusals inside
+                // one run are one session, which is the whole point.
+                sessions: existing.lastSessionId === input.sessionId ? existing.sessions : existing.sessions + 1,
+                lastSessionId: input.sessionId,
+            }
+            : {
+                route: input.route,
+                status: input.status,
+                code,
+                supported,
+                firstSeenAt: at,
+                lastSeenAt: at,
+                sessions: 1,
+                lastSessionId: input.sessionId,
+            };
+        mkdirSync(mcpHomeDir(env), { recursive: true });
+        writeFileAtomic(contractErrorsFile(env), `${JSON.stringify(file, null, 2)}\n`);
+    }
+    catch {
+        /* a journal that cannot be written is still not a reason to fail a check */
+    }
+}
+/** Clears the file. `vibedefend status` uses it once the disagreement is fixed. */
+export function clearContractErrors(env = process.env) {
+    try {
+        mkdirSync(mcpHomeDir(env), { recursive: true });
+        writeFileAtomic(contractErrorsFile(env), `${JSON.stringify({ version: 1, errors: {} }, null, 2)}\n`);
+    }
+    catch {
+        /* nothing to do: the next successful call will not re-file anything */
+    }
+}
+//# sourceMappingURL=contract-errors.js.map

package/dist/mcp/verify/contract-errors.js.map

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

package/dist/mcp/verify/digest.js

@@ -0,0 +1,91 @@
+import { createHash } from 'node:crypto';
+/**
+ * Maximum nesting depth accepted by the canonicalisation.
+ *
+ * The depth is attacker-controlled and the canonicalisation recurses. On this
+ * engine the stack overflows around 2,500 levels, while a 5,000-level schema
+ * weighs only ~30 KB, far below any size cap. Without a bound the resulting
+ * `RangeError` was neither a business error nor a shape error: it became an
+ * internal failure that took the whole batch down with it.
+ *
+ * 100 is two orders of magnitude above any real JSON Schema (the deepest
+ * schemas MCP servers produce stay around twenty levels) and twenty-five times
+ * below the measured overflow: the bound refuses an attack, never a
+ * legitimate schema.
+ */
+export const MAX_CANONICAL_DEPTH = 100;
+/**
+ * A caller-side shape error, not a server failure. Kept as a dedicated class
+ * rather than a bare `RangeError` so a controller can map it to an
+ * invalid-argument response, exactly as it already does for a `SyntaxError`
+ * on a syntactically invalid schema. A genuine stack overflow stays a failure.
+ */
+export class ToolSchemaTooDeepError extends Error {
+    maxDepth;
+    constructor(maxDepth) {
+        super(`tool schema nesting exceeds ${maxDepth} levels`);
+        this.maxDepth = maxDepth;
+        this.name = 'ToolSchemaTooDeepError';
+    }
+}
+/**
+ * JSON with keys sorted at every depth: two payloads that differ only by key
+ * order produce a single string. Arrays keep their order, because in JSON
+ * Schema `required` and `enum` are ordered data.
+ *
+ * Depth-bounded: see `MAX_CANONICAL_DEPTH`.
+ */
+export function stableStringify(value) {
+    return canonicalize(value, 0);
+}
+/**
+ * The depth is passed explicitly, never through a default parameter exposed to
+ * `Array.prototype.map`: `value.map(canonicalize)` would pass the array INDEX
+ * as the second argument and reset the bound on every first element, a guard
+ * that compiles, passes nominal tests, and guards nothing.
+ */
+function canonicalize(value, depth) {
+    if (depth > MAX_CANONICAL_DEPTH) {
+        throw new ToolSchemaTooDeepError(MAX_CANONICAL_DEPTH);
+    }
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalize(item, depth + 1)).join(',')}]`;
+    const entries = Object.keys(value)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${canonicalize(value[k], depth + 1)}`);
+    return `{${entries.join(',')}}`;
+}
+/**
+ * Version of the digest formula, carried as a prefix of every digest
+ * (`d1:<sha256 hex>`). The digest is shared across organisations and
+ * repositories: bump this when the formula changes so old verdicts are
+ * ignored rather than silently mismatched.
+ */
+export const DIGEST_VERSION = 'd1';
+/**
+ * Digest of a tool definition: exactly the surface the agent consumes and the
+ * attacker controls. `title` and `annotations` are included on purpose: the
+ * agent reads them too (a lying `destructiveHint: false`, for instance).
+ *
+ * No whitespace normalisation. This digest is the cache key of the backend
+ * judge, and the judge reads the RAW text: two descriptions it would read
+ * differently must never share a verdict.
+ *
+ * Shared contract with the backend: `tests/mcp/verify/__fixtures__/digest-vectors.json`
+ * pins the expected output on both sides.
+ */
+export function toolDigest(tool) {
+    const canonical = stableStringify({
+        name: tool.name ?? '',
+        title: tool.title ?? '',
+        description: tool.description ?? '',
+        inputSchema: tool.inputSchema ?? null,
+        outputSchema: tool.outputSchema ?? null,
+        annotations: tool.annotations ?? null,
+    });
+    const hex = createHash('sha256').update(canonical, 'utf8').digest('hex');
+    return `${DIGEST_VERSION}:${hex}`;
+}
+//# sourceMappingURL=digest.js.map