sentinelayer-cli 0.35.4 → 0.36.0

package/README.md

@@ -52,14 +52,15 @@ Live MCP entry points:
 
 - Local stdio server: `sl mcp server run --path .`
 - Hosted token mint: `sl mcp token mint --scope "sessions:read" --ttl-seconds 300 --json`
-- Hosted resource smoke: `POST https://api.sentinelayer.com/mcp` with JSON-RPC `tools/list`
+- Hosted MCP paste URL: `https://api.sentinelayer.com/mcp`
+- Hosted resource smoke: `sl mcp smoke --session <senti-session-id> --json`
 - CLI bridge registry: `sl mcp registry init-cli`; credential-bearing commands are blocked from bridge execution
 
 First-debug path:
 
 1. Run `sl auth status`.
 2. For local MCP, run `sl mcp server validate --file .sentinelayer/mcp/server.<id>.json`.
-3. For hosted MCP, mint a 300-second token and smoke `/mcp` with `tools/list`.
+3. For hosted MCP, run `sl mcp doctor`, then `sl mcp smoke --session <senti-session-id> --json`.
 4. If a bearer or bridge output is exposed, set `SENTINELAYER_MCP_CLI_BRIDGE_DISABLED=1`, restart the MCP host, revoke the requesting CLI auth session with `sl auth revoke`, and follow [docs/mcp.md](docs/mcp.md#bearer-exposure-response).
 
 Architecture map: local stdio runtime and incident response are in
@@ -692,6 +693,7 @@ The CLI now includes deterministic MCP registry commands:
 Use `init-aidenid` to scaffold an Anthropic-compatible tool schema wrapper for AIdenID provisioning APIs, then customize transport/auth before runtime wiring.
 Use `init-aidenid-adapter` to scaffold a deterministic AIdenID provisioning API contract (tool binding -> HTTP path/method -> response field mapping) and cross-check it against the registry with `validate-aidenid-adapter`.
 Use `token mint` to request a short-lived hosted MCP bearer token from the Sentinelayer API. Text output hides the bearer value; `--json` is the explicit operator path that includes `accessToken`. The command is blocked from the generated CLI MCP bridge.
+Use `smoke` to verify the hosted MCP resource without printing the bearer. The canonical remote MCP paste URL is `https://api.sentinelayer.com/mcp`; the token audience/resource value is `https://mcp.sentinelayer.com` and is handled by the OAuth/MCP flow. `sl mcp smoke` works today through the CLI direct-mint path; third-party browser connectors such as Claude.ai still require the OAuth browser-flow and connector-registration work to complete before users can authenticate from that product.
 Use `init-session` plus `server run` for the local stdio Senti MCP server. It exposes session inbox, durable posts, actions/replies/reactions, file locks, and attention requests to local MCP clients. Hosted Claude-web/ChatGPT connectors need a separate HTTPS/OAuth service and are not shipped by the local stdio server. See [docs/mcp.md](docs/mcp.md).
 Use `init-cli` to generate a bridge registry for every `sl` leaf command from Commander metadata. This exposes the full CLI surface as `sl.<command.path>` tool schemas, but execution still requires a bridge-capable MCP host with OAuth/session-seat policy and human approval enforcement. The hosted connector target contract is documented in [docs/mcp-hosted-connector.md](docs/mcp-hosted-connector.md).
 
@@ -700,10 +702,9 @@ MCP operator verification:
 1. Local stdio demo: run `sl mcp registry init-session`, then
    `sl mcp server init --id sentinelayer-session --registry-file .sentinelayer/mcp/tool-registry.session-tools.json`,
    then configure the MCP host to execute `sl mcp server run --path .`.
-2. Hosted token smoke: run
-   `sl mcp token mint --scope "sessions:read sessions:usage:read" --ttl-seconds 300 --json`,
-   place `accessToken` in a local secret variable, and call hosted `/mcp`
-   `tools/list` as shown in [docs/mcp.md](docs/mcp.md).
+2. Hosted resource smoke: run `sl mcp doctor`, then
+   `sl mcp smoke --session <senti-session-id> --json`. The smoke mints the
+   short-lived bearer in memory, calls `/mcp`, and prints only redacted proof.
 3. Kill switch: set `SENTINELAYER_MCP_CLI_BRIDGE_DISABLED=1` and restart the
    MCP host if a CLI bridge or bearer credential is exposed.
 
@@ -728,8 +729,8 @@ sl mcp registry init-cli --json
   `.sentinelayer/mcp/server.<id>.json`.
 - Hosted token mint: `sl mcp token mint --scope "sessions:read" --ttl-seconds 300 --json`,
   backed by `POST /api/v1/auth/mcp-token`.
-- Hosted resource smoke: `POST https://api.sentinelayer.com/mcp` with
-  `Authorization: Bearer $SENTINELAYER_MCP_TOKEN` and JSON-RPC `tools/list`.
+- Hosted MCP paste URL: `https://api.sentinelayer.com/mcp`.
+- Hosted resource smoke: `sl mcp smoke --session <senti-session-id> --json`.
 - Generated CLI bridge registry: `sl mcp registry init-cli`; secret-bearing
   commands such as `sl mcp token mint` are blocked from bridge execution.
 
@@ -740,6 +741,9 @@ Architecture decisions:
   OAuth, session-seat binding, and server-side authorization.
 - Hosted bearer minting is API-owned. The CLI requests a token with existing
   auth and never signs, verifies, or derives token claims locally.
+- The hosted endpoint and token audience are deliberately separate today:
+  paste `https://api.sentinelayer.com/mcp` into remote MCP clients; the bearer
+  audience/resource is `https://mcp.sentinelayer.com` and must remain strict.
 - The generated CLI bridge is fail-closed for credential-bearing commands; use
   direct operator execution for token minting and the documented kill switch for
   containment.
@@ -1119,6 +1123,7 @@ The CLI now supports a command tree, while keeping slash-command compatibility:
 - `sentinelayer-cli daemon reliability run|status` and `daemon maintenance status|on|off` operate the midnight synthetic lane and maintenance billboard lifecycle
 - `sentinelayer-cli mcp schema|registry|server|bridge ...` manages MCP registry schema, server configs, and VS Code bridge scaffolds
 - `sentinelayer-cli mcp token mint --scope "sessions:read" --ttl-seconds 300 --json` mints a short-lived hosted MCP bearer; text mode hides the secret, and generated CLI bridge execution blocks this command
+- `sentinelayer-cli mcp smoke --session <id> --json` verifies hosted `/mcp` tools and optional Senti room reads without printing bearer values
 - `sentinelayer-cli plugin init|validate|list|order` manages plugin/template/policy packs and deterministic load-order governance
 - `sentinelayer-cli policy list|use <pack-id>` manages active policy pack selection (`community`, `strict`, `compliance-soc2`, `compliance-hipaa`, plugin packs)
 - `sentinelayer-cli ai provision-email` scaffolds and optionally executes AIdenID identity provisioning requests
@@ -1151,5 +1156,6 @@ Roadmap:
 - `GitHub CLI not installed`: install `gh` or run manual fallback.
 - `Invalid repo format`: use exact `owner/repo`.
 - `Missing token in workflow`: ensure `.github/workflows/omar-gate.yml` maps `sentinelayer_token: ${{ secrets.SENTINELAYER_TOKEN }}`.
+- `INVALID_MCP_TOKEN` on hosted MCP: verify the client is calling `https://api.sentinelayer.com/mcp` and using a fresh token whose audience/resource is `https://mcp.sentinelayer.com`; run `sentinelayer-cli mcp smoke --session <id> --json` for redacted proof.
 - `Hosted MCP bearer exposed`: set `SENTINELAYER_MCP_CLI_BRIDGE_DISABLED=1`, restart the MCP host, revoke/rotate the requesting CLI auth session with `sentinelayer-cli auth revoke`, and follow [docs/mcp.md](docs/mcp.md#bearer-exposure-response).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinelayer-cli",
-  "version": "0.35.4",
+  "version": "0.36.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/mcp.js

@@ -32,6 +32,7 @@ import { requestHostedMcpAccessToken } from "../mcp/token-service.js";
 import { buildSentinelayerCliRegistryTemplate } from "../mcp/cli-registry.js";
 import { runMcpStdioServer } from "../mcp/session-stdio-server.js";
 import { runMcpDoctorProbes } from "../mcp/doctor.js";
+import { runHostedMcpSmoke } from "../mcp/smoke.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { resolveOutputRoot } from "../config/service.js";
 
@@ -230,6 +231,84 @@ Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
       console.log(pc.gray("Secret value hidden in text output; use --json when you need the bearer value."));
     });
 
+  mcp
+    .command("smoke")
+    .description(
+      "Smoke the hosted MCP resource with an in-memory bearer; prints only redacted proof"
+    )
+    .option("--session <id>", "Optional Senti session id to read through sessions.events.list")
+    .option("--limit <n>", "Maximum session events to read when --session is set", "5")
+    .option(
+      "--scope <scopes>",
+      "Space- or comma-separated MCP scopes for the smoke token",
+      "sessions:read"
+    )
+    .option("--ttl-seconds <seconds>", "Token lifetime in seconds (API default and maximum are server-configured)")
+    .option("--timeout-ms <ms>", "Sentinelayer API/MCP request timeout in milliseconds", String(DEFAULT_REQUEST_TIMEOUT_MS))
+    .option("--api-url <url>", "Override Sentinelayer API base URL")
+    .option("--no-auto-rotate", "Disable stored CLI token rotation before minting")
+    .option("--json", "Emit machine-readable redacted proof")
+    .action(async (options, command) => {
+      const emitJson = shouldEmitJson(options, command);
+      let result;
+      try {
+        result = await runHostedMcpSmoke({
+          cwd: process.cwd(),
+          env: process.env,
+          explicitApiUrl: options.apiUrl,
+          autoRotate: options.autoRotate !== false,
+          scope: options.scope,
+          ttlSeconds: options.ttlSeconds,
+          timeoutMs: options.timeoutMs,
+          sessionId: options.session,
+          limit: options.limit,
+        });
+      } catch (error) {
+        throw new Error(formatApiError(error));
+      }
+
+      const payload = { command: "mcp smoke", ...result };
+      if (emitJson) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else {
+        console.log(pc.bold(`Hosted MCP smoke — ${result.mcpUrl}`));
+        console.log(pc.gray("Bearer value is redacted and never printed by this command."));
+        const credentialMetadata = result.token;
+        console.log(`Issuer: ${credentialMetadata.issuer}`);
+        console.log(`Audience: ${credentialMetadata.audience}`);
+        console.log(`Scope: ${credentialMetadata.scope}`);
+        if (credentialMetadata.expiresAt) {
+          console.log(`Expires at: ${credentialMetadata.expiresAt}`);
+        }
+        for (const probe of result.probes) {
+          const mark = probe.verdict === "PASS" ? pc.green("PASS") : pc.red("FAIL");
+          console.log(`  [${mark}] ${probe.label}  (HTTP ${probe.status})`);
+          if (Array.isArray(probe.toolNames) && probe.toolNames.length > 0) {
+            console.log(pc.gray(`         tools=${probe.toolNames.join(", ")}`));
+          }
+          if (probe.eventCount !== undefined) {
+            console.log(
+              pc.gray(
+                `         events=${probe.eventCount} first=${probe.firstSequenceId ?? "-"} last=${probe.lastSequenceId ?? "-"}`
+              )
+            );
+          }
+          if (probe.detail) {
+            console.log(pc.gray(`         ${probe.detail}`));
+          }
+        }
+        console.log(
+          result.ok
+            ? pc.green("Hosted MCP smoke passed.")
+            : pc.red("Hosted MCP smoke FAILED — inspect the failing probe above.")
+        );
+      }
+
+      if (!result.ok) {
+        process.exitCode = 1;
+      }
+    });
+
   mcp
     .command("doctor")
     .description(

package/src/mcp/smoke.js

@@ -0,0 +1,328 @@
+import process from "node:process";
+
+import { DEFAULT_REQUEST_TIMEOUT_MS } from "../auth/http.js";
+import { requestHostedMcpAccessToken } from "./token-service.js";
+
+const PASS = "PASS";
+const FAIL = "FAIL";
+
+function joinUrl(base, suffix) {
+  const normalizedBase = String(base || "").replace(/\/+$/, "");
+  const normalizedSuffix = String(suffix || "").replace(/^\/+/, "");
+  return `${normalizedBase}/${normalizedSuffix}`;
+}
+
+function normalizePositiveNumber(rawValue, field, fallbackValue) {
+  if (rawValue === undefined || rawValue === null || String(rawValue).trim() === "") {
+    return fallbackValue;
+  }
+  const normalized = Number(rawValue);
+  if (!Number.isFinite(normalized) || normalized <= 0) {
+    throw new Error(`${field} must be a positive number.`);
+  }
+  return normalized;
+}
+
+function normalizeOptionalPositiveInteger(rawValue, field) {
+  if (rawValue === undefined || rawValue === null || String(rawValue).trim() === "") {
+    return null;
+  }
+  const normalized = Number(rawValue);
+  if (!Number.isFinite(normalized) || normalized <= 0 || !Number.isInteger(normalized)) {
+    throw new Error(`${field} must be a positive integer.`);
+  }
+  return normalized;
+}
+
+function normalizeSessionId(rawValue) {
+  return String(rawValue || "").trim();
+}
+
+function redactExactSecret(text, secret) {
+  const normalizedSecret = String(secret || "");
+  if (!normalizedSecret) {
+    return text;
+  }
+  return String(text).split(normalizedSecret).join("[REDACTED]");
+}
+
+export function redactMcpSmokeText(value, secrets = []) {
+  let text = String(value || "");
+  for (const secret of Array.isArray(secrets) ? secrets : [secrets]) {
+    text = redactExactSecret(text, secret);
+  }
+  return text
+    .replace(/\bBearer\s+[A-Za-z0-9._~+/-]+=*/gi, "Bearer [REDACTED]")
+    .replace(
+      /\b(?:access[_-]?token|refresh[_-]?token|id[_-]?token|api[_-]?key|token|secret|password)\b\s*[:=]\s*["']?[^"',\s}]+/gi,
+      (match) => {
+        const [prefix = "token"] = match.split(/[:=]/);
+        return `${prefix.trim()}=[REDACTED]`;
+      },
+    );
+}
+
+function summarizeJsonRpcError(error, secrets = []) {
+  if (!error) {
+    return "unknown JSON-RPC error";
+  }
+  const code = error.code === undefined || error.code === null ? "unknown" : String(error.code);
+  const message = redactMcpSmokeText(error.message || "JSON-RPC error", secrets);
+  return `JSON-RPC error ${code}: ${message}`;
+}
+
+async function postJsonRpc({
+  fetchImpl,
+  url,
+  accessToken,
+  payload,
+  timeoutMs,
+  redactionSecrets = [],
+}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    const text = await response.text().catch(() => "");
+    let json = null;
+    if (text) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = null;
+      }
+    }
+    return {
+      reached: true,
+      status: response.status,
+      json,
+      detail: json ? "" : redactMcpSmokeText(text, redactionSecrets),
+    };
+  } catch (error) {
+    const aborted = Boolean(error) && error.name === "AbortError";
+    return {
+      reached: false,
+      status: 0,
+      json: null,
+      detail: aborted
+        ? `timed out after ${timeoutMs}ms`
+        : redactMcpSmokeText(
+            error instanceof Error ? error.message : String(error || "network error"),
+            redactionSecrets,
+          ),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function structuredEvents(result) {
+  const structured = result?.structuredContent;
+  if (structured && Array.isArray(structured.events)) {
+    return structured.events;
+  }
+  return [];
+}
+
+/**
+ * Smoke the hosted MCP resource with a short-lived in-memory bearer.
+ *
+ * This intentionally returns token metadata only. The bearer value is used for
+ * the /mcp calls and then discarded so JSON/text output can be pasted into
+ * Senti or PRs without exposing credentials.
+ */
+export async function runHostedMcpSmoke({
+  cwd = process.cwd(),
+  env = process.env,
+  explicitApiUrl = "",
+  autoRotate = true,
+  scope = "sessions:read",
+  ttlSeconds = null,
+  timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+  sessionId = "",
+  limit = 5,
+  homeDir,
+  requestTokenImpl = requestHostedMcpAccessToken,
+  fetchImpl = fetch,
+} = {}) {
+  const normalizedTimeoutMs = normalizePositiveNumber(timeoutMs, "timeoutMs", DEFAULT_REQUEST_TIMEOUT_MS);
+  const normalizedLimit = normalizeOptionalPositiveInteger(limit, "limit") || 5;
+  const normalizedSessionId = normalizeSessionId(sessionId);
+
+  const minted = await requestTokenImpl({
+    cwd,
+    env,
+    explicitApiUrl,
+    autoRotate,
+    scope,
+    ttlSeconds,
+    timeoutMs: normalizedTimeoutMs,
+    homeDir,
+  });
+  const accessToken = String(minted.accessToken || "");
+  if (!accessToken) {
+    throw new Error("Hosted MCP token mint succeeded but returned no access token.");
+  }
+  const redactionSecrets = [accessToken];
+
+  const mcpUrl = joinUrl(minted.apiUrl, "/mcp");
+  const probes = [];
+  const toolNames = [];
+
+  const toolsResponse = await postJsonRpc({
+    fetchImpl,
+    url: mcpUrl,
+    accessToken,
+    timeoutMs: normalizedTimeoutMs,
+    redactionSecrets,
+    payload: {
+      jsonrpc: "2.0",
+      id: "mcp-smoke-tools",
+      method: "tools/list",
+      params: {},
+    },
+  });
+
+  if (!toolsResponse.reached) {
+    probes.push({
+      id: "tools_list",
+      label: "MCP tools/list",
+      status: toolsResponse.status,
+      verdict: FAIL,
+      detail: toolsResponse.detail,
+    });
+  } else if (toolsResponse.status !== 200) {
+    probes.push({
+      id: "tools_list",
+      label: "MCP tools/list",
+      status: toolsResponse.status,
+      verdict: FAIL,
+      detail: `expected HTTP 200, got HTTP ${toolsResponse.status}`,
+    });
+  } else if (toolsResponse.json?.error) {
+    probes.push({
+      id: "tools_list",
+      label: "MCP tools/list",
+      status: toolsResponse.status,
+      verdict: FAIL,
+      detail: summarizeJsonRpcError(toolsResponse.json.error, redactionSecrets),
+    });
+  } else {
+    for (const tool of toolsResponse.json?.result?.tools || []) {
+      const name = String(tool?.name || "").trim();
+      if (name) {
+        toolNames.push(name);
+      }
+    }
+    probes.push({
+      id: "tools_list",
+      label: "MCP tools/list",
+      status: toolsResponse.status,
+      verdict: toolNames.length > 0 ? PASS : FAIL,
+      detail: toolNames.length > 0 ? `${toolNames.length} tool(s) returned` : "tools/list returned no tools",
+      toolNames,
+    });
+  }
+
+  if (normalizedSessionId) {
+    if (!toolNames.includes("sessions.events.list")) {
+      probes.push({
+        id: "session_events_list",
+        label: "MCP sessions.events.list",
+        status: 0,
+        verdict: FAIL,
+        detail: "sessions.events.list tool was not advertised by tools/list",
+        sessionId: normalizedSessionId,
+      });
+    } else {
+      const eventsResponse = await postJsonRpc({
+        fetchImpl,
+        url: mcpUrl,
+        accessToken,
+        timeoutMs: normalizedTimeoutMs,
+        redactionSecrets,
+        payload: {
+          jsonrpc: "2.0",
+          id: "mcp-smoke-events",
+          method: "tools/call",
+          params: {
+            name: "sessions.events.list",
+            arguments: {
+              sessionId: normalizedSessionId,
+              limit: normalizedLimit,
+            },
+          },
+        },
+      });
+
+      if (!eventsResponse.reached) {
+        probes.push({
+          id: "session_events_list",
+          label: "MCP sessions.events.list",
+          status: eventsResponse.status,
+          verdict: FAIL,
+          detail: eventsResponse.detail,
+          sessionId: normalizedSessionId,
+        });
+      } else if (eventsResponse.status !== 200) {
+        probes.push({
+          id: "session_events_list",
+          label: "MCP sessions.events.list",
+          status: eventsResponse.status,
+          verdict: FAIL,
+          detail: `expected HTTP 200, got HTTP ${eventsResponse.status}`,
+          sessionId: normalizedSessionId,
+        });
+      } else if (eventsResponse.json?.error) {
+        probes.push({
+          id: "session_events_list",
+          label: "MCP sessions.events.list",
+          status: eventsResponse.status,
+          verdict: FAIL,
+          detail: summarizeJsonRpcError(eventsResponse.json.error, redactionSecrets),
+          sessionId: normalizedSessionId,
+        });
+      } else {
+        const events = structuredEvents(eventsResponse.json?.result);
+        const sequences = events
+          .map((event) => Number(event?.sequenceId))
+          .filter((value) => Number.isFinite(value));
+        probes.push({
+          id: "session_events_list",
+          label: "MCP sessions.events.list",
+          status: eventsResponse.status,
+          verdict: PASS,
+          detail: `${events.length} event(s) returned`,
+          sessionId: normalizedSessionId,
+          eventCount: events.length,
+          firstSequenceId: sequences.length ? Math.min(...sequences) : null,
+          lastSequenceId: sequences.length ? Math.max(...sequences) : null,
+        });
+      }
+    }
+  }
+
+  return {
+    apiUrl: minted.apiUrl,
+    mcpUrl,
+    ok: probes.every((probe) => probe.verdict !== FAIL),
+    token: {
+      redacted: true,
+      tokenType: minted.tokenType,
+      expiresIn: minted.expiresIn,
+      expiresAt: minted.expiresAt,
+      issuer: minted.issuer,
+      audience: minted.audience,
+      scope: minted.scope,
+    },
+    probes,
+  };
+}