echelongraph-mcp 2.3.4 → 2.4.0

package/README.md

@@ -22,6 +22,19 @@ API call a tool needs to answer.
 | `get_cve` | Full record for one CVE: CVSS v3 and (when scored) v4, the EchelonGraph score and its confidence, whether EchelonGraph has scored it (`score_assessed`), EPSS, CISA-KEV status and known ransomware use, the GitHub GHSA id, references, and its published, modified and `updated_at` times. |
 | `cve_exposure` | Internet-exposure footprint for a CVE: exposed service count (distinct ip:port, the `exposed_hosts` field) + country/product breakdown, from the KEV-exposure radar. |
 | `exposure_radar` | Aggregate totals across the exposure radars: services running CISA-KEV CVEs; unauthenticated data stores and observability UIs, found through Shodan (LeakIX when Shodan query credits run low) and then confirmed by EchelonGraph's own identified check, which is not a pure read (on Redis it names its client; on ClickHouse its query lands in the server's query log); leaked credentials; shadow AI; and MCP servers found in EchelonGraph's own Certificate Transparency feed, by RFC 9728 verdict, protocol era and transport. Every number is labelled by what it counts, and a field the tool cannot label is left out and named. |
+| `kev_recent` | The CVEs CISA has added to its Known Exploited Vulnerabilities catalog, newest first (`kev_added_date`), from EchelonGraph's copy of the catalog, polled from CISA every 5 minutes: due date, vendor, product, known ransomware use, EchelonGraph's severity, CVSS, EPSS and `eg_kev_tier`, and `our_first_seen_kev`. Filter by date range, ransomware and vendor; page with `limit` and `next_cursor`. Dated by `last_successful_fetch_at`, our last successful fetch of CISA's feed; the filters travel as request headers, never in the URL. |
+| `epss_history` | How one CVE's EPSS score has changed, as EchelonGraph recorded it: one point per recorded change (`series_kind` `change_only`), never a daily series, with the value now and `series_starts_at`, when recording began; before it a missing point means not recorded, not unchanged. |
+| `check_affected` | Whether a product (its NVD CPE product token) or a registry package (`ecosystem` and `package`) at a given version is affected by known CVEs, from the matcher behind echelongraph.io/am-i-affected: `assessed` first (false: not evaluated, with `not_assessed_reason`, and a count of 0 then is not "not affected"), the matching CVEs with `kev_listed`, `ransomware`, `epss_score`, `effective_score` and `score_assessed`, and advisories it cannot decide counted as `undetermined_count`, never as safe. What you look up travels in request headers, never in the URL. |
+| `check_sbom` | A dependency list checked against EchelonGraph's advisory corpus (OSV.dev records), one verdict per component: `affected`, `not_affected`, `undetermined` or `not_assessed`, each with its `not_assessed_reason`. Pass up to 200 purls, or a CycloneDX JSON or SPDX JSON document: the purls are read from it on your machine and only they are sent, in a POST body; the document is not. A deb, apk or rpm purl without a `distro` qualifier naming its release is not assessed (`distro_release_unknown`): EchelonGraph does not guess a release. Only `not_affected` is clean. No ranking, no score. |
+| `cve_intel` | Weakness, public exploit code, affected packages and fixed versions for one CVE, from EchelonGraph's per-CVE enrichment: `cwes`, `exploits` (at most 10, verified first) with `exploits_total`, `exploits_capped`, `exploits_by_kind` and `exploits_by_status`, `affected_packages`, `fixed_versions` and `timeline`. `verified_status` is the label stored with each reference, not a guarantee that the exploit works. An empty `exploits` list is not evidence that no public exploit exists; a section the API could not read is named in `coverage.sections_failed`, never relayed as an empty list. |
+| `get_cwe` | One CWE (weakness class) and the CVEs classified under it: `name` and `description` from the MITRE CWE catalog EchelonGraph embeds, `total`, and one page of 50 `cves`, ordered as `order` states (CISA-KEV-listed first, then EchelonGraph score). A `total` of 0 says that no CVE in EchelonGraph's feed is classified under that CWE, not that none exists. |
+| `vendor_advisories_for_cve` | The vendor-published advisories (Microsoft MSRC, Red Hat, Cisco, Palo Alto Networks, GitHub GHSA and the other feeds EchelonGraph polls) that name one CVE, newest first, at most 20. |
+| `get_vendor_advisory` | One vendor advisory in full: description, severity, `cve_ids` and the subset with a CVE record here (`known_cve_ids`), `affected_products`, `remediation` and `references`. |
+| `search_vendor_advisories` | Search vendor advisories by text (title, description, vendor, advisory ID, products, CVE IDs), vendor, severity and whether they name a CVE. The search text is sent in a request header, never in the URL. |
+
+The three vendor-advisory tools relay `vendor_published_at` (the vendor's date), `our_first_seen_at`
+(when EchelonGraph first recorded the advisory) and `withdrawn` (the vendor rescinded it; the note
+names each one, and the search leaves them out).
 
 Every figure is as fresh as the schedule that refreshes it. The CVE feed is polled from its
 sources on a schedule; each radar refreshes on its own.
@@ -276,6 +289,38 @@ above, each a whole number adding up to the count it divides, is left out whole
 field this version does not know is left out, and named only when its name is shaped like a
 field name.
 
+### How `check_affected` decides
+
+`check_affected` asks the matcher behind
+[echelongraph.io/am-i-affected](https://echelongraph.io/am-i-affected) whether a version is
+affected, by one of two lookup paths:
+
+- **CPE path** — `product` and `version`. `product` is the NVD CPE product token (`openssl`,
+  `nginx`), which can differ from a package name. It returns the CVEs whose NVD CPE match
+  criteria name that product with a version range that includes the version. It matches the
+  token across vendors, so each match carries `cpe_vendor` and `vendor_unknown`: a match with
+  `vendor_unknown` true is real, but its vendor is not verified to be yours.
+- **Registry path** — `ecosystem` (`npm`, `PyPI`, `Maven`, …), `package` and `version`. Each OSV
+  advisory record EchelonGraph holds for the package is decided against the version as
+  affected (a match), not affected (`not_affected_count`) or undetermined.
+
+Read `assessed` before `count`. `assessed` false means the lookup did not evaluate the
+component, and `not_assessed_reason` says why: `product_not_in_cpe_corpus`,
+`package_not_cpe_nameable`, `candidate_load_pending` (with `degraded` true),
+`candidate_window_truncated`, `package_not_in_advisory_corpus` or `no_decidable_advisory`. The
+result's `state` is then `not_assessed`, and its `count` of 0 never means "not affected". An
+advisory whose version range cannot be decided at this version is counted in
+`undetermined_count` (up to 50 listed in `undetermined`) and is never reported as safe. `capped`
+says the match list stopped at its cap, and `candidates_capped` that not every candidate CVE was
+loaded. A failed advisory lookup (`advisory_lookup_failed`) comes back as a failure. Each match
+keeps `kev_listed`, `ransomware`, `epss_score`, `effective_score`, `effective_severity` and
+`score_assessed` as the API sent them.
+
+`product`, `version`, `ecosystem` and `package` travel in the `X-EG-Product`, `X-EG-Version`,
+`X-EG-Ecosystem` and `X-EG-Package` request headers, never in the URL, so request logs and
+trace spans that record URLs do not hold what was looked up. The endpoint reads a CPE vendor
+from the URL only, so this tool takes none.
+
 ## What a result means
 
 Every tool answers in one of two shapes, so a model reading the result cannot mistake an
@@ -323,7 +368,7 @@ declares its shape as an `outputSchema` in `tools/list`, with a title and the an
 | `state` | `measured`, `not_assessed`, `failed` or `invalid_input` (below). |
 | `measured_at` | When the underlying observation was made, as the API states it. `null` when the answer does not say or holds no observation; never the Go zero time. |
 | `method` | How the numbers were produced. `null` on a failure. |
-| `coverage` | What the answer covers, where the tool can say: `in_scope` for `cve_exposure`, the list's own account of its count for `search_cves`, and the radars that answered for `exposure_radar`. |
+| `coverage` | What the answer covers, where the tool can say: `in_scope` for `cve_exposure`, the list's own account of its count for `search_cves`, the radars that answered for `exposure_radar`, and `assessed`, `not_assessed_reason`, the lookup path and the match counts for `check_affected`. |
 | `freshness` | The producing radar's last completed check (`last_run_at`), where the API serves one; `null` where it serves none. |
 | `notes` | The caveats, one sentence each: what the envelope itself needs saying, then the note from the text block. |
 | `data` | On a success only: the same JSON as the first text block. |
@@ -372,14 +417,19 @@ a note says so. Per tool:
   to `mcp_servers.window.to`, over checks made at different times, which is not one observation
   time. Its numbers keep the labels above. `freshness` holds each radar's `last_run_at` where the
   API serves one, for `shadow_ai` also `running`, and for `mcp_servers` also `enabled`.
+- `check_affected` is `measured` only when the answer says `assessed` true, and `not_assessed`
+  when it says false or does not say. Its `measured_at` and `freshness` are `null`: a match answer
+  carries no observation time. Its `coverage` gives `assessed` and `not_assessed_reason` first,
+  then `lookup` (`cpe` or `registry`), `match_layer`, `count`, `capped`, `candidates_capped`,
+  `excluded_count`, `undetermined_count`, `not_affected_count` and `degraded`.
 
 The CVE feed tools' `freshness` is `null`: the feed's answers carry no time at which its
 pollers last completed a poll for the feed as a whole.
 
 A success whose fields do not fit the tool's `outputSchema` (a field of a type the schema does
 not allow) is returned as a failure with `error.kind` `unexpected_shape`, never relayed. A
-field the API adds later is still relayed by the four tools that relay the API's JSON, and
-`exposure_radar` leaves it out and names it, as above.
+field the API adds later is still relayed by every tool that relays the API's JSON as data, and
+`exposure_radar` and `cve_intel`, which relay a selection, leave it out and name what they leave out.
 
 ## Protocol versions
 
@@ -446,6 +496,7 @@ services does EchelonGraph's radar have on record for it?"*
 |---|---|---|
 | `ECHELONGRAPH_API_BASE` | `https://app.echelongraph.io` | Override the API base (self-host / proxy). |
 | `ECHELONGRAPH_API_TIMEOUT_MS` | `15000` | Per-request timeout. A slower answer is reported as a failed lookup, not as empty data. |
+| `ECHELONGRAPH_MCP_UA` | unset | One product token (for example `my-monitor/1.0`) put ahead of this package's own User-Agent, so automated callers such as monitors are told apart from people using the server. A value that is not a single token is ignored. |
 
 ## Develop
 

package/dist/http.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+// The hosted, keyless remote MCP endpoint: https://mcp.echelongraph.io/mcp (#2316).
+//
+// Streamable HTTP on @modelcontextprotocol/server 2.x's createMcpHandler, serving the SAME tool
+// module as the npm package (index.ts's createServer), in both protocol eras: a 2026-07-28
+// client's per-request envelope (server/discover first), and a 2025-era client's initialize,
+// answered statelessly by the SDK's legacy fallback. Nothing is kept between requests: each one
+// gets a fresh server from the factory.
+//
+//   POST /mcp     the MCP endpoint (GET and DELETE are the 2025 session operations; stateless,
+//                 the SDK answers them 405)
+//   OPTIONS /mcp  CORS preflight, for a browser client on an https Origin
+//   GET /health   liveness. Not /healthz: Cloud Run's front end reserves paths ending in "z"
+//                 and answers them itself, so a /healthz would never reach this process.
+//
+// No auth: the endpoint serves only public data (MCP makes authorization optional), and the
+// server's instructions say what it is. The edge rules — Origin policy, per-client limit, body
+// cap, what is logged — are in httpPolicy.ts, each with its reasoning.
+//
+// The API sees every remote user as the client it is, not as this service: each call carries the
+// client's address and a forward token core-backend checks (runtime.ts; core-backend
+// waf/mcpforward.go, #2212). MCP_REQUIRE_FORWARD_TOKEN=1 (set by deploy-all.sh) makes a missing
+// token fatal at start-up, because without it every remote user would share one API budget.
+import http from "node:http";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { forwardToken, markHttpEntrypoint, withClient } from "./runtime.js";
+import { BODY_TOO_LARGE_CODE, DEFAULT_RATE_LIMIT_PER_MIN, FixedWindowLimiter, ORIGIN_REFUSED_CODE, RATE_LIMITED_CODE, bodyFacts, originVerdict, resolveClient, revisionLabel, rpcError, uaFamily, } from "./httpPolicy.js";
+// Must run before index.ts is evaluated: it is how index.ts knows not to start stdio.
+markHttpEntrypoint();
+const { createServer, NAME, VERSION, SHOWN_BASE, TIMEOUT_MS } = await import("./index.js");
+const positiveInt = (v, fallback) => {
+    const n = Number(v);
+    return Number.isInteger(n) && n > 0 ? n : fallback;
+};
+const PORT = (() => {
+    const n = Number(process.env.PORT);
+    return Number.isInteger(n) && n >= 0 && n < 65536 && process.env.PORT !== "" && process.env.PORT !== undefined ? n : 8080;
+})();
+const RATE_LIMIT_PER_MIN = positiveInt(process.env.MCP_RATE_LIMIT_PER_MIN, DEFAULT_RATE_LIMIT_PER_MIN);
+// Tool arguments are a CVE ID or a short search; 64 KiB is far above any real request and far
+// below the SDK's 4 MiB default.
+const MAX_BODY_BYTES = positiveInt(process.env.MCP_MAX_BODY_BYTES, 64 * 1024);
+const MCP_PATH = "/mcp";
+const HEALTH_PATH = "/health";
+// One JSON object per line on stdout: Cloud Logging reads `severity` and `message`.
+function log(severity, message, fields = {}) {
+    process.stdout.write(`${JSON.stringify({ severity, message, ...fields })}\n`);
+}
+if (process.env.MCP_REQUIRE_FORWARD_TOKEN === "1" && !forwardToken()) {
+    log("ERROR", "mcp_remote_refusing_to_start", {
+        reason: "MCP_REQUIRE_FORWARD_TOKEN=1 but ECHELONGRAPH_FORWARD_TOKEN is empty: the API would count every remote user as this one service (#2212)",
+    });
+    process.exit(1);
+}
+const handler = createMcpHandler(createServer, {
+    legacy: "stateless",
+    // responseMode stays the SDK default, "auto": a modern request is answered with one JSON body
+    // unless a handler emits something before its result (none of these tools does). The legacy
+    // leg answers over SSE, as a 2025-era streamable HTTP server does.
+    maxRequestBodySize: MAX_BODY_BYTES,
+    // Names only: an SDK error message can quote what the client sent.
+    onerror: (e) => log("WARNING", "mcp_handler_error", { error_name: e.name }),
+});
+const limiter = new FixedWindowLimiter(RATE_LIMIT_PER_MIN);
+// CORS for a browser client on an https Origin (the Origin policy has already admitted it).
+// A wildcard is safe here because nothing is credentialed: no cookies, no auth.
+const CORS_HEADERS = {
+    "Access-Control-Allow-Origin": "*",
+    "Access-Control-Expose-Headers": "Mcp-Session-Id, MCP-Protocol-Version, Retry-After",
+};
+const PREFLIGHT_HEADERS = {
+    ...CORS_HEADERS,
+    "Access-Control-Allow-Methods": "POST, GET, DELETE, OPTIONS",
+    "Access-Control-Allow-Headers": "Content-Type, Accept, MCP-Protocol-Version, Mcp-Method, Mcp-Name, Mcp-Session-Id, Last-Event-ID",
+    "Access-Control-Max-Age": "600",
+};
+const HOP_BY_HOP = new Set(["host", "connection", "content-length", "transfer-encoding", "keep-alive", "upgrade", "expect"]);
+function send(res, status, body, headers = {}) {
+    res.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store", ...headers });
+    res.end(body);
+}
+// Reads the body up to MAX_BODY_BYTES. Over the cap: "too_large", and the rest is discarded
+// unread (the response closes the connection).
+function readBody(req) {
+    const declared = Number(req.headers["content-length"]);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        req.resume();
+        return Promise.resolve("too_large");
+    }
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let done = false;
+        req.on("data", (chunk) => {
+            if (done)
+                return;
+            size += chunk.length;
+            if (size > MAX_BODY_BYTES) {
+                done = true;
+                resolve("too_large");
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => {
+            if (!done)
+                resolve(Buffer.concat(chunks));
+        });
+        req.on("error", (e) => {
+            if (!done)
+                reject(e);
+        });
+    });
+}
+async function serveMcp(req, res, pathname) {
+    const method = req.method ?? "GET";
+    const origin = req.headers.origin;
+    const verdict = originVerdict(Array.isArray(origin) ? origin.join(", ") : origin);
+    if (!verdict.ok) {
+        send(res, 403, rpcError(ORIGIN_REFUSED_CODE, `Origin refused: ${verdict.reason}. This endpoint serves requests with no Origin or an https Origin.`));
+        return { status: 403, refused: "origin" };
+    }
+    const cors = origin === undefined ? {} : CORS_HEADERS;
+    if (method === "OPTIONS") {
+        res.writeHead(204, PREFLIGHT_HEADERS);
+        res.end();
+        return { status: 204 };
+    }
+    const xff = req.headers["x-forwarded-for"];
+    const client = resolveClient(Array.isArray(xff) ? xff.join(",") : xff, req.socket.remoteAddress);
+    const hit = limiter.hit(client.key);
+    if (!hit.allowed) {
+        send(res, 429, rpcError(RATE_LIMITED_CODE, `Rate limit exceeded: at most ${RATE_LIMIT_PER_MIN} requests per minute per client address. Retry after ${hit.retryAfterSec} s.`, { limit: RATE_LIMIT_PER_MIN, window_seconds: 60, retry_after_seconds: hit.retryAfterSec }), { ...cors, "Retry-After": String(hit.retryAfterSec) });
+        log("WARNING", "mcp_rate_limited", { client: client.key, limit: RATE_LIMIT_PER_MIN });
+        return { status: 429, throttled: true };
+    }
+    let body;
+    if (method === "POST") {
+        const read = await readBody(req);
+        if (read === "too_large") {
+            send(res, 413, rpcError(BODY_TOO_LARGE_CODE, `Request body too large: at most ${MAX_BODY_BYTES} bytes.`), { ...cors, Connection: "close" });
+            return { status: 413, refused: "body_size" };
+        }
+        body = read;
+    }
+    const headers = new Headers();
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (v === undefined || HOP_BY_HOP.has(k))
+            continue;
+        for (const one of Array.isArray(v) ? v : [v])
+            headers.append(k, one);
+    }
+    const abort = new AbortController();
+    res.on("close", () => abort.abort());
+    const request = new Request(`http://localhost${pathname}`, {
+        method,
+        headers,
+        body: body && body.length > 0 ? new Uint8Array(body) : undefined,
+        signal: abort.signal,
+    });
+    const response = await withClient(client.forwardAddress, () => handler.fetch(request));
+    const out = { ...cors };
+    response.headers.forEach((v, k) => {
+        out[k] = v;
+    });
+    res.writeHead(response.status, out);
+    if (response.body) {
+        for await (const chunk of response.body)
+            res.write(chunk);
+    }
+    res.end();
+    return { status: response.status, body };
+}
+const server = http.createServer((req, res) => {
+    const start = process.hrtime.bigint();
+    // The path only: a query string is never read, kept or logged.
+    let pathname = "/";
+    try {
+        pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        pathname = "(unparseable)";
+    }
+    const method = req.method ?? "GET";
+    const finish = (o) => {
+        const facts = o.body ? bodyFacts(o.body) : { rpc_method: "(none)" };
+        log("INFO", "mcp_request", {
+            method,
+            path: pathname === MCP_PATH || pathname === HEALTH_PATH ? pathname : "(other)",
+            status: o.status,
+            duration_ms: Number((process.hrtime.bigint() - start) / 1000000n),
+            ...facts,
+            protocol_version: revisionLabel(req.headers["mcp-protocol-version"]),
+            origin_present: req.headers.origin !== undefined,
+            body_bytes: o.body?.length ?? 0,
+            throttled: o.throttled === true,
+            refused: o.refused ?? "",
+            ua_family: uaFamily(req.headers["user-agent"]),
+        });
+    };
+    if (pathname === HEALTH_PATH) {
+        if (method !== "GET" && method !== "HEAD") {
+            send(res, 405, JSON.stringify({ error: "method not allowed" }), { Allow: "GET, HEAD" });
+            return finish({ status: 405 });
+        }
+        send(res, 200, JSON.stringify({ status: "ok", name: NAME, version: VERSION }));
+        return finish({ status: 200 });
+    }
+    if (pathname !== MCP_PATH) {
+        send(res, 404, JSON.stringify({ error: "not found", mcp_endpoint: MCP_PATH }));
+        return finish({ status: 404 });
+    }
+    serveMcp(req, res, pathname).then(finish, (e) => {
+        log("ERROR", "mcp_request_failed", { error_name: e instanceof Error ? e.name : typeof e });
+        if (!res.headersSent)
+            send(res, 500, rpcError(-32603, "Internal error"));
+        else
+            res.end();
+        finish({ status: 500 });
+    });
+});
+server.listen(PORT, () => {
+    const addr = server.address();
+    log("INFO", "mcp_remote_listening", {
+        port: typeof addr === "object" && addr ? addr.port : PORT,
+        name: NAME,
+        version: VERSION,
+        api_base: SHOWN_BASE,
+        api_timeout_ms: TIMEOUT_MS,
+        forward_token_configured: forwardToken() !== "",
+        rate_limit_per_min: RATE_LIMIT_PER_MIN,
+        max_body_bytes: MAX_BODY_BYTES,
+    });
+});
+const shutdown = () => {
+    server.close();
+    void handler.close();
+};
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);

package/dist/httpPolicy.js

@@ -0,0 +1,244 @@
+// The hosted endpoint's edge rules (#2316), kept apart from the server wiring so each can be
+// tested on its own: who the client is, which Origins are served, the per-client limit, and the
+// JSON-RPC error bodies the edge answers with.
+import { isIP } from "node:net";
+// ── JSON-RPC errors from the edge ──
+//
+// Every refusal at the edge is a JSON-RPC error object, never an HTML page and never a bare
+// status: an MCP client parses the body, and a model shown an HTML error page has nothing to say
+// to its user. id is null because the edge answers before it has read (or trusted) the body.
+export const ORIGIN_REFUSED_CODE = -32000; // the SDK's own code for an Origin refusal (originValidationResponse)
+export const RATE_LIMITED_CODE = -32029; // implementation-defined server error range (-32000..-32099); "429"
+export const BODY_TOO_LARGE_CODE = -32600; // Invalid Request
+export function rpcError(code, message, data) {
+    return JSON.stringify({ jsonrpc: "2.0", id: null, error: { code, message, ...(data ? { data } : {}) } });
+}
+export function originVerdict(origin) {
+    if (origin === undefined)
+        return { ok: true };
+    const o = origin.trim();
+    if (o === "")
+        return { ok: false, reason: "an empty Origin header" };
+    if (o.toLowerCase() === "null")
+        return { ok: false, reason: 'the opaque Origin "null"' };
+    if (/[\s,]/.test(o))
+        return { ok: false, reason: "a malformed Origin header (not a single origin)" };
+    let url;
+    try {
+        url = new URL(o);
+    }
+    catch {
+        return { ok: false, reason: "a malformed Origin header" };
+    }
+    if (url.protocol !== "https:")
+        return { ok: false, reason: "a non-https Origin" };
+    // A serialized origin is scheme://host[:port] and nothing else.
+    if (url.username || url.password || `${url.protocol}//${url.host}` !== o.toLowerCase()) {
+        return { ok: false, reason: "a malformed Origin header (not a bare origin)" };
+    }
+    return { ok: true };
+}
+// The eight 16-bit words of an IPv6 literal that net.isIP has already accepted.
+function expandIPv6(s) {
+    // A dotted IPv4 tail ("::ffff:203.0.113.7") is rewritten as its two words first.
+    const lastColon = s.lastIndexOf(":");
+    const v4 = s.slice(lastColon + 1);
+    if (v4.includes(".")) {
+        const o = v4.split(".").map(Number);
+        if (o.length !== 4 || o.some((n) => !Number.isInteger(n) || n < 0 || n > 255))
+            return undefined;
+        s = `${s.slice(0, lastColon + 1)}${((o[0] << 8) | o[1]).toString(16)}:${((o[2] << 8) | o[3]).toString(16)}`;
+    }
+    const parts = s.split("::");
+    if (parts.length > 2)
+        return undefined;
+    const head = parts[0] ? parts[0].split(":") : [];
+    const rest = parts.length === 2 && parts[1] ? parts[1].split(":") : [];
+    const fill = parts.length === 2 ? 8 - head.length - rest.length : 0;
+    if (fill < 0 || (parts.length === 1 && head.length !== 8))
+        return undefined;
+    const words = [...head, ...Array(fill).fill("0"), ...rest].map((h) => parseInt(h, 16));
+    if (words.length !== 8 || words.some((w) => !Number.isInteger(w) || w < 0 || w > 0xffff))
+        return undefined;
+    return words;
+}
+/** One forwarded hop or socket address, parsed with a forwarded hop's tolerances; undefined if it is not an address. */
+export function parseAddress(raw) {
+    if (!raw)
+        return undefined;
+    let s = raw.trim();
+    if (!s)
+        return undefined;
+    // "[2001:db8::1]:443" / "[2001:db8::1]" → the literal; "203.0.113.7:51234" → the address.
+    const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(s);
+    if (bracketed)
+        s = bracketed[1];
+    else if (/^[\d.]+:\d+$/.test(s))
+        s = s.slice(0, s.lastIndexOf(":"));
+    const zone = s.indexOf("%");
+    if (zone >= 0)
+        s = s.slice(0, zone);
+    const fam = isIP(s);
+    if (fam === 4)
+        return { family: 4, octets: s.split(".").map(Number), text: s };
+    if (fam !== 6)
+        return undefined;
+    const h = expandIPv6(s.toLowerCase());
+    if (!h)
+        return undefined;
+    // IPv4-mapped (::ffff:a.b.c.d) is the IPv4 address.
+    if (h.slice(0, 5).every((w) => w === 0) && h[5] === 0xffff) {
+        const octets = [h[6] >> 8, h[6] & 0xff, h[7] >> 8, h[7] & 0xff];
+        return { family: 4, octets, text: octets.join(".") };
+    }
+    return { family: 6, hextets: h, text: s.toLowerCase() };
+}
+/** Whether a parsed address is one a client on the public internet could have arrived from (core-backend's publicUnicast). */
+export function isPublic(a) {
+    if (a.family === 4) {
+        const [o0, o1] = a.octets;
+        if (o0 === 0 || o0 === 10 || o0 === 127 || o0 >= 224)
+            return false; // this-network, private, loopback, multicast/reserved/broadcast
+        if (o0 === 169 && o1 === 254)
+            return false; // link-local (the platform's front end)
+        if (o0 === 172 && o1 >= 16 && o1 <= 31)
+            return false;
+        if (o0 === 192 && o1 === 168)
+            return false;
+        return true;
+    }
+    const h = a.hextets;
+    if (h.every((w) => w === 0))
+        return false; // ::
+    if (h.slice(0, 7).every((w) => w === 0) && h[7] === 1)
+        return false; // ::1
+    if ((h[0] & 0xffc0) === 0xfe80)
+        return false; // fe80::/10 link-local
+    if ((h[0] & 0xff00) === 0xff00)
+        return false; // ff00::/8 multicast
+    if ((h[0] & 0xfe00) === 0xfc00)
+        return false; // fc00::/7 unique local
+    return true;
+}
+function keyOf(a) {
+    if (a.family === 4)
+        return a.octets.join(".");
+    return `${a.hextets.slice(0, 4).map((w) => w.toString(16)).join(":")}::/64`;
+}
+/** The client of one request: see the section comment. */
+export function resolveClient(xff, socketAddress) {
+    if (xff) {
+        const hops = xff.split(",");
+        for (let i = hops.length - 1; i >= 0; i--) {
+            const a = parseAddress(hops[i]);
+            if (a && isPublic(a))
+                return { forwardAddress: a.text, key: keyOf(a) };
+        }
+    }
+    const peer = parseAddress(socketAddress);
+    if (!peer)
+        return { key: socketAddress || "(unknown)" };
+    return { forwardAddress: isPublic(peer) ? peer.text : undefined, key: isPublic(peer) ? keyOf(peer) : peer.text };
+}
+// ── Per-client limit ──
+//
+// A fixed one-minute window per client key, in this instance's memory. The default is derived
+// from the public API's own per-client ceiling, not invented: core-backend's WAF admits 600
+// requests a minute per client address on the API's base paths (waf.DefaultTierConfigs
+// ["default"], 10 a second), and the costliest tool here, exposure_radar, makes up to five API
+// calls per MCP request. 600 / 5 = 120 MCP requests a minute keeps one client's heaviest use
+// inside the ceiling the API applies to it (core-backend keys this service's calls on the
+// forwarded client, #2212), so a client meets THIS limit — a JSON-RPC error it can read — before
+// the API's. It is not a tier: it grants nothing the API does not already grant one address.
+//
+// Counted per instance: with Cloud Run's max-instances at N, one client spread over every
+// instance could make N times this many requests a minute here; the API's own ceiling, which
+// is counted fleet-wide, still binds behind it.
+export const DEFAULT_RATE_LIMIT_PER_MIN = 120;
+export class FixedWindowLimiter {
+    max;
+    windowMs;
+    now;
+    maxKeys;
+    windows = new Map();
+    constructor(max, windowMs = 60_000, now = Date.now, maxKeys = 50_000) {
+        this.max = max;
+        this.windowMs = windowMs;
+        this.now = now;
+        this.maxKeys = maxKeys;
+    }
+    hit(key) {
+        const t = this.now();
+        let w = this.windows.get(key);
+        if (!w || t - w.start >= this.windowMs) {
+            if (!w && this.windows.size >= this.maxKeys)
+                this.sweep(t);
+            w = { start: t, count: 0 };
+            this.windows.set(key, w);
+        }
+        if (w.count >= this.max) {
+            return { allowed: false, retryAfterSec: Math.max(1, Math.ceil((w.start + this.windowMs - t) / 1000)) };
+        }
+        w.count++;
+        return { allowed: true, remaining: this.max - w.count };
+    }
+    // Drop expired windows; if every key is live (a flood of distinct addresses), drop the oldest
+    // half rather than grow without bound. Forgetting a key early can only admit, never refuse.
+    sweep(t) {
+        for (const [k, w] of this.windows)
+            if (t - w.start >= this.windowMs)
+                this.windows.delete(k);
+        if (this.windows.size < this.maxKeys)
+            return;
+        let drop = Math.floor(this.windows.size / 2);
+        for (const k of this.windows.keys()) {
+            if (drop-- <= 0)
+                break;
+            this.windows.delete(k);
+        }
+    }
+}
+// ── Bounded access-log fields ──
+//
+// The access line carries no body, no query string, no argument and no client address: only
+// values from small closed sets or shapes, so nothing a client types reaches the log (#1983).
+const RPC_METHOD = /^[a-z][a-z/_]{0,39}$/i;
+const TOOL_NAME = /^[a-z][a-z0-9_]{0,39}$/;
+const REVISION = /^\d{4}-\d{2}-\d{2}$/;
+const UA_FAMILY = /^[A-Za-z0-9._-]{1,40}$/;
+/** The JSON-RPC method and, for tools/call, the tool name, shape-checked; never anything else from the body. */
+export function bodyFacts(body) {
+    if (!body || body.length === 0)
+        return { rpc_method: "(none)" };
+    let parsed;
+    try {
+        parsed = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        return { rpc_method: "(unparseable)" };
+    }
+    if (Array.isArray(parsed))
+        return { rpc_method: "(batch)" };
+    if (parsed === null || typeof parsed !== "object")
+        return { rpc_method: "(other)" };
+    const m = parsed.method;
+    if (typeof m !== "string")
+        return { rpc_method: "(response)" };
+    if (!RPC_METHOD.test(m))
+        return { rpc_method: "(other)" };
+    if (m !== "tools/call")
+        return { rpc_method: m };
+    const name = parsed.params?.name;
+    return { rpc_method: m, tool: typeof name === "string" && TOOL_NAME.test(name) ? name : "(other)" };
+}
+export function revisionLabel(v) {
+    if (v === undefined)
+        return "(none)";
+    return REVISION.test(v.trim()) ? v.trim() : "(other)";
+}
+export function uaFamily(ua) {
+    if (!ua)
+        return "(none)";
+    const fam = ua.split(/[/\s]/, 1)[0];
+    return UA_FAMILY.test(fam) ? fam : "(other)";
+}