@songsid/agend 2.1.12-beta.9 → 2.2.0-alpha.1

package/dist/web-preview.js

@@ -0,0 +1,240 @@
+/**
+ * #1306: the preview listener — where an agent's HTML may run, away from the dashboard's authority.
+ * Design: docs/design/1306-inline-html-preview.md (r3, approved).
+ *
+ * A second loopback listener (default health_port + 1) serves one static document, `GET /frame`: a shim that
+ * receives HTML by postMessage only from the dashboard origins it was built with, and writes it into its own
+ * opaque, sandboxed document. Everything else is an empty 404. It reads no cookie, no header but Host, and logs
+ * nothing about a request. The dashboard decides per /ui load whether a preview origin is reachable from the
+ * browser's address (Host only — never X-Forwarded-Host), and the page re-checks that against location.origin.
+ *
+ * What this does NOT promise: that a preview cannot send data out (WebRTC and self-navigation are known ways
+ * around the restrictions — design §4.3). It promises the account boundary only (G1): the preview cannot act as
+ * the signed-in person.
+ */
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { allowedHostNames, hostnameOf, LOOPBACK_HOST_NAMES } from "./web-host-guard.js";
+/** The most HTML a preview takes (UTF-8 bytes): the parent refuses more before sending, the shim refuses it too. */
+export const PREVIEW_HTML_MAX_BYTES = 1024 * 1024;
+/** The settings a fleet runs with: `web.preview`, `web.preview_port` (default health_port + 1), `web.preview_origin`. */
+export function previewSettings(web, healthPort) {
+    // An ephemeral web listener (port 0: tests, harnesses) gets an ephemeral preview listener; its real port is filled
+    // in once it listens (createPreviewListener). Otherwise the fixed default, so an SSH user can forward it too.
+    const port = typeof web?.preview_port === "number" && Number.isInteger(web.preview_port) ? web.preview_port
+        : healthPort === 0 ? 0 : healthPort + 1 <= 65535 ? healthPort + 1 : null;
+    const origin = typeof web?.preview_origin === "string" ? normalizeOrigin(web.preview_origin) : null;
+    return { enabled: web?.preview !== false, port, origin };
+}
+/** scheme://host[:port] for an http(s) URL with nothing else in it; null otherwise. A default port is dropped. */
+export function normalizeOrigin(value) {
+    let u;
+    try {
+        u = new URL(value.trim());
+    }
+    catch {
+        return null;
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:")
+        return null;
+    if (u.username || u.password || u.search || u.hash || (u.pathname !== "/" && u.pathname !== ""))
+        return null;
+    if (!u.hostname || u.hostname.includes("*"))
+        return null;
+    // The raw text must not carry a query/fragment marker either ("https://x/?" parses to an empty search).
+    if (/[?#]/.test(value))
+        return null;
+    return u.origin;
+}
+/**
+ * Why a `web.preview_origin` cannot be used, or null when it can (design §3.1). It must be a bare http(s) origin
+ * (no path, query, credentials or wildcard), and its host must not be one the dashboard answers to — that would be
+ * a same-origin preview by another name.
+ */
+export function previewOriginProblem(value, config) {
+    if (typeof value !== "string")
+        return "must be an origin such as https://preview.example.net";
+    const origin = normalizeOrigin(value);
+    if (!origin)
+        return "must be a bare http(s) origin — scheme, host and optional port; no path, query, fragment, credentials or wildcard";
+    const host = hostnameOf(new URL(origin).host);
+    if (!host || allowedHostNames(config).has(host))
+        return "must be a separate host name, not one the dashboard answers to (loopback names, hostname, web.allowed_hosts)";
+    return null;
+}
+const DEFAULT_PORT = { "http:": "80", "https:": "443" };
+/** scheme://host[:port] from a Host header the host guard already accepted; a default port is dropped. */
+export function dashboardOriginFor(hostHeader, secure) {
+    if (typeof hostHeader !== "string" || hostnameOf(hostHeader) === null)
+        return null;
+    const scheme = secure ? "https:" : "http:";
+    try {
+        return new URL(`${scheme}//${hostHeader.trim().toLowerCase()}`).origin;
+    }
+    catch {
+        return null;
+    }
+    // (URL drops a default port: http://x:80 → http://x, so it matches what the browser reports as location.origin.)
+}
+/**
+ * For one /ui request: a loopback Host and no preview_origin → the same loopback name on the preview port;
+ * preview_origin set → that; anything else (a tunnel, a proxy, `hostname`, `allowed_hosts`) → disabled.
+ * Only Host is read; X-Forwarded-Host never is.
+ */
+export function previewAvailability(settings, hostHeader, secure, accepted) {
+    const dashboardOrigin = dashboardOriginFor(hostHeader, secure);
+    const off = (reason) => ({ dashboardOrigin, previewOrigin: null, reason });
+    if (!settings || !settings.enabled)
+        return off("Previews are turned off for this fleet (web.preview: false).");
+    if (!dashboardOrigin)
+        return off("This address cannot be checked.");
+    if (settings.port === null && !settings.origin)
+        return off("Previews have no port: set web.preview_port (health_port is the highest port).");
+    // The page must be at an origin the shim takes HTML from (and that may frame it) — exactly, or a frame would never
+    // render. A name in web.allowed_hosts served on a non-default port must be listed with that port.
+    if (accepted && !accepted.includes(dashboardOrigin))
+        return off(`Previews are not offered at ${dashboardOrigin}: list this address (with its port) in web.allowed_hosts, and set web.preview_origin.`);
+    let preview;
+    if (settings.origin)
+        preview = settings.origin;
+    else {
+        const host = hostnameOf(hostHeader);
+        if (!LOOPBACK_HOST_NAMES.includes(host))
+            return off("Previews need web.preview_origin when the dashboard is reached through a tunnel or proxy.");
+        preview = `http://${host}:${settings.port}`;
+    }
+    // An https page cannot frame an http preview (mixed content).
+    if (dashboardOrigin.startsWith("https:") && preview.startsWith("http:"))
+        return off("Previews need an https web.preview_origin when the dashboard is reached over https.");
+    if (preview === dashboardOrigin)
+        return off("The preview origin cannot be the dashboard's own.");
+    return { dashboardOrigin, previewOrigin: preview, reason: null };
+}
+/**
+ * The exact dashboard origins a preview may be framed by, and accept HTML from (design §5.1): the loopback names on
+ * the dashboard's port, plus — when a preview_origin is set — `https://<name>` for each name the dashboard answers to
+ * besides loopback (`hostname`, `web.allowed_hosts`). Never 'self', never *.
+ */
+export function dashboardOrigins(settings, healthPort, config) {
+    // As the browser writes location.origin: a default port is dropped (http://127.0.0.1:80 → http://127.0.0.1).
+    const origin = (u) => { try {
+        return new URL(u).origin;
+    }
+    catch {
+        return null;
+    } };
+    const out = LOOPBACK_HOST_NAMES.map(h => origin(`http://${h}:${healthPort}`)).filter((o) => !!o);
+    if (settings.origin) {
+        // Each extra dashboard name as written — with its port when it has one (fleet.example.net:8443).
+        const extra = [config?.hostname, ...(Array.isArray(config?.web?.allowed_hosts) ? config.web.allowed_hosts : [])];
+        for (const entry of extra) {
+            if (typeof entry !== "string")
+                continue;
+            const name = hostnameOf(entry);
+            if (!name || LOOPBACK_HOST_NAMES.includes(name))
+                continue;
+            const o = origin(`https://${entry.trim().toLowerCase()}`);
+            if (o)
+                out.push(o);
+        }
+    }
+    return [...new Set(out)];
+}
+// ── The listener ────────────────────────────────────────────────────────────────────────────────────────────
+const PERMISSIONS_POLICY = "camera=(), microphone=(), geolocation=(), clipboard-read=(), clipboard-write=(), usb=(), serial=(), hid=(), bluetooth=(), payment=(), display-capture=(), fullscreen=()";
+/** The /frame response's Content-Security-Policy (design §5.1): exact, no 'self', no *. */
+export function previewFrameCsp(ancestors) {
+    return [
+        "default-src 'none'", "script-src 'unsafe-inline'", "style-src 'unsafe-inline'",
+        "img-src data: blob:", "font-src data:", "media-src data: blob:",
+        "connect-src 'none'", "worker-src 'none'", "frame-src 'none'", "child-src 'none'",
+        "form-action 'none'", "base-uri 'none'", "manifest-src 'none'", "object-src 'none'",
+        "webrtc 'block'",
+        `frame-ancestors ${ancestors.join(" ")}`,
+        "sandbox allow-scripts",
+    ].join("; ");
+}
+/**
+ * The shim (design §4): posts `ready` with the listener's boot id; takes ONE `render` — from its parent window, from
+ * an exact listed dashboard origin (never "null"), with exactly {v, type, ch, html}, html ≤ 1 MiB — removes the WebRTC
+ * entry points from its realm (defence in depth only), and writes a heartbeat/height prologue and the HTML into its
+ * own document. Every later message is ignored.
+ */
+export function buildShim(bootId, origins) {
+    const script = `(function () {
+  "use strict";
+  var BOOT = ${JSON.stringify(bootId)}, ORIGINS = ${JSON.stringify([...origins])}, MAX = ${PREVIEW_HTML_MAX_BYTES};
+  var done = false;
+  function bytes(s) { try { return new TextEncoder().encode(s).length; } catch (e) { return s.length * 3; } }
+  window.addEventListener("message", function (e) {
+    if (done || e.source !== window.parent || ORIGINS.indexOf(e.origin) < 0) return;
+    var d = e.data;
+    if (!d || typeof d !== "object" || Object.getPrototypeOf(d) !== Object.prototype) return;
+    if (Object.keys(d).sort().join(",") !== "ch,html,type,v" || d.v !== 1 || d.type !== "render") return;
+    if (typeof d.ch !== "string" || !/^[0-9a-f]{16,64}$/.test(d.ch) || typeof d.html !== "string" || bytes(d.html) > MAX) return;
+    done = true;
+    ["RTCPeerConnection", "webkitRTCPeerConnection", "RTCDataChannel", "RTCIceTransport", "RTCSctpTransport"].forEach(function (k) {
+      try { delete window[k]; } catch (x) { /* not configurable */ }
+      try { if (window[k]) Object.defineProperty(window, k, { value: undefined, configurable: false, writable: false }); } catch (x) { /* best effort */ }
+    });
+    var prologue = "<script>(function(){var ch=" + JSON.stringify(d.ch) + ",p=window.parent,last=-1;" +
+      "function size(){var h=Math.ceil(Math.max(document.documentElement?document.documentElement.scrollHeight:0,document.body?document.body.scrollHeight:0));" +
+      "if(h!==last){last=h;p.postMessage({v:1,type:\\"resize\\",ch:ch,height:h},\\"*\\");}}" +
+      "setInterval(function(){p.postMessage({v:1,type:\\"heartbeat\\",ch:ch},\\"*\\");},2000);" +
+      "p.postMessage({v:1,type:\\"heartbeat\\",ch:ch},\\"*\\");" +
+      "try{new ResizeObserver(size).observe(document.documentElement);}catch(e){setInterval(size,500);}" +
+      "addEventListener(\\"load\\",size);setTimeout(size,0);})();<\\/script>";
+    document.open();
+    document.write(prologue + d.html);
+    document.close();
+  });
+  window.parent.postMessage({ v: 1, type: "ready", ch: null, boot: BOOT }, "*");
+})();`;
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Preview</title></head><body><script>${script}</script></body></html>`;
+}
+/**
+ * The preview listener: GET /frame (no query) → the shim with the §5.1 headers; anything else → empty 404; a Host
+ * it does not answer to → empty 403. No X-Frame-Options (it must be framable by the dashboard), no cookie or
+ * header parsing beyond Host, nothing logged per request. Built once: the shim and its headers never change.
+ */
+export function createPreviewListener(opts) {
+    const bootId = opts.bootId ?? randomBytes(16).toString("hex");
+    const origins = dashboardOrigins(opts.settings, opts.healthPort, opts.config);
+    const body = Buffer.from(buildShim(bootId, origins), "utf8");
+    const headers = {
+        "Content-Type": "text/html; charset=utf-8",
+        "Content-Security-Policy": previewFrameCsp(origins),
+        "Permissions-Policy": PERMISSIONS_POLICY,
+        "Referrer-Policy": "no-referrer",
+        "Cross-Origin-Resource-Policy": "same-origin",
+        "X-Content-Type-Options": "nosniff",
+        "Cache-Control": "no-store",
+        "Content-Length": String(body.length),
+    };
+    const hosts = new Set(LOOPBACK_HOST_NAMES);
+    if (opts.settings.origin) {
+        const h = hostnameOf(new URL(opts.settings.origin).host);
+        if (h)
+            hosts.add(h);
+    }
+    const empty = (res, status) => {
+        res.writeHead(status, { "Content-Length": "0", "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer" });
+        res.end();
+    };
+    const server = createServer((req, res) => {
+        // Host only. The cookie a same-host port receives (cookies are not port-isolated) is never read.
+        const host = typeof req.headers.host === "string" ? hostnameOf(req.headers.host) : null;
+        if (!host || !hosts.has(host))
+            return empty(res, 403);
+        if (req.method !== "GET" || req.url !== "/frame")
+            return empty(res, 404);
+        res.writeHead(200, headers);
+        res.end(body);
+    });
+    const settings = { ...opts.settings };
+    // A listener on port 0 learns its real port when it binds: that is the one a /ui load must be offered.
+    server.on("listening", () => { const a = server.address(); if (a && typeof a === "object")
+        settings.port = a.port; });
+    return { server, bootId, settings, origins, close: () => { server.close(); } };
+}
+//# sourceMappingURL=web-preview.js.map

package/dist/web-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-preview.js","sourceRoot":"","sources":["../src/web-preview.ts"],"names":[],"mappings":"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"}

package/dist/web-request-context.d.ts

@@ -0,0 +1,10 @@
+/** Listener-owned provenance. HTTP headers can never select a public surface. */
+export interface GatewayRequestContext {
+    readonly surface: "gateway";
+    readonly exposureId: string;
+    readonly expectedOrigin: string;
+    readonly isCurrent: () => boolean;
+}
+export declare function bindGatewayRequest(req: object, context: GatewayRequestContext): void;
+export declare function gatewayRequestContext(req: object): GatewayRequestContext | undefined;
+export declare function isWebRequestCurrent(req: object): boolean;

package/dist/web-request-context.js

@@ -0,0 +1,13 @@
+const contexts = new WeakMap();
+export function bindGatewayRequest(req, context) {
+    if (contexts.has(req))
+        throw new Error("request context already bound");
+    contexts.set(req, Object.freeze({ ...context }));
+}
+export function gatewayRequestContext(req) {
+    return contexts.get(req);
+}
+export function isWebRequestCurrent(req) {
+    return contexts.get(req)?.isCurrent() ?? true;
+}
+//# sourceMappingURL=web-request-context.js.map

package/dist/web-request-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-request-context.js","sourceRoot":"","sources":["../src/web-request-context.ts"],"names":[],"mappings":"AAOA,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAiC,CAAC;AAC9D,MAAM,UAAU,kBAAkB,CAAC,GAAW,EAAE,OAA8B;IAC5E,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACxE,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC,CAAC;AACnD,CAAC;AACD,MAAM,UAAU,qBAAqB,CAAC,GAAW;IAC/C,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC;AACD,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC;AAChD,CAAC"}

package/dist/web-session.d.ts

@@ -0,0 +1,167 @@
+import { renameSync, unlinkSync, writeFileSync } from "node:fs";
+export type SessionSurface = "local" | "gateway";
+/** `admin` may do everything the panel can; `read` is reserved for the read-only tier (design D6). */
+export type SessionTier = "admin" | "read";
+export interface SessionPolicy {
+    /** Hard cap from creation; activity never extends it. */
+    readonly absoluteMs: number;
+    /** Slides with activity, never past the absolute cap. */
+    readonly idleMs: number;
+}
+/** Design D4. The gateway numbers are shorter because a session there is reachable from the internet. */
+export declare const DEFAULT_SESSION_POLICY: Readonly<Record<SessionSurface, SessionPolicy>>;
+/** More than this and the least recently used one is dropped. */
+export declare const MAX_WEB_SESSIONS = 8;
+/** `lastSeen` is only written to disk this often; creation and revocation always write. */
+export declare const SESSION_PERSIST_DEBOUNCE_MS: number;
+export interface SessionRecord {
+    /** Opaque, safe to show and to name in a revoke request. Not the id and not its hash. */
+    readonly handle: string;
+    readonly idHash: string;
+    readonly created: number;
+    lastSeen: number;
+    readonly absoluteExpiry: number;
+    idleExpiry: number;
+    readonly tier: SessionTier;
+    readonly surface: SessionSurface;
+    readonly exposureId?: string;
+    /** What the person sees in the device list. Display only, never an input to a decision. */
+    readonly label: string;
+    /** `sha256(web.token)` when the session was made; a mismatch means the token was rotated. */
+    readonly tokenEpoch: string;
+}
+export interface SessionSummary {
+    readonly handle: string;
+    readonly created: number;
+    readonly lastSeen: number;
+    readonly absoluteExpiry: number;
+    readonly idleExpiry: number;
+    readonly tier: SessionTier;
+    readonly surface: SessionSurface;
+    readonly label: string;
+    readonly current: boolean;
+}
+export declare function sessionIdHash(sessionId: string): string;
+/** Binds a session to the `web.token` it was issued under. */
+export declare function tokenEpoch(webToken: string): string;
+/**
+ * The value a page sends back in `X-Agend-CSRF`.
+ *
+ * Derived from the session id so it needs no storage, and different from the
+ * cookie value so it can be handed to script that must never see the cookie.
+ */
+export declare function csrfTokenFor(sessionId: string): string;
+export declare function isWellFormedSessionId(value: string): boolean;
+/** Printable, bounded, and never empty: a label is drawn in a page by other people's code. */
+export declare function sanitizeLabel(raw: string): string;
+/** "Chrome on macOS" out of a User-Agent, coarse on purpose — it is a hint for a person, not a fingerprint. */
+export declare function labelFromUserAgent(userAgent: string | undefined): string;
+/** The three file operations the store makes, so a test can make one of them fail. */
+export interface SessionFileOps {
+    writeFileSync: typeof writeFileSync;
+    renameSync: typeof renameSync;
+    unlinkSync: typeof unlinkSync;
+}
+export interface WebSessionStoreOptions {
+    /** Where `web-sessions.json` lives. Omit for a memory-only store (tests). */
+    readonly dataDir?: string;
+    /** Override individual file operations (tests only). */
+    readonly fileOps?: Partial<SessionFileOps>;
+    readonly now?: () => number;
+    readonly policy?: Partial<Record<SessionSurface, SessionPolicy>>;
+    readonly maxSessions?: number;
+    readonly onWarn?: (message: string) => void;
+}
+export declare class WebSessionStore {
+    private readonly pending;
+    private readonly byHash;
+    private readonly now;
+    private readonly policy;
+    private readonly maxSessions;
+    private readonly path;
+    private readonly warn;
+    private dirty;
+    private lastPersist;
+    private readonly ops;
+    /** The sessions the file on disk holds right now, as far as this process knows. */
+    private persisted;
+    constructor(opts?: WebSessionStoreOptions);
+    get size(): number;
+    /** How long a session on this surface may sit unused before it ends. For showing people, not for deciding. */
+    idleWindowMs(surface: SessionSurface): number;
+    /**
+     * Make a session. The id is returned once and never stored; the caller puts it
+     * in a cookie and forgets it.
+     */
+    create(input: {
+        tier: SessionTier;
+        surface: SessionSurface;
+        label: string;
+        tokenEpoch: string;
+        exposureId?: string;
+        pending?: boolean;
+    }): {
+        sessionId: string;
+        record: SessionRecord;
+    };
+    /**
+     * The session this id belongs to, if it is still good.
+     *
+     * Expiry and a rotated `web.token` are decided here, on the server, on every
+     * call — nothing is taken on the cookie's word. An expired or stale record is
+     * deleted as it is found so it cannot be revived by a clock or config change.
+     *
+     * `touch: false` is for a stream that re-checks itself on a timer: counting
+     * that as activity would keep an idle session alive for as long as a tab is
+     * open.
+     */
+    authenticate(sessionId: string | undefined, currentEpoch: string, opts?: {
+        touch?: boolean;
+        surface?: SessionSurface;
+        exposureId?: string;
+    }): SessionRecord | null;
+    /** Recheck a retained server record without retaining/replaying its bearer cookie. */
+    isCurrent(record: SessionRecord, currentEpoch: string): boolean;
+    /** A candidate has no usable credential until the public notice and final fence passed. */
+    activate(sessionId: string): boolean;
+    revokeExposure(exposureId: string): {
+        count: number;
+        durable: boolean;
+    };
+    /** Every live session, newest activity first. `currentIdHash` marks the caller's own. */
+    list(currentIdHash?: string): SessionSummary[];
+    revokeByHandle(handle: string): {
+        found: boolean;
+        durable: boolean;
+    };
+    revokeById(sessionId: string): {
+        removed: boolean;
+        durable: boolean;
+    };
+    /** Every session: how many there were, and whether the revocation is durable. */
+    revokeAll(): {
+        count: number;
+        durable: boolean;
+    };
+    /** Write anything pending. Called on shutdown. */
+    flush(): void;
+    private purgeExpired;
+    private evictLeastRecentlyUsed;
+    private persistIfDue;
+    /**
+     * Write the store. Returns whether it is DURABLE: whether a restart is now unable to bring back a
+     * session memory has dropped — true when the file was replaced, when the old file held nothing memory
+     * dropped (it is merely behind), or when it was removed; false only when a stale file is still there.
+     *
+     * The failure path matters more than the success path. Memory forgets a revoked
+     * session at once; if the file cannot be replaced it still holds that session, and a
+     * restart would read it back — a revoked session, alive again. So when a write fails:
+     * the store stays owing the disk a write (`dirty`, retried by the next change, the
+     * next debounce and shutdown), and if the old file holds anything memory has since
+     * dropped, the old file is removed. A restart then finds no sessions and everyone
+     * signs in again, which is the failure that is safe; it says so, loudly, when even
+     * that removal is impossible.
+     */
+    private persistNow;
+    private load;
+}