@monster-orange/den 0.4.0 → 0.4.2

package/src/ui/cli/web-command.ts

@@ -12,6 +12,26 @@ import {
 } from "../../shared/secrets/index.js";
 import { getDistRoot, getEngineRoot, getStateDir } from "../../shared/paths.js";
 import { hasDenUiMarker } from "../../shared/ui-marker.js";
+import {
+  cliAuthHeaders,
+  ensureWebSecret,
+  osUser,
+  personToken,
+  readWebSecret,
+  rotateWebSecret,
+} from "../../shared/web-secret.js";
+import {
+  ignoredConfigWarning,
+  localhostOrigin,
+  loginLink,
+  mintLoginCode,
+  parseOrigin,
+  readWebAuthConfig,
+  SESSION_TOUCH_MS,
+  sessionIdPrefix,
+  WebSessionStore,
+} from "../../shared/web-session.js";
+import { revokeAllActorTokens } from "../../shared/actor-token.js";
 import { engineBin, engineModuleFile } from "../../shared/engine.js";
 import { readWebPort } from "../../shared/edge/config.js";
 import {
@@ -22,8 +42,10 @@ import {
 } from "./server-identity.js";
 
 import { product } from "../../shared/product.js";
+import { redactSecrets } from "../../shared/redact.js";
 interface WebCommandOptions {
-  action: "up" | "down" | "restart";
+  /** `open` is `up` that always opens a fresh sign-in tab (SEC-1b). */
+  action: "up" | "down" | "restart" | "open";
   port: number;
   openBrowser: boolean;
   silent: boolean;
@@ -33,6 +55,8 @@ interface WebCommandOptions {
 interface StartedServer {
   pid: number | undefined;
   logPath: string;
+  /** Where this start's output begins in the log. */
+  logOffset?: number;
 }
 
 interface WebServerState {
@@ -113,6 +137,7 @@ export function parseWebCommandArgs(
     const arg = args[i];
     if (
       arg === "up" ||
+      arg === "open" ||
       arg === "down" ||
       arg === "restart" ||
       arg === "start" || // legacy alias for up
@@ -159,6 +184,7 @@ export function parseWebCommandArgs(
     throw new Error(`Unknown web option: ${arg}`);
   }
 
+  if (options.action === "open") options.openBrowser = true;
   if (options.setupBrowserAccess && options.action !== "up") {
     throw new Error(
       `--setup-browser-access is only valid with ${product().cli} web up`,
@@ -310,10 +336,50 @@ export async function isDenWebRunning(port: number): Promise<boolean> {
   return (await isDenWebApiRunning(port)) && (await isDenWebUiReady(port));
 }
 
-async function waitForDenWeb(port: number): Promise<boolean> {
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Why a server that just started refused to (its `✗ <reason>` line: the
+ * bind refusal, a wrong web.session value), read from this start's part of
+ * its log, secret-shaped values redacted. Null when it said none.
+ */
+export function startupRefusal(logPath: string, offset = 0): string | null {
+  let text: string;
+  try {
+    const fd = fs.openSync(logPath, "r");
+    try {
+      const size = fs.fstatSync(fd).size;
+      const from = Math.max(0, Math.min(offset, size), size - 64 * 1024);
+      const buf = Buffer.alloc(size - from);
+      fs.readSync(fd, buf, 0, buf.length, from);
+      text = buf.toString("utf-8");
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+  const lines = text
+    .split(/\r?\n/)
+    .map((l) => /^\s*✗\s+(.+?)\s*$/.exec(l)?.[1])
+    .filter((l): l is string => !!l);
+  const last = lines.at(-1);
+  return last ? redactSecrets(last).slice(0, 600) : null;
+}
+
+async function waitForDenWeb(port: number, pid?: number): Promise<boolean> {
   const deadline = Date.now() + WEB_START_TIMEOUT_MS;
   while (Date.now() < deadline) {
     if (await isDenWebRunning(port)) return true;
+    // A server that refused to start has exited: no point waiting it out.
+    if (pid !== undefined && !pidAlive(pid)) return isDenWebRunning(port);
     await new Promise((resolve) => setTimeout(resolve, WEB_START_POLL_MS));
   }
   return false;
@@ -393,6 +459,7 @@ function startDenWebServer(options: WebCommandOptions): StartedServer {
     `\n--- ${product().cli} web start ${new Date().toISOString()} ---\n`,
   );
 
+  const logOffset = fs.statSync(logPath).size;
   const logFd = fs.openSync(logPath, "a");
   try {
     const child = spawn(
@@ -406,7 +473,7 @@ function startDenWebServer(options: WebCommandOptions): StartedServer {
       },
     );
     child.unref();
-    const started = { pid: child.pid, logPath };
+    const started = { pid: child.pid, logPath, logOffset };
     writeWebServerState({
       ...started,
       port: options.port,
@@ -867,15 +934,26 @@ function openUrl(url: string): BrowserOpenResult {
   return { status: "open-failed", error };
 }
 
-function openOrFocusDenWebUrl(url: string, port: number): BrowserOpenResult {
-  const focusResult = focusExistingBrowserTab(port);
-  if (focusResult.status === "focused") return focusResult;
-
-  if (focusResult.status === "error" && process.platform === "darwin") {
-    return focusResult;
+/**
+ * Focus a tab already on this server, else open `url()` (SEC-1b: the
+ * sign-in link, minted only when it is opened). `focus: false` (`web
+ * open`) always opens.
+ */
+function openOrFocusDenWebUrl(
+  url: () => string,
+  port: number,
+  focus = true,
+): BrowserOpenResult {
+  if (focus) {
+    const focusResult = focusExistingBrowserTab(port);
+    if (focusResult.status === "focused") return focusResult;
+
+    if (focusResult.status === "error" && process.platform === "darwin") {
+      return focusResult;
+    }
   }
 
-  return openUrl(url);
+  return openUrl(url());
 }
 
 function buildBrowserAccessProbeScript(appName: string): string {
@@ -987,12 +1065,28 @@ function setupBrowserAccess(): void {
   console.log(chalk.gray(`  ${product().cli} web --setup-browser-access\n`));
 }
 
+/** `web` subcommands that answer their own --help (cmdWeb dispatches them first). */
+export const WEB_SUBCOMMANDS_WITH_HELP = [
+  "token",
+  "login",
+  "sessions",
+  "logout",
+] as const;
+
 export function displayWebHelp(): void {
   console.log(chalk.bold("\nUsage:"));
   console.log(
     `  ${product().cli} web [up|down|restart] [--port <port>] [--no-open] [--verbose]`,
   );
   console.log(`  ${product().cli} web --setup-browser-access`);
+  console.log(`  ${product().cli} web token --print`);
+  console.log(
+    `  ${product().cli} web login [--next <path>] [--origin <url>] [--port <port>]`,
+  );
+  console.log(`  ${product().cli} web sessions [--json] [--port <port>]`);
+  console.log(
+    `  ${product().cli} web logout [<id prefix>] [--all] [--port <port>]`,
+  );
   console.log();
   console.log(chalk.bold("Actions:"));
   console.log(
@@ -1002,6 +1096,19 @@ export function displayWebHelp(): void {
     `  down               Stop the ${product().title} web daemon only`,
   );
   console.log(`  restart            Stop then start ${product().title} web`);
+  console.log(
+    "  open               Start if needed, and sign this browser in (a new tab)",
+  );
+  console.log(
+    "  login              Print a one-time sign-in link (60 s), for another browser",
+  );
+  console.log("  sessions           List the signed-in browsers");
+  console.log(
+    "  logout [<id>]      Sign out one browser, or all; --all also rotates web.secret and revokes agent tokens",
+  );
+  console.log(
+    "  token --print      Print your CLI token, for curl (Authorization: Bearer …)",
+  );
   console.log("  (start/stop remain accepted as legacy aliases for up/down)");
   console.log();
   console.log(chalk.bold("Options:"));
@@ -1021,7 +1128,62 @@ export function displayWebHelp(): void {
   console.log();
 }
 
+/**
+ * `<cli> web token --print` (SEC-1a): the person token, for curl. The token
+ * alone on stdout; a one-line note on stderr that it grants the user's
+ * access. Creates web.secret on first need.
+ */
+export function cmdWebToken(
+  args: string[],
+  io: {
+    out: (s: string) => void;
+    err: (s: string) => void;
+    stateDir?: string;
+  } = {
+    out: (s) => process.stdout.write(s),
+    err: (s) => process.stderr.write(s),
+  },
+): number {
+  const usage =
+    `Usage: ${product().cli} web token --print\n` +
+    "  Prints the token that authorizes your CLI's calls to the web server.\n";
+  if (isHelp(args)) {
+    io.out(usage);
+    return 0;
+  }
+  const rest = args.filter((a) => a !== "--print");
+  if (!args.includes("--print") || rest.length > 0) {
+    io.err(usage);
+    return 2;
+  }
+  const secret = ensureWebSecret(io.stateDir ?? getStateDir());
+  io.err(
+    `${product().cli}: this token grants your access (person:${osUser()}) to ` +
+      `${product().title} web; keep it out of logs and shared shells.\n`,
+  );
+  io.out(`${personToken(secret)}\n`);
+  return 0;
+}
+
 export async function cmdWeb(args: string[]): Promise<void> {
+  // A subcommand with its own help answers its own --help (it is
+  // dispatched first); the rest (up, down, restart, open) share this one.
+  if (args[0] === "token") {
+    process.exitCode = cmdWebToken(args.slice(1));
+    return;
+  }
+  if (args[0] === "login") {
+    process.exitCode = cmdWebLogin(args.slice(1));
+    return;
+  }
+  if (args[0] === "sessions") {
+    process.exitCode = await cmdWebSessions(args.slice(1));
+    return;
+  }
+  if (args[0] === "logout") {
+    process.exitCode = await cmdWebLogout(args.slice(1));
+    return;
+  }
   if (args.includes("--help") || args.includes("-h")) {
     displayWebHelp();
     return;
@@ -1079,6 +1241,15 @@ export async function cmdWeb(args: string[]): Promise<void> {
     );
   }
 
+  // SEC-1b: a wrong web.allow_plain_http_remote would stop the server at
+  // start; say so here, naming the key, instead of "did not become ready".
+  // A key read and ignored (the distribution's web.allow_plain_http_remote:
+  // only user.yml counts) is said here too, not only in the server's log.
+  const ignored = ignoredConfigWarning(
+    readWebAuthConfig(getDistRoot(), product().configFile),
+  );
+  if (ignored) console.log(chalk.yellow(`\n  ⚠ ${ignored}`));
+
   const apiRunning = await isDenWebApiRunning(options.port);
   let running = apiRunning && (await isDenWebUiReady(options.port));
   let started: StartedServer | null = null;
@@ -1102,10 +1273,14 @@ export async function cmdWeb(args: string[]): Promise<void> {
     console.log(chalk.cyan(`\n  Starting ${product().cli} web on ${url}...`));
     try {
       started = startDenWebServer(options);
-      running = await waitForDenWeb(options.port);
+      running = await waitForDenWeb(options.port, started.pid);
       if (!running) {
+        // The server's own reason, when it gave one, then where to look.
+        const why = startupRefusal(started.logPath, started.logOffset);
         throw new Error(
-          `${product().title} web did not become ready. See ${started.logPath}`,
+          why
+            ? `${product().title} web refused to start: ${why}\n  See ${started.logPath}`
+            : `${product().title} web did not become ready. See ${started.logPath}`,
         );
       }
       console.log(
@@ -1130,7 +1305,16 @@ export async function cmdWeb(args: string[]): Promise<void> {
     return;
   }
 
-  const browser = openOrFocusDenWebUrl(url, options.port);
+  // SEC-1b: what opens is a sign-in link (localhost, one-time, 60 s). It
+  // is printed only when the browser couldn't be opened: the one line the
+  // person then needs.
+  let link: string | null = null;
+  const signIn = () => (link ??= freshLoginLink(options.port));
+  const browser = openOrFocusDenWebUrl(
+    signIn,
+    options.port,
+    options.action !== "open",
+  );
   if (browser.status === "focused") {
     console.log(chalk.green(`  OK Focused existing ${browser.app} tab`));
     console.log(chalk.gray(`  ${url}\n`));
@@ -1162,5 +1346,349 @@ export async function cmdWeb(args: string[]): Promise<void> {
   } else {
     console.log(chalk.yellow("\n  Could not open a browser automatically."));
   }
-  console.log(chalk.gray(`  Visit: ${url}\n`));
+  console.log(`  Sign in (once, within 60 s): ${signIn()}\n`);
+}
+
+// ── SEC-1b: sign-in (`web login`, `web sessions`, `web logout`) ─────────────
+
+/** A fresh one-time sign-in link for `origin` (localhost by default). */
+export function freshLoginLink(
+  port: number,
+  next = "/",
+  origin: string = localhostOrigin(port),
+  stateDir: string = getStateDir(),
+): string {
+  return loginLink(origin, mintLoginCode(ensureWebSecret(stateDir)), next);
+}
+
+interface CliIo {
+  out: (s: string) => void;
+  err: (s: string) => void;
+  stateDir?: string;
+}
+const stdIo: CliIo = {
+  out: (s) => process.stdout.write(s),
+  err: (s) => process.stderr.write(s),
+};
+
+/** `--help` or `-h` among a subcommand's args. */
+function isHelp(args: readonly string[]): boolean {
+  return args.includes("--help") || args.includes("-h");
+}
+
+/** `--port <p>` / `--port=<p>` / `-p <p>`, and the rest of `args`. */
+function takePort(args: string[]): { port: number; rest: string[] } {
+  let port = parsePort(process.env.PORT);
+  const rest: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--port" || a === "-p") {
+      port = parsePort(args[++i]);
+    } else if (a.startsWith("--port=")) {
+      port = parsePort(a.slice("--port=".length));
+    } else rest.push(a);
+  }
+  return { port, rest };
+}
+
+/**
+ * `<cli> web login [--next <path>] [--origin <url>]`: a fresh sign-in link
+ * on stdout, alone (the only place a login code is ever printed); a note on
+ * stderr. `--origin` for the edge hostname or a LAN name, where the cookie
+ * must be set (the signed-out page there says which).
+ */
+export function cmdWebLogin(args: string[], io: CliIo = stdIo): number {
+  const usage = `Usage: ${product().cli} web login [--next <path>] [--origin <url>] [--port <port>]\n`;
+  if (isHelp(args)) {
+    io.out(
+      usage +
+        "  Prints a one-time sign-in link (it works once, within 60 s) for one browser.\n" +
+        "  On localhost nothing asks for a sign-in; it is needed when this server is\n" +
+        "  reached beyond this machine (the edge, or a LAN address: pass its --origin).\n" +
+        "  --next <path>   where the browser lands after signing in (same origin only)\n" +
+        "  --origin <url>  the address the browser uses, http(s)://host[:port]\n",
+    );
+    return 0;
+  }
+  let next = "/";
+  let origin: string | null = null;
+  let port: number;
+  let rest: string[];
+  try {
+    ({ port, rest } = takePort(args));
+  } catch (e) {
+    io.err(`${(e as Error).message}\n`);
+    return 2;
+  }
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    const val = (flag: string) =>
+      a === flag
+        ? rest[++i]
+        : a.startsWith(`${flag}=`)
+          ? a.slice(flag.length + 1)
+          : undefined;
+    const n = val("--next");
+    const o = val("--origin");
+    if (n !== undefined) next = n;
+    else if (o !== undefined) {
+      origin = parseOrigin(o);
+      if (!origin) {
+        io.err(
+          `--origin must be http(s)://host[:port] with no path, got "${o}"\n`,
+        );
+        return 2;
+      }
+    } else {
+      io.err(usage);
+      return 2;
+    }
+  }
+  const link = freshLoginLink(
+    port,
+    next,
+    origin ?? localhostOrigin(port),
+    io.stateDir ?? getStateDir(),
+  );
+  io.err(
+    `${product().cli}: open this link within 60 seconds; it signs in one browser, once.\n`,
+  );
+  io.out(`${link}\n`);
+  return 0;
+}
+
+interface SessionRow {
+  id: string;
+  createdAt: string;
+  lastSeenAt: string;
+  userAgent: string;
+  host: string;
+}
+
+/**
+ * A call to the running server with the person token, or null when no
+ * server answers on the port (the caller then edits the state files).
+ */
+function serverCall(
+  stateDir: string,
+  port: number,
+  method: string,
+  p: string,
+  body?: unknown,
+): Promise<{ status: number; json: unknown } | null> {
+  return new Promise((resolve) => {
+    const payload = body === undefined ? undefined : JSON.stringify(body);
+    const req = http.request(
+      {
+        host: "127.0.0.1",
+        port,
+        path: p,
+        method,
+        timeout: 10_000,
+        headers: {
+          ...cliAuthHeaders(stateDir),
+          ...(payload !== undefined
+            ? {
+                "Content-Type": "application/json",
+                "Content-Length": String(Buffer.byteLength(payload)),
+              }
+            : {}),
+        },
+      },
+      (res) => {
+        let out = "";
+        res.setEncoding("utf-8");
+        res.on("data", (d: string) => (out += d));
+        res.on("end", () => {
+          let json: unknown = null;
+          try {
+            json = JSON.parse(out);
+          } catch {
+            /* not JSON */
+          }
+          resolve({ status: res.statusCode ?? 0, json });
+        });
+      },
+    );
+    req.on("timeout", () => req.destroy());
+    req.on("error", () => resolve(null));
+    req.end(payload);
+  });
+}
+
+function offlineStore(stateDir: string): WebSessionStore {
+  return new WebSessionStore({
+    stateDir: () => stateDir,
+    secret: () => readWebSecret(stateDir),
+  });
+}
+
+function apiError(r: { status: number; json: unknown }): string {
+  const e = (r.json as { error?: unknown } | null)?.error;
+  return typeof e === "string" ? e : `the server answered ${r.status}`;
+}
+
+/** `<cli> web sessions [--json]`: the signed-in browsers. */
+export async function cmdWebSessions(
+  args: string[],
+  io: CliIo = stdIo,
+): Promise<number> {
+  let port: number;
+  let rest: string[];
+  try {
+    ({ port, rest } = takePort(args));
+  } catch (e) {
+    io.err(`${(e as Error).message}\n`);
+    return 2;
+  }
+  const usage = `Usage: ${product().cli} web sessions [--json] [--port <port>]\n`;
+  if (isHelp(rest)) {
+    io.out(
+      usage +
+        "  The browsers signed in to this server: ID (for `web logout <id>`), CREATED,\n" +
+        `  LAST SEEN, HOST and USER AGENT. LAST SEEN is written at most once a\n` +
+        `  minute (${SESSION_TOUCH_MS / 1000} s) per session, so it trails a browser's last request by up to\n` +
+        "  that long (right after sign-in it equals CREATED). A session never\n" +
+        "  expires: it ends at sign-out or `web logout`.\n",
+    );
+    return 0;
+  }
+  const asJson = rest.includes("--json");
+  if (rest.some((a) => a !== "--json")) {
+    io.err(usage);
+    return 2;
+  }
+  const stateDir = io.stateDir ?? getStateDir();
+  let rows: SessionRow[];
+  const r = await serverCall(stateDir, port, "GET", "/api/web/sessions");
+  if (r) {
+    if (r.status !== 200) {
+      io.err(`${product().cli}: ${apiError(r)}\n`);
+      return 1;
+    }
+    rows = (r.json as { sessions: SessionRow[] }).sessions;
+  } else {
+    rows = offlineStore(stateDir)
+      .list()
+      .map((x) => ({
+        id: sessionIdPrefix(x.key),
+        createdAt: new Date(x.createdAt).toISOString(),
+        lastSeenAt: new Date(x.lastSeenAt).toISOString(),
+        userAgent: x.userAgent,
+        host: x.host,
+      }));
+  }
+  if (asJson) {
+    io.out(`${JSON.stringify(rows, null, 2)}\n`);
+    return 0;
+  }
+  if (rows.length === 0) {
+    io.out("No signed-in browsers.\n");
+    return 0;
+  }
+  const when = (iso: string) => iso.replace("T", " ").replace(/\.\d+Z$/, "Z");
+  const table = [
+    ["ID", "CREATED", "LAST SEEN", "HOST", "USER AGENT"],
+    ...rows.map((x) => [
+      x.id,
+      when(x.createdAt),
+      when(x.lastSeenAt),
+      x.host,
+      x.userAgent,
+    ]),
+  ];
+  const widths = table[0].map((_, c) =>
+    Math.max(...table.map((row) => row[c].length)),
+  );
+  for (const row of table)
+    io.out(
+      `${row
+        .map((cell, c) =>
+          c === row.length - 1 ? cell : cell.padEnd(widths[c]),
+        )
+        .join("  ")
+        .trimEnd()}\n`,
+    );
+  return 0;
+}
+
+/**
+ * `<cli> web logout [<id prefix>] [--all]`: sign out one browser, or every
+ * browser; `--all` also rotates web.secret, which ends every session and
+ * every person token (the CLI re-reads it, so it keeps working), and
+ * revokes every agent's actor token (SEC-1 §6c.2).
+ */
+export async function cmdWebLogout(
+  args: string[],
+  io: CliIo = stdIo,
+): Promise<number> {
+  let port: number;
+  let rest: string[];
+  try {
+    ({ port, rest } = takePort(args));
+  } catch (e) {
+    io.err(`${(e as Error).message}\n`);
+    return 2;
+  }
+  const usage = `Usage: ${product().cli} web logout [<id prefix>] [--all] [--port <port>]\n`;
+  if (isHelp(rest)) {
+    io.out(
+      usage +
+        "  <id prefix>  sign out one browser (an ID from `web sessions`)\n" +
+        "  (none)       sign out every browser; agents keep their tokens\n" +
+        "  --all        sign out every browser, rotate web.secret (every person token\n" +
+        "               is void; this CLI re-reads it) and revoke every agent's token:\n" +
+        "               a running agent must be restarted or resumed for a new one\n",
+    );
+    return 0;
+  }
+  const all = rest.includes("--all");
+  const ids = rest.filter((a) => a !== "--all");
+  if (
+    ids.length > 1 ||
+    ids.some((a) => a.startsWith("-")) ||
+    (all && ids.length)
+  ) {
+    io.err(usage);
+    return 2;
+  }
+  const id = ids[0];
+  const stateDir = io.stateDir ?? getStateDir();
+  const r = await serverCall(stateDir, port, "POST", "/api/web/logout", {
+    ...(id ? { id } : {}),
+    ...(all ? { rotate: true } : {}),
+  });
+  let ended: number;
+  let agentTokens = 0;
+  if (r) {
+    if (r.status !== 200) {
+      io.err(`${product().cli}: ${apiError(r)}\n`);
+      return 1;
+    }
+    const j = r.json as { ended?: unknown[]; agentTokens?: unknown };
+    ended = (j.ended ?? []).length;
+    if (typeof j.agentTokens === "number") agentTokens = j.agentTokens;
+  } else {
+    // No server: the state files themselves (the same OS user's).
+    const store = offlineStore(stateDir);
+    try {
+      ended = id ? (store.endByPrefix(id), 1) : store.endAll();
+    } catch (e) {
+      io.err(`${product().cli}: ${(e as Error).message}\n`);
+      return 1;
+    }
+    if (all) {
+      if (readWebSecret(stateDir)) rotateWebSecret(stateDir);
+      agentTokens = revokeAllActorTokens(stateDir);
+    }
+  }
+  io.out(
+    `Signed out ${ended} browser${ended === 1 ? "" : "s"}.` +
+      (all
+        ? ` web.secret rotated: every old session and person token is void; this CLI keeps working.` +
+          ` Revoked ${agentTokens} agent token${agentTokens === 1 ? "" : "s"}: a running agent must be restarted or resumed to get a new one.`
+        : "") +
+      "\n",
+  );
+  return 0;
 }

package/src/ui/mcp/api.ts

@@ -10,6 +10,7 @@
  * every tool says whose server it is instead of serving its data.
  */
 import { product } from "../../shared/product.js";
+import { cliAuthHeaders } from "../../shared/web-secret.js";
 import {
   foreignServerMessage,
   identifyServer,
@@ -233,6 +234,11 @@ export function createDenApi(opts: {
   headers: () => Record<string, string>;
   /** Check whose server it is before any request (the MCP server does). */
   identity?: IdentityCheck;
+  /**
+   * The credential every call carries (SEC-1a): the person token from
+   * web.secret by default (cliAuthHeaders, the one CLI-side helper).
+   */
+  auth?: () => Record<string, string>;
 }): DenApi {
   const { baseUrl, cli } = opts;
   const { hostname } = new URL(baseUrl);
@@ -284,6 +290,7 @@ export function createDenApi(opts: {
         method,
         headers: {
           ...opts.headers(),
+          ...(opts.auth ?? cliAuthHeaders)(),
           ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
         },
         ...(body !== undefined ? { body: JSON.stringify(body) } : {}),