@monster-orange/den 0.3.0 → 0.4.1

package/src/shared/secret-env.ts

@@ -0,0 +1,70 @@
+/**
+ * Which environment variables are credentials, by name or by value. One
+ * set of patterns for everything that checks an environment: the test
+ * workers (tests/scrub-env.ts), the audit of `sessions start --keep-env`,
+ * and `<cli> doctor --probe` (with the text redactor's own patterns,
+ * redact.ts). They err on the side of flagging: a harmless variable called
+ * a credential costs less than a token called harmless.
+ *
+ * Nothing here returns or logs a value.
+ */
+
+import { redactSecrets, SECRET_PATTERNS } from "./redact.js";
+
+/** Variable names that hold credentials. */
+const SECRET_NAME =
+  /(TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|API_?KEY|PRIVATE_KEY|ACCESS_KEY|AUTH)/i;
+
+/** Whole families of credential variables. */
+const SECRET_PREFIX = /^(OP_|DOPPLER_|AWS_|GH_|GITHUB_|NPM_|ANTHROPIC_)/i;
+
+/** Values shaped like well-known tokens, whatever the variable is called. */
+const SECRET_VALUE =
+  /(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|ops_[A-Za-z0-9]{20,}|sk-ant-[A-Za-z0-9_-]{20,}|dp\.(st|ct|sa|scim)\.[A-Za-z0-9]{20,}|npm_[A-Za-z0-9]{20,}|xox[abpr]-[A-Za-z0-9-]{10,})/;
+
+/** Whether a variable looks like a credential, by name or by value. */
+export function isCredentialEnv(
+  name: string,
+  value: string | undefined,
+): boolean {
+  return (
+    SECRET_NAME.test(name) ||
+    SECRET_PREFIX.test(name) ||
+    (value !== undefined && SECRET_VALUE.test(value))
+  );
+}
+
+/**
+ * Credential-shaped: by name or value (isCredentialEnv), or a value the
+ * text redactor would redact.
+ */
+export function isCredentialShaped(
+  name: string,
+  value: string | undefined,
+): boolean {
+  return (
+    isCredentialEnv(name, value) ||
+    (value !== undefined && value !== "" && redactSecrets(value) !== value)
+  );
+}
+
+/**
+ * Every pattern isCredentialShaped uses, as plain data (source and flags,
+ * global flag dropped), for a check run in another process (the probe).
+ */
+export function credentialPatternData(): {
+  name: { source: string; flags: string }[];
+  value: { source: string; flags: string }[];
+} {
+  const data = (re: RegExp) => ({
+    source: re.source,
+    flags: re.flags.replace("g", ""),
+  });
+  return {
+    name: [SECRET_NAME, SECRET_PREFIX].map(data),
+    value: [SECRET_VALUE, ...SECRET_PATTERNS.map((p) => p.re)].map(data),
+  };
+}
+
+/** An environment variable name (`--keep-env NAME`). */
+export const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;

package/src/shared/sessions/client.ts

@@ -0,0 +1,284 @@
+/**
+ * A client of the session host (protocol.ts): one socket connection, many
+ * requests and attachments over it. ensureHost starts a host on demand when
+ * none answers (the first client starts it; later ones find it).
+ */
+import { EventEmitter } from "events";
+import * as net from "net";
+import {
+  frame,
+  LineReader,
+  PROTOCOL_VERSION,
+  type HostErrorCode,
+  type HostEvent,
+} from "./protocol.js";
+import type {
+  AttachHandlers,
+  Attachment,
+  SessionInfo,
+  SessionSignal,
+  SessionSpec,
+} from "./types.js";
+
+/** A request the host refused. */
+export class HostError extends Error {
+  constructor(
+    readonly code: HostErrorCode | "closed",
+    message: string,
+  ) {
+    super(message);
+    this.name = "HostError";
+  }
+}
+
+interface Pending {
+  resolve(v: Record<string, unknown>): void;
+  reject(e: Error): void;
+}
+
+let aidSeq = 0;
+
+export class HostClient extends EventEmitter {
+  private nextId = 1;
+  private readonly pending = new Map<number, Pending>();
+  private readonly attachments = new Map<string, AttachHandlers>();
+  hostPid = 0;
+  hostStartedAt = "";
+
+  constructor(private readonly socket: net.Socket) {
+    super();
+    const reader = new LineReader((line) => this.onLine(line));
+    socket.on("data", (c) => {
+      if (!reader.push(c)) socket.destroy();
+    });
+    socket.on("error", () => undefined);
+    socket.on("close", () => {
+      for (const p of this.pending.values())
+        p.reject(
+          new HostError("closed", "the session host closed the connection"),
+        );
+      this.pending.clear();
+      this.attachments.clear();
+      this.emit("close");
+    });
+  }
+
+  private onLine(line: string): void {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      return;
+    }
+    if (typeof msg.ev === "string") {
+      const ev = msg as unknown as HostEvent;
+      const h = this.attachments.get(ev.aid);
+      if (!h) return;
+      if (ev.ev === "data") h.onData(Buffer.from(ev.data, "base64"));
+      else {
+        this.attachments.delete(ev.aid);
+        h.onExit?.(ev.exitCode);
+      }
+      return;
+    }
+    const p = this.pending.get(msg.id as number);
+    if (!p) return;
+    this.pending.delete(msg.id as number);
+    if (msg.ok) p.resolve(msg);
+    else
+      p.reject(
+        new HostError(
+          msg.code as HostErrorCode,
+          String(msg.error ?? "refused"),
+        ),
+      );
+  }
+
+  /** Send one request; resolves with the host's reply. */
+  request(
+    op: string,
+    body: Record<string, unknown> = {},
+  ): Promise<Record<string, unknown>> {
+    if (this.socket.destroyed)
+      return Promise.reject(
+        new HostError("closed", "not connected to the session host"),
+      );
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.socket.write(frame({ v: PROTOCOL_VERSION, id, op, ...body }));
+    });
+  }
+
+  /** Fire and forget: errors are dropped (write, resize, signal). */
+  private send(op: string, body: Record<string, unknown>): void {
+    this.request(op, body).catch(() => undefined);
+  }
+
+  async hello(): Promise<void> {
+    const r = await this.request("hello");
+    this.hostPid = Number(r.pid);
+    this.hostStartedAt = String(r.startedAt ?? "");
+  }
+
+  async start(
+    spec: SessionSpec,
+    opts: {
+      limit?: number;
+      /** `--keep-env` names, for the host's audit line (never values). */
+      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 || opts.refusedEnv?.length
+        ? { actor: opts.actor ?? "unknown" }
+        : {}),
+      ...(opts.keptEnv?.length ? { keptEnv: opts.keptEnv } : {}),
+      ...(opts.refusedEnv?.length ? { refusedEnv: opts.refusedEnv } : {}),
+    });
+    return r.info as SessionInfo;
+  }
+
+  async list(): Promise<SessionInfo[]> {
+    return (await this.request("list")).sessions as SessionInfo[];
+  }
+
+  /**
+   * Attach to session `id`: the replay (the newest `replay` bytes, all of
+   * the scrollback by default) arrives first, then live output.
+   */
+  attach(
+    id: string,
+    handlers: AttachHandlers,
+    opts: { replay?: number } = {},
+  ): Attachment {
+    const aid = `${process.pid}.${++aidSeq}`;
+    this.attachments.set(aid, handlers);
+    const ready = this.request("attach", {
+      ref: id,
+      aid,
+      ...(opts.replay !== undefined ? { replay: opts.replay } : {}),
+    }).then(
+      (r) => r.info as SessionInfo,
+      (e: Error) => {
+        this.attachments.delete(aid);
+        throw e;
+      },
+    );
+    return {
+      ready,
+      detach: () => {
+        this.attachments.delete(aid);
+        this.send("detach", { aid });
+      },
+    };
+  }
+
+  write(id: string, bytes: Uint8Array): void {
+    this.send("write", {
+      ref: id,
+      data: Buffer.from(bytes).toString("base64"),
+    });
+  }
+
+  resize(id: string, cols: number, rows: number): void {
+    this.send("resize", { ref: id, cols, rows });
+  }
+
+  signal(id: string, signal: SessionSignal): void {
+    this.send("signal", { ref: id, signal });
+  }
+
+  /** Like signal, but says when the host refused (exited, unknown). */
+  async kill(id: string, signal: SessionSignal): Promise<void> {
+    await this.request("signal", { ref: id, signal });
+  }
+
+  async scrollback(id: string, max: number): Promise<Buffer> {
+    const r = await this.request("scrollback", { ref: id, max });
+    return Buffer.from(String(r.data ?? ""), "base64");
+  }
+
+  async forget(id: string): Promise<void> {
+    await this.request("forget", { ref: id });
+  }
+
+  /** Stop the host: every running session ends. */
+  async shutdown(): Promise<void> {
+    await this.request("shutdown");
+  }
+
+  close(): void {
+    this.socket.end();
+    this.socket.destroy();
+  }
+}
+
+/** Whether a connect error means no host is serving on the socket. */
+export function noHost(e: unknown): boolean {
+  const code = (e as NodeJS.ErrnoException)?.code;
+  return code === "ENOENT" || code === "ECONNREFUSED";
+}
+
+/** Connect to the host on `socket` and say hello (checks the protocol). */
+export function connectHost(socket: string): Promise<HostClient> {
+  return new Promise((resolve, reject) => {
+    const s = net.connect(socket);
+    const fail = (e: Error) => reject(e);
+    s.once("error", fail);
+    s.once("connect", () => {
+      s.off("error", fail);
+      const c = new HostClient(s);
+      c.hello().then(
+        () => resolve(c),
+        (e: Error) => {
+          c.close();
+          reject(e);
+        },
+      );
+    });
+  });
+}
+
+export interface EnsureHostOptions {
+  socket: string;
+  /** Start a host in the background (detached, its own process group). */
+  spawnHost: () => void;
+  /** How long a new host gets to answer (default 15 s). */
+  timeoutMs?: number;
+  /** Named in the timeout error: where the host writes its log. */
+  logHint?: string;
+}
+
+/** A client of the running host, started first when none answers. */
+export async function ensureHost(o: EnsureHostOptions): Promise<HostClient> {
+  try {
+    return await connectHost(o.socket);
+  } catch (e) {
+    if (!noHost(e)) throw e;
+  }
+  o.spawnHost();
+  const deadline = Date.now() + (o.timeoutMs ?? 15_000);
+  for (;;) {
+    await new Promise((r) => setTimeout(r, 50));
+    try {
+      return await connectHost(o.socket);
+    } catch (e) {
+      if (!noHost(e)) throw e;
+      if (Date.now() > deadline)
+        throw new Error(
+          `the session host did not start within ${Math.round((o.timeoutMs ?? 15_000) / 1000)}s` +
+            (o.logHint ? `: see ${o.logHint}` : ""),
+        );
+    }
+  }
+}

package/src/shared/sessions/den-pty.ts

@@ -0,0 +1,97 @@
+/**
+ * den-pty: Den's built-in session backend (AG-3a). Its sessions live in the
+ * session host (host.ts), and this side is a client of it, so whoever holds
+ * a DenPtyBackend (the CLI now, the web server from AG-4a) can restart
+ * without ending a session.
+ *
+ * Registered as strategy kind `session-backend`, so `<cli> doctor` shows
+ * whether it can work here and why not. A workspace picking a backend in
+ * config (`sessions.backend`) comes with the second backend (tmux, AG-3b);
+ * until then den-pty is the implicit choice.
+ */
+import {
+  registerStrategy,
+  type StrategyEntry,
+} from "../strategies/registry.js";
+import type { HostClient } from "./client.js";
+import { BACKEND_ID } from "./host.js";
+import { loadPty, type PtyLoad } from "./pty.js";
+import type {
+  AttachHandlers,
+  Attachment,
+  SessionBackend,
+  SessionInfo,
+  SessionRef,
+  SessionSignal,
+  SessionSpec,
+} from "./types.js";
+
+export const SESSION_BACKEND_KIND = "session-backend";
+export { BACKEND_ID as DEN_PTY_ID };
+
+export interface DenPtyOptions {
+  /** A client of the running host (ensureHost). */
+  client: HostClient;
+  /** Applied to every start: agents.max_concurrent. */
+  limit?: number;
+}
+
+export class DenPtyBackend implements SessionBackend {
+  readonly id = BACKEND_ID;
+  constructor(private readonly opts: DenPtyOptions) {}
+
+  private own(ref: SessionRef): string {
+    if (ref.backend !== BACKEND_ID)
+      throw new Error(
+        `session ${ref.id} belongs to ${ref.backend}, not ${BACKEND_ID}`,
+      );
+    return ref.id;
+  }
+
+  async start(spec: SessionSpec): Promise<SessionRef> {
+    return (await this.opts.client.start(spec, { limit: this.opts.limit })).ref;
+  }
+  list(): Promise<SessionInfo[]> {
+    return this.opts.client.list();
+  }
+  attach(ref: SessionRef, handlers: AttachHandlers): Attachment {
+    return this.opts.client.attach(this.own(ref), handlers);
+  }
+  write(ref: SessionRef, bytes: Uint8Array): void {
+    this.opts.client.write(this.own(ref), bytes);
+  }
+  resize(ref: SessionRef, cols: number, rows: number): void {
+    this.opts.client.resize(this.own(ref), cols, rows);
+  }
+  signal(ref: SessionRef, signal: SessionSignal): void {
+    this.opts.client.signal(this.own(ref), signal);
+  }
+  async scrollback(ref: SessionRef, maxBytes: number): Promise<Uint8Array> {
+    return this.opts.client.scrollback(this.own(ref), maxBytes);
+  }
+  externalAttach(): string | null {
+    return null;
+  }
+}
+
+export interface SessionBackendCapabilities {
+  /** Whether the backend can start sessions here (the PTY module). */
+  pty(): PtyLoad;
+}
+
+const denPty: StrategyEntry<
+  typeof SESSION_BACKEND_KIND,
+  SessionBackendCapabilities
+> = {
+  id: BACKEND_ID,
+  kind: SESSION_BACKEND_KIND,
+  detect() {
+    const load = loadPty();
+    return load.available
+      ? { available: true, reason: "PTY module loaded" }
+      : { available: false, reason: load.reason };
+  },
+  capabilities: { pty: () => loadPty() },
+};
+
+registerStrategy(denPty);

package/src/shared/sessions/env.ts

@@ -0,0 +1,89 @@
+/**
+ * The environment a session starts with (AG spec §5a-env). The host passes
+ * `env` whole (it inherits nothing), so what is built here is all a session
+ * gets. There is no denylist: every session's env starts empty.
+ *
+ *   1. the allowlist, from the caller's env (SESSION_BASE_ENV, LC_*)
+ *   2. `keep`: names the user asked for (`sessions start --keep-env NAME`;
+ *      exact names, never for an agent)
+ *   3. `passthrough`: names a runtime declares (Runtime.envPassthrough)
+ *   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, 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. */
+export const AGENT_ACTOR_ENV = "DEN_AGENT";
+
+/** What a terminal program needs to run as the user: no more. */
+export const SESSION_BASE_ENV = [
+  "PATH",
+  "HOME",
+  "USER",
+  "LOGNAME",
+  "SHELL",
+  "TERM",
+  "COLORTERM",
+  "LANG",
+  "TZ",
+  "TMPDIR",
+] as const;
+
+/** Whether the allowlist takes `name` (the list, and every LC_*). */
+export function inSessionBase(name: string): boolean {
+  return (
+    (SESSION_BASE_ENV as readonly string[]).includes(name) ||
+    name.startsWith("LC_")
+  );
+}
+
+/** Whether a scrubEnv pattern (an exact name, or a prefix ending in *) matches. */
+export function matchesScrub(
+  name: string,
+  patterns: readonly string[],
+): boolean {
+  return patterns.some((p) =>
+    p.endsWith("*") ? name.startsWith(p.slice(0, -1)) : name === p,
+  );
+}
+
+export interface SessionEnvInput {
+  caller: NodeJS.ProcessEnv;
+  keep?: readonly string[];
+  passthrough?: readonly string[];
+  launch?: Record<string, string>;
+  extra?: Record<string, string>;
+  den?: Record<string, string>;
+  scrub?: readonly string[];
+}
+
+/** A session's environment, built as the header says. */
+export function buildSessionEnv(i: SessionEnvInput): Record<string, string> {
+  const named = new Set([...(i.keep ?? []), ...(i.passthrough ?? [])]);
+  const env: 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 ?? {});
+  delete env[ACTOR_TOKEN_ENV];
+  Object.assign(env, i.den ?? {});
+  const scrub = i.scrub ?? [];
+  for (const [k, v] of Object.entries(env))
+    if (matchesScrub(k, scrub) || isPersonCredentialEnv(k, v)) delete env[k];
+  return env;
+}