@thotischner/observability-mcp 3.8.2 → 3.9.0

package/dist/auth/credentials.d.ts

@@ -33,10 +33,21 @@
  *                  # tools list = no restriction). Unlisted keys see
  *                  # every registered tool — back-compat with the
  *                  # pre-Products world. See docs/products.md.
+ *   OMCP_KEY_TOOLS="agent=query_logs|get_service_health;ci=list_services"
+ *                  # optional per-key tool allow-list — same shape as
+ *                  # OMCP_KEY_SOURCES. When set, the credential's /mcp
+ *                  # tools/list (and dispatch) is scoped to exactly these
+ *                  # tool names. Composes with a bound Product by
+ *                  # INTERSECTION (most-restrictive wins). Unlisted keys
+ *                  # see every registered tool — back-compat. This is the
+ *                  # per-credential, source-symmetric counterpart to the
+ *                  # Product bundle: scope one API key to a few tools
+ *                  # without authoring a Product. See docs/products.md
+ *                  # ("Per-credential tool allow-list").
  *
- * Rich role-based access control (tools/services/lookback/read-only, the
- * full governance object) is intentionally NOT here — this is only the
- * authentication + identity + coarse source-scoping primitive.
+ * Rich role-based access control (services/lookback/read-only, the full
+ * governance object) is intentionally NOT here — this is the authentication
+ * + identity + coarse source/tool-scoping primitive.
  */
 export interface Credential {
     name: string;
@@ -58,6 +69,11 @@ export interface Credential {
      *  is filtered to the Product's `tools` allow-list. Resolved against
      *  the credential's tenant so cross-tenant Products don't leak. */
     productId?: string;
+    /** Per-credential tool allow-list (OMCP_KEY_TOOLS). When set, /mcp
+     *  tools/list and dispatch are scoped to these tool names; composes
+     *  with a bound Product by intersection (most-restrictive wins).
+     *  Undefined → no per-credential tool restriction (back-compat). */
+    allowedTools?: string[];
 }
 /** Parse credentials from env. Returns an empty list when unconfigured. */
 export declare function loadCredentials(env?: NodeJS.ProcessEnv): Credential[];

package/dist/auth/credentials.js

@@ -33,10 +33,21 @@
  *                  # tools list = no restriction). Unlisted keys see
  *                  # every registered tool — back-compat with the
  *                  # pre-Products world. See docs/products.md.
+ *   OMCP_KEY_TOOLS="agent=query_logs|get_service_health;ci=list_services"
+ *                  # optional per-key tool allow-list — same shape as
+ *                  # OMCP_KEY_SOURCES. When set, the credential's /mcp
+ *                  # tools/list (and dispatch) is scoped to exactly these
+ *                  # tool names. Composes with a bound Product by
+ *                  # INTERSECTION (most-restrictive wins). Unlisted keys
+ *                  # see every registered tool — back-compat. This is the
+ *                  # per-credential, source-symmetric counterpart to the
+ *                  # Product bundle: scope one API key to a few tools
+ *                  # without authoring a Product. See docs/products.md
+ *                  # ("Per-credential tool allow-list").
  *
- * Rich role-based access control (tools/services/lookback/read-only, the
- * full governance object) is intentionally NOT here — this is only the
- * authentication + identity + coarse source-scoping primitive.
+ * Rich role-based access control (services/lookback/read-only, the full
+ * governance object) is intentionally NOT here — this is the authentication
+ * + identity + coarse source/tool-scoping primitive.
  */
 import { parseKeyTenants } from "../tenancy/context.js";
 function parseKeySources(raw) {
@@ -84,6 +95,8 @@ export function loadCredentials(env = process.env) {
     const rawQueryNames = parseBypassSet(env.OMCP_KEY_RAW_QUERY);
     const keyTenants = parseKeyTenants(env.OMCP_KEY_TENANTS);
     const keyProducts = parseKeyProducts(env.OMCP_KEY_PRODUCTS);
+    // OMCP_KEY_TOOLS shares the OMCP_KEY_SOURCES grammar (`name=a|b;name2=c`).
+    const keyTools = parseKeySources(env.OMCP_KEY_TOOLS);
     const creds = [];
     for (const part of raw.split(",").map((s) => s.trim()).filter(Boolean)) {
         const idx = part.indexOf(":");
@@ -99,6 +112,7 @@ export function loadCredentials(env = process.env) {
             allowRawQuery: rawQueryNames.has(name) || undefined,
             tenant: keyTenants.get(name) || undefined,
             productId: keyProducts.get(name) || undefined,
+            allowedTools: keyTools.get(name),
         });
     }
     return creds;

package/dist/auth/credentials.test.js

@@ -11,7 +11,7 @@ describe("single-tenant auth primitive", () => {
     it("parses name:token and bare token", () => {
         const creds = loadCredentials({ OMCP_API_KEYS: "ci:tok_abc, tok_bare " });
         assert.equal(creds.length, 2);
-        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined, bypassRedaction: undefined, allowRawQuery: undefined, tenant: undefined, productId: undefined });
+        assert.deepEqual(creds[0], { name: "ci", token: "tok_abc", allowedSources: undefined, bypassRedaction: undefined, allowRawQuery: undefined, tenant: undefined, productId: undefined, allowedTools: undefined });
         assert.equal(creds[1].name, "key");
         assert.equal(creds[1].token, "tok_bare");
     });
@@ -23,6 +23,16 @@ describe("single-tenant auth primitive", () => {
         assert.deepEqual(creds[0].allowedSources, ["prom-prod", "loki-prod"]);
         assert.deepEqual(creds[1].allowedSources, ["prom-staging"]);
     });
+    it("parses per-key tool allow-list (OMCP_KEY_TOOLS)", () => {
+        const creds = loadCredentials({
+            OMCP_API_KEYS: "agent:tok1,ci:tok2,full:tok3",
+            OMCP_KEY_TOOLS: "agent=query_logs|get_service_health; ci=list_services",
+        });
+        assert.deepEqual(creds.find((c) => c.name === "agent")?.allowedTools, ["query_logs", "get_service_health"]);
+        assert.deepEqual(creds.find((c) => c.name === "ci")?.allowedTools, ["list_services"]);
+        // Unlisted key → undefined (no restriction, back-compat), not [].
+        assert.equal(creds.find((c) => c.name === "full")?.allowedTools, undefined);
+    });
     it("parses OMCP_KEY_BYPASS_REDACTION → flags only the listed names", () => {
         const creds = loadCredentials({
             OMCP_API_KEYS: "agent:tok1,ci:tok2,unprivileged:tok3",

package/dist/connectors/loader.d.ts

@@ -27,6 +27,7 @@ export declare class PluginLoader {
     private verify;
     private trustRootPath?;
     private trustRoot?;
+    private requireSignature;
     /** Optional HookRegistry — when set, the loader auto-registers
      *  every entry in `manifest.hooks[]` after the plugin loads, and
      *  unregisters them when a same-name plugin replaces it. Hooks
@@ -39,6 +40,7 @@ export declare class PluginLoader {
         verify?: boolean;
         trustRoot?: string;
         hookRegistry?: HookRegistry;
+        requireSignature?: boolean;
     });
     load(): Promise<void>;
     list(): LoadedConnector[];
@@ -49,6 +51,10 @@ export declare class PluginLoader {
     create(name: string): ObservabilityConnector | undefined;
     private loadBuiltins;
     private loadFilesystem;
+    /** A filesystem plugin failed the verification gate. In strict mode
+     *  (PLUGIN_REQUIRE_SIGNATURE) this throws to abort load(); otherwise it
+     *  warns and the caller skips the plugin (fail-closed but non-fatal). */
+    private gateFailure;
     private loadFilesystemPlugin;
     private register;
 }

package/dist/connectors/loader.js

@@ -31,6 +31,15 @@ export class PluginLoader {
     verify;
     trustRootPath;
     trustRoot;
+    // Strict mode (PLUGIN_REQUIRE_SIGNATURE=true). Default OFF. When OFF, a
+    // filesystem plugin that fails the verification gate is silently SKIPPED
+    // (warn + continue) — the server still boots, just without that connector.
+    // When ON, a present-but-unverifiable plugin (missing manifest / missing
+    // or invalid signature / integrity mismatch), or a missing/unloadable trust
+    // root, is a HARD error that aborts load() — so an operator who demands
+    // signed connectors fails to start rather than silently running a reduced
+    // set. Implies verify (you cannot require signatures without verifying).
+    requireSignature;
     /** Optional HookRegistry — when set, the loader auto-registers
      *  every entry in `manifest.hooks[]` after the plugin loads, and
      *  unregisters them when a same-name plugin replaces it. Hooks
@@ -50,11 +59,24 @@ export class PluginLoader {
         this.disabled = new Set([...(opts.disabled ?? []), ...envDisabled]);
         this.verify = opts.verify ?? !/^(0|false|no|off)$/i.test(process.env.VERIFY_PLUGINS ?? "true");
         this.trustRootPath = opts.trustRoot ?? process.env.PLUGIN_TRUST_ROOT;
+        this.requireSignature =
+            opts.requireSignature ?? /^(1|true|yes|on)$/i.test(process.env.PLUGIN_REQUIRE_SIGNATURE ?? "");
+        // Requiring signatures implies verifying them — an operator who sets
+        // PLUGIN_REQUIRE_SIGNATURE=true but left VERIFY_PLUGINS=false meant the
+        // stricter posture; honour it rather than silently no-op.
+        if (this.requireSignature)
+            this.verify = true;
     }
     async load() {
         this.loadBuiltins();
         if (this.verify) {
             if (!this.trustRootPath) {
+                // In strict mode this is a misconfiguration — the operator demanded
+                // signed connectors but gave no way to verify them. Fail hard rather
+                // than silently degrade to builtins-only.
+                if (this.requireSignature) {
+                    throw new PluginVerificationError("PLUGIN_REQUIRE_SIGNATURE is on but PLUGIN_TRUST_ROOT is unset — cannot enforce signatures. Set a trust root or unset PLUGIN_REQUIRE_SIGNATURE.");
+                }
                 console.warn("VERIFY_PLUGINS is on but PLUGIN_TRUST_ROOT is unset — refusing to load any filesystem plugins (fail-closed). Builtins remain available.");
                 return;
             }
@@ -63,6 +85,9 @@ export class PluginLoader {
                 console.log("Plugin verification enabled; trust root loaded from %s", sanitizeForLog(this.trustRootPath));
             }
             catch (err) {
+                if (this.requireSignature) {
+                    throw new PluginVerificationError(`PLUGIN_REQUIRE_SIGNATURE is on but the trust root failed to load (${String(err)}) — cannot enforce signatures.`);
+                }
                 console.warn("VERIFY_PLUGINS is on but trust root failed to load (%s) — refusing to load any filesystem plugins (fail-closed). Builtins remain available.", sanitizeForLog(String(err)));
                 return;
             }
@@ -161,10 +186,23 @@ export class PluginLoader {
                 await this.loadFilesystemPlugin(pluginRoot);
             }
             catch (err) {
+                // In strict mode a verification failure must abort load() rather than
+                // be swallowed as a per-plugin warning — propagate it.
+                if (this.requireSignature && err instanceof PluginVerificationError)
+                    throw err;
                 console.warn("Failed to load plugin %s: %s", sanitizeForLog(entry), sanitizeForLog(String(err)));
             }
         }
     }
+    /** A filesystem plugin failed the verification gate. In strict mode
+     *  (PLUGIN_REQUIRE_SIGNATURE) this throws to abort load(); otherwise it
+     *  warns and the caller skips the plugin (fail-closed but non-fatal). */
+    gateFailure(name, reason) {
+        if (this.requireSignature) {
+            throw new PluginVerificationError(`PLUGIN_REQUIRE_SIGNATURE: plugin ${name} ${reason} — refusing to start.`);
+        }
+        console.warn("VERIFY_PLUGINS: plugin %s %s — skipping (fail-closed)", sanitizeForLog(name), sanitizeForLog(reason));
+    }
     async loadFilesystemPlugin(pluginRoot) {
         const pkgPath = join(pluginRoot, "package.json");
         if (!existsSync(pkgPath))
@@ -180,18 +218,29 @@ export class PluginLoader {
             manifestPath = resolve(pluginRoot, marker.manifest);
             if (existsSync(manifestPath)) {
                 manifestBytes = readFileSync(manifestPath);
-                const raw = JSON.parse(manifestBytes.toString("utf8"));
+                // A present-but-malformed manifest (corrupt JSON / schema-invalid /
+                // name mismatch) is "present but cannot be verified" — under strict
+                // mode gateFailure() aborts startup, so the connector can't silently
+                // go missing; otherwise it warns + skips as before.
+                let raw;
+                try {
+                    raw = JSON.parse(manifestBytes.toString("utf8"));
+                }
+                catch (err) {
+                    this.gateFailure(marker.name, `has unparseable manifest.json (${String(err)})`);
+                    return;
+                }
                 const parsed = manifestSchema.safeParse(raw);
                 if (!parsed.success) {
                     const issues = parsed.error.issues
                         .map((i) => `${i.path.join(".")}: ${i.message}`)
                         .join("; ");
-                    console.warn("Plugin %s has invalid manifest.json — %s; skipping", sanitizeForLog(marker.name), sanitizeForLog(issues));
+                    this.gateFailure(marker.name, `has invalid manifest.json — ${issues}`);
                     return;
                 }
                 manifest = parsed.data;
                 if (manifest.name !== marker.name) {
-                    console.warn("Plugin %s package.json marker name does not match manifest.json (%s); skipping", sanitizeForLog(marker.name), sanitizeForLog(manifest.name));
+                    this.gateFailure(marker.name, `package.json marker name does not match manifest.json (${manifest.name})`);
                     return;
                 }
             }
@@ -208,12 +257,12 @@ export class PluginLoader {
         // against the trust root. Everything is local — airgapped-safe.
         if (this.verify) {
             if (!manifest || !manifestPath || !manifestBytes) {
-                console.warn("VERIFY_PLUGINS: plugin %s has no manifest.json — skipping (fail-closed)", sanitizeForLog(marker.name));
+                this.gateFailure(marker.name, "has no manifest.json");
                 return;
             }
             const sigPath = manifestPath + ".sig";
             if (!existsSync(sigPath)) {
-                console.warn("VERIFY_PLUGINS: plugin %s missing manifest signature %s — skipping (fail-closed)", sanitizeForLog(marker.name), sanitizeForLog(marker.manifest + ".sig"));
+                this.gateFailure(marker.name, `missing manifest signature ${marker.manifest + ".sig"}`);
                 return;
             }
             try {
@@ -222,7 +271,7 @@ export class PluginLoader {
             }
             catch (err) {
                 const detail = err instanceof PluginVerificationError ? err.message : String(err);
-                console.warn("VERIFY_PLUGINS: plugin %s failed verification (%s) — skipping (fail-closed)", sanitizeForLog(marker.name), sanitizeForLog(detail));
+                this.gateFailure(marker.name, `failed verification (${detail})`);
                 return;
             }
             console.log("VERIFY_PLUGINS: plugin %s signature + integrity OK", sanitizeForLog(marker.name));

package/dist/connectors/loader.test.js

@@ -1,12 +1,49 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { generateKeyPairSync, sign as cryptoSign } from "node:crypto";
 import { PluginLoader } from "./loader.js";
+import { PluginVerificationError, sha256Integrity } from "./verify.js";
 function tmp() {
     return mkdtempSync(join(tmpdir(), "loader-default-"));
 }
+const ENTRY_SRC = "export default () => ({});\n";
+/** Write a public-key PEM trust root + return its path and the signing key. */
+function makeTrustRoot() {
+    const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+    const dir = mkdtempSync(join(tmpdir(), "loader-trust-"));
+    const p = join(dir, "trust.pem");
+    writeFileSync(p, publicKey.export({ type: "spki", format: "pem" }));
+    return { path: p, privateKey };
+}
+/** Build a filesystem connector plugin dir under `pluginsDir`.
+ *  opts.manifest=false → no manifest.json; opts.sign omitted → no .sig;
+ *  opts.sign=key → a valid detached signature over the manifest bytes. */
+function makePlugin(pluginsDir, name, opts = {}) {
+    const root = join(pluginsDir, name);
+    mkdirSync(root, { recursive: true });
+    writeFileSync(join(root, "index.js"), ENTRY_SRC);
+    writeFileSync(join(root, "package.json"), JSON.stringify({ main: "index.js", observabilityMcp: { kind: "connector", name, manifest: "manifest.json" } }));
+    if (opts.manifest === false)
+        return;
+    const manifestPath = join(root, "manifest.json");
+    const manifestBytes = opts.rawManifest !== undefined
+        ? Buffer.from(opts.rawManifest)
+        : Buffer.from(JSON.stringify({
+            schemaVersion: 1,
+            name,
+            displayName: name,
+            version: "1.0.0",
+            description: `${name} test connector`,
+            signalTypes: ["metrics"],
+            integrity: opts.integrity ?? sha256Integrity(Buffer.from(ENTRY_SRC)),
+        }));
+    writeFileSync(manifestPath, manifestBytes);
+    if (opts.sign)
+        writeFileSync(manifestPath + ".sig", cryptoSign(null, manifestBytes, opts.sign));
+}
 function withEnv(overrides, fn) {
     const saved = {};
     for (const k of Object.keys(overrides)) {
@@ -87,3 +124,87 @@ test("PluginLoader.load(): builtins carry manifest metadata (description shows i
         assert.equal(c.manifest.name, name);
     }
 });
+// --- PLUGIN_REQUIRE_SIGNATURE (strict load-time enforcement) ---
+test("PluginLoader: PLUGIN_REQUIRE_SIGNATURE=true sets requireSignature and forces verify on", () => {
+    for (const v of ["true", "1", "yes", "On"]) {
+        // Even with VERIFY_PLUGINS=false, requiring signatures implies verifying.
+        withEnv({ PLUGIN_REQUIRE_SIGNATURE: v, VERIFY_PLUGINS: "false" }, () => {
+            const loader = new PluginLoader({ pluginsDir: tmp() });
+            assert.equal(loader["requireSignature"], true, `value ${v} should enable strict mode`);
+            assert.equal(loader["verify"], true, "requireSignature implies verify");
+        });
+    }
+    withEnv({ PLUGIN_REQUIRE_SIGNATURE: undefined }, () => {
+        assert.equal(new PluginLoader({ pluginsDir: tmp() })["requireSignature"], false, "default OFF");
+    });
+});
+test("strict mode: a plugin with no manifest ABORTS load() (hard fail, not skip)", async () => {
+    const dir = tmp();
+    makePlugin(dir, "unsigned-conn", { manifest: false });
+    const trust = makeTrustRoot();
+    const loader = new PluginLoader({ pluginsDir: dir, verify: true, trustRoot: trust.path, requireSignature: true });
+    await assert.rejects(() => loader.load(), PluginVerificationError);
+});
+test("strict mode: a plugin with manifest but missing .sig ABORTS load()", async () => {
+    const dir = tmp();
+    makePlugin(dir, "nosig-conn", { /* manifest yes, sign no */});
+    const trust = makeTrustRoot();
+    const loader = new PluginLoader({ pluginsDir: dir, verify: true, trustRoot: trust.path, requireSignature: true });
+    await assert.rejects(() => loader.load(), PluginVerificationError);
+});
+test("strict mode: missing trust root ABORTS load() (misconfiguration)", async () => {
+    const loader = new PluginLoader({ pluginsDir: tmp(), verify: true, trustRoot: undefined, requireSignature: true });
+    await assert.rejects(() => loader.load(), /PLUGIN_TRUST_ROOT is unset/);
+});
+test("NON-strict (default): the same unverifiable plugin is skipped, builtins still load", async () => {
+    const dir = tmp();
+    makePlugin(dir, "unsigned-conn", { manifest: false });
+    const trust = makeTrustRoot();
+    const loader = new PluginLoader({ pluginsDir: dir, verify: true, trustRoot: trust.path /* requireSignature default false */ });
+    await loader.load(); // must NOT throw
+    const names = loader.supportedTypes();
+    assert.ok(names.includes("prometheus"), "builtins still load");
+    assert.ok(!names.includes("unsigned-conn"), "unverifiable plugin skipped, not registered");
+});
+test("strict mode: a correctly-signed plugin loads without error", async () => {
+    const dir = tmp();
+    const trust = makeTrustRoot();
+    makePlugin(dir, "good-conn", { sign: trust.privateKey });
+    const loader = new PluginLoader({ pluginsDir: dir, verify: true, trustRoot: trust.path, requireSignature: true });
+    await loader.load(); // valid signature + integrity → no throw
+    assert.ok(loader.supportedTypes().includes("good-conn"), "signed plugin registered under strict mode");
+});
+// A present-but-malformed manifest is "present but cannot be verified" — strict
+// mode must hard-fail, not silently drop the connector.
+test("strict mode: unparseable manifest.json ABORTS load()", async () => {
+    const dir = tmp();
+    makePlugin(dir, "corrupt-conn", { rawManifest: "{ this is not valid json" });
+    const trust = makeTrustRoot();
+    const loader = new PluginLoader({ pluginsDir: dir, verify: true, trustRoot: trust.path, requireSignature: true });
+    await assert.rejects(() => loader.load(), PluginVerificationError);
+});
+test("strict mode: schema-invalid manifest.json ABORTS load()", async () => {
+    const dir = tmp();
+    // Missing required fields (displayName/version/signalTypes/...).
+    makePlugin(dir, "badschema-conn", { rawManifest: JSON.stringify({ schemaVersion: 1, name: "badschema-conn" }) });
+    const trust = makeTrustRoot();
+    const loader = new PluginLoader({ pluginsDir: dir, verify: true, trustRoot: trust.path, requireSignature: true });
+    await assert.rejects(() => loader.load(), PluginVerificationError);
+});
+test("strict mode: integrity mismatch ABORTS load() (signed manifest, wrong digest)", async () => {
+    const dir = tmp();
+    const trust = makeTrustRoot();
+    // Validly signed manifest, but its integrity does not match index.js.
+    makePlugin(dir, "tampered-conn", { sign: trust.privateKey, integrity: "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=" });
+    const loader = new PluginLoader({ pluginsDir: dir, verify: true, trustRoot: trust.path, requireSignature: true });
+    await assert.rejects(() => loader.load(), PluginVerificationError);
+});
+test("NON-strict: a malformed manifest is still skipped (not fatal), builtins load", async () => {
+    const dir = tmp();
+    makePlugin(dir, "corrupt-conn", { rawManifest: "{ nope" });
+    const trust = makeTrustRoot();
+    const loader = new PluginLoader({ pluginsDir: dir, verify: true, trustRoot: trust.path /* non-strict */ });
+    await loader.load(); // must NOT throw
+    assert.ok(loader.supportedTypes().includes("prometheus"), "builtins still load");
+    assert.ok(!loader.supportedTypes().includes("corrupt-conn"), "malformed plugin skipped");
+});

package/dist/context.d.ts

@@ -39,6 +39,12 @@ export interface RequestContext {
      *  Anonymous + Product-less credentials leave this unset and see
      *  every registered tool. */
     allowedTools?: string[];
+    /** Per-credential tool allow-list (OMCP_KEY_TOOLS) — a SEPARATE axis from
+     *  the Product `allowedTools`. The registration gate requires a tool to
+     *  pass BOTH (each via allowsTool, undefined = no restriction), so the two
+     *  compose by intersection without overloading the empty-list semantics.
+     *  Unset for anonymous + unscoped credentials. */
+    credentialTools?: string[];
     /** Correlates all tool calls within one transport request/session. */
     correlationId: string;
 }
@@ -59,6 +65,7 @@ export declare function principalContext(principalId: string, allowedSources?: s
     allowRawQuery?: boolean;
     tenant?: string;
     allowedTools?: string[];
+    credentialTools?: string[];
 }): RequestContext;
 /** Context for an authenticated management-plane (browser / OIDC /
  *  basic-auth) request. The session-derived tenant flows into tool
@@ -85,3 +92,14 @@ export declare function sessionContext(session: {
  *  Tool names are compared case-sensitively; the MCP spec is
  *  case-sensitive on `name`. */
 export declare function allowsTool(allowedTools: string[] | undefined, toolName: string): boolean;
+/** Combine two tool allow-lists into the effective (most-restrictive) one.
+ *  Both lists NARROW access, so the result is their intersection:
+ *    - either side undefined → the other side wins (an absent list means
+ *      "no restriction", so it can't tighten the other).
+ *    - both set → only tools present in BOTH survive (so a per-credential
+ *      OMCP_KEY_TOOLS list and a bound Product's `tools` list compose
+ *      without one silently widening the other; an empty intersection
+ *      means the credential can call nothing through that binding).
+ *  Used to fold the per-credential allow-list together with the Product
+ *  allow-list at request entry. */
+export declare function intersectAllowed(a: string[] | undefined, b: string[] | undefined): string[] | undefined;

package/dist/context.js

@@ -27,6 +27,7 @@ export function principalContext(principalId, allowedSources, opts = {}) {
         allowRawQuery: opts.allowRawQuery || undefined,
         tenant: normaliseTenant(opts.tenant),
         allowedTools: opts.allowedTools && opts.allowedTools.length > 0 ? opts.allowedTools : undefined,
+        credentialTools: opts.credentialTools && opts.credentialTools.length > 0 ? opts.credentialTools : undefined,
         correlationId: randomUUID(),
     };
 }
@@ -64,3 +65,21 @@ export function allowsTool(allowedTools, toolName) {
         return true;
     return allowedTools.includes(toolName);
 }
+/** Combine two tool allow-lists into the effective (most-restrictive) one.
+ *  Both lists NARROW access, so the result is their intersection:
+ *    - either side undefined → the other side wins (an absent list means
+ *      "no restriction", so it can't tighten the other).
+ *    - both set → only tools present in BOTH survive (so a per-credential
+ *      OMCP_KEY_TOOLS list and a bound Product's `tools` list compose
+ *      without one silently widening the other; an empty intersection
+ *      means the credential can call nothing through that binding).
+ *  Used to fold the per-credential allow-list together with the Product
+ *  allow-list at request entry. */
+export function intersectAllowed(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    const bSet = new Set(b);
+    return a.filter((t) => bSet.has(t));
+}

package/dist/context.test.js

@@ -1,6 +1,6 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { allowsTool, defaultContext, principalContext } from "./context.js";
+import { allowsTool, intersectAllowed, defaultContext, principalContext } from "./context.js";
 test("allowsTool — undefined allow-list = no Product binding = every tool allowed", () => {
     assert.equal(allowsTool(undefined, "list_sources"), true);
     assert.equal(allowsTool(undefined, "query_logs"), true);
@@ -15,6 +15,44 @@ test("allowsTool — non-empty allow-list gates by exact match", () => {
     assert.equal(allowsTool(allow, "query_logs"), false);
     assert.equal(allowsTool(allow, "get_topology"), false);
 });
+// intersectAllowed folds a per-credential list (OMCP_KEY_TOOLS) with a Product
+// list — most-restrictive wins.
+test("intersectAllowed — either side undefined returns the other (no widening)", () => {
+    assert.equal(intersectAllowed(undefined, undefined), undefined);
+    assert.deepEqual(intersectAllowed(["a", "b"], undefined), ["a", "b"]);
+    assert.deepEqual(intersectAllowed(undefined, ["a", "b"]), ["a", "b"]);
+});
+test("intersectAllowed — both set → intersection only", () => {
+    assert.deepEqual(intersectAllowed(["query_logs", "list_services"], ["query_logs", "get_topology"]), ["query_logs"]);
+    // Disjoint → empty list: the credential can call nothing through that binding.
+    assert.deepEqual(intersectAllowed(["query_logs"], ["get_topology"]), []);
+    // Order follows the first (credential) list.
+    assert.deepEqual(intersectAllowed(["b", "a"], ["a", "b"]), ["b", "a"]);
+});
+// The registration gate ANDs two independent allowsTool axes (Product +
+// per-credential OMCP_KEY_TOOLS). This is what makes disjoint lists deny
+// everything WITHOUT routing through an overloaded empty intersection — an
+// empty `[]` would be read by allowsTool as "allow all", which is why the two
+// axes are kept separate rather than pre-intersected into one list.
+function passesGate(productTools, credTools, name) {
+    return allowsTool(productTools, name) && allowsTool(credTools, name);
+}
+test("two-axis gate — disjoint Product and credential lists deny every tool", () => {
+    // Product allows get_topology; credential allows only query_logs → nothing passes.
+    assert.equal(passesGate(["get_topology"], ["query_logs"], "query_logs"), false);
+    assert.equal(passesGate(["get_topology"], ["query_logs"], "get_topology"), false);
+});
+test("two-axis gate — credential list narrows within an unrestricted Product axis", () => {
+    assert.equal(passesGate(undefined, ["query_logs"], "query_logs"), true);
+    assert.equal(passesGate(undefined, ["query_logs"], "get_topology"), false);
+});
+test("two-axis gate — overlapping lists allow only the overlap", () => {
+    const product = ["query_logs", "get_topology", "list_services"];
+    const cred = ["query_logs", "list_services"];
+    assert.equal(passesGate(product, cred, "query_logs"), true);
+    assert.equal(passesGate(product, cred, "list_services"), true);
+    assert.equal(passesGate(product, cred, "get_topology"), false); // in Product, not in credential
+});
 test("allowsTool — case-sensitive (matches MCP spec)", () => {
     const allow = ["list_sources"];
     assert.equal(allowsTool(allow, "List_Sources"), false);

package/dist/enrich/rdap.d.ts

@@ -6,7 +6,27 @@ export type FetchLike = (url: string, init?: {
     ok: boolean;
     status: number;
     json: () => Promise<unknown>;
+    /** Optional — used to honor `Retry-After` on a throttle response. */
+    headers?: {
+        get(name: string): string | null;
+    };
 }>;
+/** Why a lookup failed in a way that is NOT a stable property of the address —
+ *  retrying later (or in a smaller batch) may succeed. Issue #523. */
+export type RdapTransientReason = "rate_limited" | "timeout" | "upstream_error" | "network_error";
+/** Outcome of a single RDAP lookup. `not_found` is a genuine negative (the
+ *  address is not in any registry / carries no enrichment) and is safe to
+ *  cache; `transient` is an upstream failure (throttle, timeout, 5xx) that must
+ *  NOT be conflated with a negative and is never cached. */
+export type RdapOutcome = {
+    status: "ok";
+    value: IpEnrichment;
+} | {
+    status: "not_found";
+} | {
+    status: "transient";
+    reason: RdapTransientReason;
+};
 export interface RdapResolverOptions {
     /** Bootstrap base; rdap.org redirects to the authoritative RIR. */
     baseUrl?: string;
@@ -18,6 +38,14 @@ export interface RdapResolverOptions {
     fetch?: FetchLike;
     /** Max cache entries (LRU-ish trim). */
     maxCache?: number;
+    /** Retries on a TRANSIENT failure (throttle/timeout/5xx). Default 2. A true
+     *  negative (404 / no-data) is never retried. */
+    maxRetries?: number;
+    /** Base backoff in ms; attempt N waits min(base * 2^N, 5000), unless the
+     *  throttle response carries a usable `Retry-After`. Default 250. */
+    backoffMs?: number;
+    /** Injected sleep (tests pass a no-op to stay fast). Defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
 }
 /** Parse an RDAP IP-network response into our enrichment shape. country +
  *  org/name only; RDAP carries no city or hosting flag. */
@@ -29,12 +57,23 @@ export declare class RdapResolver {
     private readonly timeoutMs;
     private readonly fetch;
     private readonly maxCache;
+    private readonly maxRetries;
+    private readonly backoffMs;
+    private readonly sleep;
     private cache;
     /** Monotonic clock injected for tests; defaults to Date.now via a getter. */
     now: () => number;
     constructor(opts?: RdapResolverOptions);
-    /** Look up one IP via RDAP. Returns null on miss/error (never throws —
-     *  a flaky RIR must not fail the batch). Cached by IP with a TTL. */
+    /** Look up one IP via RDAP. Returns the enrichment on a hit, or null on a
+     *  miss OR a transient failure (never throws). Back-compat shim — callers
+     *  that need to tell a true negative from a throttle should use {@link resolve}. */
     lookup(ip: string): Promise<IpEnrichment | null>;
+    /** Look up one IP via RDAP, distinguishing a genuine negative (`not_found`,
+     *  cached) from a transient upstream failure (`transient`, never cached so a
+     *  later retry can succeed). Bounded retry with backoff on transient. Never
+     *  throws — a flaky RIR must not fail the batch (issue #523). */
+    resolve(ip: string): Promise<RdapOutcome>;
+    /** One RDAP HTTP attempt mapped to an outcome (+ a Retry-After hint). */
+    private attempt;
     private put;
 }

package/dist/enrich/rdap.js

@@ -71,6 +71,9 @@ export class RdapResolver {
     timeoutMs;
     fetch;
     maxCache;
+    maxRetries;
+    backoffMs;
+    sleep;
     cache = new Map();
     /** Monotonic clock injected for tests; defaults to Date.now via a getter. */
     now;
@@ -81,34 +84,74 @@ export class RdapResolver {
         this.timeoutMs = opts.timeoutMs ?? 4000;
         this.fetch = opts.fetch ?? globalThis.fetch;
         this.maxCache = opts.maxCache ?? 10_000;
+        this.maxRetries = opts.maxRetries ?? 2;
+        this.backoffMs = opts.backoffMs ?? 250;
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
         this.now = () => Date.now();
     }
-    /** Look up one IP via RDAP. Returns null on miss/error (never throws —
-     *  a flaky RIR must not fail the batch). Cached by IP with a TTL. */
+    /** Look up one IP via RDAP. Returns the enrichment on a hit, or null on a
+     *  miss OR a transient failure (never throws). Back-compat shim — callers
+     *  that need to tell a true negative from a throttle should use {@link resolve}. */
     async lookup(ip) {
+        const o = await this.resolve(ip);
+        return o.status === "ok" ? o.value : null;
+    }
+    /** Look up one IP via RDAP, distinguishing a genuine negative (`not_found`,
+     *  cached) from a transient upstream failure (`transient`, never cached so a
+     *  later retry can succeed). Bounded retry with backoff on transient. Never
+     *  throws — a flaky RIR must not fail the batch (issue #523). */
+    async resolve(ip) {
         if (ipv4ToInt(ip) === null && ipv6ToBigInt(ip) === null)
-            return null;
+            return { status: "not_found" };
         const cached = this.cache.get(ip);
-        if (cached && cached.expiresAt > this.now())
-            return cached.value;
-        let value = null;
+        if (cached && cached.expiresAt > this.now()) {
+            return cached.value ? { status: "ok", value: cached.value } : { status: "not_found" };
+        }
+        for (let attempt = 0;; attempt++) {
+            const { outcome, retryAfterMs } = await this.attempt(ip);
+            if (outcome.status === "ok") {
+                this.put(ip, { value: outcome.value, expiresAt: this.now() + this.ttlMs });
+                return outcome;
+            }
+            if (outcome.status === "not_found") {
+                this.put(ip, { value: null, expiresAt: this.now() + this.negTtlMs });
+                return outcome;
+            }
+            // transient — retry with backoff, but never cache it as a negative.
+            if (attempt >= this.maxRetries)
+                return outcome;
+            const backoff = retryAfterMs ?? Math.min(this.backoffMs * 2 ** attempt, 5000);
+            await this.sleep(backoff);
+        }
+    }
+    /** One RDAP HTTP attempt mapped to an outcome (+ a Retry-After hint). */
+    async attempt(ip) {
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), this.timeoutMs);
         try {
-            const ac = new AbortController();
-            const timer = setTimeout(() => ac.abort(), this.timeoutMs);
-            try {
-                const res = await this.fetch(`${this.baseUrl}/ip/${encodeURIComponent(ip)}`, { signal: ac.signal });
-                if (res.ok)
-                    value = parseRdapResponse(await res.json());
+            const res = await this.fetch(`${this.baseUrl}/ip/${encodeURIComponent(ip)}`, { signal: ac.signal });
+            if (res.ok) {
+                const parsed = parseRdapResponse(await res.json());
+                // A 2xx with no country/org is a genuine "no enrichment for this IP".
+                return { outcome: parsed ? { status: "ok", value: parsed } : { status: "not_found" } };
             }
-            finally {
-                clearTimeout(timer);
+            // 429/403 are the throttle responses RIRs use; 5xx is upstream trouble —
+            // both are transient. 404 (and other malformed-query 4xx) is a genuine
+            // negative for this address.
+            if (res.status === 429 || res.status === 403) {
+                return { outcome: { status: "transient", reason: "rate_limited" }, retryAfterMs: retryAfter(res) };
             }
+            if (res.status >= 500)
+                return { outcome: { status: "transient", reason: "upstream_error" } };
+            return { outcome: { status: "not_found" } };
         }
         catch {
-            value = null; // network/timeout/parse — treat as a miss
+            // AbortController fired → our own timeout; otherwise a network error.
+            return { outcome: { status: "transient", reason: ac.signal.aborted ? "timeout" : "network_error" } };
+        }
+        finally {
+            clearTimeout(timer);
         }
-        this.put(ip, { value, expiresAt: this.now() + (value ? this.ttlMs : this.negTtlMs) });
-        return value;
     }
     put(ip, entry) {
         if (this.cache.size >= this.maxCache) {
@@ -120,3 +163,14 @@ export class RdapResolver {
         this.cache.set(ip, entry);
     }
 }
+/** Parse a `Retry-After` header (delta-seconds form) into ms, capped at 5s so a
+ *  hostile/huge value can't stall a batch. Ignores the HTTP-date form. */
+function retryAfter(res) {
+    const raw = res.headers?.get?.("retry-after");
+    if (!raw)
+        return undefined;
+    const secs = Number(raw.trim());
+    if (!Number.isFinite(secs) || secs < 0)
+        return undefined;
+    return Math.min(secs * 1000, 5000);
+}

package/dist/enrich/rdap.test.js

@@ -76,3 +76,85 @@ describe("RdapResolver", () => {
         assert.equal(await r.lookup("8.8.8.8"), null);
     });
 });
+// Issue #523: a rate-limit / upstream failure must be distinguishable from a
+// true negative, and must NOT poison the cache as one.
+describe("RdapResolver.resolve — transient vs true negative (#523)", () => {
+    const noSleep = async () => { };
+    it("maps a 200 hit to ok", async () => {
+        const { fetch } = stubFetch(() => ({ ok: true, status: 200, body: RDAP_GOOGLE }));
+        const r = new RdapResolver({ fetch, sleep: noSleep });
+        assert.deepEqual(await r.resolve("8.8.8.8"), { status: "ok", value: { country: "US", org: "Google LLC" } });
+    });
+    it("maps a 404 to a true negative (not_found)", async () => {
+        const { fetch } = stubFetch(() => ({ ok: false, status: 404, body: {} }));
+        const r = new RdapResolver({ fetch, sleep: noSleep });
+        assert.deepEqual(await r.resolve("203.0.113.7"), { status: "not_found" });
+    });
+    it("maps a 200 with no country/org to not_found, not a bogus hit", async () => {
+        const { fetch } = stubFetch(() => ({ ok: true, status: 200, body: { handle: "x" } }));
+        const r = new RdapResolver({ fetch, sleep: noSleep });
+        assert.deepEqual(await r.resolve("203.0.113.8"), { status: "not_found" });
+    });
+    it("maps a 429 to transient:rate_limited after exhausting retries", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: false, status: 429, body: {} }));
+        const r = new RdapResolver({ fetch, sleep: noSleep, maxRetries: 2 });
+        assert.deepEqual(await r.resolve("203.0.113.10"), { status: "transient", reason: "rate_limited" });
+        assert.equal(calls.length, 3, "1 initial + 2 retries");
+    });
+    it("maps a 5xx to transient:upstream_error", async () => {
+        const { fetch } = stubFetch(() => ({ ok: false, status: 503, body: {} }));
+        const r = new RdapResolver({ fetch, sleep: noSleep, maxRetries: 0 });
+        assert.deepEqual(await r.resolve("203.0.113.11"), { status: "transient", reason: "upstream_error" });
+    });
+    it("maps a thrown network error to transient:network_error", async () => {
+        const r = new RdapResolver({ fetch: (async () => { throw new Error("ECONNRESET"); }), sleep: noSleep, maxRetries: 0 });
+        assert.deepEqual(await r.resolve("8.8.8.8"), { status: "transient", reason: "network_error" });
+    });
+    it("does NOT cache a transient failure — a later success resolves", async () => {
+        let mode = "throttle";
+        const calls = [];
+        const fetch = async (url) => {
+            calls.push(url);
+            return mode === "throttle"
+                ? { ok: false, status: 429, json: async () => ({}) }
+                : { ok: true, status: 200, json: async () => RDAP_GOOGLE };
+        };
+        const r = new RdapResolver({ fetch, sleep: noSleep, maxRetries: 0 });
+        assert.deepEqual(await r.resolve("8.8.8.8"), { status: "transient", reason: "rate_limited" });
+        mode = "ok";
+        assert.deepEqual(await r.resolve("8.8.8.8"), { status: "ok", value: { country: "US", org: "Google LLC" } });
+        assert.equal(calls.length, 2, "transient was not cached, so the retry re-fetched");
+    });
+    it("retries a transient then succeeds, returning ok", async () => {
+        let n = 0;
+        const fetch = async () => {
+            n++;
+            return n === 1
+                ? { ok: false, status: 429, json: async () => ({}) }
+                : { ok: true, status: 200, json: async () => RDAP_GOOGLE };
+        };
+        const r = new RdapResolver({ fetch, sleep: noSleep, maxRetries: 2 });
+        assert.deepEqual(await r.resolve("8.8.8.8"), { status: "ok", value: { country: "US", org: "Google LLC" } });
+        assert.equal(n, 2, "succeeded on the first retry");
+    });
+    it("honors a numeric Retry-After for backoff (capped)", async () => {
+        const slept = [];
+        let n = 0;
+        const fetch = async () => {
+            n++;
+            if (n === 1)
+                return { ok: false, status: 429, json: async () => ({}), headers: { get: (h) => (h.toLowerCase() === "retry-after" ? "2" : null) } };
+            return { ok: true, status: 200, json: async () => RDAP_GOOGLE };
+        };
+        const r = new RdapResolver({ fetch, sleep: async (ms) => { slept.push(ms); }, maxRetries: 1 });
+        await r.resolve("8.8.8.8");
+        assert.deepEqual(slept, [2000], "waited the Retry-After delta (2s) before retrying");
+    });
+    it("caches a true negative (no re-fetch within negTtl)", async () => {
+        const { fetch, calls } = stubFetch(() => ({ ok: false, status: 404, body: {} }));
+        const r = new RdapResolver({ fetch, sleep: noSleep });
+        await r.resolve("203.0.113.7");
+        await r.resolve("203.0.113.7");
+        assert.equal(calls.length, 1, "negative cached");
+    });
+});

package/dist/index.js

@@ -9,7 +9,7 @@ import { z } from "zod";
 import { loadConfig, saveConfig, DEFAULT_HEALTH_THRESHOLDS, DEFAULT_SETTINGS } from "./config/loader.js";
 import { ConnectorRegistry, getSupportedTypes } from "./connectors/registry.js";
 import { isTopologyProvider } from "./connectors/interface.js";
-import { defaultContext, principalContext, sessionContext, allowsTool } from "./context.js";
+import { defaultContext, principalContext, sessionContext, allowsTool, intersectAllowed } from "./context.js";
 import { parseKeyTenants, isMultiTenantConfigured } from "./tenancy/context.js";
 import { enforceEntitledAccess, enterpriseGateStatus, enterpriseGateInfo, enterprisePolicyView, enterpriseCatalogView, enterpriseAuditTail, authorizeAdmin, updateRbacPolicy, updateCatalog, inspectEnforceEntitled, featureEntitled, entitledFeatures, } from "./enterprise-gate.js";
 import { loadCredentials, credentialsConfigured, extractToken, resolveToken, } from "./auth/credentials.js";
@@ -382,8 +382,13 @@ async function main() {
         // reaches the caller. When no hooks are registered (the default in
         // the OSS demo) the wrapper is a thin pass-through.
         const registerTool = ((name, ...rest) => {
-            if (!allowsTool(ctx.allowedTools, name))
+            // Two independent allow-list axes must BOTH pass: the Product binding
+            // (ctx.allowedTools, OMCP_KEY_PRODUCTS) and the per-credential list
+            // (ctx.credentialTools, OMCP_KEY_TOOLS). Either undefined = no restriction
+            // on that axis; disjoint non-empty lists therefore deny every tool.
+            if (!allowsTool(ctx.allowedTools, name) || !allowsTool(ctx.credentialTools, name)) {
                 return undefined;
+            }
             if (rest.length > 0 && typeof rest[rest.length - 1] === "function") {
                 const originalHandler = rest[rest.length - 1];
                 const wrappedHandler = wrapToolHandler(hookRegistry, { principal: ctx.principalId, tenant: ctx.tenant || "default", target: name }, originalHandler);
@@ -794,6 +799,7 @@ async function main() {
             "Resolve a batch of IPv4 or IPv6 addresses to geo (country/city), ASN/org, and a hosting/proxy flag.",
             "When to use: answering 'where are these visitors from?' or 'which of these IPs are bots / datacenter / VPN exit nodes?' over access logs, without an out-of-band geo-API call per IP. Both IPv4 and IPv6 clients are resolved — don't pre-filter v6 out.",
             "Behavior: read-only. By default looks each IP up in a LOCAL offline dataset the operator configured (OMCP_IP_ENRICH_FILE) with NO external network call — safe in air-gapped deployments. Optionally, if the operator enabled OMCP_IP_ENRICH_RDAP, IPs the dataset doesn't cover fall back to an online RDAP query (country/org only) and the result carries via:'rdap'; the offline dataset is always preferred. Returns one row per input IP with found=true/false plus any known fields. If neither is configured it returns a clear notice explaining how to enable them.",
+            "RDAP rate-limits: a row with found=false AND transient:true (error names the cause, e.g. 'rate_limited') is NOT a confirmed negative — the registry throttled or failed the lookup, so the IP may resolve on a later retry or in a smaller batch. Such rows are counted in summary.transient (separate from summary.unmatched) and a top-level `note` is added. Don't treat transient rows as 'unknown/suspicious'; retry them (results are cached, so repeats are cheap).",
             "Related: pull the IPs from `query_logs` (use `labels`/`aggregate` to find the IPs of interest first).",
         ].join(" "), {
             ips: z
@@ -1848,6 +1854,7 @@ async function main() {
                 productId: c.productId,
                 bypassRedaction: !!c.bypassRedaction,
                 allowedSources: c.allowedSources,
+                allowedTools: c.allowedTools,
             });
         }
         // OIDC groups → role mappings.
@@ -3669,6 +3676,11 @@ async function main() {
             allowRawQuery: cred.allowRawQuery,
             tenant: cred.tenant,
             allowedTools,
+            // Per-credential tool allow-list (OMCP_KEY_TOOLS) — a SEPARATE axis from
+            // the Product one. The registration gate requires a tool to pass BOTH,
+            // so disjoint lists deny everything without overloading the empty-list
+            // "allow all" semantics allowsTool uses for the Product axis.
+            credentialTools: cred.allowedTools,
         });
     }
     app.post("/mcp", async (req, res) => {
@@ -3740,14 +3752,6 @@ async function main() {
     // registerTool gate, so the surface a /mcp/v/<slug> client sees is
     // strictly product.tools (intersected with any pre-existing
     // allowedTools the credential already carries).
-    function intersectAllowed(a, b) {
-        if (!a)
-            return b;
-        if (!b)
-            return a;
-        const bSet = new Set(b);
-        return a.filter((t) => bSet.has(t));
-    }
     async function resolveVirtualProduct(req, res, baseCtx) {
         const slug = req.params.slug;
         if (!slug || typeof slug !== "string") {
@@ -3910,6 +3914,7 @@ async function main() {
                 allowRawQuery: cred.allowRawQuery,
                 tenant: cred.tenant,
                 allowedTools,
+                credentialTools: cred.allowedTools,
             }),
             selectedSubprotocol,
         };

package/dist/tools/enrich-ips.d.ts

@@ -19,6 +19,12 @@ export interface IpEnrichmentResult {
     /** Which backend produced the hit — "dataset" (offline CSV) or "rdap"
      *  (online fallback). Absent when not found. */
     via?: "dataset" | "rdap";
+    /** True when `found:false` is NOT a confirmed negative but an RDAP upstream
+     *  failure (throttle/timeout/5xx) — the address may resolve on a later retry.
+     *  Issue #523: never conflate a rate-limit with "not in any registry". */
+    transient?: boolean;
+    /** Machine-readable reason when `transient` — e.g. "rate_limited". */
+    error?: string;
 }
 export declare function enrichIpsHandler(dataset: IpEnrichmentDataset | null, args: EnrichIpsArgs, _ctx?: RequestContext, rdap?: RdapResolver | null): Promise<{
     content: {

package/dist/tools/enrich-ips.js

@@ -38,6 +38,7 @@ rdap) {
     let invalid = 0;
     let matched = 0;
     let viaRdap = 0;
+    let transient = 0;
     for (const ip of ips) {
         if (typeof ip !== "string" || !isValidIp(ip)) {
             invalid++;
@@ -53,16 +54,26 @@ rdap) {
             continue;
         }
         if (rdap) {
-            const r = await rdap.lookup(ip);
-            if (r) {
+            const r = await rdap.resolve(ip);
+            if (r.status === "ok") {
                 matched++;
                 viaRdap++;
-                results.push({ ip, found: true, via: "rdap", ...r });
+                results.push({ ip, found: true, via: "rdap", ...r.value });
+                continue;
+            }
+            if (r.status === "transient") {
+                // NOT a confirmed negative — an RDAP throttle/timeout/5xx. Mark it so an
+                // agent doesn't treat the IP as "unknown" and can retry later (#523).
+                transient++;
+                results.push({ ip, found: false, transient: true, error: r.reason });
                 continue;
             }
         }
         results.push({ ip, found: false });
     }
+    // unmatched = confirmed negatives only; transient failures are reported
+    // separately so the all-clear can't silently absorb a wall of rate-limits.
+    const unmatched = ips.length - matched - invalid - transient;
     return {
         content: [
             {
@@ -72,12 +83,19 @@ rdap) {
                     summary: {
                         total: ips.length,
                         matched,
-                        unmatched: ips.length - matched - invalid,
+                        unmatched,
                         invalid,
-                        ...(rdap ? { viaRdap } : {}),
+                        ...(rdap ? { viaRdap, transient } : {}),
                     },
                     datasetSize: dataset?.size ?? 0,
                     ...(rdap ? { rdapEnabled: true } : {}),
+                    ...(transient > 0
+                        ? {
+                            note: `${transient} RDAP lookup(s) failed transiently (e.g. rate-limited by the ` +
+                                `registry) and are marked transient:true — these are NOT confirmed negatives. ` +
+                                `Retry them later or in a smaller batch; results are cached so repeats are cheap.`,
+                        }
+                        : {}),
                 }, null, 2),
             },
         ],

package/dist/tools/enrich-ips.test.js

@@ -48,13 +48,21 @@ describe("enrichIpsHandler (R6, issue #415 Gap B)", () => {
     });
 });
 describe("enrichIpsHandler — optional RDAP fallback (issue #477)", () => {
-    // Minimal RdapResolver stub: returns a fixed hit for one IP, null otherwise,
-    // and records which IPs it was asked about (to prove CSV-first).
-    function rdapStub(hit) {
+    // Minimal RdapResolver stub: returns a fixed hit for one IP, a true negative
+    // otherwise, and records which IPs it was asked about (to prove CSV-first).
+    // `transient` IPs resolve to a transient outcome (e.g. rate-limited) — #523.
+    function rdapStub(hit, transient = {}) {
         const asked = [];
         return {
             asked,
-            resolver: { lookup: async (ip) => { asked.push(ip); return hit[ip] ?? null; } },
+            resolver: {
+                resolve: async (ip) => {
+                    asked.push(ip);
+                    if (transient[ip])
+                        return { status: "transient", reason: transient[ip] };
+                    return hit[ip] ? { status: "ok", value: hit[ip] } : { status: "not_found" };
+                },
+            },
         };
     }
     it("with no dataset but RDAP enabled → not 'not configured'; resolves via RDAP", async () => {
@@ -90,4 +98,29 @@ describe("enrichIpsHandler — optional RDAP fallback (issue #477)", () => {
         assert.match(out.error, /not configured/i);
         assert.match(out.error, /OMCP_IP_ENRICH_RDAP/);
     });
+    // Issue #523: a rate-limited lookup must NOT masquerade as a confirmed negative.
+    it("marks a rate-limited lookup transient (not a confirmed negative)", async () => {
+        const { resolver } = rdapStub({ "8.8.8.8": { country: "US", org: "Google LLC" } }, { "203.0.113.10": "rate_limited" });
+        const out = parse(await enrichIpsHandler(null, { ips: ["8.8.8.8", "203.0.113.10"] }, undefined, resolver));
+        const hit = out.results.find((r) => r.ip === "8.8.8.8");
+        assert.equal(hit.found, true);
+        const throttled = out.results.find((r) => r.ip === "203.0.113.10");
+        assert.equal(throttled.found, false);
+        assert.equal(throttled.transient, true);
+        assert.equal(throttled.error, "rate_limited");
+        // The throttled IP is counted as transient, NOT folded into `unmatched`.
+        assert.equal(out.summary.matched, 1);
+        assert.equal(out.summary.transient, 1);
+        assert.equal(out.summary.unmatched, 0);
+        assert.match(out.note, /NOT confirmed negatives/i);
+    });
+    it("a genuine miss stays a clean negative — no transient marker, no note", async () => {
+        const { resolver } = rdapStub({ "8.8.8.8": { country: "US", org: "Google LLC" } });
+        const out = parse(await enrichIpsHandler(null, { ips: ["8.8.8.8", "203.0.113.9"] }, undefined, resolver));
+        const miss = out.results.find((r) => r.ip === "203.0.113.9");
+        assert.equal(miss.found, false);
+        assert.equal(miss.transient, undefined);
+        assert.equal(out.summary.transient, 0);
+        assert.equal(out.note, undefined);
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thotischner/observability-mcp",
-  "version": "3.8.2",
+  "version": "3.9.0",
   "description": "Unified observability gateway for AI agents — one MCP server for Prometheus, Loki, and any backend",
   "type": "module",
   "license": "Apache-2.0",