agent-yes 1.236.0 → 1.237.0

package/ts/serve.ts

@@ -39,6 +39,7 @@ import {
 } from "./subcommands.ts";
 import { answerAsk, listAsks } from "./askApi.ts";
 import { TYPING_BADGE } from "./badges.ts";
+import { isTermToken, mintTermToken, verifyTermToken, type TermScope } from "./termToken.ts";
 import { isCallbackRevoked, loadCallbackSecretReadOnly } from "./callback.ts";
 import { CLAUDE_SESSION_PIN_ENV } from "./sessionEnv.ts";
 import { MAX_CALLBACK_MSG_BYTES, frameVisitorMessage, verifyCapability } from "./callbackCore.ts";
@@ -217,6 +218,122 @@ function checkAuth(req: Request, expectedToken: string): boolean {
   return q ? tokenEqual(q, expectedToken) : false;
 }
 
+// Authorization result: the master token grants everything (as before); a scoped
+// terminal-embed token (termToken.ts) grants a NARROW capability confined to one
+// agent by scopedGate() below.
+type AuthResult = { kind: "master" } | { kind: "scoped"; scope: TermScope };
+
+function authorizeRequest(req: Request, expectedToken: string): AuthResult | null {
+  const auth = req.headers.get("authorization") ?? "";
+  const bearer = auth.startsWith("Bearer ") ? auth.slice(7) : null;
+  const provided = bearer ?? new URL(req.url).searchParams.get("token") ?? "";
+  if (!provided) return null;
+  if (tokenEqual(provided, expectedToken)) return { kind: "master" };
+  // A scoped token is verified against the master token (stateless HMAC).
+  if (isTermToken(provided)) {
+    const scope = verifyTermToken(expectedToken, provided);
+    if (scope) return { kind: "scoped", scope };
+  }
+  return null;
+}
+
+// The embeddable terminal routes. Token-gated (master OR scoped) but CORS-open so
+// a cross-origin report page can reach the daemon — the token is still required to
+// get a 200, and no cookies are involved, so `*` leaks nothing.
+function isTermCorsPath(p: string): boolean {
+  return /^\/api\/(tail|size)\/.+$/.test(p) || p === "/api/send";
+}
+
+function withTermCors(req: Request, res: Response | undefined): Response | undefined {
+  if (!res) return res; // mux upgrade returns undefined
+  if (isTermCorsPath(new URL(req.url).pathname)) {
+    try {
+      res.headers.set("Access-Control-Allow-Origin", "*");
+      res.headers.set("Vary", "Origin");
+    } catch {
+      /* immutable headers — skip */
+    }
+  }
+  return res;
+}
+
+function termCorsPreflight(): Response {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+      "Access-Control-Allow-Headers": "content-type, authorization",
+      "Access-Control-Max-Age": "600",
+    },
+  });
+}
+
+/** Does `keyword` resolve to the exact pid a scoped token is bound to? */
+async function scopedKeywordOk(keyword: string, scope: TermScope): Promise<boolean> {
+  try {
+    const rec = await resolveOne(keyword, defaultOpts({ all: true }));
+    return String(rec.pid) === String(scope.pid);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Confine a scoped token to its capability. Returns a 403 Response when the
+ * request is outside the token's grant, or null when it's allowed to proceed.
+ * Allowed: GET /api/tail|size/<kw> for the bound pid; POST /api/send for the bound
+ * pid IFF the token is interactive (canSend). Everything else is denied.
+ */
+async function scopedGate(
+  scope: TermScope,
+  method: string,
+  p: string,
+): Promise<Response | null> {
+  const forbid = (m: string) => new Response(m, { status: 403 });
+  const m = /^\/api\/(?:tail|size)\/(.+)$/.exec(p);
+  if (method === "GET" && m) {
+    return (await scopedKeywordOk(decodeURIComponent(m[1]!), scope))
+      ? null
+      : forbid("scoped token: not bound to this agent");
+  }
+  if (method === "POST" && p === "/api/send") {
+    if (!scope.canSend) return forbid("scoped token is read-only");
+    return null; // pid binding enforced in the /api/send handler (it has the body)
+  }
+  // Interactive viewers may renegotiate the agent's PTY size (drag-to-resize) —
+  // send-capable scope only, bound pid. The keyword is in the path, so bind here.
+  const rz = /^\/api\/resize\/(.+)$/.exec(p);
+  if (method === "POST" && rz) {
+    if (!scope.canSend) return forbid("scoped token is read-only");
+    return (await scopedKeywordOk(decodeURIComponent(rz[1]!), scope))
+      ? null
+      : forbid("scoped token: not bound to this agent");
+  }
+  return forbid("scoped token: route not permitted");
+}
+
+/**
+ * Mint a scoped terminal-embed token locally (no daemon round-trip): read the
+ * master token file, resolve the keyword to a concrete pid, and sign. Used by
+ * `ay term mint`. Throws if there's no serve token or the agent can't be resolved.
+ */
+export async function mintScopedTermToken(
+  keyword: string,
+  opts: { ttlSec: number; canSend: boolean },
+): Promise<{ token: string; pid: string; exp: number; canSend: boolean }> {
+  const master = await loadTokenReadOnly();
+  if (!master)
+    throw new Error(
+      "no serve token at ~/.agent-yes/.serve-token — run `ay serve` once on this host to create it",
+    );
+  const rec = await resolveOne(keyword, defaultOpts({ all: true }));
+  const pid = String(rec.pid);
+  const exp = Math.floor(Date.now() / 1000) + Math.max(1, Math.floor(opts.ttlSec));
+  const token = mintTermToken(master, { pid, canSend: opts.canSend, exp });
+  return { token, pid, exp, canSend: opts.canSend };
+}
+
 const defaultOpts = (overrides: Partial<CommonOpts> = {}): CommonOpts => ({
   all: false,
   active: false,
@@ -2019,13 +2136,24 @@ export async function cmdServe(rest: string[]): Promise<number> {
     req: Request,
     srv?: { upgrade: (r: Request, o?: unknown) => boolean },
   ): Promise<Response> => {
-    if (!checkAuth(req, token)) {
-      return new Response("Unauthorized", { status: 401 });
-    }
-
     const url = new URL(req.url);
     const p = url.pathname;
 
+    // CORS preflight for the embeddable terminal routes carries no auth header —
+    // answer it before the auth gate.
+    if (req.method === "OPTIONS" && isTermCorsPath(p)) return termCorsPreflight();
+
+    const authResult = authorizeRequest(req, token);
+    if (!authResult) {
+      return withTermCors(req, new Response("Unauthorized", { status: 401 }))!;
+    }
+    // A scoped token is confined to its bound agent + capability; the master token
+    // is unrestricted (existing behavior).
+    if (authResult.kind === "scoped") {
+      const denied = await scopedGate(authResult.scope, req.method, p);
+      if (denied) return withTermCors(req, denied)!;
+    }
+
     // GET /api/mux — WebSocket request multiplexer. HTTP/1.1 gives a browser
     // ~6 concurrent same-origin connections and no multiplexing, so console
     // bursts (a palette query fans out ~20 tail reads + a history search)
@@ -2727,6 +2855,10 @@ export async function cmdServe(rest: string[]): Promise<number> {
           pid: record.pid,
           cols: size?.cols ?? null,
           rows: size?.rows ?? null,
+          // Enough identity for a widget's title bar without exposing /api/ls to a
+          // scoped token (it's bound to this pid anyway — no extra info leaked).
+          cwd: record.cwd,
+          cli: record.cli,
           // This host negotiates the PTY size from viewer capacities (presence
           // `cap`) — a capable console should report its cap instead of pushing
           // /api/resize directly, so viewers stop fighting last-writer-wins.
@@ -2936,6 +3068,11 @@ export async function cmdServe(rest: string[]): Promise<number> {
       if (!keyword || typeof keyword !== "string") {
         return new Response("missing keyword", { status: 400 });
       }
+      // A scoped interactive token may only write to the agent it's bound to
+      // (the gate already confirmed canSend; bind the pid now that we have the body).
+      if (authResult.kind === "scoped" && !(await scopedKeywordOk(keyword, authResult.scope))) {
+        return new Response("scoped token: not bound to this agent", { status: 403 });
+      }
       try {
         const record = await resolveOne(keyword, defaultOpts());
         if (!record.fifo_file)
@@ -3804,7 +3941,9 @@ export async function cmdServe(rest: string[]): Promise<number> {
     if (req.method === "GET" && p === "/icon.svg") return serveUiFile("icon.svg", "image/svg+xml");
     if (req.method === "GET" && p === "/favicon.ico") return new Response(null, { status: 204 });
     if (p.startsWith("/cb/")) return handleCallback(req, p);
-    return apiFetch(req, srv);
+    // CORS-open the embeddable terminal routes (tail/size/send) so a cross-origin
+    // report page can reach this daemon; the token is still required for a 200.
+    return withTermCors(req, await apiFetch(req, srv)) as Response;
   };
 
   const serverOpts: any = {

package/ts/subcommands.ts

@@ -365,6 +365,7 @@ const SUBCOMMANDS = new Set([
   "todo",
   "ch",
   "channels",
+  "term",
   "serve",
   "schedule",
   "remote",
@@ -486,6 +487,10 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
         const { cmdCh } = await import("./channels.ts");
         return cmdCh(rest);
       }
+      case "term": {
+        const { cmdTerm } = await import("./terminal.ts");
+        return cmdTerm(rest);
+      }
       case "serve": {
         const { cmdServe } = await import("./serve.ts");
         return cmdServe(rest);
@@ -622,6 +627,7 @@ export async function cmdHelp(managerCommands = true): Promise<number> {
       `  ay send <keyword> <msg>             send a message (keyword '.' = agent in this cwd)\n` +
       `  ay msgs [keyword] [--in|--out]      inter-agent message log (sent + received)\n` +
       `  ay ch mk|join|send|read|tail <topic>  local-first E2E channels: AI ↔ humans on a topic (ay ch help)\n` +
+      `  ay term embed <pid>                 <script> to embed a live read-only agent terminal in a page (ay term help)\n` +
       `  ay key <keyword> <key...>           send raw keystrokes (down/up/enter/esc/…) — drives menus\n` +
       `  ay select <keyword> <N>             pick option N of a needs_input selection menu\n` +
       `  ay attach <keyword>                 interactive attach (detach: Ctrl-\\)\n` +

package/ts/termToken.spec.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { isTermToken, mintTermToken, verifyTermToken } from "./termToken.ts";
+
+const MASTER = "master-token-abc123";
+const now = 1_000_000; // fixed epoch seconds for deterministic exp checks
+
+describe("termToken", () => {
+  it("round-trips a valid read-only token", () => {
+    const tok = mintTermToken(MASTER, { pid: "4242", canSend: false, exp: now + 900 });
+    expect(isTermToken(tok)).toBe(true);
+    const scope = verifyTermToken(MASTER, tok, now);
+    expect(scope).toEqual({ pid: "4242", canSend: false, exp: now + 900 });
+  });
+
+  it("round-trips an interactive token (canSend true)", () => {
+    const tok = mintTermToken(MASTER, { pid: "7", canSend: true, exp: now + 60 });
+    expect(verifyTermToken(MASTER, tok, now)?.canSend).toBe(true);
+  });
+
+  it("rejects a token signed with a different master (forgery)", () => {
+    const tok = mintTermToken(MASTER, { pid: "7", canSend: true, exp: now + 60 });
+    expect(verifyTermToken("other-master", tok, now)).toBeNull();
+  });
+
+  it("rejects an expired token", () => {
+    const tok = mintTermToken(MASTER, { pid: "7", canSend: false, exp: now - 1 });
+    expect(verifyTermToken(MASTER, tok, now)).toBeNull();
+  });
+
+  it("rejects a tampered payload (pid swap) — signature no longer matches", () => {
+    const tok = mintTermToken(MASTER, { pid: "7", canSend: false, exp: now + 60 });
+    const [prefix, , sig] = tok.split(".");
+    const evil = Buffer.from(JSON.stringify({ p: "9999", w: 1, x: now + 60 })).toString("base64url");
+    expect(verifyTermToken(MASTER, `${prefix}.${evil}.${sig}`, now)).toBeNull();
+  });
+
+  it("rejects the master token itself and other non-scoped strings", () => {
+    expect(isTermToken(MASTER)).toBe(false);
+    expect(verifyTermToken(MASTER, MASTER, now)).toBeNull();
+    expect(verifyTermToken(MASTER, "ayt1.only-two-parts", now)).toBeNull();
+    expect(verifyTermToken(MASTER, "", now)).toBeNull();
+    expect(verifyTermToken(MASTER, undefined, now)).toBeNull();
+  });
+});

package/ts/termToken.ts

@@ -0,0 +1,85 @@
+// Scoped terminal-embed tokens — a capability you can safely put in a web page.
+//
+// The serve daemon's MASTER token (~/.agent-yes/.serve-token) is full-fleet
+// read+write+spawn = RCE; it must NEVER land in an embed. A scoped token instead
+// grants a NARROW capability: read (and optionally write to) exactly ONE agent
+// session, and only until it expires. It is a stateless HMAC bearer token — the
+// daemon verifies it with the same master token it already holds, so there is no
+// server-side token store to manage or revoke (short TTL is the bound).
+//
+//   ayt1.<payloadB64url>.<sigB64url>
+//     payload = {p: <pid>, w: 0|1 (write/interactive), x: <exp epoch-seconds>}
+//     sig     = HMAC-SHA256(keyFor(masterToken), "ayt1.<payloadB64url>")
+//
+// `ay term mint` signs one locally (it can read the master token file); the
+// daemon's checkAuth verifies it and confines the request to the bound pid.
+// (ed25519 per-author signing is a stronger future form; symmetric HMAC already
+// delivers short-TTL + read-only + single-session, which is what embeds need.)
+import { createHash, createHmac, timingSafeEqual } from "crypto";
+
+export interface TermScope {
+  /** The agent pid this token is bound to (resolved to a concrete pid at mint time). */
+  pid: string;
+  /** Interactive: may also write to this pid's stdin (/api/send). Read-only when false. */
+  canSend: boolean;
+  /** Expiry, epoch seconds. */
+  exp: number;
+}
+
+const PREFIX = "ayt1";
+
+/** Dedicated HMAC key derived from the master token (so the token isn't signed with the raw master). */
+function keyFor(masterToken: string): Buffer {
+  return createHash("sha256")
+    .update("ay/term/token/v1\n" + masterToken)
+    .digest();
+}
+
+/** True for anything shaped like a scoped terminal token (cheap pre-check before verify). */
+export function isTermToken(tok: unknown): tok is string {
+  return typeof tok === "string" && tok.startsWith(PREFIX + ".");
+}
+
+/** Mint a scoped token bound to `scope.pid`, signed with the master token. */
+export function mintTermToken(masterToken: string, scope: TermScope): string {
+  const payload = Buffer.from(
+    JSON.stringify({ p: scope.pid, w: scope.canSend ? 1 : 0, x: Math.floor(scope.exp) }),
+  ).toString("base64url");
+  const body = `${PREFIX}.${payload}`;
+  const sig = createHmac("sha256", keyFor(masterToken)).update(body).digest().toString("base64url");
+  return `${body}.${sig}`;
+}
+
+/**
+ * Verify a scoped token against the master token. Returns the scope if the
+ * signature is valid AND it hasn't expired, else null. Fail-closed on any
+ * malformed input. `nowSec` is injectable for tests.
+ */
+export function verifyTermToken(
+  masterToken: string,
+  tok: unknown,
+  nowSec: number = Math.floor(Date.now() / 1000),
+): TermScope | null {
+  if (!isTermToken(tok)) return null;
+  const parts = tok.split(".");
+  if (parts.length !== 3) return null;
+  const body = `${parts[0]}.${parts[1]}`;
+  const expected = createHmac("sha256", keyFor(masterToken)).update(body).digest();
+  let got: Buffer;
+  try {
+    got = Buffer.from(parts[2]!, "base64url");
+  } catch {
+    return null;
+  }
+  // constant-time compare; length check first (timingSafeEqual throws on mismatch)
+  if (got.length !== expected.length || !timingSafeEqual(got, expected)) return null;
+  let obj: { p?: unknown; w?: unknown; x?: unknown };
+  try {
+    obj = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf-8"));
+  } catch {
+    return null;
+  }
+  if (typeof obj.p !== "string" || !obj.p) return null;
+  if (typeof obj.x !== "number" || !Number.isFinite(obj.x) || obj.x <= nowSec) return null; // expired
+  return { pid: obj.p, canSend: obj.w === 1, exp: obj.x };
+}