@aimarket/warden 0.0.1 → 0.4.0

package/dist/threat-feed.d.ts

@@ -0,0 +1,138 @@
+import type { McpServerRef, ThreatRecord, ToolDef, WardenFinding, WardenGate, WardenGateInput, WardenGateResult, WardenLogger } from "./types.js";
+/**
+ * Threat-intel feed for known-bad MCP servers/tools.
+ *
+ * Reputation answers "is this server trusted?"; the threat feed answers "is this
+ * server a *known* bad actor?". It ships with a small built-in deny-list of
+ * patterns (credential-stealing, destructive commands, crypto-drainer keywords,
+ * typosquat-style names) and can be topped up from a signed remote feed.
+ *
+ * **In the shipping configuration there is no remote feed.** `warden.threatFeedUrl`
+ * and `warden.feedPublicKey` default to `undefined` (see `src/config.ts`), so
+ * unless an operator sets both, this gate *is* the {@link BUILTIN} list — a fixed
+ * floor of 11 patterns, not live intel. That is a deliberate default: ARGUS ships
+ * no feed endpoint and no publisher key, because a feed URL baked into the binary
+ * is a single point every install would have to trust.
+ *
+ * When a feed *is* configured, three properties are enforced fail-closed — any of
+ * them failing keeps the built-in floor and changes nothing else:
+ *
+ * - **Authenticity.** An Ed25519 signature over the canonical form of
+ *   `{records, timestamp}`, verified with a pre-configured public key. Unsigned
+ *   feeds are refused outright.
+ * - **Freshness.** The signed `timestamp` must be within {@link
+ *   DEFAULT_FEED_MAX_AGE_MS} (configurable). Without this, whoever serves the feed
+ *   URL can replay a months-old snapshot forever and silently erase every threat
+ *   record added since — a signature says *who* wrote a document, never *when you
+ *   were handed it*.
+ * - **Determinism.** The signed bytes are RFC 8785 canonical (§4 of
+ *   `awr/SPEC.md`), so publisher and verifier agree on them regardless of the key
+ *   order the wire used.
+ *
+ * The remote fetch degrades silently otherwise: a feed outage must never weaken
+ * the built-in floor or crash a connection check.
+ */
+/**
+ * Default freshness window for a signed remote feed: 24 h.
+ *
+ * Rationale for a *default* rather than an opt-in: a feed whose age is unchecked
+ * is indistinguishable from a feed that is being replayed. An operator publishing
+ * on a slower cadence should raise `warden.feedMaxAgeMs`, not disable the check.
+ *
+ * (Note the deliberate difference from AWR documents, where age is *policy, not
+ * validity* — SPEC §11.3. A work receipt from two years ago is still a true
+ * statement about the past; a deny-list from two years ago is a false statement
+ * about the present.)
+ */
+export declare const DEFAULT_FEED_MAX_AGE_MS: number;
+/**
+ * Tolerance for a feed timestamp in the future — publisher/host clock skew.
+ * Beyond it the feed is refused: a future-dated snapshot would otherwise pass the
+ * freshness check for as long as the date it claims.
+ */
+export declare const FEED_CLOCK_SKEW_MS: number;
+export interface ThreatFeedOptions {
+    /** Ed25519 public key (hex-encoded SPKI DER) of the feed publisher. */
+    feedPublicKey?: string;
+    /**
+     * Maximum age of a signed feed's `timestamp`. Defaults to
+     * {@link DEFAULT_FEED_MAX_AGE_MS}; a non-finite or non-positive value falls back
+     * to the default rather than disabling the check.
+     */
+    maxAgeMs?: number;
+    log?: WardenLogger;
+    /** Clock source. Injectable so freshness is testable without waiting a day. */
+    now?: () => number;
+}
+export declare class ThreatFeed {
+    private records;
+    private compiled;
+    private feedPublicKey?;
+    private readonly maxAgeMs;
+    private readonly now;
+    private readonly log?;
+    constructor(opts?: ThreatFeedOptions);
+    /** The built-in floor, always present regardless of remote load state. */
+    get builtins(): ThreatRecord[];
+    all(): ThreatRecord[];
+    /** Single place where the record set changes, so the match cache cannot go stale. */
+    private setRecords;
+    /**
+     * Fetch and verify a signed remote threat feed.
+     *
+     * Feed format: `{ records: ThreatRecord[], timestamp: number, signature: string }`
+     * where `timestamp` is **epoch milliseconds** and `signature` is a hex-encoded
+     * Ed25519 signature over the RFC 8785 (JCS) canonical form of
+     * `{records, timestamp}` — see {@link canonicalize}. A publisher that signs
+     * `JSON.stringify` output instead will not verify here, and that is the point:
+     * `JSON.stringify` bytes depend on the key order of whatever object the
+     * publisher happened to build, so the same logical feed could be signed and then
+     * fail to verify.
+     *
+     * - Without a configured `feedPublicKey`, remote feeds are refused.
+     * - Signature failure logs a warning and preserves the built-in floor.
+     * - A missing/non-integer `timestamp`, a snapshot older than `maxAgeMs`, or one
+     *   dated further ahead than {@link FEED_CLOCK_SKEW_MS} is refused — a replayed
+     *   old snapshot would otherwise erase every newer threat record.
+     * - Network/parse errors degrade silently — built-ins remain.
+     */
+    load(feedUrl?: string): Promise<void>;
+    /**
+     * Match a server — and its advertised tool definitions — against every record.
+     * One finding per matched record per surface.
+     *
+     * Two surfaces, because a threat record about an MCP server is not only a
+     * statement about the config the user wrote:
+     *
+     * - **Server identity** (`id`, `name`, `url`, `command`, `args`): the local
+     *   config. This is the only surface a pattern matches when its `scope` is
+     *   `"server"`.
+     * - **Tool definitions** (`name`, `description`, `inputSchema`): attacker-
+     *   controlled text the *server* chose, which is where a poisoned tool actually
+     *   lives. Matched for records scoped `"any"` (the default) or `"tool"`.
+     *
+     * Findings from the tool surface carry `tool`, so `Warden.partitionTools()` can
+     * quarantine the one tool instead of attributing the match to the whole
+     * connection. The connection is still blocked when the severity reaches
+     * `policy.blockAtSeverity` — per-tool attribution narrows the *blame*, it does
+     * not soften the policy.
+     */
+    match(server: McpServerRef, tools?: ToolDef[]): WardenFinding[];
+}
+/**
+ * Gate wrapper around a ThreatFeed. Any match is disqualifying for the score; a
+ * critical-severity match against the *server's identity* short-circuits the chain
+ * (fatal), because nothing about that connection is salvageable.
+ *
+ * A critical match against a single tool definition is deliberately not fatal: it
+ * still scores 0 and still blocks under the default `blockAtSeverity`, but letting
+ * the remaining gates run means the verdict names every problem and every affected
+ * tool instead of only the first one found.
+ */
+export declare class ThreatGate implements WardenGate {
+    private readonly feed;
+    readonly name = "threat-feed";
+    constructor(feed: ThreatFeed);
+    evaluate(input: WardenGateInput): Promise<WardenGateResult>;
+}
+//# sourceMappingURL=threat-feed.d.ts.map

package/dist/threat-feed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"threat-feed.d.ts","sourceRoot":"","sources":["../src/threat-feed.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,YAAY,EAEZ,YAAY,EAEZ,OAAO,EACP,aAAa,EACb,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,QAAsB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAgB,CAAC;AA2HhD,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,+EAA+E;IAC/E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAcD,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,QAAQ,CAA2C;IAC3D,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAe;gBAExB,IAAI,CAAC,EAAE,iBAAiB;IAUpC,0EAA0E;IAC1E,IAAI,QAAQ,IAAI,YAAY,EAAE,CAE7B;IAED,GAAG,IAAI,YAAY,EAAE;IAIrB,qFAAqF;IACrF,OAAO,CAAC,UAAU;IAKlB;;;;;;;;;;;;;;;;;;OAkBG;IACG,IAAI,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA8I3C;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,GAAE,OAAO,EAAO,GAAG,aAAa,EAAE;CAmDpE;AAED;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,UAAU;IAG/B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,QAAQ,CAAC,IAAI,iBAAiB;gBAED,IAAI,EAAE,UAAU;IAEvC,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC;CAMlE"}