papercliped 1.1.0-beta.2 → 2.1.0

package/dist/openapi.js

@@ -1,4 +1,4 @@
-import { zodToJsonSchema } from "zod-to-json-schema";
+import { z } from "zod";
 import { VERSION as SERVER_VERSION } from "./version.js";
 import { tools } from "./tools.js";
 /**
@@ -6,10 +6,27 @@ import { tools } from "./tools.js";
  * catalogue the MCP server uses, so the two surfaces cannot drift.
  * Each tool is `POST /actions/{name}` with the tool input as the JSON body.
  */
+/**
+ * Zod's JSON Schema for a tool input, shaped like the hand-checked contract ChatGPT Actions have always seen: objects with
+ * fixed properties reject unknown keys, and Zod-only string formats (e.g. "starts_with") are left out.
+ */
+function tidy(node) {
+    if (Array.isArray(node))
+        return node.map(tidy);
+    if (!node || typeof node !== "object")
+        return node;
+    const out = {};
+    for (const [k, v] of Object.entries(node))
+        if (!(k === "format" && v === "starts_with"))
+            out[k] = tidy(v);
+    if (out.type === "object" && out.properties && !("additionalProperties" in out))
+        out.additionalProperties = false;
+    return out;
+}
 export function buildOpenApi(serverUrl) {
     const paths = {};
     for (const t of tools) {
-        const { $schema, ...schema } = zodToJsonSchema(t.schema, { target: "openApi3" });
+        const { $schema, ...schema } = tidy(z.toJSONSchema(t.schema, { target: "openapi-3.0", io: "input" }));
         paths[`/actions/${t.name}`] = {
             post: {
                 operationId: t.name,

package/dist/public-api/health.js

@@ -0,0 +1,46 @@
+/** Bridges report 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 };
+}
+/** 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 }));
+}

package/dist/public-api/openapi.js

@@ -0,0 +1,51 @@
+import { AUTH_FAILURE_REASONS, ERROR_CLASSES, PUBLIC_SCHEMA_VERSION, PUBLIC_WINDOWS } from "./types.js";
+/**
+ * OpenAPI for the public, aggregate-only API. Kept separate from /openapi.json on purpose: that document is imported as
+ * ChatGPT Actions, and these system statistics are not tools the model should call.
+ */
+export function buildPublicOpenApi(serverUrl, version) {
+    const win = { name: "window", in: "query", required: false, schema: { type: "string", enum: [...PUBLIC_WINDOWS], default: "24h" } };
+    const counts = (keys) => ({ type: "object", properties: Object.fromEntries(keys.map((k) => [k, { type: "integer" }])), required: [...keys] });
+    const ok = (ref) => ({
+        "200": { description: "OK (cached up to 30 s)", content: { "application/json": { schema: { $ref: `#/components/schemas/${ref}` } } } },
+        "400": { description: "Invalid window" },
+        "429": { description: "Rate limited (60 requests per minute per address)" },
+        "503": { description: "Statistics temporarily unavailable" },
+    });
+    const latency = { type: "object", properties: { p50: { type: "number" }, p95: { type: "number" }, p99: { type: "number" } } };
+    return {
+        openapi: "3.1.0",
+        info: { title: "Papercliped public API", version, description: `Aggregate-only system statistics (schemaVersion ${PUBLIC_SCHEMA_VERSION}). No identities, hosts or per-user data. CORS-open for GET, no credentials.` },
+        servers: [{ url: serverUrl }],
+        tags: [{ name: "public", description: "Public, read-only, aggregate statistics" }],
+        paths: {
+            "/api/public/v1/info": { get: { tags: ["public"], operationId: "publicInfo", summary: "API info", responses: ok("PublicInfo") } },
+            "/api/public/v1/status": { get: { tags: ["public"], operationId: "publicStatus", summary: "Service status", responses: ok("PublicStatus") } },
+            "/api/public/v1/stats": { get: { tags: ["public"], operationId: "publicStats", summary: "Aggregate statistics", parameters: [win], responses: ok("PublicStats") } },
+            "/api/public/v1/series": { get: { tags: ["public"], operationId: "publicSeries", summary: "Statistics over time", parameters: [win], responses: ok("PublicSeries") } },
+            "/api/public/v1/repo": { get: { tags: ["public"], operationId: "publicRepo", summary: "GitHub stars, forks and open issues (cached for an hour)", responses: { "200": { description: "OK", content: { "application/json": { schema: { type: "object", properties: { repo: { type: "string" }, url: { type: "string" }, stars: { type: ["integer", "null"] }, forks: { type: ["integer", "null"] }, openIssues: { type: ["integer", "null"] }, fetchedAt: { type: ["string", "null"] } } } } } } } } },
+            "/api/public/v1/errors": { get: { tags: ["public"], operationId: "publicErrors", summary: "Error mix", parameters: [win], responses: ok("PublicErrors") } },
+        },
+        components: {
+            schemas: {
+                PublicInfo: { type: "object", properties: { schemaVersion: { type: "integer" }, service: { type: "string" }, version: { type: "string" }, docs: { type: "string" }, endpoints: { type: "array", items: { type: "object", properties: { path: { type: "string" }, description: { type: "string" } } } } } },
+                PublicStatus: { type: "object", properties: { schemaVersion: { type: "integer" }, status: { type: "string", enum: ["ok", "degraded", "down"] }, version: { type: "string" }, uptimeSeconds: { type: "integer" }, checkedAt: { type: "string", format: "date-time" } } },
+                PublicStats: {
+                    type: "object",
+                    properties: {
+                        schemaVersion: { type: "integer" }, window: { type: "string" }, windowSeconds: { type: "integer" }, generatedAt: { type: "string", format: "date-time" },
+                        service: { type: "object", properties: { version: { type: "string" }, uptimeSeconds: { type: "integer" }, status: { type: "string" } } },
+                        users: { type: "object", properties: { total: { type: "integer" }, active: { type: "integer" }, new: { type: "integer" } } },
+                        connections: { type: "object", properties: { live: { type: "integer" } } },
+                        auth: { type: "object", properties: { flowsStarted: { type: "integer" }, flowsCompleted: { type: "integer" }, flowsFailed: { type: "integer" }, successRate: { type: ["number", "null"] }, failuresByReason: counts(AUTH_FAILURE_REASONS) } },
+                        requests: { type: "object", properties: { count: { type: "integer" }, errors: { type: "integer" }, faults: { type: "integer" }, successRate: { type: ["number", "null"] }, latencyMs: latency, callsPerMinute: { type: "number" }, byTool: { type: "object", additionalProperties: { type: "integer" }, description: "Calls per tool name from the public tool catalogue" } } },
+                        errors: { type: "object", properties: { total: { type: "integer" }, byClass: counts(ERROR_CLASSES) } },
+                        load: { type: "object", properties: { eventLoopLagP99Ms: { type: ["number", "null"] }, dbPingMs: { type: ["number", "null"] }, memoryMb: { type: ["number", "null"] }, bridgesReporting: { type: "integer" } } },
+                    },
+                },
+                PublicSeries: { type: "object", properties: { schemaVersion: { type: "integer" }, window: { type: "string" }, bucketSeconds: { type: "integer" }, buckets: { type: "array", items: { type: "object", properties: { t: { type: "string", format: "date-time" }, requests: { type: "integer" }, errors: { type: "integer" }, faults: { type: "integer" }, p95Ms: { type: "number" }, authCompleted: { type: "integer" }, authFailed: { type: "integer" }, newUsers: { type: "integer" } } } } } },
+                PublicErrors: { type: "object", properties: { schemaVersion: { type: "integer" }, window: { type: "string" }, requests: { type: "integer" }, errorRate: { type: ["number", "null"] }, byClass: counts(ERROR_CLASSES), authFailuresByReason: counts(AUTH_FAILURE_REASONS) } },
+            },
+        },
+    };
+}

package/dist/public-api/routes.js

@@ -0,0 +1,251 @@
+import { tools } from "../tools.js";
+import { buildPublicOpenApi } from "./openapi.js";
+import { assessHealth, BRIDGE_SILENT_MS, latestPerNode } from "./health.js";
+import { AUTH_FAILURE_REASONS, ERROR_CLASSES, PUBLIC_SCHEMA_VERSION, PUBLIC_WINDOWS, } from "./types.js";
+const REPO_CACHE_MS = 3_600_000;
+async function githubRepo(repo) {
+    const r = await fetch(`https://api.github.com/repos/${repo}`, { headers: { accept: "application/vnd.github+json", "user-agent": "papercliped-bridge" }, signal: AbortSignal.timeout(5000) });
+    if (!r.ok)
+        throw new Error(`github ${r.status}`);
+    const j = (await r.json());
+    const n = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0);
+    return { stars: n(j.stargazers_count), forks: n(j.forks_count), openIssues: n(j.open_issues_count) };
+}
+const WINDOW_SPEC = {
+    "1h": { span: 3_600_000, bucket: 300_000 }, // 12 buckets of 5 minutes
+    "24h": { span: 86_400_000, bucket: 3_600_000 }, // 24 hourly buckets
+    "7d": { span: 7 * 86_400_000, bucket: 6 * 3_600_000 }, // 28 buckets of 6 hours
+};
+const CACHE_MS = 30_000;
+const RATE_PER_MIN = 60;
+const TOOL_NAMES = new Set(tools.map((t) => t.name));
+const iso = (ms) => new Date(ms).toISOString();
+const zero = (keys) => Object.fromEntries(keys.map((k) => [k, 0]));
+const ENDPOINTS = [
+    { path: "/api/public/v1/info", description: "This document: version, endpoints, limits." },
+    { path: "/api/public/v1/openapi.json", description: "OpenAPI description of this public API." },
+    { path: "/api/public/v1/status", description: "Is the service up: ok, degraded or down." },
+    { path: "/api/public/v1/stats?window=1h|24h|7d", description: "Aggregate users, connections, sign-ins, requests, errors and load." },
+    { path: "/api/public/v1/series?window=1h|24h|7d", description: "The same numbers over time, in fixed buckets." },
+    { path: "/api/public/v1/errors?window=1h|24h|7d", description: "Error mix by class and sign-in failures by reason." },
+    { path: "/api/public/v1/repo", description: "GitHub stars, forks and open issues of the project (cached for an hour)." },
+    { path: "/api/public/stats", description: "Legacy: total users and live connections." },
+];
+/**
+ * GET /api/public/v1/*: system-level numbers anyone may read. Aggregate only (see types.ts), cached for 30 s, rate-limited
+ * per client address, CORS-open for GET with no credentials.
+ */
+export class PublicApiRoutes {
+    o;
+    now;
+    startedAt;
+    cache = new Map();
+    repoState = { at: 0, v: null, inflight: null };
+    constructor(o) {
+        this.o = o;
+        this.now = o.now ?? Date.now;
+        this.startedAt = o.startedAt ?? this.now();
+    }
+    ip(req) {
+        const hops = this.o.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, extra = {}) {
+        res.writeHead(status, {
+            "Content-Type": "application/json",
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, OPTIONS",
+            "Access-Control-Max-Age": "86400",
+            "X-Content-Type-Options": "nosniff",
+            "Cache-Control": status === 200 ? `public, max-age=${CACHE_MS / 1000}` : "no-store",
+            ...extra,
+        });
+        res.end(JSON.stringify(body));
+        return true;
+    }
+    async cached(key, build) {
+        const hit = this.cache.get(key);
+        if (hit && this.now() - hit.at < CACHE_MS)
+            return hit.body;
+        const body = await build();
+        this.cache.set(key, { at: this.now(), body });
+        return body;
+    }
+    async handle(req, res, url) {
+        const path = url.pathname.replace(/\/+$/, "");
+        if (!path.startsWith("/api/public/v1"))
+            return false;
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, OPTIONS", "Access-Control-Max-Age": "86400" });
+            res.end();
+            return true;
+        }
+        if (req.method !== "GET" && req.method !== "HEAD")
+            return this.send(res, 405, { error: "Only GET is allowed" }, { Allow: "GET, OPTIONS" });
+        if (!(await this.o.store.hit(`pubapi:${this.ip(req)}`, RATE_PER_MIN, 60_000)))
+            return this.send(res, 429, { error: `Rate limit: ${RATE_PER_MIN} requests per minute` }, { "Retry-After": "60" });
+        const route = path.slice("/api/public/v1".length) || "/";
+        const w = url.searchParams.get("window") ?? "24h";
+        const needsWindow = route === "/stats" || route === "/series" || route === "/errors";
+        if (needsWindow && !PUBLIC_WINDOWS.includes(w))
+            return this.send(res, 400, { error: `window must be one of ${PUBLIC_WINDOWS.join(", ")}` });
+        const win = w;
+        try {
+            if (route === "/info")
+                return this.send(res, 200, this.info());
+            if (route === "/openapi.json")
+                return this.send(res, 200, buildPublicOpenApi(this.o.publicUrl ?? `${url.protocol}//${req.headers.host ?? "localhost"}`, this.o.version));
+            if (route === "/repo")
+                return this.send(res, 200, await this.repo());
+            if (route === "/status")
+                return this.send(res, 200, await this.cached("status", () => this.status()));
+            if (route === "/stats")
+                return this.send(res, 200, await this.cached(`stats:${win}`, () => this.stats(win)));
+            if (route === "/series")
+                return this.send(res, 200, await this.cached(`series:${win}`, () => this.series(win)));
+            if (route === "/errors")
+                return this.send(res, 200, await this.cached(`errors:${win}`, () => this.errors(win)));
+        }
+        catch {
+            return this.send(res, 503, { error: "Statistics are temporarily unavailable" });
+        }
+        return this.send(res, 404, { error: "Not found", endpoints: ENDPOINTS.map((e) => e.path) });
+    }
+    info() {
+        return { schemaVersion: PUBLIC_SCHEMA_VERSION, service: "papercliped", version: this.o.version, docs: this.o.docsUrl, endpoints: ENDPOINTS, windows: PUBLIC_WINDOWS, rateLimit: { requestsPerMinute: RATE_PER_MIN }, cacheSeconds: CACHE_MS / 1000 };
+    }
+    /** Stale-while-revalidate: always answers at once; refreshes from GitHub at most once an hour (and after a failure, after 10 min). */
+    async repo() {
+        const name = this.o.repo ?? "OpenSourcx/papercliped";
+        const st = this.repoState;
+        const age = this.now() - st.at;
+        const due = !st.v ? true : st.v.stars == null ? age > 600_000 : age > REPO_CACHE_MS;
+        if (due && !st.inflight) {
+            st.inflight = (async () => {
+                try {
+                    const n = await (this.o.repoFetcher ?? githubRepo)(name);
+                    st.v = { schemaVersion: PUBLIC_SCHEMA_VERSION, repo: name, url: `https://github.com/${name}`, ...n, fetchedAt: iso(this.now()) };
+                }
+                catch {
+                    st.v = st.v?.stars != null ? st.v : { schemaVersion: PUBLIC_SCHEMA_VERSION, repo: name, url: `https://github.com/${name}`, stars: null, forks: null, openIssues: null, fetchedAt: null };
+                }
+                finally {
+                    st.at = this.now();
+                    st.inflight = null;
+                }
+            })();
+            if (!st.v)
+                await st.inflight; // the very first request waits (up to the 5 s timeout)
+        }
+        return st.v;
+    }
+    uptime = () => Math.max(0, Math.round((this.now() - this.startedAt) / 1000));
+    /** Service health over the last hour, from tool-call totals and the bridges' own health reports. */
+    async health() {
+        const to = this.now() + 1;
+        const [totals, samples] = await Promise.all([this.o.store.auditTotals("tool", to - 3_600_000, to), this.o.store.nodeSamples(to - 15 * 60_000)]);
+        const nodes = latestPerNode(samples, this.now());
+        const fresh = nodes.filter((n) => n.ageMs <= BRIDGE_SILENT_MS);
+        const h = assessHealth({
+            count: totals.count,
+            faults: totals.faults,
+            p95: totals.p95,
+            dbPingMs: nodes[0]?.dbPingMs ?? null,
+            loopLagP99Ms: Math.max(0, ...fresh.map((n) => n.loopLagP99Ms)),
+            slowMs: this.o.slowMs ?? 2000,
+            recentDbFailed: samples.slice(0, 3).length > 0 && samples.slice(0, 3).every((x) => x.dbPingMs == null),
+            bridgeSilentMs: nodes.length ? Math.min(...nodes.map((n) => n.ageMs)) : null,
+        });
+        // This process is answering, so "no bridge has reported yet" (e.g. a fresh start) is not an outage.
+        const status = h.state === "critical" ? "down" : h.state === "degraded" && !(h.reasons.length === 1 && h.reasons[0].startsWith("no bridge")) ? "degraded" : "ok";
+        const lead = fresh[0];
+        return { status, load: { eventLoopLagP99Ms: lead ? Math.round(lead.loopLagP99Ms) : null, dbPingMs: lead?.dbPingMs != null ? Math.round(lead.dbPingMs) : null, memoryMb: lead ? Math.round(lead.rssMb) : null, bridgesReporting: fresh.length } };
+    }
+    async status() {
+        return { schemaVersion: PUBLIC_SCHEMA_VERSION, status: (await this.health()).status, version: this.o.version, uptimeSeconds: this.uptime(), checkedAt: iso(this.now()) };
+    }
+    failuresByReason(failures) {
+        const out = zero(AUTH_FAILURE_REASONS);
+        for (const [key, n] of Object.entries(failures)) {
+            const reason = key.split(":")[1];
+            out[AUTH_FAILURE_REASONS.includes(reason) ? reason : "other"] += n;
+        }
+        return out;
+    }
+    byClass(rows) {
+        const out = zero(ERROR_CLASSES);
+        for (const r of rows)
+            out[ERROR_CLASSES.includes(r.key) ? r.key : "other"] += r.count;
+        return out;
+    }
+    async stats(win) {
+        const { span } = WINDOW_SPEC[win];
+        const to = this.now() + 1;
+        const from = to - span;
+        const S = this.o.store;
+        const [totals, byTool, toolErrors, httpErrors, users, active, counts, live, health] = await Promise.all([
+            S.auditTotals("tool", from, to),
+            S.auditBreakdown("tool", "name", from, to, 100),
+            S.auditBreakdown("tool", "errorClass", from, to, 50),
+            S.auditBreakdown("http", "errorClass", from, to, 50),
+            S.countAccounts(),
+            S.auditActiveUsers(from, to),
+            S.userEventCounts(from, to),
+            S.liveGrantCount(),
+            this.health(),
+        ]);
+        const started = counts.byKind.started ?? 0;
+        const completed = counts.byKind.completed ?? 0;
+        const failures = this.failuresByReason(counts.failures);
+        const failed = Object.values(failures).reduce((a, b) => a + b, 0);
+        const errorClasses = this.byClass([...toolErrors.filter((r) => r.key && r.key !== "null").map((r) => ({ key: r.key, count: r.errors || r.count })), ...httpErrors.filter((r) => r.key && r.key !== "null").map((r) => ({ key: r.key, count: r.errors || r.count }))]);
+        const tools = {};
+        for (const r of byTool)
+            if (TOOL_NAMES.has(r.key))
+                tools[r.key] = r.count; // only catalogue names, never other keys
+        return {
+            schemaVersion: PUBLIC_SCHEMA_VERSION,
+            window: win,
+            windowSeconds: span / 1000,
+            generatedAt: iso(this.now()),
+            service: { version: this.o.version, uptimeSeconds: this.uptime(), status: health.status },
+            users: { total: users, active, new: counts.byKind.joined ?? 0 },
+            connections: { live },
+            auth: { flowsStarted: started, flowsCompleted: completed, flowsFailed: failed, successRate: started > 0 ? Math.min(1, completed / started) : null, failuresByReason: failures },
+            requests: {
+                count: totals.count,
+                errors: totals.errors,
+                faults: totals.faults,
+                successRate: totals.count ? (totals.count - totals.errors) / totals.count : null,
+                latencyMs: { p50: Math.round(totals.p50), p95: Math.round(totals.p95), p99: Math.round(totals.p99) },
+                callsPerMinute: Math.round((totals.count / (span / 60_000)) * 100) / 100,
+                byTool: tools,
+            },
+            errors: { total: Object.values(errorClasses).reduce((a, b) => a + b, 0), byClass: errorClasses },
+            load: health.load,
+        };
+    }
+    async series(win) {
+        const { span, bucket } = WINDOW_SPEC[win];
+        const to = this.now() + 1;
+        const from = to - span;
+        const [calls, flows] = await Promise.all([this.o.store.auditSeries("tool", from, to, bucket), this.o.store.userEventSeries(from, to, bucket)]);
+        const start = Math.floor(from / bucket) * bucket;
+        const buckets = [];
+        for (let t = start; t < to; t += bucket) {
+            const c = calls.find((x) => x.t === t);
+            const f = flows.find((x) => x.t === t);
+            buckets.push({ t: iso(t), requests: c?.count ?? 0, errors: c?.errors ?? 0, faults: c?.faults ?? 0, p95Ms: Math.round(c?.p95 ?? 0), authCompleted: f?.completed ?? 0, authFailed: f?.failed ?? 0, newUsers: f?.joined ?? 0 });
+        }
+        return { schemaVersion: PUBLIC_SCHEMA_VERSION, window: win, bucketSeconds: bucket / 1000, generatedAt: iso(this.now()), buckets };
+    }
+    async errors(win) {
+        const s = await this.cached(`stats:${win}`, () => this.stats(win));
+        return { schemaVersion: PUBLIC_SCHEMA_VERSION, window: win, generatedAt: s.generatedAt, requests: s.requests.count, errorRate: s.requests.count ? s.requests.errors / s.requests.count : null, byClass: s.errors.byClass, authFailuresByReason: s.auth.failuresByReason };
+    }
+}

package/dist/public-api/types.js

@@ -0,0 +1,14 @@
+/**
+ * The public, aggregate-only Papercliped API (GET /api/public/v1/*). These types are the contract: consumers (the website's
+ * status page, the separate domain service and its dashboard) can import or copy them. Additive changes keep
+ * `schemaVersion`; anything breaking bumps it and gets a new path (/v2).
+ *
+ * Aggregate only, by design: no usernames, aliases, account/grant ids, Paperclip hosts, app names, IPs, tokens or free text,
+ * and no per-user or per-tenant breakdown. Categories are fixed lists, never values taken from user data.
+ */
+export const PUBLIC_SCHEMA_VERSION = 1;
+export const PUBLIC_WINDOWS = ["1h", "24h", "7d"];
+/** Why a sign-in or connect flow failed. Anything the bridge records outside this list is counted as `other`. */
+export const AUTH_FAILURE_REASONS = ["bad_credentials", "rate_limited", "denied", "expired", "unreachable", "invalid_instance", "too_many_attempts", "other"];
+/** Error classes of tool calls and protocol requests. Anything else is counted as `other`. */
+export const ERROR_CLASSES = ["invalid_input", "insufficient_scope", "read_only", "upstream_4xx", "upstream_5xx", "upstream_unreachable", "rate_limited", "unauthorized", "internal", "other"];

package/dist/server.js

@@ -111,6 +111,10 @@ export function createHttpServer(config, http, opts = {}) {
                 const host = req.headers.host ?? `${http.host}:${http.port}`;
                 return json(res, 200, buildOpenApi(http.oauth?.issuer ?? http.publicUrl ?? `http://${host}`));
             }
+            if (opts.publicApi && (await opts.publicApi.handle(req, res, url)))
+                return;
+            if (opts.web && (await opts.web.handle(req, res, url)))
+                return;
             if (opts.site && (await opts.site.handle(req, res, url)))
                 return;
             if (opts.manage && (await opts.manage.handle(req, res, url)))

package/dist/site/landing.js

@@ -57,7 +57,7 @@ export function landingBody() {
   <p class="sub2">Pick what you would let Claude do, then see what happens when it tries.</p>
   <div class="seg" role="group" aria-label="Access level">
     <button type="button" data-l="read" aria-pressed="true">Read only</button>
-    <button type="button" data-l="control" aria-pressed="false">Full control (beta)</button>
+    <button type="button" data-l="control" aria-pressed="false">Full control</button>
   </div>
   <div class="chat" id="chat" aria-live="polite"></div>
 </section>
@@ -65,7 +65,7 @@ export function landingBody() {
 <section class="band"><div class="big">Papercliped, not Paperclipped.<small>The little clip that connects your AI to the Paperclip you already run. No lock-in, and you can disconnect in one click.</small></div></section>
 
 <section class="cards" style="margin-top:34px">
-  <div class="card"><h2>You choose the access</h2><p>Read only by default. Full control (beta) is opt-in, every time you connect.</p></div>
+  <div class="card"><h2>You choose the access</h2><p>Read only by default. Full control is opt-in, every time you connect.</p></div>
   <div class="card"><h2>Your keys stay sealed</h2><p>Your Paperclip key is stored encrypted and is never shown to the AI app.</p></div>
   <div class="card"><h2>Optionally anonymous</h2><p>Appear as an alias like Ann02 in the operator's logs instead of your username.</p></div>
   <div class="card"><h2>Manage it yourself</h2><p>Beta users get a page to see every connected app, change its access and disconnect it.</p></div>
@@ -136,7 +136,7 @@ const SCRIPT_TEXT = `
       ["me", "Pause the Web Engineer."],
       ["ai", "Done. The Web Engineer is paused. I will tell you before I do anything destructive.", "Change agents", true],
       ["me", "Terminate the Mail Officer."],
-      ["ai", "That needs Admin access, which you did not give me. I can pause it instead.", "Terminate agents", false]
+      ["ai", "Terminating can't be undone, so I will check first: do you want me to terminate the Mail Officer?", "Terminate agents", true]
     ]
   };
   function show(l) {

package/dist/site/markdown.js

@@ -1,4 +1,5 @@
-import { esc } from "../oauth/pages.js";
+// No imports, so the website (web/) can reuse this renderer as is.
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 /**
  * A deliberately small Markdown renderer for the project's own pages (docs, privacy, terms). Everything is HTML-escaped first;
  * only a fixed set of constructs produces tags, and links are limited to http(s), mailto and same-site paths.

package/dist/site/site.js

@@ -7,12 +7,24 @@ import { LANDING_CSS, LANDING_SCRIPT, landingBody } from "./landing.js";
 import { renderMarkdown } from "./markdown.js";
 const NAV = [
     { slug: "getting-started", title: "Getting started" },
+    { slug: "what-is-papercliped", title: "What is Papercliped?" },
     { slug: "signup", title: "Create your account" },
-    { slug: "manage", title: "Manage connections (beta)" },
+    { slug: "connect-your-paperclip", title: "Set up your Paperclip" },
+    { slug: "other-ai-apps", title: "Any AI app (MCP)" },
+    { slug: "chatgpt", title: "ChatGPT setup" },
     { slug: "permissions", title: "Permissions" },
+    { slug: "manage", title: "Manage connections" },
+    { slug: "paperclip-plugin", title: "Paperclip plugin" },
     { slug: "anonymous-mode", title: "Anonymous mode" },
+    { slug: "self-hosting", title: "Run it yourself" },
+    { slug: "tools", title: "Tool reference" },
+    { slug: "manage-api", title: "Manage API" },
+    { slug: "public-api", title: "Public API and status" },
+    { slug: "environment", title: "Environment variables" },
+    { slug: "cli", title: "Command line" },
+    { slug: "limits-and-errors", title: "Limits and errors" },
     { slug: "security", title: "Security" },
-    { slug: "chatgpt", title: "ChatGPT setup" },
+    { slug: "faq", title: "FAQ" },
     { slug: "troubleshooting", title: "Troubleshooting" },
 ];
 const CLIP = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>`;
@@ -53,7 +65,7 @@ export class SiteRoutes {
     constructor(o) {
         this.o = o;
         const dir = o.dir ?? new URL("../../site/", import.meta.url);
-        const fill = (md) => md.replaceAll("{{URL}}", o.url).replaceAll("{{CONTACT}}", o.contact).replaceAll("{{DATE}}", o.effective);
+        const fill = (md) => md.replaceAll("{{MCP}}", o.mcpUrl ?? o.url).replaceAll("{{URL}}", o.url).replaceAll("{{CONTACT}}", o.contact).replaceAll("{{DATE}}", o.effective);
         const load = (rel) => renderMarkdown(fill(readFileSync(new URL(rel, dir), "utf8")));
         this.pages.set("/privacy", { title: "Privacy", html: load("privacy.md") });
         this.pages.set("/terms", { title: "Terms", html: load("terms.md") });
@@ -62,7 +74,7 @@ export class SiteRoutes {
     }
     layout(title, body, current, script) {
         const nav = `<nav aria-label="Main"><a href="/docs/getting-started"${current.startsWith("/docs") ? " aria-current=page" : ""}>Docs</a><a href="/privacy"${current === "/privacy" ? " aria-current=page" : ""}>Privacy</a><a href="/terms"${current === "/terms" ? " aria-current=page" : ""}>Terms</a><a href="https://github.com/OpenSourcx/papercliped" rel="noopener noreferrer">GitHub</a></nav>`;
-        return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light"><title>${esc(title)} · Papercliped</title>${FAVICON_LINK}<meta name="description" content="Connect Claude and ChatGPT to your Paperclip: control agents, sync and get reports, with permissions you choose."><style>${CSS}${script?.css ?? ""}</style></head><body><header><a class="brand" href="/">${CLIP}<span>Papercliped</span></a>${nav}</header>${body}<footer>Papercliped ${esc(VERSION)} (beta) · <a href="/privacy">Privacy</a> · <a href="/terms">Terms</a> · <a href="/docs/security">Security</a></footer>${script ? `<script nonce="${script.nonce}">${script.code}</script>` : ""}</body></html>`;
+        return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light"><title>${esc(title)} · Papercliped</title>${FAVICON_LINK}<meta name="description" content="Connect Claude and ChatGPT to your Paperclip: control agents, sync and get reports, with permissions you choose."><style>${CSS}${script?.css ?? ""}</style></head><body><header><a class="brand" href="/">${CLIP}<span>Papercliped</span></a>${nav}</header>${body}<footer>Papercliped ${esc(VERSION)} · <a href="/privacy">Privacy</a> · <a href="/terms">Terms</a> · <a href="/docs/security">Security</a></footer>${script ? `<script nonce="${script.nonce}">${script.code}</script>` : ""}</body></html>`;
     }
     doc(path) {
         const p = this.pages.get(path);

package/dist/telemetry/recorder.js

@@ -157,7 +157,7 @@ export class SystemSampler {
     }
 }
 /**
- * Writes this bridge process's health to the database every 30 s, so the separate panel can show it and notice when it STOPS
+ * Writes this bridge process's health to the database every 30 s, so the public status API and the operator dashboard can show it and notice when it STOPS
  * (asleep on a free tier, crashed, or cut off from the database). Failures are swallowed: reporting must never hurt the bridge.
  */
 export class NodeReporter {

package/dist/tools.js

@@ -389,6 +389,43 @@ export const tools = [
         },
     }),
     // ───────────────────────────── escape hatch ─────────────────────────────
+    // ───────────────────────────── Papercliped itself ─────────────────────────────
+    tool({
+        name: "papercliped_service_status",
+        title: "Papercliped service status",
+        description: "Is the hosted Papercliped service working? Returns its status (ok, degraded, down), version and aggregate 24-hour numbers (requests, success rate, latency, sign-ins). Public data only; does not touch Paperclip.",
+        access: "read",
+        schema: z.object({ window: z.enum(["1h", "24h", "7d"]).optional().describe("Time window for the numbers (default 24h)") }),
+        run: async (_c, i) => {
+            const base = paperclipedUrl();
+            const get = async (path) => {
+                let r;
+                try {
+                    r = await fetch(`${base}${path}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(8000) });
+                }
+                catch {
+                    throw new Error(`Cannot reach Papercliped's status API at ${base}`);
+                }
+                if (!r.ok)
+                    throw new Error(`Cannot reach Papercliped's status API at ${base} (HTTP ${r.status})`);
+                return (await r.json());
+            };
+            const w = i.window ?? "24h";
+            const [status, stats] = await Promise.all([get("/api/public/v1/status"), get(`/api/public/v1/stats?window=${w}`)]);
+            return {
+                service: base,
+                status: status.status,
+                version: status.version,
+                uptimeSeconds: status.uptimeSeconds,
+                window: w,
+                users: stats.users,
+                liveConnections: stats.connections?.live,
+                requests: { count: stats.requests?.count, successRate: stats.requests?.successRate, latencyMs: stats.requests?.latencyMs },
+                signIns: { started: stats.auth?.flowsStarted, completed: stats.auth?.flowsCompleted, successRate: stats.auth?.successRate },
+                statusPage: `${base}/status`,
+            };
+        },
+    }),
     tool({
         name: "paperclip_api_request",
         title: "Raw API request",
@@ -397,8 +434,8 @@ export const tools = [
         schema: z.object({
             method: z.enum(["GET", "POST", "PATCH", "PUT", "DELETE"]),
             path: z.string().startsWith("/").describe("Path after /api, e.g. /companies"),
-            query: z.record(z.union([z.string(), z.number(), z.boolean()])).optional(),
-            body: z.record(z.unknown()).optional(),
+            query: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+            body: z.record(z.string(), z.unknown()).optional(),
             confirm: z.boolean().optional().describe("Required true for non-GET calls"),
         }),
         run: (c, i) => {
@@ -410,3 +447,12 @@ export const tools = [
     }),
 ];
 export const toolsByName = new Map(tools.map((t) => [t.name, t]));
+/** Where papercliped_service_status looks (PAPERCLIPED_URL; https, or http on localhost for development). */
+function paperclipedUrl() {
+    const raw = (process.env.PAPERCLIPED_URL ?? "").trim() || "https://papercliped.co";
+    const u = new URL(raw);
+    const loop = ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname);
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && loop))
+        throw new ToolInputError("PAPERCLIPED_URL must be an https address");
+    return u.origin;
+}

package/dist/web/csp.js

@@ -0,0 +1,16 @@
+/**
+ * The Content-Security-Policy for the website (web/). The bridge sends it with every page, and `vite preview` sends the same
+ * one so the website's route check catches violations: everything from our own origin, nothing inline, no third parties.
+ */
+export const SITE_CSP = [
+    "default-src 'none'",
+    "script-src 'self'",
+    "style-src 'self'",
+    "font-src 'self'",
+    "img-src 'self' data:",
+    "connect-src 'self'",
+    "manifest-src 'self'",
+    "frame-ancestors 'none'",
+    "base-uri 'none'",
+    "form-action 'self'",
+].join("; ");

package/dist/web/hosts.js

@@ -0,0 +1,23 @@
+const ROLES = ["marketing", "docs", "api", "forum"];
+const HOST = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(:\d{1,5})?$/;
+export function parseHosts(raw) {
+    const map = { marketing: [], docs: [], api: [], forum: [] };
+    for (const part of (raw ?? "").split(";").map((s) => s.trim()).filter(Boolean)) {
+        const [role, list] = part.split("=");
+        const r = role?.trim().toLowerCase();
+        if (!ROLES.includes(r))
+            throw new Error(`PUBLIC_HOSTS: unknown role "${role}" (use ${ROLES.join(", ")})`);
+        for (const h of (list ?? "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)) {
+            if (!HOST.test(h))
+                throw new Error(`PUBLIC_HOSTS: "${h}" is not a host name`);
+            if (ROLES.some((x) => map[x].includes(h)))
+                throw new Error(`PUBLIC_HOSTS: "${h}" is listed twice`);
+            map[r].push(h);
+        }
+    }
+    return map;
+}
+export function roleOf(map, host) {
+    const h = (host ?? "").toLowerCase();
+    return ROLES.find((r) => map[r].includes(h)) ?? null;
+}