loopctl-mcp-server 2.53.1 → 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
@@ -297,7 +305,7 @@ it is enforced server-side and a no-op for a non-superadmin key — see below.)
 | Tool | Description |
 |---|---|
 | `llm_config` | **Check your onboarding status.** Get the tenant's BYO LLM config: per-operation models and whether each key is set — `has_api_key` (Anthropic) / `has_embedding_key` (OpenAI embedding) — plus masked last-4 hints. Never returns a key. Requires **user** key. |
-| `set_llm_config` | **First-time setup (do once).** Set/rotate the tenant's OWN **Anthropic `api_key`** (powers ingest) AND **OpenAI `embedding_api_key`** (powers semantic search) — both stored encrypted, never returned — plus the per-operation models (`extraction_model`/`classification_model`/`merge_model`/`embedding_model`). Any subset; partial-merge (omitting a key leaves it untouched). See [First-time setup](#first-time-setup--provision-your-byo-llm-keys). Requires **user** key. |
+| `set_llm_config` | **First-time setup (do once).** Set/rotate the tenant's OWN **Anthropic `api_key`** (powers ingest) AND **OpenAI `embedding_api_key`** (powers semantic search) — both stored encrypted, never returned — plus the per-operation models (`extraction_model`/`classification_model`/`merge_model`/`embedding_model`). Any subset; partial-merge (omitting a key leaves it untouched). **Private tier (US-41.3):** also sets `chat_provider` (`anthropic` | `openai_compatible`), `chat_base_url`, `extraction_model` (required on that provider) and `chat_api_key` (optional — omit it for a keyless local server) so ingest extraction / classification / merge / memory promotion run against YOUR OWN OpenAI-compatible endpoint and document text never leaves your boundary. Every model the config resolves to is PROBED with a trivial completion before it is saved (a 422 persists nothing); the probe re-runs on any chat-surface change (provider, base_url, key rotation, model), a private-range host is refused by the SSRF guard, and moving to a NEW host needs a matching `chat_api_key` or `acknowledge_key_transmission: true`. See [First-time setup](#first-time-setup--provision-your-byo-llm-keys). Requires **user** key. |
 | `knowledge_llm_usage` | Per-tenant LLM token-usage summary, grouped by operation + model + source_type + day over an optional `from`/`to` range (defaults to a 90-day lookback; effective window echoed in `meta.from`/`meta.to`), with `limit`/`offset` pagination. Record-only (no budget enforcement). Requires orchestrator key. |
 
 ### Knowledge Analytics Tools (orchestrator key)
@@ -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

@@ -1852,6 +1852,10 @@ async function setLlmConfig({
   merge_model,
   embedding_api_key,
   embedding_model,
+  chat_provider,
+  chat_base_url,
+  chat_api_key,
+  acknowledge_key_transmission,
 }) {
   const body = {};
   if (api_key != null) body.api_key = api_key;
@@ -1860,6 +1864,15 @@ async function setLlmConfig({
   if (merge_model !== undefined) body.merge_model = merge_model;
   if (embedding_api_key != null) body.embedding_api_key = embedding_api_key;
   if (embedding_model !== undefined) body.embedding_model = embedding_model;
+  // US-41.3: pluggable OpenAI-compatible chat endpoint. The server PROBES the
+  // endpoint with a trivial completion before persisting, and refuses an endpoint
+  // change that carries neither a matching chat_api_key nor an explicit
+  // acknowledge_key_transmission.
+  if (chat_provider !== undefined) body.chat_provider = chat_provider;
+  if (chat_base_url !== undefined) body.chat_base_url = chat_base_url;
+  if (chat_api_key != null) body.chat_api_key = chat_api_key;
+  if (acknowledge_key_transmission === true)
+    body.acknowledge_key_transmission = true;
   // PATCH (partial-merge) + EXACT user key (review #12, #13).
   const result = await apiCall(
     "PATCH",
@@ -1889,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;
@@ -4949,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 " +
@@ -4958,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: [] },
   },
   {
@@ -4972,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",
@@ -5114,7 +5218,11 @@ const TOOLS = [
       "(extraction_model / classification_model / merge_model / embedding_model) are " +
       "free-form (any model the key permits) and default server-side when omitted. Typical " +
       'onboarding call: set_llm_config({api_key: "sk-ant-...", embedding_api_key: "sk-..."}). ' +
-      "Verify anytime with llm_config (has_api_key / has_embedding_key). REQUIRES your " +
+      "PRIVATE TIER: set chat_provider 'openai_compatible' + chat_base_url + " +
+      "extraction_model (+ chat_api_key unless your server is keyless) to run " +
+      "extraction/classification/merge against YOUR OWN endpoint so document text " +
+      "never leaves your boundary; every model it resolves to is probed before it is saved. " +
+      "Verify anytime with llm_config (has_api_key / has_embedding_key / chat_provider). REQUIRES your " +
       "user-role key LOOPCTL_USER_KEY (minted by the human-anchored signup ceremony); if it " +
       "is unset the tool fails fast telling you to set it.",
     inputSchema: {
@@ -5128,7 +5236,14 @@ const TOOLS = [
         },
         extraction_model: {
           type: "string",
-          description: "Model id for knowledge extraction (null → server default).",
+          description:
+            "Model id for knowledge extraction (null → server default). REQUIRED with " +
+            "chat_provider 'openai_compatible': the server default is an Anthropic model " +
+            "id your endpoint cannot serve, so there is no safe fallback. It is also the " +
+            "fallback for classification_model / merge_model on that provider. " +
+            "HuggingFace repo ids are valid (e.g. 'meta-llama/Meta-Llama-3-8B-Instruct') " +
+            "— it is sent verbatim as the OpenAI `model` field, so it must match the name " +
+            "your server actually serves.",
         },
         classification_model: {
           type: "string",
@@ -5150,6 +5265,48 @@ const TOOLS = [
           description:
             "Embedding model id (null → server default text-embedding-3-small).",
         },
+        chat_provider: {
+          type: "string",
+          enum: ["anthropic", "openai_compatible"],
+          description:
+            "Which provider serves the CHAT surface (ingest extraction, classification, " +
+            "merge synthesis, memory promotion). Omit or 'anthropic' keeps the hardcoded " +
+            "Anthropic endpoint and identical behaviour. 'openai_compatible' routes that " +
+            "surface — the largest and most sensitive payload in the pipeline, your " +
+            "documents' full text — to YOUR OWN endpoint instead.",
+        },
+        chat_base_url: {
+          type: "string",
+          description:
+            "API base of your OpenAI-compatible server, e.g. " +
+            "'https://llm.example.internal/v1' (the client appends /chat/completions). " +
+            "Required with chat_provider 'openai_compatible'. PROBED with a trivial " +
+            "completion per resolved model BEFORE it is saved: an unreachable host, a " +
+            "rejected credential or a non-OpenAI-compatible response is a 422 and NOTHING " +
+            "is persisted. A host resolving into a private/loopback/link-local range is " +
+            "refused outright unless the OPERATOR allowlisted it (SSRF guard). Must be a " +
+            "BARE base: no query string, no fragment, no user:pass@ credentials (this " +
+            "column is NOT encrypted — anything in the URL is stored and echoed back). " +
+            "Plaintext http is accepted ONLY for a host the egress policy classifies " +
+            "network-local; a public http:// endpoint is refused because the request " +
+            "carries your key and your documents' full text in cleartext.",
+        },
+        chat_api_key: {
+          type: "string",
+          description:
+            "Credential for chat_base_url. Write-only; stored encrypted, never returned. " +
+            "SEPARATE from api_key — your Anthropic key is never sent to your endpoint. " +
+            "OPTIONAL: a local server that serves /chat/completions with no auth is " +
+            "configured by omitting this, and no authorization header is then sent.",
+        },
+        acknowledge_key_transmission: {
+          type: "boolean",
+          description:
+            "Required when CHANGING chat_base_url without supplying a matching " +
+            "chat_api_key: explicitly acknowledges that the already-stored key will be " +
+            "transmitted to the new host. The probe never ships an existing credential to " +
+            "a new host silently. Not persisted.",
+        },
       },
       required: [],
     },
@@ -5157,7 +5314,7 @@ const TOOLS = [
   {
     name: "knowledge_llm_usage",
     description:
-      "Per-tenant LLM token-usage summary, grouped by operation + model + source_type + " +
+      "Per-tenant LLM token-usage summary, grouped by operation + model + provider + source_type + " +
       "day over an optional date range, newest day first, with offset/limit pagination " +
       "over meta.total_count. When `from` is omitted it defaults to a 90-day lookback; the " +
       "EFFECTIVE window is echoed in meta.from/meta.to so you can detect that older usage " +
@@ -5909,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.53.1",
+  "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",