@lelouchhe/webagent 0.3.0 → 0.4.0

package/lib/share/sanitize.js

@@ -0,0 +1,179 @@
+export class SanitizeError extends Error {
+    status = 400;
+    /** The event seq that triggered the hard-reject; surfaced to owner as event_id. */
+    event_id;
+    rule;
+    constructor(event_id, rule, message) {
+        super(message);
+        this.event_id = event_id;
+        this.rule = rule;
+    }
+}
+// --- Layer 1c: hard-reject patterns ---
+//
+// Order matters only for error messages; any match aborts. Patterns are
+// designed to be low-false-positive (we're looking for obvious leakage,
+// not heuristic secrets — those belong to Layer 1b).
+// Rule set aims at well-known token prefixes that would not normally
+// appear in shared agent output. Every entry has a fixed prefix and a
+// minimum body length — keeps false positives low (a README that
+// mentions "ghp_" without a body passes; a real token does not).
+// Add new entries here; share-sanitize-secrets.test.ts enumerates each.
+const HARD_REJECT_RULES = [
+    {
+        id: "private_key",
+        // Matches OpenSSH, RSA, EC, DSA, encrypted, and PKCS8 ("BEGIN PRIVATE KEY").
+        // PGP has a different armor shape ("... BLOCK-----") — covered by pgp_private_key below.
+        pattern: /-----BEGIN (?:OPENSSH |RSA |EC |DSA |ENCRYPTED |)PRIVATE KEY-----/,
+        msg: "private key detected",
+    },
+    {
+        id: "pgp_private_key",
+        pattern: /-----BEGIN PGP PRIVATE KEY BLOCK-----/,
+        msg: "PGP private key detected",
+    },
+    {
+        id: "github_pat",
+        pattern: /\bgithub_pat_[A-Za-z0-9_]{22,}\b/,
+        msg: "GitHub PAT detected",
+    },
+    {
+        id: "github_ghp",
+        pattern: /\bghp_[A-Za-z0-9]{20,}\b/,
+        msg: "GitHub classic token detected",
+    },
+    {
+        id: "github_oauth",
+        // gho_/ghu_/ghs_/ghr_ — oauth + user-to-server + server-to-server + refresh.
+        pattern: /\bgh[oursw]_[A-Za-z0-9]{20,}\b/,
+        msg: "GitHub OAuth/app token detected",
+    },
+    {
+        id: "anthropic_api",
+        pattern: /\bsk-ant-(?:api|sid)[0-9]{2}-[A-Za-z0-9_-]{32,}\b/,
+        msg: "Anthropic API key detected",
+    },
+    {
+        id: "openai_api",
+        pattern: /\bsk-(?:proj|svcacct|admin)-[A-Za-z0-9_-]{32,}\b/,
+        msg: "OpenAI API key detected",
+    },
+    {
+        id: "slack_token",
+        pattern: /\bxox[baprs]-[A-Za-z0-9-]{20,}\b/,
+        msg: "Slack token detected",
+    },
+    {
+        id: "google_api",
+        pattern: /\bAIza[A-Za-z0-9_-]{35,}\b/,
+        msg: "Google API key detected",
+    },
+    {
+        id: "stripe_key",
+        pattern: /\b(?:sk|rk)_live_[A-Za-z0-9]{24,}\b/,
+        msg: "Stripe live key detected",
+    },
+    {
+        id: "aws_secret",
+        pattern: /aws_secret_access_key\s*[:=]\s*['"]?[A-Za-z0-9/+=]{20,}/i,
+        msg: "AWS secret access key detected",
+    },
+];
+/**
+ * Escape a string for safe inclusion in a RegExp. Needed for the homedir
+ * / cwd rewrite where paths may contain regex metachars (mac paths don't
+ * in practice, but defense in depth).
+ */
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Layer 1a: structured rewrite on a single string.
+ *
+ * Runs homedir/cwd first (longer match wins), then internal_hosts. The
+ * order is important — cwd often starts with homedir, and rewriting
+ * homedir first would leave "<home>/rest/of/cwd" un-collapsed. We
+ * rewrite cwd before homedir to catch that.
+ */
+function rewriteStructured(s, cwd, homeDir, internalHosts) {
+    let out = s;
+    // cwd first (usually longer / more specific than homedir)
+    if (cwd)
+        out = out.replace(new RegExp(escapeRegExp(cwd), "g"), "<cwd>");
+    if (homeDir)
+        out = out.replace(new RegExp(escapeRegExp(homeDir), "g"), "<home>");
+    for (const host of internalHosts) {
+        if (!host)
+            continue;
+        out = out.replace(new RegExp(escapeRegExp(host), "g"), "<internal-host>");
+    }
+    return out;
+}
+/** Hard-reject scan on a string. Throws SanitizeError on first match. */
+function assertNoHardRejects(seq, s) {
+    for (const rule of HARD_REJECT_RULES) {
+        if (rule.pattern.test(s)) {
+            throw new SanitizeError(seq, rule.id, rule.msg);
+        }
+    }
+}
+/**
+ * Sanitize a single StoredEvent. Rewrite applied in-place on a cloned
+ * JSON shape; hard-reject check runs on the stringified raw form so
+ * nested fields are all scanned without a schema enumeration.
+ */
+function sanitizeEvent(event, cwd, homeDir, internalHosts) {
+    // Normalize: if .data is a JSON string (StoredEvent), parse it.
+    let parsedData;
+    if (typeof event.data === "string") {
+        try {
+            parsedData = JSON.parse(event.data);
+        }
+        catch {
+            parsedData = {};
+        }
+    }
+    else {
+        parsedData = event.data;
+    }
+    // Hard-reject scan runs on pre-rewrite stringified form so the rules
+    // see the actual payload rather than the "<home>"-scrubbed version.
+    const raw = JSON.stringify(parsedData);
+    assertNoHardRejects(event.seq, raw);
+    const rewrittenData = deepRewriteStrings(parsedData, (s) => rewriteStructured(s, cwd, homeDir, internalHosts));
+    return {
+        id: "id" in event ? event.id : undefined,
+        session_id: "session_id" in event ? event.session_id : undefined,
+        seq: event.seq,
+        type: event.type,
+        data: rewrittenData,
+        created_at: "created_at" in event ? event.created_at : undefined,
+    };
+}
+function deepRewriteStrings(value, rewrite) {
+    if (typeof value === "string")
+        return rewrite(value);
+    if (Array.isArray(value))
+        return value.map((v) => deepRewriteStrings(v, rewrite));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = deepRewriteStrings(v, rewrite);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Main entry — sanitize a batch of events for share output.
+ *
+ * Throws SanitizeError with event_id on Layer-1c hard-reject (owner gets
+ * 4xx + event_id so they can jump to the offending event).
+ */
+export function sanitizeEventsForShare(input) {
+    const out = [];
+    for (const ev of input.events) {
+        out.push(sanitizeEvent(ev, input.cwd, input.homeDir, input.internalHosts));
+    }
+    return { events: out, flags: [] };
+}

package/lib/sse-manager.js

@@ -1,4 +1,16 @@
 import { randomBytes } from "node:crypto";
+import { reSignAttachmentUrlsInJson } from "./auth.js";
+import { enrichEventForDisplay } from "./attachment-labels.js";
+/**
+ * SSE heartbeat frame — a NAMED event so the frontend can hook
+ * `es.addEventListener("heartbeat", ...)` and refresh its per-session
+ * visibility record on the server. Comment-line form (`: heartbeat\n\n`)
+ * is silently discarded by EventSource — no `onmessage` fires — which is
+ * why we use a named event instead. Riding the SSE connection's natural
+ * pulse means connection alive → server TTL stays fresh; connection dies
+ * → TTL expires the ghost automatically.
+ */
+const SSE_HEARTBEAT_FRAME = "event: heartbeat\ndata: {}\n\n";
 /**
  * Manages Server-Sent Event connections.
  * Tracks connected clients, broadcasts events, handles cleanup.
@@ -8,21 +20,59 @@ export class SseManager {
     heartbeatTimer = null;
     heartbeatInterval;
     onRemoveCallback = null;
-    constructor(heartbeatMs = 20_000) {
+    isTokenRevoked = null;
+    attachmentSecret = null;
+    getLabelMap = null;
+    constructor(heartbeatMs = 15_000) {
         this.heartbeatInterval = heartbeatMs;
     }
     /** Register a callback invoked when a client disconnects. */
     onRemove(cb) {
         this.onRemoveCallback = cb;
     }
+    /** When set, every outgoing SSE message has its image URLs re-signed with
+     *  a fresh exp/sig — required for stored events to render past the
+     *  original 1h signature TTL. */
+    setAttachmentSecret(secret) {
+        this.attachmentSecret = secret;
+    }
+    /**
+     * Wire a label-map provider to enrich attachment uuid paths with
+     * user-friendly labels at egress (CLAUDE.md "Attachment label
+     * egress rewrite"). Applied per-event-session inside `sendEvent`,
+     * so both `broadcast()` and direct `sendEvent()` callers (e.g.
+     * SSE Last-Event-ID replay) get enriched output. DB still stores
+     * raw events.
+     */
+    setLabelMapProvider(fn) {
+        this.getLabelMap = fn;
+    }
+    /** Install a revocation check called on every heartbeat. If it returns
+     *  true the SSE connection is closed immediately (within one heartbeat
+     *  interval, ≤15s by default). */
+    setRevocationCheck(check) {
+        this.isTokenRevoked = check;
+    }
     /** Start the periodic heartbeat. Call once after construction. */
     startHeartbeat() {
         if (this.heartbeatTimer)
             return;
         this.heartbeatTimer = setInterval(() => {
             for (const client of this.clients.values()) {
-                if (!client.res.writableEnded)
-                    client.res.write(": heartbeat\n\n");
+                if (client.res.writableEnded)
+                    continue;
+                // Close any stream whose backing token has been revoked.
+                if (client.tokenName && this.isTokenRevoked?.(client.tokenName)) {
+                    try {
+                        client.res.end();
+                    }
+                    catch {
+                        /* already torn down */
+                    }
+                    this.remove(client.id);
+                    continue;
+                }
+                client.res.write(SSE_HEARTBEAT_FRAME);
             }
         }, this.heartbeatInterval);
         this.heartbeatTimer.unref();
@@ -41,7 +91,23 @@ export class SseManager {
     /** Register a new SSE client connection. */
     add(client) {
         this.clients.set(client.id, client);
-        client.res.on("close", () => this.remove(client.id));
+        client.res.on("close", () => {
+            this.remove(client.id);
+        });
+    }
+    /** Write a single heartbeat frame to the given client. Used right after
+     *  the "connected" handshake so the frontend's heartbeat-driven
+     *  /visibility refresh fires at T+0 and the server-side visibility TTL
+     *  doesn't wait a full interval to reset after a reconnect. */
+    writeHeartbeat(client) {
+        if (client.res.writableEnded)
+            return;
+        try {
+            client.res.write(SSE_HEARTBEAT_FRAME);
+        }
+        catch {
+            // socket already dead; res.on("close") will clean up
+        }
     }
     /** Remove a client by ID. */
     remove(id) {
@@ -52,11 +118,31 @@ export class SseManager {
     sendEvent(client, event, seq) {
         if (client.res.writableEnded)
             return;
+        let outEvent = event;
+        if (this.getLabelMap) {
+            const sid = event.sessionId;
+            if (sid) {
+                const map = this.getLabelMap(sid);
+                if (map.size > 0)
+                    outEvent = enrichEventForDisplay(event, map);
+            }
+        }
+        let data = JSON.stringify(outEvent);
+        if (this.attachmentSecret && data.includes("/attachments/")) {
+            data = reSignAttachmentUrlsInJson(data, this.attachmentSecret);
+        }
         let msg = "";
         if (seq != null)
             msg += `id: ${seq}\n`;
-        msg += `data: ${JSON.stringify(event)}\n\n`;
-        client.res.write(msg);
+        msg += `data: ${data}\n\n`;
+        try {
+            client.res.write(msg);
+        }
+        catch {
+            // Socket torn down between writableEnded check and write.
+            // Drop the client so we stop writing to it on every broadcast.
+            this.remove(client.id);
+        }
     }
     /**
      * Broadcast an event to all connected SSE clients.
@@ -64,10 +150,10 @@ export class SseManager {
      */
     broadcast(event) {
         const sessionId = event.sessionId;
-        for (const client of this.clients.values()) {
+        const snapshot = [...this.clients.values()];
+        for (const client of snapshot) {
             if (client.res.writableEnded)
                 continue;
-            // Global clients get everything; session clients only get matching events
             if (client.sessionId && client.sessionId !== sessionId)
                 continue;
             this.sendEvent(client, event);

package/lib/sse-ticket.js

@@ -0,0 +1,45 @@
+import { generateSseTicket } from "./tokens.js";
+/**
+ * Short-lived single-use tickets that authenticate an SSE EventSource
+ * connection (which can't carry a Bearer header). Lifecycle:
+ *   1. Client POSTs /api/v1/sse-ticket with Bearer → mint() returns ticket.
+ *   2. Client opens EventSource(?ticket=...) → consume() validates + deletes.
+ *   3. After TTL (default 60s) any unused ticket is invalid; gc() purges.
+ */
+export class TicketStore {
+    tickets = new Map();
+    ttlMs;
+    now;
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs ?? 60_000;
+        this.now = opts.now ?? Date.now;
+    }
+    mint(principal) {
+        const ticket = generateSseTicket();
+        this.tickets.set(ticket, {
+            tokenName: principal.tokenName,
+            scope: principal.scope,
+            expiresAt: this.now() + this.ttlMs,
+        });
+        return ticket;
+    }
+    consume(ticket) {
+        const rec = this.tickets.get(ticket);
+        if (!rec)
+            return null;
+        this.tickets.delete(ticket);
+        if (rec.expiresAt <= this.now())
+            return null;
+        return { tokenName: rec.tokenName, scope: rec.scope };
+    }
+    gc() {
+        const cutoff = this.now();
+        for (const [k, v] of this.tickets) {
+            if (v.expiresAt <= cutoff)
+                this.tickets.delete(k);
+        }
+    }
+    get size() {
+        return this.tickets.size;
+    }
+}

package/lib/startup-checks.js

@@ -0,0 +1,94 @@
+// Unified startup-time checks — preflight + auth bootstrap + first-run
+// mint — shared by every launch path:
+//
+//   1. `webagent` (foreground via bin)        → server.ts top-level
+//   2. `node src/server.ts ...` (dev / source) → server.ts top-level
+//   3. `webagent start` (daemon supervisor)   → cmdStart parent process
+//
+// The daemon path runs these checks in the operator's foreground TTY
+// *before* fork. On success, it sets `WEBAGENT_STARTUP_CHECKED=1` in
+// the child env so the server skips re-running the checks (and avoids
+// printing the same `[check]` lines twice). On failure, it never forks.
+//
+// Why this matters: under daemon mode the server child is detached
+// with stdio piped to a log file. Without the parent-side gate, any
+// failure (port busy, agent missing, no auth.json) would land in the
+// log instead of the operator's terminal — exactly the "silent fork
+// and die" UX we want to avoid. And the foreground first-run mint
+// banner can't be shown by a TTY-less child either.
+import { existsSync } from "node:fs";
+import { join as pathJoin } from "node:path";
+import { runPreflight } from "./preflight.js";
+import { AuthStore } from "./auth-store.js";
+import { decideBootstrap, formatBootstrapBanner } from "./bootstrap.js";
+import { log } from "./log.js";
+/** Env var the daemon parent sets when handing off to its server child. */
+export const STARTUP_CHECKED_ENV = "WEBAGENT_STARTUP_CHECKED";
+/**
+ * Run the full startup gate. Prints `[check] <name>: <detail>  ✓|✗`
+ * lines to stdout/stderr in the same style as preflight. Exits 78
+ * (sysexits.h EX_CONFIG) on any failure so the daemon supervisor
+ * stops its restart loop (see `decideRestart` in daemon.ts).
+ *
+ * If `WEBAGENT_STARTUP_CHECKED=1` is set in the env, returns
+ * immediately with the configured `agent_cmd` verbatim — assumes a
+ * parent process already ran the same checks for this server's data
+ * directory.
+ */
+export async function runStartupChecks(config) {
+    if (process.env[STARTUP_CHECKED_ENV] === "1") {
+        return { agentCmd: config.agent_cmd };
+    }
+    // 1. Preflight (node version, data_dir writable, agent resolvable, port free).
+    const preflight = await runPreflight({
+        data_dir: config.data_dir,
+        agent_cmd: config.agent_cmd,
+        port: config.port,
+    });
+    // 2. Auth bootstrap. Same `[check] auth: ...` style; first-run mint
+    //    or refuse-to-serve land here.
+    const authJsonPath = pathJoin(config.data_dir, "auth.json");
+    const authStore = new AuthStore(authJsonPath);
+    await authStore.load();
+    const tokenCount = authStore.list().length;
+    const action = decideBootstrap({
+        authJsonExists: existsSync(authJsonPath),
+        tokenCount,
+        isTTY: Boolean(process.stdin.isTTY),
+        firstRunEnabled: config.auth.first_run_bootstrap,
+    });
+    if (action.kind === "exit-config") {
+        console.error(`[check] auth: no tokens in auth.json — refusing to serve  ✗`);
+        console.error(`        create one with:  webagent --create-token <name>`);
+        console.error(`        then start the server again (or send SIGHUP to the running process).`);
+        await authStore.close();
+        process.exit(78);
+    }
+    if (action.kind === "mint") {
+        try {
+            const created = await authStore.addToken("first-run", "admin");
+            console.log(`[check] auth: minted first-run admin token  ✓`);
+            console.log(formatBootstrapBanner({
+                token: created.token,
+                port: config.port,
+                isTTY: Boolean(process.stdout.isTTY),
+            }));
+            log.scope("bootstrap").info("first-run admin token minted", {
+                name: created.record.name,
+            });
+        }
+        catch (err) {
+            console.error(`[check] auth: mint failed: ${String(err)}  ✗`);
+            await authStore.close();
+            process.exit(78);
+        }
+    }
+    else {
+        console.log(`[check] auth: ${tokenCount} token(s) loaded  ✓`);
+    }
+    // We don't keep this AuthStore handle — server.ts opens its own.
+    // Keeping it open here would tie the file to a process that's about
+    // to either fork (daemon) or hand off control (server.ts top-level).
+    await authStore.close();
+    return { agentCmd: preflight.agentCmd };
+}