sentinelayer-cli 0.32.4 → 0.33.0

package/README.md

@@ -46,6 +46,27 @@ sl watch run-events --run-id <run-id>
 
 Windows PowerShell note: `sl` is a built-in alias for `Set-Location`. Use `sentinelayer-cli` (or short alias `slc`) instead.
 
+## MCP Live Entry Points And Incident Response
+
+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`
+- 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`.
+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
+[docs/mcp.md](docs/mcp.md); hosted OAuth/session-seat design is in
+[docs/mcp-hosted-connector.md](docs/mcp-hosted-connector.md); session
+coordination behavior is in [docs/sessions.md](docs/sessions.md).
+
 ## 60-second flow
 
 1. Trigger:
@@ -662,6 +683,7 @@ The CLI now includes deterministic MCP registry commands:
 - `sl mcp registry init-cli`
 - `sl mcp registry validate --file <path>`
 - `sl mcp registry validate-aidenid-adapter --file <path> [--registry-file <path>]`
+- `sl mcp token mint --scope "sessions:read sessions:usage:read" --ttl-seconds 300 --json`
 - `sl mcp server init --id <server-id> --registry-file <path>`
 - `sl mcp server validate --file <path>`
 - `sl mcp server run --path .`
@@ -669,9 +691,60 @@ 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 `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).
 
+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).
+3. Kill switch: set `SENTINELAYER_MCP_CLI_BRIDGE_DISABLED=1` and restart the
+   MCP host if a CLI bridge or bearer credential is exposed.
+
+Architecture references: local stdio runtime and incident response live in
+[docs/mcp.md](docs/mcp.md); hosted OAuth/session-seat requirements live in
+[docs/mcp-hosted-connector.md](docs/mcp-hosted-connector.md); Senti room
+coordination behavior lives in [docs/sessions.md](docs/sessions.md).
+
+### MCP Live Entry Point Map
+
+- Local stdio server: `sl mcp server run --path .`, configured from
+  `.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`.
+- Generated CLI bridge registry: `sl mcp registry init-cli`; secret-bearing
+  commands such as `sl mcp token mint` are blocked from bridge execution.
+
+Architecture decisions:
+
+- Local stdio and hosted HTTPS MCP are intentionally separate. Browser-hosted
+  clients cannot spawn the local process, so hosted execution must enforce
+  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 generated CLI bridge is fail-closed for credential-bearing commands; use
+  direct operator execution for token minting and the documented kill switch for
+  containment.
+
+### MCP Incident Response And Kill Switch
+
+If a hosted MCP bearer or bridge command output is exposed:
+
+1. Set `SENTINELAYER_MCP_CLI_BRIDGE_DISABLED=1`.
+2. Restart the MCP host process so the generated CLI bridge cannot execute.
+3. Run `sentinelayer-cli auth revoke` or revoke the requesting session from the
+   dashboard, then re-authenticate with `sentinelayer-cli auth login`.
+4. Remove the exposed value from local logs/transcripts where possible.
+5. Verify `/mcp` rejects the old bearer after expiry or revocation.
+
 ## Plugin governance foundation (Phase 5.2 slice)
 
 The CLI now includes deterministic plugin/template/policy pack governance commands:
@@ -1035,6 +1108,7 @@ The CLI now supports a command tree, while keeping slash-command compatibility:
 - `sentinelayer-cli daemon map scope|list|show` builds hybrid deterministic+semantic impact scopes with import-graph overlay for daemon work items
 - `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 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
@@ -1067,4 +1141,5 @@ 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 }}`.
+- `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.32.4",
+  "version": "0.33.0",
   "description": "Scaffold Sentinelayer spec/prompt/guide artifacts with secure browser auth and token bootstrap.",
   "type": "module",
   "scripts": {

package/src/commands/mcp.js

@@ -6,6 +6,7 @@ import { ZodError } from "zod";
 
 import fs from "node:fs/promises";
 
+import { DEFAULT_REQUEST_TIMEOUT_MS, SentinelayerApiError } from "../auth/http.js";
 import {
   buildAidenIdProvisioningAdapterTemplate,
   buildHostedSentiSessionConnectorContract,
@@ -27,6 +28,7 @@ import {
   validateMcpToolRegistry,
   writeJsonFile,
 } from "../mcp/registry.js";
+import { requestHostedMcpAccessToken } from "../mcp/token-service.js";
 import { buildSentinelayerCliRegistryTemplate } from "../mcp/cli-registry.js";
 import { runMcpStdioServer } from "../mcp/session-stdio-server.js";
 import { resolveOutputRoot } from "../config/service.js";
@@ -56,6 +58,14 @@ function zodIssueSummary(error) {
     .join("; ");
 }
 
+function formatApiError(error) {
+  if (!(error instanceof SentinelayerApiError)) {
+    return error instanceof Error ? error.message : String(error || "Unknown error");
+  }
+  const requestId = error.requestId ? ` request_id=${error.requestId}` : "";
+  return `${error.message} [${error.code}] status=${error.status}${requestId}`;
+}
+
 export function registerMcpCommand(program) {
   const mcp = program.command("mcp").description("Manage Sentinelayer MCP registry schemas and adapters");
 
@@ -113,6 +123,67 @@ export function registerMcpCommand(program) {
       }
     });
 
+  const token = mcp.command("token").description("Mint hosted MCP resource tokens");
+
+  token
+    .command("mint")
+    .description("Mint a short-lived bearer token for the hosted Sentinelayer MCP resource")
+    .option(
+      "--scope <scopes>",
+      "Space- or comma-separated MCP scopes (API default: sessions:read)"
+    )
+    .option("--ttl-seconds <seconds>", "Token lifetime in seconds (API default and maximum are server-configured)")
+    .option("--timeout-ms <ms>", "Sentinelayer API 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 output, including the minted access token")
+    .action(async (options, command) => {
+      const emitJson = shouldEmitJson(options, command);
+      let result;
+      try {
+        result = await requestHostedMcpAccessToken({
+          cwd: process.cwd(),
+          env: process.env,
+          explicitApiUrl: options.apiUrl,
+          autoRotate: options.autoRotate !== false,
+          scope: options.scope,
+          ttlSeconds: options.ttlSeconds,
+          timeoutMs: options.timeoutMs,
+        });
+      } catch (error) {
+        throw new Error(formatApiError(error));
+      }
+
+      const payload = {
+        command: "mcp token mint",
+        apiUrl: result.apiUrl,
+        authSource: result.authSource,
+        rotated: result.rotated,
+        accessToken: result.accessToken,
+        tokenType: result.tokenType,
+        expiresIn: result.expiresIn,
+        expiresAt: result.expiresAt,
+        issuer: result.issuer,
+        audience: result.audience,
+        scope: result.scope,
+      };
+      if (emitJson) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+
+      console.log(pc.green("Minted hosted MCP bearer credential"));
+      console.log(pc.gray(`API: ${payload.apiUrl}`));
+      console.log(`Expires in: ${payload.expiresIn}s`);
+      if (payload.expiresAt) {
+        console.log(`Expires at: ${payload.expiresAt}`);
+      }
+      console.log(`Issuer: ${payload.issuer}`);
+      console.log(`Audience: ${payload.audience}`);
+      console.log(`Scope: ${payload.scope}`);
+      console.log(pc.gray("Secret value hidden in text output; use --json when you need the bearer value."));
+    });
+
   const schema = mcp.command("schema").description("Inspect or materialize MCP tool-registry schema");
   schema
     .command("show")

package/src/mcp/cli-command-tools.js

@@ -17,6 +17,7 @@ const SENSITIVE_COMMAND_PATHS = new Set([
   "auth.login",
   "auth.logout",
   "auth.revoke",
+  "mcp.token.mint",
   "config.edit",
   "config.get",
   "config.list",

package/src/mcp/token-service.js

@@ -0,0 +1,156 @@
+import process from "node:process";
+
+import { DEFAULT_REQUEST_TIMEOUT_MS, requestJsonMutation } from "../auth/http.js";
+import {
+  DEFAULT_API_TOKEN_TTL_DAYS,
+  DEFAULT_TOKEN_ROTATE_THRESHOLD_DAYS,
+  resolveActiveAuthSession,
+} from "../auth/service.js";
+import { authLoginHint } from "../ui/command-hints.js";
+
+function normalizePositiveNumber(rawValue, field, fallbackValue) {
+  if (rawValue === undefined || rawValue === null || String(rawValue).trim() === "") {
+    if (fallbackValue !== undefined) {
+      return fallbackValue;
+    }
+    throw new Error(`${field} must be a positive number.`);
+  }
+  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 buildApiPath(apiUrl, pathSuffix) {
+  const base = String(apiUrl || "").replace(/\/+$/, "");
+  const suffix = String(pathSuffix || "").replace(/^\/+/, "");
+  return `${base}/${suffix}`;
+}
+
+function toAuthHeader(token) {
+  return {
+    Authorization: `Bearer ${String(token || "").trim()}`,
+  };
+}
+
+function applyScope(body, { scope = "", scopes } = {}) {
+  const normalizedScope = String(scope || "").trim();
+  const normalizedScopes = Array.isArray(scopes)
+    ? scopes.map((item) => String(item || "").trim()).filter(Boolean)
+    : String(scopes || "").trim();
+  if (normalizedScope && normalizedScopes && (!Array.isArray(normalizedScopes) || normalizedScopes.length > 0)) {
+    throw new Error("Use either scope or scopes, not both.");
+  }
+  if (normalizedScope) {
+    body.scope = normalizedScope;
+  } else if (Array.isArray(normalizedScopes) && normalizedScopes.length > 0) {
+    body.scopes = normalizedScopes;
+  } else if (typeof normalizedScopes === "string" && normalizedScopes) {
+    body.scope = normalizedScopes;
+  }
+}
+
+/**
+ * Request a short-lived hosted MCP bearer credential.
+ * The CLI authenticates with its existing Sentinelayer API token; the API
+ * performs all credential minting server-side and returns the secret in-memory.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   explicitApiUrl?: string,
+ *   autoRotate?: boolean,
+ *   rotateThresholdDays?: number,
+ *   tokenLabel?: string,
+ *   tokenTtlDays?: number,
+ *   homeDir?: string,
+ *   scope?: string,
+ *   scopes?: string[] | string,
+ *   ttlSeconds?: number | string | null,
+ *   timeoutMs?: number | string | null
+ * }} [options]
+ * @returns {Promise<{
+ *   apiUrl: string,
+ *   authSource: string,
+ *   rotated: boolean,
+ *   accessToken: string,
+ *   tokenType: string,
+ *   expiresIn: number,
+ *   expiresAt: string,
+ *   issuer: string,
+ *   audience: string,
+ *   scope: string
+ * }>}
+ */
+export async function requestHostedMcpAccessToken({
+  cwd = process.cwd(),
+  env = process.env,
+  explicitApiUrl = "",
+  autoRotate = true,
+  rotateThresholdDays = DEFAULT_TOKEN_ROTATE_THRESHOLD_DAYS,
+  tokenLabel = "",
+  tokenTtlDays = DEFAULT_API_TOKEN_TTL_DAYS,
+  homeDir,
+  scope = "",
+  scopes,
+  ttlSeconds = null,
+  timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS,
+} = {}) {
+  const session = await resolveActiveAuthSession({
+    cwd,
+    env,
+    explicitApiUrl,
+    autoRotate,
+    rotateThresholdDays,
+    tokenLabel,
+    tokenTtlDays,
+    homeDir,
+  });
+  if (!session || !session.token) {
+    throw new Error(`Not authenticated. Run \`${authLoginHint()}\` first.`);
+  }
+
+  const body = {};
+  applyScope(body, { scope, scopes });
+  const normalizedTtlSeconds = normalizeOptionalPositiveInteger(ttlSeconds, "ttlSeconds");
+  if (normalizedTtlSeconds !== null) {
+    body.ttl_seconds = normalizedTtlSeconds;
+  }
+  const normalizedTimeoutMs = normalizePositiveNumber(timeoutMs, "timeoutMs", DEFAULT_REQUEST_TIMEOUT_MS);
+
+  const response = await requestJsonMutation(
+    buildApiPath(session.apiUrl, "/api/v1/auth/mcp-token"),
+    {
+      method: "POST",
+      operationName: "mcp-token-mint",
+      headers: toAuthHeader(session.token),
+      body,
+      timeoutMs: normalizedTimeoutMs,
+    }
+  );
+
+  return {
+    apiUrl: session.apiUrl,
+    authSource: session.source,
+    rotated: Boolean(session.rotated),
+    accessToken: String(response.access_token || ""),
+    tokenType: String(response.token_type || "Bearer"),
+    expiresIn: Number(response.expires_in || 0),
+    expiresAt: String(response.expires_at || ""),
+    issuer: String(response.issuer || ""),
+    audience: String(response.audience || ""),
+    scope: String(response.scope || ""),
+  };
+}

package/src/session/usage-report.js

@@ -124,7 +124,7 @@ function hostedRollupToJson(rollup, fallbackLabel = "") {
   const hasCustomerCost = Boolean(bag.hasCustomerCost ?? bag.has_customer_cost ?? bag.customerCostUsd != null ?? bag.customer_cost_usd != null);
   return {
     label: normalize(bag.label ?? bag.agentId ?? bag.agent_id ?? bag.action ?? fallbackLabel) || "unknown",
-    entries: nonNegativeInt(bag.entries ?? bag.count),
+    entries: nonNegativeInt(bag.entries ?? bag.entryCount ?? bag.entry_count ?? bag.count ?? bag.interactions),
     inputTokens: nonNegativeInt(bag.inputTokens ?? bag.input_tokens),
     outputTokens: nonNegativeInt(bag.outputTokens ?? bag.output_tokens),
     totalTokens: nonNegativeInt(bag.totalTokens ?? bag.total_tokens),
@@ -249,11 +249,24 @@ export function buildSessionUsageReportFromLedgerPayload({
     ? embedded
     : root;
   const entries = sourceArray(source.entries).map(hostedEntryToJson);
-  const totals = hostedRollupToJson(object(source.totals), "session");
-  const priceBookVersions = sourceArray(source.priceBooks || source.price_books || source.priceBookVersions || source.price_book_versions)
+  const sourceTotals = object(source.totals);
+  const totals = hostedRollupToJson(sourceTotals, "session");
+  const priceBookVersions = sourceArray(
+    source.priceBooks ||
+      source.price_books ||
+      source.priceBookVersions ||
+      source.price_book_versions ||
+      sourceTotals.priceBooks ||
+      sourceTotals.price_books ||
+      sourceTotals.priceBookVersions ||
+      sourceTotals.price_book_versions,
+  )
     .map(normalize)
     .filter(Boolean)
     .sort();
+  const resolvedPriceBookVersions = priceBookVersions.length
+    ? priceBookVersions
+    : [...new Set(entries.map((entry) => normalize(entry.priceBookVersion)).filter(Boolean))].sort();
   const limit = clampRecentLimit(recentLimit);
   return {
     schema: SESSION_USAGE_REPORT_SCHEMA,
@@ -268,12 +281,28 @@ export function buildSessionUsageReportFromLedgerPayload({
       providerCostUsd: totals.providerCostUsd,
       customerCostUsd: totals.customerCostUsd,
       unpriced: totals.unpriced,
-      priceBookVersions,
+      priceBookVersions: resolvedPriceBookVersions,
     },
-    perAgent: sourceArray(source.agents || source.perAgent || source.per_agent || source.agentsById || source.agents_by_id)
+    perAgent: sourceArray(
+      source.agents ||
+        source.perAgent ||
+        source.per_agent ||
+        source.byAgent ||
+        source.by_agent ||
+        source.agentsById ||
+        source.agents_by_id,
+    )
       .map((rollup) => hostedRollupToJson(rollup))
       .sort((a, b) => b.providerCostUsd - a.providerCostUsd || b.totalTokens - a.totalTokens || a.label.localeCompare(b.label)),
-    perAction: sourceArray(source.actions || source.perAction || source.per_action || source.actionsById || source.actions_by_id)
+    perAction: sourceArray(
+      source.actions ||
+        source.perAction ||
+        source.per_action ||
+        source.byAction ||
+        source.by_action ||
+        source.actionsById ||
+        source.actions_by_id,
+    )
       .map((rollup) => hostedRollupToJson(rollup))
       .sort((a, b) => b.providerCostUsd - a.providerCostUsd || b.totalTokens - a.totalTokens || a.label.localeCompare(b.label)),
     recentEntries: recentReportEntries(entries, limit),