loopctl-mcp-server 2.34.0 → 2.36.0

package/README.md

@@ -2,7 +2,7 @@
 
 MCP (Model Context Protocol) server for [loopctl](https://loopctl.com) -- structural trust for AI development loops.
 
-Wraps the loopctl REST API into 72 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
+Wraps the loopctl REST API into 73 typed MCP tools so AI coding agents (Claude Code, etc.) can interact with loopctl without writing curl commands.
 
 ## Installation
 
@@ -84,9 +84,18 @@ per-operation model overrides (`extraction_model`, `classification_model`,
 
 ### The smooth path (once, at onboarding)
 
-1. **Sign up** and obtain your keys. Tenant signup is anchored to a hardware
-   authenticator (WebAuthn) — the one human touch. Signup mints your **user-role**
-   API key. Also grab your **agent** and **orchestrator** keys for day-to-day work.
+1. **Sign up** and obtain your keys. loopctl has two trust tiers (US-26.7.1):
+   - **Human-anchored (unlocks work-breakdown / chain-of-custody too):** visit
+     `https://loopctl.com/signup` and enroll a hardware authenticator (WebAuthn) —
+     the one human touch. This mints your **user-role** API key; also grab your
+     **agent** and **orchestrator** keys for day-to-day work.
+   - **Agent-rooted (KB-tier only, fully automated):** call the `signup` MCP tool
+     (or `POST /api/v1/signup` directly) with `name`/`slug`/`email` — no human, no
+     hardware key. This mints a one-time `role: user` API key with the FULL
+     knowledge-wiki surface (ingest/search/curate, BYO LLM config, agent
+     registration), but it **cannot** perform work-breakdown / chain-of-custody
+     operations. The `raw_key` in the response is shown ONCE — save it
+     immediately (it cannot be retrieved again).
 2. **Set the env** in your `.mcp.json` (see [Configuration](#configuration)):
    `LOOPCTL_SERVER`, `LOOPCTL_USER_KEY` (needed for this step), plus `LOOPCTL_AGENT_KEY`
    / `LOOPCTL_ORCH_KEY`.
@@ -112,7 +121,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 (72)
+## Tools (73)
 
 ### Project Tools
 
@@ -258,6 +267,7 @@ Key distribution for the dispatch pattern (Epic 26): per-dispatch ephemeral keys
 
 | Tool | Description |
 |---|---|
+| `signup` | **US-26.7.1.** Create a NEW **agent-rooted (KB-tier)** tenant and mint its one-time root API key — entirely through this call, no human operator, no hardware authenticator, no existing API key required. The tenant gets the FULL knowledge-wiki surface but **cannot** perform work-breakdown / chain-of-custody operations (those require a separate human-anchored tenant via the WebAuthn ceremony at `https://loopctl.com/signup`). Rate-limited per client IP (<= 5/hour). The `raw_key` is shown ONCE — save it immediately (e.g. as `LOOPCTL_USER_KEY`). Required: `name`, `slug`, `email`. |
 | `dispatch` | Mint an ephemeral, scoped api_key for a sub-agent dispatch, carrying its lineage path. The `raw_key` is returned ONCE — pass it to the sub-agent's launch args, never store it in env vars; it expires after `expires_in_seconds` (default 3600, max 14400). Required: `role` (`agent`/`orchestrator`), `agent_id`. Optional: `parent_dispatch_id`, `story_id`. |
 | `recover_cap` | Re-mint a capability token for a story you're assigned to, after a session crash lost your cap. Required: `story_id`. Optional: `cap_type` (`start_cap`/`report_cap`, default `start_cap`), `lineage`. |
 | `get_sth` | Get the latest Signed Tree Head for a tenant's tamper-evident audit chain. Public — no auth required. Required: `tenant_id`. |

package/index.js

@@ -189,6 +189,75 @@ async function apiCall(method, path, body, keyOverride, { exactKey = false } = {
   return responseBody;
 }
 
+/**
+ * Unauthenticated request helper for genuinely public endpoints (currently
+ * only POST /api/v1/signup). No Authorization header is sent — the public
+ * signup POST carries no witness header either (US-26.7.1), so this
+ * bypasses `witnessClientFor` entirely and calls `fetch` directly. Response
+ * parsing mirrors `apiCall`'s so callers can pass the result straight to
+ * `toContent`/`toContentCompact`.
+ */
+async function publicApiCall(method, path, body) {
+  const url = `${getBaseUrl()}${path}`;
+  const headers = { "Content-Type": "application/json", Accept: "application/json" };
+  const serializedBody =
+    body !== undefined && body !== null ? JSON.stringify(body) : undefined;
+
+  let response;
+  try {
+    response = await fetch(url, {
+      method,
+      headers,
+      body: serializedBody,
+      signal: AbortSignal.timeout(30_000),
+    });
+  } catch (err) {
+    if (err.name === "TimeoutError") {
+      return { error: true, status: 0, body: "Request timed out after 30s" };
+    }
+    const cause = err.cause?.message ? ` (${err.cause.message})` : "";
+    return { error: true, status: 0, body: `Network error: ${err.message}${cause}` };
+  }
+
+  if (response.status === 204) {
+    return { ok: true };
+  }
+
+  let responseBody;
+  const contentType = response.headers.get("content-type") || "";
+  if (contentType.includes("application/json")) {
+    const raw = await response.text();
+    const outcome = parseJsonResponseBody(raw, response.status);
+    if (outcome.error) {
+      return outcome;
+    }
+    responseBody = outcome.parsed;
+  } else {
+    const text = await response.text();
+    try {
+      responseBody = JSON.parse(text);
+    } catch {
+      responseBody = text;
+    }
+  }
+
+  if (!response.ok) {
+    let errorBody = responseBody;
+    if (typeof errorBody === "string" && errorBody.length > 500) {
+      errorBody = errorBody
+        .replace(/<[^>]+>/g, " ")
+        .replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 500) + "... (truncated)";
+    }
+    return { error: true, status: response.status, body: errorBody };
+  }
+
+  return responseBody;
+}
+
 function toContent(result) {
   const isErr = result && result.error === true;
   return {
@@ -1611,6 +1680,81 @@ async function createDispatch({
   return toContent(result);
 }
 
+// US-26.7.1: public, agent-rooted (KB-tier) self-signup. No API key required —
+// this creates the tenant AND the key. The resulting tenant is KB-tier only
+// (knowledge ingest/search/curate on the caller's own BYO LLM keys); the
+// work-breakdown / chain-of-custody surface requires a separate,
+// human-anchored WebAuthn signup ceremony at https://loopctl.com/signup.
+async function signup({ name, slug, email }) {
+  const result = await publicApiCall("POST", "/api/v1/signup", { name, slug, email });
+  return toContent(result);
+}
+
+// US-26.7.2: opt-in WebAuthn trust-tier upgrade ceremony (agent_rooted ->
+// human_anchored) + authenticator revocation. All four require the EXACT
+// user-role key (LOOPCTL_USER_KEY) + ownership of `tenant_id` — mirroring
+// set_llm_config's exactKey:true pattern, since these mutate the tenant's
+// root of trust. NOT headless: completing enrollment/revocation requires an
+// INTERACTIVE WebAuthn client (a browser or a native FIDO2 library) with a
+// human present to touch the hardware authenticator — an agent alone cannot
+// produce a valid attestation or assertion, by design (see
+// docs/chain-of-custody-v2.md §9).
+async function requestAuthenticatorChallenge({ tenant_id }) {
+  const result = await apiCall(
+    "POST",
+    `/api/v1/tenants/${tenant_id}/authenticators/challenge`,
+    {},
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function enrollAuthenticator({
+  tenant_id,
+  challenge_id,
+  attestation_object,
+  client_data_json,
+  credential_id,
+  friendly_name,
+  reauth_assertion,
+}) {
+  const body = { challenge_id, attestation_object, client_data_json, credential_id };
+  if (friendly_name != null) body.friendly_name = friendly_name;
+  if (reauth_assertion != null) body.reauth_assertion = reauth_assertion;
+
+  const result = await apiCall(
+    "POST",
+    `/api/v1/tenants/${tenant_id}/authenticators`,
+    body,
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function requestAuthenticatorRevokeChallenge({ tenant_id }) {
+  const result = await apiCall(
+    "POST",
+    `/api/v1/tenants/${tenant_id}/authenticators/revoke-challenge`,
+    {},
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
+async function revokeAuthenticator({ tenant_id, authenticator_id, webauthn_assertion }) {
+  const result = await apiCall(
+    "DELETE",
+    `/api/v1/tenants/${tenant_id}/authenticators/${authenticator_id}`,
+    { webauthn_assertion },
+    process.env.LOOPCTL_USER_KEY,
+    { exactKey: true },
+  );
+  return toContent(result);
+}
+
 // US-26: Signed Tree Head retrieval
 async function getSth({ tenant_id }) {
   const result = await apiCall("GET", `/api/v1/audit/sth/${tenant_id}`);
@@ -3788,6 +3932,139 @@ const TOOLS = [
   },
 
   // Chain of Custody v2 tools
+  {
+    name: "signup",
+    description:
+      "Create a NEW agent-rooted (KB-tier) tenant and mint its one-time root API key — " +
+      "entirely through this call, no human operator and no hardware authenticator required. " +
+      "Public — no existing API key needed to call this tool. The returned tenant can " +
+      "immediately use the FULL knowledge-wiki surface (ingest/search/context/curate, BYO " +
+      "LLM key config, agent registration) but CANNOT perform work-breakdown / " +
+      "chain-of-custody operations (create projects/epics/stories, claim/verify/report, " +
+      "dispatch, etc.) — those require a separate, human-anchored tenant created via the " +
+      "WebAuthn ceremony at https://loopctl.com/signup. Rate-limited per client IP " +
+      "(<= 5 signups/hour). The raw_key in the response is shown ONCE — save it immediately " +
+      "(e.g. as LOOPCTL_USER_KEY) since it cannot be retrieved again. Next steps after " +
+      "signup: configure your BYO LLM keys with set_llm_config, then register an agent " +
+      "identity, then ingest/search the wiki.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Tenant display name.", maxLength: 120 },
+        slug: { type: "string", description: "URL-safe unique tenant slug.", maxLength: 64 },
+        email: { type: "string", description: "Contact email for the tenant." },
+      },
+      required: ["name", "slug", "email"],
+    },
+  },
+  {
+    name: "request_authenticator_challenge",
+    description:
+      "Step 1 of the opt-in WebAuthn trust-tier upgrade ceremony (US-26.7.2): issues a " +
+      "registration challenge for enrolling a hardware authenticator against an EXISTING " +
+      "agent_rooted (KB-tier) tenant, promoting it to human_anchored on success. " +
+      "IMPORTANT: completing this ceremony requires an INTERACTIVE WebAuthn client " +
+      "(a browser calling navigator.credentials.create(), or a native FIDO2 library) " +
+      "with a HUMAN present to physically touch the authenticator — an agent alone " +
+      "cannot produce a valid attestation, by design. Use this tool to fetch the " +
+      "challenge/rp/user/pubKeyCredParams payload, drive the WebAuthn ceremony in your " +
+      "interactive client, then call enroll_authenticator with the result. If the " +
+      "tenant is already human_anchored, the response includes reauth_required: true " +
+      "plus a reauth_challenge — enroll_authenticator will need a fresh assertion from " +
+      "an EXISTING authenticator too (see enroll_authenticator's description). Requires " +
+      "LOOPCTL_USER_KEY (user role) bound to tenant_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID to enroll an authenticator for." },
+      },
+      required: ["tenant_id"],
+    },
+  },
+  {
+    name: "enroll_authenticator",
+    description:
+      "Step 2 of the opt-in WebAuthn trust-tier upgrade ceremony: completes enrollment " +
+      "with the attestation produced by navigator.credentials.create() against the " +
+      "challenge from request_authenticator_challenge. On a tenant's FIRST enrollment " +
+      "(zero prior authenticators) this call FLIPS the tenant from agent_rooted to " +
+      "human_anchored, unlocking the work-breakdown / chain-of-custody surface " +
+      "(projects, stories, dispatch, ...). On a SUBSEQUENT (backup) enrollment for an " +
+      "already human_anchored tenant, `reauth_assertion` (a fresh WebAuthn assertion " +
+      "from an EXISTING enrolled authenticator, from the challenge's reauth_challenge) " +
+      "is REQUIRED — omitting it when required returns 401 reauth_required. All " +
+      "binary fields are base64url encoded. Requires LOOPCTL_USER_KEY (user role) " +
+      "bound to tenant_id. Cannot be completed by an agent alone — see " +
+      "request_authenticator_challenge.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID." },
+        challenge_id: {
+          type: "string",
+          description: "challenge_id from request_authenticator_challenge.",
+        },
+        attestation_object: { type: "string", description: "Base64url attestation object." },
+        client_data_json: { type: "string", description: "Base64url raw client data JSON." },
+        credential_id: { type: "string", description: "Base64url credential id." },
+        friendly_name: {
+          type: "string",
+          description: "Operator-supplied label (1..120 chars, default \"Authenticator\").",
+        },
+        reauth_assertion: {
+          type: "object",
+          description:
+            "Required ONLY when enrolling a backup authenticator on an already " +
+            "human_anchored tenant: a fresh assertion (challenge_id, credential_id, " +
+            "authenticator_data, signature, client_data_json — all base64url) from an " +
+            "EXISTING enrolled authenticator, bound to the reauth_challenge returned by " +
+            "request_authenticator_challenge.",
+        },
+      },
+      required: ["tenant_id", "challenge_id", "attestation_object", "client_data_json", "credential_id"],
+    },
+  },
+  {
+    name: "request_authenticator_revoke_challenge",
+    description:
+      "Issues a fresh-assertion challenge to authorize revoking one of a tenant's " +
+      "enrolled WebAuthn authenticators. Requires an INTERACTIVE WebAuthn client + " +
+      "human touch to produce the assertion revoke_authenticator needs — an agent " +
+      "alone cannot authorize a revocation. Requires LOOPCTL_USER_KEY (user role) " +
+      "bound to tenant_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID." },
+      },
+      required: ["tenant_id"],
+    },
+  },
+  {
+    name: "revoke_authenticator",
+    description:
+      "Revokes an enrolled authenticator using the assertion from " +
+      "request_authenticator_revoke_challenge (navigator.credentials.get() against an " +
+      "EXISTING authenticator — human touch required). Refuses (409 last_authenticator) " +
+      "to remove a human_anchored tenant's LAST authenticator — there is no " +
+      "auto-downgrade; losing every authenticator is a fatal, human-recovery-only event " +
+      "(docs/chain-of-custody-v2.md §9.3). Requires LOOPCTL_USER_KEY (user role) bound " +
+      "to tenant_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tenant_id: { type: "string", description: "Tenant UUID." },
+        authenticator_id: { type: "string", description: "UUID of the authenticator to revoke." },
+        webauthn_assertion: {
+          type: "object",
+          description:
+            "The assertion (challenge_id, credential_id, authenticator_data, signature, " +
+            "client_data_json — all base64url) bound to the revoke-challenge.",
+        },
+      },
+      required: ["tenant_id", "authenticator_id", "webauthn_assertion"],
+    },
+  },
   {
     name: "get_sth",
     description: "Get the latest Signed Tree Head for a tenant's audit chain. Public — no auth required.",
@@ -4075,6 +4352,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     case "dispatch":
       return await createDispatch(args);
 
+    case "signup":
+      return await signup(args);
+
+    case "request_authenticator_challenge":
+      return await requestAuthenticatorChallenge(args);
+
+    case "enroll_authenticator":
+      return await enrollAuthenticator(args);
+
+    case "request_authenticator_revoke_challenge":
+      return await requestAuthenticatorRevokeChallenge(args);
+
+    case "revoke_authenticator":
+      return await revokeAuthenticator(args);
+
     case "get_sth":
       return await getSth(args);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopctl-mcp-server",
-  "version": "2.34.0",
+  "version": "2.36.0",
   "description": "MCP server for loopctl — structural trust for AI development loops",
   "type": "module",
   "main": "index.js",