@songsid/agend 2.1.12 → 2.2.0-alpha.1

package/dist/web-host-guard.js

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 export const WEB_HOST_REJECTED_MESSAGE = "Host not allowed — if you reach AgEnD through a reverse proxy or another name, add it to web.allowed_hosts in fleet.yaml";
 /** Names a browser on this machine uses for a loopback listener. */
 export const LOOPBACK_HOST_NAMES = ["localhost", "127.0.0.1", "[::1]"];
@@ -30,6 +31,34 @@ export function hostnameOf(value) {
     // either direction.
     return match[1].replace(/\.$/, "") || null;
 }
+/**
+ * What a page served here may load and where it may send anything.
+ *
+ * `script-src` is this origin only — no `'unsafe-inline'` (#1268): a panel's own inline
+ * script runs because the panel is served with a per-response nonce for it
+ * (sendPanelHtml), and no panel has an inline `on*=` handler. Injected markup can
+ * therefore not run script. `connect-src`, `img-src` and `form-action` are this
+ * origin, so nothing read can be posted elsewhere, and `base-uri`, `object-src` and
+ * `frame-ancestors` are closed. Styles are the same (#1300): `style-src 'self'`, and a
+ * panel's own `<style>` block carries the response's nonce. No panel has a `style="…"`
+ * attribute — what a script colours or sizes at run time goes through the style object
+ * (CSSOM), which the policy does not govern — so injected markup cannot add inline styles of its
+ * own (it can still carry the page's existing class names).
+ *
+ * Fonts, scripts and styles are all served from here; nothing loads from a CDN.
+ */
+export const WEB_CONTENT_SECURITY_POLICY = [
+    "default-src 'self'",
+    "script-src 'self'",
+    "style-src 'self'",
+    "img-src 'self' data: blob:",
+    "font-src 'self' data:",
+    "connect-src 'self'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "form-action 'self'",
+    "frame-ancestors 'none'",
+].join("; ");
 /** Loopback names, the `hostname:` handed out in /dashboard links, and `web.allowed_hosts`. */
 export function allowedHostNames(config) {
     const names = new Set(LOOPBACK_HOST_NAMES);
@@ -67,9 +96,36 @@ export function applyWebSecurityHeaders(res) {
     // These pages have buttons that restart instances and change configuration;
     // a page that can be framed can be clicked through.
     res.setHeader("X-Frame-Options", "DENY");
-    res.setHeader("Content-Security-Policy", "frame-ancestors 'none'");
+    res.setHeader("Content-Security-Policy", WEB_CONTENT_SECURITY_POLICY);
     // Authorization now depends on a cookie, so a shared cache (a tunnel, a
     // corporate proxy) must not keep or replay any of it.
     res.setHeader("Cache-Control", "no-store");
 }
+/**
+ * The panel policy for one response: WEB_CONTENT_SECURITY_POLICY with this response's nonce for scripts and styles,
+ * and — for /ui only, when a preview origin was chosen for this load (#1306) — `frame-src <preview origin>/frame`:
+ * path-scoped, so nothing else of that origin can be framed or navigated to. Without it, frames fall back to
+ * default-src 'self'.
+ */
+export function panelContentSecurityPolicy(nonce, opts = {}) {
+    const policy = WEB_CONTENT_SECURITY_POLICY
+        .replace("script-src 'self'", `script-src 'self' 'nonce-${nonce}'`)
+        .replace("style-src 'self'", `style-src 'self' 'nonce-${nonce}'`);
+    return opts.frameSrc ? `${policy}; frame-src ${opts.frameSrc}` : policy;
+}
+/**
+ * Send a panel page (/ui, /view, /settings, the sign-in page). Its own inline `<script>` and `<style>` blocks get a
+ * fresh nonce, and the response's CSP names that nonce and nothing else inline (#1268, #1300): a script or a style
+ * that was not in the file as served — anything injected into the page — has no nonce and does not apply.
+ */
+export function sendPanelHtml(res, html, status = 200, headers = {}, csp = {}) {
+    const nonce = randomBytes(18).toString("base64");
+    res.setHeader("Content-Security-Policy", panelContentSecurityPolicy(nonce, csp));
+    res.writeHead(status, { "Content-Type": "text/html; charset=utf-8", ...headers });
+    // Exactly the page's own bare `<script>` / `<style>` tags, as written in our files, get the nonce: a plain string
+    // match, not a tag filter. Any other spelling (`<SCRIPT>`, `<script src=…>`, `<script type=module>`) is left as is
+    // and so has no nonce: inline it is blocked, `src=` scripts load by 'self'. Widening the match would hand the
+    // nonce to more spellings; nothing here sanitises input.
+    res.end(html.split("<script>").join(`<script nonce="${nonce}">`).split("<style>").join(`<style nonce="${nonce}">`));
+}
 //# sourceMappingURL=web-host-guard.js.map

package/dist/web-host-guard.js.map

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

package/dist/web-login.d.ts

@@ -0,0 +1,72 @@
+import type { SessionTier } from "./web-session.js";
+export declare const LOGIN_CODE_TTL_MS: number;
+/** Same reasoning as setup: eight characters on a phone get mistyped. */
+export declare const MAX_LOGIN_CODE_ATTEMPTS = 5;
+export declare const LOGIN_BREAKER_WINDOW_MS: number;
+export declare const LOGIN_BREAKER_THRESHOLD = 20;
+export declare const LOGIN_BREAKER_PAUSE_MS: number;
+export interface LoginCodeOwner {
+    /** Server-owned live adapter identity; never accepted from HTTP. */
+    readonly binding?: object;
+    readonly adapterId: string;
+    readonly userId: string;
+    readonly chatId: string;
+    readonly threadId?: string;
+}
+export interface IssuedLoginCode {
+    readonly issuanceId: string;
+    /** As typed: `ABCD-EFGH`. */
+    readonly display: string;
+    readonly expiresAt: number;
+    readonly tier: SessionTier;
+}
+export type LoginRedeemResult = {
+    readonly kind: "ok";
+    readonly tier: SessionTier;
+    readonly owner?: LoginCodeOwner;
+}
+/** Wrong, expired, spent, or none issued — deliberately indistinguishable. */
+ | {
+    readonly kind: "invalid";
+}
+/** The breaker is open. Even a correct code is refused until it closes. */
+ | {
+    readonly kind: "paused";
+    readonly retryAfterMs: number;
+};
+export interface WebLoginCodesOptions {
+    readonly now?: () => number;
+    /** For tests that need a known code. */
+    readonly generate?: () => string;
+    readonly onEvent?: (event: "issued" | "spent" | "burned" | "breaker-open") => void;
+}
+export declare class WebLoginCodes {
+    private outstanding;
+    private failures;
+    private pausedUntil;
+    private readonly now;
+    private readonly generate;
+    private readonly onEvent;
+    constructor(opts?: WebLoginCodesOptions);
+    /**
+     * Issue a code, replacing any outstanding one. Only ever called from a channel the operator controls.
+     * `epoch` is the current web token's (`tokenEpoch`): rotating the token — from this process or from
+     * `agend web-token rotate` in another — withdraws an unused code, because redemption re-checks it.
+     */
+    issue(opts: {
+        tier?: SessionTier;
+        epoch: string;
+        audience?: string;
+        owner?: LoginCodeOwner;
+    }): IssuedLoginCode;
+    /** Whether a redemption right now would be compared against anything. */
+    get hasOutstandingCode(): boolean;
+    /** Withdraw the outstanding code without spending it (`/dashboard revoke`). */
+    revoke(): void;
+    /** `currentEpoch` is the web token's epoch NOW: a code issued under another token is gone. */
+    revokeIfCurrent(issuanceId: string): void;
+    revokeAudience(audience: string): void;
+    redeem(input: string, currentEpoch: string, audience?: string): LoginRedeemResult;
+    private activeCode;
+    private recordFailure;
+}

package/dist/web-login.js

@@ -0,0 +1,132 @@
+/**
+ * The dashboard's login codes: who may redeem one, how often they may be wrong,
+ * and what happens when they are wrong too often.
+ *
+ * Deliberately not `SetupCredentials`. That class belongs to a ten-minute
+ * escape hatch whose answer to five wrong tries is to destroy itself; a fleet
+ * that runs for months must not be closable by whoever finds its address. So the
+ * rules here are different, and each is a property worth testing directly:
+ *
+ * - **No outstanding code, nothing to guess.** A redemption while no code has
+ *   been issued gets the same refusal as a wrong code and counts against
+ *   nothing. The door is only a door in the few minutes after the operator asked
+ *   for a code on a channel only they can read.
+ * - **A code dies with its fifth wrong try — the code, not the fleet.** The
+ *   cost to a stranger who guesses is that the operator asks for another.
+ * - **A breaker for the rest.** Enough wrong tries across codes pauses
+ *   redemption for a while, correct codes included, so a patient guesser cannot
+ *   turn five-per-code into an unbounded stream. Sessions already signed in are
+ *   not affected: this object knows nothing about them.
+ * - **One code at a time, single use.** Issuing replaces the outstanding code;
+ *   redeeming it spends it.
+ *
+ * The code is only an exchange key. What a successful redemption yields is a
+ * fresh 256-bit session id from `web-session.ts` that has no relation to it.
+ *
+ * Deliberately has no idea what an HTTP request is.
+ */
+import { constantTimeMatches, formatOneTimeCode, generateOneTimeCode, normalizeOneTimeCode, } from "./auth/one-time-code.js";
+import { randomBytes } from "node:crypto";
+export const LOGIN_CODE_TTL_MS = 5 * 60 * 1000;
+/** Same reasoning as setup: eight characters on a phone get mistyped. */
+export const MAX_LOGIN_CODE_ATTEMPTS = 5;
+export const LOGIN_BREAKER_WINDOW_MS = 15 * 60 * 1000;
+export const LOGIN_BREAKER_THRESHOLD = 20;
+export const LOGIN_BREAKER_PAUSE_MS = 5 * 60 * 1000;
+/** Compared against when nothing is outstanding, so "no code" costs what "wrong code" costs. */
+const NO_CODE_PLACEHOLDER = "AAAAAAAA";
+export class WebLoginCodes {
+    outstanding = null;
+    failures = [];
+    pausedUntil = 0;
+    now;
+    generate;
+    onEvent;
+    constructor(opts = {}) {
+        this.now = opts.now ?? Date.now;
+        this.generate = opts.generate ?? generateOneTimeCode;
+        this.onEvent = opts.onEvent ?? (() => { });
+    }
+    /**
+     * Issue a code, replacing any outstanding one. Only ever called from a channel the operator controls.
+     * `epoch` is the current web token's (`tokenEpoch`): rotating the token — from this process or from
+     * `agend web-token rotate` in another — withdraws an unused code, because redemption re-checks it.
+     */
+    issue(opts) {
+        const code = this.generate();
+        const tier = opts.tier ?? "admin";
+        const expiresAt = this.now() + LOGIN_CODE_TTL_MS;
+        const issuanceId = randomBytes(16).toString("hex");
+        this.outstanding = { code, expiresAt, tier, epoch: opts.epoch, failures: 0, issuanceId, audience: opts.audience ?? "local", owner: opts.owner };
+        this.onEvent("issued");
+        return { display: formatOneTimeCode(code), expiresAt, tier, issuanceId };
+    }
+    /** Whether a redemption right now would be compared against anything. */
+    get hasOutstandingCode() {
+        return this.activeCode() !== null;
+    }
+    /** Withdraw the outstanding code without spending it (`/dashboard revoke`). */
+    revoke() {
+        this.outstanding = null;
+    }
+    /** `currentEpoch` is the web token's epoch NOW: a code issued under another token is gone. */
+    revokeIfCurrent(issuanceId) {
+        if (this.outstanding?.issuanceId === issuanceId)
+            this.outstanding = null;
+    }
+    revokeAudience(audience) {
+        if (this.outstanding?.audience === audience)
+            this.outstanding = null;
+    }
+    redeem(input, currentEpoch, audience = "local") {
+        const now = this.now();
+        if (now < this.pausedUntil)
+            return { kind: "paused", retryAfterMs: this.pausedUntil - now };
+        const provided = normalizeOneTimeCode(input);
+        // Nothing typed is not a guess; it costs nothing (same as the setup page).
+        if (!provided)
+            return { kind: "invalid" };
+        let active = this.activeCode();
+        if (active && active.epoch !== currentEpoch) {
+            // The token was rotated after this code was issued: the rotation withdrew it.
+            this.outstanding = null;
+            active = null;
+        }
+        if (!active) {
+            constantTimeMatches(provided, NO_CODE_PLACEHOLDER);
+            return { kind: "invalid" };
+        }
+        if (constantTimeMatches(provided, active.code) && active.audience === audience) {
+            this.outstanding = null;
+            this.onEvent("spent");
+            return { kind: "ok", tier: active.tier, ...(active.owner ? { owner: active.owner } : {}) };
+        }
+        active.failures += 1;
+        this.recordFailure(now);
+        if (active.failures >= MAX_LOGIN_CODE_ATTEMPTS) {
+            this.outstanding = null;
+            this.onEvent("burned");
+        }
+        return { kind: "invalid" };
+    }
+    activeCode() {
+        if (!this.outstanding)
+            return null;
+        if (this.now() >= this.outstanding.expiresAt) {
+            this.outstanding = null;
+            return null;
+        }
+        return this.outstanding;
+    }
+    recordFailure(now) {
+        this.failures.push(now);
+        const cutoff = now - LOGIN_BREAKER_WINDOW_MS;
+        this.failures = this.failures.filter(t => t > cutoff);
+        if (this.failures.length >= LOGIN_BREAKER_THRESHOLD) {
+            this.pausedUntil = now + LOGIN_BREAKER_PAUSE_MS;
+            this.failures = [];
+            this.onEvent("breaker-open");
+        }
+    }
+}
+//# sourceMappingURL=web-login.js.map

package/dist/web-login.js.map

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

package/dist/web-org.d.ts

@@ -0,0 +1,55 @@
+/**
+ * #1389: the fleet's org chart, as the web shows it (Fleet → Org chart). Presentation only (the user's Discord-first
+ * rule): nothing here is a new source of truth. The structure is read from what already exists — fleet.yaml's
+ * instances and teams, General (general_topic), each instance's world and thread — and the live state is not here at
+ * all: the page takes it from the stream it already follows (status, activity, `needs`).
+ */
+import type { WorldPlace } from "./needs-you.js";
+export interface OrgInstanceConfig {
+    description?: unknown;
+    tags?: unknown;
+}
+export interface OrgInput {
+    /** Every instance the dashboard lists, in its order (fleet.yaml's, then ClassicBot rooms). */
+    names: readonly string[];
+    instances: Readonly<Record<string, OrgInstanceConfig | undefined>>;
+    teams: Readonly<Record<string, {
+        members?: unknown;
+        description?: unknown;
+    } | undefined>> | undefined;
+    isGeneral(name: string): boolean;
+    isClassic(name: string): boolean;
+    /** The platform and group of the world the instance lives in, when it has one. */
+    place(name: string): WorldPlace | undefined;
+    /** The instance's own thread/topic (or ClassicBot channel) id. */
+    topic(name: string): string | undefined;
+}
+export interface OrgThread {
+    platform: "discord" | "telegram";
+    url: string;
+}
+export interface OrgInstance {
+    description?: string;
+    tags?: string[];
+    general?: true;
+    classic?: true;
+    thread?: OrgThread;
+}
+export interface OrgTeam {
+    name: string;
+    description?: string;
+    /** As configured, in order; a name the fleet no longer has is kept (the page shows it as missing). */
+    members: string[];
+}
+export interface OrgChart {
+    /** General instances (one per world at most, in practice): the top of the chart. */
+    general: string[];
+    teams: OrgTeam[];
+    instances: Record<string, OrgInstance>;
+}
+/**
+ * A browser link to an instance's thread: Discord's channel URL, Telegram's topic link. Undefined when the place or
+ * the id is not one a link can be built from (Telegram's General topic, 1, has no topic link).
+ */
+export declare function threadUrl(place: WorldPlace | undefined, topicId: string | undefined): OrgThread | undefined;
+export declare function buildOrgChart(input: OrgInput): OrgChart;

package/dist/web-org.js

@@ -0,0 +1,67 @@
+const SNOWFLAKE = /^\d{5,25}$/;
+const MAX_DESCRIPTION = 500;
+const MAX_TAGS = 12;
+/**
+ * A browser link to an instance's thread: Discord's channel URL, Telegram's topic link. Undefined when the place or
+ * the id is not one a link can be built from (Telegram's General topic, 1, has no topic link).
+ */
+export function threadUrl(place, topicId) {
+    if (!place || !topicId)
+        return undefined;
+    if (place.type === "discord") {
+        if (!place.groupId || !SNOWFLAKE.test(place.groupId) || !SNOWFLAKE.test(topicId))
+            return undefined;
+        return { platform: "discord", url: `https://discord.com/channels/${place.groupId}/${topicId}` };
+    }
+    if (place.type === "telegram") {
+        const m = /^-100(\d+)$/.exec(place.groupId ?? "");
+        if (!m || !/^\d+$/.test(topicId) || topicId === "1")
+            return undefined;
+        return { platform: "telegram", url: `https://t.me/c/${m[1]}/${topicId}` };
+    }
+    return undefined;
+}
+const text = (v) => {
+    if (typeof v !== "string")
+        return undefined;
+    const s = v.trim();
+    return s ? (s.length > MAX_DESCRIPTION ? `${s.slice(0, MAX_DESCRIPTION - 1)}…` : s) : undefined;
+};
+export function buildOrgChart(input) {
+    // Keyed by instance name, and any name the validators accept is a key — "__proto__" included (#1467 review): a
+    // prototype-less map makes every assignment an own property, so JSON carries it like any other name.
+    const instances = Object.create(null);
+    const general = [];
+    for (const name of input.names) {
+        const cfg = input.instances[name];
+        const entry = {};
+        const description = text(cfg?.description);
+        if (description)
+            entry.description = description;
+        if (Array.isArray(cfg?.tags)) {
+            const tags = cfg.tags.filter((t) => typeof t === "string" && t.trim() !== "").map(t => t.trim()).slice(0, MAX_TAGS);
+            if (tags.length)
+                entry.tags = tags;
+        }
+        if (input.isGeneral(name)) {
+            entry.general = true;
+            general.push(name);
+        }
+        if (input.isClassic(name))
+            entry.classic = true;
+        const thread = threadUrl(input.place(name), input.topic(name));
+        if (thread)
+            entry.thread = thread;
+        instances[name] = entry;
+    }
+    const teams = [];
+    for (const [name, team] of Object.entries(input.teams ?? {})) {
+        if (!team)
+            continue;
+        const members = Array.isArray(team.members) ? [...new Set(team.members.filter((m) => typeof m === "string" && m !== ""))] : [];
+        const description = text(team.description);
+        teams.push({ name, ...(description ? { description } : {}), members });
+    }
+    return { general, teams, instances };
+}
+//# sourceMappingURL=web-org.js.map

package/dist/web-org.js.map

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

package/dist/web-preview.d.ts

@@ -0,0 +1,77 @@
+import { type Server } from "node:http";
+import { type HostGuardConfig } 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 declare const PREVIEW_HTML_MAX_BYTES: number;
+export interface PreviewWebConfig {
+    preview?: unknown;
+    preview_port?: unknown;
+    preview_origin?: unknown;
+}
+export interface PreviewSettings {
+    /** `web.preview` (default true): false means no listener, and cards show Source / Download only. */
+    enabled: boolean;
+    /** The preview listener's port, on 127.0.0.1; null when there is no valid one (health_port 65535 and no preview_port). */
+    port: number | null;
+    /** `web.preview_origin`, normalised to scheme://host[:port], or null. */
+    origin: string | null;
+}
+/** The settings a fleet runs with: `web.preview`, `web.preview_port` (default health_port + 1), `web.preview_origin`. */
+export declare function previewSettings(web: PreviewWebConfig | null | undefined, healthPort: number): PreviewSettings;
+/** scheme://host[:port] for an http(s) URL with nothing else in it; null otherwise. A default port is dropped. */
+export declare function normalizeOrigin(value: string): string | null;
+/**
+ * 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 declare function previewOriginProblem(value: unknown, config: HostGuardConfig | null | undefined): string | null;
+export interface PreviewAvailability {
+    /** The origin the server believes the browser is at (from Host and the TLS signal), or null. */
+    dashboardOrigin: string | null;
+    /** The preview origin for this load, or null: preview disabled for it. */
+    previewOrigin: string | null;
+    /** Why it is disabled, when it is. */
+    reason: string | null;
+}
+/** scheme://host[:port] from a Host header the host guard already accepted; a default port is dropped. */
+export declare function dashboardOriginFor(hostHeader: string | undefined, secure: boolean): string | null;
+/**
+ * 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 declare function previewAvailability(settings: PreviewSettings | null, hostHeader: string | undefined, secure: boolean, accepted?: readonly string[]): PreviewAvailability;
+/**
+ * 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 declare function dashboardOrigins(settings: PreviewSettings, healthPort: number, config: HostGuardConfig | null | undefined): string[];
+/** The /frame response's Content-Security-Policy (design §5.1): exact, no 'self', no *. */
+export declare function previewFrameCsp(ancestors: readonly string[]): string;
+/**
+ * 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 declare function buildShim(bootId: string, origins: readonly string[]): string;
+export interface PreviewListener {
+    readonly server: Server;
+    readonly bootId: string;
+    readonly settings: PreviewSettings;
+    /** The dashboard origins the shim accepts HTML from and may be framed by. */
+    readonly origins: readonly string[];
+    close(): void;
+}
+/**
+ * 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 declare function createPreviewListener(opts: {
+    settings: PreviewSettings;
+    healthPort: number;
+    config: HostGuardConfig | null | undefined;
+    bootId?: string;
+}): PreviewListener;