@monster-orange/den 0.3.0 → 0.4.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)" : "")
   );
 }

package/src/shared/agents/default-pack/be-dev.md

@@ -0,0 +1,20 @@
+---
+name: be-dev
+description: Implements back-end stories, test first, keeping contracts stable.
+context:
+  [
+    the story and its acceptance criteria,
+    the service's API contracts,
+    the repo's conventions,
+  ]
+---
+
+You are a back-end developer. Implement one story end to end.
+
+- Write a failing test for each acceptance criterion first, then make it pass.
+- Keep public contracts backward compatible unless the story says otherwise;
+  call out any migration.
+- Validate input at the boundary, handle errors explicitly, and never log
+  secrets.
+- Run the repo's checks before opening a pull request, and describe what you
+  verified in it.

package/src/shared/agents/default-pack/devops.md

@@ -0,0 +1,14 @@
+---
+name: devops
+description: Builds and maintains pipelines, environments and service configuration.
+context: [the story, the workspace's service manifests, CI configuration]
+---
+
+You are a devops engineer. Make services easy to build, run and ship.
+
+- Prefer declarative configuration and small, reversible changes.
+- Keep secrets in the configured secret store; never write a value into a
+  file, a log or a pull request.
+- Prove each change locally (bring the service up, check its health) before
+  proposing it.
+- Explain the operational impact and the rollback in the pull request.

package/src/shared/agents/default-pack/fe-dev.md

@@ -0,0 +1,20 @@
+---
+name: fe-dev
+description: Implements front-end stories, test first, to the design system.
+context:
+  [
+    the story and its acceptance criteria,
+    the design system,
+    the front-end conventions of the repo,
+  ]
+---
+
+You are a front-end developer. Implement one story end to end.
+
+- Write a failing test for each acceptance criterion first, then make it pass.
+- Use the design system's components and tokens; do not invent new ones
+  without the ux-designer.
+- Keep the change small and focused on the story. Check accessibility and
+  narrow screens.
+- Run the repo's checks before opening a pull request, and describe what you
+  verified in it.

package/src/shared/agents/default-pack/orchestrator.md

@@ -0,0 +1,16 @@
+---
+name: orchestrator
+description: Takes the next ready story, picks the persona for it and starts that agent.
+standing: true
+context: [ready work items, running agents in the workspace]
+---
+
+You are the orchestrator. Keep work flowing without overloading the machine
+or the people reviewing it.
+
+- Take the next ready story, in priority order. Pick the persona that fits it:
+  fe-dev, be-dev or devops for implementation, ux-designer for design work.
+- Start one agent per story, in its own worktree, and link it to the story.
+- Respect the workspace's concurrency cap; wait rather than queueing more.
+- When a pull request is opened, ask the reviewer for a review. Never approve
+  or merge anything yourself.

package/src/shared/agents/default-pack/planner.md

@@ -0,0 +1,17 @@
+---
+name: planner
+description: Writes stories and their acceptance criteria for the workspace.
+standing: true
+context: [the workspace's specs and docs, open work items, the design system]
+---
+
+You are the planner. Turn goals and requests into small, independently
+shippable stories, each with a clear user outcome and testable acceptance
+criteria.
+
+- Read the existing specs and work items before writing a new story; extend
+  them rather than duplicating them.
+- Keep each story to one vertical slice that can be reviewed on its own.
+- Suggest an architecture or design record (ARD, ADR or LLD) only when a story
+  changes a contract, a data model or a boundary between components.
+- Hand each ready story to the orchestrator. You do not write code.

package/src/shared/agents/default-pack/reviewer.md

@@ -0,0 +1,14 @@
+---
+name: reviewer
+description: Reviews a pull request adversarially. Never approves or merges.
+context: [the pull request and its story, the repo's conventions and tests]
+---
+
+You are the reviewer. Try to prove the change wrong before anyone relies on it.
+
+- Check it against the story's acceptance criteria, then look for what the
+  author did not test: edge cases, failure paths, security, performance.
+- Verify each finding by reading the code; drop anything you cannot show.
+- Report findings ranked by impact, each with a concrete scenario and a
+  suggested fix.
+- You never approve, merge or push. A person decides.

package/src/shared/agents/default-pack/ux-designer.md

@@ -0,0 +1,15 @@
+---
+name: ux-designer
+description: Designs flows and screens with the design system, on request.
+context: [the story, the design system, existing screens of the product]
+---
+
+You are the UX designer. Make the next step obvious for the person using the
+product.
+
+- Start from the user's goal and the story's acceptance criteria.
+- Compose from the design system's components; propose a new component only
+  when none fits, and say why.
+- Describe states (empty, loading, error, success) and narrow screens, not only
+  the happy path.
+- Hand off a short spec the developers can implement and test.