sentinelayer-cli 0.32.5 → 0.34.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,70 @@ 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).
+
+Worked MCP examples:
+
+```bash
+sl mcp list --json
+sl mcp registry init-session --force
+sl mcp server init --id sentinelayer-session --registry-file .sentinelayer/mcp/tool-registry.session-tools.json
+sl mcp server run --path .
+sl mcp registry init-cli --json
+```
+
+### 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:
@@ -747,7 +830,7 @@ gh secret set SENTINELAYER_TOKEN --repo <owner/repo>
 gh secret list --repo <owner/repo>
 ```
 
-3. For manual setup details: `https://sentinelayer.com/docs/getting-started/install-workflow`
+3. For manual setup details: `https://github.com/mrrCarter/create-sentinelayer#manual-fallback-if-auto-injection-is-skipped`
 
 4. BYOK mode (no Sentinelayer token):
    - keep generated `docs/spec.md`, `docs/build-guide.md`, `prompts/execution-prompt.md`, and `tasks/todo.md`
@@ -1035,6 +1118,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 +1151,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.5",
+  "version": "0.34.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,8 +28,11 @@ 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 { runMcpDoctorProbes } from "../mcp/doctor.js";
+import { resolveActiveAuthSession } from "../auth/service.js";
 import { resolveOutputRoot } from "../config/service.js";
 
 function shouldEmitJson(options, command) {
@@ -56,8 +60,60 @@ 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 async function resolveMcpDoctorApiBaseUrl({
+  explicitApiUrl = "",
+  cwd = process.cwd(),
+  env = process.env,
+  resolveActiveAuthSessionImpl = resolveActiveAuthSession,
+} = {}) {
+  const directApiUrl = String(explicitApiUrl || "").trim();
+  if (directApiUrl) {
+    return directApiUrl;
+  }
+
+  // Probes are unauthenticated, but the API base URL can live in the CLI auth
+  // config. Read it without token rotation so doctor remains side-effect-free.
+  try {
+    const session = await resolveActiveAuthSessionImpl({
+      cwd,
+      env,
+      autoRotate: false,
+    });
+    return String((session && session.apiUrl) || "").trim();
+  } catch {
+    return "";
+  }
+}
+
 export function registerMcpCommand(program) {
-  const mcp = program.command("mcp").description("Manage Sentinelayer MCP registry schemas and adapters");
+  const mcp = program
+    .command("mcp")
+    .description("Manage local MCP registries, stdio servers, and guarded CLI bridge metadata")
+    .addHelpText(
+      "after",
+      `
+Examples:
+  sl mcp list --json
+  sl mcp registry init-session --force
+  sl mcp server init --id sentinelayer-session --registry-file .sentinelayer/mcp/tool-registry.session-tools.json
+  sl mcp server run --path .
+  sl mcp registry init-cli --json
+
+Notes:
+  Local stdio MCP works for clients that can spawn the CLI process.
+  Hosted Claude/ChatGPT connectors require the separate HTTPS/OAuth hosted connector contract.
+  Generated CLI bridge tools are metadata only until a bridge host enforces auth, approval, and runtime policy.
+
+Docs: https://github.com/mrrCarter/create-sentinelayer/blob/main/docs/mcp.md`,
+    );
 
   mcp
     .command("list")
@@ -113,6 +169,126 @@ 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."));
+    });
+
+  mcp
+    .command("doctor")
+    .description(
+      "Diagnose hosted MCP auth: probe the OAuth discovery chain (PRM, AS metadata, JWKS) and verify unauthenticated /mcp is rejected"
+    )
+    .option(
+      "--api-url <url>",
+      "Sentinelayer API base URL to probe (default: resolved from your CLI auth session)"
+    )
+    .option("--timeout-ms <ms>", "Per-probe request timeout in milliseconds", String(DEFAULT_REQUEST_TIMEOUT_MS))
+    .option("--json", "Emit machine-readable output")
+    .action(async (options, command) => {
+      const emitJson = shouldEmitJson(options, command);
+      const parsedTimeout = Number(options.timeoutMs);
+      const timeoutMs =
+        Number.isFinite(parsedTimeout) && parsedTimeout > 0 ? parsedTimeout : DEFAULT_REQUEST_TIMEOUT_MS;
+
+      const apiBaseUrl = await resolveMcpDoctorApiBaseUrl({
+        explicitApiUrl: options.apiUrl,
+        cwd: process.cwd(),
+        env: process.env,
+      });
+      if (!apiBaseUrl) {
+        throw new Error(
+          "Could not resolve the Sentinelayer API URL. Pass --api-url <url>, or run `sl auth login` first."
+        );
+      }
+
+      const result = await runMcpDoctorProbes({ apiBaseUrl, timeoutMs });
+
+      if (emitJson) {
+        console.log(JSON.stringify({ command: "mcp doctor", ...result }, null, 2));
+      } else {
+        console.log(pc.bold(`MCP auth doctor — ${result.apiBaseUrl}`));
+        for (const probe of result.probes) {
+          const mark =
+            probe.verdict === "PASS"
+              ? pc.green("PASS")
+              : probe.verdict === "WARN"
+                ? pc.yellow("WARN")
+                : pc.red("FAIL");
+          console.log(`  [${mark}] ${probe.label}  (HTTP ${probe.status})`);
+          console.log(pc.gray(`         ${probe.url}`));
+          if (probe.detail) {
+            console.log(pc.gray(`         ${probe.detail}`));
+          }
+        }
+        console.log(
+          result.ok
+            ? pc.green("All critical MCP auth probes passed.")
+            : pc.red("One or more MCP auth probes FAILED — remote agents may not authenticate correctly.")
+        );
+      }
+
+      if (!result.ok) {
+        process.exitCode = 1;
+      }
+    });
+
   const schema = mcp.command("schema").description("Inspect or materialize MCP tool-registry schema");
   schema
     .command("show")
@@ -300,7 +476,7 @@ export function registerMcpCommand(program) {
 
   registry
     .command("init-cli")
-    .description("Write a generated MCP registry for every SentinelLayer CLI leaf command")
+    .description("Write guarded sl.* CLI bridge metadata for bridge-capable MCP hosts")
     .option("--path <path>", "Destination file path override")
     .option("--output-dir <path>", "Optional artifact output root override")
     .option("--force", "Overwrite destination file if it already exists")
@@ -328,7 +504,8 @@ export function registerMcpCommand(program) {
       }
       console.log(pc.green(`Wrote SentinelLayer CLI MCP registry template: ${writtenPath}`));
       console.log(pc.gray(`${template.tools.length} CLI leaf commands exposed as bridge tools.`));
-      console.log(pc.gray("Execution requires a bridge-capable MCP host; local stdio run still exposes session tools."));
+      console.log(pc.gray("Execution requires a bridge-capable MCP host with auth, approval, and runtime policy."));
+      console.log(pc.gray("Sensitive token, export, and identity-mutation commands are runtime-blocked."));
     });
 
   registry

package/src/legacy-cli.js

@@ -292,7 +292,13 @@ function printUsage() {
   console.log("  sl auth login && npx create-sentinelayer my-app && cd my-app");
   console.log("  # Then hand docs/spec.md to your coding agent");
   console.log("");
-  console.log("Docs: https://sentinelayer.com/docs");
+  console.log("Examples:");
+  console.log("  sl session read <id> --remote --agent <agent> --tail 20");
+  console.log("  sl session react <id> ack --target-sequence <seq> --agent <agent>");
+  console.log("  sl mcp registry init-session --force && sl mcp server run --path .");
+  console.log("  sl mcp registry init-cli --json");
+  console.log("");
+  console.log("Docs: https://github.com/mrrCarter/create-sentinelayer#readme");
 }
 
 function normalizeInterviewInput(

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/doctor.js

@@ -0,0 +1,247 @@
+/**
+ * `sl mcp doctor` probe logic.
+ *
+ * Diagnoses whether the hosted Sentinelayer MCP server is correctly set up for
+ * remote-agent (ChatGPT / Claude) OAuth authentication. All probes are
+ * UNAUTHENTICATED on purpose: they read public OAuth discovery documents and
+ * confirm the resource server REJECTS an unauthenticated call. No bearer token
+ * is sent and no token is minted, so the command is side-effect-free and safe
+ * to run before `sl auth login`.
+ *
+ * Checks (RFCs map to the WARDEN hosted-MCP-auth build-spec §2/§4):
+ *   1. Protected Resource Metadata  GET /.well-known/oauth-protected-resource  (RFC 9728)
+ *   2. Authorization Server Metadata GET /.well-known/oauth-authorization-server (RFC 8414)
+ *   3. JSON Web Key Set             GET /.well-known/jwks.json
+ *   4. Enforcement                  POST /mcp with no Authorization -> must 401 + WWW-Authenticate
+ */
+
+export const DEFAULT_DOCTOR_TIMEOUT_MS = 10_000;
+
+const PASS = "PASS";
+const WARN = "WARN";
+const FAIL = "FAIL";
+
+function joinUrl(base, suffix) {
+  const normalizedBase = String(base || "").replace(/\/+$/, "");
+  const normalizedSuffix = String(suffix || "").replace(/^\/+/, "");
+  return `${normalizedBase}/${normalizedSuffix}`;
+}
+
+async function probeRequest(fetchImpl, url, { method = "GET", headers, body, timeoutMs } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url, { method, headers, body, 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, headers: response.headers, json };
+  } catch (error) {
+    const aborted = Boolean(error) && error.name === "AbortError";
+    return {
+      reached: false,
+      status: 0,
+      detail: aborted ? `timed out after ${timeoutMs}ms` : String((error && error.message) || error),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function headerValue(headers, name) {
+  if (headers && typeof headers.get === "function") {
+    return String(headers.get(name) || "");
+  }
+  if (headers && typeof headers === "object") {
+    return String(headers[name] || headers[name.toLowerCase()] || "");
+  }
+  return "";
+}
+
+/**
+ * Run the hosted MCP auth discovery + enforcement probes.
+ *
+ * @param {{ apiBaseUrl: string, timeoutMs?: number, fetchImpl?: typeof fetch }} params
+ * @returns {Promise<{ apiBaseUrl: string, ok: boolean, probes: Array<{id:string,label:string,url:string,status:number,verdict:string,detail:string}> }>}
+ */
+export async function runMcpDoctorProbes({
+  apiBaseUrl,
+  timeoutMs = DEFAULT_DOCTOR_TIMEOUT_MS,
+  fetchImpl = fetch,
+} = {}) {
+  const base = String(apiBaseUrl || "").trim().replace(/\/+$/, "");
+  if (!base) {
+    throw new Error("apiBaseUrl is required to run MCP doctor probes.");
+  }
+
+  const probes = [];
+  // Whether PRM advertised an authorization server changes how severe an
+  // AS-metadata 503 is: advertised pointer + 503 is a broken chain (FAIL),
+  // while omitted pointer + 503 is a consistent fail-closed state (WARN).
+  let prmAdvertisesAuthServer = false;
+
+  // 1. Protected Resource Metadata (RFC 9728)
+  {
+    const url = joinUrl(base, "/.well-known/oauth-protected-resource");
+    const result = await probeRequest(fetchImpl, url, { timeoutMs });
+    let verdict = FAIL;
+    let detail;
+    if (!result.reached) {
+      detail = result.detail;
+    } else if (result.status === 200 && result.json && typeof result.json.resource === "string" && result.json.resource) {
+      verdict = PASS;
+      const count = Array.isArray(result.json.authorization_servers)
+        ? result.json.authorization_servers.length
+        : 0;
+      prmAdvertisesAuthServer = count > 0;
+      detail = `resource=${result.json.resource}; authorization_servers=${count}`;
+    } else if (result.status === 200) {
+      verdict = WARN;
+      detail = "200 but missing the required 'resource' field";
+    } else {
+      detail = `expected 200, got HTTP ${result.status}`;
+    }
+    probes.push({
+      id: "protected_resource_metadata",
+      label: "Protected Resource Metadata (RFC 9728)",
+      url,
+      status: result.status,
+      verdict,
+      detail,
+    });
+  }
+
+  // 2. Authorization Server Metadata (RFC 8414)
+  {
+    const url = joinUrl(base, "/.well-known/oauth-authorization-server");
+    const result = await probeRequest(fetchImpl, url, { timeoutMs });
+    let verdict = FAIL;
+    let detail;
+    if (!result.reached) {
+      detail = result.detail;
+    } else if (result.status === 200) {
+      verdict = PASS;
+      detail =
+        result.json && result.json.token_endpoint
+          ? `token_endpoint=${result.json.token_endpoint}`
+          : "advertised";
+    } else if (result.status === 503) {
+      if (prmAdvertisesAuthServer) {
+        // Broken discovery chain: PRM points clients at an authorization server
+        // that then returns 503. Clients WILL follow the pointer and fail.
+        verdict = FAIL;
+        detail =
+          "PRM advertises authorization_servers but AS metadata is 503 — remote clients will follow the advertised pointer to an unconfigured authorization server (broken discovery chain)";
+      } else {
+        // Consistent fail-closed: no AS advertised, AS metadata not configured.
+        verdict = WARN;
+        detail =
+          "503 unconfigured and PRM does not advertise an authorization server (fail-closed, consistent) — set MCP_OAUTH_AUTHORIZATION_ENDPOINT + MCP_OAUTH_TOKEN_ENDPOINT to enable remote auto-discovery";
+      }
+    } else {
+      detail = `expected 200, got HTTP ${result.status}`;
+    }
+    probes.push({
+      id: "authorization_server_metadata",
+      label: "Authorization Server Metadata (RFC 8414)",
+      url,
+      status: result.status,
+      verdict,
+      detail,
+    });
+  }
+
+  // 3. JSON Web Key Set
+  {
+    const url = joinUrl(base, "/.well-known/jwks.json");
+    const result = await probeRequest(fetchImpl, url, { timeoutMs });
+    let verdict = FAIL;
+    let detail;
+    if (!result.reached) {
+      detail = result.detail;
+    } else if (result.status === 200 && result.json && Array.isArray(result.json.keys) && result.json.keys.length > 0) {
+      const keys = result.json.keys;
+      // A PUBLIC JWKS must only ever publish ASYMMETRIC public keys. A symmetric
+      // key (kty "oct" / HS* alg) here IS the shared HMAC signing secret — anyone
+      // who can read it can forge MCP access tokens. Treat that as a hard failure.
+      const symmetricKeys = keys.filter((key) => {
+        const kty = String((key && key.kty) || "").toLowerCase();
+        const alg = String((key && key.alg) || "").toUpperCase();
+        return kty === "oct" || alg.startsWith("HS");
+      });
+      if (symmetricKeys.length > 0) {
+        verdict = FAIL;
+        detail = `CRITICAL: ${symmetricKeys.length} symmetric key(s) (kty=oct / HS*) published in the public JWKS — that is the HMAC signing secret and lets anyone forge MCP access tokens`;
+      } else {
+        verdict = PASS;
+        const algs = [
+          ...new Set(keys.map((key) => String((key && key.alg) || (key && key.kty) || "?"))),
+        ].join(", ");
+        detail = `${keys.length} asymmetric signing key(s) published (${algs})`;
+      }
+    } else if (result.status === 200) {
+      verdict = WARN;
+      detail = "200 but no signing keys published (expected for HS256/non-prod; production must publish an RS256 JWKS)";
+    } else {
+      detail = `expected 200, got HTTP ${result.status}`;
+    }
+    probes.push({
+      id: "jwks",
+      label: "JSON Web Key Set",
+      url,
+      status: result.status,
+      verdict,
+      detail,
+    });
+  }
+
+  // 4. Enforcement: an unauthenticated /mcp call must be rejected with a
+  //    401 + WWW-Authenticate challenge that points back at the PRM document.
+  {
+    const url = joinUrl(base, "/mcp");
+    const result = await probeRequest(fetchImpl, url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: "mcp-doctor", method: "ping" }),
+      timeoutMs,
+    });
+    let verdict = FAIL;
+    let detail;
+    if (!result.reached) {
+      detail = result.detail;
+    } else if (result.status === 401) {
+      const challenge = headerValue(result.headers, "www-authenticate");
+      if (challenge && /resource_metadata=/i.test(challenge)) {
+        verdict = PASS;
+        detail = "401 + WWW-Authenticate challenge advertises the protected-resource metadata";
+      } else if (challenge) {
+        verdict = WARN;
+        detail = "401 but the WWW-Authenticate challenge omits resource_metadata (clients cannot auto-discover the AS)";
+      } else {
+        verdict = WARN;
+        detail = "401 but no WWW-Authenticate header (clients cannot auto-discover the AS)";
+      }
+    } else if (result.status === 200) {
+      detail = "CRITICAL: unauthenticated /mcp returned 200 — the resource server is NOT enforcing authentication";
+    } else {
+      detail = `expected 401, got HTTP ${result.status}`;
+    }
+    probes.push({
+      id: "mcp_enforcement",
+      label: "Unauthenticated /mcp is rejected",
+      url,
+      status: result.status,
+      verdict,
+      detail,
+    });
+  }
+
+  const ok = probes.every((probe) => probe.verdict !== FAIL);
+  return { apiBaseUrl: base, ok, probes };
+}

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/scan/generator.js

@@ -498,7 +498,7 @@ export function buildSecretSetupInstructions(
     `- gh secret set ${normalizedSecret} --repo ${resolvedRepoSlug}`,
     `- Verify secret visibility: gh secret list --repo ${resolvedRepoSlug}`,
     "- Commit and push .github/workflows/omar-gate.yml",
-    "- For manual setup: https://sentinelayer.com/docs/getting-started/install-workflow",
+    "- For manual setup: https://github.com/mrrCarter/create-sentinelayer#manual-fallback-if-auto-injection-is-skipped",
   ];
 }
 

package/src/session/recap.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
@@ -72,6 +73,25 @@ function normalizePositiveInteger(value, fallbackValue) {
   return Math.max(1, Math.floor(normalized));
 }
 
+function buildWorkPlanSourceContext(targetPath = process.cwd(), { sourceReason = "caller_target_path" } = {}) {
+  const workspacePath = path.resolve(String(targetPath || "."));
+  const workspaceLabel = normalizeString(path.basename(workspacePath)) || ".";
+  const workspaceFingerprint = createHash("sha256")
+    .update(workspacePath)
+    .digest("hex")
+    .slice(0, 8);
+  const sourceLabel = `${WORK_PLAN_RELATIVE_PATH} from ${workspaceLabel}#${workspaceFingerprint}`;
+  return {
+    workspacePath,
+    filePath: path.join(workspacePath, WORK_PLAN_RELATIVE_PATH),
+    path: WORK_PLAN_RELATIVE_PATH,
+    workspaceLabel,
+    workspaceFingerprint,
+    sourceLabel,
+    sourceReason: normalizeString(sourceReason),
+  };
+}
+
 function toEpoch(value, fallbackIso = new Date().toISOString()) {
   return Date.parse(normalizeIsoTimestamp(value, fallbackIso)) || 0;
 }
@@ -407,9 +427,13 @@ function emptyTaskLedgerSummary() {
   };
 }
 
-function emptyWorkPlanSummary() {
+function emptyWorkPlanSummary(sourceContext = {}) {
   return {
-    path: WORK_PLAN_RELATIVE_PATH,
+    path: normalizeString(sourceContext.path) || WORK_PLAN_RELATIVE_PATH,
+    workspaceLabel: normalizeString(sourceContext.workspaceLabel),
+    workspaceFingerprint: normalizeString(sourceContext.workspaceFingerprint),
+    sourceLabel: normalizeString(sourceContext.sourceLabel),
+    sourceReason: normalizeString(sourceContext.sourceReason),
     exists: false,
     truncated: false,
     detailSuppressed: false,
@@ -434,8 +458,11 @@ function shortWorkPlanText(value) {
   return `${text.slice(0, 97)}...`;
 }
 
-function summarizeWorkPlanMarkdown(raw = "", { limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT, truncated = false } = {}) {
-  const summary = emptyWorkPlanSummary();
+function summarizeWorkPlanMarkdown(
+  raw = "",
+  { limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT, truncated = false, sourceContext = {} } = {}
+) {
+  const summary = emptyWorkPlanSummary(sourceContext);
   summary.exists = true;
   summary.truncated = Boolean(truncated);
   if (summary.truncated) {
@@ -487,15 +514,19 @@ function summarizeWorkPlanMarkdown(raw = "", { limit = DEFAULT_WORK_PLAN_SUMMARY
   return summary;
 }
 
-async function readWorkPlanSummary({ targetPath = process.cwd(), limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT } = {}) {
-  const filePath = path.join(path.resolve(String(targetPath || ".")), WORK_PLAN_RELATIVE_PATH);
+async function readWorkPlanSummary({
+  targetPath = process.cwd(),
+  limit = DEFAULT_WORK_PLAN_SUMMARY_LIMIT,
+  sourceReason = "caller_target_path",
+} = {}) {
+  const sourceContext = buildWorkPlanSourceContext(targetPath, { sourceReason });
   try {
-    const stats = await fsp.stat(filePath);
+    const stats = await fsp.stat(sourceContext.filePath);
     let source = "";
     let truncated = false;
     if (stats.size > MAX_WORK_PLAN_BYTES) {
       truncated = true;
-      const handle = await fsp.open(filePath, "r");
+      const handle = await fsp.open(sourceContext.filePath, "r");
       try {
         const buffer = Buffer.alloc(MAX_WORK_PLAN_BYTES);
         const position = Math.max(0, stats.size - MAX_WORK_PLAN_BYTES);
@@ -505,14 +536,18 @@ async function readWorkPlanSummary({ targetPath = process.cwd(), limit = DEFAULT
         await handle.close();
       }
     } else {
-      source = await fsp.readFile(filePath, "utf-8");
+      source = await fsp.readFile(sourceContext.filePath, "utf-8");
     }
-    return summarizeWorkPlanMarkdown(source, { limit, truncated });
+    return summarizeWorkPlanMarkdown(source, {
+      limit,
+      truncated,
+      sourceContext,
+    });
   } catch (error) {
     if (error && typeof error === "object" && error.code === "ENOENT") {
-      return emptyWorkPlanSummary();
+      return emptyWorkPlanSummary(sourceContext);
     }
-    return emptyWorkPlanSummary();
+    return emptyWorkPlanSummary(sourceContext);
   }
 }
 
@@ -733,9 +768,24 @@ function buildWorkPlanText(workPlan = emptyWorkPlanSummary()) {
   }
   const open = Number(workPlan.open || 0);
   const completed = Number(workPlan.completed || 0);
-  const pathText = normalizeString(workPlan.path) || WORK_PLAN_RELATIVE_PATH;
+  const sourceText =
+    normalizeString(workPlan.sourceLabel) ||
+    (() => {
+      const pathText = normalizeString(workPlan.path) || WORK_PLAN_RELATIVE_PATH;
+      const workspaceLabel = normalizeString(workPlan.workspaceLabel);
+      const workspaceFingerprint = normalizeString(workPlan.workspaceFingerprint);
+      if (!workspaceLabel) {
+        return pathText;
+      }
+      const workspaceText = workspaceFingerprint
+        ? `${workspaceLabel}#${workspaceFingerprint}`
+        : workspaceLabel;
+      return `${pathText} from ${workspaceText}`;
+    })();
+  const sourceReason = normalizeString(workPlan.sourceReason);
+  const sourceReasonText = sourceReason ? ` (${sourceReason})` : "";
   if (workPlan.detailSuppressed || workPlan.truncated) {
-    return `Plan: ${open} open / ${completed} done in recent ${pathText} window. Current/next items suppressed because the plan file is large.`;
+    return `Plan: ${open} open / ${completed} done in recent ${sourceText} window${sourceReasonText}. Current/next items suppressed because the plan file is large.`;
   }
   const currentSection = normalizeString(workPlan.currentSection);
   const currentText = currentSection ? ` Current: ${currentSection}.` : "";
@@ -752,7 +802,7 @@ function buildWorkPlanText(workPlan = emptyWorkPlanSummary()) {
           .join("; ")}.`
       : "";
   const truncatedText = workPlan.truncated ? " Recent window only." : "";
-  return `Plan: ${open} open / ${completed} done in ${pathText}.${currentText}${nextText}${truncatedText}`;
+  return `Plan: ${open} open / ${completed} done in ${sourceText}${sourceReasonText}.${currentText}${nextText}${truncatedText}`;
 }
 
 function roundCurrency(value) {
@@ -911,6 +961,12 @@ export async function buildSessionRecap(
   } catch {
     sessionMetadata = null;
   }
+  const sessionWorkspaceTargetPath = path.resolve(
+    normalizeString(sessionMetadata?.targetPath) || normalizedTargetPath,
+  );
+  const workPlanSourceReason = normalizeString(sessionMetadata?.targetPath)
+    ? "session_metadata_target_path"
+    : "caller_target_path";
   const sortedEvents = sortEventsByConversationTime(dedupeSessionEvents(allEvents), normalizedNow);
   const usageSummary = normalizeUsageSummary(sortedEvents);
   const events = sortedEvents.slice(-normalizedMaxEvents);
@@ -955,7 +1011,8 @@ export async function buildSessionRecap(
     targetPath: normalizedTargetPath,
   });
   const workPlan = await readWorkPlanSummary({
-    targetPath: normalizedTargetPath,
+    targetPath: sessionWorkspaceTargetPath,
+    sourceReason: workPlanSourceReason,
   });
   const snippets = summarizeRecentActivity(actorEvents, {
     forAgentId: normalizedForAgentId,

package/src/session/store.js

@@ -407,6 +407,7 @@ export function isSessionCacheExpired(metadata, nowIso = new Date().toISOString(
 function buildSessionPayload(metadata, paths, nowIso = new Date().toISOString()) {
   return {
     sessionId: metadata.sessionId,
+    targetPath: metadata.targetPath,
     sessionDir: paths.sessionDir,
     metadataPath: paths.metadataPath,
     streamPath: paths.streamPath,