@monster-orange/den 0.3.0 → 0.4.1

package/src/ui/mcp/scope.ts

@@ -4,11 +4,18 @@
  * filters lists to it, and stamps the actor on every web API call (the
  * x-den-mcp-agent / x-den-mcp-workspace headers, see shared/agent-actor.ts).
  *
+ * `--grant <ws>` (AG-2a, AG spec §5b; repeatable) widens the scope to another
+ * workspace, and only as far as the org config's `agents.<id>.grants` says
+ * (checkGrants): an agent never grants itself one. A call that names a
+ * granted workspace is served, and reported to the audit trail with both
+ * workspaces named. Lists show the scoped workspace and its grants.
+ *
  * It binds cooperating agents only: the scope lives in this process, and the
  * web server's HTTP API does not check it yet (WS-3a).
  */
 import * as path from "path";
 import { AGENT_ACTOR_RE, WORKSPACE_NAME_RE } from "../../shared/agent-actor.js";
+import type { ResolvedAgentsConfig } from "../../shared/den-config.js";
 import type { DenApi } from "./api.js";
 import { Refusal } from "./guards.js";
 
@@ -17,6 +24,16 @@ export interface McpScope {
   workspace: string;
   /** Who acts: `agent:<id>`. */
   actor: string;
+  /**
+   * Other workspaces it may name (`--grant`, from agents.<id>.grants);
+   * absent when there are none.
+   */
+  grants?: string[];
+}
+
+/** The workspaces a scope serves: its own first, then its grants. */
+export function scopeWorkspaces(scope: McpScope): string[] {
+  return [scope.workspace, ...(scope.grants ?? [])];
 }
 
 /** A call reached outside the scoped workspace. Always reported (F2). */
@@ -35,10 +52,11 @@ export class ScopeUsageError extends Error {
   }
 }
 
-const FLAGS: Record<string, "workspace" | "actor"> = {
+const FLAGS: Record<string, "workspace" | "actor" | "grant"> = {
   "--workspace": "workspace",
   "-w": "workspace",
   "--actor": "actor",
+  "--grant": "grant",
 };
 
 /**
@@ -53,6 +71,7 @@ export function parseScopeFlags(argv: readonly string[]): {
   rest: string[];
 } {
   const got: Partial<Record<"workspace" | "actor", string>> = {};
+  const grants: string[] = [];
   const rest: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
@@ -71,12 +90,25 @@ export function parseScopeFlags(argv: readonly string[]): {
         throw new ScopeUsageError(`${name} needs a value`);
       i++;
     }
+    if (key === "grant") {
+      if (!WORKSPACE_NAME_RE.test(value))
+        throw new ScopeUsageError(
+          `--grant "${printable(value)}" is not a workspace name`,
+        );
+      if (!grants.includes(value)) grants.push(value);
+      continue;
+    }
     if (got[key] !== undefined && got[key] !== value)
       throw new ScopeUsageError(`--${key} given twice`);
     got[key] = value;
   }
-  if (got.workspace === undefined && got.actor === undefined)
+  if (got.workspace === undefined && got.actor === undefined) {
+    if (grants.length)
+      throw new ScopeUsageError(
+        "--grant needs --workspace and --actor: a grant widens a scoped server",
+      );
     return { scope: null, rest };
+  }
   if (got.workspace === undefined)
     throw new ScopeUsageError(
       "--actor needs --workspace: a scoped server serves one workspace",
@@ -95,7 +127,35 @@ export function parseScopeFlags(argv: readonly string[]): {
       `--actor "${printable(got.actor)}" is not agent:<id> ` +
         "(the id: letters, digits, dots, dashes, underscores; at most 64)",
     );
-  return { scope: { workspace: got.workspace, actor: got.actor }, rest };
+  const widened = grants.filter((g) => g !== got.workspace);
+  return {
+    scope: {
+      workspace: got.workspace,
+      actor: got.actor,
+      ...(widened.length ? { grants: widened } : {}),
+    },
+    rest,
+  };
+}
+
+/**
+ * Null when every `--grant` is one the org config gives this agent
+ * (`agents.<id>.grants`), else the refusal. A grant is config in git,
+ * reviewed like code: a flag alone never widens a scope.
+ */
+export function checkGrants(
+  scope: McpScope,
+  agents: Pick<ResolvedAgentsConfig, "agents">,
+): string | null {
+  const id = scope.actor.slice("agent:".length);
+  const allowed = agents.agents[id]?.grants ?? [];
+  for (const g of scope.grants ?? [])
+    if (!allowed.includes(g))
+      return (
+        `--grant ${g}: ${scope.actor} has no such grant in agents.${id}.grants ` +
+        "of the org config; a grant is config, never a flag alone"
+      );
+  return null;
 }
 
 /** A value echoed back in an error: one printable line, bounded. */
@@ -124,7 +184,14 @@ export function printablePath(v: string, max = 160): string {
   return `${head}…${more}${tail}`;
 }
 
-/** The refusal for a call that names `other`. */
+/** "grants: a, b" or "no grants": what else the scope reaches. */
+function grantsNote(scope: McpScope): string {
+  return scope.grants?.length
+    ? `grants: ${scope.grants.join(", ")}`
+    : "no grants";
+}
+
+/** The refusal for a call that names `other`; it names the agent's grants. */
 export function otherWorkspace(
   tool: string,
   scope: McpScope,
@@ -132,7 +199,7 @@ export function otherWorkspace(
 ): ScopeRefusal {
   return new ScopeRefusal(
     `${tool}: this MCP server is scoped to workspace "${scope.workspace}" ` +
-      `(${scope.actor}); "${printable(other)}" is another workspace, so nothing was read or run.`,
+      `(${scope.actor}; ${grantsNote(scope)}); "${printable(other)}" is another workspace, so nothing was read or run.`,
   );
 }
 
@@ -146,9 +213,20 @@ export function pinWorkspace(
   scope: McpScope,
 ): Record<string, unknown> {
   const ws = args.workspace;
-  if (ws !== undefined && ws !== null && ws !== "" && ws !== scope.workspace)
+  if (ws === undefined || ws === null || ws === "")
+    return { ...args, workspace: scope.workspace };
+  if (!scopeWorkspaces(scope).includes(String(ws)))
     throw otherWorkspace(tool, scope, String(ws));
-  return { ...args, workspace: scope.workspace };
+  return { ...args, workspace: String(ws) };
+}
+
+/** The granted workspace `args` names, or null for the scope's own. */
+export function crossedWorkspace(
+  args: Record<string, unknown>,
+  scope: McpScope,
+): string | null {
+  const ws = args.workspace;
+  return typeof ws === "string" && ws && ws !== scope.workspace ? ws : null;
 }
 
 /** What /api/workspaces answers (the fields the scope reads). */
@@ -175,13 +253,20 @@ export function filterWorkspacesBody(
 ): Record<string, unknown> {
   const b = asRecord(body) as WorkspacesBody;
   const ws = scope.workspace;
+  const served = scopeWorkspaces(scope);
   const only = (v: unknown): Record<string, unknown> => {
     const r = asRecord(v);
-    return ws in r ? { [ws]: r[ws] } : {};
+    return Object.fromEntries(
+      served.filter((n) => n in r).map((n) => [n, r[n]]),
+    );
   };
   return {
-    active: Array.isArray(b.active) ? b.active.filter((n) => n === ws) : [],
-    ...(b.focus === ws ? { focus: ws } : {}),
+    active: Array.isArray(b.active)
+      ? b.active.filter((n) => served.includes(n as string))
+      : [],
+    ...(typeof b.focus === "string" && served.includes(b.focus)
+      ? { focus: b.focus }
+      : {}),
     workspaces: only(b.workspaces),
     ...(b.resolvedDirs !== undefined
       ? { resolvedDirs: only(b.resolvedDirs) }
@@ -189,7 +274,11 @@ export function filterWorkspacesBody(
     ...(b.codeWorkspacePaths !== undefined
       ? { codeWorkspacePaths: only(b.codeWorkspacePaths) }
       : {}),
-    scope: { workspace: ws, actor: scope.actor },
+    scope: {
+      workspace: ws,
+      actor: scope.actor,
+      ...(scope.grants?.length ? { grants: scope.grants } : {}),
+    },
   };
 }
 
@@ -219,23 +308,38 @@ export async function assertScopeExists(
   return body;
 }
 
+/** Throws unless the granted workspace `ws` exists in this distribution. */
+export async function assertGrantExists(
+  tool: string,
+  api: DenApi,
+  scope: McpScope,
+  ws: string,
+): Promise<void> {
+  const body = await api.get("/api/workspaces");
+  if (!(ws in asRecord(asRecord(body).workspaces)))
+    throw new ScopeRefusal(
+      `${tool}: ${scope.actor} has a grant for workspace "${printable(ws)}", which does not exist in this distribution; nothing was read or run.`,
+    );
+}
+
 /**
  * Tests run against the focused workspace (the web server has no workspace
  * argument for them): a scoped server runs or lists them only when that is
- * its own.
+ * its own or a granted one. Returns the focused workspace.
  */
 export async function assertScopeFocused(
   tool: string,
   api: DenApi,
   scope: McpScope,
-): Promise<void> {
+): Promise<string> {
   const focused = focusedOf(await api.get("/api/workspaces"));
-  if (focused !== scope.workspace)
-    throw new ScopeRefusal(
-      `${tool}: tests run against the focused workspace` +
-        `${focused ? ` ("${focused}")` : ""}, and this MCP server is scoped to ` +
-        `"${scope.workspace}". Focus "${scope.workspace}" first; nothing was read or run.`,
-    );
+  // A granted workspace that is focused is served too (and audited).
+  if (focused && scopeWorkspaces(scope).includes(focused)) return focused;
+  throw new ScopeRefusal(
+    `${tool}: tests run against the focused workspace` +
+      `${focused ? ` ("${focused}")` : ""}, and this MCP server is scoped to ` +
+      `"${scope.workspace}". Focus "${scope.workspace}" first; nothing was read or run.`,
+  );
 }
 
 /** The fields of an /api/services entry the scope checks read. */

package/src/ui/mcp/server.ts

@@ -11,18 +11,25 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { agentAuditHeaders } from "../../shared/agent-actor.js";
 import {
+  readAgentsConfig,
   readMcpConfig,
   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";
 import { ownServer } from "../cli/server-identity.js";
 import { callTool, toolsFor, type ToolContext } from "./tools.js";
 import { plural } from "../../shared/plural.js";
-import { parseScopeFlags, ScopeUsageError, type McpScope } from "./scope.js";
+import {
+  checkGrants,
+  parseScopeFlags,
+  ScopeUsageError,
+  type McpScope,
+} from "./scope.js";
 
 export interface DenMcpOptions {
   cfg: ResolvedMcpConfig;
@@ -146,7 +153,7 @@ export const MCP_USAGE = (cli: string): string =>
     `Usage: ${cli} mcp [--port <web port>]`,
     `       ${cli} mcp --list`,
     `       ${cli} mcp --call <tool> ['<json args>']`,
-    `       ${cli} mcp --workspace <ws> --actor agent:<id> [...]`,
+    `       ${cli} mcp --workspace <ws> --actor agent:<id> [--grant <ws>…] [...]`,
     "",
     `An MCP server over stdio for agents, a client of the running web server`,
     `(\`${cli} web up\`; default port: config web.port). Read tools always;`,
@@ -160,6 +167,10 @@ export const MCP_USAGE = (cli: string): string =>
     "is recorded as agent:<id>. It binds cooperating agents only: the web",
     "server's HTTP API does not check the scope yet.",
     "",
+    "--grant <ws> (repeatable) also serves another workspace, only when the org",
+    "config's agents.<id>.grants lists it; each such call is recorded with both",
+    "workspaces. `agents start` passes an agent's grants for you.",
+    "",
     `Register it with your agents: ${cli} mcp clients, then ${cli} mcp connect <client> (or --all).`,
   ].join("\n");
 
@@ -249,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;
@@ -269,6 +337,26 @@ 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;
+    try {
+      refused = checkGrants(scope, readAgentsConfig());
+    } catch (e) {
+      refused = (e as Error).message;
+    }
+    if (refused) {
+      process.stderr.write(`${cli} mcp: ${refused}\n`);
+      process.exitCode = 2;
+      return;
+    }
+  }
   let port = parsePort(argv);
   if (port === undefined) {
     try {
@@ -312,9 +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}` : "") +
-      "\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/mcp/tools.ts

@@ -35,10 +35,12 @@ import {
 } from "./guards.js";
 import {
   ScopeRefusal,
+  assertGrantExists,
   assertPathInScope,
   assertScopeExists,
   assertScopeFocused,
   assertServicesInScope,
+  crossedWorkspace,
   filterWorkspacesBody,
   pinWorkspace,
   type McpScope,
@@ -303,7 +305,12 @@ const READ_TOOLS: DenTool[] = [
     "The test modules of a pillar, and which repos (branch + SHA) they come from.",
     { pillar: z.enum(PILLARS) },
     async (a, { api, scope }) => {
-      if (scope) await assertScopeFocused("tests_available", api, scope);
+      if (scope)
+        await crossIfGranted(
+          { api, scope },
+          "tests_available",
+          await assertScopeFocused("tests_available", api, scope),
+        );
       return {
         modules: await api.get("/api/modules", { pillar: String(a.pillar) }),
         sources: await api.get("/api/test-sources", {
@@ -538,7 +545,12 @@ const ACTION_TOOLS: Record<McpAction, DenTool> = {
       const mode =
         pillar === "security" ? (str(a.mode) ?? "baseline") : undefined;
       assertRunTestsAllowed({ pillar, env, mode }, cfg);
-      if (scope) await assertScopeFocused("run_tests", api, scope);
+      if (scope)
+        await crossIfGranted(
+          { api, scope },
+          "run_tests",
+          await assertScopeFocused("run_tests", api, scope),
+        );
       if (pillar === "security") {
         for (const service of modules.length ? modules : [undefined]) {
           const plan = (await api.get("/api/security/plan", {
@@ -710,9 +722,36 @@ async function scopeArgs(
     await assertScopeExists(ctx.api, scope);
     verifiedScopes.add(scope);
   }
-  return "workspace" in tool.shape
-    ? pinWorkspace(tool.name, args, scope)
-    : args;
+  if (!("workspace" in tool.shape)) return args;
+  const pinned = pinWorkspace(tool.name, args, scope);
+  const crossed = crossedWorkspace(pinned, scope);
+  if (crossed) {
+    await assertGrantExists(tool.name, ctx.api, scope, crossed);
+    await reportCrossWorkspace(ctx.api, tool.name, crossed);
+  }
+  return pinned;
+}
+
+/**
+ * A call into a granted workspace (AG-2a, §5b) is recorded before it runs,
+ * with both workspaces named: the server's entry takes the scoped one from
+ * the actor's headers and the target from this report.
+ */
+async function reportCrossWorkspace(
+  api: DenApi,
+  tool: string,
+  target: string,
+): Promise<void> {
+  await api.get("/api/activity", {}, "POST", { tool, crossWorkspace: target });
+}
+
+/** Report `ws` when it is a granted workspace, not the scope's own. */
+async function crossIfGranted(
+  ctx: { api: DenApi; scope: McpScope },
+  tool: string,
+  ws: string,
+): Promise<void> {
+  if (ws !== ctx.scope.workspace) await reportCrossWorkspace(ctx.api, tool, ws);
 }
 
 export async function callTool(