sentinelayer-cli 0.44.0 → 0.45.0

package/README.md

@@ -206,7 +206,7 @@ required` (or `legacy`).
 The owner actions (`approve`, `deny`, `revoke`, `mode`) run on the owner's own
 session. They are unavailable in an agent context, meaning `SENTINELAYER_AGENT_ID`
 is set or agent admission credentials are stored on the machine; owners use the
-web dashboard from such machines. `session access` commands are not exposed
+web dashboard from such machines. `session access` commands are not callable
 through the MCP CLI bridge.
 
 Sentinelayer includes a deterministic session coordination surface for multi-agent coding loops:
@@ -759,7 +759,7 @@ Use `init-aidenid-adapter` to scaffold a deterministic AIdenID provisioning API
 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, API-authoritative file leases, and attention requests to local MCP clients. File-lease lifecycle operations never write session events; install edit preflights with `sl session guard-install` and remove them with `sl session guard-uninstall` before any CLI rollback. 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) and [docs/file-leases.md](docs/file-leases.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).
+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 MCP bridge now enforces the human-approval requirement on CLI tools; they are unavailable over MCP until approval is supported. Senti session tools are unaffected. The local stdio server does not list the `sl.*` tools, and a call to one returns a JSON-RPC error (code `-32001`, `data.reason` `human_approval_required`) that says to run the `sl` command in a terminal. A file or directory input to a bridged command must stay inside the workspace (no absolute path, no `..` or symlink out of it). The hosted connector target contract is documented in [docs/mcp-hosted-connector.md](docs/mcp-hosted-connector.md).
 
 MCP operator verification:
 
@@ -770,7 +770,7 @@ MCP operator verification:
    `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.
+   MCP host if a CLI bridge or bearer credential is exposed. In this version the MCP server already refuses every `sl.*` call for human approval, so the switch does not change MCP responses; it is defence in depth for the CLI bridge handler and for approved execution in a future version.
 
 Architecture references: local stdio runtime and incident response live in
 [docs/mcp.md](docs/mcp.md); hosted OAuth/session-seat requirements live in
@@ -817,7 +817,7 @@ Architecture decisions:
 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.
+2. Restart the MCP host process. In this version the MCP server already refuses every `sl.*` call for human approval, so the switch does not change MCP responses; it is defence in depth for the CLI bridge handler and for approved execution in a future version.
 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.
@@ -912,6 +912,10 @@ gh secret list --repo <owner/repo>
 - `SENTINELAYER_DISABLE_KEYRING=1` (force file-based credential storage)
 - `AIDENID_API_KEY`, `AIDENID_ORG_ID`, `AIDENID_PROJECT_ID` (used by `sl ai provision-email --execute`)
 
+When the CLI sends your SentinelLayer token over HTTP, it sends it only to the API named by `SENTINELAYER_API_URL` (else by `apiUrl` in `~/.sentinelayer/config.yml`, else the default API), or to the pocket gateway named by `SENTI_POCKET_URL`. `POCKET_GATEWAY_URL` is no longer read. The CLI decides this once, when it starts. Custom API origins must be configured: an `--api-url` or `--gateway-url` that names another origin is refused for any request that would carry the token. A project `.sentinelayer.yml` chooses neither the API nor the token: its `apiUrl` and `sentinelayerToken` are not used, nor are its provider keys (`openaiApiKey`, `anthropicApiKey`, `googleApiKey`), which come from the environment or the global config. Watchdog alert channels (`alerts.channels`) also come from the global config only; a channel's `${NAME}` placeholders are filled only from `SLACK_WEBHOOK_URL`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` or `SENTINELAYER_ALERT_*` (any other name, or an unset one, refuses the channel), and Slack alerts go only to `https://hooks.slack.com/`. When a project config sets any of these, the CLI prints one notice saying what to set instead. Requests that carry the token do not follow redirects.
+
+The token leaves the CLI in other ways only through operator commands, none of which is available through the MCP bridge: `sl scan setup-secrets` writes it to a GitHub Actions secret with the `gh` CLI (or to the file named by `SENTINELAYER_SECRET_SINK_FILE`, used in tests), and `sl mcp token mint --json` prints a short-lived hosted MCP bearer minted from it. The project token that `sl init` receives for a new scaffold (not your login token) is written to the project's `.env`, its `.sentinelayer/config.json` lockfile and, only when you pass `--inject-secret` (or set `injectSecret` in the interview), a GitHub Actions secret on this directory's own git remote, after `gh` confirms you can write to it. `OPENAI_API_KEY` from your environment is set there only with `--inject-openai-key`. Neither is available through the MCP bridge. Other services' keys (model providers, AIdenID, a memory or embedding service) are sent to their own endpoints.
+
 ## Layered config (PR 0.2)
 
 The CLI supports layered config resolution:

package/package.json

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

package/src/agents/jules/tools/aidenid-email.js

@@ -11,8 +11,8 @@ import {
   resolveAidenIdCredentials,
   normalizeAidenIdApiUrl,
 } from "../../../ai/aidenid.js";
-import { readStoredSession } from "../../../auth/session-store.js";
 import { fetchAidenIdCredentials } from "../../../auth/service.js";
+import { isAuthenticated } from "../../../auth/credential-destinations.js";
 
 /**
  * AIdenID email tool definition for agent dispatch.
@@ -57,16 +57,14 @@ export const AIDENID_EMAIL_TOOL = {
 export async function executeAidenIdEmailTool(input, ctx = {}) {
   const operation = String(input.operation || "").trim();
 
-  let session = null;
-  try {
-    session = await readStoredSession();
-  } catch {
-    // no session
-  }
+  const { resolveActiveAuthSession } = await import("../../../auth/service.js");
+  const session = await resolveActiveAuthSession({ cwd: process.cwd(), env: process.env, autoRotate: false }).catch(
+    () => null,
+  );
 
   const makeFetcher = () => {
-    if (!session || !session.token) return null;
-    return () => fetchAidenIdCredentials({ apiUrl: session.apiUrl, token: session.token });
+    if (!isAuthenticated(session)) return null;
+    return () => fetchAidenIdCredentials({ apiUrl: session.apiUrl, auth: session });
   };
 
   const credentials = await resolveAidenIdCredentials({

package/src/agents/jules/tools/frontend-analyze.js

@@ -4,6 +4,7 @@ import { execFileSync } from "node:child_process";
 import { glob as globTool } from "./glob.js";
 import { grep as grepTool } from "./grep.js";
 import { fileRead } from "./file-read.js";
+import { buildScrubbedEnv } from "../../shared-tools/shell.js";
 
 /**
  * FrontendAnalyze — 24 deterministic operations for the Jules Tanaka persona.
@@ -346,11 +347,22 @@ function checkErrorBoundaries(rootPath) {
   };
 }
 
+// npm runs in the repository with credentials removed from its environment, so the repository's
+// .npmrc cannot place them in a request.
+function npmAuditInvocation(rootPath, env = process.env) {
+  return {
+    file: "npm",
+    args: ["audit", "--json", "--production"],
+    options: { cwd: rootPath, encoding: "utf-8", timeout: 30000, stdio: ["pipe", "pipe", "pipe"], env: buildScrubbedEnv(env) },
+  };
+}
+
+export const __frontendAnalyzeForTests = Object.freeze({ npmAuditInvocation });
+
 function auditNpmDeps(rootPath) {
   try {
-    const output = execFileSync("npm", ["audit", "--json", "--production"], {
-      cwd: rootPath, encoding: "utf-8", timeout: 30000, stdio: ["pipe", "pipe", "pipe"],
-    });
+    const invocation = npmAuditInvocation(rootPath);
+    const output = execFileSync(invocation.file, invocation.args, invocation.options);
     const audit = JSON.parse(output);
     return {
       vulnerabilities: audit.metadata?.vulnerabilities || {},

package/src/agents/jules/tools/runtime-audit.js

@@ -3,7 +3,9 @@ import path from "node:path";
 import fs from "node:fs";
 import os from "node:os";
 import { randomUUID } from "node:crypto";
+import { credentialedRequest, isAuthenticated } from "../../../auth/credential-destinations.js";
 import { assertPermittedAuditTarget } from "./url-policy.js";
+import { buildScrubbedEnv } from "../../shared-tools/shell.js";
 
 /**
  * Jules Tanaka — Runtime Audit Tool
@@ -46,6 +48,37 @@ const RUNTIME_DISPATCH = {
   check_dom_stats: checkDomStats,
 };
 
+/**
+ * How Lighthouse runs. No shell: the target URL can come from the repository (package.json,
+ * vercel.json, .env files), and a shell would expand variables and operators inside it. Credentials
+ * are removed from npx's environment, so a repository .npmrc cannot place them in a request.
+ * On Windows, where npx is a .cmd file, npm's npx script runs under this Node.js instead.
+ */
+function lighthouseInvocation(
+  targetUrl,
+  outputPath,
+  { platform = process.platform, execPath = process.execPath, exists = fs.existsSync, env = process.env } = {},
+) {
+  const args = [
+    "--yes", "lighthouse@12", targetUrl,
+    "--output", "json", "--output-path", outputPath,
+    "--chrome-flags=--headless --no-sandbox --disable-gpu", "--quiet",
+  ];
+  const options = {
+    encoding: "utf-8",
+    timeout: LIGHTHOUSE_TIMEOUT_MS,
+    stdio: ["pipe", "pipe", "pipe"],
+    env: buildScrubbedEnv(env),
+  };
+  if (platform !== "win32") {
+    return { file: "npx", args, options };
+  }
+  const npxCli = path.join(path.dirname(execPath), "node_modules", "npm", "bin", "npx-cli.js");
+  return exists(npxCli) ? { file: execPath, args: [npxCli, ...args], options } : null;
+}
+
+export const __runtimeAuditForTests = Object.freeze({ lighthouseInvocation, detectDeployedUrl });
+
 /**
  * Run Lighthouse via npx (no install required).
  * Returns performance, accessibility, best-practices, SEO scores + key metrics.
@@ -74,16 +107,11 @@ async function lighthouseScan(input) {
     const outputDir = path.dirname(outputPath);
     if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
 
-    execFileSync("npx", [
-      "--yes", "lighthouse@12", targetUrl,
-      "--output", "json", "--output-path", outputPath,
-      "--chrome-flags=--headless --no-sandbox --disable-gpu", "--quiet",
-    ], {
-      encoding: "utf-8",
-      timeout: LIGHTHOUSE_TIMEOUT_MS,
-      stdio: ["pipe", "pipe", "pipe"],
-      shell: true, // Windows: npx is npx.cmd, needs shell resolution
-    });
+    const invocation = lighthouseInvocation(targetUrl, outputPath);
+    if (!invocation) {
+      return { available: false, reason: "npx is not available next to this Node.js" };
+    }
+    execFileSync(invocation.file, invocation.args, invocation.options);
 
     if (!fs.existsSync(outputPath)) {
       return { available: false, reason: "Lighthouse produced no output" };
@@ -437,7 +465,7 @@ async function callScannerApi(url) {
     });
   } catch { /* session read failed */ }
 
-  if (!session || !session.token) {
+  if (!isAuthenticated(session)) {
     return { available: false, reason: "Not authenticated — run sl auth login" };
   }
 
@@ -445,14 +473,16 @@ async function callScannerApi(url) {
   const scanEndpoint = apiUrl + "/api/v1/scan/url";
 
   // Submit scan
-  const submitResponse = await fetchWithTimeout(scanEndpoint, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "Authorization": "Bearer " + session.token,
+  const submitResponse = await credentialedRequest(
+    session.credential,
+    scanEndpoint,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ url, scan_type: "lighthouse" }),
     },
-    body: JSON.stringify({ url, scan_type: "lighthouse" }),
-  }, 15000);
+    { fetchImpl: (target, init) => fetchWithTimeout(target, init, 15000) },
+  );
 
   if (!submitResponse.ok) {
     return { available: false, reason: "Scanner API returned " + submitResponse.status };
@@ -469,9 +499,9 @@ async function callScannerApi(url) {
   for (let attempt = 0; attempt < 30; attempt++) {
     await new Promise(r => setTimeout(r, 3000));
     try {
-      const pollResponse = await fetchWithTimeout(pollUrl, {
-        headers: { "Authorization": "Bearer " + session.token },
-      }, 10000);
+      const pollResponse = await credentialedRequest(session.credential, pollUrl, {}, {
+        fetchImpl: (target, init) => fetchWithTimeout(target, init, 10000),
+      });
       if (!pollResponse.ok) continue;
       const pollData = await pollResponse.json();
       if (pollData.status === "completed" || pollData.status === "complete") {

package/src/ai/aidenid.js

@@ -1,5 +1,6 @@
 import process from "node:process";
 import { authLoginHint } from "../ui/command-hints.js";
+import { isAuthenticated } from "../auth/credential-destinations.js";
 
 export const DEFAULT_AIDENID_API_URL = "https://api.aidenid.com";
 
@@ -179,14 +180,14 @@ async function resolveSessionCredentialContext({
       env,
       autoRotate: false,
     });
-    if (activeSession && activeSession.token) {
+    if (isAuthenticated(activeSession)) {
       resolvedSession = activeSession;
     }
-    if (resolvedSession && resolvedSession.token && (!resolvedFetcher || activeSession?.token)) {
+    if (isAuthenticated(resolvedSession) && (!resolvedFetcher || isAuthenticated(activeSession))) {
       resolvedFetcher = () =>
         fetchAidenIdCredentials({
           apiUrl: resolvedSession.apiUrl || "https://api.sentinelayer.com",
-          token: resolvedSession.token,
+          auth: resolvedSession,
         });
     }
   } catch {
@@ -230,7 +231,7 @@ export async function resolveAidenIdCredentials(
   const activeSession = sessionContext.session;
   const activeFetchCredentials = sessionContext.fetchCredentials;
   const sessionAidenId = activeSession && activeSession.aidenid ? activeSession.aidenid : null;
-  const hasSessionToken = Boolean(String(activeSession && activeSession.token ? activeSession.token : "").trim());
+  const hasSessionToken = isAuthenticated(activeSession);
 
   let resolvedApiKey = String(apiKey || env.AIDENID_API_KEY || "").trim();
   let resolvedOrgId = String(orgId || env.AIDENID_ORG_ID || (sessionAidenId && sessionAidenId.orgId) || "").trim();

package/src/ai/proxy.js

@@ -8,6 +8,7 @@
  * Response: { content, usage: { model, provider, tokens_in, tokens_out, cost_usd, latency_ms } }
  */
 
+import { CredentialDestinationRefused, credentialedRequest, credentialFor, isAuthenticated } from "../auth/credential-destinations.js";
 import { resolveActiveAuthSession } from "../auth/service.js";
 import { authLoginHint } from "../ui/command-hints.js";
 
@@ -318,7 +319,7 @@ function buildProxyError(status, parsed) {
  * @param {number} [options.maxTokens] - Max output tokens (default: 4096)
  * @param {number} [options.temperature] - Temperature (default: 0.1)
  * @param {string} [options.apiUrl] - Override API URL
- * @param {string} [options.token] - Override Bearer token
+ * @param {string} [options.token] - The user's token, if the caller holds it: bound to the configured API
  * @param {string} [options.sessionId] - Optional Senti session id for server-side usage metering
  * @param {string} [options.agentId] - Optional session agent id for server-side usage metering
  * @param {string} [options.action] - Optional metered action, defaults server-side when omitted
@@ -346,23 +347,24 @@ export async function invokeViaProxy({
   metadata = null,
   fetchImpl = fetch,
 } = {}) {
-  // Resolve credentials from session if not provided
+  // Resolve credentials from session if not provided. A passed token is bound to the configured
+  // API (src/auth/credential-destinations.js), so an apiUrl on any other origin is refused.
   let resolvedApiUrl = String(apiUrl || "").trim();
-  let resolvedToken = String(token || "").trim();
+  let credential = String(token || "").trim() ? await credentialFor({ token }) : null;
 
-  if (!resolvedApiUrl || !resolvedToken) {
+  if (!resolvedApiUrl || !credential) {
     const session = await resolveActiveAuthSession({
       cwd: process.cwd(),
       env: process.env,
       autoRotate: false,
     });
-    if (!session || !session.token) {
+    if (!isAuthenticated(session)) {
       throw new Error(
         `SentinelLayer LLM proxy requires authentication. Run '${authLoginHint()}' first.`
       );
     }
     if (!resolvedApiUrl) resolvedApiUrl = String(session.apiUrl || "https://api.sentinelayer.com").trim();
-    if (!resolvedToken) resolvedToken = String(session.token).trim();
+    if (!credential) credential = await credentialFor(session);
   }
 
   const url = `${resolvedApiUrl.replace(/\/+$/, "")}/api/v1/proxy/llm`;
@@ -393,7 +395,6 @@ export async function invokeViaProxy({
 
   const headers = {
     "Content-Type": "application/json",
-    Authorization: `Bearer ${resolvedToken}`,
     Accept: "application/json",
   };
   if (normalizedUsageIdempotencyKey) {
@@ -410,12 +411,12 @@ export async function invokeViaProxy({
       const controller = new AbortController();
       const timeoutHandle = setTimeout(() => controller.abort(), PROXY_TIMEOUT_MS);
       try {
-        response = await fetchImpl(url, {
-          method: "POST",
-          headers,
-          body,
-          signal: controller.signal,
-        });
+        response = await credentialedRequest(
+          credential,
+          url,
+          { method: "POST", headers, body, signal: controller.signal },
+          { fetchImpl },
+        );
       } finally {
         clearTimeout(timeoutHandle);
       }
@@ -436,7 +437,7 @@ export async function invokeViaProxy({
 
       throw buildProxyError(response.status, parsedError);
     } catch (err) {
-      if (err instanceof SentinelayerProxyError) {
+      if (err instanceof SentinelayerProxyError || err instanceof CredentialDestinationRefused) {
         throw err;
       }
       lastError = err;

package/src/audit/orchestrator.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import fsp from "node:fs/promises";
 import path from "node:path";
 
+import { userCredential } from "../auth/credential-destinations.js";
 import { resolveOutputRoot } from "../config/service.js";
 import { createAgentEvent } from "../events/schema.js";
 import { resolveCodebaseIngest } from "../ingest/engine.js";
@@ -566,11 +567,12 @@ export async function runAuditOrchestrator({
   }
   const memoryProvider = resolveMemoryProvider(process.env);
   const memoryApiEndpoint = normalizeString(process.env.SENTINELAYER_MEMORY_API_ENDPOINT);
-  const memoryApiKey = normalizeString(
-    process.env.SENTINELAYER_MEMORY_API_KEY ||
-      process.env.SENTINELAYER_TOKEN ||
-      process.env.SENTINELAYER_API_TOKEN
-  );
+  // The memory service's own key, if configured; otherwise the user's token as a credential, which
+  // reaches the memory endpoint only if it is on the configured API's origin.
+  const memoryApiKey = normalizeString(process.env.SENTINELAYER_MEMORY_API_KEY);
+  const memoryCredential = memoryApiKey
+    ? null
+    : await userCredential(process.env.SENTINELAYER_TOKEN || process.env.SENTINELAYER_API_TOKEN, { source: "env" });
   const sharedMemoryCorpus = await buildSharedMemoryCorpus({
     outputRoot,
     targetPath: normalizedTargetPath,
@@ -628,6 +630,7 @@ export async function runAuditOrchestrator({
       provider: memoryProvider,
       apiEndpoint: memoryApiEndpoint,
       apiKey: memoryApiKey,
+      credential: memoryCredential,
     });
     sharedMemoryQueries.push({
       agentId: agent.id,

package/src/auth/admission-scope.js

@@ -8,11 +8,13 @@
 // from inside the scope, so no human-authenticated subrequest can hide behind a
 // scoped main request.
 //
-// It imports nothing from this codebase, so the auth service can depend on it
-// without an import cycle.
+// It imports only the credential module, so the auth service can depend on it without an
+// import cycle.
 
 import { AsyncLocalStorage } from "node:async_hooks";
 
+import { admissionCredential } from "./credential-destinations.js";
+
 export const admittedAgentScope = new AsyncLocalStorage();
 
 /**
@@ -26,7 +28,7 @@ export function scopedAdmissionAuth() {
   if (!(credential.expiresAt * 1000 > Date.now())) return null;
   return {
     apiUrl: credential.apiUrl,
-    token: credential.token,
+    credential: admissionCredential(credential), // bound to the API that issued it; its token stays inside
     source: "session_admission",
     user: null,
     admissionId: credential.admissionId,

package/src/auth/credential-destinations.js

@@ -0,0 +1,221 @@
+// credential-destinations.js — the user's credentials, and the one way to send them.
+//
+// A credential is an opaque object, { origin, source }, and only this module makes one. The
+// token it carries is held here, out of reach: it is not a property of the credential or of any
+// auth result, so code elsewhere cannot read it, copy it into a header, a URL, a body or a
+// cookie, or hand it to a child process. credentialedRequest is the one thing that uses it.
+//
+// Its origin is fixed when it is minted, from ONE trust context (resolveTrustContext) built from
+// the environment and the user's global config:
+//
+//   - the configured API: SENTINELAYER_API_URL, else `apiUrl` in ~/.sentinelayer/config.yml,
+//     else the default API
+//   - the pocket gateway: SENTI_POCKET_URL, when set (POCKET_GATEWAY_URL is not read)
+//
+// The CLI entry resolves that context once, at start, and freezes it (freezeProcessTrustContext),
+// so nothing that changes process.env later can move it. Login, auth resolution and the request
+// check all use it; tests inject their own env and homeDir. Nothing a command is given (an
+// option, an argument, an MCP tool input, a workspace's .sentinelayer.yml) can change where a
+// credential goes. An agent's admission credential is bound to the API that issued it
+// (src/auth/admission-scope.js) and is never re-bound to the pocket gateway.
+//
+// credentialedRequest(credential, url, init, { fetchImpl }) is the one way to send a credential.
+// It refuses a URL on any other origin, sets the Authorization header itself, and never follows
+// a redirect. An injected transport (fetchImpl) is what it calls once those checks pass. A bare
+// token from an injected auth resolver (tests) is bound to the configured API by credentialFor.
+// tests/unit.credential-census.test.mjs fails on any other place in src/ that builds an
+// Authorization header, reads a raw token, or writes a trust-source variable into process.env.
+
+import { createHmac } from "node:crypto";
+import os from "node:os";
+import process from "node:process";
+
+import { readConfigFile } from "../config/io.js";
+import { getGlobalConfigPath } from "../config/paths.js";
+
+export const DEFAULT_API_URL = "https://api.sentinelayer.com";
+
+const tokens = new WeakMap(); // credential -> token; the only place a token is kept
+const contexts = new WeakSet(); // trust contexts this module built
+const USER_SOURCES = new Set(["user", "env", "config", "session"]); // the person's own token
+let processContext = null; // frozen at the CLI entry
+
+export class CredentialDestinationRefused extends Error {
+  constructor(origin, trusted = []) {
+    super(
+      `Refusing to send your SentinelLayer credential to ${origin}: it is only sent to ` +
+        `${trusted.filter(Boolean).join(", ") || "the configured API"}. Custom API origins must be configured: set ` +
+        `SENTINELAYER_API_URL or SENTI_POCKET_URL (or \`apiUrl\` in ~/.sentinelayer/config.yml).`,
+    );
+    this.name = "CredentialDestinationRefused";
+    this.code = "CREDENTIAL_DESTINATION_REFUSED";
+    this.origin = origin;
+  }
+}
+
+function originOf(value) {
+  try {
+    const parsed = new URL(String(value || "").trim());
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.origin : "";
+  } catch {
+    return "";
+  }
+}
+
+function mint(token, origin, source) {
+  const value = String(token ?? "").trim();
+  if (!value || !origin) return null;
+  const credential = Object.freeze({ origin, source });
+  tokens.set(credential, value);
+  return credential;
+}
+
+/** Whether a value is a credential this module minted. */
+export function isCredential(value) {
+  return tokens.has(value);
+}
+
+/** Whether an auth result carries a credential (or, from an injected resolver, a bare token). */
+export function isAuthenticated(auth) {
+  return isCredential(auth?.credential) || Boolean(String(auth?.token ?? "").trim());
+}
+
+async function buildTrustContext({ env, homeDir }) {
+  let apiUrl = String(env.SENTINELAYER_API_URL || "").trim();
+  if (!apiUrl) {
+    const globalConfig = await readConfigFile(getGlobalConfigPath({ homeDir })).catch(() => ({}));
+    apiUrl = String(globalConfig?.apiUrl || "").trim() || DEFAULT_API_URL;
+  }
+  const context = Object.freeze({
+    apiOrigin: originOf(apiUrl),
+    gatewayOrigin: originOf(env.SENTI_POCKET_URL),
+  });
+  contexts.add(context);
+  return context;
+}
+
+/**
+ * Resolve the process trust context once, from the real environment and global config, and
+ * freeze it: from then on, process.env changes do not move it. Called first by the CLI entry.
+ */
+export async function freezeProcessTrustContext() {
+  if (!processContext) {
+    const env = { SENTINELAYER_API_URL: process.env.SENTINELAYER_API_URL, SENTI_POCKET_URL: process.env.SENTI_POCKET_URL };
+    processContext = await buildTrustContext({ env, homeDir: os.homedir() });
+  }
+  return processContext;
+}
+
+/**
+ * THE trust context: where the user's credentials may be sent. Built from the environment and
+ * the global config only. For the process environment, once frozen, it is the frozen context.
+ */
+export async function resolveTrustContext({ env = process.env, homeDir } = {}) {
+  if (processContext && env === process.env && homeDir === undefined) return processContext;
+  return buildTrustContext({ env, homeDir });
+}
+
+async function trustOf({ context, env, homeDir }) {
+  if (context === undefined) return resolveTrustContext({ env, homeDir });
+  if (!contexts.has(context)) throw new TypeError("A trust context from resolveTrustContext is required.");
+  return context;
+}
+
+/** A credential for one of the user's tokens, bound to the configured API. */
+export async function userCredential(token, { context, env, homeDir, source = "user" } = {}) {
+  return mint(token, (await trustOf({ context, env, homeDir })).apiOrigin, source);
+}
+
+/**
+ * The person's own token bound to the configured pocket gateway; null when none is configured.
+ * An agent's admission credential, or any token minted for one purpose, is never re-bound.
+ */
+export async function gatewayCredential(credential, { context, env, homeDir } = {}) {
+  if (!isCredential(credential)) throw new TypeError("gatewayCredential needs a credential.");
+  const trust = await trustOf({ context, env, homeDir });
+  if (!USER_SOURCES.has(credential.source)) {
+    throw new CredentialDestinationRefused(trust.gatewayOrigin || "the pocket gateway", [credential.origin]);
+  }
+  return mint(tokens.get(credential), trust.gatewayOrigin, "pocket_gateway");
+}
+
+/** An agent's admission credential, bound to the API that issued it. */
+export function admissionCredential({ token, apiUrl } = {}) {
+  return mint(token, originOf(apiUrl), "session_admission");
+}
+
+/**
+ * The credential for an auth result: its own, or, for a bare token from an injected resolver,
+ * the token bound to the configured API. Never bound to an origin the caller supplies.
+ */
+export async function credentialFor(auth, { context, env, homeDir } = {}) {
+  if (isCredential(auth?.credential)) return auth.credential;
+  if (!String(auth?.token ?? "").trim()) return null;
+  return userCredential(auth.token, { context, env, homeDir, source: auth.source || "user" });
+}
+
+/** Refuse an API URL outside the trust context, before any credential is minted for it. */
+export async function assertTrustedApiUrl(url, { context, env, homeDir } = {}) {
+  const trust = await trustOf({ context, env, homeDir });
+  const origin = originOf(url) || String(url);
+  if (origin !== trust.apiOrigin) throw new CredentialDestinationRefused(origin, [trust.apiOrigin]);
+}
+
+/** Refuse sending `credential` anywhere but its own origin. `target` is the exact URL string sent. */
+export function assertCredentialDestination(credential, target) {
+  if (!isCredential(credential)) throw new TypeError("A credential from src/auth/credential-destinations.js is required.");
+  const origin = originOf(target);
+  if (origin !== credential.origin) throw new CredentialDestinationRefused(origin || String(target), [credential.origin]);
+}
+
+/**
+ * An injectable request function (requestJson-shaped: (url, options)), checked first: a
+ * credential in its options goes nowhere but its own origin, whichever implementation runs.
+ */
+export function checkedTransport(requestImpl) {
+  return async (url, options, ...rest) => {
+    const target = String(url); // checked and passed on as the same string
+    if (options?.credential) assertCredentialDestination(options.credential, target);
+    return requestImpl(target, options, ...rest);
+  };
+}
+
+function headersWithout(headers, name) {
+  const entries = headers instanceof Headers ? [...headers.entries()] : Object.entries(headers || {});
+  return Object.fromEntries(entries.filter(([key]) => String(key).toLowerCase() !== name));
+}
+
+/**
+ * Send a request carrying `credential`: only to the credential's own origin, with the
+ * Authorization header set here, and without following redirects. `fetchImpl` is the transport
+ * it calls once those checks pass. The URL is turned into a string once, and that string is both
+ * checked and sent.
+ */
+export async function credentialedRequest(credential, url, init = {}, { fetchImpl = globalThis.fetch } = {}) {
+  const target = String(url);
+  assertCredentialDestination(credential, target);
+  return fetchImpl(target, {
+    ...init,
+    headers: { ...headersWithout(init.headers, "authorization"), Authorization: `Bearer ${tokens.get(credential)}` },
+    redirect: "error",
+  });
+}
+
+/** An HMAC-SHA256 of `message` keyed by the credential's token (a request proof; never the token). */
+export function credentialHmac(credential, message) {
+  if (!isCredential(credential)) throw new TypeError("A credential from src/auth/credential-destinations.js is required.");
+  return createHmac("sha256", tokens.get(credential)).update(String(message), "utf8").digest("hex");
+}
+
+/**
+ * The token itself, for the one reviewed export: the operator command `sl scan setup-secrets`,
+ * which writes it to a GitHub Actions secret through the gh CLI. Nothing else may call this
+ * (tests/unit.credential-census.test.mjs).
+ */
+export function exportCredentialToken(credential, { purpose } = {}) {
+  if (purpose !== "github-actions-secret") throw new TypeError("exportCredentialToken: unknown purpose.");
+  if (!isCredential(credential) || !USER_SOURCES.has(credential.source)) {
+    throw new TypeError("exportCredentialToken needs the person's own credential.");
+  }
+  return tokens.get(credential);
+}