papercliped 1.1.0-beta.2 → 2.2.0

package/dist/panel/routes.js

@@ -1,284 +0,0 @@
-import { createHmac, hkdfSync, timingSafeEqual } from "node:crypto";
-import { randomToken, safeEqual } from "../oauth/crypto.js";
-import { loginPage, panelPage } from "./page.js";
-/** window → [span ms, bucket ms] */
-export const WINDOWS = {
-    "5m": [5 * 60_000, 5_000],
-    "15m": [15 * 60_000, 15_000],
-    "1h": [3_600_000, 60_000],
-    "6h": [6 * 3_600_000, 300_000],
-    "24h": [24 * 3_600_000, 900_000],
-    "7d": [7 * 24 * 3_600_000, 3_600_000],
-};
-/** The bridge reports every 30 s. Silence for this long means it is down, asleep (free tier), or cannot reach the database. */
-export const BRIDGE_SILENT_MS = 120_000;
-export function assessHealth(i) {
-    const reasons = [];
-    let level = 0;
-    const bump = (l, why) => {
-        level = Math.max(level, l);
-        reasons.push(why);
-    };
-    const faultRate = i.count ? i.faults / i.count : 0;
-    if (i.count >= 5) {
-        if (faultRate >= 0.1)
-            bump(2, `${(faultRate * 100).toFixed(1)}% of calls hit a system fault`);
-        else if (faultRate >= 0.02)
-            bump(1, `${(faultRate * 100).toFixed(1)}% of calls hit a system fault`);
-        if (i.p95 >= i.slowMs * 3)
-            bump(2, `p95 latency ${Math.round(i.p95)} ms`);
-        else if (i.p95 >= i.slowMs)
-            bump(1, `p95 latency ${Math.round(i.p95)} ms`);
-    }
-    if (i.bridgeSilentMs === null)
-        bump(1, "no bridge has reported yet");
-    else if (i.bridgeSilentMs > BRIDGE_SILENT_MS)
-        bump(2, `the bridge has not reported for ${Math.round(i.bridgeSilentMs / 1000)} s (asleep, down, or cannot reach the database)`);
-    if (i.recentDbFailed)
-        bump(2, "database ping is failing");
-    else if (i.dbPingMs != null && i.dbPingMs >= 1000)
-        bump(2, `database ping ${Math.round(i.dbPingMs)} ms`);
-    else if (i.dbPingMs != null && i.dbPingMs >= 250)
-        bump(1, `database ping ${Math.round(i.dbPingMs)} ms`);
-    if (i.loopLagP99Ms >= 500)
-        bump(2, `event-loop lag p99 ${Math.round(i.loopLagP99Ms)} ms`);
-    else if (i.loopLagP99Ms >= 100)
-        bump(1, `event-loop lag p99 ${Math.round(i.loopLagP99Ms)} ms`);
-    if (level === 0)
-        return { state: i.count === 0 ? "idle" : "healthy", reasons: i.count === 0 ? ["no calls in this window"] : [] };
-    return { state: level === 2 ? "critical" : "degraded", reasons };
-}
-const COOKIE = "pcp_panel";
-export class PanelRoutes {
-    d;
-    key;
-    now;
-    grantsCache = { at: 0, v: null };
-    constructor(d) {
-        this.d = d;
-        this.key = Buffer.from(hkdfSync("sha256", d.token, "paperclip-bridge", "admin-session-v1", 32));
-        this.now = d.now ?? Date.now;
-    }
-    sign(expSec) {
-        return `${expSec}.${createHmac("sha256", this.key).update(`admin|${expSec}`).digest("base64url")}`;
-    }
-    sessionValid(req) {
-        const m = new RegExp(`(?:^|; )${COOKIE}=([^;]+)`).exec(req.headers.cookie ?? "");
-        if (!m)
-            return false;
-        const [exp, mac] = m[1].split(".");
-        const expSec = Number(exp);
-        if (!Number.isFinite(expSec) || expSec * 1000 < this.now() || !mac)
-            return false;
-        const want = Buffer.from(this.sign(expSec).split(".")[1]);
-        const got = Buffer.from(mac);
-        return want.length === got.length && timingSafeEqual(want, got);
-    }
-    ip(req) {
-        const hops = this.d.proxyHops ?? 0;
-        if (hops > 0) {
-            const parts = String(req.headers["x-forwarded-for"] ?? "").split(",").map((x) => x.trim()).filter(Boolean);
-            if (parts.length >= hops)
-                return parts[parts.length - hops];
-        }
-        return req.socket.remoteAddress ?? "unknown";
-    }
-    send(res, status, body, type, extra = {}) {
-        res.writeHead(status, { "Content-Type": type, "Cache-Control": "no-store", "X-Content-Type-Options": "nosniff", "Referrer-Policy": "no-referrer", ...extra });
-        res.end(body);
-        return true;
-    }
-    json = (res, status, body) => this.send(res, status, JSON.stringify(body), "application/json");
-    html(res, status, build, extra = {}) {
-        const nonce = randomToken(12);
-        return this.send(res, status, build(nonce), "text/html; charset=utf-8", {
-            "Content-Security-Policy": `default-src 'none'; img-src data:; script-src 'nonce-${nonce}'; style-src 'unsafe-inline'; connect-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'`,
-            "X-Frame-Options": "DENY",
-            ...extra,
-        });
-    }
-    cookie(value, maxAgeSec) {
-        return `${COOKIE}=${value}; Path=/; HttpOnly; SameSite=Strict; Max-Age=${maxAgeSec}${this.d.secureCookie ? "; Secure" : ""}`;
-    }
-    async handle(req, res, url) {
-        const p = url.pathname;
-        const m = req.method ?? "GET";
-        if (p === "/healthz")
-            return this.json(res, 200, { ok: true });
-        if (m === "POST" && p === "/login")
-            return this.login(req, res);
-        if (m === "POST" && p === "/logout")
-            return this.send(res, 303, "", "text/plain", { Location: "/", "Set-Cookie": this.cookie("", 0) });
-        const authed = this.sessionValid(req);
-        if (m === "GET" && (p === "/" || p === "/index.html")) {
-            return authed ? this.html(res, 200, (n) => panelPage(n, { slowMs: this.d.slowMs })) : this.html(res, 200, (n) => loginPage(n));
-        }
-        if (!p.startsWith("/api/"))
-            return this.json(res, 404, { error: "Not found" });
-        if (!authed)
-            return this.json(res, 401, { error: "Sign in first" });
-        if (m === "GET" && p === "/api/summary")
-            return this.summary(res, url);
-        if (m === "GET" && p === "/api/events")
-            return this.events(res, url);
-        if (m === "GET" && p === "/api/community/events")
-            return this.communityEvents(res, url);
-        return this.json(res, 404, { error: "Not found" });
-    }
-    async login(req, res) {
-        if (!this.d.limit(`panel-login:${this.ip(req)}`, 5, 60_000)) {
-            return this.html(res, 429, (n) => loginPage(n, "Too many attempts. Wait a minute."));
-        }
-        let body = "";
-        for await (const c of req) {
-            body += c;
-            if (body.length > 4096)
-                break;
-        }
-        const token = new URLSearchParams(body).get("token") ?? "";
-        if (!safeEqual(token, this.d.token))
-            return this.html(res, 401, (n) => loginPage(n, "Incorrect token."));
-        const maxAge = this.d.sessionHours * 3600;
-        const expSec = Math.floor(this.now() / 1000) + maxAge;
-        return this.send(res, 303, "", "text/plain", { Location: "/", "Set-Cookie": this.cookie(this.sign(expSec), maxAge) });
-    }
-    async grants() {
-        if (this.now() - this.grantsCache.at > 10_000) {
-            this.grantsCache = { at: this.now(), v: await this.d.store.liveGrantCount().catch(() => null) };
-        }
-        return this.grantsCache.v;
-    }
-    async summary(res, url) {
-        const win = url.searchParams.get("window") ?? "15m";
-        const spec = WINDOWS[win];
-        if (!spec)
-            return this.json(res, 400, { error: `window must be one of ${Object.keys(WINDOWS).join(", ")}` });
-        const [span, bucketMs] = spec;
-        const to = this.now() + 1; // include events stamped in this very millisecond
-        const from = to - span;
-        const S = this.d.store;
-        try {
-            const [totals, prev, series, histogram, byTool, byInstance, byError, slowest, httpTotals, httpByRoute, httpSeries, live, byUser, userCounts, userSeries, activeUsers, totalUsers] = await Promise.all([
-                S.auditTotals("tool", from, to),
-                S.auditTotals("tool", from - span, from),
-                S.auditSeries("tool", from, to, bucketMs),
-                S.auditHistogram("tool", from, to),
-                S.auditBreakdown("tool", "name", from, to, 30),
-                S.auditBreakdown("tool", "instance", from, to, 50),
-                S.auditBreakdown("tool", "errorClass", from, to, 20),
-                S.auditSlowest("tool", from, to, 8),
-                S.auditTotals("http", from, to),
-                S.auditBreakdown("http", "name", from, to, 20),
-                S.auditSeries("http", from, to, bucketMs),
-                this.grants(),
-                S.auditBreakdown("tool", "username", from, to, 50),
-                S.userEventCounts(from, to),
-                S.userEventSeries(from, to, bucketMs),
-                S.auditActiveUsers(from, to),
-                S.countAccounts(),
-            ]);
-            const started = userCounts.byKind.started ?? 0;
-            const completed = userCounts.byKind.completed ?? 0;
-            const nowMs = this.now();
-            const samples = await this.d.store.nodeSamples(nowMs - 15 * 60_000);
-            const nodes = latestPerNode(samples, nowMs);
-            const newest = nodes.length ? Math.min(...nodes.map((n) => n.ageMs)) : null;
-            const pings = samples.filter((x) => x.dbPingMs != null).slice(0, 12).map((x) => x.dbPingMs).reverse();
-            const lead = nodes[0];
-            const health = assessHealth({
-                count: totals.count,
-                faults: totals.faults,
-                p95: totals.p95,
-                dbPingMs: lead?.dbPingMs ?? null,
-                loopLagP99Ms: Math.max(0, ...nodes.filter((n) => n.ageMs <= BRIDGE_SILENT_MS).map((n) => n.loopLagP99Ms)),
-                slowMs: this.d.slowMs,
-                recentDbFailed: samples.slice(0, 3).length > 0 && samples.slice(0, 3).every((x) => x.dbPingMs == null),
-                bridgeSilentMs: newest,
-            });
-            return this.json(res, 200, {
-                window: win,
-                from,
-                to,
-                bucketMs,
-                slowMs: this.d.slowMs,
-                generatedAt: this.now(),
-                health,
-                totals,
-                previous: prev,
-                series,
-                histogram,
-                byTool,
-                byInstance,
-                byError,
-                slowest: slowest.map(rowJson),
-                http: { totals: httpTotals, byRoute: httpByRoute, series: httpSeries },
-                community: {
-                    name: this.d.communityName ?? "cliped",
-                    totalUsers,
-                    activeUsers,
-                    counts: userCounts.byKind,
-                    failures: userCounts.failures,
-                    series: userSeries,
-                    byUser,
-                    // Flows that were started but never finished (abandoned) count against the rate: that is what a visitor experienced.
-                    successRate: started > 0 ? Math.min(1, completed / started) : null,
-                },
-                system: { nodes, bridgeSilentMs: newest, bridgeSilentAfterMs: BRIDGE_SILENT_MS, recentPing: pings, mode: this.d.mode, persistent: this.d.persistent, liveGrants: live, panelPingMs: this.d.panelPingMs?.() ?? null },
-            });
-        }
-        catch (e) {
-            return this.json(res, 500, { error: `Could not read telemetry: ${e.message}` });
-        }
-    }
-    async communityEvents(res, url) {
-        const after = Math.max(0, Number(url.searchParams.get("after")) || 0);
-        const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit")) || 60));
-        try {
-            // `started` / `completed` are counters, not log lines; the feed is the human-readable stream.
-            const rows = (await this.d.store.userEventsRecent(after, limit * 3)).filter((e) => !["started", "completed"].includes(e.kind)).slice(0, limit);
-            return this.json(res, 200, { name: this.d.communityName ?? "cliped", events: rows.map((e) => ({ id: e.id, at: e.at, kind: e.kind, username: e.username, detail: e.detail })) });
-        }
-        catch (e) {
-            return this.json(res, 500, { error: `Could not read community events: ${e.message}` });
-        }
-    }
-    async events(res, url) {
-        const after = Math.max(0, Number(url.searchParams.get("after")) || 0);
-        const limit = Math.min(200, Math.max(1, Number(url.searchParams.get("limit")) || 50));
-        const k = url.searchParams.get("kind");
-        const kind = k === "http" ? "http" : k === "all" ? undefined : "tool"; // the live tail is about tool calls; HTTP housekeeping has its own table
-        try {
-            return this.json(res, 200, { events: (await this.d.store.auditRecent(after, limit, kind)).map(rowJson) });
-        }
-        catch (e) {
-            return this.json(res, 500, { error: `Could not read events: ${e.message}` });
-        }
-    }
-}
-/** The newest reading from each bridge process that reported recently. */
-export function latestPerNode(samples, nowMs) {
-    const m = new Map();
-    for (const x of samples)
-        if (!m.has(x.node) || x.at > m.get(x.node).at)
-            m.set(x.node, x);
-    return [...m.values()].sort((a, b) => b.at - a.at).map((x) => ({ node: x.node, version: x.version, at: x.at, ageMs: Math.max(0, nowMs - x.at), dbPingMs: x.dbPingMs, loopLagP99Ms: x.loopLagP99Ms, rssMb: x.rssMb, heapMb: x.heapMb, uptimeS: x.uptimeS }));
-}
-function rowJson(r) {
-    return {
-        id: r.id,
-        at: r.at,
-        kind: r.kind,
-        name: r.name,
-        mutation: r.mutation,
-        ok: r.ok,
-        status: r.status,
-        errorClass: r.errorClass,
-        totalMs: r.totalMs,
-        upstreamMs: r.upstreamMs,
-        upstreamCalls: r.upstreamCalls,
-        scope: r.scope,
-        client: r.client,
-        instance: r.instance,
-        node: r.node,
-    };
-}

package/dist/panel/server.js

@@ -1,37 +0,0 @@
-import { createServer } from "node:http";
-import { ipMatcher } from "./config.js";
-/** Client address: `hops` entries from the right of X-Forwarded-For (a client can only forge the left side). */
-export function clientAddress(req, hops) {
-    if (hops > 0) {
-        const parts = String(req.headers["x-forwarded-for"] ?? "").split(",").map((x) => x.trim()).filter(Boolean);
-        if (parts.length >= hops)
-            return parts[parts.length - hops];
-    }
-    return req.socket.remoteAddress ?? "unknown";
-}
-export function createPanelServer(o) {
-    const allowed = o.allowedIps?.length ? ipMatcher(o.allowedIps) : null;
-    return createServer(async (req, res) => {
-        try {
-            const url = new URL(req.url ?? "/", "http://panel");
-            if (url.pathname === "/healthz") {
-                res.writeHead(200, { "Content-Type": "application/json" });
-                return void res.end('{"ok":true}');
-            }
-            if (allowed && !allowed(clientAddress(req, o.proxyHops ?? 0))) {
-                res.writeHead(403, { "Content-Type": "text/plain" });
-                return void res.end("Forbidden");
-            }
-            if (!(await o.routes.handle(req, res, url)) && !res.headersSent) {
-                res.writeHead(404, { "Content-Type": "application/json" });
-                res.end('{"error":"Not found"}');
-            }
-        }
-        catch {
-            if (!res.headersSent) {
-                res.writeHead(500, { "Content-Type": "application/json" });
-                res.end('{"error":"Internal error"}');
-            }
-        }
-    });
-}

package/docs/panel-role.sql

@@ -1,26 +0,0 @@
--- READ-ONLY database role for the operator panel (the separate admin dashboard).
--- Run as your ADMIN role after the migrations (and again after any future migration).
---
--- 1. Create the role yourself with a strong generated password (don't commit it):
---      create role panel_ro login password '<paste a long random password>';
--- 2. Run the rest of this file.
--- 3. Use that role in the panel's PANEL_DATABASE_URL. The bridge never sees this role; the panel never sees the bridge's.
---
--- What this role can read: the telemetry tables (audit_events, user_events, node_samples) and three views that EXCLUDE every secret
--- (panel_accounts, panel_grants, panel_links). It cannot read bridge.accounts (secret hashes, real usernames), bridge.account_links
--- (sealed Paperclip credentials), bridge.grants, tokens, codes or pending requests, and it cannot write anything.
-
-grant usage on schema bridge to panel_ro;
-
-grant select on bridge.panel_accounts, bridge.panel_grants, bridge.panel_links to panel_ro;
-grant select on bridge.audit_events, bridge.user_events, bridge.node_samples to panel_ro;
-
--- RLS is on for every table with no policies (deny by default); admit panel_ro to the three telemetry tables only.
-do $$
-declare t text;
-begin
-  foreach t in array array['audit_events', 'user_events', 'node_samples'] loop
-    execute format('drop policy if exists panel_ro_read on bridge.%I', t);
-    execute format('create policy panel_ro_read on bridge.%I for select to panel_ro using (true)', t);
-  end loop;
-end $$;