chamba 0.7.0 → 0.8.0

package/templates/webterm/specs.js

@@ -1,358 +0,0 @@
-// =========================================================================================================================================
-// 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();
-        },
-    };
-}