@cybedefend/vibedefend 1.5.0 → 1.7.0

package/dist/mcp/verify/verifier.js

@@ -0,0 +1,1166 @@
+/**
+ * Deciding what to do with a `tools/list`, and asking the backend as little
+ * as possible to get there.
+ *
+ * ─── The shape of a verification ────────────────────────────────────────────
+ *
+ * Every tool is hashed with the shared digest (`digest.ts`), one hash per
+ * tool and never a hash of the list — a list-level hash would make one added
+ * tool invalidate every verdict on the other twenty. The hashes are looked up
+ * in the local cache; if they are all there and still fresh, nothing leaves
+ * the machine at all, which is the common case after the first session.
+ *
+ * Otherwise the backend is asked, and WHEN it is asked is the whole design:
+ *
+ *   - at `tools/list`, digests only (`verify`). Free, and it answers for
+ *     every tool anybody has ever submitted — which, once the park is
+ *     seeded, is most of them. Nothing is judged here: a catalogue of
+ *     eighty tools of which the agent will call two is not eighty
+ *     judgements.
+ *   - at `tools/call`, the CONTENT of the one tool being called
+ *     (`verifyOne`), and only if nobody has ever submitted that digest.
+ *     Billable, and the only thing that ever leaves the machine beyond a
+ *     hash. A digest is bought at most once (`ToolRecord.submittedAt`) —
+ *     with one exception, at the list: a FLAGGED tool the dictionary no
+ *     longer knows (the judge moved on) is bought again, so a false positive
+ *     corrected upstream can reach the user. See `withdrawn`.
+ *
+ * Arguments and results of a `tools/call` are never part of either. That is
+ * not a policy this file enforces; it is that they are not in scope here at
+ * all, and Phase 4 keeps them local by construction.
+ *
+ * ─── Time ───────────────────────────────────────────────────────────────────
+ *
+ * The verification is allowed to hold the `tools/list` answer for four
+ * seconds. Past that it fails open: the list goes through, the verdict is
+ * `pending`, and the work continues in the background so the NEXT session
+ * has the answer. A cold LLM judgement was measured at up to two minutes on
+ * the previous generation, and there is no version of "the agent waits two
+ * minutes for its tool list" that is acceptable.
+ */
+import { randomUUID } from 'node:crypto';
+import { McpContractError, DigestVersionUnsupportedError, UntrustedApiBaseError, checkMcpServers, getOrgPolicy, verifyMcpTools, } from './api.js';
+import { ADVISORY_ID_PATTERN, MAX_ADVISORY_IDS, isExpired, mergeVerdict, sameStamp, emptyCacheFile, } from './cache.js';
+import { toolDigest } from './digest.js';
+import { hasPublicCoordinate, upstreamCheckInput } from './identity.js';
+import { ORG_BLOCK_CLOCK_SKEW_MS, ORG_BLOCK_STICKY_MAX_MS } from '../report/constants.js';
+import { reportToolName, toReportVerdict } from '../report/coalesce.js';
+import { runPool } from './pool.js';
+import { actionFor, decide, DEFAULT_ORG_POLICY, failClosed, worstAction, worstVerdict, } from './policy.js';
+import { readStoredPolicy, writeStoredPolicy } from './policy-store.js';
+import { PERSISTENT_AFTER_SESSIONS, recordContractError, listContractErrors, } from './contract-errors.js';
+/** How long a verification may hold the `tools/list` answer. */
+export const DEFAULT_VERIFY_TIMEOUT_MS = 4000;
+/**
+ * How long a `tools/call` may wait for the judgement of the one tool it
+ * names. One definition is judged in a second or two; past this the call
+ * goes through as `pending` and the verdict lands for the next call. Kept
+ * under the HTTP timeout of `api.ts`, so the request outlives the wait and
+ * the answer is still written when it arrives.
+ */
+export const DEFAULT_CALL_TIMEOUT_MS = 8000;
+/** Definitions per request when `judgeAll` buys a whole catalogue. */
+export const JUDGE_ALL_BATCH = 50;
+/** Slices of `JUDGE_ALL_BATCH` in flight together during an audit. */
+export const JUDGE_ALL_CONCURRENCY = 3;
+/**
+ * How long a submission mark on a record that never got its verdict counts
+ * as a purchase.
+ *
+ * The mark is written BEFORE the answer, so a process killed mid-submission
+ * leaves `pending` + `submittedAt` behind and nothing ever comes back for it;
+ * `mergeVerdict` then carries the mark across every later free lookup. Past
+ * this the mark is stale — nobody is on it any more — and the tool is bought
+ * again. A judgement takes seconds, so ten minutes is generous.
+ */
+/** `learnedAt` of a policy nobody ever served this machine: the epoch, so any real one is newer. */
+const NEVER_LEARNED = new Date(0).toISOString();
+export const SUBMISSION_MARK_TTL_MS = 10 * 60 * 1000;
+/** The finding kind of a server the organization blocks. */
+export const ORG_BLOCK_KIND = 'blocked by your organization';
+/** Flagged tools that travel with the inventory: the gateway takes 20. */
+const MAX_FLAGGED_TOOLS = 20;
+export class Verifier {
+    options;
+    now;
+    /** Digests seen at the start of the session, for the `list_changed` check. */
+    baseline;
+    changedDuringSession = false;
+    /** The tools of the latest list verification, with their verdicts. */
+    lastListTools;
+    /** Why the latest outcome blocked, for the inventory. */
+    lastBlockedBy;
+    /** Kept so a background completion cannot outlive its usefulness. */
+    pending;
+    /** Judgements in flight, by digest: two calls to one tool buy it once. */
+    inFlight = new Map();
+    /**
+     * The file as last read or written, with the stamp it had then. Served
+     * again while the stamp has not moved — a `tools/call` on a known tool
+     * then costs one `stat`, not a read and a parse. Treated as READ-ONLY by
+     * everything but `mutate`.
+     */
+    loaded;
+    /** Set when a backend call failed or never happened during this verification. */
+    backendAnswered = false;
+    /**
+     * Set when the backend ANSWERED and refused us (400 / 409 / 422).
+     *
+     * Kept apart from `backendAnswered` on purpose: a refusal IS an answer, so
+     * folding the two would make a client whose every request is rejected read
+     * as a healthy one.
+     */
+    contractError;
+    sessionId;
+    /**
+     * The freshest policy known, with the moment it was learned — so a cached
+     * action can be told apart from one the policy has since overtaken.
+     */
+    currentPolicy;
+    /** `GET …/policy` is read at most once per instance. */
+    policyFetched;
+    /** The organization, once resolved — see `BackendAccess.resolveOrganizationId`. */
+    organizationResolved;
+    organizationIdResolved;
+    warnedNoOrganization = false;
+    constructor(options) {
+        this.options = options;
+        this.now = options.now ?? (() => new Date());
+        this.sessionId = options.sessionId ?? randomUUID();
+    }
+    /** The policy this verifier decides under right now (without `learnedAt`). */
+    policy() {
+        const { mode, strictIssuer } = this.knownPolicy();
+        return { mode, strictIssuer };
+    }
+    get organizationId() {
+        return this.options.organizationId ?? this.options.backend?.organizationId ?? this.organizationIdResolved;
+    }
+    /**
+     * Everything a backend call needs, or `null` when there is no organization
+     * to make it as. Resolved once per instance, at the first call that needs
+     * it. Said once, as a count-free line: the reason is in the resolver's
+     * own log line, which names how many organizations there were.
+     */
+    async backendCtx(backend, token) {
+        let organizationId = backend.organizationId ?? this.organizationIdResolved;
+        if (!organizationId && backend.resolveOrganizationId) {
+            this.organizationResolved ??= backend.resolveOrganizationId().catch((error) => {
+                this.options.logger.warn('verify: could not resolve the organization', { error: describe(error) });
+                return null;
+            });
+            organizationId = (await this.organizationResolved) ?? undefined;
+            if (organizationId)
+                this.organizationIdResolved = organizationId;
+        }
+        if (!organizationId) {
+            if (!this.warnedNoOrganization) {
+                this.warnedNoOrganization = true;
+                this.options.logger.warn('verify: no organization selected, nothing is asked — fail-open', {
+                    serverId: this.options.serverId,
+                });
+            }
+            return null;
+        }
+        return { apiBase: backend.apiBase, token, mcpName: backend.mcpName, organizationId };
+    }
+    /**
+     * In order: what a response said during this instance, what an earlier
+     * session left on disk for this organization, the default. The default is
+     * stamped at the epoch so that ANY action filed on a record outranks it —
+     * the default is for nothing ever learned, not for overriding what was.
+     */
+    knownPolicy() {
+        if (this.currentPolicy)
+            return this.currentPolicy;
+        const organizationId = this.organizationId;
+        const stored = organizationId ? readStoredPolicy(organizationId, { env: this.options.env }) : null;
+        this.currentPolicy = stored ?? { ...DEFAULT_ORG_POLICY, learnedAt: NEVER_LEARNED };
+        return this.currentPolicy;
+    }
+    /** A policy the backend just served: remembered, and kept on disk for the degraded session. */
+    notePolicy(policy, now) {
+        if (!policy)
+            return;
+        this.currentPolicy = { mode: policy.mode, strictIssuer: policy.strictIssuer, learnedAt: now.toISOString() };
+        const organizationId = this.organizationId;
+        if (!organizationId)
+            return;
+        try {
+            writeStoredPolicy(organizationId, policy, { env: this.options.env, now });
+        }
+        catch (error) {
+            this.options.logger.warn('verify: could not keep the organization policy on disk', { error: describe(error) });
+        }
+    }
+    /**
+     * Reads `GET …/policy` once per instance, before the first decision that
+     * asks the backend. Every verify/check response carries the policy too;
+     * this is what refreshes it for the decisions only the cache will answer.
+     * Fail-open like the other calls: what is known stands.
+     */
+    ensurePolicy(ctx, opts) {
+        if (this.policyFetched)
+            return this.policyFetched;
+        this.policyFetched = getOrgPolicy(ctx, opts)
+            .then((policy) => this.notePolicy(policy, this.now()))
+            .catch((error) => {
+            if (!this.noteContractError(error, 'policy')) {
+                this.options.logger.warn('verify: could not read the organization policy, using the last known one', {
+                    error: describe(error),
+                });
+            }
+        });
+        return this.policyFetched;
+    }
+    /**
+     * Files a contract refusal and remembers it for this verification.
+     *
+     * Returns `true` when the error WAS a contract refusal, so each call site
+     * can keep its own fail-open path for everything else — a network error, a
+     * timeout or a 5xx still means "could not ask", and still says nothing.
+     */
+    noteContractError(error, route) {
+        // Not a contract error and not an outage either: WE refused to call. Said
+        // as "backend unreachable" it sends the reader to check a network that is
+        // fine — see `UntrustedApiBaseError`.
+        if (error instanceof UntrustedApiBaseError) {
+            this.options.logger.warn('verify: apiBase is not a trusted origin — nothing was sent, fail-open', { serverId: this.options.serverId, route, apiBase: error.apiBase });
+            return true;
+        }
+        if (!(error instanceof McpContractError))
+            return false;
+        this.contractError = error;
+        recordContractError({
+            route,
+            status: error.status,
+            code: error instanceof DigestVersionUnsupportedError ? error.code : undefined,
+            supported: error instanceof DigestVersionUnsupportedError ? error.supported : undefined,
+            sessionId: this.sessionId,
+        }, { env: this.options.env, now: this.now() });
+        this.options.logger.warn('verify: the backend refused our request — contract error', {
+            serverId: this.options.serverId,
+            route,
+            status: error.status,
+            ...(error instanceof DigestVersionUnsupportedError
+                ? { code: error.code, supported: error.supported }
+                : {}),
+        });
+        return true;
+    }
+    /**
+     * Told when the upstream announced its list changed.
+     *
+     * The announcement alone is NOT a finding. `server-everything` — the
+     * reference implementation — registers its conditional tools once it has
+     * seen the client's capabilities and announces the change immediately
+     * after `initialized`, before anybody has listed anything. Treating that as
+     * a rug-pull flagged the reference server on a clean run, and every real
+     * server that does the same would have been flagged with it.
+     *
+     * So the announcement only counts once there is a list to compare against,
+     * and what actually raises the finding is the digest comparison in
+     * `noteBaseline`: the CONTENT changed, not merely that somebody said so.
+     */
+    noteListChanged() {
+        if (this.baseline)
+            this.changedDuringSession = true;
+    }
+    get listChanged() {
+        return this.changedDuringSession;
+    }
+    /** Waits for whatever is still running. Tests only. */
+    async settle() {
+        await this.pending;
+    }
+    async verify(tools) {
+        const outcome = await this.verifyWith(tools, tools.map(safeDigest));
+        this.lastListTools = outcome.tools;
+        return outcome;
+    }
+    /** `verify`, with the digests already computed — once per call, by whoever calls. */
+    async verifyWith(tools, hashes) {
+        const now = this.now();
+        this.backendAnswered = false;
+        this.contractError = undefined;
+        const digests = tools.map((tool, index) => ({ tool, digest: hashes[index] ?? null }));
+        const seen = new Set(digests.map((entry) => entry.digest).filter((digest) => digest !== null));
+        this.noteBaseline(seen);
+        // The advisory lookup only means something for a server with a public
+        // coordinate: a URL, or a pinned package. A local command has none, so
+        // treating its server record as perpetually stale would re-ask the
+        // backend about the same tools every single session.
+        const serverCheckApplies = hasPublicCoordinate(this.options.spec);
+        // What this list changes about the server record is written now and once,
+        // per field — never the whole file after the network call, which would
+        // put back the stale view read here over whatever a `tools/call` bought
+        // in the meantime.
+        const file = this.mutate((file) => {
+            file.server.lastSeen = now.toISOString();
+            // A server with no public coordinate has no advisory list to be absent
+            // from, so "we never asked" is the wrong thing to record: it would make
+            // the aggregate verdict of every locally-spawned server `unknown` for
+            // ever, and `status` would show a park of question marks whose tools
+            // were all verified. What is true is that no advisory applies.
+            if (!serverCheckApplies && file.server.verdict === 'unknown') {
+                file.server.verdict = 'ok';
+                file.server.verdictAt = now.toISOString();
+            }
+            // The whole list as it is right now, not just what we asked about: the
+            // field is what a later session compares against to see the list
+            // change between runs, and half of it would be worse than none.
+            file.server.toolDigests = [...seen];
+        });
+        const unknown = digests.filter((entry) => {
+            if (!entry.digest)
+                return false; // a tool we cannot hash cannot be asked about
+            const record = file.tools[entry.digest];
+            return !record || isExpired(record, now);
+        });
+        const serverStale = serverCheckApplies && isExpired(file.server, now);
+        // A `malicious` on file is never served from the cache alone, even though
+        // it has no TTL. Two reasons, and they pull the same way:
+        //
+        //  - a verdict can be WITHDRAWN. A false positive corrected upstream must
+        //    reach the user, and a verdict that never expires would never let it.
+        //  - it is how the outage is detected at all. Without this call there is
+        //    nothing to fail, so "the backend is down and this server is on the
+        //    local blacklist" — the one case section 0 fails closed on — could
+        //    not be told apart from ordinary operation.
+        //
+        // It costs one round trip per session for the rare server that is on the
+        // list, and nothing at all for every other.
+        const locallyMalicious = file.server.verdict === 'malicious' ||
+            Object.values(file.tools).some((record) => record.verdict === 'malicious');
+        if (unknown.length === 0 && !serverStale && !locallyMalicious) {
+            return this.conclude(file, tools, true, 'cache', hashes);
+        }
+        if (!this.options.backend || !this.options.backend.token) {
+            this.options.logger.info('verify: no backend credential, fail-open', {
+                serverId: this.options.serverId,
+                unknown: unknown.length,
+            });
+            return this.conclude(file, tools, true, 'no-backend', hashes);
+        }
+        // What the backend is actually asked about: what we do not know, plus
+        // what we know to be malicious and want re-confirmed. A tool with a fresh
+        // local verdict is left out — asking again would cost a judgement for an
+        // answer already on disk, and the second call is the billable one.
+        const toAsk = digests.filter((entry) => {
+            if (!entry.digest)
+                return false;
+            const record = file.tools[entry.digest];
+            return !record || isExpired(record, now) || record.verdict === 'malicious';
+        });
+        // The list waits, but only for so long. Whatever is still running when
+        // the deadline passes keeps going and writes the cache for next time.
+        const work = this.ask(toAsk, now).catch((error) => {
+            this.options.logger.warn('verify: backend call failed', { error: describe(error) });
+        });
+        this.pending = work;
+        const finished = await race(work, this.options.timeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS);
+        if (!finished) {
+            this.options.logger.warn('verify: timed out, forwarding the list and finishing in the background', {
+                serverId: this.options.serverId,
+                timeoutMs: this.options.timeoutMs ?? DEFAULT_VERIFY_TIMEOUT_MS,
+            });
+            // `pending` on the unresolved tools, so the decision is made on what we
+            // actually know rather than on an optimistic blank. A view for this
+            // decision only: nothing here is written.
+            const view = overlay(file);
+            for (const entry of unknown) {
+                if (!entry.digest)
+                    continue;
+                view.tools[entry.digest] ??= {
+                    name: entry.tool.name,
+                    verdict: 'pending',
+                    verdictAt: now.toISOString(),
+                };
+            }
+            this.applyContractError(view, digests, now);
+            return this.conclude(view, tools, false, this.backendAnswered ? 'backend' : 'unreachable', hashes);
+        }
+        const refreshed = overlay(this.load(now));
+        this.applyContractError(refreshed, digests, now);
+        return this.conclude(refreshed, tools, false, this.backendAnswered ? 'backend' : 'unreachable', hashes);
+    }
+    /**
+     * The file as it is right now, or an empty one. READ-ONLY: it may be the
+     * instance's loaded copy, served again while the store's stamp has not
+     * moved. A store with no `stat` is read every time, as before.
+     */
+    load(now) {
+        const cache = this.options.cache;
+        const serverId = this.options.serverId;
+        if (!cache.stat)
+            return cache.read(serverId) ?? emptyCacheFile(serverId, now);
+        const stamp = cache.stat(serverId);
+        if (this.loaded && sameStamp(this.loaded.stamp, stamp))
+            return this.loaded.file;
+        const file = cache.read(serverId) ?? emptyCacheFile(serverId, now);
+        this.loaded = { file, stamp };
+        return file;
+    }
+    /**
+     * The ONE way anything is written.
+     *
+     * Loads the file, applies the change, writes. Every caller changes only
+     * its own digests (through `mergeVerdict`) or its own server fields, so two
+     * writers — the list's free lookup finishing late, the call that bought a
+     * verdict in between, `scan` in another process — compose instead of the
+     * last one winning the whole file. Returns `false` from `fn` to write
+     * nothing.
+     */
+    mutate(fn) {
+        const cache = this.options.cache;
+        const file = this.load(this.now());
+        if (fn(file) === false)
+            return file;
+        cache.write(file);
+        // What was just written IS the current content: remember it under the
+        // stamp the store gives it, so the next `load` is a `stat`, not a read.
+        if (cache.stat)
+            this.loaded = { file, stamp: cache.stat(this.options.serverId) };
+        return file;
+    }
+    /** The first list of a session is the baseline every later one is compared to. */
+    noteBaseline(digests) {
+        if (!this.baseline) {
+            this.baseline = digests;
+            return;
+        }
+        for (const digest of digests) {
+            if (!this.baseline.has(digest)) {
+                this.changedDuringSession = true;
+                this.options.logger.warn('verify: the tool list changed during the session', {
+                    serverId: this.options.serverId,
+                });
+                this.baseline = digests;
+                return;
+            }
+        }
+        this.baseline = digests;
+    }
+    /**
+     * The judgement, bought at the call for the one tool being called.
+     *
+     * Nothing leaves the machine when the answer is already here: a fresh
+     * `ok`, a `malicious` (which never expires), a user override, or the mark
+     * that this exact digest was already submitted — whatever the judge made
+     * of it, it is not bought twice; the free lookup at the next list will
+     * pick up a verdict somebody else has bought since.
+     *
+     * Otherwise the definition is submitted, alone, and the call waits up to
+     * `callTimeoutMs` for the verdict. Past that it goes through as `pending`
+     * and the work finishes in the background, exactly like the list does.
+     */
+    async verifyOne(tool) {
+        const now = this.now();
+        const serverId = this.options.serverId;
+        const file = this.load(now);
+        const digest = safeDigest(tool);
+        if (!digest)
+            return this.conclude(file, [tool], true, 'cache', [digest]);
+        // In flight in THIS process comes first: the mark is already on disk, and
+        // read as "answered" it would let this call through as `pending` while
+        // the judge is seconds from an answer that may be MALICIOUS.
+        let work = this.inFlight.get(digest);
+        if (!work && this.isAnswered(file, file.tools[digest], now)) {
+            return this.conclude(file, [tool], true, 'cache', [digest]);
+        }
+        if (!this.options.backend?.token) {
+            this.options.logger.info('verify: no backend credential, the call is not judged', {
+                serverId,
+                tool: tool.name,
+            });
+            return this.conclude(file, [tool], true, 'no-backend', [digest]);
+        }
+        if (!work) {
+            this.mutate((file) => this.markSubmitted(file, [{ tool, digest }], now));
+            this.options.logger.info('verify: submitting the called tool for judgement', {
+                serverId,
+                tool: tool.name,
+            });
+            work = this.submit([{ tool, digest }]).finally(() => this.inFlight.delete(digest));
+            this.inFlight.set(digest, work);
+            const previous = this.pending;
+            this.pending = Promise.allSettled([previous, work]).then(() => undefined);
+        }
+        const finished = await race(work, this.options.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS);
+        if (!finished) {
+            this.options.logger.warn('verify: the judgement did not arrive in time, the call goes through as pending', {
+                serverId,
+                tool: tool.name,
+            });
+        }
+        return this.conclude(this.load(now), [tool], false, this.backendAnswered ? 'backend' : 'unreachable', [digest]);
+    }
+    /**
+     * The billable call: these definitions, and nothing else.
+     *
+     * On failure the marks come OFF. A 401, a 5xx or a dead network means the
+     * judge never saw the definition, and a mark that survived it would turn
+     * one expired token into a permanent exemption for every tool called while
+     * it was expired. The mark is for "the judge was asked", not "we tried".
+     */
+    async submit(entries, timeoutMs) {
+        const backend = this.options.backend;
+        if (!backend?.token || entries.length === 0)
+            return;
+        const opts = timeoutMs ? { ...(backend.options ?? {}), timeoutMs } : (backend.options ?? {});
+        const ctx = await this.backendCtx(backend, backend.token);
+        if (!ctx) {
+            // No organization to ask as: the judge never saw the definition, so the
+            // mark comes off, exactly as after a failed request.
+            this.unmark(entries.map((entry) => entry.digest));
+            return;
+        }
+        await this.ensurePolicy(ctx, opts);
+        const submissions = entries.map(({ tool, digest }) => ({
+            digest,
+            definition: {
+                name: tool.name,
+                title: tool.title,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                outputSchema: tool.outputSchema,
+                annotations: tool.annotations,
+            },
+        }));
+        try {
+            const judged = await verifyMcpTools(ctx, submissions, opts);
+            this.backendAnswered = true;
+            const now = this.now();
+            this.notePolicy(judged.policy, now);
+            const byDigest = new Map(judged.verdicts.map((verdict) => [verdict.digest, verdict]));
+            this.mutate((file) => this.record(file, entries, byDigest, now));
+        }
+        catch (error) {
+            this.unmark(entries.map((entry) => entry.digest));
+            if (!this.noteContractError(error, 'tools/verify')) {
+                this.options.logger.warn('verify: backend unreachable, the call goes through unjudged', {
+                    route: 'tools/verify (definition)',
+                    tools: entries.map((entry) => entry.tool.name),
+                    error: describe(error),
+                });
+            }
+        }
+    }
+    /**
+     * Whether nothing needs to leave the machine for this tool.
+     *
+     * A user override, a fresh verdict, a `malicious` (never expires) — or the
+     * mark that this digest was already bought, which holds for a record that
+     * carries a real verdict whatever it is, and for a `pending` / `unknown`
+     * only while the mark is young: see `SUBMISSION_MARK_TTL_MS`.
+     */
+    isAnswered(file, record, now) {
+        if (file.server.override !== undefined)
+            return true;
+        if (!record)
+            return false;
+        if (!isExpired(record, now))
+            return true;
+        if (record.submittedAt === undefined)
+            return false;
+        if (record.verdict !== 'pending' && record.verdict !== 'unknown')
+            return true;
+        return this.markedRecently(record, now);
+    }
+    /** Whether the "bought" mark on this record is younger than `SUBMISSION_MARK_TTL_MS`. */
+    markedRecently(record, now) {
+        if (record.submittedAt === undefined)
+            return false;
+        const at = Date.parse(record.submittedAt);
+        return !Number.isNaN(at) && now.getTime() - at <= SUBMISSION_MARK_TTL_MS;
+    }
+    /**
+     * Puts the "bought" mark on, BEFORE the answer: a second call while this
+     * one is in flight, and a process that dies mid-way, must both know it.
+     */
+    markSubmitted(file, entries, now) {
+        const at = now.toISOString();
+        for (const { tool, digest } of entries) {
+            file.tools[digest] = mergeVerdict(file.tools[digest], {
+                name: tool.name,
+                verdict: 'pending',
+                verdictAt: at,
+                submittedAt: at,
+            });
+        }
+    }
+    /** Takes the "bought" mark off digests the judge never actually received. */
+    unmark(digests) {
+        this.mutate((file) => {
+            let changed = false;
+            for (const digest of digests) {
+                const record = file.tools[digest];
+                if (record?.submittedAt === undefined)
+                    continue;
+                delete record.submittedAt;
+                if (record.verdict === 'pending')
+                    record.verdict = 'unknown';
+                changed = true;
+            }
+            return changed ? undefined : false;
+        });
+    }
+    /**
+     * The audit: every tool the dictionary does not know, bought now, in one
+     * request. This is `vibedefend scan`, and nothing else calls it — a list
+     * in an agent session must never cost eighty judgements, but a user who
+     * typed `scan` asked exactly that question and is waiting for the answer.
+     *
+     * Runs the free lookup first, so what somebody else already bought is not
+     * bought again, then submits the rest. Waits for the whole thing: the
+     * judge takes a second per tool, and a scan that reported `unknown` for
+     * what it just paid for would be a scan nobody trusts.
+     */
+    async judgeAll(tools, options = {}) {
+        const outcome = await this.judgeAllTools(tools, options);
+        this.lastListTools = outcome.tools;
+        return outcome;
+    }
+    async judgeAllTools(tools, options) {
+        const hashes = tools.map(safeDigest);
+        await this.verifyWith(tools, hashes);
+        await this.settle();
+        const now = this.now();
+        const serverId = this.options.serverId;
+        if (!this.options.backend?.token) {
+            this.options.logger.info('verify: no backend credential, nothing is judged', { serverId });
+            return this.conclude(this.load(now), tools, true, 'no-backend', hashes);
+        }
+        const toBuy = [];
+        const file = this.mutate((file) => {
+            tools.forEach((tool, index) => {
+                const digest = hashes[index];
+                if (!digest)
+                    return;
+                if (!this.isAnswered(file, file.tools[digest], now))
+                    toBuy.push({ tool, digest });
+            });
+            if (toBuy.length === 0)
+                return false;
+            this.markSubmitted(file, toBuy, now);
+        });
+        if (toBuy.length === 0) {
+            return this.conclude(file, tools, true, this.backendAnswered ? 'backend' : 'cache', hashes);
+        }
+        this.options.logger.info('verify: submitting every unknown tool for judgement', {
+            serverId,
+            count: toBuy.length,
+        });
+        // In slices: the backend caps a request, and a slice that fails takes
+        // only its own marks off. A few slices at a time, and ONE deadline for
+        // all of them — `timeoutMs` is the bound on the audit, not on each of
+        // its requests, or a catalogue of five hundred would wait ten times the
+        // documented limit. A slice that starts past the deadline is not sent.
+        const slices = [];
+        for (let index = 0; index < toBuy.length; index += JUDGE_ALL_BATCH) {
+            slices.push(toBuy.slice(index, index + JUDGE_ALL_BATCH));
+        }
+        const deadline = options.timeoutMs === undefined ? undefined : now.getTime() + options.timeoutMs;
+        await runPool(slices, JUDGE_ALL_CONCURRENCY, async (slice) => {
+            const remaining = deadline === undefined ? undefined : deadline - this.now().getTime();
+            if (remaining !== undefined && remaining <= 0) {
+                this.unmark(slice.map((entry) => entry.digest));
+                return;
+            }
+            await this.submit(slice, remaining);
+        });
+        return this.conclude(this.load(now), tools, false, this.backendAnswered ? 'backend' : 'unreachable', hashes);
+    }
+    /**
+     * The two backend calls, plus the advisory lookup on the server itself.
+     *
+     * Written to be safe to abandon: it writes the cache when it finishes,
+     * whether or not anybody is still waiting for it.
+     */
+    async ask(digests, now) {
+        const backend = this.options.backend;
+        if (!backend?.token)
+            return;
+        const opts = backend.options ?? {};
+        const ctx = await this.backendCtx(backend, backend.token);
+        if (!ctx)
+            return;
+        await this.ensurePolicy(ctx, opts);
+        // The server itself: is this URL or package on a list, or blocked by the organization?
+        await this.checkServerWith(ctx, opts, now);
+        const unresolved = digests.filter((entry) => entry.digest !== null);
+        if (unresolved.length === 0)
+            return;
+        // Call 1: digests alone. Free, and it answers for anything anyone has
+        // submitted before.
+        let verdicts = [];
+        try {
+            const answer = await verifyMcpTools(ctx, unresolved.map((entry) => ({ digest: entry.digest })), opts);
+            this.backendAnswered = true;
+            this.notePolicy(answer.policy, now);
+            verdicts = answer.verdicts;
+        }
+        catch (error) {
+            if (!this.noteContractError(error, 'tools/verify')) {
+                this.options.logger.warn('verify: backend unreachable, fail-open', {
+                    route: 'tools/verify (digests)',
+                    error: describe(error),
+                });
+            }
+            return;
+        }
+        // And that is all a list costs. What the backend did not know stays
+        // `unknown` until the agent actually CALLS it — see `verifyOne`.
+        const byDigest = new Map(verdicts.map((verdict) => [verdict.digest, verdict]));
+        const withdrawn = this.withdrawn(unresolved, byDigest, now);
+        this.mutate((file) => this.record(file, unresolved, byDigest, now));
+        if (withdrawn.length === 0)
+            return;
+        // With one exception. The dictionary is keyed by the judge's version: a
+        // judge upgrade empties it for every digest, and the lookup then answers
+        // `known: false` for a tool an EARLIER judge had flagged. `record` kept
+        // that verdict — a withdrawal is not "nothing to report" — but this is
+        // precisely the moment a false positive corrected upstream can reach the
+        // user, and the only one: a flagged tool is never bought at the call
+        // (`isAnswered`). So the definition is bought again, once per mark. An
+        // undecided judge is not a withdrawal: the old verdict stands.
+        this.mutate((file) => this.markSubmitted(file, withdrawn, now));
+        this.options.logger.info('verify: re-judging flagged tools the dictionary no longer knows', {
+            serverId: this.options.serverId,
+            tools: withdrawn.map((entry) => entry.tool.name),
+        });
+        await this.submit(withdrawn);
+    }
+    /**
+     * Asks the backend about the server itself, for the whole life of the proxy
+     * (also called by the periodic check, not only by `ask`).
+     *
+     * `'blocked'` / `'unblocked'` only when the organization block CHANGED;
+     * `'unreachable'` when nothing was learned (no token, no organization, or
+     * any failure), in which case the record is left exactly as it was: a known
+     * block stays, and nothing is ever invented.
+     */
+    async checkServer() {
+        const backend = this.options.backend;
+        if (!backend?.token)
+            return 'unreachable';
+        const ctx = await this.backendCtx(backend, backend.token);
+        if (!ctx)
+            return 'unreachable';
+        return this.checkServerWith(ctx, backend.options ?? {}, this.now());
+    }
+    /**
+     * The organization block in force, or `null`: confirmed no longer than
+     * `ORG_BLOCK_STICKY_MAX_MS` ago, and no more than `ORG_BLOCK_CLOCK_SKEW_MS` ahead.
+     */
+    organizationBlock() {
+        return this.blockOf(this.load(this.now()));
+    }
+    /** The block recorded on `file`, if still in force. Reads nothing. */
+    blockOf(file) {
+        const block = file.server.organizationBlock;
+        if (!block)
+            return null;
+        const age = this.now().getTime() - Date.parse(block.confirmedAt);
+        // A date further in the future than a clock correction explains is no
+        // confirmation: it would outlive the limit.
+        return Number.isNaN(age) || age < -ORG_BLOCK_CLOCK_SKEW_MS || age > ORG_BLOCK_STICKY_MAX_MS
+            ? null
+            : { since: block.confirmedAt };
+    }
+    /**
+     * What the inventory report says about this server, or `null` before any
+     * list was verified when no organization block is known either.
+     */
+    inventorySnapshot() {
+        const now = this.now();
+        const file = this.load(now);
+        const blocked = this.blockOf(file) !== null;
+        if (!blocked && this.lastListTools === undefined && file.server.toolDigests === undefined)
+            return null;
+        const policy = this.knownPolicy();
+        const records = (file.server.toolDigests ?? [])
+            .map((digest) => file.tools[digest])
+            .filter((record) => record !== undefined);
+        const flagged = records.filter((record) => record.verdict === 'malicious' || record.verdict === 'suspicious');
+        const verdict = worstVerdict([file.server.verdict, ...records.map((record) => record.verdict)]);
+        const action = blocked
+            ? 'block'
+            : worstAction([effectiveAction(file.server, policy), ...records.map((record) => effectiveAction(record, policy))]);
+        const flaggedTools = (this.lastListTools ?? [])
+            .filter((tool) => tool.verdict === 'malicious' || tool.verdict === 'suspicious')
+            .sort((a, b) => Number(b.verdict === 'malicious') - Number(a.verdict === 'malicious'))
+            .slice(0, MAX_FLAGGED_TOOLS)
+            .map((tool) => ({ name: reportToolName(tool.name), digest: tool.digest }));
+        return {
+            verdict: toReportVerdict(verdict) ?? 'unverified',
+            action,
+            blockedBy: blocked ? 'organization' : (this.lastBlockedBy ?? null),
+            advisoryIds: [...(file.server.advisoryIds ?? [])],
+            toolCount: file.server.toolDigests?.length ?? 0,
+            flaggedToolCount: flagged.length,
+            flaggedTools,
+        };
+    }
+    /** What a backend call needs (token and organization included), or `null` when there is none to make. */
+    async backendContext() {
+        const backend = this.options.backend;
+        if (!backend?.token)
+            return null;
+        return this.backendCtx(backend, backend.token);
+    }
+    warnedServerKeyRefused = false;
+    async checkServerWith(ctx, opts, now) {
+        const checkInput = upstreamCheckInput(this.options.spec);
+        if (!checkInput)
+            return 'unreachable';
+        try {
+            const answer = await checkMcpServers(ctx, [checkInput], opts);
+            this.backendAnswered = true;
+            this.notePolicy(answer.policy, now);
+            const [result] = answer.results;
+            if (!result)
+                return 'unreachable';
+            const wasBlocked = this.organizationBlock() !== null;
+            const blocked = result.blockedBy === 'organization';
+            this.mutate((file) => {
+                // A server with no public coordinate has no advisory verdict to learn:
+                // what was true before the check stays true.
+                if (hasPublicCoordinate(this.options.spec)) {
+                    file.server.verdict = advisoryVerdict(result.advisories);
+                    file.server.verdictAt = now.toISOString();
+                    file.server.reason = result.advisories[0]?.summary;
+                }
+                // The organization block lives ONLY in `organizationBlock`, which expires
+                // offline. The stored action is what advisories and mode alone give, or
+                // the block would outlive its limit through `effectiveAction`.
+                file.server.action = blocked ? (result.advisories.length > 0 ? (answer.policy?.mode ?? this.policy().mode) : 'allow') : result.action;
+                file.server.advisoryIds = result.advisories
+                    .map((advisory) => advisory.id)
+                    .filter((id) => ADVISORY_ID_PATTERN.test(id))
+                    .slice(0, MAX_ADVISORY_IDS);
+                if (blocked)
+                    file.server.organizationBlock = { confirmedAt: now.toISOString() };
+                else
+                    delete file.server.organizationBlock;
+            });
+            if (blocked === wasBlocked)
+                return 'unchanged';
+            return blocked ? 'blocked' : 'unblocked';
+        }
+        catch (error) {
+            if (error instanceof McpContractError &&
+                error.status === 400 &&
+                checkInput.serverKey !== undefined &&
+                !checkInput.url &&
+                !checkInput.purl) {
+                // A gateway older than the `serverKey` field refuses it. Not a contract
+                // error of the verification: said once, and the record is left alone.
+                if (!this.warnedServerKeyRefused) {
+                    this.warnedServerKeyRefused = true;
+                    this.options.logger.warn('verify: the backend does not take a serverKey check yet, ignored', {
+                        serverId: this.options.serverId,
+                    });
+                }
+                return 'unreachable';
+            }
+            if (!this.noteContractError(error, 'servers/check')) {
+                this.options.logger.warn('verify: backend unreachable, fail-open', {
+                    route: 'servers/check',
+                    error: describe(error),
+                });
+            }
+            return 'unreachable';
+        }
+    }
+    /**
+     * Flagged on file, unknown to the backend now, and not bought within the
+     * mark: a verdict the dictionary has withdrawn since it was given.
+     */
+    withdrawn(entries, verdicts, now) {
+        const file = this.load(now);
+        return entries.filter(({ digest }) => {
+            if (verdicts.get(digest)?.known)
+                return false;
+            const record = file.tools[digest];
+            if (record?.verdict !== 'suspicious' && record?.verdict !== 'malicious')
+                return false;
+            return !this.markedRecently(record, now);
+        });
+    }
+    record(file, entries, verdicts, now) {
+        for (const entry of entries) {
+            const verdict = verdicts.get(entry.digest);
+            const next = {
+                name: entry.tool.name,
+                verdict: verdict ? toolVerdict(verdict) : 'unknown',
+                reason: verdict?.reason || undefined,
+                category: verdict?.category || undefined,
+                severity: verdict?.severity || undefined,
+                verdictAt: now.toISOString(),
+                // The server's decision, filed with the verdict it was made on.
+                ...(verdict ? { action: verdict.action } : {}),
+            };
+            file.tools[entry.digest] = mergeVerdict(file.tools[entry.digest], next);
+        }
+    }
+    /**
+     * Writes `contract-error` where a refusal left a hole.
+     *
+     * ⚠️ It only ever fills `pending` / `unknown` — never a verdict somebody
+     * actually reached. Overwriting a `malicious` would turn breaking the
+     * contract into a way of whitewashing a blacklisted server, and overwriting
+     * an `ok` would report a server as broken when what is broken is us.
+     */
+    applyContractError(file, digests, now) {
+        if (!this.contractError)
+            return;
+        const at = now.toISOString();
+        for (const entry of digests) {
+            if (!entry.digest)
+                continue;
+            const record = file.tools[entry.digest];
+            if (!record) {
+                file.tools[entry.digest] = {
+                    name: entry.tool.name,
+                    verdict: 'contract-error',
+                    verdictAt: at,
+                };
+            }
+            else if (record.verdict === 'pending' || record.verdict === 'unknown') {
+                record.verdict = 'contract-error';
+                record.verdictAt = at;
+            }
+        }
+        if (file.server.verdict === 'unknown' || file.server.verdict === 'pending') {
+            file.server.verdict = 'contract-error';
+            file.server.verdictAt = at;
+        }
+    }
+    /** The record for the refusal we just hit, if it is on file. */
+    currentContractRecord() {
+        const error = this.contractError;
+        if (!error)
+            return undefined;
+        const code = error instanceof DigestVersionUnsupportedError ? error.code : undefined;
+        return listContractErrors(this.options.env).find((record) => record.route === error.route &&
+            record.status === error.status &&
+            (record.code ?? undefined) === code);
+    }
+    conclude(file, tools, fromCache, source, 
+    /** The tools' digests, by index, when the caller already has them. */
+    hashes) {
+        const relevant = [];
+        const verified = [];
+        // A tool with no record at all — never asked about, or asked and not
+        // answered — counts as `unknown` in the aggregate, exactly like a
+        // record that says so. Left out, a list nobody verified would read as
+        // clean on the strength of the server record alone.
+        const actions = [];
+        const policy = this.knownPolicy();
+        for (const [index, tool] of tools.entries()) {
+            const digest = hashes ? (hashes[index] ?? null) : safeDigest(tool);
+            if (!digest)
+                continue;
+            const record = file.tools[digest];
+            if (record)
+                relevant.push(record);
+            actions.push(record ? effectiveAction(record, policy) : 'pending');
+            verified.push({
+                name: tool.name,
+                digest,
+                verdict: record?.verdict ?? 'unknown',
+                ...(record?.reason ? { reason: record.reason } : {}),
+                ...(record?.category ? { category: record.category } : {}),
+                ...(record?.severity ? { severity: record.severity } : {}),
+            });
+        }
+        const verdict = worstVerdict([file.server.verdict, ...verified.map((tool) => tool.verdict)]);
+        // The server's action for each record — fresh from a response, or
+        // recomputed from the verdict under the freshest policy — and the worst
+        // of them for the aggregate, as for the verdict.
+        const action = worstAction([effectiveAction(file.server, policy), ...actions]);
+        const contractRecord = this.currentContractRecord();
+        const contractErrorPersisted = (contractRecord?.sessions ?? 0) >= PERSISTENT_AFTER_SESSIONS;
+        const organizationBlock = this.blockOf(file) !== null;
+        let decision = decide({
+            action,
+            verdict,
+            organizationBlock,
+            override: file.server.override,
+            changedDuringSession: this.changedDuringSession,
+            contractErrorPersisted,
+        });
+        // A server whose cached verdict is still `ok` from a previous session
+        // would otherwise never surface a persistent refusal: the aggregate never
+        // becomes `contract-error`, so `decide` never sees it. The disagreement
+        // is about US, not about this server, so it is raised here rather than by
+        // degrading a verdict somebody actually reached — and never over a real
+        // security finding, which is the more urgent thing to say.
+        if (this.contractError &&
+            contractErrorPersisted &&
+            decision.action === 'pass' &&
+            verdict !== 'malicious' &&
+            verdict !== 'suspicious' &&
+            !file.server.override &&
+            !organizationBlock) {
+            decision = { action: 'alert', rationale: 'contract-error' };
+        }
+        // The one place the proxy fails CLOSED, and the reason the asymmetry
+        // exists: an outage must not turn every server off, and it must not turn
+        // a known-bad one back on either.
+        //
+        // "Degraded" is both shapes of the same thing — a backend that could not
+        // be reached, and no backend configured at all. In either case the only
+        // thing we have is what this machine already knew, and a `malicious` in
+        // there is not something to serve on the strength of a `warn` default
+        // that was chosen for LIVE verdicts a user can act on.
+        // An outage neither opens the door nor hardens the policy. A cached
+        // `malicious` was already decided above under the last known policy of
+        // the organization (warn ⇒ alert, block ⇒ block), and losing the backend
+        // must not change that answer — that is what `policy.json` is for. The
+        // one fail-closed case left is a machine that never learned any policy:
+        // there, the default `warn` was chosen by nobody, so a known-bad server
+        // blocks rather than run on a guess.
+        const degraded = source === 'unreachable' || source === 'no-backend';
+        const policyNeverLearned = policy.learnedAt === NEVER_LEARNED;
+        if (!organizationBlock && degraded && policyNeverLearned && failClosed(verdict, file.server.override)) {
+            this.options.logger.warn('verify: no live verdict, no policy ever learned, and the local cache says malicious — failing closed', { serverId: this.options.serverId, source });
+            decision = { action: 'block', rationale: 'malicious' };
+        }
+        else if (source === 'unreachable') {
+            this.options.logger.info('verify: backend unreachable, fail-open', {
+                serverId: this.options.serverId,
+            });
+        }
+        const flagged = relevant.filter((record) => record.verdict === 'malicious' || record.verdict === 'suspicious');
+        let blockedBy;
+        if (organizationBlock) {
+            blockedBy = 'organization';
+        }
+        else if (decision.action === 'block' && decision.rationale !== 'denied-by-user') {
+            blockedBy =
+                effectiveAction(file.server, policy) === 'block' && file.server.verdict !== 'ok'
+                    ? 'advisory'
+                    : 'verdict';
+        }
+        this.lastBlockedBy = blockedBy;
+        return {
+            decision,
+            action: organizationBlock ? 'block' : action,
+            advisoryIds: [...(file.server.advisoryIds ?? [])],
+            ...(blockedBy ? { blockedBy } : {}),
+            verdict,
+            fromCache,
+            source,
+            policy: { mode: policy.mode, strictIssuer: policy.strictIssuer },
+            tools: verified,
+            finding: {
+                serverName: this.options.serverName,
+                kind: kindOf(decision, verdict),
+                tools: flagged.map((record) => record.name),
+                reason: flagged[0]?.reason ?? file.server.reason,
+                ...(organizationBlock ? { byOrganization: true } : {}),
+            },
+        };
+    }
+}
+/**
+ * The action a record is executed under.
+ *
+ * A FRESH server action always wins over one recomputed here, and a fresh
+ * policy always wins over a stale cached action: the action filed on the
+ * record is used only when it was decided no earlier than the policy was
+ * learned; otherwise the verdict is re-read under the policy of today. That
+ * is how an organization that moves to `block` on Monday blocks a tool
+ * judged malicious the week before, without re-buying its judgement.
+ */
+function effectiveAction(record, policy) {
+    if (record.action && record.verdictAt && record.verdictAt >= policy.learnedAt)
+        return record.action;
+    return actionFor(record.verdict, policy);
+}
+function kindOf(decision, verdict) {
+    if (decision.rationale === 'blocked-by-organization')
+        return ORG_BLOCK_KIND;
+    if (decision.rationale === 'denied-by-user')
+        return 'refused by you (vibedefend deny)';
+    if (decision.rationale === 'changed-mid-session') {
+        return 'its tool list changed during this session';
+    }
+    if (verdict === 'malicious')
+        return 'known malicious';
+    if (verdict === 'suspicious')
+        return 'suspicious';
+    return verdict;
+}
+/** A copy shallow enough to add records to without touching the original. */
+function overlay(file) {
+    const tools = {};
+    for (const [digest, record] of Object.entries(file.tools))
+        tools[digest] = { ...record };
+    return { ...file, server: { ...file.server }, tools };
+}
+/**
+ * A digest, or `null` for a tool we cannot hash.
+ *
+ * A schema nested a hundred levels deep throws by design (`digest.ts`); the
+ * tool is then carried through as un-hashable rather than taking the whole
+ * list down with it.
+ */
+function safeDigest(tool) {
+    try {
+        return toolDigest(tool);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Advisories to a verdict.
+ *
+ * Only a CRITICAL advisory is a blocking fact. The rest — a deprecation, a
+ * low-severity note, an impersonation report nobody has confirmed — is worth
+ * telling the user about and is not worth taking a server away over.
+ */
+export function advisoryVerdict(advisories) {
+    if (advisories.length === 0)
+        return 'ok';
+    return advisories.some((advisory) => advisory.severity.toLowerCase() === 'critical')
+        ? 'malicious'
+        : 'suspicious';
+}
+/**
+ * A backend tool verdict to ours.
+ *
+ * `known: false` is "not verified", never "nothing to report": it maps to
+ * `unknown`, which adds nothing to the agent's view and leaves the tool to be
+ * asked about again.
+ */
+export function toolVerdict(verdict) {
+    if (!verdict.known)
+        return 'unknown';
+    if (verdict.verdict === 'MALICIOUS')
+        return 'malicious';
+    if (verdict.verdict === 'SUSPICIOUS')
+        return 'suspicious';
+    if (verdict.verdict === 'CLEAN')
+        return 'ok';
+    // A verdict this binary does not know is named, not collapsed into `ok`.
+    return 'unknown';
+}
+export { worstVerdict };
+async function race(work, ms) {
+    return Promise.race([
+        work.then(() => true),
+        new Promise((resolve) => {
+            const timer = setTimeout(() => resolve(false), ms);
+            if (typeof timer.unref === 'function')
+                timer.unref();
+        }),
+    ]);
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=verifier.js.map