sentinelayer-cli 0.44.0 → 0.46.0

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);
+}

package/src/auth/gate.js

@@ -7,6 +7,7 @@ import pc from "picocolors";
 import { resolveActiveAuthSession } from "./service.js";
 import { resolveAgentAdmissionTarget } from "../session/admission-auth.js";
 import { authLoginHint } from "../ui/command-hints.js";
+import { isAuthenticated } from "./credential-destinations.js";
 
 /**
  * Auth gate — ensures user is logged in before running any command.
@@ -316,12 +317,11 @@ function isSessionUnexpired(tokenExpiresAt) {
 // without fixing anything.
 //
 // So the gate checks:
-//   - session.token is present and non-empty
+//   - the session carries a credential
 //   - for source === "session", expiry is in the future
 //   - for source === "env" or "config", the downstream API call is the gate
 function isAuthenticatedSessionValid(session) {
-  const token = String(session?.token || "").trim();
-  if (!token) {
+  if (!isAuthenticated(session)) {
     return false;
   }
   if (String(session?.source || "").trim() === "session") {
@@ -369,7 +369,7 @@ export async function checkAuthGate(args) {
     }
     if (session) {
       // Session resolved but failed validation (empty token or expired).
-      const tokenPresent = Boolean(String(session?.token || "").trim());
+      const tokenPresent = isAuthenticated(session);
       if (!tokenPresent) {
         resolveError = "session_token_missing";
       } else if (String(session?.source || "").trim() === "session" && !isSessionUnexpired(session?.tokenExpiresAt)) {

package/src/auth/http.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { installTestEgressGuard } from "../net/test-egress-guard.js";
+import { CredentialDestinationRefused, credentialedRequest, isCredential } from "./credential-destinations.js";
 
 // No-op outside tests; see src/net/test-egress-guard.js.
 installTestEgressGuard();
@@ -20,7 +21,10 @@ export const CIRCUIT_BREAKER_THRESHOLD = 5;
 export const CIRCUIT_BREAKER_COOLDOWN_MS = 30_000;
 
 const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
-const CIRCUIT_TRACK_STATUS_CODES = new Set([401, 403, 408, 425, 429, 500, 502, 503, 504]);
+// 401 and 403 are not tracked: they refuse one credential (for example an expired or
+// revoked agent admission) and say nothing about the origin's health, so they must not
+// open the per-origin breaker for every other credential on this machine.
+const CIRCUIT_TRACK_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
 const circuitStateByScope = new Map();
 
 // File-backed cache. Lets cooldown + failure counts survive across CLI
@@ -422,7 +426,8 @@ export function __resetRequestCircuitForTests(scope) {
  *   maxRetries?: number,
  *   retryDelayMs?: number
  *   allowEmptyBody?: boolean
- * }} [options]
+ *   credential?: object
+ * }} [options] `credential` (src/auth/credential-destinations.js) is sent with credentialedRequest.
  * @returns {Promise<any>}
  */
 export async function requestJson(
@@ -430,6 +435,7 @@ export async function requestJson(
   {
     method = "GET",
     headers = {},
+    credential = null,
     body,
     idempotencyKey = null,
     allowNonIdempotent = false,
@@ -439,6 +445,13 @@ export async function requestJson(
     allowEmptyBody = false,
   } = {}
 ) {
+  if (credential && !isCredential(credential)) {
+    throw new TypeError("requestJson: credential must come from src/auth/credential-destinations.js.");
+  }
+  // Without a credential, nothing here attaches one: a caller-built Authorization header is refused.
+  if (Object.keys(headers || {}).some((name) => /^(?:proxy-)?authorization$/i.test(name))) {
+    throw new TypeError("requestJson: send a credential with { credential }, not an Authorization header.");
+  }
   const normalizedMethod = String(method || "GET").trim().toUpperCase();
   const explicitIdempotencyKey = String(idempotencyKey || "").trim() || null;
   const existingIdempotencyKey = explicitIdempotencyKey || resolveIdempotencyKey(headers);
@@ -492,13 +505,14 @@ export async function requestJson(
     }, normalizedTimeoutMs);
 
     try {
-      const response = await fetch(String(url), {
+      const init = {
         method: normalizedMethod,
         headers: outgoingHeaders,
         body: body === undefined ? undefined : JSON.stringify(body),
         redirect: "error",
         signal: controller.signal,
-      });
+      };
+      const response = credential ? await credentialedRequest(credential, url, init) : await fetch(String(url), init);
 
       const rawBody = await response.text();
       const trimmedBody = rawBody.trim();
@@ -575,7 +589,8 @@ export async function requestJson(
       await sleep(delayMs);
       continue;
     } catch (error) {
-      if (error instanceof SentinelayerApiError) {
+      // A refused destination is final: nothing was sent, so no retry and no breaker count.
+      if (error instanceof SentinelayerApiError || error instanceof CredentialDestinationRefused) {
         throw error;
       }
 
@@ -647,6 +662,7 @@ export async function requestJsonMutation(
   {
     method = "POST",
     headers = {},
+    credential = null,
     body,
     idempotencyKey = null,
     operationName,
@@ -675,6 +691,7 @@ export async function requestJsonMutation(
   return requestJson(url, {
     method: normalizedMethod,
     headers,
+    credential,
     body,
     idempotencyKey: resolvedIdempotencyKey,
     timeoutMs,

package/src/auth/service.js

@@ -6,6 +6,14 @@ import open from "open";
 
 import { loadConfig } from "../config/service.js";
 import { scopedAdmissionAuth } from "./admission-scope.js";
+import {
+  DEFAULT_API_URL,
+  assertTrustedApiUrl,
+  credentialFor,
+  isAuthenticated,
+  resolveTrustContext,
+  userCredential,
+} from "./credential-destinations.js";
 import { SentinelayerApiError, requestJson, requestJsonMutation } from "./http.js";
 import {
   clearStoredSession,
@@ -15,7 +23,6 @@ import {
 } from "./session-store.js";
 import { authLoginHint } from "../ui/command-hints.js";
 
-const DEFAULT_API_URL = "https://api.sentinelayer.com";
 /** Default maximum wall-clock wait for browser-based CLI auth approval (ms). */
 export const DEFAULT_AUTH_TIMEOUT_MS = 10 * 60 * 1000;
 /** Default lifetime for issued API tokens used by CLI sessions (days). */
@@ -57,12 +64,6 @@ function normalizePositiveNumber(rawValue, field, fallbackValue) {
   return normalized;
 }
 
-function toAuthHeader(token) {
-  return {
-    Authorization: `Bearer ${String(token || "").trim()}`,
-  };
-}
-
 function normalizeUser(user = {}) {
   return {
     id: String(user.id || "").trim(),
@@ -171,7 +172,6 @@ function isNearExpiry(tokenExpiresAt, thresholdDays) {
  * @returns {Promise<string>}
  */
 export async function resolveApiUrl({
-  cwd = process.cwd(),
   env = process.env,
   explicitApiUrl = "",
   homeDir,
@@ -180,19 +180,9 @@ export async function resolveApiUrl({
   if (overrideUrl) {
     return normalizeApiUrl(overrideUrl);
   }
-
-  const envUrl = String(env.SENTINELAYER_API_URL || "").trim();
-  if (envUrl) {
-    return normalizeApiUrl(envUrl);
-  }
-
-  const config = await loadConfig({ cwd, env, homeDir });
-  const configuredApiUrl = String(config.resolved.apiUrl || "").trim();
-  if (configuredApiUrl) {
-    return normalizeApiUrl(configuredApiUrl);
-  }
-
-  return normalizeApiUrl(DEFAULT_API_URL);
+  // The trust context's API (SENTINELAYER_API_URL, else the global config, else the default). A
+  // workspace .sentinelayer.yml does not choose the API.
+  return normalizeApiUrl((await resolveTrustContext({ env, homeDir })).apiOrigin);
 }
 
 async function startCliAuthSession({ apiUrl, challenge, ide, cliVersion, flowRequestId }) {
@@ -379,20 +369,21 @@ async function pollCliAuthSession({
   });
 }
 
-async function fetchCurrentUser({ apiUrl, token, flowRequestId }) {
+async function fetchCurrentUser({ apiUrl, credential, flowRequestId }) {
   return requestAuthJson(
     flowRequestId,
     buildApiPath(apiUrl, "/api/v1/auth/me"),
     {
       method: "GET",
-      headers: withFlowRequestHeaders(toAuthHeader(token), flowRequestId),
+      credential,
+      headers: withFlowRequestHeaders({}, flowRequestId),
     }
   );
 }
 
 async function issueApiToken({
   apiUrl,
-  authToken,
+  credential,
   tokenLabel,
   tokenTtlDays,
   flowRequestId,
@@ -406,12 +397,8 @@ async function issueApiToken({
     {
       method: "POST",
       operationName: "issue-token",
-      headers: withFlowRequestHeaders(
-        {
-          ...toAuthHeader(authToken),
-        },
-        flowRequestId
-      ),
+      credential,
+      headers: withFlowRequestHeaders({}, flowRequestId),
       body: {
         label: String(tokenLabel || "").trim() || defaultTokenLabel(),
         scope: "cli",
@@ -422,7 +409,7 @@ async function issueApiToken({
   );
 }
 
-async function revokeApiToken({ apiUrl, authToken, tokenId }) {
+async function revokeApiToken({ apiUrl, credential, tokenId }) {
   const normalizedTokenId = String(tokenId || "").trim();
   if (!normalizedTokenId) {
     return false;
@@ -430,9 +417,7 @@ async function revokeApiToken({ apiUrl, authToken, tokenId }) {
   await requestJsonMutation(buildApiPath(apiUrl, `/api/v1/auth/api-tokens/${encodeURIComponent(normalizedTokenId)}`), {
     method: "DELETE",
     operationName: "revoke-token",
-    headers: {
-      ...toAuthHeader(authToken),
-    },
+    credential,
   });
   return true;
 }
@@ -443,6 +428,7 @@ async function rotateStoredApiTokenIfNeeded({
   tokenLabel,
   tokenTtlDays,
   homeDir,
+  context,
 }) {
   if (!session || !session.token || !session.tokenExpiresAt) {
     return { session, rotated: false };
@@ -453,7 +439,7 @@ async function rotateStoredApiTokenIfNeeded({
 
   const issued = await issueApiToken({
     apiUrl: session.apiUrl,
-    authToken: session.token,
+    credential: await userCredential(session.token, { context, source: "session" }),
     tokenLabel,
     tokenTtlDays,
   });
@@ -475,7 +461,7 @@ async function rotateStoredApiTokenIfNeeded({
     try {
       await revokeApiToken({
         apiUrl: session.apiUrl,
-        authToken: nextSession.token,
+        credential: await userCredential(nextSession.token, { context, source: "session" }),
         tokenId: session.tokenId,
       });
     } catch (error) {
@@ -536,6 +522,10 @@ export async function loginAndPersistSession({
   homeDir,
 } = {}) {
   const apiUrl = await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir });
+  // The token this flow issues is the user's, so the API that issues it must be the configured
+  // one: refuse any other before the browser step. Resolution and trust share env and homeDir.
+  const context = await resolveTrustContext({ env, homeDir });
+  await assertTrustedApiUrl(apiUrl, { context });
   const challenge = generateChallenge();
   const flowRequestId = createFlowRequestId();
   const session = await startCliAuthSession({
@@ -574,13 +564,14 @@ export async function loginAndPersistSession({
       requestId: flowRequestId || null,
     });
   }
+  const approvalCredential = await userCredential(approvalToken, { context, source: "login_approval" });
 
   const user = normalizeUser(
-    approval.user || (await fetchCurrentUser({ apiUrl, token: approvalToken, flowRequestId }))
+    approval.user || (await fetchCurrentUser({ apiUrl, credential: approvalCredential, flowRequestId }))
   );
   const issuedApiToken = await issueApiToken({
     apiUrl,
-    authToken: approvalToken,
+    credential: approvalCredential,
     tokenLabel,
     tokenTtlDays,
     flowRequestId,
@@ -641,7 +632,7 @@ export async function loginAndPersistSession({
  * }} [options]
  * @returns {Promise<null | {
  *   apiUrl: string,
- *   token: string,
+ *   credential: object,
  *   source: "env" | "config" | "session",
  *   user: {
  *     id: string,
@@ -674,12 +665,15 @@ export async function resolveActiveAuthSession({
   if (scoped !== undefined) return scoped;
 
   const apiUrl = await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir });
+  // Each token below is bound to the configured API by the one trust context; `apiUrl` may name
+  // another origin (--api-url, a project config), and then a request carrying it is refused.
+  const context = await resolveTrustContext({ env, homeDir });
 
   const envToken = String(env.SENTINELAYER_TOKEN || "").trim();
   if (envToken) {
     return {
       apiUrl,
-      token: envToken,
+      credential: await userCredential(envToken, { context, source: "env" }),
       source: "env",
       user: null,
       aidenid: null,
@@ -692,12 +686,13 @@ export async function resolveActiveAuthSession({
     };
   }
 
+  // The user's own config only: a workspace .sentinelayer.yml does not choose whose token is used.
   const config = await loadConfig({ cwd, env, homeDir });
-  const configuredToken = String(config.resolved.sentinelayerToken || "").trim();
+  const configuredToken = String(config.layers.global.sentinelayerToken || "").trim();
   if (configuredToken) {
     return {
       apiUrl,
-      token: configuredToken,
+      credential: await userCredential(configuredToken, { context, source: "config" }),
       source: "config",
       user: null,
       aidenid: null,
@@ -725,6 +720,7 @@ export async function resolveActiveAuthSession({
         tokenLabel,
         tokenTtlDays,
         homeDir,
+        context,
       });
       active = rotateResult.session;
       rotated = rotateResult.rotated;
@@ -743,7 +739,7 @@ export async function resolveActiveAuthSession({
 
   return {
     apiUrl,
-    token: active.token,
+    credential: await userCredential(active.token, { context, source: "session" }),
     source: "session",
     user: normalizeUser(active.user || {}),
     aidenid: active.aidenid || null,
@@ -829,7 +825,7 @@ export async function getAuthStatus({
   let remoteError = null;
   if (checkRemote) {
     try {
-      remoteUser = normalizeUser(await fetchCurrentUser({ apiUrl: session.apiUrl, token: session.token }));
+      remoteUser = normalizeUser(await fetchCurrentUser({ apiUrl: session.apiUrl, credential: session.credential }));
     } catch (error) {
       remoteError =
         error instanceof SentinelayerApiError
@@ -938,7 +934,7 @@ export async function revokeAuthToken({
     autoRotate: false,
     homeDir,
   });
-  if (!active || !active.token) {
+  if (!isAuthenticated(active)) {
     throw new SentinelayerApiError(`No active auth token found. Run \`${authLoginHint()}\` first.`, {
       status: 401,
       code: "AUTH_REQUIRED",
@@ -954,7 +950,7 @@ export async function revokeAuthToken({
 
   await revokeApiToken({
     apiUrl: active.apiUrl,
-    authToken: active.token,
+    credential: active.credential,
     tokenId: targetTokenId,
   });
 
@@ -1020,7 +1016,7 @@ export async function logoutSession({
     try {
       await revokeApiToken({
         apiUrl: await resolveApiUrl({ cwd, env, explicitApiUrl, homeDir }),
-        authToken: stored.token,
+        credential: await userCredential(stored.token, { env, homeDir, source: "session" }),
         tokenId: stored.tokenId,
       });
       revokedRemote = true;
@@ -1043,15 +1039,15 @@ export async function logoutSession({
  *
  * @param {{
  *   apiUrl: string,
- *   authToken: string,
+ *   credential: object,
  *   runId: string,
  *   afterEventId?: string | null
- * }} [options]
+ * }} [options] credential: the resolved auth's `credential` (src/auth/credential-destinations.js)
  * @returns {Promise<any>}
  */
 export async function listRuntimeRunEvents({
   apiUrl,
-  authToken,
+  credential,
   runId,
   afterEventId = null,
 } = {}) {
@@ -1062,7 +1058,7 @@ export async function listRuntimeRunEvents({
     buildApiPath(apiUrl, `/api/v1/runtime/runs/${encodeURIComponent(String(runId || ""))}/events/list${query}`),
     {
       method: "GET",
-      headers: toAuthHeader(authToken),
+      credential,
     }
   );
 }
@@ -1070,7 +1066,7 @@ export async function listRuntimeRunEvents({
 /**
  * Fetch runtime run status snapshot from the Sentinelayer API.
  *
- * @param {{ apiUrl: string, authToken: string, runId: string }} [options]
+ * @param {{ apiUrl: string, credential: object, runId: string }} [options]
  * @returns {Promise<any>}
  */
 /**
@@ -1079,13 +1075,13 @@ export async function listRuntimeRunEvents({
  */
 export async function fetchAidenIdCredentials({
   apiUrl = DEFAULT_API_URL,
-  token = "",
+  auth = null,
 } = {}) {
   const response = await requestJson(
     buildApiPath(apiUrl, "/api/v1/aidenid/credentials"),
     {
       method: "GET",
-      headers: toAuthHeader(token),
+      credential: await credentialFor(auth),
     }
   );
   return {
@@ -1099,14 +1095,14 @@ export async function fetchAidenIdCredentials({
 
 export async function getRuntimeRunStatus({
   apiUrl,
-  authToken,
+  credential,
   runId,
 } = {}) {
   return requestJson(
     buildApiPath(apiUrl, `/api/v1/runtime/runs/${encodeURIComponent(String(runId || ""))}/status`),
     {
       method: "GET",
-      headers: toAuthHeader(authToken),
+      credential,
     }
   );
 }