@aimarket/warden 0.0.1 → 0.3.0

package/dist/types.d.ts

@@ -0,0 +1,158 @@
+export type JSONSchema = Record<string, unknown>;
+/** An MCP tool as its server advertises it — the primary attack surface. */
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: JSONSchema;
+}
+export interface McpServerRef {
+    id: string;
+    name: string;
+    transport: "stdio" | "sse" | "http";
+    command?: string;
+    args?: string[];
+    url?: string;
+    env?: Record<string, string>;
+    /** Optional catalog this server was discovered from. */
+    catalog?: string;
+}
+export type Severity = "info" | "low" | "medium" | "high" | "critical";
+export interface WardenFinding {
+    gate: string;
+    severity: Severity;
+    /** Stable machine code, e.g. "TOOL_DEF_INJECTION". */
+    code: string;
+    message: string;
+    /** Optional tool the finding refers to. */
+    tool?: string;
+    /**
+     * Report-only: this finding NEVER blocks a connection and never costs a tool,
+     * at ANY `blockAtSeverity` setting. It is still reported. Whether it affects a
+     * gate's score is the gate's decision — the static scanner excludes advisory
+     * hits from its score, the pinning gate still rates an unpinned server 0.9.
+     *
+     * The tier is data, not a consequence of severity, because severity answers
+     * "how much attention" and tiering answers "is this a defect at all". A tool
+     * whose schema takes an `api_key` is worth pointing at and is not a defect;
+     * expressing that by lowering its severity would have made it blocking again
+     * for anyone who tightened `blockAtSeverity`.
+     */
+    advisory?: boolean;
+}
+export interface WardenVerdict {
+    allow: boolean;
+    /** 0..1 composite safety score (1 = safe). */
+    score: number;
+    /** The gate that produced the final decision, if blocked. */
+    decidedBy?: string;
+    findings: WardenFinding[];
+    /** Per-tool decisions when partial allow is in play. */
+    allowedTools: string[];
+    blockedTools: string[];
+    /**
+     * Which rule tables produced these findings. A recorded scan is only
+     * reproducible together with them: the same server can score differently
+     * under a later ruleset, and without the version and digest there is no way
+     * to tell that apart from the server having changed.
+     */
+    rulesets: {
+        staticScan: RulesetRef;
+    };
+}
+/** Identifies an exact rule table: a human version plus a digest of its content. */
+export interface RulesetRef {
+    /** Monotonic version of the rule table. */
+    version: string;
+    /** `sha256-<base64>` over the canonical serialization of every rule. */
+    digest: string;
+}
+/** What a gate sees: the server + its advertised tools + accumulating state. */
+export interface WardenGateInput {
+    server: McpServerRef;
+    tools: ToolDef[];
+    /** Findings accumulated by earlier gates. */
+    prior: WardenFinding[];
+    policy: WardenPolicy;
+}
+export interface WardenGateResult {
+    findings: WardenFinding[];
+    /** Per-gate score contribution 0..1 (1 = this gate is satisfied). */
+    score: number;
+    /** If true, short-circuit the chain and block immediately. */
+    fatal?: boolean;
+}
+export interface WardenGate {
+    readonly name: string;
+    evaluate(input: WardenGateInput): Promise<WardenGateResult>;
+}
+export interface WardenPolicy {
+    /** Block the whole connection if any finding >= this severity. */
+    blockAtSeverity: Severity;
+    /** Tool names that always require explicit user approval before running. */
+    sensitiveToolPatterns: string[];
+    /**
+     * Allow connecting to servers the operator never declared — that is, servers
+     * the host discovered from a remote catalog, which carry
+     * `McpServerRef.catalog`. `false` is fail-closed: only servers the operator
+     * listed explicitly may connect.
+     *
+     * This knob used to mean "has no reputation score yet", which no deployment
+     * could satisfy: nothing ever passed trust edges to the reputation oracle, so
+     * every server came back unvouched and `false` blocked all of them. Catalog
+     * provenance is a fact the host actually holds locally, needs no network, and
+     * cannot deadlock — a declared server is always known.
+     */
+    allowUnknownServers: boolean;
+    /** Re-approval required if a server's tool defs change after pinning. */
+    pinToolDefs: boolean;
+}
+/** A pinned snapshot of a server's tools, used for drift detection. */
+export interface PinnedServer {
+    serverId: string;
+    /** sha256 over the canonical tool-def set. */
+    toolsHash: string;
+    approvedAt: string;
+    toolNames: string[];
+}
+/**
+ * Where approvals are remembered between runs — the only persistence WARDEN
+ * needs. Narrow on purpose: any store with these two methods works, including a
+ * Map for tests. Without durable pins, drift detection degrades to "every
+ * server is seen for the first time, every time".
+ */
+export interface PinStore {
+    getPin(serverId: string): Promise<PinnedServer | undefined>;
+    putPin(p: PinnedServer): Promise<void>;
+}
+/**
+ * Which surface a threat pattern is meaningful against:
+ * - `server` — the server's identity/config only (id, name, url, command, args).
+ * - `tool` — the advertised tool definitions only (name, description, inputSchema).
+ * - `any` — both. This is the default when a record omits `scope`.
+ */
+export type ThreatScope = "server" | "tool" | "any";
+/** A signed threat-intel record about a known-bad server/tool. */
+export interface ThreatRecord {
+    /** Pattern matched against server identity and/or tool definitions per `scope`. */
+    pattern: string;
+    severity: Severity;
+    code: string;
+    reason: string;
+    source: string;
+    /** Match surface; defaults to `"any"` when absent. */
+    scope?: ThreatScope;
+}
+export type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Where WARDEN writes. Structurally identical to most host loggers, so an
+ * existing one usually satisfies it as-is; `silentLogger()` is provided for
+ * hosts that have none.
+ */
+export interface WardenLogger {
+    debug(msg: string, ...a: unknown[]): void;
+    info(msg: string, ...a: unknown[]): void;
+    warn(msg: string, ...a: unknown[]): void;
+    error(msg: string, ...a: unknown[]): void;
+    child(scope: string): WardenLogger;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,QAAQ,CAAC;IACnB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,OAAO,CAAC;IACf,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,wDAAwD;IACxD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,EAAE;QAAE,UAAU,EAAE,UAAU,CAAA;KAAE,CAAC;CACtC;AAED,oFAAoF;AACpF,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,6CAA6C;IAC7C,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,8DAA8D;IAC9D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,eAAe,EAAE,QAAQ,CAAC;IAC1B,4EAA4E;IAC5E,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC;;;;;;;;;;;OAWG;IACH,mBAAmB,EAAE,OAAO,CAAC;IAC7B,yEAAyE;IACzE,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAAC;IAC5D,MAAM,CAAC,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;AAEpD,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,QAAQ,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,KAAK,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3D;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC1C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IACzC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC1C,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC;CACpC"}

package/dist/types.js

@@ -0,0 +1,11 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// WARDEN — the MCP security firewall: protocol types
+//
+// Everything a host needs to talk to WARDEN lives in this file, and nothing
+// here depends on a particular agent. Two of these interfaces are host-supplied
+// seams rather than data — `PinStore` (where approvals are remembered) and
+// `WardenLogger` (where findings are written) — deliberately narrowed to what
+// the gates actually call, so a host can satisfy them with a Map and a no-op.
+// ─────────────────────────────────────────────────────────────────────────────
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qDAAqD;AACrD,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;AAChF,2EAA2E;AAC3E,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF"}

package/package.json

@@ -1,18 +1,75 @@
 {
   "name": "@aimarket/warden",
-  "version": "0.0.1",
-  "description": "ARGUS WARDEN MCP firewall namespace",
+  "version": "0.3.0",
+  "description": "WARDEN — MCP security firewall. Vets an MCP server's tool definitions, threat feed, origin and pinning before any tool runs. Zero runtime dependencies.",
+  "type": "module",
   "license": "MIT",
-  "main": "index.js",
-  "files": ["index.js", "README.md"],
-  "homepage": "https://www.npmjs.com/package/argus-warden",
+  "author": "AICOM (alexar76)",
+  "homepage": "https://github.com/alexar76/warden",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/alexar76/aimarket-sdks.git"
+    "url": "git+https://github.com/alexar76/warden.git"
   },
-  "keywords": ["aimarket", "modelmarket", "ai-market"],
-  "publishConfig": { "access": "public" },
+  "bugs": {
+    "url": "https://github.com/alexar76/warden/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./jcs": {
+      "types": "./dist/jcs.d.ts",
+      "import": "./dist/jcs.js",
+      "default": "./dist/jcs.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README-ru.md",
+    "README-es.md",
+    "README-fr.md",
+    "README-zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
   "scripts": {
-    "test": "node -e \"require('./index.js')\""
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-security",
+    "model-context-protocol",
+    "prompt-injection",
+    "tool-poisoning",
+    "warden",
+    "firewall",
+    "security",
+    "ai-agent",
+    "llm",
+    "aimarket",
+    "aicom"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@vitest/coverage-v8": "^2.1.9",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
   }
 }

package/index.js

@@ -1,6 +0,0 @@
-'use strict';
-module.exports = {
-  name: '@aimarket/warden',
-  install: 'npm install -g argus-warden',
-  homepage: 'https://www.npmjs.com/package/argus-warden',
-};