papercliped 1.1.0-beta.2 → 2.2.0

package/dist/oauth/provider.js

@@ -1,4 +1,3 @@
-import { hkdfSync } from "node:crypto";
 import { generateSecretKey, burnVerify, hashSecretKey, normalizeSecretKey, verifySecretKey } from "../accounts/secret.js";
 import { anonInstanceLabel, displayName, generateAlias } from "../accounts/alias.js";
 import { AliasTakenError } from "../accounts/types.js";
@@ -9,13 +8,20 @@ import { UnsafeUrlError, createSafeFetch, parseInstanceUrl } from "../net/safe-f
 import { Keyring, isValidCodeChallenge, randomToken, safeEqual, sha256Hex, verifyPkce } from "./crypto.js";
 import { approvePage, choosePage, consentPage, errorPage, instancePage, scopePage, secretPage, usernamePage, welcomePage } from "./pages.js";
 import { LoginError, PaperclipLogin } from "./paperclip-login.js";
+import { VERSION } from "../version.js";
 import { MemoryStore } from "./store.js";
-import { SCOPES, grantableScopes, isScope, maxRank, scopeAllows, scopesUpTo } from "./scopes.js";
+import { SCOPES, grantableScopes, isScope, maxRank, normalizeScope, normalizeScopes, scopeAllows, scopesUpTo } from "./scopes.js";
 const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
 const PENDING_TTL_MS = 10 * 60_000;
 const CODE_TTL_MS = 60_000;
 const MAX_PENDING = 5000;
 const MAX_INSTANCE_ATTEMPTS = 5;
+/** The plugin offered on the instance step: one fixed package, pinned to this bridge's own version (both are released together). */
+const PLUGIN_PACKAGE = "papercliped-paperclip-plugin";
+/** Its id inside Paperclip (the manifest id), used to see whether it is already installed. */
+const PLUGIN_KEY = "papercliped.remote-control";
+/** Paperclip runs npm on its side for an install; allow it more time than ordinary calls. */
+const PLUGIN_INSTALL_MS = 120_000;
 const MAX_FORM_BYTES = 16 * 1024;
 const DAY_MS = 24 * 3600 * 1000;
 class OAuthError extends Error {
@@ -59,6 +65,10 @@ export class OAuthProvider {
     keyring;
     now;
     safeFetch;
+    /** Longer-lived egress-guarded fetch for the plugin install, which makes Paperclip run npm. */
+    installFetch;
+    /** Plugin installs running after a sign-in finished, so tests (and shutdown) can wait for them. */
+    background = new Set();
     multi;
     accounts;
     constructor(deps) {
@@ -69,6 +79,7 @@ export class OAuthProvider {
         this.multi = deps.oauth.mode === "multi";
         this.accounts = deps.oauth.accounts && this.multi;
         this.safeFetch = deps.safeFetch ?? createSafeFetch({ timeoutMs: deps.config.timeoutMs, maxBytes: 2_000_000 });
+        this.installFetch = deps.safeFetch ?? createSafeFetch({ timeoutMs: PLUGIN_INSTALL_MS, maxBytes: 200_000 });
         this.resource = `${deps.oauth.issuer}/mcp`;
         this.metadataUrl = `${deps.oauth.issuer}/.well-known/oauth-protected-resource`;
     }
@@ -83,7 +94,7 @@ export class OAuthProvider {
             /* telemetry only */
         }
     }
-    /** The name logs and the panel show for an account: its alias if it opted into anonymity, else its username. */
+    /** The name logs and the operator dashboard show for an account: its alias if it opted into anonymity, else its username. */
     async who(accountId) {
         if (!accountId)
             return null;
@@ -222,8 +233,8 @@ export class OAuthProvider {
             /* best effort */
         }
     }
-    // ───────────── account management (the beta connection manager) ─────────────
-    // Everything here acts on ONE account and is reached only through ManageRoutes after the owner proved the secret key.
+    // ───────────── account management (the Paperclip plugin's connection manager) ─────────────
+    // Everything here acts on ONE account and is reached only through ManageRoutes, with a plugin token or the secret key.
     /** Username + secret key, throttled exactly like the sign-in page (shared counters, so there is no cheaper way to guess). */
     async manageLogin(req, username, secret) {
         const typed = username.trim().slice(0, 64);
@@ -249,45 +260,21 @@ export class OAuthProvider {
             return false;
         return verifySecretKey(secret, a.secretHash);
     }
-    /** Key for signing manager session cookies (derived from the service secret; never the secret itself). */
-    manageSigningKey() {
-        return Buffer.from(hkdfSync("sha256", this.deps.oauth.secret, "papercliped", "manage-session-v1", 32));
-    }
-    // ── the Paperclip plugin link: a one-time code (typed into the plugin) is exchanged for a long-lived plugin token ──
+    // ── the Paperclip plugin link: the plugin signs in once with username + secret key and gets a long-lived plugin token ──
     // The token is stored as a hash on a synthetic grant (client "paperclip-plugin", NO scopes), so it appears in no tool list,
     // cannot call any Paperclip tool, and is revoked like any grant. It only opens the manage API for its own account.
-    /** A single-use code the user types into the Paperclip plugin. Valid 10 minutes. */
-    async manageIssueLinkCode(a) {
-        const raw = randomToken(9).replace(/[^A-Za-z0-9]/g, "").toUpperCase().padEnd(10, "7").slice(0, 10);
-        const code = `pcl_${raw.slice(0, 5)}-${raw.slice(5)}`;
-        const ttl = 10 * 60_000;
-        await this.store.putCode(sha256Hex(code), { clientId: "plugin-link", redirectUri: "", codeChallenge: "", scopes: [], clientName: "Paperclip plugin", userId: null, instanceUrl: null, sealedCredential: null, accountId: a.id, username: displayName(a), path: "plugin", expiresAt: this.now() + ttl });
-        await this.event("updated", { accountId: a.id, username: displayName(a) }, "plugin_code");
-        return { code, expiresInSec: ttl / 1000 };
-    }
-    /** Trade a link code for a plugin token. Wrong, used and expired codes all look the same. */
-    async manageExchangeLinkCode(req, code, meta) {
-        if (!(await this.limit(`plink:ip:${this.ip(req)}`, 20)))
-            return null;
-        const norm = code.trim().toUpperCase();
-        if (!/^PCL_[A-Z0-9]{5}-[A-Z0-9]{5}$/.test(norm))
-            return null;
-        const taken = await this.store.takeCode(sha256Hex(`pcl_${norm.slice(4)}`));
-        if (taken.status !== "ok" || taken.record.clientId !== "plugin-link" || taken.record.expiresAt < this.now() || !taken.record.accountId)
-            return null;
-        const a = await this.store.getAccount(taken.record.accountId);
-        if (!a || a.disabled)
-            return null;
+    /** A plugin token for an account whose owner just proved the secret key. */
+    async manageLinkPlugin(a, meta) {
         const id = `pcb_pg_${randomToken(10)}`;
         const token = `pcb_pl_${randomToken(32)}`;
         await this.store.putGrant({ id, clientId: "paperclip-plugin", clientName: "Paperclip plugin", userId: meta.paperclipUserId, scopes: [], resource: "manage", instanceUrl: meta.instanceHost ? `https://${meta.instanceHost}` : null, sealedCredential: null, accountId: a.id, username: displayName(a), createdAt: this.now(), lastUsedAt: this.now(), revoked: false });
         await this.store.putAccess(sha256Hex(token), { grantId: id, expiresAt: this.now() + 180 * DAY_MS });
         await this.event("updated", { accountId: a.id, username: displayName(a) }, "plugin_linked");
-        return { token };
+        return { token, linkId: id };
     }
-    /** The account a plugin token belongs to (null if unknown, expired, revoked, or not a plugin token). */
-    async manageAccountForPluginToken(token) {
-        if (!token.startsWith("pcb_pl_"))
+    /** The account (and link id) a plugin token belongs to (null if unknown, expired, revoked, or not a plugin token). */
+    async managePluginPrincipal(token) {
+        if (!token.startsWith("pcb_pl_") || token.length > 200)
             return null;
         const rec = await this.store.getAccess(sha256Hex(token));
         if (!rec || rec.expiresAt < this.now())
@@ -299,10 +286,10 @@ export class OAuthProvider {
         if (!a || a.disabled)
             return null;
         await this.store.touchGrant(g.id);
-        return a;
+        return { account: a, linkId: g.id };
     }
     async manageListPluginLinks(accountId) {
-        return (await this.store.listAccountGrants(accountId)).filter((g) => g.clientId === "paperclip-plugin" && !g.revoked).map((g) => ({ id: g.id, host: g.instanceUrl ? new URL(g.instanceUrl).host : null, createdAt: g.createdAt, lastUsedAt: g.lastUsedAt }));
+        return (await this.store.listAccountGrants(accountId)).filter((g) => g.clientId === "paperclip-plugin" && !g.revoked).map((g) => ({ id: g.id, host: g.instanceUrl ? new URL(g.instanceUrl).host : null, paperclipUserId: g.userId, createdAt: g.createdAt, lastUsedAt: g.lastUsedAt }));
     }
     async manageRevokePluginLink(a, id) {
         const g = await this.store.getGrant(id);
@@ -315,24 +302,16 @@ export class OAuthProvider {
     manageAccount(accountId) {
         return this.store.getAccount(accountId);
     }
-    async manageSetBeta(a, beta) {
-        if (!!a.beta === beta)
-            return;
-        await this.store.setAccountBeta(a.id, beta);
-        await this.event("updated", { accountId: a.id, username: displayName(a) }, beta ? "beta_on" : "beta_off");
-    }
     async manageConnections(accountId) {
         return (await this.store.listAccountGrants(accountId))
             .filter((g) => !g.revoked && g.clientId !== "paperclip-plugin")
             .map((g) => ({ id: g.id, app: g.clientName, level: levelOf(g.scopes), createdAt: g.createdAt, lastUsedAt: g.lastUsedAt }));
     }
-    /** Change what a connected app may do. The owner may move it between read and control, or lower an admin grant; admin is never granted here. */
+    /** Change what a connected app may do: Read only or Full control. */
     async manageSetLevel(a, grantId, level) {
         const g = await this.store.getGrant(grantId);
         if (!g || g.revoked || g.accountId !== a.id || g.clientId === "paperclip-plugin")
             return false;
-        if (level === "paperclip:admin" && levelOf(g.scopes) !== "paperclip:admin")
-            return false;
         if (!(await this.store.setGrantScopes(g.id, scopesUpTo(level))))
             return false;
         await this.event("updated", { accountId: a.id, username: displayName(a) }, `level_${level.split(":")[1]}`);
@@ -352,6 +331,10 @@ export class OAuthProvider {
     async manageRotateSecret(a) {
         const secret = generateSecretKey();
         await this.store.setAccountSecret(a.id, await hashSecretKey(normalizeSecretKey(secret)));
+        // A new secret key means "I may be compromised": every plugin link goes too (the caller relinks the plugin it came from).
+        for (const g of await this.store.listAccountGrants(a.id))
+            if (g.clientId === "paperclip-plugin" && !g.revoked)
+                await this.store.revokeGrant(g.id);
         await this.event("updated", { accountId: a.id, username: displayName(a) }, "secret_rotated");
         return secret;
     }
@@ -418,6 +401,46 @@ export class OAuthProvider {
             throw new UnsafeUrlError("This service is not open to that host yet.");
         return u;
     }
+    /** Wait for plugin installs that are still running (tests and graceful shutdown). */
+    async drainBackground() {
+        await Promise.allSettled([...this.background]);
+    }
+    /**
+     * Install the Papercliped plugin into the user's Paperclip after they approved the sign-in and ticked the box.
+     * Runs after the page has been answered: npm can take a while on their side, and the connection must not wait for it
+     * or fail because of it. The outcome is recorded as a "plugin" event and never carries anything but a short word.
+     */
+    installPluginLater(p, token) {
+        const instanceUrl = p.instanceUrl;
+        if (!instanceUrl)
+            return;
+        const accountId = p.accountId ?? null;
+        const run = (async () => {
+            let outcome = "failed";
+            try {
+                const login = this.pluginLoginFor(instanceUrl);
+                const now = await login.pluginState(token, PLUGIN_KEY);
+                if (now.state === "unsupported")
+                    outcome = "unsupported";
+                else if (now.state === "installed")
+                    outcome = "already";
+                else
+                    outcome = await login.installPlugin(token, PLUGIN_PACKAGE, VERSION);
+            }
+            catch {
+                outcome = "failed";
+            }
+            await this.event("plugin", await this.who(accountId), outcome);
+        })();
+        const tracked = run.finally(() => this.background.delete(tracked));
+        this.background.add(tracked);
+    }
+    pluginLoginFor(instanceUrl) {
+        if (this.deps.loginFor)
+            return this.deps.loginFor(instanceUrl);
+        const origin = this.checkedInstance(instanceUrl).origin; // re-validated: policy can tighten between steps
+        return new PaperclipLogin({ apiUrl: `${origin}/api`, publicOrigin: origin, fetch: this.installFetch, timeoutMs: PLUGIN_INSTALL_MS });
+    }
     loginFor(instanceUrl) {
         if (this.deps.loginFor)
             return this.deps.loginFor(instanceUrl);
@@ -520,7 +543,7 @@ export class OAuthProvider {
             "X-Frame-Options": "DENY",
             "X-Content-Type-Options": "nosniff",
             "Referrer-Policy": "no-referrer",
-            "Content-Security-Policy": `default-src 'none'; img-src data:; style-src 'unsafe-inline'; ${nonce ? `script-src 'nonce-${nonce}'; connect-src 'self'; ` : ""}form-action 'self'${formOrigin ? ` ${formOrigin}` : ""}; frame-ancestors 'none'; base-uri 'none'`,
+            "Content-Security-Policy": `default-src 'none'; img-src data:; style-src 'unsafe-inline'; font-src 'self'; ${nonce ? `script-src 'nonce-${nonce}'; connect-src 'self'; ` : ""}form-action 'self'${formOrigin ? ` ${formOrigin}` : ""}; frame-ancestors 'none'; base-uri 'none'`,
         });
         res.end(body);
         return true;
@@ -640,7 +663,7 @@ export class OAuthProvider {
             return this.html(res, 429, errorPage("Too many requests", "Please wait a minute and try again."));
         if ((await this.store.countPending()) >= MAX_PENDING)
             return this.html(res, 503, errorPage("Busy", "Too many sign-ins in progress. Try again shortly."));
-        const asked = (q.get("scope") ?? "").split(/\s+/).filter(isScope);
+        const asked = (q.get("scope") ?? "").split(/\s+/).map(normalizeScope).filter(isScope);
         const requestedMax = asked.length ? levelOf(asked) : "paperclip:read";
         const rid = randomToken(24);
         const p = { clientId: client.id, clientName: client.name, redirectUri, state, codeChallenge: challenge, requestedMax, csrf: randomToken(24), attempts: 0, expiresAt: this.now() + PENDING_TTL_MS };
@@ -676,7 +699,7 @@ export class OAuthProvider {
             clientName: p.clientName,
             redirectHost: u.host,
             loopbackOnly: u.protocol === "http:" && LOOPBACK.has(u.hostname),
-            requestedMax: p.requestedMax,
+            requestedMax: normalizeScope(p.requestedMax),
             login: this.deps.oauth.login,
             approvalUrl: ch?.approvalUrl,
             approved,
@@ -716,7 +739,7 @@ export class OAuthProvider {
             await this.event("connect_failed", null, "denied");
             return this.redirectWith(res, p.redirectUri, { error: "access_denied", error_description: "The user denied the request", state: p.state });
         }
-        const allowed = scopesUpTo(p.requestedMax);
+        const allowed = grantableScopes();
         const level = (f.get("level") ?? "");
         if (!allowed.includes(level))
             return this.renderConsent(res, rid, p, false, "Choose an access level.");
@@ -782,7 +805,7 @@ export class OAuthProvider {
         const c = this.ctx(rid, p, error);
         switch (p.stage) {
             case "instance":
-                return this.page(res, status, instancePage({ ...c, value: extra.value, notice: extra.notice }), p);
+                return this.page(res, status, instancePage({ ...c, value: extra.value, notice: extra.notice, installPlugin: p.installPlugin }), p);
             case "approve": {
                 const ch = this.unsealChallenge(p);
                 if (!ch || !p.instanceUrl) {
@@ -805,7 +828,7 @@ export class OAuthProvider {
                 const link = p.accountId ? await this.store.getLink(p.accountId) : undefined;
                 const u = new URL(p.redirectUri);
                 const acct = p.accountId ? await this.store.getAccount(p.accountId) : undefined;
-                return this.page(res, status, scopePage({ ...c, requestedMax: p.requestedMax, loopbackOnly: u.protocol === "http:" && LOOPBACK.has(u.hostname), instanceHost: link ? new URL(link.instanceUrl).host : "your Paperclip", username: p.username ?? "", anonymous: !!acct?.anonymous, alias: acct?.alias ?? null, beta: !!acct?.beta }), p);
+                return this.page(res, status, scopePage({ ...c, requestedMax: normalizeScope(p.requestedMax), loopbackOnly: u.protocol === "http:" && LOOPBACK.has(u.hostname), instanceHost: link ? new URL(link.instanceUrl).host : "your Paperclip", username: p.username ?? "", anonymous: !!acct?.anonymous, alias: acct?.alias ?? null }), p);
             }
             default:
                 return this.page(res, status, choosePage(c), p);
@@ -941,6 +964,7 @@ export class OAuthProvider {
             return this.html(res, 429, errorPage("Too many attempts", "Too many addresses tried. Start again from the app."));
         }
         p.attempts += 1;
+        p.installPlugin = f.get("install_plugin") === "on";
         const typed = (f.get("instance") ?? "").slice(0, 300);
         const fail = async (why, detail) => {
             await this.store.putPending(rid, p);
@@ -1007,6 +1031,8 @@ export class OAuthProvider {
         }
         if (!userId)
             return this.renderStage(res, rid, p, "Paperclip did not say who you are, so we can't link a username to it.");
+        if (p.installPlugin)
+            this.installPluginLater(p, ch.boardApiToken);
         const owner = await this.store.getLinkByIdentity(p.instanceUrl, userId);
         if (p.accountId) {
             // Reconnecting an account the user already signed in to with their secret key.
@@ -1140,7 +1166,7 @@ export class OAuthProvider {
         if (!s)
             return true;
         const { f, p, rid } = s;
-        const allowed = grantableScopes(p.requestedMax);
+        const allowed = grantableScopes();
         const level = (f.get("level") ?? "");
         if (!allowed.includes(level))
             return this.renderStage(res, rid, p, "Choose an access level.");
@@ -1156,13 +1182,6 @@ export class OAuthProvider {
             if (want !== !!acct.anonymous)
                 acct = await this.setPrivacy(acct, want);
         }
-        if (f.get("beta_present") === "1") {
-            const want = f.get("beta") === "on";
-            if (want !== !!acct.beta) {
-                await this.manageSetBeta(acct, want);
-                acct = { ...acct, beta: want };
-            }
-        }
         const code = `pcb_ac_${randomToken(32)}`;
         await this.store.putCode(sha256Hex(code), {
             clientId: p.clientId,
@@ -1174,7 +1193,7 @@ export class OAuthProvider {
             instanceUrl: link.instanceUrl,
             sealedCredential: null, // the credential stays on the account link
             accountId: p.accountId,
-            username: displayName(acct), // grants carry the DISPLAY name: that is what audit rows and the panel see
+            username: displayName(acct), // grants carry the DISPLAY name: that is what audit rows and the operator dashboard see
             path: p.path ?? "connect",
             expiresAt: this.now() + CODE_TTL_MS,
         });
@@ -1246,7 +1265,7 @@ export class OAuthProvider {
         }
         if (f.get("client_id") !== grant.clientId)
             throw new OAuthError("invalid_grant", "client_id mismatch");
-        const asked = (f.get("scope") ?? "").split(/\s+/).filter(Boolean);
+        const asked = (f.get("scope") ?? "").split(/\s+/).filter(Boolean).map(normalizeScope);
         if (asked.some((s) => !isScope(s) || !scopeAllows(grant.scopes, s)))
             throw new OAuthError("invalid_scope", "Requested scope exceeds the original grant");
         return this.issue(grant);
@@ -1257,7 +1276,7 @@ export class OAuthProvider {
         const refresh = `pcb_rt_${randomToken(32)}`;
         await this.store.putAccess(sha256Hex(access), { grantId: grant.id, expiresAt: t + this.deps.oauth.accessTtlSec * 1000 });
         await this.store.putRefresh(sha256Hex(refresh), { grantId: grant.id, expiresAt: t + this.deps.oauth.refreshTtlSec * 1000 });
-        return { access_token: access, token_type: "Bearer", expires_in: this.deps.oauth.accessTtlSec, refresh_token: refresh, scope: grant.scopes.join(" ") };
+        return { access_token: access, token_type: "Bearer", expires_in: this.deps.oauth.accessTtlSec, refresh_token: refresh, scope: normalizeScopes(grant.scopes).join(" ") };
     }
     // ───────────── POST /revoke (RFC 7009) ─────────────
     async revoke(req, res) {

package/dist/oauth/scopes.js

@@ -1,24 +1,27 @@
-export const SCOPES = ["paperclip:read", "paperclip:control", "paperclip:admin"];
-const RANK = { "paperclip:read": 1, "paperclip:control": 2, "paperclip:admin": 3 };
-/** Tools that are `write` by access class but too consequential for the control tier. */
-const ADMIN_TOOLS = new Set(["paperclip_decide_approval", "paperclip_set_agent_budget"]);
+/**
+ * Two levels: Read only and Full control. Full control is every tool, because the point of Papercliped is to run your
+ * Paperclip from anywhere, not just to watch it.
+ */
+export const SCOPES = ["paperclip:read", "paperclip:control"];
+/** A retired third level. Old grants and apps that still ask for it get Full control. */
+export const LEGACY_ADMIN = "paperclip:admin";
+const RANK = { "paperclip:read": 1, "paperclip:control": 2 };
 export const isScope = (s) => SCOPES.includes(s);
-/** read < control < admin; each level includes the ones below. */
+export const normalizeScope = (s) => (s === LEGACY_ADMIN ? "paperclip:control" : s);
+/** Known scopes only, retired names mapped, no duplicates. */
+export const normalizeScopes = (list) => [...new Set(list.map(normalizeScope).filter(isScope))];
+/** read < control; control includes read. */
 export function maxRank(granted) {
-    return Math.max(0, ...granted.filter(isScope).map((s) => RANK[s]));
+    return Math.max(0, ...normalizeScopes(granted).map((s) => RANK[s]));
 }
+/** Reads (and raw GETs) need Read only; anything that changes something needs Full control. */
 export function requiredScope(tool, input = {}) {
     if (tool.name === "paperclip_api_request")
-        return input.method === "GET" ? "paperclip:read" : "paperclip:admin";
-    if (tool.access === "destructive" || ADMIN_TOOLS.has(tool.name))
-        return "paperclip:admin";
-    return tool.access === "write" ? "paperclip:control" : "paperclip:read";
+        return input.method === "GET" ? "paperclip:read" : "paperclip:control";
+    return tool.access === "read" ? "paperclip:read" : "paperclip:control";
 }
 export const scopeAllows = (granted, needed) => maxRank(granted) >= RANK[needed];
-/** Highest-level scope name for a rank, e.g. 2 → paperclip:control. */
+/** The scope list for a level, e.g. control → [read, control]. */
 export const scopesUpTo = (level) => SCOPES.filter((s) => RANK[s] <= RANK[level]);
-/**
- * Levels the person may choose in the account flow. Control ("Full control (beta)") is always on offer, because the person
- * is the one granting it; Admin is only offered when the app itself asked for it.
- */
-export const grantableScopes = (requestedMax) => scopesUpTo(RANK[requestedMax] >= RANK["paperclip:control"] ? requestedMax : "paperclip:control");
+/** Levels the person may choose: always both, because the person is the one granting it. */
+export const grantableScopes = (_requestedMax) => [...SCOPES];

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) } },
+            },
+        },
+    };
+}