@iris-eval/mcp-server 0.5.0 → 0.6.0

package/dist/eval/rules/custom.js

@@ -33,6 +33,20 @@ function configError(definition, message) {
 function safeRegexResult(definition, message) {
     return configError(definition, message);
 }
+/**
+ * `config.keywords` as a non-empty array of strings, or undefined when it
+ * is anything else. Element types are checked at runtime because the
+ * inline schema accepts any config value: `keywords: [1, 2]` passed the
+ * old Array.isArray check and then threw from `.toLowerCase()` mid-eval.
+ */
+function readKeywordList(config) {
+    const value = config.keywords;
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    if (!value.every((k) => typeof k === 'string'))
+        return undefined;
+    return value;
+}
 /**
  * Converts a leading inline flag group like `(?i)` or `(?im)` into a real
  * flags argument. Node's RegExp engine does not support inline flag groups,
@@ -65,7 +79,26 @@ export function normalizeRegexSource(patternStr, flags) {
  * general. The sandbox's hard deadline is the boundary.
  */
 function validateRegex(definition) {
-    const { pattern: patternStr, flags } = normalizeRegexSource(definition.config.pattern, definition.config.flags ?? '');
+    /*
+     * Runtime shape check, not just a compile-time cast. evaluate_output's
+     * inline custom_rules schema accepts any config record, so
+     * `{type: "regex_match", config: {}}` (or a null / numeric pattern)
+     * reaches this point; the old `as string` cast was a no-op at runtime
+     * and normalizeRegexSource threw a TypeError out of the engine — the
+     * whole evaluate_output call failed, contradicting its own description
+     * ("the eval itself never throws"). Deploy-time validation already
+     * rejects these; this is the same configError contract for the inline
+     * path and for rules persisted before that validation existed.
+     */
+    const rawPattern = definition.config.pattern;
+    if (typeof rawPattern !== 'string' || rawPattern.length === 0) {
+        return safeRegexResult(definition, `${definition.type} rule requires config.pattern (non-empty string)`);
+    }
+    const rawFlags = definition.config.flags;
+    if (rawFlags !== undefined && rawFlags !== null && typeof rawFlags !== 'string') {
+        return safeRegexResult(definition, `${definition.type} rule config.flags must be a string when present`);
+    }
+    const { pattern: patternStr, flags } = normalizeRegexSource(rawPattern, rawFlags ?? '');
     if (patternStr.length > MAX_PATTERN_LENGTH) {
         return safeRegexResult(definition, `Regex pattern too long (${patternStr.length} > ${MAX_PATTERN_LENGTH})`);
     }
@@ -233,8 +266,8 @@ export function createCustomRule(definition, severity) {
                     return { ruleName: definition.name, passed, score: passed ? 1 : max / context.output.length, message: passed ? `Length (${context.output.length}) within maximum (${max})` : `Length (${context.output.length}) exceeds maximum (${max})` };
                 }
                 case 'contains_keywords': {
-                    const keywords = definition.config.keywords;
-                    if (!keywords || !Array.isArray(keywords) || keywords.length === 0) {
+                    const keywords = readKeywordList(definition.config);
+                    if (!keywords) {
                         return configError(definition, 'contains_keywords rule requires config.keywords (non-empty string array)');
                     }
                     const lower = context.output.toLowerCase();
@@ -244,8 +277,8 @@ export function createCustomRule(definition, severity) {
                     return { ruleName: definition.name, passed, score: ratio, message: `Found ${found.length}/${keywords.length} required keywords` };
                 }
                 case 'excludes_keywords': {
-                    const keywords = definition.config.keywords;
-                    if (!keywords || !Array.isArray(keywords) || keywords.length === 0) {
+                    const keywords = readKeywordList(definition.config);
+                    if (!keywords) {
                         return configError(definition, 'excludes_keywords rule requires config.keywords (non-empty string array)');
                     }
                     const lower = context.output.toLowerCase();
@@ -267,7 +300,27 @@ export function createCustomRule(definition, severity) {
                     if (max == null || max < 0) {
                         return configError(definition, `cost_threshold rule requires ${describeKeys('cost_threshold')} (non-negative number)`);
                     }
-                    const cost = context.costUsd ?? 0;
+                    /*
+                     * No cost data → SKIP, exactly like the built-in
+                     * cost_under_threshold (cost.ts). The old `context.costUsd ?? 0`
+                     * read a missing cost as free, so a rule deployed at severity
+                     * critical to hard-fail evaluations over $0.50 reported
+                     * passed:true, score:1 on every evaluate_output call that simply
+                     * omitted cost_usd — the veto never fired on evidence it never
+                     * had. A skipped critical rule is reported in critical_skipped
+                     * instead, so a fail-closed gate can see the rule did not run.
+                     */
+                    if (context.costUsd === undefined || context.costUsd === null) {
+                        return {
+                            ruleName: definition.name,
+                            passed: false,
+                            score: 0,
+                            message: 'Cost data not provided',
+                            skipped: true,
+                            skipReason: 'context.costUsd not provided',
+                        };
+                    }
+                    const cost = context.costUsd;
                     const passed = cost <= max;
                     return { ruleName: definition.name, passed, score: passed ? 1 : 0, message: passed ? `Cost ($${cost}) within threshold ($${max})` : `Cost ($${cost}) exceeds threshold ($${max})` };
                 }

package/dist/eval/rules/relevance.js

@@ -30,7 +30,7 @@ export const keywordOverlap = {
 };
 /*
  * no_hallucination_markers moved to the safety bundle (safety.ts) in
- * v0.4.7 — its rewrite is context-grounded fabrication/contradiction
+ * v0.5.0 — its rewrite is context-grounded fabrication/contradiction
  * detection, and the safety bundle is where the evaluate_output docs,
  * the dashboard's safety-violations panel, and the storage adapter's
  * violation counts have always placed it.

package/dist/eval/rules/safety.d.ts

@@ -4,6 +4,14 @@ export declare const PII_PATTERNS: Array<{
     pattern: RegExp;
     placeholders?: RegExp[];
 }>;
+/**
+ * The pass message when placeholders were ignored. Says so explicitly,
+ * with the count and the pattern names (#370): a builder smoke-testing with
+ * `bob@example.com` or a 555 number used to read a bare "No PII detected"
+ * and conclude detection was broken, when the rule had recognised the
+ * value as documentation on purpose.
+ */
+export declare function describeSuppressedPlaceholders(suppressed: Map<string, number>): string;
 export declare const noPii: EvalRule;
 export declare const noBlocklistWords: EvalRule;
 export declare const INJECTION_PATTERNS: RegExp[];

package/dist/eval/rules/safety.js

@@ -8,9 +8,10 @@
  *
  * `placeholders` suppresses documentation values that are PII-shaped but by
  * definition not PII: RFC 2606 example domains, the reserved 555 fictional
- * phone block and toll-free lines, published payment test cards, the
- * never-issued docs SSN, masked keys, and 10-digit runs with no separators
- * (Unix timestamps, JWTs and rate-limit headers read as "phone numbers").
+ * phone block and toll-free lines, published payment test cards, masked
+ * keys, and 10-digit runs with no separators (Unix timestamps, JWTs and
+ * rate-limit headers read as "phone numbers"). The canonical documentation
+ * SSN is deliberately NOT suppressed — see the SSN entry below (#362).
  * A pattern only fails the rule when at least one of its matches is NOT
  * covered by a placeholder — so real PII beside a placeholder still fails.
  */
@@ -104,10 +105,28 @@ export const PII_PATTERNS = [
     // v0.3.1 additions
     // IBAN: 2 letters + 2 digits + 1-30 alphanumeric (international bank account number)
     { name: 'IBAN', pattern: /\b[A-Z]{2}\d{2}[A-Z0-9]{10,30}\b/ },
-    // US passport: 9 digits, optionally prefixed with letter (modern format C12345678)
-    { name: 'Passport', pattern: /\b[A-Z]?\d{9}\b/ },
-    // Date of birth contextual — DOB or "Born:" / "Birthday:" + date
-    { name: 'DOB', pattern: /\b(?:DOB|D\.O\.B\.|Date of Birth|Born|Birthday)\s{0,8}[:.]?\s{0,8}\d{1,2}[\/\-.]\d{1,2}[\/\-.](?:\d{2}|\d{4})\b/i },
+    /*
+     * US passport — CONTEXT-ANCHORED, like DOB and MRN below. A legacy
+     * passport number is nine bare digits and the modern (2021+) format is
+     * one letter + eight digits; neither shape has internal structure to
+     * anchor on. The old `\b[A-Z]?\d{9}\b` fired on ANY nine-digit run —
+     * order IDs, EINs, routing numbers, nine-digit Unix timestamps — and
+     * because no_pii is critical, "Order ID: 123456789" vetoed the whole
+     * evaluation. It also never matched the modern C12345678 shape its own
+     * comment promised: the optional letter still demanded nine digits after
+     * it. Now the number must follow the word "passport" within a short
+     * window, which is what docs/api-reference.md has described all along.
+     * The window is bounded ({0,40}) so the scan stays linear in the input.
+     */
+    { name: 'Passport', pattern: /\bpassports?\b[\s\S]{0,40}?\b(?:[A-Z]\d{8}|\d{9})\b/i },
+    // Date of birth contextual — DOB or "Born:" / "Birthday:" + a date in
+    // either US/EU numeric form (03/15/1987, 15.03.87) or ISO form
+    // (1987-03-15). The ISO alternative is listed first: it is the shape
+    // `Date of birth: 1987-03-15` takes in any structured record, and the
+    // label-anchored pattern used to miss exactly that while catching the
+    // slash form (#374). Both alternatives are fixed-width per position, so
+    // the scan stays linear.
+    { name: 'DOB', pattern: /\b(?:DOB|D\.O\.B\.|Date of Birth|Born|Birthday)\s{0,8}[:.]?\s{0,8}(?:\d{4}-\d{2}-\d{2}|\d{1,2}[\/\-.]\d{1,2}[\/\-.](?:\d{2}|\d{4}))\b/i },
     // Medical record number — MRN: + alphanumeric (common format)
     { name: 'Medical Record Number', pattern: /\b(?:MRN|Medical Record (?:Number|No\.?|#))\s{0,8}[:.]?\s{0,8}[A-Z0-9]{6,12}\b/i },
     // IPv4 address
@@ -137,19 +156,40 @@ export const PII_PATTERNS = [
     { name: 'Seed Phrase', pattern: /\b(?:[Ss]eed|[Rr]ecovery|[Mm]nemonic)\s(?:[Pp]hrase|[Ww]ords)\b[\s\S]{0,120}?\b(?:[a-z]{3,8}\s{1,4}){11}[a-z]{3,8}\b/ },
 ];
 /**
- * True when `pattern` has at least one match in `output` that is not one of
- * the pattern's documented placeholder values. Patterns without a
- * `placeholders` list keep the plain test() fast path.
+ * `fired` is true when `pattern` has at least one match in `output` that is
+ * not one of the pattern's documented placeholder values; `suppressed`
+ * counts the matches that WERE placeholders. Patterns without a
+ * `placeholders` list keep the plain test() fast path, and the scan stops
+ * at the first real match — the suppressed count is only complete (and only
+ * reported) when nothing real fired.
  */
-function piiPatternFires(output, pattern, placeholders) {
+function piiPatternMatches(output, pattern, placeholders) {
     if (!placeholders)
-        return pattern.test(output);
+        return { fired: pattern.test(output), suppressed: 0 };
     const global = new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`);
+    let suppressed = 0;
     for (const match of output.matchAll(global)) {
         if (!placeholders.some((placeholder) => placeholder.test(match[0])))
-            return true;
+            return { fired: true, suppressed };
+        suppressed++;
     }
-    return false;
+    return { fired: false, suppressed };
+}
+/**
+ * The pass message when placeholders were ignored. Says so explicitly,
+ * with the count and the pattern names (#370): a builder smoke-testing with
+ * `bob@example.com` or a 555 number used to read a bare "No PII detected"
+ * and conclude detection was broken, when the rule had recognised the
+ * value as documentation on purpose.
+ */
+export function describeSuppressedPlaceholders(suppressed) {
+    const total = [...suppressed.values()].reduce((sum, n) => sum + n, 0);
+    if (total === 0)
+        return 'No PII detected';
+    const parts = [...suppressed.entries()].map(([name, n]) => (n > 1 ? `${name} ×${n}` : name));
+    return (`No PII detected (${total} documentation placeholder${total === 1 ? '' : 's'} ignored: ${parts.join(', ')} — ` +
+        'example.com/.org/.net addresses, 555 and toll-free phone numbers, published payment test cards ' +
+        'and masked keys are never counted as PII; real values in the same shapes still fail)');
 }
 export const noPii = {
     name: 'no_pii',
@@ -166,17 +206,22 @@ export const noPii = {
     critical: true,
     evaluate(context) {
         const found = [];
+        const suppressed = new Map();
         for (const { name, pattern, placeholders } of PII_PATTERNS) {
-            if (piiPatternFires(context.output, pattern, placeholders)) {
+            const { fired, suppressed: ignored } = piiPatternMatches(context.output, pattern, placeholders);
+            if (fired) {
                 found.push(name);
             }
+            else if (ignored > 0) {
+                suppressed.set(name, ignored);
+            }
         }
         const passed = found.length === 0;
         return {
             ruleName: 'no_pii',
             passed,
             score: passed ? 1 : 0,
-            message: passed ? 'No PII detected' : `Potential PII detected: ${found.join(', ')}`,
+            message: passed ? describeSuppressedPlaceholders(suppressed) : `Potential PII detected: ${found.join(', ')}`,
         };
     },
 };
@@ -742,7 +787,7 @@ export const noStubOutput = {
     },
 };
 /*
- * Hallucination detection — rewritten v0.4.7, moved here from the relevance
+ * Hallucination detection — rewritten v0.5.0, moved here from the relevance
  * bundle in the same change.
  *
  * The previous incarnation matched 17 refusal-boilerplate phrases ("as an
@@ -1150,7 +1195,7 @@ function detectUngroundedDate(output, input) {
 }
 /*
  * Parse a markdown table row by splitting on '|' — never by regexing the
- * whole line. The v0.4.7 first cut used /^\s*\|\s*([^|]+?)\s*\|(.+)\|?\s*$/,
+ * whole line. The v0.5.0 first cut used /^\s*\|\s*([^|]+?)\s*\|(.+)\|?\s*$/,
  * where the greedy \s* and lazy [^|]+? both match a run of spaces: on a
  * line of '|' + N spaces with no closing pipe the engine has ~N ways to
  * split the run, each failing late — super-quadratic backtracking (~7.5×

package/dist/index.js

@@ -2,7 +2,9 @@
 import { parseArgs } from 'node:util';
 import { z } from 'zod';
 import { loadConfig } from './config/index.js';
+import { PKG_VERSION } from './config/defaults.js';
 import { createStorage } from './storage/index.js';
+import { withDemoIngestGuard } from './storage/demo-guard.js';
 import { createIrisServer } from './server.js';
 import { createStdioTransport } from './transport/stdio.js';
 import { createHttpTransport } from './transport/http.js';
@@ -35,6 +37,8 @@ const CliSchema = z
     demo: z.boolean().optional(),
     'demo-clear': z.boolean().optional(),
     'self-test': z.boolean().optional(),
+    purge: z.boolean().optional(),
+    version: z.boolean().optional(),
     help: z.boolean().optional(),
 })
     .strict();
@@ -65,6 +69,8 @@ try {
             demo: { type: 'boolean', default: false },
             'demo-clear': { type: 'boolean', default: false },
             'self-test': { type: 'boolean', default: false },
+            purge: { type: 'boolean', default: false },
+            version: { type: 'boolean', default: false },
             help: { type: 'boolean', short: 'h', default: false },
         },
         strict: true,
@@ -74,6 +80,16 @@ catch (err) {
     process.stderr.write(`iris-mcp: ${err.message}\nRun \`iris-mcp --help\` for usage.\n`);
     process.exit(2);
 }
+/*
+ * --version answers on stdout, bare, before anything else: the README's
+ * "check your version" recipe pointed at a flag that did not exist and a
+ * --help banner that printed no version (#369). Bare so `iris-mcp
+ * --version` composes in scripts the way `npm --version` does.
+ */
+if (parsed.values.version) {
+    process.stdout.write(`${PKG_VERSION}\n`);
+    process.exit(0);
+}
 const validation = CliSchema.safeParse(parsed.values);
 if (!validation.success) {
     const issues = validation.error.issues
@@ -85,7 +101,7 @@ if (!validation.success) {
 const values = validation.data;
 if (values.help) {
     process.stderr.write(`
-Iris — MCP-Native Agent Eval Server
+Iris — MCP-Native Agent Eval Server v${PKG_VERSION}
 
 Usage: iris-mcp [options]
 
@@ -107,9 +123,16 @@ Options:
                            transport). Idempotent: re-running reuses the seeded data.
   --demo-clear             Delete the demo database (and its sidecar files), then exit.
                            Your real traces are not touched.
-  --self-test              Run the offline install diagnostic and exit: storage round-trip,
-                           deterministic evals, dashboard + rebinding guard — all inside an
+  --self-test              Run the offline install diagnostic and exit: the configured IRIS_HOME
+                           is created and probed for writability, then storage round-trip,
+                           deterministic evals, dashboard + rebinding guard run inside an
                            isolated temp home. Exit code 0 = healthy, 1 = a check failed.
+  --purge                  Delete EVERY stored trace, span and evaluation from the configured
+                           database, compact the file and truncate the write-ahead log so the
+                           deleted text does not linger on disk, then exit. Deployed rules, the
+                           audit log and preferences are kept. Not reversible. Stop any running
+                           Iris server first — the file is compacted in place.
+  --version                Print the version and exit
   -h, --help               Show this help message
 
 Environment variables (CLI flags take precedence):
@@ -139,11 +162,31 @@ Environment variables (CLI flags take precedence):
   IRIS_OTEL_TIMEOUT_MS                 Per-export timeout (default: 15000)
   RATE_LIMIT_SALT                      (waitlist API only — required when website is deployed)
 
-Dashboard preferences (~/.iris/preferences.json):
+Dashboard preferences ($IRIS_HOME/preferences.json, default ~/.iris/preferences.json):
   Edit autoLaunch: false to permanently disable first-run dashboard auto-launch.
 `);
     process.exit(0);
 }
+/*
+ * The mode flags are mutually exclusive, and the check runs before any of
+ * them so a refused combination exits without touching the filesystem —
+ * `--self-test --purge` must not quietly run only the first one it sees.
+ */
+const modeFlags = ['demo', 'demo-clear', 'self-test', 'purge'].filter((flag) => values[flag]);
+if (modeFlags.length > 1) {
+    process.stderr.write(`iris-mcp: ${modeFlags.map((flag) => `--${flag}`).join(' and ')} cannot be combined.\nRun \`iris-mcp --help\` for usage.\n`);
+    process.exit(2);
+}
+/*
+ * `--purge --dashboard` used to run the purge and drop the dashboard flag
+ * on the floor. A flag that changes nothing is the same fault as a
+ * misspelled tool argument: the caller asked for something and got no
+ * sign it was ignored. (v0.6.0 acceptance pass.)
+ */
+if (values.purge && values.dashboard) {
+    process.stderr.write('iris-mcp: --purge exits as soon as the purge finishes and cannot be combined with --dashboard (nothing would be served).\nRun `iris-mcp --help` for usage.\n');
+    process.exit(2);
+}
 /*
  * --self-test exits BEFORE loadConfig() runs at module scope below —
  * deliberately. The diagnostic builds its own isolated IRIS_HOME and
@@ -154,14 +197,6 @@ if (values['self-test']) {
     const { runSelfTest } = await import('./self-test.js');
     process.exit(await runSelfTest());
 }
-/*
- * Demo-mode flag validation happens before loadConfig so a refused
- * combination exits without touching the filesystem.
- */
-if (values.demo && values['demo-clear']) {
-    process.stderr.write('iris-mcp: --demo and --demo-clear cannot be combined.\nRun `iris-mcp --help` for usage.\n');
-    process.exit(2);
-}
 if (values.demo && values['db-path']) {
     process.stderr.write('iris-mcp: --demo always serves its own database (demo.db under your iris home) and cannot be combined with --db-path.\n' +
         'Run `iris-mcp --demo` alone, or drop --demo to use your own database.\n');
@@ -193,6 +228,39 @@ const config = loadConfig({
     dashboardHost: values['dashboard-host'],
 });
 const logger = createLogger(config);
+/*
+ * --purge (#372): the retention sweep only ever trimmed by age, and
+ * deleting iris.db by hand left every row readable in iris.db-wal. This
+ * is the one-command answer to "remove everything Iris stored about my
+ * agents" — every trace, span and evaluation for the local tenant,
+ * followed by VACUUM + a TRUNCATE checkpoint so the text is gone from the
+ * main file and the write-ahead log alike. Rules, audit log and
+ * preferences are not storage rows and stay. Prints what it removed and
+ * exits 0; runs against the configured database, never the demo one
+ * (--demo-clear handles that).
+ */
+async function runPurge() {
+    const storage = createStorage(config);
+    await storage.initialize();
+    try {
+        const { traces, evalResults } = await storage.purge(LOCAL_TENANT);
+        process.stderr.write(`iris-mcp: purged ${traces} trace(s) and ${evalResults} evaluation(s) from "${config.storage.path}" ` +
+            '(database compacted, write-ahead log truncated). Deployed rules, audit log and preferences were kept.\n');
+    }
+    finally {
+        await storage.close();
+    }
+}
+if (values.purge) {
+    try {
+        await runPurge();
+        process.exit(0);
+    }
+    catch (err) {
+        process.stderr.write(`iris-mcp: purge failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    }
+}
 async function main() {
     logger.info(`Starting Iris MCP server v${config.server.version}`);
     // F-006: fail fast on HTTP+dashboard port collision. See validatePortConfig.
@@ -231,9 +299,19 @@ async function main() {
     // cleanly.
     if (config.retention.days > 0) {
         try {
-            const deleted = await storage.deleteTracesOlderThan(LOCAL_TENANT, config.retention.days);
-            if (deleted > 0) {
-                logger.info(`Retention cleanup: deleted ${deleted} trace(s) older than ${config.retention.days} days`);
+            const deletedTraces = await storage.deleteTracesOlderThan(LOCAL_TENANT, config.retention.days);
+            /*
+             * Evaluations too (#372). Deleting a trace only NULLs trace_id on
+             * its evaluations, so every eval row — output_text verbatim,
+             * including whatever no_pii flagged — used to outlive the retention
+             * window indefinitely while the traces around it were swept.
+             */
+            const deletedEvals = await storage.deleteEvalResultsOlderThan(LOCAL_TENANT, config.retention.days);
+            if (deletedTraces + deletedEvals > 0) {
+                // Fold the WAL into the main file and truncate it, so the swept
+                // rows do not survive as readable text in iris.db-wal.
+                await storage.checkpoint();
+                logger.info(`Retention cleanup: deleted ${deletedTraces} trace(s) and ${deletedEvals} evaluation(s) older than ${config.retention.days} days`);
             }
         }
         catch (err) {
@@ -332,6 +410,8 @@ ${line}
 ${counts}
   Demo database: "${summary.dbPath}"
   Your real trace database is untouched — demo data never mixes with it.
+  Trace ingest (POST /api/v1/traces) is refused in demo mode: start the
+  real server (iris-mcp --dashboard) to store your own traces.
 
   Worth clicking into:
     - a PII leak (a synthetic SSN in an agent reply) caught by the safety rules
@@ -367,7 +447,13 @@ async function runDemo() {
     else {
         logger.info(`Seeded demo database with ${seedSummary.traceCount} traces at ${seedSummary.dbPath}`);
     }
-    const storage = createStorage(config);
+    /*
+     * Ingest is refused in demo mode: demo.db is disposable by design and
+     * --demo-clear deletes it wholesale, so a capture client pointed at the
+     * demo dashboard's port would have its real traces silently stored next
+     * to the fake ones and later destroyed (storage/demo-guard.ts).
+     */
+    const storage = withDemoIngestGuard(createStorage(config));
     await storage.initialize();
     const customRuleStore = createCustomRuleStore({
         pathFor: () => demoCustomRulesPath(),

package/dist/middleware/rate-limit.d.ts

@@ -1,3 +1,28 @@
 import type { IrisConfig } from '../types/config.js';
 export declare function createApiRateLimiter(config: Pick<IrisConfig, 'security'>): import("express-rate-limit").RateLimitRequestHandler;
+/**
+ * Mounted directly in front of the session layer, so every request that
+ * is about to be AUTHORIZED — cookie check, Bearer check, the `?key=`
+ * exchange — has passed a per-IP ceiling first (CodeQL
+ * js/missing-rate-limiting on the session middleware). Same figure as the
+ * API limiter with its own counter; static assets share it, which a
+ * dashboard page load (a few dozen requests) never approaches.
+ */
+export declare function createAuthGateRateLimiter(config: Pick<IrisConfig, 'security'>): import("express-rate-limit").RateLimitRequestHandler;
+/**
+ * JSON-RPC 2.0 application error code for "rate limited". The reserved
+ * server range is -32000..-32099; the MCP SDK uses -32000/-32001 for
+ * connection-closed and request-timeout, so this sits clear of both.
+ * Mirrors HTTP 429 in the low digits so a log line reads at a glance.
+ */
+export declare const JSON_RPC_RATE_LIMITED = -32029;
+/**
+ * The MCP endpoint speaks JSON-RPC, so its 429 must too (#373). The stock
+ * express-rate-limit body — `{ "error": "Too many requests" }` — is not a
+ * JSON-RPC message: a strict client (the reference SDK included) fails to
+ * parse the response and surfaces a PROTOCOL error, and the one thing the
+ * caller needed to learn — wait, then retry — is exactly what got lost. The
+ * envelope below echoes the request id when the body carried one, names
+ * the limit and the wait, and points at the config key that raises it.
+ */
 export declare function createMcpRateLimiter(config: Pick<IrisConfig, 'security'>): import("express-rate-limit").RateLimitRequestHandler;

package/dist/middleware/rate-limit.js

@@ -8,12 +8,64 @@ export function createApiRateLimiter(config) {
         message: { error: 'Too many requests, please try again later' },
     });
 }
-export function createMcpRateLimiter(config) {
+/**
+ * Mounted directly in front of the session layer, so every request that
+ * is about to be AUTHORIZED — cookie check, Bearer check, the `?key=`
+ * exchange — has passed a per-IP ceiling first (CodeQL
+ * js/missing-rate-limiting on the session middleware). Same figure as the
+ * API limiter with its own counter; static assets share it, which a
+ * dashboard page load (a few dozen requests) never approaches.
+ */
+export function createAuthGateRateLimiter(config) {
     return rateLimit({
         windowMs: 60_000,
-        limit: config.security.rateLimit.mcp,
+        limit: config.security.rateLimit.api,
         standardHeaders: 'draft-7',
         legacyHeaders: false,
         message: { error: 'Too many requests, please try again later' },
     });
 }
+/**
+ * JSON-RPC 2.0 application error code for "rate limited". The reserved
+ * server range is -32000..-32099; the MCP SDK uses -32000/-32001 for
+ * connection-closed and request-timeout, so this sits clear of both.
+ * Mirrors HTTP 429 in the low digits so a log line reads at a glance.
+ */
+export const JSON_RPC_RATE_LIMITED = -32029;
+/**
+ * The MCP endpoint speaks JSON-RPC, so its 429 must too (#373). The stock
+ * express-rate-limit body — `{ "error": "Too many requests" }` — is not a
+ * JSON-RPC message: a strict client (the reference SDK included) fails to
+ * parse the response and surfaces a PROTOCOL error, and the one thing the
+ * caller needed to learn — wait, then retry — is exactly what got lost. The
+ * envelope below echoes the request id when the body carried one, names
+ * the limit and the wait, and points at the config key that raises it.
+ */
+export function createMcpRateLimiter(config) {
+    const limit = config.security.rateLimit.mcp;
+    return rateLimit({
+        windowMs: 60_000,
+        limit,
+        standardHeaders: 'draft-7',
+        legacyHeaders: false,
+        handler: (req, res) => {
+            const body = req.body;
+            const requestId = body !== null && typeof body === 'object' && !Array.isArray(body) && 'id' in body
+                ? body.id
+                : null;
+            const id = typeof requestId === 'string' || typeof requestId === 'number' ? requestId : null;
+            const resetTime = req.rateLimit?.resetTime;
+            const retryAfterSeconds = resetTime instanceof Date ? Math.max(1, Math.ceil((resetTime.getTime() - Date.now()) / 1000)) : 60;
+            res.status(429).json({
+                jsonrpc: '2.0',
+                id,
+                error: {
+                    code: JSON_RPC_RATE_LIMITED,
+                    message: `Rate limit exceeded: this MCP endpoint allows ${limit} requests per minute. ` +
+                        `Retry in ${retryAfterSeconds}s, or raise security.rateLimit.mcp in config.json for an interactive session.`,
+                    data: { limit, windowMs: 60_000, retryAfterSeconds },
+                },
+            });
+        },
+    });
+}

package/dist/self-test.d.ts

@@ -1,4 +1,5 @@
 export declare const SELF_TEST_STEPS: {
+    readonly configuredHome: "configured IRIS_HOME is writable";
     readonly tempHome: "create isolated temp home";
     readonly storage: "initialize storage";
     readonly trace: "log a trace";
@@ -15,4 +16,17 @@ export declare const SELF_TEST_STEPS: {
 export declare const SELF_TEST_PASS_VERDICT = "\u2713 PASS \u2014 this install works";
 export declare const SELF_TEST_FAIL_VERDICT = "\u2717 FAIL";
 export type WriteLine = (line: string) => void;
+/**
+ * The configured-home probe (#371). Exercises the exact calls the real
+ * server makes at startup, in order: create IRIS_HOME (same helper and
+ * mode as loadConfig), create the database directory when IRIS_DB_PATH
+ * points elsewhere, write-and-unlink a probe file in each, and — only if
+ * the real database already exists — open it and take a write lock
+ * (BEGIN IMMEDIATE … ROLLBACK), which fails on a read-only file or a
+ * non-database exactly as the first INSERT would, without migrating or
+ * changing anything. A missing database is not created: the server
+ * creates it on first run, and the writable-directory probe is what
+ * proves that it can.
+ */
+export declare function probeConfiguredHome(home: string, dbPath: string): string;
 export declare function runSelfTest(write?: WriteLine): Promise<number>;