@mcp-guardian/server 1.0.1 → 1.2.0

package/dist/utils/dashboard-server.js

@@ -3,84 +3,256 @@ import { readFileSync } from 'fs';
 import { resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { Logger } from './logger.js';
+import { DashboardAuth } from '../auth/dashboard-auth.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 /**
  * Lightweight dashboard server that serves:
- * - / — the dashboard HTML
- * - /api/policy — current policy (JSON)
- * - /api/policy/reload — trigger policy reload
- * - /metrics — Prometheus metrics
+ * - / — the dashboard HTML (requires auth if enabled)
+ * - /login — login page (when JWT auth is enabled)
+ * - /api/login — POST login endpoint
+ * - /api/policy — current policy (JSON, requires auth)
+ * - /api/policy/reload — trigger policy reload (requires auth)
+ * - /metrics — Prometheus metrics (can be auth-gated or public via DASHBOARD_METRICS_PUBLIC=true)
+ *
+ * v1.2: Integrated DashboardAuth for JWT/API key authentication, CSRF protection.
  */
-export async function startDashboardServer(port = 4000, policyWatcher) {
+export async function startDashboardServer(port = 4000, policyWatcher, dashboardAuth) {
     if (process.env['DASHBOARD_ENABLED'] !== 'true') {
         Logger.debug('[dashboard] Dashboard server not enabled (set DASHBOARD_ENABLED=true)');
-        return;
+        return { auth: dashboardAuth || new DashboardAuth({ enabled: false }), server: createServer((_req, res) => {
+                res.writeHead(200);
+                res.end();
+            }) };
+    }
+    const auth = dashboardAuth || new DashboardAuth();
+    const authEnabled = auth.isEnabled();
+    if (authEnabled) {
+        Logger.info('[dashboard] Dashboard authentication enabled');
+    }
+    else {
+        Logger.info('[dashboard] Dashboard running without authentication (set DASHBOARD_AUTH_ENABLED=true)');
     }
     const dashboardHtml = readFileSync(resolve(__dirname, '..', '..', 'deploy', 'dashboard.html'), 'utf-8');
+    /** Read JSON body from request */
+    async function readBody(req) {
+        return new Promise((resolve, reject) => {
+            let data = '';
+            req.on('data', (chunk) => { data += chunk.toString(); });
+            req.on('end', () => {
+                try {
+                    resolve(data ? JSON.parse(data) : {});
+                }
+                catch {
+                    resolve({});
+                }
+            });
+            req.on('error', reject);
+        });
+    }
+    /** Parse form-encoded body from request */
+    async function readFormBody(req) {
+        return new Promise((resolve) => {
+            let data = '';
+            req.on('data', (chunk) => { data += chunk.toString(); });
+            req.on('end', () => {
+                const result = {};
+                if (data) {
+                    try {
+                        const params = new URLSearchParams(data);
+                        for (const [key, value] of params) {
+                            result[key] = value;
+                        }
+                    }
+                    catch {
+                        // Ignore parse errors
+                    }
+                }
+                resolve(result);
+            });
+        });
+    }
+    /** Get client IP for rate limiting */
+    function getClientIp(req) {
+        const forwarded = req.headers['x-forwarded-for'];
+        if (forwarded) {
+            const first = Array.isArray(forwarded) ? forwarded[0] : forwarded.split(',')[0];
+            return (first || '').trim();
+        }
+        return req.socket?.remoteAddress || 'unknown';
+    }
+    /** Write JSON response */
+    function writeJson(res, status, data) {
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(data));
+    }
     const server = createServer(async (req, res) => {
         const url = req.url || '/';
+        const method = req.method || 'GET';
+        // ── CORS preflight ─────────────────────────────────────
+        if (method === 'OPTIONS') {
+            res.writeHead(204, {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-API-Key',
+            });
+            res.end();
+            return;
+        }
+        // ── CORS headers on all responses ─────────────────────
+        const setCors = () => {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+        };
         try {
-            // ── Dashboard HTML ──────────────────────────────────────
+            // ── Login page (only when JWT auth is enabled, no API key set) ──
+            if (url === '/login' && method === 'GET') {
+                setCors();
+                if (auth.isEnabled() && auth.hasJwtSessionAuth()) {
+                    res.writeHead(200, { 'Content-Type': 'text/html' });
+                    res.end(auth.getLoginPageHtml());
+                }
+                else {
+                    res.writeHead(302, { 'Location': '/' });
+                    res.end();
+                }
+                return;
+            }
+            // ── Login API endpoint ──────────────────────────────
+            if (url === '/api/login' && method === 'POST') {
+                setCors();
+                const ip = getClientIp(req);
+                const contentType = req.headers['content-type'] || '';
+                let body;
+                if (contentType.includes('application/x-www-form-urlencoded')) {
+                    body = await readFormBody(req);
+                }
+                else {
+                    body = await readBody(req);
+                }
+                const result = auth.login({
+                    url,
+                    headers: req.headers,
+                    body: {
+                        username: body.username,
+                        password: body.password,
+                        api_key: body.api_key,
+                    },
+                    ip,
+                });
+                if (result.success && req.headers['content-type']?.includes('form')) {
+                    // Form submission — redirect to dashboard with token
+                    res.writeHead(302, {
+                        'Location': `/?api_key=${encodeURIComponent(result.token)}`,
+                        'Set-Cookie': `mcp_guardian_session=${result.token}; Path=/; HttpOnly; SameSite=Strict; Max-Age=3600`,
+                    });
+                    res.end();
+                    return;
+                }
+                if (result.success) {
+                    writeJson(res, 200, { success: true, token: result.token });
+                }
+                else {
+                    writeJson(res, 401, { success: false, error: result.error });
+                }
+                return;
+            }
+            // ── Auth check for all other routes ─────────────────
+            const authResult = auth.authenticate({ url, headers: req.headers, method });
+            if (!authResult.authenticated) {
+                setCors();
+                if (req.headers['accept']?.includes('text/html')) {
+                    // Browser request — redirect to login
+                    res.writeHead(302, { 'Location': '/login' });
+                    res.end();
+                }
+                else {
+                    writeJson(res, 401, { error: 'Authentication required', reason: authResult.reason });
+                }
+                return;
+            }
+            // ── Dashboard HTML ──────────────────────────────────
             if (url === '/' || url === '/dashboard.html') {
+                setCors();
                 res.writeHead(200, { 'Content-Type': 'text/html' });
                 res.end(dashboardHtml);
                 return;
             }
-            // ── Policy API ──────────────────────────────────────────
-            if (url === '/api/policy' && req.method === 'GET') {
+            // ── Policy API ──────────────────────────────────────
+            if (url === '/api/policy' && method === 'GET') {
+                setCors();
                 if (!policyWatcher || !policyWatcher.get()) {
-                    res.writeHead(404, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'No active policy. Start proxy with --policy flag.' }));
+                    writeJson(res, 404, { error: 'No active policy. Start proxy with --policy flag.' });
                     return;
                 }
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ mode: policyWatcher.get().getMode(), rules: 'Policy engine active (YAML view available on filesystem)' }));
+                writeJson(res, 200, { mode: policyWatcher.get().getMode(), rules: 'Policy engine active (YAML view available on filesystem)' });
                 return;
             }
-            if (url === '/api/policy/reload' && req.method === 'POST') {
+            if (url === '/api/policy/reload' && method === 'POST') {
+                setCors();
                 if (!policyWatcher) {
-                    res.writeHead(404, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Policy watcher not configured' }));
+                    writeJson(res, 404, { error: 'Policy watcher not configured' });
                     return;
                 }
-                // PolicyWatcher auto-reloads via chokidar — no manual reload needed
-                res.writeHead(200, { 'Content-Type': 'application/json' });
-                res.end(JSON.stringify({ status: 'ok', message: 'Policy watcher is active. File changes are auto-detected.' }));
+                writeJson(res, 200, { status: 'ok', message: 'Policy watcher is active. File changes are auto-detected.' });
                 return;
             }
-            // ── Prometheus /metrics proxy ──────────────────────────
+            // ── Prometheus /metrics proxy ──────────────────────
             if (url === '/metrics') {
-                try {
-                    // Fetch from the metrics server (port 9090 by default)
-                    const metricsPort = process.env['METRICS_PORT'] || '9090';
-                    const metricsRes = await fetch(`http://localhost:${metricsPort}/metrics`);
-                    if (!metricsRes.ok)
-                        throw new Error(`Metrics server returned ${metricsRes.status}`);
-                    const text = await metricsRes.text();
-                    res.writeHead(200, {
-                        'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
-                        'Access-Control-Allow-Origin': '*',
-                    });
-                    res.end(text);
+                setCors();
+                const metricsPublic = process.env['DASHBOARD_METRICS_PUBLIC'] === 'true';
+                // Re-check auth for metrics unless public
+                if (metricsPublic || authResult.authenticated) {
+                    try {
+                        const metricsPort = process.env['METRICS_PORT'] || '9090';
+                        const metricsRes = await fetch(`http://localhost:${metricsPort}/metrics`);
+                        if (!metricsRes.ok)
+                            throw new Error(`Metrics server returned ${metricsRes.status}`);
+                        const text = await metricsRes.text();
+                        res.writeHead(200, {
+                            'Content-Type': 'text/plain; version=0.0.4; charset=utf-8',
+                            'Access-Control-Allow-Origin': '*',
+                        });
+                        res.end(text);
+                    }
+                    catch {
+                        writeJson(res, 200, { error: 'Metrics not available. Ensure METRICS_ENABLED=true and proxy is running.' });
+                    }
                 }
-                catch {
-                    res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ error: 'Metrics not available. Ensure METRICS_ENABLED=true and proxy is running.' }));
+                else {
+                    writeJson(res, 401, { error: 'Authentication required for metrics' });
+                }
+                return;
+            }
+            // ── Auth status check ───────────────────────────────
+            if (url === '/api/auth/status' && method === 'GET') {
+                setCors();
+                writeJson(res, 200, { authenticated: true, identity: authResult.identity, authEnabled });
+                return;
+            }
+            // ── Logout ──────────────────────────────────────────
+            if (url === '/api/logout' && method === 'POST') {
+                setCors();
+                const authHeader = req.headers['authorization'];
+                if (authHeader) {
+                    const match = authHeader.match(/^Bearer\s+(.+)$/i);
+                    if (match)
+                        auth.logout(match[1]);
                 }
+                writeJson(res, 200, { status: 'ok', message: 'Logged out' });
                 return;
             }
-            // ── 404 ─────────────────────────────────────────────────
-            res.writeHead(404, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Not found' }));
+            // ── 404 ──────────────────────────────────────────────
+            setCors();
+            writeJson(res, 404, { error: 'Not found' });
         }
         catch (err) {
-            res.writeHead(500, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: err?.message || 'Internal error' }));
+            setCors();
+            writeJson(res, 500, { error: err?.message || 'Internal error' });
         }
     });
     server.listen(port, () => {
-        Logger.info(`[dashboard] Dashboard available at http://localhost:${port}`);
+        Logger.info(`[dashboard] Dashboard available at http://localhost:${port}${authEnabled ? ' (auth enabled)' : ''}`);
     });
+    return { auth, server };
 }
 //# sourceMappingURL=dashboard-server.js.map

package/dist/utils/dashboard-server.js.map

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

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