chamba 0.6.1 → 0.7.0

package/templates/webterm/specs.js

@@ -0,0 +1,358 @@
+// =========================================================================================================================================
+// specs.js - The Specs tool, as webterm mounts it.
+//
+// The tool's own knowledge - what a root of specs holds, what one spec holds, what it writes - is a module
+// built elsewhere and bundled into one file (see ../pane-apps/). This is the mount around it: the credentials
+// that open it, the rules about which request may reach which part of it, and the shape of every answer.
+//
+// One function decides all of that. `handle()` takes a request as plain data and gives back a status, headers
+// and a body, and never throws: a module that fails answers with a status, so a bug in spec reading costs the
+// tab its view and nothing else. The express side is one delegation in server.js, and holds no decision.
+//
+// Three kinds of request reach the tool, each with its own credential, and neither credential opens anything
+// but its own kind:
+//   - The tool's client, a document and its assets, served open by server.js like every other static file.
+//     It holds nothing secret and drives nothing, and its responses are CORS-readable because the client runs
+//     with an opaque origin and fetches its own module scripts cross-origin.
+//   - The data routes, gated by a Specs-scoped key the shell hands into the frame, presented as a header and
+//     never in a URL. These alone answer the cross-origin preflight that header needs.
+//   - Workspace-file loads, gated by a raw-route token that rides as a path segment, because a frame and an
+//     image cannot send a header.
+// The master key opens none of this, and none of this opens the master key: a rendering bug inside the frame
+// leaks spec reading at worst, never the key that types into terminals.
+// =========================================================================================================================================
+
+import { timingSafeEqual } from "node:crypto";
+import { BadRequest, createSpecsModule, statusFor } from "../pane-apps/server/specs.mjs";
+
+// The module maker, re-exported so the path to the built dist is written once. webterm resolves the pane apps
+// as a sibling directory, which is where the image bakes them and where a checkout stages them.
+export { createSpecsModule };
+
+// The header the Specs key travels in. A header rather than a URL for the reason the pane's key is one: a
+// document can read the URL it was loaded from, and workspace content renders inside this tool.
+export const SPECS_KEY_HEADER = "x-specs-key";
+
+// Everything the tool answers sits under one prefix, and the two kinds are told apart by the next segment.
+export const SPECS_PREFIX = "/specs";
+export const SPECS_KEYS_PATH = "/specs/keys";
+// The `specs` helper's door. Behind the master key like every other helper route, and behind being a process
+// inside a session as well.
+export const SPECS_AGENT_PATH = "/specs/agent";
+export const API_PREFIX = "/specs/api/";
+export const RAW_PREFIX = "/specs/raw/";
+
+// Where the built tool clients are served from. Open statics, one directory per tool.
+export const CLIENT_PREFIX = "/pane-apps";
+
+// Read by the frame, which has an opaque origin, so every answer it may read says so. It carries no
+// credential of its own - the browser sends none without `Access-Control-Allow-Credentials`, which nothing
+// here sends - so this opens a route to any origin that already holds the key the route asks for.
+//
+// The data routes alone. Workspace files are not readable cross-origin by anybody: a jailed document can read
+// the token out of its own URL, and making the files it opens readable as well would turn one rendering bug
+// into every spec in the repository, posted anywhere. A frame and an image need no permission to render.
+const CORS_OPEN = { "Access-Control-Allow-Origin": "*" };
+
+// The media types the data routes hand back as text, which is what this client reads rather than renders.
+// Everything else - a page, a diagram, a stylesheet, an image - is something a browser renders for itself,
+// and is loaded from the workspace-file path, where a frame and an image reach it without sending a header.
+// An allowlist rather than a family, because `text/html` is in the family and is exactly the wrong side of
+// this line.
+const TEXTUAL = new Set(["text/markdown", "text/plain", "application/json"]);
+
+// The jail on workspace bytes, sent whatever the media type. Unconditional on purpose: a per-type list would
+// put the one control between workspace content and this origin at the mercy of an enumeration, and the next
+// scriptable type would walk past it. The sandbox token set is the one /pane/page already sends.
+const JAIL = {
+    "Content-Security-Policy": "sandbox allow-scripts allow-forms",
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "no-store",
+};
+
+/** One query or header value as a string. A repeated parameter parses to an array, which is not a value. */
+function field(value) {
+    return typeof value === "string" ? value : "";
+}
+
+/** Whether a presented credential is the live one, compared in constant time. */
+function holds(presented, secret) {
+    if (typeof presented !== "string" || presented === "") return false;
+    // Byte lengths, not string lengths: timingSafeEqual throws on a length mismatch, and a multi-byte
+    // character makes those two differ.
+    const shown = Buffer.from(presented);
+    const live = Buffer.from(secret);
+    if (shown.length !== live.length) return false;
+    return timingSafeEqual(shown, live);
+}
+
+/**
+ * What a caller is told a failure was.
+ *
+ * The module's own words name the path it was asked for, which is the caller's own text. Anything else came
+ * from below it, and those messages carry the container path the tool resolved to - which no caller needs and
+ * which the log is the place for.
+ */
+function reason(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith("specs:")) return message;
+    console.warn(`[webterm] specs: ${message}`);
+    return "that could not be read";
+}
+
+/** A workspace path as the URL spells it, one segment at a time. Throws for a segment that is not a path. */
+function decodePath(rest) {
+    return rest
+        .split("/")
+        .map((segment) => decodeURIComponent(segment))
+        .join("/");
+}
+
+/**
+ * Mount the Specs module behind its credentials.
+ *
+ * `module` is what the tool knows, made by createSpecsModule and handed in the way paneStore is handed to the
+ * pane: this file decides who may ask, never what the answer is. `key` opens the data routes and `rawToken`
+ * opens the workspace files, and the two are separate so that neither one is the other's spare.
+ */
+export function mountSpecs({ module, key, rawToken }) {
+    // The data set, as one table. The gate, the preflight answer and the router all read it, so they cannot
+    // disagree about which routes exist or which methods each one takes.
+    const DATA = {
+        dashboard: { GET: () => module.dashboard() },
+        entry: { GET: (query) => module.entry(field(query.path)) },
+        state: {
+            GET: (query) => module.state(field(query.entry)),
+            PUT: (query, body) => {
+                module.writeState(field(query.entry), body);
+                return { ok: true };
+            },
+        },
+        feedback: {
+            GET: (query) => ({ rounds: module.filed(field(query.entry)) }),
+            POST: (query, body) => module.feedback(field(query.entry), body),
+        },
+        file: { GET: (query) => textOf(field(query.path)) },
+        // The protocol, as the reader sees and answers it. What an agent posts is not here: it arrives at the
+        // helper's door below, which is gated by being inside a session rather than by holding this key.
+        stages: { GET: () => ({ stages: module.stages() }) },
+        protocol: { GET: (query) => module.specState(field(query.entry)) },
+        // A declared round or gate as it was written. Read through the tool rather than as a workspace file:
+        // it lives in the dot-directory, which the file route refuses on purpose.
+        round: { GET: (query) => module.round(field(query.entry), field(query.id)) },
+        intake: { POST: (_query, body) => module.intake(body) },
+        confirm: { POST: (query, body) => module.confirm(field(query.entry), body) },
+        // The user answering a gate, a round or a decision card. The agent's side of the same file is a verb
+        // at the helper's door, so neither caller can do the other's half.
+        answer: { POST: (query, body) => module.answer(field(query.entry), field(query.id), body) },
+    };
+
+    // The helper's verbs, which an agent reaches from inside a session. A verb that is not here is not one.
+    const VERBS = {
+        // The first call any agent makes: it answers whether there is a pane at all, and where the specs
+        // this pane serves live. An agent writing into a spec needs a path, and the root is a mount
+        // parameter, so nothing it could work out for itself.
+        stages: () => ({ root: module.root, stages: module.stages() }),
+        state: (entry) => module.specState(entry),
+        intake: (_entry, payload) => module.intake(payload),
+        propose: (entry, payload) => module.propose(entry, payload),
+        await: (entry, payload) => module.declare(entry, payload),
+        post: (entry, payload) => module.post(entry, payload),
+        review: (entry, payload) => module.review(entry, payload),
+        answers: (entry, payload) => ({ answer: module.answers(entry, field(payload?.id)) }),
+    };
+
+    /** One workspace file as text. Anything a page renders rather than reads is refused to this route. */
+    function textOf(path) {
+        const read = module.file(path);
+        const type = read.mediaType.split(";")[0].trim();
+        if (!TEXTUAL.has(type)) throw new BadRequest(`${path} is not read as text - load it as a workspace file`);
+        return { path, mediaType: read.mediaType, size: read.size, modified: read.modified, text: read.bytes.toString("utf8") };
+    }
+
+    /**
+     * The route a path names, or undefined.
+     *
+     * Through `Object.hasOwn`, because everything inherits `constructor`, `toString` and their neighbours: a
+     * plain lookup would answer for `/specs/api/constructor` and make a name that is not a route act like one.
+     */
+    function routeFor(path) {
+        const name = path.slice(API_PREFIX.length);
+        return Object.hasOwn(DATA, name) ? DATA[name] : undefined;
+    }
+
+    /** The path a workspace file is loaded from. The token is a segment because a frame sends no headers. */
+    const rawBase = `${RAW_PREFIX}${rawToken}`;
+
+    function refused(what) {
+        return { status: 403, headers: CORS_OPEN, body: { error: what } };
+    }
+
+    // The preflight the Specs key header needs, answered for the data routes and for nothing else. A route
+    // that is not in the table gets no `Access-Control-Allow-` header at all, which is what a browser reads as
+    // "not allowed" rather than as an answer it may act on.
+    function preflight(path) {
+        const route = routeFor(path);
+        if (!route) return { status: 403, headers: {}, body: { error: "not a Specs data route" } };
+        return {
+            status: 204,
+            headers: {
+                ...CORS_OPEN,
+                "Access-Control-Allow-Methods": Object.keys(route).join(", "),
+                "Access-Control-Allow-Headers": `${SPECS_KEY_HEADER}, content-type`,
+                "Access-Control-Max-Age": "600",
+            },
+            body: null,
+        };
+    }
+
+    function data(method, path, query, body, headers) {
+        const route = routeFor(path);
+        if (!route) return { status: 404, headers: CORS_OPEN, body: { error: "no such Specs route" } };
+        // The gate before the body: a caller without the key learns nothing about what a body would have done.
+        if (!holds(field(headers[SPECS_KEY_HEADER]), key)) {
+            return refused(`the Specs routes take their key in the ${SPECS_KEY_HEADER} header`);
+        }
+        const handler = route[method];
+        if (!handler) {
+            const allowed = Object.keys(route).join(", ");
+            return { status: 405, headers: { ...CORS_OPEN, Allow: allowed }, body: { error: `this route takes ${allowed}` } };
+        }
+        let payload = null;
+        if (body !== null && body !== undefined && body !== "") {
+            try {
+                payload = typeof body === "string" ? JSON.parse(body) : body;
+            } catch {
+                return { status: 400, headers: CORS_OPEN, body: { error: "the body is not JSON" } };
+            }
+        }
+        try {
+            return { status: 200, headers: CORS_OPEN, body: handler(query, payload) };
+        } catch (error) {
+            return { status: statusFor(error), headers: CORS_OPEN, body: { error: reason(error) } };
+        }
+    }
+
+    function raw(method, path, headers) {
+        // The jail rides on every answer this route gives, a refusal included: the rule is about the route,
+        // not about the happy path, and a body that says why is still workspace-shaped text.
+        const base = { ...JAIL };
+        if (method !== "GET" && method !== "HEAD") {
+            return { status: 405, headers: { ...base, Allow: "GET, HEAD" }, body: { error: "this route takes GET, HEAD" } };
+        }
+        // Frame and subresource only. The jail's second mechanism is the sandbox of whatever embeds the file,
+        // and a top-level document has no embedder - it would rest on the header alone, which is the
+        // one-mechanism state the content boundary forbids, and a top-level document can do more on an origin
+        // than a framed one can.
+        //
+        // A request that says nothing about where it is going is refused with it. Reading an absent header as
+        // "not a document" would hand that refusal to whoever leaves the header off, and the cost of the
+        // other way round is visible and small: in a browser that sends no Fetch Metadata, workspace files do
+        // not render.
+        const dest = field(headers["sec-fetch-dest"]);
+        if (dest === "" || dest === "document") {
+            return { status: 403, headers: base, body: { error: "a workspace file renders inside the tool, not as a page of its own" } };
+        }
+        const rest = path.slice(RAW_PREFIX.length);
+        const cut = rest.indexOf("/");
+        if (!holds(cut === -1 ? rest : rest.slice(0, cut), rawToken)) {
+            return { status: 403, headers: base, body: { error: "the workspace files take their token in the path" } };
+        }
+        let wanted = "";
+        try {
+            wanted = decodePath(cut === -1 ? "" : rest.slice(cut + 1));
+        } catch {
+            return { status: 400, headers: base, body: { error: "that path cannot be read" } };
+        }
+        try {
+            const file = module.file(wanted);
+            return { status: 200, headers: { ...base, "Content-Type": file.mediaType }, body: file.bytes };
+        } catch (error) {
+            return { status: statusFor(error), headers: base, body: { error: reason(error) } };
+        }
+    }
+
+    return {
+        /** The root the module resolved, so the mount can say what it is serving. */
+        root: module.root,
+        /** The path prefix a workspace file is loaded from, token included. Handed to the frame, never logged. */
+        rawBase,
+
+        /**
+         * Where a file the tool wrote sits on disk, or null.
+         *
+         * What a typed line is allowed to name. The module refuses any path that is not inside a `.specs/`,
+         * so a delivery can point an agent at something this tool wrote and at nothing else - not at a file
+         * of the workspace, and not at anything outside the served root.
+         */
+        fileFor(path) {
+            try {
+                return module.toolPath(field(path));
+            } catch {
+                return null;
+            }
+        },
+
+        /**
+         * Answer one verb from the `specs` helper.
+         *
+         * The other half of the coordination channel: the pane writes a file and types a line, and an agent
+         * moves the work through these. There is no key here on purpose - the caller is gated by being a
+         * process inside a session this server started, which server.js works out from the caller's pid, the
+         * way it does for `webpane`. A key on disk would add nothing, since everything in the container can
+         * read the one that is there.
+         */
+        agent({ verb, entry, payload }) {
+            const name = field(verb);
+            if (!Object.hasOwn(VERBS, name)) {
+                return { status: 400, body: { error: `specs: no verb named ${name || "(none)"}` } };
+            }
+            try {
+                return { status: 200, body: VERBS[name](field(entry), payload ?? null) };
+            } catch (error) {
+                return { status: statusFor(error), body: { error: reason(error) } };
+            }
+        },
+
+        /**
+         * Answer one request under the Specs prefix.
+         *
+         * Takes the request as plain data - method, path, query, headers, body - and gives back `{ status,
+         * headers, body }`, where the body is a Buffer for a workspace file, an object for everything else,
+         * and null for an answer that carries none. It never throws.
+         */
+        handle({ method, path, query, headers, body }) {
+            const verb = String(method || "GET").toUpperCase();
+            const where = String(path || "");
+            // The path decides first and the method second, so the workspace-file route answers everything
+            // under it - a preflight included, which it refuses as a method it does not take, with the jail on
+            // the refusal like every other answer it gives.
+            if (where.startsWith(RAW_PREFIX)) return raw(verb, where, headers ?? {});
+            if (where.startsWith(API_PREFIX)) {
+                if (verb === "OPTIONS") return preflight(where);
+                return data(verb, where, query ?? {}, body, headers ?? {});
+            }
+            return { status: 404, headers: {}, body: { error: "no such Specs route" } };
+        },
+
+        /**
+         * Whether this request may carry a body at all.
+         *
+         * Asked before a body is read, so nothing without the key reaches a parser - not the JSON one, and not
+         * the buffering underneath it, which would otherwise hold whatever an anonymous caller sent up to the
+         * body limit. The rule is the same one the data routes are gated by; it is answered earlier.
+         */
+        takesBody(method, path, headers) {
+            const verb = String(method || "").toUpperCase();
+            const where = String(path || "");
+            if ((verb !== "POST" && verb !== "PUT") || !where.startsWith(API_PREFIX)) return false;
+            if (!routeFor(where)?.[verb]) return false;
+            return holds(field(headers?.[SPECS_KEY_HEADER]), key);
+        },
+
+        /** Stop watching the root. The mount holds nothing else that outlives it. */
+        close() {
+            module.close();
+        },
+    };
+}

package/templates/webterm/tool-document.js

@@ -0,0 +1,67 @@
+// =========================================================================================================================================
+// tool-document.js - The policy a tool's own document is served under.
+//
+// A tool client runs in a frame that is sandboxed without allow-same-origin, so its document has an opaque
+// origin. That is what keeps a bug in spec rendering away from the key that types into terminals, and it is
+// also why this document cannot be served under the policy everything else on this origin is: `'self'` names
+// the document's own origin, an opaque origin is nobody, and a directive that names it matches nothing at
+// all. A policy written with `'self'` in it therefore does not tighten this document - it turns its own
+// scripts off.
+//
+// So the execution directives name no origin. What may run is named by a nonce this server puts on the two
+// elements it built the document with, and the directives that decide where bytes may be fetched from name
+// the origin the document was loaded from - which is this server, and which is where the tool's assets, its
+// data routes and its jailed workspace files all live.
+//
+// Everything here is a pure function of its inputs. server.js reads the file, makes the nonce, and sends the
+// answer; the rules are decided here, where a test can run them.
+// =========================================================================================================================================
+
+// Where the built tool clients are served from, and the one document each tool has. The tool name is spelled
+// out rather than taken from the URL, so no path a caller writes ever reaches the filesystem through here.
+const DOCUMENT_PATH = /^\/pane-apps\/([a-z0-9-]+)\/index\.html$/;
+
+/**
+ * The document a URL asks for, as a path relative to the built clients directory, or null when the URL asks
+ * for something else - an asset, a stylesheet, a name that is not a tool.
+ */
+export function toolDocumentFor(urlPath) {
+    const asked = DOCUMENT_PATH.exec(String(urlPath || ""));
+    return asked ? `${asked[1]}/index.html` : null;
+}
+
+/**
+ * The document with its nonce on it.
+ *
+ * The build emits one module script and one stylesheet link, and both have to carry the nonce, because the
+ * policy below names nothing else that may run or style. This is a rewrite of a file this build made, not of
+ * anything a workspace wrote: no content from the served root passes through here.
+ */
+export function withNonce(html, nonce) {
+    return String(html).replace(/<(script|link)\b/gi, (tag) => `${tag} nonce="${nonce}"`);
+}
+
+/**
+ * The policy the document is sent under.
+ *
+ * `default-src 'none'` is the floor, so anything not named below is refused. What runs is named by the nonce
+ * alone. What is fetched is named by `origin` - the scheme and host the document was loaded from - because
+ * the client's own assets, the tool's data routes and the jailed workspace files are all served from here,
+ * and an opaque origin has no `'self'` to say that with. `base-uri` and `form-action` are named on their own,
+ * since neither one falls back to `default-src`.
+ */
+export function documentPolicy(nonce, origin) {
+    return [
+        "default-src 'none'",
+        `script-src 'nonce-${nonce}'`,
+        `style-src-elem 'nonce-${nonce}'`,
+        `img-src ${origin}`,
+        `connect-src ${origin}`,
+        `frame-src ${origin}`,
+        "base-uri 'none'",
+        "form-action 'none'",
+        // The document is framed by this interface and by nothing else. Without it a page elsewhere could
+        // frame the same document with no sandbox and run it as an ordinary document on this origin.
+        "frame-ancestors 'self'",
+    ].join("; ");
+}

package/templates/webterm/typed-line.js

@@ -0,0 +1,85 @@
+// =========================================================================================================================================
+// typed-line.js - What a message is reduced to before a terminal ever sees it.
+//
+// A tool in the pane tells the agent beside it that something arrived, by typing one line into that agent's
+// terminal. The line is framed - `[specs] <event>: "<detail>" - read <path>` - and the frame is a visual
+// convention, so what this file protects is how the line reads. An agent must be able to tell the server's
+// own words from a message's, and no message may pose as a second voice.
+//
+// The text rides a bracketed paste, where a newline is not a second submit but a second visible line inside
+// the same prompt. So a text carrying one would show the agent a line below the framed one, in no frame at
+// all. Reduction to a single line is what closes that, and it starts from the shipped single-line cleaner:
+// controls dropped, whitespace runs collapsed, ends trimmed.
+//
+// That cleaner needs two corrections here, and both live in this wrapper, so the pane's titles and its nudge
+// keep the behaviour they have.
+//
+//   - Its length argument defaults to a page title's length, which would cut a message to a fragment. The
+//     limit is checked before the reduction instead, and an over-limit message is refused with a reason.
+//   - Its character rule keeps every code point at or above U+00A0, which leaves every invisible one alive.
+//     The rule this path needs is "renders as nothing", and no single Unicode property means that, so it is
+//     built from what survives rather than from what does not - in two layers, and it needs both.
+// =========================================================================================================================================
+
+import { cleanLine } from "./artifacts.js";
+
+// The first layer: the categories a visible character is in. Letters, the marks that combine with them,
+// numbers, and the common punctuation and symbol categories, plus the one space the collapse produces.
+// Nothing outside them survives, whatever it is and whenever it was assigned - which ends the format
+// characters, the bidi controls, and the tag block at U+E0000, since all three are format characters and
+// none of those is a category here. The tag block is worth naming: it is a complete invisible copy of
+// printable ASCII, and it is the carrier a hidden second instruction actually travels in.
+const VISIBLE = /[\p{L}\p{M}\p{N}\p{P}\p{S} ]/u;
+
+// The second layer: what the first keeps by accident. The allowed categories hold blank-rendering members of
+// their own - U+3164 HANGUL FILLER is a letter, the variation selectors are combining marks, U+2800 BRAILLE
+// PATTERN BLANK is a symbol - so a category allowlist alone passes all three at full width. Every code point
+// carrying Default_Ignorable_Code_Point goes whatever its category, which covers the fillers and the
+// selectors. U+2800 is then named, because it carries no such property and nothing else separates it from
+// the braille it belongs to. That one code point is the only closed part of the rule.
+const BLANK = /[\p{Default_Ignorable_Code_Point}\u2800]/u;
+
+// No surviving code point can be confusable with the frame's quote, so every one that reads as a double
+// quote is mapped to a single one - the way the pane's nudge already does for the ASCII quote alone. The
+// rule is what a code point looks like rather than what it is called, so the property is no help: the
+// quotation-mark property leaves out the double primes, the gershayim, the modifier letters that render as
+// a pair of ticks, and the double acute, and each of those closes the frame on screen just as well.
+const DOUBLE_QUOTES =
+    /["\u00ab\u00bb\u02ba\u02dd\u02ee\u02f6\u05f4\u201c\u201d\u201e\u201f\u2033\u2036\u275d\u275e\u2e42\u3003\u301d\u301e\u301f\uff02]|[\u{1f676}-\u{1f678}]/gu;
+
+/**
+ * One line of somebody else's text, safe to put inside the frame.
+ *
+ * A code point outside the visible categories becomes a space, which the cleaner then collapses: it was a
+ * control, a separator or a format character, and a space is what it was standing in for. One that renders
+ * as nothing inside an allowed category is removed rather than spaced, because it was padding rather than a
+ * gap - which is what keeps a padded tail inside the quotes instead of pushed off the row.
+ */
+export function reduceLine(raw, max) {
+    if (typeof raw !== "string") return "";
+    let kept = "";
+    for (const ch of raw) {
+        if (BLANK.test(ch)) continue;
+        kept += VISIBLE.test(ch) ? ch : " ";
+    }
+    return cleanLine(kept.replace(DOUBLE_QUOTES, "'"), max);
+}
+
+/**
+ * The line itself.
+ *
+ * `tag` and `event` are the caller's own words and never a message's, so a tool's text sits inside
+ * delimiters it cannot close and cannot pose as the user or as another source. `detail` is the only part
+ * that arrives here already reduced.
+ *
+ * `path` is a path this server built, but it is not made of this server's words: every segment of it is a
+ * name off the filesystem, and a name may hold any byte but the separator. So it goes through the same
+ * reduction, and it is named only when the reduction changed nothing. A path that changed is not a path any
+ * more - naming the reduced spelling would send the agent to a file that does not exist - and a path holding
+ * anything the reduction removes is the one case where naming no file is the honest line.
+ */
+export function framedLine({ tag, event, detail, path }) {
+    const said = detail ? `: "${detail}"` : "";
+    const named = path && reduceLine(path, path.length) === path ? path : "";
+    return `[${tag}] ${event}${said}${named ? ` - read ${named}` : ""}`;
+}