@monster-orange/den 0.4.0 → 0.4.1

package/src/shared/agents/den-claude.ts

@@ -9,6 +9,12 @@
  *   workspace; --strict-mcp-config keeps any other MCP server out, so the
  *   agent acts only through Den (§1).
  * - The role prompt is appended to Claude Code's own system prompt.
+ * - Den's state dir is denied to the agent (SEC-1 §6c.1): a settings file
+ *   (--settings, 0600) whose `permissions.deny` lists Read and Bash rules
+ *   (any command naming the path) for `<state>/web.secret` and
+ *   `<state>/sessions/**`. It binds a
+ *   cooperating agent only: the agent runs as the same OS user, so nothing
+ *   stops one that ignores its permission config from reading them.
  * - Each launch picks a fresh conversation id (--session-id); resume
  *   continues it with --resume <id>, in the same cwd, with the same MCP.
  * - Permission prompts stay in the terminal (approvals: "terminal"):
@@ -98,6 +104,81 @@ function detect(env: NodeJS.ProcessEnv = process.env): RuntimeDetect {
   return version ? { available: true, version } : { available: true };
 }
 
+/**
+ * Claude Code `permissions.deny` rules that keep a cooperating agent out of
+ * Den's credentials (SEC-1 §6c.1): web.secret and the session host's
+ * records.
+ *
+ * - Read: absolute paths (`//…` in Claude Code's rule syntax).
+ * - Bash, in Claude Code's documented wildcard form: `*` matches any run of
+ *   characters, at any position, and a rule matches a command (each part
+ *   of a compound one) whole. `Bash(*<path>*)` denies any command that names
+ *   the path, whatever the program (cat, head, cp, base64) and whether it is
+ *   quoted ("…" or '…' still contain it). The legacy prefix form,
+ *   `Bash(cat <path>:*)`, didn't match a bare `cat <path>` on Claude Code
+ *   2.1.x (it asked for approval instead of denying: a dogfood finding), so
+ *   it is kept only for older versions, after the wildcard rules.
+ * - The readers in BASH_READERS (cat, head, tail, …) by name as well. This
+ *   binds a cooperating agent only, and no list names every reader: the
+ *   boundary is the server's token rules (SEC-1 §5), never these.
+ * - The same path as a shell writes it from `home`: `~/…` and `$HOME/…`,
+ *   `${HOME}/…`, and, when the path has a space, with each space
+ *   backslash-escaped.
+ */
+export function stateDirDenyRules(stateDir: string, home?: string): string[] {
+  const abs = path.resolve(stateDir);
+  const secret = path.join(abs, "web.secret");
+  const sessions = path.join(abs, "sessions");
+  const spellings = (p: string): string[] => {
+    const out = [p];
+    if (home) {
+      const h = path.resolve(home);
+      if (p.startsWith(h + path.sep)) {
+        const rel = p.slice(h.length + 1);
+        out.push(`~/${rel}`, `$HOME/${rel}`, "${HOME}/" + rel);
+      }
+    }
+    for (const x of [...out])
+      if (x.includes(" ")) out.push(x.replace(/ /g, "\\ "));
+    return [...new Set(out)];
+  };
+  const targets = [
+    ...spellings(secret).map((p) => `${p}*`),
+    ...spellings(sessions).map((p) => `${p}/*`),
+  ];
+  return [
+    `Read(/${secret})`,
+    `Read(/${sessions}/**)`,
+    // Any command naming the path, whatever the program.
+    ...targets.map((t) => `Bash(*${t})`),
+    // The common readers by name too, should a version match a leading
+    // wildcard differently. A deny list can't name every reader: the
+    // boundary is the server's token rules (SEC-1 §5), not these.
+    ...BASH_READERS.flatMap((r) => targets.map((t) => `Bash(${r} *${t})`)),
+    `Bash(cat ${secret}:*)`,
+    `Bash(cat ${sessions}/:*)`,
+  ];
+}
+
+/** The readers named in the Bash deny rules (stateDirDenyRules). */
+export const BASH_READERS = [
+  "cat",
+  "head",
+  "tail",
+  "less",
+  "more",
+  "xxd",
+  "od",
+  "strings",
+  "base64",
+  "cp",
+] as const;
+
+/** The settings file den-claude passes with --settings. */
+export function settingsPath(input: Pick<LaunchInput, "filesDir">): string {
+  return path.join(input.filesDir, "settings.json");
+}
+
 /** The flags every run shares: Den's MCP only, the model, the role prompt. */
 function common(input: LaunchInput): {
   argv: string[];
@@ -106,11 +187,13 @@ function common(input: LaunchInput): {
 } {
   const file = mcpConfigPath(input);
   const mode = permissionMode(input);
+  const settings = input.stateDir ? settingsPath(input) : null;
   return {
     argv: [
       "--mcp-config",
       file,
       "--strict-mcp-config",
+      ...(settings ? ["--settings", settings] : []),
       "--permission-mode",
       mode,
       ...(input.model ? ["--model", input.model] : []),
@@ -122,7 +205,22 @@ function common(input: LaunchInput): {
         input.mcp.name,
       ),
     ],
-    files: { [file]: mcpConfigJson(input.mcp) },
+    files: {
+      [file]: mcpConfigJson(input.mcp),
+      ...(settings && input.stateDir
+        ? {
+            [settings]: `${JSON.stringify(
+              {
+                permissions: {
+                  deny: stateDirDenyRules(input.stateDir, input.env?.HOME),
+                },
+              },
+              null,
+              2,
+            )}\n`,
+          }
+        : {}),
+    },
     warnings:
       mode === "bypassPermissions"
         ? [

package/src/shared/agents/runtime.ts

@@ -51,6 +51,13 @@ export interface LaunchInput {
   mcp: AgentMcp;
   /** A directory of this agent's own (0700) for the files a runtime writes. */
   filesDir: string;
+  /**
+   * Den's own state dir (web.secret, the session records). A runtime adds
+   * deny rules for it to the agent's own permission config (SEC-1 §6c.1):
+   * that binds a cooperating agent only, since an agent runs as the same OS
+   * user and could read the files itself.
+   */
+  stateDir?: string;
   /**
    * The caller's environment, for finding the runtime's CLI on PATH. The
    * agent does not get it: it starts from an allowlist (sessions/env.ts),

package/src/shared/agents/runtimes.ts

@@ -5,6 +5,7 @@
 import { denClaude } from "./den-claude.js";
 import { generic } from "./generic.js";
 import { allScrubEnv, registerRuntime, type Runtime } from "./runtime.js";
+import { ACTOR_TOKEN_ENV } from "../actor-token.js";
 import { AGENT_ACTOR_ENV, buildSessionEnv } from "../sessions/env.js";
 
 registerRuntime(denClaude);
@@ -27,13 +28,16 @@ export {
 /**
  * An agent's session env, as `agents start` builds it and `doctor --probe`
  * checks it: the allowlist, the runtime's passthrough and launch env, Den's
- * marker (DEN_AGENT=agent:<id>), then every runtime's scrubEnv.
+ * markers (DEN_AGENT=agent:<id>, and SEC-1c's DEN_ACTOR_TOKEN when one was
+ * minted), then every runtime's scrubEnv and any person credential.
  */
 export function agentSessionEnv(
   caller: NodeJS.ProcessEnv,
   rt: Pick<Runtime, "envPassthrough">,
   launch: Record<string, string>,
   agentId: string,
+  /** SEC-1c: the agent's actor token (`agents start` mints it; the probe has none). */
+  actorToken?: string,
 ): Record<string, string> {
   return buildSessionEnv({
     caller,
@@ -41,7 +45,10 @@ export function agentSessionEnv(
     launch,
     // The seam for a persona's or runtime's declared env: none yet.
     extra: {},
-    den: { [AGENT_ACTOR_ENV]: `agent:${agentId}` },
+    den: {
+      [AGENT_ACTOR_ENV]: `agent:${agentId}`,
+      ...(actorToken ? { [ACTOR_TOKEN_ENV]: actorToken } : {}),
+    },
     scrub: allScrubEnv(),
   });
 }

package/src/shared/environment-manager/scope.ts

@@ -82,6 +82,28 @@ export function scopeView(scope?: ViewScope): ScopeView {
   };
 }
 
+/**
+ * WS-6.4: what health covers, whatever is in view: every active workspace,
+ * focused first. Scope only filters what is displayed (inViewMarker); it
+ * never narrows what is polled, so a workspace outside it still shows its
+ * real health on the Workspaces page.
+ */
+export function pollView(): ScopeView {
+  return scopeView(ALL_ACTIVE);
+}
+
+/**
+ * Whether a health row is in view: one of the workspaces that define it
+ * (`workspaces`, its owners) is in `view`. A row without owners counts as
+ * in view.
+ */
+export function inViewMarker(
+  view: ScopeView,
+): (owners: readonly string[] | undefined) => boolean {
+  const names = new Set(view.workspaces.map((w) => w.name));
+  return (owners) => !owners?.length || owners.some((o) => names.has(o));
+}
+
 /** A cache key for what is in view (the scope's workspaces, in order). */
 export function scopeKey(view: ScopeView): string {
   return view.workspaces.map((w) => w.name).join(",");

package/src/shared/environment-manager/service-runner.ts

@@ -400,6 +400,70 @@ export function findDaemonByAddress(address: string): DaemonRecord | undefined {
   return _daemonRegistry.get(address);
 }
 
+/**
+ * The other spelling of a single-service repo's daemon: "<repo>" and
+ * "<repo>/<svc>" name the same process (0.4.1-dev.5, a consumer's dev.4
+ * finding: `up <repo>` recorded "<repo>", `restart <repo>/<svc>` found no
+ * record, adopted the running process instead of restarting it, and left
+ * two records on one process group). Null for a repo with several
+ * services: each of its services is its own daemon.
+ */
+function singleServiceAlias(
+  resolved: Pick<ResolvedService, "address" | "repoName" | "subsystem"> & {
+    repoPath: string;
+  },
+): string | null {
+  const keys = Object.keys(readManifest(resolved.repoPath)?.services ?? {});
+  if (keys.length !== 1 || keys[0] !== resolved.subsystem) return null;
+  const full = `${resolved.repoName}/${resolved.subsystem}`;
+  if (resolved.address === resolved.repoName) return full;
+  if (resolved.address === full) return resolved.repoName;
+  return null;
+}
+
+/**
+ * Bring a single-service repo's record to the address this command uses,
+ * so every lookup by `resolved.address` finds it whichever spelling wrote
+ * it. A record only under the other spelling moves; a duplicate (two
+ * records on one process group, the dev.4 bug's leftover, or one of them
+ * dead or without a group) is merged into one, owners and containers
+ * unioned. Two records on two different live groups are left alone.
+ */
+export function reconcileDaemonAddress(resolved: ResolvedService): void {
+  const alias = singleServiceAlias(resolved);
+  if (!alias) return;
+  loadDaemonsFromFile();
+  const other = _daemonRegistry.get(alias);
+  if (!other || other.repoPath !== resolved.repoPath) return;
+  const own = _daemonRegistry.get(resolved.address);
+  if (own) {
+    const sameGroup =
+      own.pgid === undefined ||
+      other.pgid === undefined ||
+      own.pgid === other.pgid ||
+      isDaemonVerifiablyDead(other);
+    if (!sameGroup) return;
+  }
+  // The record carrying a process group is the one `down` can stop.
+  const keep =
+    own && (own.pgid !== undefined || other.pgid === undefined) ? own : other;
+  const drop = keep === own ? other : own;
+  const merged: DaemonRecord = {
+    ...keep,
+    address: resolved.address,
+    workspaces: [
+      ...new Set([...(keep.workspaces ?? []), ...(drop?.workspaces ?? [])]),
+    ],
+  };
+  const containers = [
+    ...new Set([...(keep.containers ?? []), ...(drop?.containers ?? [])]),
+  ];
+  if (containers.length > 0) merged.containers = containers;
+  _daemonRegistry.delete(alias);
+  _daemonRegistry.set(resolved.address, merged);
+  saveDaemonsFile(getDaemonsFile());
+}
+
 /** Add a workspace owner to a running daemon (share / attach). */
 export function attachDaemonOwner(address: string, workspace: string): void {
   loadDaemonsFromFile();
@@ -1344,6 +1408,12 @@ export interface RunCommandOptions {
   explicit?: boolean;
   /** For `down`: what it found to stop (see DownOutcome). */
   onDownOutcome?: (outcome: DownOutcome) => void;
+  /**
+   * Internal: this `up` is a restart's up step ("up"), or the up step of
+   * the restart a restart ran after adopting a process ("after-adopt").
+   * A restart never ends on an adoption: what it adopts it restarts.
+   */
+  restartStep?: "up" | "after-adopt";
 }
 
 /**
@@ -1506,6 +1576,7 @@ function settleDaemonRecord(
   record: DaemonRecord | undefined;
   outcome: "adopted" | "dropped" | "busy" | null;
 } {
+  reconcileDaemonAddress(resolved);
   const record = findDaemonByAddress(resolved.address);
   if (!record || !isLegacyRecord(record)) return { record, outcome: null };
   const outcome = settleLegacyRecord(record, resolved, workspace, onLine);
@@ -1674,7 +1745,12 @@ function restartAsDownThenUp(
         options.onClose(code);
         return;
       }
-      const up = runServiceCommand({ ...options, command: "up" });
+      const up = runServiceCommand({
+        ...options,
+        command: "up",
+        restartStep:
+          options.restartStep === "after-adopt" ? "after-adopt" : "up",
+      });
       tail = up.proc;
       if (stopTail) {
         try {
@@ -2052,6 +2128,9 @@ export function runServiceCommand(
   }
 
   const { repoPath, subsystem } = resolved;
+  // A single-service repo's record answers to "<repo>" and "<repo>/<svc>":
+  // every decision below reads it under this command's spelling.
+  reconcileDaemonAddress(resolved);
 
   const explicit = options.explicit ?? true;
   const reportDown = (outcome: DownOutcome): void =>
@@ -2217,6 +2296,16 @@ export function runServiceCommand(
           `${resolved.address} not started`,
         );
         if (holder === "adopted") {
+          // A restart's up step (its down found nothing recorded): the
+          // adopted process is the old instance, so it is restarted now,
+          // never left running as if restarted (0.4.1-dev.5).
+          if (options.restartStep === "up") {
+            onLine(`restarting the adopted process for ${resolved.address}`);
+            return restartAsDownThenUp(
+              { ...options, restartStep: "after-adopt" },
+              getServiceLogPath(resolved.repoName, resolved.subsystem),
+            );
+          }
           closeAsync(0);
           return dummy();
         }
@@ -2355,7 +2444,10 @@ export function runServiceCommand(
     resolved.repoName,
     workspace,
   );
-  let cmdDef = svcCommands[command];
+  // Own properties only (SEC-1 §6b.2): `constructor` is no command.
+  let cmdDef = Object.prototype.hasOwnProperty.call(svcCommands, command)
+    ? svcCommands[command]
+    : undefined;
   const requestedCmdDef = cmdDef;
 
   // `restart` fallback: synthesise `make down && make up` when no explicit

package/src/shared/profile.ts

@@ -70,8 +70,16 @@ const expandHome = (p: string): string =>
       ? path.join(os.homedir(), p.slice(2))
       : p;
 
-/** A profile from a `product:` block; unset fields derive from the name. */
-export function profileFrom(raw: RawProduct = {}): ProductProfile {
+/**
+ * A profile from a `product:` block; unset fields derive from the name. A
+ * relative `state_dir` resolves against `baseDir`: the directory holding
+ * den.yml (the distribution root), never the cwd, so an agent's CLI or MCP
+ * server started elsewhere reads the same state.
+ */
+export function profileFrom(
+  raw: RawProduct = {},
+  baseDir: string = process.cwd(),
+): ProductProfile {
   const name = str(raw.name) ?? "den";
   if (!SLUG.test(name))
     throw new Error(
@@ -91,7 +99,10 @@ export function profileFrom(raw: RawProduct = {}): ProductProfile {
     envPrefix,
     configFile: str(raw.config) ?? `config/${name}.yml`,
     manifestFiles: json === manifest ? [manifest] : [manifest, json],
-    stateDir: path.resolve(expandHome(str(raw.state_dir) ?? `~/.${name}`)),
+    stateDir: path.resolve(
+      baseDir,
+      expandHome(str(raw.state_dir) ?? `~/.${name}`),
+    ),
     servicesDir: str(raw.services_dir) ?? `.${name}-services`,
     workspacesDir: str(raw.workspaces_dir) ?? `${name}-workspaces`,
   };
@@ -106,7 +117,7 @@ export function readProfileFile(file: string): ProductProfile {
     if ((e as NodeJS.ErrnoException).code === "ENOENT") return profileFrom();
     throw new Error(`${file}: ${(e as Error).message}`);
   }
-  return profileFrom(raw?.product ?? {});
+  return profileFrom(raw?.product ?? {}, path.dirname(path.resolve(file)));
 }
 
 let cached: { key: string; profile: ProductProfile } | null = null;

package/src/shared/sessions/client.ts

@@ -129,14 +129,21 @@ export class HostClient extends EventEmitter {
       keptEnv?: { name: string; credentialShaped: boolean }[];
       /** Who asked, for that line. */
       actor?: string;
+      /**
+       * `--keep-env` names Den refuses to forward (SEC-1 §5: a person's
+       * credential): the host records the refusal and starts nothing.
+       */
+      refusedEnv?: string[];
     } = {},
   ): Promise<SessionInfo> {
     const r = await this.request("start", {
       spec,
       ...(opts.limit !== undefined ? { limit: opts.limit } : {}),
-      ...(opts.keptEnv?.length
-        ? { keptEnv: opts.keptEnv, actor: opts.actor ?? "unknown" }
+      ...(opts.keptEnv?.length || opts.refusedEnv?.length
+        ? { actor: opts.actor ?? "unknown" }
         : {}),
+      ...(opts.keptEnv?.length ? { keptEnv: opts.keptEnv } : {}),
+      ...(opts.refusedEnv?.length ? { refusedEnv: opts.refusedEnv } : {}),
     });
     return r.info as SessionInfo;
   }

package/src/shared/sessions/env.ts

@@ -10,14 +10,21 @@
  *   4. `launch`: the runtime's launch env (LaunchOutput.env)
  *   5. `extra`: the persona's or runtime's declared env (none can declare
  *      one yet)
- *   6. `den`: Den's own markers (DEN_AGENT for an agent)
+ *   6. `den`: Den's own markers (DEN_AGENT, and SEC-1c's DEN_ACTOR_TOKEN
+ *      for an agent: the only way an actor token reaches a session; one
+ *      from anywhere above is dropped first)
  *   7. then `scrub` removes every name it matches, whatever put it back:
  *      each runtime's scrubEnv (den-claude: CLAUDECODE, CLAUDE_CODE_*).
+ *   8. and always (SEC-1 §5): a person's credential, DEN_PERSON_TOKEN or
+ *      any value that is a person token or names web.secret
+ *      (actor-token.ts isPersonCredentialEnv), whatever put it there.
  *
  * The session backend knows none of this: it is handed the result. Nothing
  * here logs or returns a value other than the env itself.
  */
 
+import { ACTOR_TOKEN_ENV, isPersonCredentialEnv } from "../actor-token.js";
+
 export const DEFAULT_TERM = "xterm-256color";
 
 /** Set in an agent's env: `agent:<id>`, so Den's CLI run inside knows. */
@@ -72,8 +79,11 @@ export function buildSessionEnv(i: SessionEnvInput): Record<string, string> {
   for (const [k, v] of Object.entries(i.caller))
     if (v !== undefined && (inSessionBase(k) || named.has(k))) env[k] = v;
   if (!env.TERM) env.TERM = DEFAULT_TERM;
-  Object.assign(env, i.launch ?? {}, i.extra ?? {}, i.den ?? {});
+  Object.assign(env, i.launch ?? {}, i.extra ?? {});
+  delete env[ACTOR_TOKEN_ENV];
+  Object.assign(env, i.den ?? {});
   const scrub = i.scrub ?? [];
-  for (const k of Object.keys(env)) if (matchesScrub(k, scrub)) delete env[k];
+  for (const [k, v] of Object.entries(env))
+    if (matchesScrub(k, scrub) || isPersonCredentialEnv(k, v)) delete env[k];
   return env;
 }

package/src/shared/sessions/host.ts

@@ -126,6 +126,17 @@ function keptEnvAudit(v: unknown): string {
     .join(", ");
 }
 
+/** A start's refused `--keep-env` names, printable: "A, B", or "". */
+function refusedEnvAudit(v: unknown): string {
+  if (!Array.isArray(v)) return "";
+  return v
+    .filter(
+      (k): k is string =>
+        typeof k === "string" && /^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(k),
+    )
+    .join(", ");
+}
+
 function printableActor(v: unknown): string {
   return (
     String(v ?? "unknown")
@@ -477,6 +488,18 @@ export class SessionHost {
     const { name, cwd, argv, env } = spec;
     if (typeof name !== "string" || !name)
       throw new Refusal("bad-request", "start needs a name");
+    // SEC-1 §5: a --keep-env the caller refused (a person's credential) is
+    // audited here, names only, and nothing starts.
+    const refusedEnv = refusedEnvAudit(req.refusedEnv);
+    if (refusedEnv || Array.isArray(req.refusedEnv)) {
+      this.log(
+        `session ${printableActor(name)} refused: --keep-env ${refusedEnv || "?"} (a person's credential is never forwarded) · by ${printableActor(req.actor)}`,
+      );
+      throw new Refusal(
+        "bad-request",
+        `--keep-env ${refusedEnv || "?"}: a person's credential is never forwarded to a session`,
+      );
+    }
     if (
       !Array.isArray(argv) ||
       !argv.length ||

package/src/shared/web-secret.ts

@@ -0,0 +1,181 @@
+/**
+ * SEC-1a: the web server's secret and the person token derived from it.
+ *
+ * `web.secret` is 32 random bytes in the distribution's state dir, mode
+ * 0600 (the dir 0700 when Den creates it). Reading it is the proof that a
+ * caller is the OS user, the same proof as the session host's socket. It is
+ * never printed, never logged and never served.
+ *
+ * The person token is HMAC-SHA256(secret, "den-person-v1:" + os user),
+ * sent as `Authorization: Bearer den_pt_<b64url>`. The server recomputes it
+ * and compares in constant time; its actor is `person:<os user>`.
+ *
+ * SEC-1b's `web logout --all` rotates the secret (rotateWebSecret).
+ * SEC-1c's agent tokens (`den_at_…`) are actor-token.ts's: random, not
+ * derived from the secret.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { ACTOR_TOKEN_ENV, isActorTokenShape } from "./actor-token.js";
+import { getStateDir } from "./paths.js";
+import { AGENT_ACTOR_ENV } from "./sessions/env.js";
+
+export const WEB_SECRET_FILE = "web.secret";
+const SECRET_BYTES = 32;
+export const PERSON_TOKEN_PREFIX = "den_pt_";
+const PERSON_CONTEXT = "den-person-v1:";
+
+/** `<state dir>/web.secret`. */
+export function webSecretPath(stateDir: string = getStateDir()): string {
+  return path.join(stateDir, WEB_SECRET_FILE);
+}
+
+/** The OS user the process runs as (the person-token actor's name). */
+export function osUser(): string {
+  try {
+    return os.userInfo().username;
+  } catch {
+    return process.env.USER ?? process.env.LOGNAME ?? "unknown";
+  }
+}
+
+/** The secret, or null when it is missing, unreadable or malformed. */
+export function readWebSecret(stateDir: string = getStateDir()): Buffer | null {
+  try {
+    const b = fs.readFileSync(webSecretPath(stateDir));
+    return b.length === SECRET_BYTES ? b : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The secret, created when missing: the state dir 0700 when it is made
+ * here, the file 0600, written exclusively so two starts never race to two
+ * secrets. An existing file looser than 0600 is tightened.
+ */
+export function ensureWebSecret(stateDir: string = getStateDir()): Buffer {
+  const file = webSecretPath(stateDir);
+  const existing = readWebSecret(stateDir);
+  if (existing) {
+    tighten(file);
+    return existing;
+  }
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const fresh = randomBytes(SECRET_BYTES);
+  try {
+    // A malformed file (wrong length) is replaced; a missing one created.
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+    fs.writeFileSync(file, fresh, { mode: 0o600, flag: "wx" });
+  } catch (e) {
+    // Another process created it first: use theirs.
+    const won = readWebSecret(stateDir);
+    if (won) return won;
+    throw e;
+  }
+  tighten(file);
+  return fresh;
+}
+
+/**
+ * SEC-1b (`web logout --all`): a fresh secret in place of the old one,
+ * written to a temp file (0600) and renamed over it, so a reader sees one
+ * or the other, never half. Every person token and every browser session
+ * derived from the old one stops verifying; the CLI re-reads the file on
+ * each call, so it keeps working.
+ */
+export function rotateWebSecret(stateDir: string = getStateDir()): void {
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const file = webSecretPath(stateDir);
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(tmp, randomBytes(SECRET_BYTES), { mode: 0o600, flag: "wx" });
+  fs.renameSync(tmp, file);
+  tighten(file);
+}
+
+function tighten(file: string): void {
+  try {
+    if ((fs.statSync(file).mode & 0o077) !== 0) fs.chmodSync(file, 0o600);
+  } catch {
+    /* gone or not ours: the read already decided */
+  }
+}
+
+/** `den_pt_<b64url(HMAC-SHA256(secret, "den-person-v1:" + user))>`. */
+export function personToken(secret: Buffer, user: string = osUser()): string {
+  const mac = createHmac("sha256", secret)
+    .update(PERSON_CONTEXT + user)
+    .digest("base64url");
+  return PERSON_TOKEN_PREFIX + mac;
+}
+
+/**
+ * The actor a presented person token proves (`person:<user>`), or null.
+ * Constant time: both sides are hashed to one length before comparing.
+ */
+export function verifyPersonToken(
+  presented: string,
+  secret: Buffer,
+  user: string = osUser(),
+): `person:${string}` | null {
+  const expected = personToken(secret, user);
+  const a = createHmac("sha256", "den-cmp").update(presented).digest();
+  const b = createHmac("sha256", "den-cmp").update(expected).digest();
+  return timingSafeEqual(a, b) ? `person:${user}` : null;
+}
+
+/**
+ * The headers every CLI and stdio-MCP call to the web server carries:
+ *  - inside an agent's session (SEC-1c): its DEN_ACTOR_TOKEN, never the
+ *    person's; an agent (DEN_AGENT set) without one sends no credential
+ *    rather than fall back to the person token;
+ *  - otherwise the person token, or none when there is no secret yet (a
+ *    server that predates SEC-1, or none started).
+ */
+export function cliAuthHeaders(
+  stateDir: string = getStateDir(),
+  env: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const actorToken = env[ACTOR_TOKEN_ENV];
+  if (isActorTokenShape(actorToken))
+    return { Authorization: `Bearer ${actorToken}` };
+  if (env[AGENT_ACTOR_ENV] !== undefined || actorToken !== undefined) return {};
+  const secret = readWebSecret(stateDir);
+  return secret ? { Authorization: `Bearer ${personToken(secret)}` } : {};
+}
+
+/**
+ * The server's view of the secret: read once, re-read when the file changes
+ * (SEC-1b's rotation), created at start.
+ */
+export class WebSecretStore {
+  private cached: { key: string; secret: Buffer } | null = null;
+  constructor(private readonly stateDir: () => string = getStateDir) {}
+
+  /** Create the secret if needed (at server start). */
+  ensure(): void {
+    const secret = ensureWebSecret(this.stateDir());
+    this.cached = { key: this.key() ?? "", secret };
+  }
+
+  /** The current secret, or null when it is missing. */
+  current(): Buffer | null {
+    const key = this.key();
+    if (key === null) return null;
+    if (this.cached?.key === key) return this.cached.secret;
+    const secret = readWebSecret(this.stateDir());
+    this.cached = secret ? { key, secret } : null;
+    return secret;
+  }
+
+  private key(): string | null {
+    try {
+      const s = fs.statSync(webSecretPath(this.stateDir()));
+      return `${s.ino}:${s.size}:${s.mtimeMs}`;
+    } catch {
+      return null;
+    }
+  }
+}