@stackwright-pro/mcp 0.2.0-alpha.3 → 0.2.0-alpha.30

package/README.md

@@ -0,0 +1,236 @@
+# @stackwright-pro/mcp
+
+The MCP server that powers the Pro Otter Raft. Exposes 30 deterministic TypeScript tools to Claude Code and other MCP clients for structured pipeline orchestration, artifact validation, and controlled file I/O.
+
+---
+
+## Architecture: Sinks Not Pipes
+
+When the Otter Raft scaled past nine concurrent agents, the foreman's context window became the bottleneck. Every specialist was shovelling its output back into the conversation, bloating the shared context until the whole raft flipped. Coordination collapsed: later otters couldn't reliably read what earlier otters had produced, and the foreman had no authoritative record of what was actually done versus what was merely narrated.
+
+The fix is a single discipline: **every intermediate result is a file on disk; MCP tools are the only I/O interface**. Otters never write anything directly — they call a tool, the tool validates and writes, and the next otter reads via another tool. The foreman never accumulates state in memory; it reads the current truth from disk on every step. This makes the pipeline inspectable, resumable, and safe to parallelize — because there is nothing to lose when a context window expires.
+
+```
+.stackwright/
+├── init-context.json          ← launcher writes once
+├── pipeline-state.json        ← set_pipeline_state
+├── questions/{phase}.json     ← write_phase_questions
+├── answers/{phase}.json       ← save_phase_answers
+└── artifacts/{output}.json    ← validate_artifact (the chokepoint)
+```
+
+---
+
+## Tools Reference
+
+### Pipeline State & Control
+
+Sourced from `registerPipelineTools` (`tools/pipeline.ts`).
+
+| Tool                                    | Purpose                                        | Reads                              | Writes                             |
+| --------------------------------------- | ---------------------------------------------- | ---------------------------------- | ---------------------------------- |
+| `stackwright_pro_get_pipeline_state`    | Read current pipeline state                    | `.stackwright/pipeline-state.json` | —                                  |
+| `stackwright_pro_set_pipeline_state`    | Update phase field or top-level status         | `.stackwright/pipeline-state.json` | `.stackwright/pipeline-state.json` |
+| `stackwright_pro_check_execution_ready` | Gate: true only when all 8 phases have answers | `.stackwright/answers/`            | —                                  |
+| `stackwright_pro_list_artifacts`        | Inventory of completed specialist outputs      | `.stackwright/artifacts/`          | —                                  |
+
+---
+
+### Question Collection
+
+Sourced from `registerPipelineTools` (`tools/pipeline.ts`), `registerQuestionTools` (`tools/questions.ts`), and `registerOrchestrationTools` (`tools/orchestration.ts`).
+
+| Tool                                      | Purpose                                                          | Reads                                 | Writes                                |
+| ----------------------------------------- | ---------------------------------------------------------------- | ------------------------------------- | ------------------------------------- |
+| `stackwright_pro_write_phase_questions`   | Parse otter `QUESTION_COLLECTION_MODE` response and sink to disk | —                                     | `.stackwright/questions/{phase}.json` |
+| `stackwright_pro_present_phase_questions` | Adapt questions for `ask_user_question` format                   | `.stackwright/questions/{phase}.json` | —                                     |
+| `stackwright_pro_save_phase_answers`      | Sink user answers to disk                                        | —                                     | `.stackwright/answers/{phase}.json`   |
+| `stackwright_pro_read_phase_answers`      | Read answers for a phase                                         | `.stackwright/answers/{phase}.json`   | —                                     |
+
+---
+
+### Specialist Execution
+
+Sourced from `registerPipelineTools` (`tools/pipeline.ts`) and `registerOrchestrationTools` (`tools/orchestration.ts`).
+
+| Tool                                      | Purpose                                                       | Reads                                         | Writes                                |
+| ----------------------------------------- | ------------------------------------------------------------- | --------------------------------------------- | ------------------------------------- |
+| `stackwright_pro_build_specialist_prompt` | Assemble answers + upstream artifacts into specialist prompt  | `answers/{phase}.json`, upstream `artifacts/` | —                                     |
+| `stackwright_pro_validate_artifact`       | Validate specialist output, detect off-script, write if valid | —                                             | `.stackwright/artifacts/{phase}.json` |
+| `stackwright_pro_get_otter_name`          | Resolve phase name → otter agent name                         | —                                             | —                                     |
+| `stackwright_pro_parse_otter_response`    | Extract JSON from otter response text                         | —                                             | —                                     |
+| `stackwright_pro_save_manifest`           | Write consolidated question manifest (legacy path)            | —                                             | `.stackwright/question-manifest.json` |
+
+---
+
+### Controlled File I/O
+
+Sourced from `registerSafeWriteTools` (`tools/safe-write.ts`).
+
+| Tool                         | Purpose                                                                             | Reads | Writes                 |
+| ---------------------------- | ----------------------------------------------------------------------------------- | ----- | ---------------------- |
+| `stackwright_pro_safe_write` | Per-otter path allowlist enforcement — the only way specialists write content files | —     | Allowlisted paths only |
+
+---
+
+### Domain Knowledge
+
+Sourced from `registerDomainTools` (`tools/domain.ts`).
+
+| Tool                                    | Purpose                                         | Reads                                                         | Writes |
+| --------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------- | ------ |
+| `stackwright_pro_list_collections`      | List API-backed collections for page generation | `.stackwright/artifacts/data-config.json` → `stackwright.yml` | —      |
+| `stackwright_pro_resolve_data_strategy` | Deterministic data freshness strategy lookup    | —                                                             | —      |
+| `stackwright_pro_validate_workflow`     | Validate workflow.yml graph structure           | `.stackwright/artifacts/workflow-config.json`                 | —      |
+
+---
+
+### Integrity
+
+Sourced from `registerIntegrityTools` (`integrity.ts`).
+
+| Tool                                     | Purpose                                                         | Reads                              | Writes |
+| ---------------------------------------- | --------------------------------------------------------------- | ---------------------------------- | ------ |
+| `stackwright_pro_verify_otter_integrity` | SHA-256 certificate-pinned verification of all otter JSON files | `packages/otters/src/*-otter.json` | —      |
+
+---
+
+### Data Explorer
+
+Sourced from `registerDataExplorerTools` (`tools/data-explorer.ts`).
+
+| Tool                              | Purpose                             |
+| --------------------------------- | ----------------------------------- |
+| `stackwright_pro_list_entities`   | List API entities from OpenAPI spec |
+| `stackwright_pro_generate_filter` | Generate endpoint filter config     |
+
+---
+
+### Security
+
+Sourced from `registerSecurityTools` (`tools/security.ts`).
+
+| Tool                                  | Purpose                                     |
+| ------------------------------------- | ------------------------------------------- |
+| `stackwright_pro_validate_spec`       | Validate OpenAPI spec against approved list |
+| `stackwright_pro_add_approved_spec`   | Add spec to approved list                   |
+| `stackwright_pro_list_approved_specs` | List approved specs                         |
+
+---
+
+### ISR Configuration
+
+Sourced from `registerIsrTools` (`tools/isr.ts`).
+
+| Tool                                  | Purpose                                |
+| ------------------------------------- | -------------------------------------- |
+| `stackwright_pro_configure_isr`       | Configure ISR for a single collection  |
+| `stackwright_pro_configure_isr_batch` | Configure ISR for multiple collections |
+
+---
+
+### Auth
+
+Sourced from `registerAuthTools` (`tools/auth.ts`).
+
+| Tool                             | Purpose                                       |
+| -------------------------------- | --------------------------------------------- |
+| `stackwright_pro_configure_auth` | Generate auth middleware from provider config |
+
+---
+
+### Clarification
+
+Sourced from `registerClarificationTools` (`tools/clarification.ts`).
+
+| Tool                              | Purpose                                |
+| --------------------------------- | -------------------------------------- |
+| `stackwright_pro_clarify`         | Surface mid-execution question to user |
+| `stackwright_pro_detect_conflict` | Detect conflicting user preferences    |
+
+---
+
+### Packages
+
+Sourced from `registerPackageTools` (`tools/packages.ts`).
+
+| Tool                             | Purpose                        |
+| -------------------------------- | ------------------------------ |
+| `stackwright_pro_setup_packages` | Bootstrap Pro npm dependencies |
+
+---
+
+### Dashboard Generation
+
+Sourced from `registerDashboardTools` (`tools/dashboard.ts`).
+
+| Tool                                   | Purpose                      |
+| -------------------------------------- | ---------------------------- |
+| `stackwright_pro_generate_dashboard`   | Generate dashboard page spec |
+| `stackwright_pro_generate_detail_page` | Generate detail page spec    |
+
+---
+
+## Security Model
+
+Three layers keep the raft from sinking:
+
+1. **Per-otter path allowlists** — `stackwright_pro_safe_write` enforces that each specialist otter can only write to approved paths. `page-otter` is limited to `pages/*/content.yml`; `auth-otter` is limited to `config/*.yml` and `.env*`. Attempts to write outside the allowlist are rejected with an error — the otter never touches the filesystem directly.
+
+2. **Artifact validation chokepoint** — specialists never write artifacts directly. All specialist output flows through `stackwright_pro_validate_artifact`, which validates the JSON structure and detects off-script code output (e.g. raw TypeScript or markdown smuggled inside a JSON field) before the file is committed. Bad output is rejected and the phase stays incomplete.
+
+3. **Certificate-pinned integrity** — canonical SHA-256 checksums for all otter JSON prompt files are hardcoded inside this MCP package. `stackwright_pro_verify_otter_integrity` re-hashes every file in `packages/otters/src/*-otter.json` at runtime and compares against the pinned values. A modified or tampered otter file is rejected before its prompt ever reaches an LLM.
+
+---
+
+## Phase Dependency Graph
+
+The pipeline enforces this dependency order. A phase cannot begin specialist execution until all of its upstream phases have committed artifacts.
+
+```
+designer ──────────────────────────────┐
+api ────────────────────────────────┐  │
+auth ───────────────────────────┐   │  │
+                                │   │  │
+data    ← api                   │   │  │
+theme   ← designer              │   │  │
+pages   ← designer, theme, api, data, auth
+dashboard ← designer, theme, api, data
+workflow  ← auth
+```
+
+---
+
+## Integrity
+
+The full integrity enforcement model is documented in [docs/INTEGRITY_MODEL.md](docs/INTEGRITY_MODEL.md), including certificate pinning at startup, known enforcement gaps, and the threat model table for each pipeline component.
+
+```bash
+# The MCP server is configured automatically by the launcher
+npx @stackwright-pro/launch-stackwright-pro
+
+# Or manually in claude_desktop_config.json / .mcp.json:
+{
+  "mcpServers": {
+    "stackwright-pro": {
+      "command": "node",
+      "args": ["node_modules/@stackwright-pro/mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+---
+
+## Development
+
+```bash
+pnpm --filter @stackwright-pro/mcp test
+pnpm --filter @stackwright-pro/mcp build
+```
+
+---
+
+## License
+
+Proprietary — Per Aspera LLC

package/dist/integrity.d.mts

@@ -0,0 +1,32 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/** Compute the hex-encoded SHA-256 digest of raw bytes. Pure, no I/O. */
+declare function computeSha256(data: Buffer): string;
+interface VerifyOtterFileResult {
+    verified: boolean;
+    filename: string;
+    error?: string;
+}
+/**
+ * Read a single otter JSON file, check its size, compute its SHA-256,
+ * and constant-time compare against the canonical checksum.
+ *
+ * Single read → hash → decode. No TOCTOU window.
+ */
+declare function verifyOtterFile(filePath: string): VerifyOtterFileResult;
+interface VerifyAllOttersResult {
+    verified: string[];
+    failed: Array<{
+        filename: string;
+        error: string;
+    }>;
+    unknown: string[];
+}
+/**
+ * Scan a directory for `*-otter.json` files, verify each one against
+ * canonical checksums. Returns lists of verified, failed, and unknown files.
+ */
+declare function verifyAllOtters(otterDir: string): VerifyAllOttersResult;
+declare function registerIntegrityTools(server: McpServer): void;
+
+export { type VerifyAllOttersResult, type VerifyOtterFileResult, computeSha256, registerIntegrityTools, verifyAllOtters, verifyOtterFile };

package/dist/integrity.d.ts

@@ -0,0 +1,32 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/** Compute the hex-encoded SHA-256 digest of raw bytes. Pure, no I/O. */
+declare function computeSha256(data: Buffer): string;
+interface VerifyOtterFileResult {
+    verified: boolean;
+    filename: string;
+    error?: string;
+}
+/**
+ * Read a single otter JSON file, check its size, compute its SHA-256,
+ * and constant-time compare against the canonical checksum.
+ *
+ * Single read → hash → decode. No TOCTOU window.
+ */
+declare function verifyOtterFile(filePath: string): VerifyOtterFileResult;
+interface VerifyAllOttersResult {
+    verified: string[];
+    failed: Array<{
+        filename: string;
+        error: string;
+    }>;
+    unknown: string[];
+}
+/**
+ * Scan a directory for `*-otter.json` files, verify each one against
+ * canonical checksums. Returns lists of verified, failed, and unknown files.
+ */
+declare function verifyAllOtters(otterDir: string): VerifyAllOttersResult;
+declare function registerIntegrityTools(server: McpServer): void;
+
+export { type VerifyAllOttersResult, type VerifyOtterFileResult, computeSha256, registerIntegrityTools, verifyAllOtters, verifyOtterFile };

package/dist/integrity.js

@@ -0,0 +1,252 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/integrity.ts
+var integrity_exports = {};
+__export(integrity_exports, {
+  computeSha256: () => computeSha256,
+  registerIntegrityTools: () => registerIntegrityTools,
+  verifyAllOtters: () => verifyAllOtters,
+  verifyOtterFile: () => verifyOtterFile
+});
+module.exports = __toCommonJS(integrity_exports);
+var import_crypto = require("crypto");
+var import_fs = require("fs");
+var import_path = require("path");
+var _checksums = /* @__PURE__ */ new Map([
+  [
+    "stackwright-pro-api-otter.json",
+    "0ac26d85a5ad35b072a58965e1d5e090dd5c5f16dc14e68c452c3e99fcbb5510"
+  ],
+  [
+    "stackwright-pro-auth-otter.json",
+    "e4314897e7dead94cbd07cf58cd9df1a2614a207c85bdddf9259121945903721"
+  ],
+  [
+    "stackwright-pro-dashboard-otter.json",
+    "600e8597429c353e5b886f316731be84a86cd8b93617bf046e3cbf390b31a431"
+  ],
+  [
+    "stackwright-pro-data-otter.json",
+    "08352843c3dbfd1e20171493fb95ae7c73fde9dca0e2d6eecb5dc2d7d7b3cda7"
+  ],
+  [
+    "stackwright-pro-designer-otter.json",
+    "f4dbff5149051c77be1645de5ee12c0bd7d590c687a0b2d86737b915a5a6d5f0"
+  ],
+  [
+    "stackwright-pro-foreman-otter.json",
+    "e361cc30f013e1e423ebb4f59c54fd1452d049fabcc0539ce56b4a49cb5ec3ea"
+  ],
+  [
+    "stackwright-pro-page-otter.json",
+    "0323d9c9f4b4008b516d7615f24c0ebab9470bdf9cd37e1d48cfc06ccf6fccee"
+  ],
+  [
+    "stackwright-pro-theme-otter.json",
+    "a303ec6c045420f2c916583e3f6efcda469e9610fedfc84a508ed8a8a75866bc"
+  ],
+  [
+    "stackwright-pro-workflow-otter.json",
+    "ec203f222b2771f2bc3b29f340d881480c6a23188667e533476f4245e78453ef"
+  ]
+]);
+Object.freeze(_checksums);
+var CANONICAL_CHECKSUMS = _checksums;
+var SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+for (const [name, digest] of CANONICAL_CHECKSUMS) {
+  if (!SHA256_HEX_RE.test(digest)) {
+    throw new Error(
+      `Malformed SHA-256 in CANONICAL_CHECKSUMS for "${name}": expected 64 hex chars, got ${digest.length}: "${digest}"`
+    );
+  }
+}
+var MAX_OTTER_BYTES = 1 * 1024 * 1024;
+function computeSha256(data) {
+  return (0, import_crypto.createHash)("sha256").update(data).digest("hex");
+}
+function safeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  return (0, import_crypto.timingSafeEqual)(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+function verifyOtterFile(filePath) {
+  const filename = (0, import_path.basename)(filePath);
+  const expected = CANONICAL_CHECKSUMS.get(filename);
+  if (expected === void 0) {
+    return { verified: false, filename, error: `Unknown otter file: not in canonical set` };
+  }
+  let stat;
+  try {
+    stat = (0, import_fs.lstatSync)(filePath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { verified: false, filename, error: `Cannot stat file: ${msg}` };
+  }
+  if (stat.isSymbolicLink()) {
+    return { verified: false, filename, error: "Refusing to verify symlink" };
+  }
+  const size = stat.size;
+  if (size > MAX_OTTER_BYTES) {
+    return {
+      verified: false,
+      filename,
+      error: `File exceeds size limit (${MAX_OTTER_BYTES.toLocaleString()} bytes, got ${size.toLocaleString()})`
+    };
+  }
+  let raw;
+  try {
+    raw = (0, import_fs.readFileSync)(filePath);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { verified: false, filename, error: `Cannot read file: ${msg}` };
+  }
+  if (raw.length > MAX_OTTER_BYTES) {
+    return {
+      verified: false,
+      filename,
+      error: `File exceeds size limit after read (${MAX_OTTER_BYTES.toLocaleString()} bytes, got ${raw.length.toLocaleString()})`
+    };
+  }
+  const actual = computeSha256(raw);
+  if (!safeEqual(actual, expected)) {
+    return {
+      verified: false,
+      filename,
+      error: `SHA-256 mismatch: expected ${expected.substring(0, 8)}\u2026, got ${actual.substring(0, 8)}\u2026`
+    };
+  }
+  try {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    decoder.decode(raw);
+  } catch {
+    return {
+      verified: false,
+      filename,
+      error: "File is not valid UTF-8 \u2014 may be corrupted or contain binary injection"
+    };
+  }
+  return { verified: true, filename };
+}
+function verifyAllOtters(otterDir) {
+  const verified = [];
+  const failed = [];
+  const unknown = [];
+  let entries;
+  try {
+    entries = (0, import_fs.readdirSync)(otterDir);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      verified: [],
+      failed: [{ filename: "<directory>", error: `Cannot read directory: ${msg}` }],
+      unknown: []
+    };
+  }
+  const otterFiles = entries.filter((f) => f.endsWith("-otter.json"));
+  for (const filename of otterFiles) {
+    const filePath = (0, import_path.join)(otterDir, filename);
+    try {
+      if ((0, import_fs.lstatSync)(filePath).isSymbolicLink()) {
+        failed.push({ filename, error: "Skipped: symlink" });
+        continue;
+      }
+    } catch {
+    }
+    const result = verifyOtterFile(filePath);
+    if (result.verified) {
+      verified.push(result.filename);
+    } else if (result.error?.startsWith("Unknown otter file")) {
+      unknown.push(result.filename);
+    } else {
+      failed.push({ filename: result.filename, error: result.error ?? "Unknown error" });
+    }
+  }
+  for (const canonicalName of CANONICAL_CHECKSUMS.keys()) {
+    if (!otterFiles.includes(canonicalName)) {
+      failed.push({ filename: canonicalName, error: "Missing from directory" });
+    }
+  }
+  return { verified, failed, unknown };
+}
+var DEFAULT_SEARCH_PATHS = ["node_modules/@stackwright-pro/otters/src/", "packages/otters/src/"];
+function resolveOtterDir() {
+  const cwd = process.cwd();
+  for (const relative of DEFAULT_SEARCH_PATHS) {
+    const candidate = (0, import_path.join)(cwd, relative);
+    try {
+      (0, import_fs.lstatSync)(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  return null;
+}
+function registerIntegrityTools(server) {
+  server.tool(
+    "stackwright_pro_verify_otter_integrity",
+    "Verify SHA-256 integrity of all Pro otter agent definitions. Call this at startup before discovering otters. Auto-discovers the otter directory from known paths. Returns verified/failed/unknown lists.",
+    {},
+    async () => {
+      const resolved = resolveOtterDir();
+      if (!resolved) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                error: true,
+                message: "Could not locate otter directory. Searched: " + DEFAULT_SEARCH_PATHS.join(", ")
+              })
+            }
+          ],
+          isError: true
+        };
+      }
+      const result = verifyAllOtters(resolved);
+      const allGood = result.failed.length === 0 && result.unknown.length === 0;
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              otterDir: resolved,
+              totalCanonical: CANONICAL_CHECKSUMS.size,
+              verifiedCount: result.verified.length,
+              failedCount: result.failed.length,
+              unknownCount: result.unknown.length,
+              verified: result.verified,
+              failed: result.failed,
+              unknown: result.unknown,
+              warning: result.failed.length > 0 ? "SHA-256 mismatches detected (non-blocking). PKI-signed manifest support coming soon." : void 0
+            })
+          }
+        ],
+        isError: false
+      };
+    }
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  computeSha256,
+  registerIntegrityTools,
+  verifyAllOtters,
+  verifyOtterFile
+});
+//# sourceMappingURL=integrity.js.map

package/dist/integrity.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/integrity.ts"],"sourcesContent":["/**\n * Otter Integrity Verification\n * ============================\n * Protects the Pro Otter Raft from disk-based prompt injection / jailbreak attacks.\n *\n * TypeScript port of python/src/stackwright_pro/raft/integrity.py — this lets\n * the MCP package verify otter files without a Python dependency.\n *\n * Certificate-pinned canonical checksums — hardcoded in the MCP package.\n *\n * These are NOT read from disk. An attacker who modifies otter JSON files\n * in @stackwright-pro/otters cannot also modify these constants without\n * compromising the separately-published @stackwright-pro/mcp package.\n *\n * To update: node scripts/sync-mcp-checksums.cjs\n * (reads from packages/otters/src/checksums.json, writes this file)\n */\nimport { createHash, timingSafeEqual } from 'crypto';\nimport { readFileSync, readdirSync, lstatSync } from 'fs';\nimport { join, basename } from 'path';\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\n\n// ---------------------------------------------------------------------------\n// Certificate-pinned canonical checksums — frozen Map, immutable by design.\n// DO NOT read these from disk — that would defeat the entire purpose.\n// Object.freeze prevents property mutation at runtime; ReadonlyMap prevents\n// .set() / .delete() at compile time (belt-and-suspenders).\n// ---------------------------------------------------------------------------\n\nconst _checksums = new Map<string, string>([\n  [\n    'stackwright-pro-api-otter.json',\n    '0ac26d85a5ad35b072a58965e1d5e090dd5c5f16dc14e68c452c3e99fcbb5510',\n  ],\n  [\n    'stackwright-pro-auth-otter.json',\n    'e4314897e7dead94cbd07cf58cd9df1a2614a207c85bdddf9259121945903721',\n  ],\n  [\n    'stackwright-pro-dashboard-otter.json',\n    '600e8597429c353e5b886f316731be84a86cd8b93617bf046e3cbf390b31a431',\n  ],\n  [\n    'stackwright-pro-data-otter.json',\n    '08352843c3dbfd1e20171493fb95ae7c73fde9dca0e2d6eecb5dc2d7d7b3cda7',\n  ],\n  [\n    'stackwright-pro-designer-otter.json',\n    'f4dbff5149051c77be1645de5ee12c0bd7d590c687a0b2d86737b915a5a6d5f0',\n  ],\n  [\n    'stackwright-pro-foreman-otter.json',\n    'e361cc30f013e1e423ebb4f59c54fd1452d049fabcc0539ce56b4a49cb5ec3ea',\n  ],\n  [\n    'stackwright-pro-page-otter.json',\n    '0323d9c9f4b4008b516d7615f24c0ebab9470bdf9cd37e1d48cfc06ccf6fccee',\n  ],\n  [\n    'stackwright-pro-theme-otter.json',\n    'a303ec6c045420f2c916583e3f6efcda469e9610fedfc84a508ed8a8a75866bc',\n  ],\n  [\n    'stackwright-pro-workflow-otter.json',\n    'ec203f222b2771f2bc3b29f340d881480c6a23188667e533476f4245e78453ef',\n  ],\n]);\nObject.freeze(_checksums);\nconst CANONICAL_CHECKSUMS: ReadonlyMap<string, string> = _checksums;\n\n// ---------------------------------------------------------------------------\n// Import-time format validation — malformed constants are a packaging bug,\n// not a runtime surprise. Fail fast, fail loud.\n// ---------------------------------------------------------------------------\n\nconst SHA256_HEX_RE = /^[0-9a-f]{64}$/;\n\nfor (const [name, digest] of CANONICAL_CHECKSUMS) {\n  if (!SHA256_HEX_RE.test(digest)) {\n    throw new Error(\n      `Malformed SHA-256 in CANONICAL_CHECKSUMS for \"${name}\": ` +\n        `expected 64 hex chars, got ${digest.length}: \"${digest}\"`\n    );\n  }\n}\n\n// 1 MB — generous headroom for agent definitions; anything larger is suspicious.\nconst MAX_OTTER_BYTES = 1 * 1024 * 1024;\n\n// ---------------------------------------------------------------------------\n// Core functions (exported for direct testing — no MCP server needed)\n// ---------------------------------------------------------------------------\n\n/** Compute the hex-encoded SHA-256 digest of raw bytes. Pure, no I/O. */\nexport function computeSha256(data: Buffer): string {\n  return createHash('sha256').update(data).digest('hex');\n}\n\n/** Constant-time comparison of two hex digest strings. */\nfunction safeEqual(a: string, b: string): boolean {\n  if (a.length !== b.length) return false;\n  return timingSafeEqual(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'));\n}\n\n// ---------------------------------------------------------------------------\n// Single-file verification\n// ---------------------------------------------------------------------------\n\nexport interface VerifyOtterFileResult {\n  verified: boolean;\n  filename: string;\n  error?: string;\n}\n\n/**\n * Read a single otter JSON file, check its size, compute its SHA-256,\n * and constant-time compare against the canonical checksum.\n *\n * Single read → hash → decode. No TOCTOU window.\n */\nexport function verifyOtterFile(filePath: string): VerifyOtterFileResult {\n  const filename = basename(filePath);\n\n  // Fast-fail on unknown filenames before any I/O\n  const expected = CANONICAL_CHECKSUMS.get(filename);\n  if (expected === undefined) {\n    return { verified: false, filename, error: `Unknown otter file: not in canonical set` };\n  }\n\n  // Symlink guard — refuse to follow symlinks (prevents symlink-based swaps)\n  let stat: ReturnType<typeof lstatSync>;\n  try {\n    stat = lstatSync(filePath);\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    return { verified: false, filename, error: `Cannot stat file: ${msg}` };\n  }\n\n  if (stat.isSymbolicLink()) {\n    return { verified: false, filename, error: 'Refusing to verify symlink' };\n  }\n\n  // Stat-based size pre-check — don't materialise oversized payloads\n  const size = stat.size;\n\n  if (size > MAX_OTTER_BYTES) {\n    return {\n      verified: false,\n      filename,\n      error: `File exceeds size limit (${MAX_OTTER_BYTES.toLocaleString()} bytes, got ${size.toLocaleString()})`,\n    };\n  }\n\n  // Single read — used for hashing and UTF-8 validation (zero TOCTOU window)\n  let raw: Buffer;\n  try {\n    raw = readFileSync(filePath);\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    return { verified: false, filename, error: `Cannot read file: ${msg}` };\n  }\n\n  // Belt-and-suspenders: re-check length after read in case of a race\n  if (raw.length > MAX_OTTER_BYTES) {\n    return {\n      verified: false,\n      filename,\n      error: `File exceeds size limit after read (${MAX_OTTER_BYTES.toLocaleString()} bytes, got ${raw.length.toLocaleString()})`,\n    };\n  }\n\n  // Hash the raw bytes\n  const actual = computeSha256(raw);\n\n  // Constant-time comparison prevents timing-oracle attacks\n  if (!safeEqual(actual, expected)) {\n    return {\n      verified: false,\n      filename,\n      error: `SHA-256 mismatch: expected ${expected.substring(0, 8)}…, got ${actual.substring(0, 8)}…`,\n    };\n  }\n\n  // UTF-8 validation — binary injection guard\n  try {\n    const decoder = new TextDecoder('utf-8', { fatal: true });\n    decoder.decode(raw);\n  } catch {\n    return {\n      verified: false,\n      filename,\n      error: 'File is not valid UTF-8 — may be corrupted or contain binary injection',\n    };\n  }\n\n  return { verified: true, filename };\n}\n\n// ---------------------------------------------------------------------------\n// Directory-level verification\n// ---------------------------------------------------------------------------\n\nexport interface VerifyAllOttersResult {\n  verified: string[];\n  failed: Array<{ filename: string; error: string }>;\n  unknown: string[];\n}\n\n/**\n * Scan a directory for `*-otter.json` files, verify each one against\n * canonical checksums. Returns lists of verified, failed, and unknown files.\n */\nexport function verifyAllOtters(otterDir: string): VerifyAllOttersResult {\n  const verified: string[] = [];\n  const failed: Array<{ filename: string; error: string }> = [];\n  const unknown: string[] = [];\n\n  let entries: string[];\n  try {\n    entries = readdirSync(otterDir);\n  } catch (err) {\n    const msg = err instanceof Error ? err.message : String(err);\n    return {\n      verified: [],\n      failed: [{ filename: '<directory>', error: `Cannot read directory: ${msg}` }],\n      unknown: [],\n    };\n  }\n\n  const otterFiles = entries.filter((f) => f.endsWith('-otter.json'));\n\n  for (const filename of otterFiles) {\n    const filePath = join(otterDir, filename);\n\n    // Skip symlinks at the directory-scan level too\n    try {\n      if (lstatSync(filePath).isSymbolicLink()) {\n        failed.push({ filename, error: 'Skipped: symlink' });\n        continue;\n      }\n    } catch {\n      // verifyOtterFile will handle stat errors\n    }\n\n    const result = verifyOtterFile(filePath);\n\n    if (result.verified) {\n      verified.push(result.filename);\n    } else if (result.error?.startsWith('Unknown otter file')) {\n      unknown.push(result.filename);\n    } else {\n      failed.push({ filename: result.filename, error: result.error ?? 'Unknown error' });\n    }\n  }\n\n  // Check for missing canonical files — ones we expect but didn't find on disk\n  for (const canonicalName of CANONICAL_CHECKSUMS.keys()) {\n    if (!otterFiles.includes(canonicalName)) {\n      failed.push({ filename: canonicalName, error: 'Missing from directory' });\n    }\n  }\n\n  return { verified, failed, unknown };\n}\n\n// ---------------------------------------------------------------------------\n// Otter directory resolution\n// ---------------------------------------------------------------------------\n\nconst DEFAULT_SEARCH_PATHS = ['node_modules/@stackwright-pro/otters/src/', 'packages/otters/src/'];\n\nfunction resolveOtterDir(): string | null {\n  const cwd = process.cwd();\n  for (const relative of DEFAULT_SEARCH_PATHS) {\n    const candidate = join(cwd, relative);\n    try {\n      lstatSync(candidate);\n      return candidate;\n    } catch {\n      // Not found, try next\n    }\n  }\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// MCP tool registration\n// ---------------------------------------------------------------------------\n\nexport function registerIntegrityTools(server: McpServer): void {\n  server.tool(\n    'stackwright_pro_verify_otter_integrity',\n    'Verify SHA-256 integrity of all Pro otter agent definitions. Call this at startup before discovering otters. Auto-discovers the otter directory from known paths. Returns verified/failed/unknown lists.',\n    {},\n    async () => {\n      const resolved = resolveOtterDir();\n\n      if (!resolved) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: JSON.stringify({\n                error: true,\n                message:\n                  'Could not locate otter directory. Searched: ' + DEFAULT_SEARCH_PATHS.join(', '),\n              }),\n            },\n          ],\n          isError: true,\n        };\n      }\n\n      const result = verifyAllOtters(resolved);\n\n      const allGood = result.failed.length === 0 && result.unknown.length === 0;\n\n      return {\n        content: [\n          {\n            type: 'text' as const,\n            text: JSON.stringify({\n              otterDir: resolved,\n              totalCanonical: CANONICAL_CHECKSUMS.size,\n              verifiedCount: result.verified.length,\n              failedCount: result.failed.length,\n              unknownCount: result.unknown.length,\n              verified: result.verified,\n              failed: result.failed,\n              unknown: result.unknown,\n              warning:\n                result.failed.length > 0\n                  ? 'SHA-256 mismatches detected (non-blocking). PKI-signed manifest support coming soon.'\n                  : undefined,\n            }),\n          },\n        ],\n        isError: false,\n      };\n    }\n  );\n}\n"],"mappings":"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","names":[]}