@mcp-guardian/server 0.4.0 → 0.5.0

package/dist/utils/metrics.d.ts

@@ -0,0 +1,17 @@
+import { Registry, Counter, Gauge, Histogram } from 'prom-client';
+/**
+ * Prometheus metrics for MCP Guardian.
+ * Exposed at /metrics for scraping by Prometheus/Grafana.
+ *
+ * Enable with: METRICS_ENABLED=true METRICS_PORT=9090
+ */
+export declare const registry: Registry<"text/plain; version=0.0.4; charset=utf-8">;
+export declare const requestsTotal: Counter<"server_name" | "decision" | "authn_success">;
+export declare const blockedRequestsTotal: Counter<"rule" | "server_name" | "block_reason">;
+export declare const authFailuresTotal: Counter<"reason" | "server_name">;
+export declare const circuitBreakerState: Gauge<"server_name">;
+export declare const activeSessions: Gauge<string>;
+export declare const proxyLatencyMs: Histogram<"server_name">;
+export declare const authLatencyMs: Histogram<"server_name">;
+export declare function startMetricsServer(port?: number): Promise<Registry>;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/utils/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/utils/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAyB,MAAM,aAAa,CAAC;AAGzF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,sDAAiB,CAAC;AAIvC,eAAO,MAAM,aAAa,uDAKxB,CAAC;AAEH,eAAO,MAAM,oBAAoB,kDAK/B,CAAC;AAEH,eAAO,MAAM,iBAAiB,mCAK5B,CAAC;AAGH,eAAO,MAAM,mBAAmB,sBAK9B,CAAC;AAEH,eAAO,MAAM,cAAc,eAIzB,CAAC;AAGH,eAAO,MAAM,cAAc,0BAMzB,CAAC;AAEH,eAAO,MAAM,aAAa,0BAMxB,CAAC;AAGH,wBAAsB,kBAAkB,CAAC,IAAI,GAAE,MAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAoB/E"}

package/dist/utils/metrics.js

@@ -0,0 +1,79 @@
+import { Registry, Counter, Gauge, Histogram, collectDefaultMetrics } from 'prom-client';
+import { Logger } from './logger.js';
+/**
+ * Prometheus metrics for MCP Guardian.
+ * Exposed at /metrics for scraping by Prometheus/Grafana.
+ *
+ * Enable with: METRICS_ENABLED=true METRICS_PORT=9090
+ */
+export const registry = new Registry();
+collectDefaultMetrics({ register: registry, prefix: 'mcp_guardian_' });
+// ── Counters ─────────────────────────────────────────────────────
+export const requestsTotal = new Counter({
+    name: 'mcp_guardian_requests_total',
+    help: 'Total number of tools/call requests processed',
+    labelNames: ['server_name', 'decision', 'authn_success'],
+    registers: [registry],
+});
+export const blockedRequestsTotal = new Counter({
+    name: 'mcp_guardian_blocked_requests_total',
+    help: 'Total number of blocked tools/call requests',
+    labelNames: ['server_name', 'block_reason', 'rule'],
+    registers: [registry],
+});
+export const authFailuresTotal = new Counter({
+    name: 'mcp_guardian_auth_failures_total',
+    help: 'Total number of authentication failures',
+    labelNames: ['server_name', 'reason'],
+    registers: [registry],
+});
+// ── Gauges ────────────────────────────────────────────────────────
+export const circuitBreakerState = new Gauge({
+    name: 'mcp_guardian_circuit_breaker_state',
+    help: 'Circuit breaker state: 0=CLOSED, 1=OPEN, 2=HALF_OPEN',
+    labelNames: ['server_name'],
+    registers: [registry],
+});
+export const activeSessions = new Gauge({
+    name: 'mcp_guardian_active_sessions',
+    help: 'Number of active session tokens',
+    registers: [registry],
+});
+// ── Histograms ────────────────────────────────────────────────────
+export const proxyLatencyMs = new Histogram({
+    name: 'mcp_guardian_proxy_latency_ms',
+    help: 'Proxy processing latency in milliseconds',
+    labelNames: ['server_name'],
+    buckets: [1, 5, 10, 25, 50, 100, 250, 500, 1000],
+    registers: [registry],
+});
+export const authLatencyMs = new Histogram({
+    name: 'mcp_guardian_auth_latency_ms',
+    help: 'Authentication/JWT validation latency in milliseconds',
+    labelNames: ['server_name'],
+    buckets: [1, 5, 10, 25, 50, 100, 250, 500],
+    registers: [registry],
+});
+// ── Metrics server ────────────────────────────────────────────────
+export async function startMetricsServer(port = 9090) {
+    if (process.env['METRICS_ENABLED'] !== 'true') {
+        Logger.debug('[metrics] Metrics server not enabled (set METRICS_ENABLED=true)');
+        return registry;
+    }
+    try {
+        const { createServer } = await import('http');
+        const server = createServer(async (_req, res) => {
+            res.writeHead(200, { 'Content-Type': registry.contentType });
+            res.end(await registry.metrics());
+        });
+        server.listen(port, () => {
+            Logger.info(`[metrics] Prometheus metrics available at http://0.0.0.0:${port}/metrics`);
+        });
+        return registry;
+    }
+    catch (err) {
+        Logger.error(`[metrics] Failed to start metrics server: ${err?.message}`);
+        return registry;
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/utils/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/utils/metrics.ts"],"names":[],"mappings":"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"}

package/dist/utils/mtls-config.d.ts

@@ -0,0 +1,27 @@
+import { Agent as HttpsAgent } from 'https';
+export interface MtlsConfig {
+    enabled: boolean;
+    ca?: Buffer;
+    cert?: Buffer;
+    key?: Buffer;
+    rejectUnauthorized: boolean;
+}
+/**
+ * Load mTLS configuration from environment variables.
+ */
+export declare function loadMtlsConfig(): MtlsConfig;
+/**
+ * Create an HTTPS Agent configured with mTLS client certificate and CA.
+ */
+export declare function createMtlsAgent(config: MtlsConfig): HttpsAgent | undefined;
+/**
+ * CLI flag names for mTLS configuration.
+ */
+export declare const MTL_CLI_FLAGS: {
+    readonly tlsEnabled: "--mtls";
+    readonly tlsCa: "--mtls-ca <path>";
+    readonly tlsCert: "--mtls-cert <path>";
+    readonly tlsKey: "--mtls-key <path>";
+    readonly tlsInsecure: "--mtls-insecure";
+};
+//# sourceMappingURL=mtls-config.d.ts.map

package/dist/utils/mtls-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtls-config.d.ts","sourceRoot":"","sources":["../../src/utils/mtls-config.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,OAAO,CAAC;AAG5C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAsC3C;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAW1E;AAED;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;;CAMhB,CAAC"}

package/dist/utils/mtls-config.js

@@ -0,0 +1,82 @@
+/**
+ * mTLS Configuration for Zero-Trust Proxy ↔ Upstream Communication.
+ *
+ * When MCP_TLS_ENABLED=true, the HTTP/SSE proxy validates the upstream
+ * server's certificate AND presents a client certificate for mutual
+ * authentication. This prevents MITM attacks and ensures only authorized
+ * proxies can connect to upstream MCP servers.
+ *
+ * Configuration via environment variables:
+ *   MCP_TLS_ENABLED=true|false
+ *   MCP_TLS_CA=/path/to/ca-cert.pem        (required — trusted CA bundle)
+ *   MCP_TLS_CERT=/path/to/client-cert.pem   (required — proxy's client cert)
+ *   MCP_TLS_KEY=/path/to/client-key.pem     (required — proxy's client key)
+ *   MCP_TLS_REJECT_UNAUTHORIZED=true|false  (default: true — strict mode)
+ */
+import { readFileSync } from 'fs';
+import { Agent as HttpsAgent } from 'https';
+import { Logger } from './logger.js';
+/**
+ * Load mTLS configuration from environment variables.
+ */
+export function loadMtlsConfig() {
+    const enabled = process.env['MCP_TLS_ENABLED'] === 'true';
+    if (!enabled) {
+        return { enabled: false, rejectUnauthorized: true };
+    }
+    const caPath = process.env['MCP_TLS_CA'];
+    const certPath = process.env['MCP_TLS_CERT'];
+    const keyPath = process.env['MCP_TLS_KEY'];
+    const rejectUnauthorized = process.env['MCP_TLS_REJECT_UNAUTHORIZED'] !== 'false';
+    const missing = [];
+    if (!caPath)
+        missing.push('MCP_TLS_CA');
+    if (!certPath)
+        missing.push('MCP_TLS_CERT');
+    if (!keyPath)
+        missing.push('MCP_TLS_KEY');
+    if (missing.length > 0) {
+        Logger.error(`[mtls] mTLS enabled but missing env vars: ${missing.join(', ')}`);
+        throw new Error(`mTLS misconfigured: missing ${missing.join(', ')}`);
+    }
+    let ca;
+    let cert;
+    let key;
+    try {
+        ca = readFileSync(caPath);
+        cert = readFileSync(certPath);
+        key = readFileSync(keyPath);
+    }
+    catch (err) {
+        Logger.error(`[mtls] Failed to read TLS files: ${err?.message}`);
+        throw err;
+    }
+    Logger.info(`[mtls] mTLS enabled (CA: ${caPath}, cert: ${certPath}, rejectUnauthorized: ${rejectUnauthorized})`);
+    return { enabled: true, ca, cert, key, rejectUnauthorized };
+}
+/**
+ * Create an HTTPS Agent configured with mTLS client certificate and CA.
+ */
+export function createMtlsAgent(config) {
+    if (!config.enabled)
+        return undefined;
+    return new HttpsAgent({
+        ca: config.ca,
+        cert: config.cert,
+        key: config.key,
+        rejectUnauthorized: config.rejectUnauthorized,
+        keepAlive: true,
+        keepAliveMsecs: 30000,
+    });
+}
+/**
+ * CLI flag names for mTLS configuration.
+ */
+export const MTL_CLI_FLAGS = {
+    tlsEnabled: '--mtls',
+    tlsCa: '--mtls-ca <path>',
+    tlsCert: '--mtls-cert <path>',
+    tlsKey: '--mtls-key <path>',
+    tlsInsecure: '--mtls-insecure',
+};
+//# sourceMappingURL=mtls-config.js.map

package/dist/utils/mtls-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mtls-config.js","sourceRoot":"","sources":["../../src/utils/mtls-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAClC,OAAO,EAAE,KAAK,IAAI,UAAU,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAUrC;;GAEG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,KAAK,MAAM,CAAC;IAE1D,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC;IACtD,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IAC3C,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,6BAA6B,CAAC,KAAK,OAAO,CAAC;IAElF,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,CAAC,MAAM;QAAE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACxC,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO;QAAE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAE1C,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,CAAC,KAAK,CAAC,6CAA6C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,+BAA+B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IAED,IAAI,EAAsB,CAAC;IAC3B,IAAI,IAAwB,CAAC;IAC7B,IAAI,GAAuB,CAAC;IAE5B,IAAI,CAAC;QACH,EAAE,GAAG,YAAY,CAAC,MAAO,CAAC,CAAC;QAC3B,IAAI,GAAG,YAAY,CAAC,QAAS,CAAC,CAAC;QAC/B,GAAG,GAAG,YAAY,CAAC,OAAQ,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAClB,MAAM,CAAC,KAAK,CAAC,oCAAoC,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QACjE,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,MAAM,CAAC,IAAI,CAAC,4BAA4B,MAAM,WAAW,QAAQ,yBAAyB,kBAAkB,GAAG,CAAC,CAAC;IAEjH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,kBAAkB,EAAE,CAAC;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,MAAkB;IAChD,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAEtC,OAAO,IAAI,UAAU,CAAC;QACpB,EAAE,EAAE,MAAM,CAAC,EAAE;QACb,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;QAC7C,SAAS,EAAE,IAAI;QACf,cAAc,EAAE,KAAK;KACtB,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,UAAU,EAAE,QAAQ;IACpB,KAAK,EAAE,kBAAkB;IACzB,OAAO,EAAE,oBAAoB;IAC7B,MAAM,EAAE,mBAAmB;IAC3B,WAAW,EAAE,iBAAiB;CACtB,CAAC"}

package/dist/utils/payload-normalizer.d.ts

@@ -0,0 +1,62 @@
+export interface NormalizationResult {
+    /** The fully normalized string ready for policy evaluation */
+    normalized: string;
+    /** Whether any normalization was applied */
+    wasModified: boolean;
+    /** What transformations were applied */
+    transformations: string[];
+    /** The original raw input */
+    original: string;
+}
+/**
+ * PayloadNormalizer applies multi-stage normalization to defeat
+ * common evasion techniques targeting regex-based policy engines.
+ */
+export declare class PayloadNormalizer {
+    private readonly maxDepth;
+    private readonly maxLength;
+    constructor(maxDepth?: number, maxLength?: number);
+    /**
+     * Full normalization pipeline for policy evaluation input.
+     */
+    normalize(input: string): NormalizationResult;
+    /**
+     * URL decode: %XX → character, handles malformed sequences.
+     */
+    private urlDecode;
+    /**
+     * Decode hex escapes: \x41 → 'A', \x00 → null byte detection.
+     */
+    private decodeHexEscapes;
+    /**
+     * Decode unicode escapes: \u0041 → 'A', \U00000041 → 'A'.
+     */
+    private decodeUnicodeEscapes;
+    /**
+     * Decode HTML entities: < -> <, &#60; -> <, &#x3C; -> <.
+     * Entity map built at runtime to avoid source-level entity decoding issues.
+     */
+    private static htmlEntityMap;
+    private static getHtmlEntityMap;
+    private decodeHtmlEntities;
+    /**
+     * Unwrap double escapes: \\. → literal character.
+     */
+    private unwrapDoubleEscapes;
+    /**
+     * Shell normalize: collapse common shell obfuscation patterns.
+     *
+     * - $'cmd' → cmd (ANSI-C quoting)
+     * - "c"m"d" → cmd (quote splitting)
+     * - ''cmd'' → cmd (empty quote pairs)
+     * - c\md → cmd (backslash escapes)
+     */
+    private shellNormalize;
+    /**
+     * Specifically normalize a JSON string value (tool argument).
+     * Handles nested JSON structures recursively.
+     */
+    normalizeJsonValue(value: unknown, depth?: number): unknown;
+}
+export declare function getNormalizer(): PayloadNormalizer;
+//# sourceMappingURL=payload-normalizer.d.ts.map

package/dist/utils/payload-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-normalizer.d.ts","sourceRoot":"","sources":["../../src/utils/payload-normalizer.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,mBAAmB;IAClC,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,WAAW,EAAE,OAAO,CAAC;IACrB,wCAAwC;IACxC,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,QAAQ,SAAI,EAAE,SAAS,SAAY;IAK/C;;OAEG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,mBAAmB;IAmE7C;;OAEG;IACH,OAAO,CAAC,SAAS;IAejB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IASxB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAoB5B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa,CAAwC;IAEpE,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAiC/B,OAAO,CAAC,kBAAkB;IAmB1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAQ3B;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAkBtB;;;OAGG;IACH,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO;CAqBvD;AAKD,wBAAgB,aAAa,IAAI,iBAAiB,CAKjD"}

package/dist/utils/payload-normalizer.js

@@ -0,0 +1,240 @@
+/**
+ * PayloadNormalizer applies multi-stage normalization to defeat
+ * common evasion techniques targeting regex-based policy engines.
+ */
+export class PayloadNormalizer {
+    maxDepth;
+    maxLength;
+    constructor(maxDepth = 5, maxLength = 1_000_000) {
+        this.maxDepth = maxDepth;
+        this.maxLength = maxLength;
+    }
+    /**
+     * Full normalization pipeline for policy evaluation input.
+     */
+    normalize(input) {
+        const transformations = [];
+        let current = input;
+        let depth = 0;
+        // ── Step 0: Truncate oversized inputs (memory safety) ──
+        if (current.length > this.maxLength) {
+            current = current.slice(0, this.maxLength);
+            transformations.push('truncated');
+        }
+        // ── Step 1: Unicode normalization (NFKC) — collapses homoglyphs ──
+        const unicodeNormalized = current.normalize('NFKC');
+        if (unicodeNormalized !== current) {
+            transformations.push('unicode-nfkc');
+            current = unicodeNormalized;
+        }
+        // ── Step 2: Iterative decode loop (URL, hex, HTML entities) ──
+        while (depth < this.maxDepth) {
+            const before = current;
+            // URL decode (handles %20, %00 null bytes, %2F slashes)
+            current = this.urlDecode(current);
+            // Hex escape decode (\x41, \x00, \x2F)
+            current = this.decodeHexEscapes(current);
+            // Unicode escape decode (\u0041, \U00000041)
+            current = this.decodeUnicodeEscapes(current);
+            // HTML entity decode (<, &#60;, &#x3C;)
+            current = this.decodeHtmlEntities(current);
+            // Double-backslash unwrap (\\. → .)
+            current = this.unwrapDoubleEscapes(current);
+            if (current === before)
+                break;
+            depth++;
+        }
+        if (current !== unicodeNormalized) {
+            transformations.push('decode-loop');
+        }
+        // ── Step 3: Shell normalization ──
+        const shellNormalized = this.shellNormalize(current);
+        if (shellNormalized !== current) {
+            transformations.push('shell-normalize');
+            current = shellNormalized;
+        }
+        // ── Step 4: Whitespace normalization (collapse runs) ──
+        const whitespaceNormalized = current.replace(/\s+/g, ' ').trim();
+        if (whitespaceNormalized !== current) {
+            transformations.push('whitespace');
+            current = whitespaceNormalized;
+        }
+        return {
+            normalized: current,
+            wasModified: transformations.length > 0,
+            transformations,
+            original: input,
+        };
+    }
+    /**
+     * URL decode: %XX → character, handles malformed sequences.
+     */
+    urlDecode(input) {
+        try {
+            return decodeURIComponent(input.replace(/\+/g, ' '));
+        }
+        catch {
+            // Gracefully handle malformed % sequences: replace only valid ones
+            return input.replace(/%([0-9A-Fa-f]{2})/g, (_match, hex) => {
+                try {
+                    return String.fromCharCode(parseInt(hex, 16));
+                }
+                catch {
+                    return _match;
+                }
+            });
+        }
+    }
+    /**
+     * Decode hex escapes: \x41 → 'A', \x00 → null byte detection.
+     */
+    decodeHexEscapes(input) {
+        return input.replace(/\\x([0-9A-Fa-f]{2})/g, (_match, hex) => {
+            const code = parseInt(hex, 16);
+            // Preserve null byte as marker for detection
+            if (code === 0)
+                return '\0';
+            return String.fromCharCode(code);
+        });
+    }
+    /**
+     * Decode unicode escapes: \u0041 → 'A', \U00000041 → 'A'.
+     */
+    decodeUnicodeEscapes(input) {
+        return input
+            .replace(/\\u([0-9A-Fa-f]{4})/g, (_match, hex) => {
+            try {
+                return String.fromCharCode(parseInt(hex, 16));
+            }
+            catch {
+                return _match;
+            }
+        })
+            .replace(/\\U([0-9A-Fa-f]{8})/g, (_match, hex) => {
+            try {
+                const code = parseInt(hex, 16);
+                if (code > 0x10ffff)
+                    return _match; // Invalid unicode
+                return String.fromCodePoint(code);
+            }
+            catch {
+                return _match;
+            }
+        });
+    }
+    /**
+     * Decode HTML entities: < -> <, &#60; -> <, &#x3C; -> <.
+     * Entity map built at runtime to avoid source-level entity decoding issues.
+     */
+    static htmlEntityMap = null;
+    static getHtmlEntityMap() {
+        if (PayloadNormalizer.htmlEntityMap)
+            return PayloadNormalizer.htmlEntityMap;
+        const a = String.fromCharCode(38); // ampersand char
+        const pairs = [
+            [a + 'lt;', '<'],
+            [a + 'gt;', '>'],
+            [a + 'amp;', a],
+            [a + 'quot;', '"'],
+            [a + '#39;', "'"],
+            [a + 'apos;', "'"],
+            [a + 'sol;', '/'],
+            [a + 'bsol;', '\\'],
+            [a + 'colon;', ':'],
+            [a + 'semi;', ';'],
+            [a + 'verbar;', '|'],
+            [a + 'dollar;', '$'],
+            [a + 'lpar;', '('],
+            [a + 'rpar;', ')'],
+            [a + 'lcub;', '{'],
+            [a + 'rcub;', '}'],
+            [a + 'lbrack;', '['],
+            [a + 'rbrack;', ']'],
+        ];
+        PayloadNormalizer.htmlEntityMap = pairs.map(([entity, ch]) => {
+            const escaped = entity.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            return [new RegExp(escaped, 'g'), ch];
+        });
+        return PayloadNormalizer.htmlEntityMap;
+    }
+    decodeHtmlEntities(input) {
+        let result = input;
+        // Named entities
+        for (const [regex, ch] of PayloadNormalizer.getHtmlEntityMap()) {
+            result = result.replace(regex, ch);
+        }
+        // Numeric decimal entities: &#60;
+        result = result.replace(/&#(\d+);/g, (_match, dec) => {
+            const code = parseInt(dec, 10);
+            return (code > 0 && code < 65536) ? String.fromCharCode(code) : _match;
+        });
+        // Numeric hex entities: &#x3C;
+        result = result.replace(/&#x([0-9A-Fa-f]+);/g, (_match, hex) => {
+            const code = parseInt(hex, 16);
+            return (code > 0 && code < 65536) ? String.fromCharCode(code) : _match;
+        });
+        return result;
+    }
+    /**
+     * Unwrap double escapes: \\. → literal character.
+     */
+    unwrapDoubleEscapes(input) {
+        return input.replace(/\\(.)/g, (_match, char) => {
+            // Only unwrap if the backslash is escaping a non-special char
+            if ('\\$`"\''.includes(char))
+                return _match;
+            return char;
+        });
+    }
+    /**
+     * Shell normalize: collapse common shell obfuscation patterns.
+     *
+     * - $'cmd' → cmd (ANSI-C quoting)
+     * - "c"m"d" → cmd (quote splitting)
+     * - ''cmd'' → cmd (empty quote pairs)
+     * - c\md → cmd (backslash escapes)
+     */
+    shellNormalize(input) {
+        let result = input;
+        // ANSI-C quoting: $'command' → command
+        result = result.replace(/\$'([^']*)'/g, '$1');
+        // Quote splitting: "a""b" → ab, 'a''b' → ab
+        result = result.replace(/["']\s*["']/g, '');
+        // Shell backslash escapes on non-special chars
+        result = result.replace(/\\([^\\$`"'|&;><~#%{}()\[\]])/g, '$1');
+        // Null byte detection (normalized → mark as NUL for policy patterns)
+        result = result.replace(/\0/g, '\\0');
+        return result;
+    }
+    /**
+     * Specifically normalize a JSON string value (tool argument).
+     * Handles nested JSON structures recursively.
+     */
+    normalizeJsonValue(value, depth = 0) {
+        if (depth > 10)
+            return value; // Recursion guard
+        if (typeof value === 'string') {
+            return this.normalize(value).normalized;
+        }
+        if (Array.isArray(value)) {
+            return value.map((item) => this.normalizeJsonValue(item, depth + 1));
+        }
+        if (value !== null && typeof value === 'object') {
+            const result = {};
+            for (const [key, val] of Object.entries(value)) {
+                result[key] = this.normalizeJsonValue(val, depth + 1);
+            }
+            return result;
+        }
+        return value;
+    }
+}
+/** Singleton instance for policy engine integration */
+let defaultInstance = null;
+export function getNormalizer() {
+    if (!defaultInstance) {
+        defaultInstance = new PayloadNormalizer();
+    }
+    return defaultInstance;
+}
+//# sourceMappingURL=payload-normalizer.js.map

package/dist/utils/payload-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload-normalizer.js","sourceRoot":"","sources":["../../src/utils/payload-normalizer.ts"],"names":[],"mappings":"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"}

package/dist/utils/policy-auditor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Policy Audit Trail — records every policy change for compliance.
+ * Logs: who changed what, when, old/new values, and rollback info.
+ * Enable with: POLICY_AUDIT_ENABLED=true
+ */
+export interface PolicyChangeRecord {
+    timestamp: string;
+    actor: string;
+    change: string;
+    oldValue?: string;
+    newValue?: string;
+    sourceHash?: string;
+}
+export declare class PolicyAuditor {
+    private auditPath;
+    private enabled;
+    private lastHash;
+    constructor(auditPath?: string);
+    record(change: PolicyChangeRecord): void;
+    readAuditTrail(): PolicyChangeRecord[];
+    computeHash(content: string): string;
+    hasChanged(content: string): boolean;
+}
+//# sourceMappingURL=policy-auditor.d.ts.map

package/dist/utils/policy-auditor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-auditor.d.ts","sourceRoot":"","sources":["../../src/utils/policy-auditor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,QAAQ,CAAuB;gBAE3B,SAAS,CAAC,EAAE,MAAM;IAK9B,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAWxC,cAAc,IAAI,kBAAkB,EAAE;IAUtC,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAUpC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;CASrC"}

package/dist/utils/policy-auditor.js

@@ -0,0 +1,58 @@
+/**
+ * Policy Audit Trail — records every policy change for compliance.
+ * Logs: who changed what, when, old/new values, and rollback info.
+ * Enable with: POLICY_AUDIT_ENABLED=true
+ */
+import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { Logger } from './logger.js';
+export class PolicyAuditor {
+    auditPath;
+    enabled;
+    lastHash = null;
+    constructor(auditPath) {
+        this.enabled = process.env['POLICY_AUDIT_ENABLED'] === 'true';
+        this.auditPath = auditPath || process.env['POLICY_AUDIT_LOG'] || './policy-audit.jsonl';
+    }
+    record(change) {
+        if (!this.enabled)
+            return;
+        try {
+            const line = JSON.stringify({ ...change, source: 'mcp-guardian-policy-auditor' }) + '\n';
+            writeFileSync(this.auditPath, line, { flag: 'a' });
+            Logger.debug(`[policy-auditor] Change recorded: ${change.change}`);
+        }
+        catch (err) {
+            Logger.error(`[policy-auditor] Failed to write audit log: ${err?.message}`);
+        }
+    }
+    readAuditTrail() {
+        if (!existsSync(this.auditPath))
+            return [];
+        try {
+            const content = readFileSync(this.auditPath, 'utf-8');
+            return content.trim().split('\n').filter(Boolean).map(l => JSON.parse(l));
+        }
+        catch {
+            return [];
+        }
+    }
+    computeHash(content) {
+        let hash = 0;
+        for (let i = 0; i < content.length; i++) {
+            const char = content.charCodeAt(i);
+            hash = ((hash << 5) - hash) + char;
+            hash |= 0;
+        }
+        return hash.toString(16);
+    }
+    hasChanged(content) {
+        const currentHash = this.computeHash(content);
+        if (this.lastHash && this.lastHash !== currentHash) {
+            this.lastHash = currentHash;
+            return true;
+        }
+        this.lastHash = currentHash;
+        return false;
+    }
+}
+//# sourceMappingURL=policy-auditor.js.map

package/dist/utils/policy-auditor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-auditor.js","sourceRoot":"","sources":["../../src/utils/policy-auditor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAC7D,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAWrC,MAAM,OAAO,aAAa;IAChB,SAAS,CAAS;IAClB,OAAO,CAAU;IACjB,QAAQ,GAAkB,IAAI,CAAC;IAEvC,YAAY,SAAkB;QAC5B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,KAAK,MAAM,CAAC;QAC9D,IAAI,CAAC,SAAS,GAAG,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,sBAAsB,CAAC;IAC1F,CAAC;IAED,MAAM,CAAC,MAA0B;QAC/B,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC,GAAG,IAAI,CAAC;YACzF,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;YACnD,MAAM,CAAC,KAAK,CAAC,qCAAqC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QACrE,CAAC;QAAC,OAAO,GAAQ,EAAE,CAAC;YAClB,MAAM,CAAC,KAAK,CAAC,+CAA+C,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAED,cAAc;QACZ,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACtD,OAAO,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,WAAW,CAAC,OAAe;QACzB,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACnC,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;YACnC,IAAI,IAAI,CAAC,CAAC;QACZ,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,UAAU,CAAC,OAAe;QACxB,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;YACnD,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC;YAC5B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,WAAW,CAAC;QAC5B,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}