chamba 0.6.1 → 0.7.0

package/templates/webterm/server.js

@@ -46,7 +46,11 @@ import {
     MAX_PANE_BYTES,
     MAX_PANE_FILES,
     MAX_SESSIONS,
+    MAX_SPECS_BYTES,
+    MAX_SPECS_LINE_LENGTH,
+    MAX_SPECS_LINES_PER_SESSION,
     MAX_UPLOAD_BYTES,
+    PANE_APPS_CLIENT_DIR,
     PANE_DIR,
     PANE_SCAN_MS,
     PASTE_END,
@@ -54,6 +58,11 @@ import {
     PORT,
     RESUME_STAMP,
     resolveWorkspacePath,
+    SPECS_KEY,
+    SPECS_LINE_MIN_INTERVAL_MS,
+    SPECS_NEW_SESSION_DELAY_MS,
+    SPECS_RAW_TOKEN,
+    SPECS_ROOT,
     STATE_FILE,
     STATUS_SCAN_MS,
     STOP_ANNOUNCE_MS,
@@ -72,6 +81,9 @@ import { isSelfOrDescendant, processStart } from "./proc.js";
 import { resumeArgvFor } from "./resume.js";
 import { createRegistry, WORK_TICK_MS } from "./sessions.js";
 import { statusFor, writesSnapshots } from "./snapshot.js";
+import { CLIENT_PREFIX, createSpecsModule, mountSpecs, SPECS_AGENT_PATH, SPECS_KEYS_PATH, SPECS_PREFIX } from "./specs.js";
+import { documentPolicy, toolDocumentFor, withNonce } from "./tool-document.js";
+import { framedLine, reduceLine } from "./typed-line.js";
 
 // node-pty is a native CommonJS addon; load it through createRequire under ESM.
 const require = createRequire(import.meta.url);
@@ -346,6 +358,64 @@ app.use("/vendor/xterm", express.static(join(import.meta.dirname, "node_modules"
 app.use("/vendor/xterm", express.static(join(import.meta.dirname, "node_modules", "@xterm", "xterm", "lib")));
 app.use("/vendor/xterm-fit", express.static(join(import.meta.dirname, "node_modules", "@xterm", "addon-fit", "lib")));
 
+// The pane's tool clients, built elsewhere and baked beside this directory. Open like the statics above, and
+// CORS-readable on top of it: a tool renders in a frame with an opaque origin, so it fetches its own module
+// scripts cross-origin and a browser will not run them without being told they may be read. Nothing here is
+// secret and nothing here drives anything - the data behind a tool is gated separately, in specs.js.
+//
+// `frame-ancestors` is the one thing that is not open. A tool's document is only ever framed by this
+// interface, and framed by it inside a sandbox; a page somewhere else could otherwise frame the same document
+// without one and run it as an ordinary document on this origin.
+//
+// The document of a tool is served ahead of the statics, under a policy of its own: it is the one file here
+// that runs anything, and the frame it runs in has an opaque origin, where a policy written with `'self'`
+// names nobody. See tool-document.js.
+// Which origin the policy names has to come from the request. The browser reaches this server through a
+// port the host published, and the container is not told which one, so `Host` is the only place the origin
+// the document actually loaded from is written down. That makes it the caller's word, and it goes into a
+// response header, so it is taken only in the shape an authority has: a host and an optional port, and
+// nothing that could end the header or name a scheme. Anything else falls back to the address inside the
+// container, which names no outside origin and so grants nothing.
+const AUTHORITY = /^[A-Za-z0-9._-]+(:\d{1,5})?$|^\[[0-9A-Fa-f:.]+\](:\d{1,5})?$/;
+
+function originOf(req) {
+    const host = req.get("host") ?? "";
+    return AUTHORITY.test(host) ? `http://${host}` : `http://127.0.0.1:${PORT}`;
+}
+
+// The wildcard is express 4's, which is what this directory's package.json pins. Express 5 spells the same
+// thing `/*splat`, and that spelling compiles here to a route that ends in the literal word - it matches
+// nothing anyone loads, and the document falls through to the statics below with no policy on it at all.
+// The failure is silent, which is why a test issues a real request through a real express instead of
+// reading this line.
+app.get(`${CLIENT_PREFIX}/*`, (req, res, next) => {
+    const document = toolDocumentFor(req.path);
+    if (!document) return next();
+    let html;
+    try {
+        html = readFileSync(join(PANE_APPS_CLIENT_DIR, document), "utf8");
+    } catch {
+        return next();
+    }
+    const nonce = randomBytes(16).toString("base64");
+    res.set("Access-Control-Allow-Origin", "*");
+    res.set("Content-Security-Policy", documentPolicy(nonce, originOf(req)));
+    res.set("X-Content-Type-Options", "nosniff");
+    // A nonce is good for one response, so the document it sits in is never a document to keep.
+    res.set("Cache-Control", "no-store");
+    res.type("html").send(withNonce(html, nonce));
+});
+
+app.use(
+    CLIENT_PREFIX,
+    express.static(PANE_APPS_CLIENT_DIR, {
+        setHeaders: (res) => {
+            res.set("Access-Control-Allow-Origin", "*");
+            res.set("Content-Security-Policy", "frame-ancestors 'self'");
+        },
+    }),
+);
+
 // Accept a raw image body (the client POSTs the pasted/dropped blob with its Content-Type).
 // Reject non-image types up front; limit the size so a bad request cannot fill the disk.
 app.post("/upload", requireKey, express.raw({ type: () => true, limit: MAX_UPLOAD_BYTES }), (req, res) => {
@@ -549,6 +619,25 @@ function sessionForPid(pid) {
     return null;
 }
 
+// --- The Specs tool ----------------------------------------------------------------------------------------------------------------------
+//
+// The first of the pane's tools, mounted the way the pane store is: something built elsewhere is handed what
+// only this process can give it - where to look, and who to tell when the disk moves - and its answers are
+// registered behind gates it does not hold itself. It is not a process and not a port: a failure inside it is
+// one request answered with a status, and every terminal in this container carries on.
+
+const specs = mountSpecs({
+    module: createSpecsModule({ root: SPECS_ROOT, onChange: (change) => broadcastSpecs(change) }),
+    key: SPECS_KEY,
+    rawToken: SPECS_RAW_TOKEN,
+});
+
+// A spec directory moved. Every window hears it, not one: a spec belongs to the repository rather than to a
+// session, and two windows reading the same spec both need to know.
+function broadcastSpecs(change) {
+    for (const client of clients) send(client, { t: "specs", change });
+}
+
 // --- The status strip --------------------------------------------------------------------------------------------------------------------
 //
 // A claude session's own numbers, above the composer: the model, the context it is holding, what is left of
@@ -806,6 +895,185 @@ function nudge(session, title, path) {
     pasteToSession(session, `[web pane] Feedback submitted on "${quoted}" - read ${homeLabel(path)}`);
 }
 
+// --- Specs routes ------------------------------------------------------------------------------------------------------------------------
+
+/**
+ * The scoped credentials, for the shell alone. It holds the master key already, so nothing new is exposed by
+ * telling it these; what matters is where they go next - the shell posts the key into the tool's frame once,
+ * and the frame presents it as a header. Behind the pane's gate, which is the master key in a header and
+ * never in a URL, because a URL that carries it is a URL a document can read itself out of.
+ */
+app.get(SPECS_KEYS_PATH, requirePaneKey, (_req, res) => {
+    res.json({ key: SPECS_KEY, raw: specs.rawBase });
+});
+
+/**
+ * The `specs` helper's door: the agent's half of the coordination channel.
+ *
+ * The gate is the master key, which every helper route takes and which nothing outside the container has.
+ * The session behind it is a claim rather than a second gate: the helper sends its own pid, this walks up
+ * the process tree to see whether it lands in a session this server started, and any process in the
+ * container could send another process's pid instead - the same rule `webpane` publishes under, and its
+ * docstring says the same of itself. What that buys is a helper run outside a web session getting a clear
+ * answer rather than a silent one, and it is not asked to buy more: the session is used for nothing else,
+ * because a verb moves files in a spec directory, which belongs to the repository rather than to a terminal.
+ */
+app.post(SPECS_AGENT_PATH, requirePaneKey, express.json({ limit: MAX_SPECS_BYTES }), (req, res) => {
+    const session = sessionForPid(Number(req.headers["x-specs-pid"]));
+    if (!session) {
+        res.status(409).json({ error: "not running inside a web session - there is no pane to tell" });
+        return;
+    }
+    const body = req.body && typeof req.body === "object" ? req.body : {};
+    const answer = specs.agent({ verb: body.verb, entry: body.spec, payload: body.payload });
+    res.status(answer.status).json(answer.body);
+});
+
+// The body of a Specs request, read only for a request the mount says may carry one. Reading it is itself
+// something a caller gets to make this process do - hold the bytes, decode them - so it sits behind the same
+// key as the route, rather than in front of it where every other body route in this file would not put it.
+const specsBody = express.text({ type: () => true, limit: MAX_SPECS_BYTES });
+
+/**
+ * Everything else the tool answers. One delegation and no decision: specs.js takes the request as plain data
+ * and gives back the status, the headers and the body, and it never throws, so a Specs failure is a view that
+ * says so rather than a process that went down.
+ */
+app.all(
+    `${SPECS_PREFIX}/*`,
+    (req, res, next) => {
+        if (specs.takesBody(req.method, req.path, req.headers)) specsBody(req, res, next);
+        else next();
+    },
+    (req, res) => {
+        const answer = specs.handle({
+            method: req.method,
+            path: req.path,
+            query: req.query,
+            headers: req.headers,
+            body: req.body,
+        });
+        res.status(answer.status).set(answer.headers);
+        if (answer.body === null) {
+            res.end();
+            return;
+        }
+        // A workspace file goes out as its own bytes, under the type the tool decided; the rest is JSON.
+        if (Buffer.isBuffer(answer.body)) res.send(answer.body);
+        else res.json(answer.body);
+    },
+);
+
+// --- The Specs delivery ------------------------------------------------------------------------------------------------------------------
+//
+// Everything the pane sends the agent lands as a file plus one typed line. The file is written through the
+// data routes above, by the tool; this is the line. It rides the window's own socket, so the session it
+// reaches is the session that window is driving - the tool never names one, and there is no id on the frame
+// for it to name.
+//
+// The words of the line are this server's. The event is a key into the table below, so a tool picks which of
+// a few sentences is typed and never what it says; the detail is the one part that came from somewhere else
+// and is reduced before it goes anywhere near a terminal; and the path has to be a file the tool itself
+// wrote, which the mount decides.
+
+// What a delivery may say it is. A key that is not here is not a delivery.
+const SPECS_EVENTS = {
+    annotations: "Annotations sent",
+    intake: "A new spec was filed",
+    answers: "A round of answers was submitted",
+    gate: "A gate was answered",
+    brief: "Pick up this spec",
+};
+
+// The gap and the total, per session, for as long as this container runs. Held here rather than in the
+// registry because they are about this one channel: a session that is closed and gone takes its count with
+// it, which is the same span the resume marker uses.
+const lastSpecsLine = new Map();
+const specsLineCount = new Map();
+
+/** Whether this session has had as much of this channel as it may have, and why. */
+function specsLimited(sid) {
+    const now = Date.now();
+    if (now - (lastSpecsLine.get(sid) ?? 0) < SPECS_LINE_MIN_INTERVAL_MS) {
+        return "that was just delivered - give it a moment";
+    }
+    if ((specsLineCount.get(sid) ?? 0) >= MAX_SPECS_LINES_PER_SESSION) {
+        return `this session has had the ${MAX_SPECS_LINES_PER_SESSION} deliveries it may have`;
+    }
+    return null;
+}
+
+function specsDelivered(sid) {
+    lastSpecsLine.set(sid, Date.now());
+    specsLineCount.set(sid, (specsLineCount.get(sid) ?? 0) + 1);
+}
+
+/**
+ * Type one Specs line into a session, or say why not.
+ *
+ * The length is checked before the reduction, so an over-limit detail is refused with a reason rather than
+ * cut into half a sentence - which is the one thing a silent trim would make unreadable.
+ *
+ * `after` is for a session this delivery has just started: the line waits for the agent to be there to read
+ * it, and the delivery is answered now, because the session did start and the line will follow.
+ */
+function typeSpecsLine(session, msg, after = 0) {
+    const event = SPECS_EVENTS[typeof msg.event === "string" ? msg.event : ""];
+    if (!event) return { ok: false, error: "that is not something the Specs tool delivers" };
+    const detail = typeof msg.detail === "string" ? msg.detail : "";
+    if (detail.length > MAX_SPECS_LINE_LENGTH) {
+        return { ok: false, error: `that message is longer than the ${MAX_SPECS_LINE_LENGTH} characters a delivery may carry` };
+    }
+    const limited = specsLimited(session.id);
+    if (limited) return { ok: false, error: limited };
+    // A path is optional - a briefing names no file - and one that is not a file this tool wrote is dropped
+    // rather than refused: the line still reads, and it names nothing that is not there.
+    const absolute = msg.path ? specs.fileFor(msg.path) : null;
+    const line = framedLine({
+        tag: "specs",
+        event,
+        detail: reduceLine(detail, MAX_SPECS_LINE_LENGTH),
+        path: absolute === null ? "" : homeLabel(absolute),
+    });
+    specsDelivered(session.id);
+    if (after > 0) {
+        // Only if that session is still there when the wait is over.
+        setTimeout(() => {
+            const still = registry.get(session.id);
+            if (still) pasteToSession(still, line);
+        }, after).unref();
+    } else {
+        pasteToSession(session, line);
+    }
+    console.log(`[webterm] specs: delivered to session "${session.name || session.label}"`);
+    return { ok: true };
+}
+
+/**
+ * A delivery from the Specs tool, arriving over the shell's own socket.
+ *
+ * With no session on this window there is nobody to tell, and the tool has already asked the user whether to
+ * start one: `create` is that answer, and the briefing becomes the first line the new agent reads.
+ */
+function deliverSpecs(ws, msg) {
+    const session = registry.sessionFor(ws);
+    if (session) {
+        send(ws, { t: "specs:delivered", ...typeSpecsLine(session, msg) });
+        return;
+    }
+    if (msg.create !== true) {
+        send(ws, { t: "specs:delivered", ok: false, error: "no-session" });
+        return;
+    }
+    newSession(ws);
+    const started = registry.sessionFor(ws);
+    if (!started) {
+        send(ws, { t: "specs:delivered", ok: false, error: "a session could not be started" });
+        return;
+    }
+    send(ws, { t: "specs:delivered", ...typeSpecsLine(started, msg, SPECS_NEW_SESSION_DELAY_MS) });
+}
+
 // --- Resume, once per container start ----------------------------------------------------------------------------------------------------
 
 // PID 1 is CONTAINER_KEEP_ALIVE, so it starts when the container does and its start time is a different
@@ -1110,6 +1378,11 @@ function handleFrame(ws, msg) {
         case "paste":
             if (typeof msg.data === "string") paste(ws, msg.data);
             return;
+        case "specs:deliver":
+            // The pane's tool telling the agent something arrived. Like the pane's own frames, it reaches
+            // the session this window is driving, and the frame carries no id for it to reach another.
+            deliverSpecs(ws, msg);
+            return;
         case "resize":
             resize(ws, msg.cols, msg.rows);
             return;