@monster-orange/den 0.4.0 → 0.4.2

package/src/ui/mcp/server.ts

@@ -16,7 +16,8 @@ import {
   type ResolvedMcpConfig,
 } from "../../shared/den-config.js";
 import { readWebPort } from "../../shared/edge/config.js";
-import { engineVersion } from "../../shared/paths.js";
+import { engineVersion, getStateDir } from "../../shared/paths.js";
+import { ACTOR_TOKEN_ENV, lookupActorToken } from "../../shared/actor-token.js";
 import { product } from "../../shared/product.js";
 import { DEFAULT_PORT } from "../../shared/constants.js";
 import { createDenApi, type DenApi } from "./api.js";
@@ -259,6 +260,63 @@ export async function runOneShot(
   return r.isError ? 1 : 0;
 }
 
+/**
+ * SEC-1c: the MCP server Den starts for an agent carries the agent's actor
+ * token (DEN_ACTOR_TOKEN, inherited from the agent's session) as the
+ * credential of every call (cliAuthHeaders), and the web server records
+ * that token's agent as the actor. Why it must not start, or null: a token
+ * minted for another agent than `--actor`, or one this distribution never
+ * minted. With no token it runs as before (a person's own scoped server:
+ * the person token, its --actor an unverified claim).
+ */
+export function actorTokenRefusal(
+  scope: McpScope | null,
+  env: NodeJS.ProcessEnv,
+  stateDir: string,
+): string | null {
+  const token = env[ACTOR_TOKEN_ENV];
+  if (token === undefined) return null;
+  const rec = lookupActorToken(stateDir, token);
+  if (!rec)
+    return `${ACTOR_TOKEN_ENV} is not a live actor token of this distribution (stopped, resumed, or never minted here)`;
+  if (rec.revokedAt)
+    return `${ACTOR_TOKEN_ENV} was revoked (\`web logout --all\`): restart or resume the agent to get a new one`;
+  if (scope && scope.actor !== rec.actor)
+    return `--actor ${scope.actor} does not match ${ACTOR_TOKEN_ENV}, which is ${rec.actor}'s`;
+  if (scope && scope.workspace !== rec.workspace)
+    return `--workspace ${scope.workspace} does not match ${ACTOR_TOKEN_ENV}, which is workspace ${rec.workspace}'s`;
+  return null;
+}
+
+/**
+ * The line the stdio server prints at start (stderr). Its actor reads
+ * `as agent:<id>` only when DEN_ACTOR_TOKEN verified it (actorTokenRefusal
+ * passed with a token); without one the actor is a claim, and says so.
+ */
+export function mcpStartupLine(o: {
+  cli: string;
+  tools: number;
+  actions: readonly string[];
+  baseUrl: string;
+  scope: McpScope | null;
+  /** A DEN_ACTOR_TOKEN that matched the scope's actor and workspace. */
+  verified: boolean;
+}): string {
+  const { scope } = o;
+  const actor = scope
+    ? o.verified
+      ? scope.actor
+      : `${scope.actor} (unverified: no ${ACTOR_TOKEN_ENV})`
+    : "";
+  return (
+    `${o.cli} mcp: ${plural(o.tools, "tool")} ` +
+    `(${o.actions.length ? `actions: ${o.actions.join(", ")}` : "read only"}) → ${o.baseUrl}` +
+    (scope ? ` · scoped to ${scope.workspace} as ${actor}` : "") +
+    (scope?.grants?.length ? ` · grants: ${scope.grants.join(", ")}` : "") +
+    "\n"
+  );
+}
+
 /** Run `<cli> mcp` until stdin closes (or one `--call` / `--list`). */
 export async function runMcp(rawArgv: string[]): Promise<void> {
   const cli = product().cli;
@@ -279,6 +337,12 @@ export async function runMcp(rawArgv: string[]): Promise<void> {
     process.exitCode = 2;
     return;
   }
+  const refusedToken = actorTokenRefusal(scope, process.env, getStateDir());
+  if (refusedToken) {
+    process.stderr.write(`${cli} mcp: ${refusedToken}\n`);
+    process.exitCode = 2;
+    return;
+  }
   if (scope?.grants?.length) {
     // A grant is config: a flag alone never widens a scope.
     let refused: string | null;
@@ -336,10 +400,14 @@ export async function runMcp(rawArgv: string[]): Promise<void> {
   });
   await server.connect(new StdioServerTransport());
   process.stderr.write(
-    `${cli} mcp: ${plural(toolsFor(cfg).length, "tool")} ` +
-      `(${cfg.actions.length ? `actions: ${cfg.actions.join(", ")}` : "read only"}) → ${baseUrl}` +
-      (scope ? ` · scoped to ${scope.workspace} as ${scope.actor}` : "") +
-      (scope?.grants?.length ? ` · grants: ${scope.grants.join(", ")}` : "") +
-      "\n",
+    mcpStartupLine({
+      cli,
+      tools: toolsFor(cfg).length,
+      actions: cfg.actions,
+      baseUrl,
+      scope,
+      // actorTokenRefusal passed: a token, if any, is this scope's.
+      verified: process.env[ACTOR_TOKEN_ENV] !== undefined,
+    }),
   );
 }

package/src/ui/server/agent-routes.ts

@@ -0,0 +1,324 @@
+/**
+ * The Workspaces page's Agents section (AG-4a, AG spec §5c), its routes:
+ *
+ *   GET  /api/personas                            personas and runtimes
+ *   GET  /api/workspaces/<ws>/agents              the workspace's agents
+ *   POST /api/workspaces/<ws>/agents              start { persona, runtime?, model?, id? }
+ *   POST /api/workspaces/<ws>/agents/<id>/stop
+ *   POST /api/workspaces/<ws>/agents/<id>/resume
+ *
+ * Each calls the CLI's own operation (cli/agent-ops.ts): neither the page
+ * nor the CLI keeps state of its own, so an agent started here is the one
+ * `<cli> agents list -w <ws>` shows, and the other way round. A workspace
+ * lists its own agents only: another workspace's id is no agent here.
+ *
+ * Guards on Start, Stop and Resume, as on a service action:
+ *   - the lock (R8): locked, the action is refused (423 locked); the page
+ *     opens the lock popover first, as Local Dev's service actions do;
+ *   - a person only: an agent (its actor token, SEC-1c) can't start or
+ *     stop agents from the page (403; agents use MCP agent_spawn, §5,
+ *     under its own guards);
+ *   - agents.max_concurrent (the host's cap on agents, never plain
+ *     sessions: 429 cap).
+ * The env is the CLI's (§5a-env): the allowlist and the runtime's, built
+ * from this server's environment, never all of it. Every action, refused
+ * or done, is audited (recordAction) with the person as its actor.
+ *
+ * There is no terminal here: the Agents tab's io (session-routes.ts) is
+ * the only route that writes to a session or streams its output.
+ */
+import * as http from "http";
+import { getReposRoot } from "../../shared/den-config.js";
+import {
+  readWorkspacesFile,
+  resolveWorkspaceDir,
+} from "../../shared/environment-manager/workspaces.js";
+import { getStateDir } from "../../shared/paths.js";
+import { HostError } from "../../shared/sessions/client.js";
+import {
+  AgentError,
+  agentRecord,
+  listAgents,
+  listPersonas,
+  listRuntimes,
+  NOT_IN_WORKSPACE,
+  resolveAgentsDeps,
+  resumeAgent,
+  startAgent,
+  stopAgent,
+  type AgentsDeps,
+  type AgentsResolved,
+  type Started,
+} from "../cli/agent-ops.js";
+import { recordAction } from "./audit.js";
+import { auditActorOf, principalOf } from "./request-guard.js";
+import { readBody, sendJson } from "./http-helpers.js";
+import { hasPasswordlessSudo, hasSudoPassword } from "./sudo-store.js";
+import type { Actor } from "../../shared/agent-actor.js";
+
+export interface AgentRouteDeps {
+  /** The operations' deps (tests: an in-process host, a temp state dir). */
+  agents?: AgentsDeps;
+  /** R8: whether the lock is open (the lock chip's own status). */
+  unlocked?: () => boolean;
+}
+
+const AGENTS_PATH =
+  /^\/api\/workspaces\/([^/]+)\/agents(?:\/([^/]+)\/(stop|resume))?$/;
+/** A start's body is a few short names. */
+const MAX_BODY = 4096;
+
+/** Never a TTY: a web start's terminal is 80×24. */
+const NO_TTY = { isTTY: false } as NodeJS.WriteStream;
+
+function webDeps(over: AgentsDeps = {}): AgentsResolved {
+  return resolveAgentsDeps({
+    stateDir: () => getStateDir(),
+    workspaceExists: (ws) => Boolean(readWorkspacesFile().workspaces[ws]),
+    workspaceDir: (ws) => {
+      const cfg = readWorkspacesFile().workspaces[ws];
+      if (!cfg) throw new AgentError(`workspace "${ws}" does not exist`);
+      return resolveWorkspaceDir(ws, cfg, getReposRoot());
+    },
+    stdout: NO_TTY,
+    out: () => undefined,
+    err: () => undefined,
+    ...over,
+  });
+}
+
+/** The lock chip's state: an admin password set, or sudo without one. */
+function defaultUnlocked(): boolean {
+  return hasSudoPassword() || hasPasswordlessSudo();
+}
+
+/** An AgentError (or the host's refusal) as the R26 answer. */
+function sendError(res: http.ServerResponse, e: unknown, ws?: string): void {
+  if (e instanceof AgentError) {
+    // From another workspace, an agent isn't there at all: no name of it.
+    const error =
+      e.code === NOT_IN_WORKSPACE && ws
+        ? `no agent here in workspace ${ws}`
+        : e.message;
+    sendJson(
+      res,
+      {
+        ok: false,
+        error,
+        ...(e.code && e.code !== NOT_IN_WORKSPACE ? { code: e.code } : {}),
+        ...(e.hints.length ? { hints: e.hints } : {}),
+      },
+      e.status,
+    );
+    return;
+  }
+  if (e instanceof HostError) {
+    sendJson(
+      res,
+      { ok: false, error: e.message, code: "session_host" },
+      e.code === "cap" ? 429 : 503,
+    );
+    return;
+  }
+  throw e;
+}
+
+/** A started or resumed agent's answer: its record, or its early exit. */
+function sendStarted(res: http.ServerResponse, s: Started): void {
+  if (s.early) {
+    const code =
+      s.early.exitCode === undefined ? "" : ` (exit ${s.early.exitCode})`;
+    sendJson(
+      res,
+      {
+        ok: false,
+        error: `agent ${s.rec.id} exited at once${code}`,
+        code: "exited_at_once",
+        tail: s.early.tail,
+        session: s.early.sessionName,
+        ...(s.warnings.length ? { warnings: s.warnings } : {}),
+      },
+      502,
+    );
+    return;
+  }
+  sendJson(res, {
+    ok: true,
+    agent: {
+      id: s.rec.id,
+      persona: s.rec.persona,
+      runtime: s.rec.runtime,
+      workspace: s.rec.workspace,
+      cwd: s.rec.cwd,
+      session: s.rec.sessionName,
+      // The host's id: the Agents tab opens its pane by it (?open=<id>).
+      sessionId: s.info.ref.id,
+      startedAt: s.rec.startedAt,
+    },
+    ...(s.warnings.length ? { warnings: s.warnings } : {}),
+  });
+}
+
+/** What a POST's body names: a few optional strings. */
+async function startBody(
+  req: http.IncomingMessage,
+): Promise<Record<string, string | undefined>> {
+  const raw = await readBody(req).catch(() => "");
+  if (raw.length > MAX_BODY)
+    throw new AgentError("request too large", { status: 413, usage: true });
+  let v: unknown;
+  try {
+    v = JSON.parse(raw || "{}");
+  } catch {
+    throw new AgentError("invalid JSON", { usage: true });
+  }
+  if (!v || typeof v !== "object" || Array.isArray(v))
+    throw new AgentError("the body must be a JSON object", { usage: true });
+  const out: Record<string, string | undefined> = {};
+  for (const k of ["persona", "runtime", "model", "id"]) {
+    const x = (v as Record<string, unknown>)[k];
+    if (x === undefined || x === null || x === "") continue;
+    if (typeof x !== "string")
+      throw new AgentError(`${k} must be a string`, { usage: true });
+    out[k] = x;
+  }
+  return out;
+}
+
+/**
+ * Handles the routes above; false when `pathname` is none of them. Every
+ * answer is JSON; an error is R26's { ok: false, error, code, requestId }
+ * (the server's jsonApiErrors adds the requestId).
+ */
+export async function handleAgentRoutes(
+  req: http.IncomingMessage,
+  res: http.ServerResponse,
+  pathname: string,
+  deps: AgentRouteDeps = {},
+): Promise<boolean> {
+  const m = AGENTS_PATH.exec(pathname);
+  if (pathname !== "/api/personas" && !m) return false;
+  const method = req.method ?? "GET";
+  const d = webDeps(deps.agents);
+
+  if (!m) {
+    if (method !== "GET") return methodNotAllowed(res, "GET");
+    try {
+      sendJson(res, { personas: listPersonas(d), runtimes: listRuntimes(d) });
+    } catch (e) {
+      sendError(res, e);
+    }
+    return true;
+  }
+
+  let ws: string;
+  try {
+    ws = decodeURIComponent(m[1]);
+  } catch {
+    sendJson(res, { ok: false, error: "not a workspace name" }, 400);
+    return true;
+  }
+  const id = m[2] === undefined ? undefined : safeDecode(m[2]);
+  const action = m[3] as "stop" | "resume" | undefined;
+
+  if (!action && method === "GET") {
+    try {
+      if (!d.workspaceExists(ws))
+        throw new AgentError(`workspace "${ws}" does not exist`, {
+          status: 404,
+        });
+      sendJson(res, {
+        workspace: ws,
+        // Asking never starts a session host: with none, nothing runs.
+        agents: await listAgents(d, ws, { startHost: false }),
+        maxConcurrent: d.maxConcurrent(),
+      });
+    } catch (e) {
+      sendError(res, e, ws);
+    }
+    return true;
+  }
+  if (method !== "POST")
+    return methodNotAllowed(res, action ? "POST" : "GET, POST");
+
+  // From the credential (SEC-1c): an agent's actor token, never a header.
+  const actor = auditActorOf(req);
+  const verb = action ?? "start";
+  const audit = (detail: string, reason?: string) =>
+    recordAction(
+      actor,
+      {
+        verb: "agents",
+        detail,
+        ...(reason ? { outcome: "refused" as const, reason } : {}),
+      },
+      principalOf(req),
+    );
+  let what = `${verb} ${id ?? "?"} in ${ws}`;
+  try {
+    // Another workspace's agent is no agent here: a 404 that doesn't name
+    // it, before the lock (a locked request says the same).
+    if (id !== undefined) agentRecord(d, id, ws);
+    guard(actor, deps.unlocked ?? defaultUnlocked);
+    if (verb === "start") {
+      const body = await startBody(req);
+      if (!body.persona)
+        throw new AgentError("persona is required", { usage: true });
+      what = `start ${body.id ?? body.persona} in ${ws}`;
+      const s = await startAgent(d, {
+        workspace: ws,
+        persona: body.persona,
+        runtime: body.runtime,
+        model: body.model,
+        id: body.id,
+      });
+      what = `start ${s.rec.id} (${s.rec.persona}, ${s.rec.runtime}) in ${ws}`;
+      audit(what, s.early ? "exited at once" : undefined);
+      sendStarted(res, s);
+    } else if (verb === "stop") {
+      const s = await stopAgent(d, id!, ws);
+      audit(what);
+      sendJson(res, { ok: true, agent: s.rec.id, wasRunning: !!s.session });
+    } else {
+      const s = await resumeAgent(d, id!, ws);
+      audit(what);
+      sendStarted(res, s);
+    }
+  } catch (e) {
+    audit(what, e instanceof Error ? e.message : String(e));
+    sendError(res, e, ws);
+  }
+  return true;
+}
+
+/**
+ * R8 and the actor: a person, with the lock open. An agent is one its actor
+ * token proves (the request checks already refuse its start and resume);
+ * an x-den-actor header alone is an unverified claim, not an agent.
+ */
+function guard(actor: Actor, unlocked: () => boolean): void {
+  if (actor && !actor.unverified)
+    throw new AgentError(
+      "an agent can't start, stop or resume agents from the page; agents use MCP agent_spawn",
+      { status: 403 },
+    );
+  if (!unlocked())
+    throw new AgentError("Unlock first: agent actions need the lock open", {
+      status: 423,
+      code: "locked",
+    });
+}
+
+function safeDecode(s: string): string {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+
+function methodNotAllowed(res: http.ServerResponse, allow: string): true {
+  res.setHeader("Allow", allow);
+  sendJson(res, { ok: false, error: "method not allowed" }, 405);
+  return true;
+}

package/src/ui/server/audit.ts

@@ -17,7 +17,28 @@ export { actorFromHeaders } from "../../shared/agent-actor.js";
 
 export interface AuditEntry {
   ts: string;
+  /** "agent" only for an agent's actor token (SEC-1c); a claim never is. */
   actor: "agent" | "user";
+  /**
+   * Who the request's credential proves it is: `person:<os user>` for the
+   * person token or a signed-in browser, `agent:<id>` for an actor token
+   * (SEC-1c). From the credential only, never from a header the caller
+   * sets; absent for a call without one.
+   */
+  principal?: string;
+  /**
+   * SEC-1c: what the caller's x-den-actor headers claimed, when no actor
+   * token proved it (unverified is then set). A label, never the actor.
+   */
+  claimed?: {
+    agent?: string;
+    workspace?: string;
+    client: string;
+    clientVersion: string;
+    mcpPid: number | null;
+    session: string;
+  };
+  unverified?: true;
   client?: string;
   clientVersion?: string;
   mcpPid?: number | null;
@@ -71,18 +92,36 @@ export function recordAction(
     addresses?: string[];
     targetWorkspace?: string;
   },
+  /** The credential's actor (request-guard principalOf). */
+  principal?: string,
 ): AuditEntry {
+  const claim = actor?.unverified ? actor : null;
+  const verified = actor && !actor.unverified ? actor : null;
   const entry: AuditEntry = {
     ts: new Date().toISOString(),
-    actor: actor ? "agent" : "user",
-    ...(actor
+    actor: verified ? "agent" : "user",
+    ...(principal ? { principal } : {}),
+    ...(claim
       ? {
-          client: actor.client,
-          clientVersion: actor.clientVersion,
-          mcpPid: actor.mcpPid,
-          session: actor.session,
-          ...(actor.agent ? { agent: actor.agent } : {}),
-          ...(actor.workspace ? { workspace: actor.workspace } : {}),
+          claimed: {
+            ...(claim.agent ? { agent: claim.agent } : {}),
+            ...(claim.workspace ? { workspace: claim.workspace } : {}),
+            client: claim.client,
+            clientVersion: claim.clientVersion,
+            mcpPid: claim.mcpPid,
+            session: claim.session,
+          },
+          unverified: true as const,
+        }
+      : {}),
+    ...(verified
+      ? {
+          client: verified.client,
+          clientVersion: verified.clientVersion,
+          mcpPid: verified.mcpPid,
+          session: verified.session,
+          ...(verified.agent ? { agent: verified.agent } : {}),
+          ...(verified.workspace ? { workspace: verified.workspace } : {}),
         }
       : {}),
     ...(action.targetWorkspace
@@ -105,7 +144,8 @@ export function recordAction(
       ? ""
       : action.detail;
   sink?.(
-    `${mark} ${action.verb}${what ? ` ${what}` : ""}${why}${actorSuffix(actor)}`,
+    `${mark} ${action.verb}${what ? ` ${what}` : ""}${why}${actorSuffix(actor)}` +
+      (principal && !verified ? ` · as ${principal}` : ""),
     actor,
   );
   return entry;
@@ -177,6 +217,7 @@ export function recordAgentRefusal(
     targets?: unknown;
     reason?: unknown;
   },
+  principal?: string,
 ): AuditEntry {
   const tool = clean(report.tool, 64).replace(/[^A-Za-z0-9_]/g, "") || "tool";
   const repo = typeof report.repo === "string" ? report.repo : "";
@@ -186,22 +227,30 @@ export function recordAgentRefusal(
   if (lifecycle && SAFE_PART.test(repo)) {
     const address =
       service && SAFE_PART.test(service) ? `${repo}/${service}` : repo;
-    return recordAction(actor, {
-      verb: "exec",
-      detail: `${address} ${lifecycle[1]} (local)`,
-      outcome: "refused",
-      reason,
-    });
+    return recordAction(
+      actor,
+      {
+        verb: "exec",
+        detail: `${address} ${lifecycle[1]} (local)`,
+        outcome: "refused",
+        reason,
+      },
+      principal,
+    );
   }
   // Any other tool: the refusal is the detail, under every service or repo
   // the call named (all of a logs_search's targets, in one entry).
-  return recordAction(actor, {
-    verb: tool,
-    detail: reason,
-    outcome: "refused",
-    reason,
-    addresses: refusedAddresses(report),
-  });
+  return recordAction(
+    actor,
+    {
+      verb: tool,
+      detail: reason,
+      outcome: "refused",
+      reason,
+      addresses: refusedAddresses(report),
+    },
+    principal,
+  );
 }
 
 /**
@@ -215,6 +264,7 @@ export function recordAgentRefusal(
 export function recordCrossWorkspace(
   actor: Actor,
   report: { tool?: unknown; crossWorkspace?: unknown },
+  principal?: string,
 ): AuditEntry | null {
   if (!actor?.agent || !actor.workspace) return null;
   const target =
@@ -222,11 +272,15 @@ export function recordCrossWorkspace(
   if (!WORKSPACE_NAME_RE.test(target) || target === actor.workspace)
     return null;
   const tool = clean(report.tool, 64).replace(/[^A-Za-z0-9_]/g, "") || "tool";
-  return recordAction(actor, {
-    verb: tool,
-    detail: `in workspace ${target}, under a grant to ${actor.agent} of workspace ${actor.workspace}`,
-    targetWorkspace: target,
-  });
+  return recordAction(
+    actor,
+    {
+      verb: tool,
+      detail: `in workspace ${target}, under a grant to ${actor.agent} of workspace ${actor.workspace}`,
+      targetWorkspace: target,
+    },
+    principal,
+  );
 }
 
 /**

package/src/ui/server/http-errors.ts

@@ -262,11 +262,16 @@ export function pluginForPath(
 
 /** What error.html is told: everything error-page.js draws from. */
 export interface ErrorPageData {
-  /** 422: the config fails validation (a ConfigError). */
-  status: 404 | 422 | 500;
+  /**
+   * 422: the config fails validation (a ConfigError). 401, 403, 421: the
+   * request checks refused it (SEC-1a): `message` says why, `code` names it.
+   */
+  status: 401 | 403 | 404 | 421 | 422 | 500;
+  /** 401, 403, 421: the refusal's code (misdirected, origin_rejected, …). */
+  code?: string;
   /** 404 and 422: the path asked for (no query). */
   path?: string;
-  /** 422: the ConfigError's message (it names config keys, never values). */
+  /** 422: the ConfigError's message (it names config keys, never values); 401/403/421: the refusal's. */
   message?: string;
   /** 422: each problem: its file, key path and message (0.3.0-dev.40). */
   issues?: Array<{ file: string; key: string; message: string }>;
@@ -281,6 +286,19 @@ export interface ErrorPageData {
   plugin?: PluginRoute | null;
   /** MD-2: the restart message, when the engine on disk is newer. */
   engine?: { loaded: string | null; onDisk: string | null; message: string };
+  /**
+   * 401 signin_required (SEC-1b): the signed-out page. `scope` terminal
+   * (shell-grade on loopback) or den (beyond loopback); `cmd` the command
+   * that prints a link; `localhost` the same path there (on 127.0.0.1 or
+   * [::1]); `expired` for a login link that expired or was used.
+   */
+  signin?: {
+    scope: "terminal" | "agents" | "den";
+    name: string;
+    cmd: string;
+    localhost?: string;
+    expired?: boolean;
+  };
 }
 
 /**