@monster-orange/den 0.4.0 → 0.4.1

package/docs/distributions.md

@@ -563,16 +563,16 @@ product:
   # workspaces_dir: acme-workspaces
 ```
 
-| Field            | Default              | What it names                                                     |
-| ---------------- | -------------------- | ----------------------------------------------------------------- |
-| `name`           | `den`                | The product; `[a-z][a-z0-9-]*`. Everything below derives from it  |
-| `cli`            | `<name>`             | The command shown in help, hints and the web UI                   |
-| `env_prefix`     | `<NAME>` (`-` → `_`) | Env vars: `<PREFIX>_ROOT`, `<PREFIX>_HOME`, `<PREFIX>_INVOKE_CWD` |
-| `config`         | `config/<name>.yml`  | The org config, relative to the distribution root                 |
-| `manifest`       | `.<name>.yml`        | The manifest file a repo carries; the `.json` twin is also read   |
-| `state_dir`      | `~/.<name>`          | Per-user state: web server, daemons, logs, history                |
-| `services_dir`   | `.<name>-services`   | Managed clones, relative to the distribution root                 |
-| `workspaces_dir` | `<name>-workspaces`  | Workspace checkouts, relative to the distribution root            |
+| Field            | Default              | What it names                                                                                                        |
+| ---------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `name`           | `den`                | The product; `[a-z][a-z0-9-]*`. Everything below derives from it                                                     |
+| `cli`            | `<name>`             | The command shown in help, hints and the web UI                                                                      |
+| `env_prefix`     | `<NAME>` (`-` → `_`) | Env vars: `<PREFIX>_ROOT`, `<PREFIX>_HOME`, `<PREFIX>_INVOKE_CWD`                                                    |
+| `config`         | `config/<name>.yml`  | The org config, relative to the distribution root                                                                    |
+| `manifest`       | `.<name>.yml`        | The manifest file a repo carries; the `.json` twin is also read                                                      |
+| `state_dir`      | `~/.<name>`          | Per-user state: web server, daemons, logs, history (a relative path is relative to den.yml's directory, not the cwd) |
+| `services_dir`   | `.<name>-services`   | Managed clones, relative to the distribution root                                                                    |
+| `workspaces_dir` | `<name>-workspaces`  | Workspace checkouts, relative to the distribution root                                                               |
 
 Env vars, with `ACME` as the prefix:
 
@@ -1179,6 +1179,86 @@ Den's scripts run with the engine's tsx (`tsxCommand()`), never through `npx`
 or a path relative to the current directory. In Den's own checkout both roots
 are the same directory.
 
+## Signing in
+
+On localhost nothing asks you to sign in: every page, the agents and the
+terminal work as they are, and the lock (R8) is the only prompt (for
+privileged actions). Signing in is for when the server is reached beyond
+this machine: through the edge hostname, a LAN address, or a bind that
+isn't loopback (`DEN_BIND_HOST`).
+
+There is no password. Reading `web.secret` (32 random bytes, mode 0600 in
+the state dir, made at the first `web up`) proves you are this computer's
+user, and the CLI does that for you:
+
+```bash
+./bin/acme web open        # start if needed, and sign this browser in (a new tab)
+./bin/acme web login       # print a one-time sign-in link, for another browser
+./bin/acme web sessions    # the signed-in browsers: id, created, last seen, host, user agent
+./bin/acme web logout <id> # sign out one browser (an id prefix from `web sessions`)
+./bin/acme web logout      # sign out every browser
+./bin/acme web logout --all  # and rotate web.secret and revoke every agent's token
+```
+
+- **The link** is `http://localhost:<port>/auth?c=<code>`, with `&next=<path>`
+  for where to land (`web login --next /settings`). The code works once,
+  within 60 seconds, and only this server's secret makes one. It is printed
+  only on the one line you asked for (`web login`, or `web up` when it
+  couldn't open the browser), never logged. Through the edge or a LAN name,
+  the cookie belongs to that name: `web login --origin https://acme.acme.localhost`
+  (the signed-out page there shows the exact command).
+- **The cookie** (`den_session_<port>`) is HttpOnly, SameSite=Strict and
+  Path=/, and Secure when the request came over HTTPS through the edge. The
+  session lives server-side (`web-sessions.json`, 0600, in the state dir)
+  and never expires: it ends at sign-out, `web logout`, or `web logout
+--all`. The cookie asks the browser to keep it for 400 days, the most a
+  browser allows. The 0.4.1-dev `web.session.idle` and `web.session.max`
+  keys are ignored; the server logs a warning naming each one it finds.
+
+  `web sessions`' LAST SEEN is written at most once a minute (60 s), so it
+  equals CREATED right after a sign-in.
+
+- **What needs it.** On loopback, nothing: pages and read-only calls are
+  open, and changes (an agent's start or resume and the terminal included)
+  need only the page's own Origin and CSRF token, which the shell sends.
+  The Host allowlist, the Origin check and the CSRF token are what stop
+  another site or a rebinding DNS name. Through the edge, or from another
+  machine, every page and call needs a signed-in browser (or a bearer). A
+  page there shows "Sign in to use <name>" with the command to run; it
+  never asks for a secret. `/api` answers 401 `signin_required`.
+- **localhost is the canonical name.** A cookie set on `localhost` isn't
+  sent to `127.0.0.1`, so the links Den prints use `localhost`.
+- **Browsers.** Chromium, Firefox and Safari 16.4 or later: a sign-in link
+  needs the browser to send `Sec-Fetch-Site` or `Origin`.
+- **Scripts and the CLI** are unaffected: the CLI and the MCP server send
+  the person token (`web token --print` prints it for curl). After `web
+logout --all` the old token is refused; the CLI reads the new one.
+- **`web logout --all` is the "something leaked" button.** It signs out
+  every browser, rotates `web.secret` (every person token is void) and
+  revokes every agent's token: a running agent's next call gets 401
+  `token_revoked` ("restart or resume the agent to get a new one"). Plain
+  `web logout` (one browser, or every browser) leaves agent tokens alone.
+- **Another machine.** `DEN_BIND_HOST=0.0.0.0` (or any non-loopback
+  address) starts only with `web.allow_plain_http_remote: true` in
+  `config/local/user.yml`, since a session cookie would otherwise cross the
+  network in clear text. Having the edge in front is not enough: the
+  server's own port would still answer plain HTTP on every interface. Only
+  `config/local/user.yml` is read (a choice for that machine); the key in
+  the distribution config is ignored, and the server logs a warning naming
+  the file. With it, the machine's own addresses and host name are accepted
+  with the port, and every route there needs a session.
+- **The edge** reaches Den on loopback (macOS, through
+  `host.docker.internal`), so it needs no other bind. On Linux, where the
+  edge container reaches the host on the Docker bridge, the one other bind
+  allowed without the key is the bridge address (`172.16.0.0/12`, for
+  example `DEN_BIND_HOST=172.17.0.1`), and only with the edge configured.
+- **The edge hostname is believed only from the edge.** A request whose
+  `Host` is the edge hostname is accepted only from a peer the edge could
+  be (loopback, the Docker bridge range or Docker Desktop's VM network);
+  from any other address it is
+  421 `misdirected`, so a LAN client can't send the edge's name straight to
+  the server's port.
+
 ## Running the web UI as a service (macOS)
 
 Den ships a launchd installer that runs the web UI at login and restarts it if
@@ -1554,6 +1634,80 @@ server scoped to its workspace.
   exits non-zero, Den prints the exit code and its last lines (at most 10,
   secret-shaped values redacted) and exits 1.
 
+### On the Workspaces page
+
+The selected workspace's agents are listed under its repo table, one row
+per agent: its id and persona, runtime, state (`running`, `stopping`,
+`stopped`, `ended` or `exited (<code>)`), directory, and when its session
+started. The workspace header counts them ("2 agents").
+
+- **Stop** sends its session TERM, as `agents stop` does; the row reads
+  `stopping…` until the session has gone. **Resume** shows only when
+  `agents resume` would run: the runtime declares resume and the agent is
+  not running.
+- **+ Start agent** picks a persona (Den's pack, then
+  `agents.persona_packs`) and a runtime (the persona's own unless you pick
+  one; one that can't run here is listed, disabled), then Start.
+- The page and the CLI call the same operations and read the same agent
+  records, so an agent started in one is listed in the other. A workspace
+  lists its own agents only.
+- Start, Stop and Resume need the lock open (🔓, the same rule as a
+  service's Start), are capped by `agents.max_concurrent`, and are refused
+  for an agent (agents don't start agents from the page). Each one is in the
+  server log's activity, with you as its actor. The agent's environment is
+  the one below, built from the web server's environment.
+- **Open in Agents →** (the section header) opens the Agents tab for the
+  workspace, and **Open** on a row with a session opens its terminal there.
+
+The routes: `GET /api/workspaces/<ws>/agents`, `POST
+/api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, id? }`), `POST
+/api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, and `GET
+/api/personas` (personas and runtimes). Errors are the usual
+`{ ok: false, error, code, requestId }`: `locked` (423), `cap` (429),
+`conflict` (409, e.g. already running, or no resume), `not_found` (404),
+`exited_at_once` (502, with the session's last lines).
+
+### The Agents tab
+
+"Agents" in the rail (Develop, after Graph) is `/agents`: every session and
+agent of the workspaces in view, and their terminals in the browser.
+
+- **The list** is grouped by workspace and follows the scope bar (or the
+  page's `?ws=<ws>`, which "Open in Agents →" sets). Each row has its
+  state, persona (a `sessions start` session is labelled "session"),
+  runtime and directory, and "waiting" when it waits on you (once the
+  session host can tell, AG-6a; not yet). An agent whose
+  token `web logout --all` revoked says "token revoked": stop and resume
+  it, or start it again.
+- **A pane** is the session's terminal: it shows the scrollback, then the
+  live output, and your keys go to the session; its size follows the
+  pane. Click more rows to tile up to four (a fifth closes the oldest).
+  The URL holds the open panes (`/agents?open=<id>,<id>`), so a link, a
+  reload or Back reopens them.
+- **Close** (×) detaches, as leaving the page does: the session keeps
+  running, and opening it again replays what you missed. **Stop** (an
+  agent only) is `agents stop`, behind the lock. **+ Start agent** (or
+  `/agents?start=1`) starts one and opens its pane; under All it asks for
+  the workspace.
+- ⌘K lists each as "Agents › <ws> / <name>", and "Start agent…".
+- Several browsers and `<cli> sessions attach` can attach to one session
+  at once and each sees every byte; the terminal's size is the last
+  one's to change it.
+- Terminals need the optional PTY module (`<cli> doctor`); without it the
+  page lists what there is and says so.
+- **Who can open one.** The terminal is shell-grade: on localhost the
+  page's own Origin and CSRF token, beyond loopback a signed-in browser
+  (the list says "Sign in to open terminals" otherwise), and an agent's
+  token only its own session's. Each attach and detach is in the server
+  log's activity, with its actor.
+
+The routes: `GET /api/sessions` (`{ sessions, workspaces, host, backend,
+io }`) and the WebSocket `/api/sessions/<id>/io` (subprotocol `den.io`, the
+CSRF token as `den.csrf.<token>`): binary frames are output and input, a
+text frame `{"type":"resize","cols":c,"rows":r}` resizes, and the server
+sends `{"type":"session",…}` first and `{"type":"exit","exitCode":n}` when
+the session ends.
+
 ### An agent's environment
 
 An agent's environment starts empty and gets, in order:
@@ -1564,7 +1718,7 @@ An agent's environment starts empty and gets, in order:
 2. the variables its runtime names (`envPassthrough`; den-claude:
    `CLAUDE_CONFIG_DIR`);
 3. the runtime's launch env;
-4. `DEN_AGENT=agent:<id>`.
+4. `DEN_AGENT=agent:<id>` and `DEN_ACTOR_TOKEN` (below).
 
 Then every runtime's `scrubEnv` is removed (den-claude: `CLAUDECODE` and
 `CLAUDE_CODE_*`), whatever put it there. Nothing else of yours reaches it:
@@ -1585,10 +1739,46 @@ Without the PTY module it says the probe is unavailable; that is not a
 failure. Plain `doctor` never spawns anything; when agents are configured it
 adds a note to run `<cli> doctor --probe`.
 
+### An agent's token
+
+`agents start` (the CLI or the Workspaces page) mints a random `den_at_…`
+token for the agent and puts it in the session as `DEN_ACTOR_TOKEN`. Den
+keeps only its hash (`actor-tokens.json`, 0600, in the state dir) with the
+agent, its workspace, its grants and its session. Stop revokes it, and so
+does the session's end; resume mints a new one and the old one stops
+working. The `<cli>` and the MCP server Den starts for the agent send it, so
+the server audits their calls as the agent, from the token, never from a
+header (agent headers without the token are recorded as an unverified
+claim).
+
+An agent's token reaches only its own session's routes, and never a
+shell-grade route, `/api/web/*`, sign-in or sign-out, or the lock: it can't
+unlock, use the sudo password or start another agent (403
+`agent_forbidden`). A person's credential never reaches a session:
+`DEN_PERSON_TOKEN`, a person token's value and a path to `web.secret` are
+always removed, and `sessions start --keep-env` of one is refused and logged.
+An agent runs as your OS user, so it could still read `web.secret` itself;
+the token keeps what Den does on its behalf attributable and bounded.
+**The boundary is the server's token rules** (above), not a deny list.
+
+As a cooperative mitigation, den-claude passes Claude Code a settings file
+(`--settings`) whose `permissions.deny` lists `Read` of `<state
+dir>/web.secret` and `<state dir>/sessions/**`, and `Bash` rules in Claude
+Code's wildcard form for the path (`Bash(*<state dir>/web.secret*)`, and
+each of `cat`, `head`, `tail`, `less`, `more`, `xxd`, `od`, `strings`,
+`base64` and `cp` followed by it), spelled as an absolute path, under `~`
+and under `$HOME`, with a path that has spaces also backslash-escaped. A
+deny list can't name every way to read a file (another program, a script,
+a copy under another name), so it is a speed bump. **It binds cooperating
+agents only**: an agent that ignores its permission config, or reads the
+file some other way, can still read them. OS-user isolation (a separate
+user, a container, a sandbox) is not in 0.4.x. `web logout --all` revokes every agent's token
+(above, under Signing in).
+
 **What the scope does not do.** An agent's MCP scope binds cooperating
 agents only. A runtime with a shell can still run `<cli>` itself, outside
-the scoped MCP server, and reach other workspaces; WS-3a and SEC-1 close
-that later. And the user's own Claude Code settings and hooks
+the scoped MCP server, and reach other workspaces (with its own token, so
+it is audited as the agent); WS-3a closes that later. And the user's own Claude Code settings and hooks
 (`~/.claude/settings.json`, its hooks, a project's `.claude/`) load in a
 den-claude agent, as in any `claude` you start.
 
@@ -1634,7 +1824,7 @@ are errors naming the file or the key.
 
 - **`den-claude`** (the default) needs `claude` on PATH; doctor reads its
   version from the install, without running it. It runs `claude --session-id
-<id> --mcp-config <file> --strict-mcp-config [--model <m>]
+<id> --mcp-config <file> --strict-mcp-config --settings <file> [--model <m>]
 --append-system-prompt <role prompt>`, so Den's MCP server is the agent's
   only one, and resumes with `claude --resume <id>`. Permission prompts stay
   in the agent's terminal: it passes `--permission-mode default` unless the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {
@@ -62,6 +62,8 @@
     "@modelcontextprotocol/sdk": "1.32.1",
     "@playwright/test": "^1.61.1",
     "@slack/webhook": "^7.0.2",
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0",
     "ajv": "^8.12.0",
     "ajv-formats": "^2.1.1",
     "auth0": "^4.3.1",

package/src/shared/actor-token.ts

@@ -0,0 +1,275 @@
+/**
+ * SEC-1c (SEC-1 spec §5): an agent's actor token.
+ *
+ * `agents start` (and resume) mints `den_at_<43 b64url>`: 32 random bytes,
+ * handed to the agent's session as DEN_ACTOR_TOKEN and to nothing else.
+ * The state dir keeps only its sha256 (`actor-tokens.json`, 0600, the dir
+ * 0700), with what it proves:
+ *
+ *   { actor: "agent:<id>", workspace, grants, session: { name, id } }
+ *
+ * - One live token per agent: minting another (a resume, a restart)
+ *   revokes the old one, so it stops working at once.
+ * - Revoked when the agent stops (`agents stop`, the page's Stop), and when
+ *   its session ends: a token verifies only while the session it was minted
+ *   for is listed as running in the session host's own record
+ *   (`sessions/<id>.json`); an ended one's token is removed when presented.
+ * - It never derives from web.secret, so it proves nothing about the
+ *   person. `web logout --all` (the "something leaked" button, SEC-1
+ *   §6c.2) revokes every token as well as rotating the secret: each record
+ *   is kept, marked `revokedAt`, so a running agent's next call is told
+ *   `token_revoked` (restart or resume it) rather than a bare 401. Minting
+ *   the agent's next token, or its session's end, drops the record.
+ *
+ * Nothing here prints or logs a token.
+ */
+import { createHash, randomBytes } from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import { AGENT_ACTOR_RE, WORKSPACE_NAME_RE } from "./agent-actor.js";
+import { sessionPaths } from "./sessions/paths.js";
+
+export const ACTOR_TOKEN_PREFIX = "den_at_";
+/** The agent's session carries its token here (AG spec §5a-env). */
+export const ACTOR_TOKEN_ENV = "DEN_ACTOR_TOKEN";
+/** A person's token in an env: never forwarded to any session. */
+export const PERSON_TOKEN_ENV = "DEN_PERSON_TOKEN";
+export const ACTOR_TOKENS_FILE = "actor-tokens.json";
+
+const TOKEN_RE = /^den_at_[A-Za-z0-9_-]{43}$/;
+/** web-secret.ts's PERSON_TOKEN_PREFIX and WEB_SECRET_FILE (it imports this module). */
+const PERSON_PREFIX = "den_pt_";
+const SECRET_FILE = "web.secret";
+
+export interface ActorTokenRecord {
+  actor: `agent:${string}`;
+  workspace: string;
+  /** The agent's grants (agents.<id>.grants) when it was minted. */
+  grants: string[];
+  /** The session it was minted for: its name, and its id once started. */
+  session: { name: string; id?: string };
+  /** ISO 8601. */
+  createdAt: string;
+  /** ISO 8601: revoked by `web logout --all`. A revoked token never verifies. */
+  revokedAt?: string;
+}
+
+interface StoreFile {
+  v: 1;
+  /** sha256(token), hex → what it proves. */
+  tokens: Record<string, ActorTokenRecord>;
+}
+
+export function actorTokensPath(stateDir: string): string {
+  return path.join(stateDir, ACTOR_TOKENS_FILE);
+}
+
+/** The token's key in the store: sha256, hex. */
+export function actorTokenKey(token: string): string {
+  return createHash("sha256").update(token).digest("hex");
+}
+
+/** Shaped like an actor token (says nothing about whether it is live). */
+export function isActorTokenShape(v: string | undefined): v is string {
+  return typeof v === "string" && TOKEN_RE.test(v);
+}
+
+function load(stateDir: string): StoreFile {
+  try {
+    const raw = JSON.parse(
+      fs.readFileSync(actorTokensPath(stateDir), "utf-8"),
+    ) as Partial<StoreFile>;
+    const tokens =
+      raw.tokens && typeof raw.tokens === "object" && !Array.isArray(raw.tokens)
+        ? raw.tokens
+        : {};
+    return { v: 1, tokens };
+  } catch {
+    return { v: 1, tokens: {} };
+  }
+}
+
+function save(stateDir: string, data: StoreFile): void {
+  fs.mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+  const file = actorTokensPath(stateDir);
+  const tmp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(tmp, 0o600);
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * A fresh token for agent `agentId`, its hash recorded, every older token
+ * of the same agent revoked. The token itself is returned once and never
+ * stored.
+ */
+export function mintActorToken(
+  stateDir: string,
+  o: {
+    agentId: string;
+    workspace: string;
+    grants?: readonly string[];
+    sessionName: string;
+  },
+): { token: string; key: string } {
+  const actor = `agent:${o.agentId}` as const;
+  if (!AGENT_ACTOR_RE.test(actor))
+    throw new Error(`"${o.agentId}" is not an agent id`);
+  if (!WORKSPACE_NAME_RE.test(o.workspace))
+    throw new Error(`"${o.workspace}" is not a workspace name`);
+  const token = ACTOR_TOKEN_PREFIX + randomBytes(32).toString("base64url");
+  const key = actorTokenKey(token);
+  const data = load(stateDir);
+  for (const [k, r] of Object.entries(data.tokens))
+    if (r.actor === actor) delete data.tokens[k];
+  data.tokens[key] = {
+    actor,
+    workspace: o.workspace,
+    grants: (o.grants ?? []).filter((g) => WORKSPACE_NAME_RE.test(g)),
+    session: { name: o.sessionName },
+    createdAt: new Date().toISOString(),
+  };
+  save(stateDir, data);
+  return { token, key };
+}
+
+/** Bind a minted token to the session id the host gave its session. */
+export function bindActorSession(
+  stateDir: string,
+  key: string,
+  sessionId: string,
+): void {
+  const data = load(stateDir);
+  const rec = data.tokens[key];
+  if (!rec) return;
+  rec.session = { ...rec.session, id: sessionId };
+  save(stateDir, data);
+}
+
+/** Revoke one token (by its key). */
+export function revokeActorToken(stateDir: string, key: string): boolean {
+  const data = load(stateDir);
+  if (!data.tokens[key]) return false;
+  delete data.tokens[key];
+  save(stateDir, data);
+  return true;
+}
+
+/** Revoke every token of agent `agentId`; how many there were. */
+export function revokeAgentTokens(stateDir: string, agentId: string): number {
+  const data = load(stateDir);
+  const actor = `agent:${agentId}`;
+  let n = 0;
+  for (const [k, r] of Object.entries(data.tokens))
+    if (r.actor === actor) {
+      delete data.tokens[k];
+      n++;
+    }
+  if (n) save(stateDir, data);
+  return n;
+}
+
+/**
+ * Revoke every agent's token (`web logout --all`, SEC-1 §6c.2): each record
+ * is marked revoked, so its agent learns why. How many were live.
+ */
+export function revokeAllActorTokens(stateDir: string): number {
+  const data = load(stateDir);
+  const now = new Date().toISOString();
+  let n = 0;
+  for (const r of Object.values(data.tokens))
+    if (!r.revokedAt) {
+      r.revokedAt = now;
+      n++;
+    }
+  if (n) save(stateDir, data);
+  return n;
+}
+
+/**
+ * The agents whose token `web logout --all` revoked and whose record is
+ * still kept (their session still runs): the Agents tab marks them, so a
+ * person knows to restart or resume them (AG-4a-term). Ids only.
+ */
+export function revokedAgentIds(stateDir: string): Set<string> {
+  const out = new Set<string>();
+  for (const r of Object.values(load(stateDir).tokens))
+    if (r.revokedAt && AGENT_ACTOR_RE.test(r.actor))
+      out.add(r.actor.slice("agent:".length));
+  return out;
+}
+
+/** What a presented token was minted as, live or not; null when unknown. */
+export function lookupActorToken(
+  stateDir: string,
+  token: string,
+): ActorTokenRecord | null {
+  if (!isActorTokenShape(token)) return null;
+  return load(stateDir).tokens[actorTokenKey(token)] ?? null;
+}
+
+/** Whether the session host lists session `id` as running (its own record). */
+export function sessionRunning(stateDir: string, id: string): boolean {
+  if (!/^[A-Za-z0-9_-]{1,128}$/.test(id)) return false;
+  try {
+    const rec = JSON.parse(
+      fs.readFileSync(
+        path.join(sessionPaths(stateDir).dir, `${id}.json`),
+        "utf-8",
+      ),
+    ) as { exited?: unknown };
+    return rec.exited !== true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What a presented token proves: its record; `"revoked"` when `web logout
+ * --all` revoked it and its session still runs (the agent is told to
+ * restart or resume); or null: unknown, not yet bound to a session, or its
+ * session has ended (then its record is removed here).
+ */
+export function checkActorToken(
+  stateDir: string,
+  token: string,
+): ActorTokenRecord | "revoked" | null {
+  const rec = lookupActorToken(stateDir, token);
+  if (!rec?.session.id) return null;
+  if (!sessionRunning(stateDir, rec.session.id)) {
+    try {
+      revokeActorToken(stateDir, actorTokenKey(token));
+    } catch {
+      /* a read-only state dir: still refused */
+    }
+    return null;
+  }
+  return rec.revokedAt ? "revoked" : rec;
+}
+
+/** The record a presented token proves, or null (checkActorToken, revoked or not). */
+export function verifyActorToken(
+  stateDir: string,
+  token: string,
+): ActorTokenRecord | null {
+  const r = checkActorToken(stateDir, token);
+  return r === "revoked" ? null : r;
+}
+
+/**
+ * A person's credential in an env (SEC-1 §5): DEN_PERSON_TOKEN, a value
+ * shaped like a person token, or a value that names a web.secret file.
+ * No session Den starts ever gets one, and `--keep-env` can't forward one.
+ */
+export function isPersonCredentialEnv(
+  name: string,
+  value: string | undefined,
+): boolean {
+  if (name === PERSON_TOKEN_ENV) return true;
+  if (value === undefined) return false;
+  const v = value.trim();
+  if (v.includes(PERSON_PREFIX)) return true;
+  return v
+    .split(/[:;,\s]+/)
+    .some((part) => path.basename(part.replace(/[/\\]+$/, "")) === SECRET_FILE);
+}

package/src/shared/agent-actor.ts

@@ -43,6 +43,11 @@ export interface AgentInfo {
 
 export interface AgentActor extends AgentInfo {
   kind: "agent";
+  /**
+   * SEC-1c: set when this came from headers the caller set, not from an
+   * agent's actor token. The audit keeps it as a claim, never as the actor.
+   */
+  unverified?: true;
 }
 
 /** null: a person in the web UI (no agent headers). */
@@ -75,7 +80,11 @@ export function agentAuditHeaders(info: AgentInfo): Record<string, string> {
   };
 }
 
-/** The actor an incoming request names, or null for a person in the UI. */
+/**
+ * The actor an incoming request's headers claim, or null. SEC-1c: a claim,
+ * never the audit actor; the server's auditActorOf (request-guard.ts)
+ * takes the actor from the credential and keeps this as unverified.
+ */
 export function actorFromHeaders(
   headers: IncomingHttpHeaders | Record<string, string | undefined>,
 ): Actor {
@@ -107,6 +116,7 @@ export function actorLabel(actor: AgentActor): string {
   const ws = actor.workspace ? `workspace ${actor.workspace}, ` : "";
   return (
     `${who} ${actor.client} ${actor.clientVersion} ` +
-    `(${ws}mcp pid ${actor.mcpPid ?? "?"}, session ${actor.session || "?"})`
+    `(${ws}mcp pid ${actor.mcpPid ?? "?"}, session ${actor.session || "?"})` +
+    (actor.unverified ? " (unverified)" : "")
   );
 }