@helm-protocol/ttt-mcp 0.4.0 → 0.4.2

package/README.md

@@ -55,12 +55,12 @@ Claude workflow → [context compressed] → agents call pot_query(eventId)
 ### Claude Code
 
 ```bash
-claude mcp add ttt -- npx -y @helm-protocol/ttt-mcp@0.3.3
+claude mcp add ttt -- npx -y @helm-protocol/ttt-mcp@0.4.0
 ```
 
 With an API key (raises the free limit to your plan's monthly quota):
 ```bash
-claude mcp add ttt -e TTT_API_KEY=your-key -- npx -y @helm-protocol/ttt-mcp@0.3.3
+claude mcp add ttt -e TTT_API_KEY=your-key -- npx -y @helm-protocol/ttt-mcp@0.4.0
 ```
 
 ### Claude Desktop
@@ -72,7 +72,7 @@ Add to `claude_desktop_config.json`:
   "mcpServers": {
     "ttt": {
       "command": "npx",
-      "args": ["-y", "@helm-protocol/ttt-mcp@0.3.3"],
+      "args": ["-y", "@helm-protocol/ttt-mcp@0.4.0"],
       "env": { "TTT_API_KEY": "your-key" }
     }
   }
@@ -81,7 +81,7 @@ Add to `claude_desktop_config.json`:
 
 ### Cursor
 
-[![Add to Cursor](https://img.shields.io/badge/Add%20to%20Cursor-1a1a1a?style=flat&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=ttt&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBoZWxtLXByb3RvY29sL3R0dC1tY3BAMC4zLjMiXX0=)
+[![Add to Cursor](https://img.shields.io/badge/Add%20to%20Cursor-1a1a1a?style=flat&logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=ttt&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBoZWxtLXByb3RvY29sL3R0dC1tY3BAMC40LjAiXX0=)
 
 One-click install, or add the same `mcpServers` block above to `.cursor/mcp.json`.
 
@@ -127,12 +127,14 @@ pot_graph(eventId: "step-2", depth: 5)
 
 ---
 
-## 8 Tools
+## 10 Tools
 
 | Tool | Purpose |
 |------|---------|
 | `pot_generate` | Stamp a workflow step with a cryptographic timestamp |
 | `pot_verify` | Verify a PoT signature |
+| `pot_generate_v2` | Generate the draft-11 180-octet PoT Record v2 core (canonical wire profile) |
+| `pot_verify_v2` | Verify a v2 record; optional TLS 1.3 exporter binding proof (fails closed without TLS) |
 | `pot_verify_v08` | Verify a draft-08 §3 Payload Digest record |
 | `pot_query` | O(1) exact lookup by eventId — core amnesia recovery |
 | `pot_graph` | Traverse causal DAG (backward + forward chain) |

package/dist/index.js

@@ -105,7 +105,7 @@ function toolSuccess(result) {
   return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
 }
 function buildMcpServer() {
-  const s = new import_mcp.McpServer({ name: "ttt-mcp", version: "0.3.2" });
+  const s = new import_mcp.McpServer({ name: "ttt-mcp", version: "0.4.2" });
   const registerTool = s.tool.bind(s);
   registerTool(
     "pot_generate",
@@ -213,7 +213,7 @@ function buildMcpServer() {
   );
   registerTool(
     "pot_query",
-    "Query Proof of Time records. Use eventId for exact O(1) lookup of a specific workflow step (collision probability 2^-256). Use startTime/endTime for time-range queries.",
+    "Query Proof of Time records. Use eventId for exact lookup of a specific workflow step. Use startTime/endTime for time-range queries.",
     {
       eventId: import_zod.z.string().optional().describe("Exact eventId lookup \u2014 call this at workflow start to restore action history after context compression"),
       startTime: import_zod.z.number().optional().describe("Start time (unix ms). Default: 24h ago"),
@@ -304,7 +304,7 @@ async function main() {
     const requestHandler = async (req, res) => {
       if (req.method === "GET" && (req.url === "/health" || req.url === "/ping")) {
         res.writeHead(200, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ status: "ok", server: "ttt-mcp", version: "0.3.2" }));
+        res.end(JSON.stringify({ status: "ok", server: "ttt-mcp", version: "0.4.2" }));
         return;
       }
       if (req.method === "POST") {
@@ -364,8 +364,8 @@ async function main() {
     }
     const httpServer = certFile && keyFile ? (0, import_https.createServer)({ minVersion: "TLSv1.3", cert: (0, import_fs.readFileSync)(certFile), key: (0, import_fs.readFileSync)(keyFile) }, (req, res) => {
       const exporter = (0, import_tls_exporter.extractTls13Exporter)(req);
-      return (0, import_transport_context.withTransportBinding)({ exporter, clientId: String(req.headers["x-ttt-client-id"] ?? ""), sessionId: String(req.headers["x-ttt-session-id"] ?? "") }, () => requestHandler(req, res));
-    }) : (0, import_http.createServer)((req, res) => (0, import_transport_context.withTransportBinding)({ clientId: String(req.headers["x-ttt-client-id"] ?? ""), sessionId: String(req.headers["x-ttt-session-id"] ?? "") }, () => requestHandler(req, res)));
+      return (0, import_transport_context.withTransportBinding)({ exporter, remoteAddress: req.socket.remoteAddress ?? "", clientId: String(req.headers["x-ttt-client-id"] ?? ""), sessionId: String(req.headers["x-ttt-session-id"] ?? "") }, () => requestHandler(req, res));
+    }) : (0, import_http.createServer)((req, res) => (0, import_transport_context.withTransportBinding)({ remoteAddress: req.socket.remoteAddress ?? "", clientId: String(req.headers["x-ttt-client-id"] ?? ""), sessionId: String(req.headers["x-ttt-session-id"] ?? "") }, () => requestHandler(req, res)));
     httpServer.listen(port, () => {
       console.error(`[ttt-mcp] OpenTTT MCP Server (${certFile ? "HTTPS/TLS1.3" : "HTTP"}) on port ${port}`);
     });

package/dist/tools.js

@@ -441,17 +441,63 @@ async function potGenerateV2(args) {
     bindingProofRequired: process.env.TTTPS_V2_REQUIRE_BINDING === "1"
   });
 }
-async function potVerifyV2(args) {
+function trustedKeyList(envName) {
+  return (process.env[envName] ?? "").split(",").map((s) => s.trim()).filter((s) => /^[0-9a-fA-F]{64}$/.test(s)).map((h) => Buffer.from(h, "hex"));
+}
+let roughtimeAdmitCache = null;
+async function roughtimeChainStatus() {
+  const url = process.env.TTTPS_ADMISSION_STATUS_URL ?? "https://api.kenosian.com/pot/status";
+  const ttlMs = Number.parseInt(process.env.TTTPS_ADMISSION_TTL_MS ?? "5000", 10);
+  if (roughtimeAdmitCache && Date.now() - roughtimeAdmitCache.at < ttlMs) {
+    return { ok: roughtimeAdmitCache.ok, digest: roughtimeAdmitCache.digest };
+  }
+  try {
+    const timeoutMs = Number.parseInt(process.env.TTTPS_ADMISSION_TIMEOUT_MS ?? "1500", 10);
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    const j = await res.json();
+    const ok = j?.chain_valid === true || j?.chain_valid === void 0 && j?.roughtime_ok === true;
+    const digest = typeof j?.d_chain_digest === "string" ? j.d_chain_digest : "";
+    roughtimeAdmitCache = { ok, digest, at: Date.now() };
+    return { ok, digest };
+  } catch {
+    roughtimeAdmitCache = { ok: false, digest: "", at: Date.now() };
+    return { ok: false, digest: "" };
+  }
+}
+async function potVerifyV2Core(args) {
   (0, import_telemetry.telemetryIncrement)("pot_verify_v2");
   const bindingRequired = process.env.TTTPS_V2_REQUIRE_BINDING === "1";
   if (bindingRequired && !args.bindingProof) {
     return serialize({ verdict: "rejected", reason: "TLS exporter binding proof is required" });
   }
   const record = Buffer.from(args.potRecordV2, "hex");
-  const issuerPubKey = args.issuerPubKey ? Buffer.from(args.issuerPubKey, "hex") : potSignerPublicKeyRawV08;
-  const freshness = args.nowTaiUs !== void 0 && args.maxSkewUs !== void 0 ? { nowTaiUs: BigInt(args.nowTaiUs), maxSkewUs: BigInt(args.maxSkewUs) } : void 0;
-  const result = (0, import_pot_record_v2.verifyPotRecordV2)(record, issuerPubKey, freshness);
-  if (result.verdict === "rejected") return serialize(result);
+  if (process.env.TTTPS_REQUIRE_ROUGHTIME_QUORUM === "1") {
+    const chain = await roughtimeChainStatus();
+    if (!chain.ok) {
+      return serialize({ verdict: "rejected", reason: "roughtime chain quorum unavailable" });
+    }
+  }
+  const freshness = process.env.TTTPS_ENFORCE_FRESHNESS === "1" ? { nowTaiUs: BigInt(Date.now()) * 1000n, maxSkewUs: BigInt(process.env.TTTPS_MAX_SKEW_US ?? "60000000") } : args.nowTaiUs !== void 0 && args.maxSkewUs !== void 0 ? { nowTaiUs: BigInt(args.nowTaiUs), maxSkewUs: BigInt(args.maxSkewUs) } : void 0;
+  const trustedIssuers = trustedKeyList("TTTPS_TRUSTED_ISSUERS");
+  const pinSelfIssuer = process.env.TTTPS_PIN_SELF_ISSUER === "1";
+  const candidates = trustedIssuers.length > 0 ? trustedIssuers : pinSelfIssuer ? [potSignerPublicKeyRawV08] : [args.issuerPubKey ? Buffer.from(args.issuerPubKey, "hex") : potSignerPublicKeyRawV08];
+  let result = (0, import_pot_record_v2.verifyPotRecordV2)(record, candidates[0], freshness);
+  for (let i = 1; i < candidates.length && result.verdict === "rejected" && result.reason === "issuer signature invalid"; i++) {
+    result = (0, import_pot_record_v2.verifyPotRecordV2)(record, candidates[i], freshness);
+  }
+  if (result.verdict === "rejected") {
+    if (trustedIssuers.length > 0 && result.reason === "issuer signature invalid") {
+      return serialize({ verdict: "rejected", reason: "issuer not trusted" });
+    }
+    return serialize(result);
+  }
+  const trustedHolders = trustedKeyList("TTTPS_TRUSTED_HOLDERS");
+  if (trustedHolders.length > 0) {
+    const holder = record.subarray(48, 80);
+    if (!trustedHolders.some((h) => h.equals(holder))) {
+      return serialize({ verdict: "rejected", reason: "holder not authorized" });
+    }
+  }
   if (args.bindingProof) {
     const exporter = (0, import_transport_context.currentTransportBinding)()?.exporter;
     if (!exporter) return serialize({ verdict: "rejected", reason: "live TLS exporter unavailable" });
@@ -471,6 +517,70 @@ async function potVerifyV2(args) {
   }
   return serialize({ verdict: "intact", wireProfile: "draft-helmprotocol-tttps-11-v2", nonce: result.nonce.toString("hex") });
 }
+const V2_AUDIT_STREAM = process.env.TTTPS_AUDIT_STREAM ?? "tttps:audit:v2";
+const V2_AUDIT_MAXLEN = Number.parseInt(process.env.TTTPS_AUDIT_MAXLEN ?? "100000", 10);
+const TTTPS_FORMAL_RECEIPT = {
+  spec: "draft-helmprotocol-tttps-11",
+  // Honest status. There is a TLA+ model (TLC model-checked) and a Lean 4 module whose
+  // theorems the kernel accepts (sorry 0, axiom propext), and this runtime. They are
+  // RELATED artifacts, not a machine-checked end-to-end 1:1 equivalence. Treat this as
+  // provenance the auditor can chase, not proof of the byte parser or the cryptography.
+  binding_status: "provenance-only; TLA+<->Lean<->runtime 1:1 equivalence is NOT machine-checked end-to-end (HOLD)",
+  lean: {
+    module: "KLean.TTTPS.Core",
+    theorems: [
+      "invalid_ingress_no_mutation",
+      "parse_is_deterministic",
+      "parsed_record_has_fixed_size",
+      "valid_ingress_commit_delta",
+      "zero_state_preservation"
+    ],
+    axioms: ["propext"],
+    content_hash: "sha256:6116b82318d540a1e4e5b694e31978739851f658356330349b9d4289aeb5bae8",
+    abstraction: "models admission at frame-size (=180) granularity; does NOT model field offsets, Ed25519, SHA-256, or the TLS exporter"
+  },
+  tla: { spec: "TTTPS_Ingress_Gate.tla", method: "TLC bounded model check (not an unbounded theorem)" },
+  anchor: {
+    receipt_id: "33108706ed730e5296ae1b06",
+    time_source: "roughtime_chain",
+    verify_url: "https://kpp.kenosian.com/v1/verify?receipt_id=33108706ed730e5296ae1b06"
+  },
+  revision: { package_commit: "677a3b9", note: "live gate runs this revision with admission flags ON; published npm 0.4.0 bytes carry the v2 core only" },
+  scope: "Kernel-checks the 180-octet parse + admission state boundary (invalid ingress => zero state mutation). Does NOT prove Ed25519/SHA-256/TLS-exporter cryptographic security, nor a byte-exact parser equivalence."
+};
+async function potVerifyV2(args) {
+  const startedNs = process.hrtime.bigint();
+  let result;
+  try {
+    result = await potVerifyV2Core(args);
+  } catch (e) {
+    result = { verdict: "rejected", reason: `verifier exception: ${e instanceof Error ? e.message : String(e)}` };
+  }
+  const serverLatencyUs = Number((process.hrtime.bigint() - startedNs) / 1000n);
+  const binding = (0, import_transport_context.currentTransportBinding)();
+  const recordHex = typeof args.potRecordV2 === "string" ? args.potRecordV2 : "";
+  const record = Buffer.from(recordHex, "hex");
+  const fields = {
+    ts_ms: String(Date.now()),
+    verdict: String(result.verdict ?? "unknown"),
+    reason: String(result.reason ?? ""),
+    case: String(args.clientId ?? binding?.clientId ?? ""),
+    session: String(args.sessionId ?? binding?.sessionId ?? ""),
+    remote: String(binding?.remoteAddress ?? ""),
+    transport: binding?.exporter ? "tls13" : "none",
+    binding_proof: args.bindingProof ? "present" : "absent",
+    record_len: String(record.length),
+    record_sha16: record.length ? (0, import_crypto.createHash)("sha256").update(record).digest("hex").slice(0, 16) : "",
+    ctx_id: record.length >= 48 ? record.subarray(16, 32).toString("hex") : "",
+    nonce: record.length >= 48 ? record.subarray(32, 48).toString("hex") : "",
+    latency_us: String(serverLatencyUs)
+  };
+  const flat = [];
+  for (const [k, v] of Object.entries(fields)) flat.push(k, v);
+  redis.call("XADD", V2_AUDIT_STREAM, "MAXLEN", "~", String(V2_AUDIT_MAXLEN), "*", ...flat).catch(() => void 0);
+  const emitFormal = process.env.TTTPS_EMIT_FORMAL_RECEIPT !== "0";
+  return serialize({ ...result, serverLatencyUs, ...emitFormal ? { formal: TTTPS_FORMAL_RECEIPT } : {} });
+}
 async function potVerifyV08(args) {
   (0, import_telemetry.telemetryIncrement)("pot_verify_v08");
   const record = Buffer.from(args.potRecordV08, "hex");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helm-protocol/ttt-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Proof-of-Time attestation — Ed25519-signed timestamps with multi-source corroboration and explicit error bounds. IETF draft-helmprotocol-tttps",
   "main": "dist/index.js",
   "bin": {