loopctl-mcp-server 2.54.0 → 2.55.0

package/README.md

@@ -16,6 +16,14 @@ Or run directly with npx:
 npx loopctl-mcp-server
 ```
 
+### Requirements
+
+- **Node.js >= 20.6.0.** The server makes all outbound HTTPS calls through Node's
+  global `fetch` (undici). Node 20.6.0 is the first release where that transport
+  honors `NODE_EXTRA_CA_CERTS` (the setting used for a custom/self-signed loopctl
+  CA -- see Troubleshooting below). On older runtimes that env var is silently
+  ignored, so the floor is enforced via `engines` in `package.json`.
+
 ## Configuration
 
 Add to your `.mcp.json` (Claude Code) or equivalent MCP config:
@@ -121,7 +129,7 @@ REST endpoint (`PATCH /api/v1/tenants/me/llm-config`), and the docs — so you (
 autonomous agent) can self-remediate without a human. Full agent-tenant lifecycle:
 [`docs/onboarding-agent-tenant.md`](../docs/onboarding-agent-tenant.md).
 
-## Tools (109)
+## Tools
 
 > Plus **per-tenant generated Context Retriever tools** (`cr_*`) appended
 > dynamically at runtime — see [Dynamic per-tenant Context Retriever
@@ -324,6 +332,8 @@ nothing changes until a scope opts in.
 | `declare_trusted_endpoint` | Declare a host you attest is YOUR OWN so a `local_only` scope can reach it. **This is an unverified tenant attestation, not network locality** — labelled as such everywhere. Three enforced constraints: PUBLIC addresses only (write time AND pin time), PURPOSE-SCOPED (`inference` / `webhook` / `ingest`), vendor hosts excluded. Carves nothing out of the SSRF denylist. Requires **user** key. |
 | `revoke_trusted_endpoint` | Revoke a declaration. Invalidation is IMMEDIATE and cluster-wide — a revoked declaration does not keep working for the remainder of the pin TTL. Requires **user** key. |
 | `egress_repin` | Recover from a `:pin_stale` error (your box got a new DHCP lease and the pinned address set changed — DISTINCT from `egress_blocked`). Re-resolves and re-pins the host. **Agent** key by design: requiring a human user-role write to recover would contradict loopctl's agent-native, no-UI design. |
+| `custody_claim` | The recorded **egress custody claim** for one article or memory row: the append-only sequence of per-operation postures (create, each embed, each re-embed, each classification, each merge) with the endpoints resolved for THAT operation and their verdicts, plus the aggregate. Rides the existing hash-chained audit log + signed tree heads — each entry carries a `chain_position` and the leaf's `chain_entry_hash`, so `GET /api/v1/audit/sth/{tenant_id}/inclusion/{position}` proves inclusion of *that* leaf, and the leaf's payload names this row by a recomputable `posture_digest`. THREE states, only one an attestation: `no_claim_recorded`, `claim_pending`, `claim_recorded` (`complete` / `partial_history` / `incomplete`). Completeness is measured against a persisted per-row high-water mark, so losing the tail of a sequence is a gap, not a clean claim. `third_party_egress_on_covered_paths` is `false` only for NETWORK-local endpoints; a tenant-declared (unverified) endpoint yields `"tenant_declared_unverified"`. Attests ONLY to the endpoints loopctl called on the paths in `coverage` — never to what those endpoints did afterwards. **Agent** key. |
+| `custody_failures` | Custody posture entries whose chain append was DROPPED after exhausting retries, plus `stale_pending` entries stranded by a flush that died outside its own final-attempt branch. Surfaced rather than silently absent: each `data` entry degrades its row's claim to `incomplete`, and a stranded entry would otherwise read as an in-flight claim forever. **Agent** key. |
 
 ### Discovery Tools
 
@@ -519,7 +529,8 @@ clean one-time bootstrap (no cross-key collision).
 
 - Verify `LOOPCTL_SERVER` is set and reachable
 - Check that the server URL includes the protocol (`https://`)
-- If using a self-signed certificate, set `NODE_TLS_REJECT_UNAUTHORIZED=0` in your environment (not recommended for production)
+- If your loopctl server uses a custom or self-signed CA, set `NODE_EXTRA_CA_CERTS=/path/to/ca.pem` in your environment so Node trusts that CA while keeping TLS certificate verification enabled. This requires **Node >= 20.6.0** (or the >= 18.19.0 backport): this server issues all requests through Node's global `fetch` (undici), which only began honoring `NODE_EXTRA_CA_CERTS` in those releases. On older runtimes the variable is silently ignored and you will still see `unable to verify the first certificate` / self-signed-cert errors -- upgrade Node rather than disabling verification.
+- Do NOT set `NODE_TLS_REJECT_UNAUTHORIZED=0` -- it disables certificate verification for the entire Node process (all outbound TLS), exposing every connection to MITM, not just the loopctl one
 
 ### Authentication errors (401)
 

package/index.js

@@ -1902,6 +1902,33 @@ async function egressPosture() {
   return toContent(result);
 }
 
+// --- US-41.7: witnessed custody claim ---------------------------------------
+//
+// A READ, at agent role for the same reason egress_posture is: verifying a
+// harvest AFTER the fact must work with the key an agent already holds.
+async function custodyClaim({ subject_type, subject_id } = {}) {
+  if (!subject_type || !subject_id) {
+    throw new Error("subject_type and subject_id are required");
+  }
+  const result = await apiCall(
+    "GET",
+    `/api/v1/custody/claims/${encodeURIComponent(subject_type)}/${encodeURIComponent(subject_id)}`,
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
+async function custodyFailures() {
+  const result = await apiCall(
+    "GET",
+    "/api/v1/custody/failures",
+    null,
+    process.env.LOOPCTL_AGENT_KEY,
+  );
+  return toContent(result);
+}
+
 async function setLocalOnly({ project_id, acknowledge } = {}) {
   const body = {};
   if (project_id != null) body.project_id = project_id;
@@ -4962,7 +4989,8 @@ const TOOLS = [
     name: "egress_posture",
     description:
       "VERIFY BEFORE YOU HARVEST. Reports this instance's egress posture for YOUR tenant: " +
-      "the resolved embedding and chat endpoints, a locality VERDICT for each " +
+      "the resolved embedding and chat endpoints, EVERY webhook destination " +
+      "(webhook_destinations), a locality VERDICT for each " +
       "(network-local / 'tenant-declared (unverified attestation), not network-local' / " +
       "non-local), your declared trusted endpoints with their purposes, per-scope " +
       "local_only status, and any named posture defects. Endpoints are shown; KEYS NEVER " +
@@ -4971,10 +4999,70 @@ const TOOLS = [
       "key you already have. NOTE the deployment allowlist CONTENTS are operator " +
       "infrastructure and are NOT disclosed at agent role: you get only a boolean per " +
       "endpoint saying whether its verdict came from the allowlist (contents at user+). " +
+      "Webhook destinations follow the same split: HOST plus verdict plus " +
+      "blocked_by_local_only at agent role, the FULL destination URL (endpoint) only at " +
+      "user+ — a webhook path is frequently the credential. " +
       "SCOPE OF THE GUARANTEE: fail-closed enforcement covers every outbound HTTP call " +
-      "made by loopctl application code on the MODEL-PROVIDER path. Webhook delivery is " +
-      "not covered yet (US-41.5), and HTTP performed inside a dependency, plus this " +
-      "separate mcp-server codebase, are outside the static chokepoint check.",
+      "made by loopctl application code on every CONTENT-CARRYING path — model-provider " +
+      "calls, the ingestion fetch, and webhook delivery (US-41.5). HTTP performed inside " +
+      "a dependency, plus this separate mcp-server codebase, are outside the static " +
+      "chokepoint check; the remaining non-content outbound paths are triaged in " +
+      "docs/egress-guard.md.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "custody_claim",
+    description:
+      "The recorded EGRESS CUSTODY CLAIM for one article or memory row: the append-only " +
+      "sequence of per-operation postures (create, each embedding, each re-embed, each " +
+      "classification/merge) with the endpoint loopctl resolved for THAT operation and its " +
+      "locality verdict, plus the aggregate over them. Each claim rides the existing " +
+      "hash-chained audit log and its signed tree heads — every recorded entry carries the " +
+      "chain_position you can fetch an inclusion proof for at " +
+      "GET /api/v1/audit/sth/{tenant_id}/inclusion/{position} and check against the public " +
+      "STH with the tenant's published audit key. THREE STATES, and only one of them is an " +
+      "attestation: 'no_claim_recorded' (no operation sequence was ever assigned — the row " +
+      "predates recording or its scope is not marked local_only; this asserts NOTHING in " +
+      "either direction), 'claim_pending' (sequences assigned, batch append not yet " +
+      "flushed), and 'claim_recorded', itself 'complete', 'partial_history' or " +
+      "'incomplete'. An INCOMPLETE sequence (a gap, a lost tail, or a dropped append) is " +
+      "never reported as no-third-party-egress: an unrecorded operation may have called " +
+      "any endpoint. Completeness is measured against a PERSISTED per-row high-water mark, " +
+      "not against the rows that happen to survive, so truncating the sequence cannot " +
+      "restore a satisfied claim. 'partial_history' means operation 0 is not this row's " +
+      "creation — recording began after the row already existed (typically the scope was " +
+      "marked local_only later), so loopctl has no record of how it was produced. " +
+      "third_party_egress_on_covered_paths is `false` ONLY when every recorded endpoint " +
+      "was NETWORK-LOCAL; when the sequence leans on a TENANT-DECLARED endpoint (a public " +
+      "host the tenant merely attested is its own, which loopctl never verified) the value " +
+      "is the string 'tenant_declared_unverified', not false. " +
+      "SCOPE, precisely: the claim attests ONLY to the endpoints loopctl called for the " +
+      "recorded operations on this row, on the egress paths enumerated in the `coverage` " +
+      "field. It makes NO statement about what those endpoints did with the data " +
+      "afterwards, and none about a path listed as uncovered. READ tool, AGENT role.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subject_type: {
+          type: "string",
+          enum: ["article", "memory"],
+          description: "The kind of row the claim is bound to.",
+        },
+        subject_id: { type: "string", description: "The row's UUID." },
+      },
+      required: ["subject_type", "subject_id"],
+    },
+  },
+  {
+    name: "custody_failures",
+    description:
+      "Custody posture entries whose audit-chain append was DROPPED after exhausting " +
+      "retries, plus (under `stale_pending`) entries that have been in flight longer than " +
+      "the stale window. A recording failure is surfaced here rather than silently absent, " +
+      "because a missing claim must never read as a satisfied one: every entry under " +
+      "`data` degrades its row's claim to 'incomplete', and a stranded `stale_pending` " +
+      "entry is one a flush stamped and then died on — it would otherwise read as an " +
+      "in-flight claim indefinitely. READ tool, AGENT role.",
     inputSchema: { type: "object", properties: {}, required: [] },
   },
   {
@@ -4985,10 +5073,13 @@ const TOOLS = [
       "everywhere; nothing changes until a scope opts in. Scope resolution is " +
       "MOST-RESTRICTIVE-WINS (project OR tenant) and a project can NEVER relax a tenant " +
       "marking. MANDATORY PRE-FLIGHT: the call is REFUSED with 409 would_block_endpoints, " +
-      "naming every endpoint that would become egress_blocked, unless you pass " +
+      "naming every endpoint that would become egress_blocked — including every WEBHOOK " +
+      "SUBSCRIPTION whose destination would be refused (kind: 'webhook', US-41.5) — " +
+      "unless you pass " +
       "acknowledge: true — because on a tenant still using vendor default endpoints this " +
       "instantly stops embedding, extraction, classification and merge, and only a " +
-      "human user-role key can undo it. Requires an ORCHESTRATOR key: tightening is safe " +
+      "human user-role key can undo it. Subscriptions are never silently disabled: they " +
+      "are either the reason for the refusal, or reported back to you on acknowledgement. Requires an ORCHESTRATOR key: tightening is safe " +
       "to automate. CLEARING is a different tool (clear_local_only) and is user-only.",
     inputSchema: {
       type: "object",
@@ -5975,6 +6066,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "egress_posture":
       return await egressPosture();
 
+    // US-41.7 — witnessed custody claim
+    case "custody_claim":
+      return await custodyClaim(args);
+
+    case "custody_failures":
+      return await custodyFailures();
+
     case "set_local_only":
       return await setLocalOnly(args);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.54.0",
+  "version": "2.55.0",
   "description": "MCP server for loopctl \u2014 structural trust for AI development loops",
   "type": "module",
   "main": "index.js",
@@ -30,7 +30,7 @@
   "license": "MIT",
   "exports": "./index.js",
   "engines": {
-    "node": ">=18"
+    "node": ">=20.6.0"
   },
   "files": [
     "index.js",