papercliped 0.0.0-stage → 1.1.0-beta.2

package/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "papercliped",
+  "owner": { "name": "KpnWorld" },
+  "plugins": [
+    {
+      "name": "papercliped",
+      "source": "./",
+      "description": "Control Paperclip agents, sync with them, and pull reports from Claude."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "papercliped",
+  "version": "1.0.0-beta.1",
+  "description": "Control Paperclip agents, sync with them, and pull reports from Claude.",
+  "author": { "name": "KpnWorld" },
+  "license": "MIT",
+  "keywords": ["paperclip", "agents", "orchestration", "mcp"]
+}

package/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "paperclip": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/stdio.js"],
+      "env": {
+        "PAPERCLIP_API_URL": "${PAPERCLIP_API_URL:-http://localhost:3100}",
+        "PAPERCLIP_API_KEY": "${PAPERCLIP_API_KEY:-}",
+        "PAPERCLIP_COMPANY_ID": "${PAPERCLIP_COMPANY_ID:-}",
+        "PAPERCLIP_READ_ONLY": "${PAPERCLIP_READ_ONLY:-}"
+      }
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## v1.1.0-beta.2 — connection manager, public site
+
+- **Beta connection manager** at `/manage` and a management API (`/api/manage/*`): sign in with username + secret key, see every connected app, switch it between Read only and Full control (beta) with immediate effect, disconnect it, toggle anonymity, make a new secret key, disconnect your Paperclip, delete your account. Sensitive actions re-ask for the secret key; Admin is never grantable from here. Opt in with **Join the beta** on the permission screen (migration `005_beta.sql`, applied automatically).
+- **Full control (beta)** is offered to everyone on the permission screen; Admin only when the app asks for it.
+- **Public site** served by the bridge: an interactive landing page ("Papercliped, not Paperclipped."), live user count, docs (getting started, create your account, permissions, anonymous mode, manage connections, security, ChatGPT, troubleshooting), privacy and terms. A new smiling-paperclip favicon on every page.
+- Windows-friendly test suite; `npm publish` only builds.
+- Set `SITE_CONTACT` (an email or support URL) so the privacy and terms pages show a real contact.
+
+Not in this release: a native Paperclip plugin that embeds the manager inside Paperclip (it needs the Paperclip plugin SDK).
+
+## v1.0.0-beta.1 — first public beta
+
+Papercliped connects Claude and ChatGPT to your own Paperclip: control agents, sync state, pull reports.
+
+- **MCP server** (stdio + Streamable HTTP) and **ChatGPT Actions** (generated OpenAPI) over Paperclip's REST API.
+- **Hosted multi-tenant bridge** with its own OAuth 2.1 server (DCR, PKCE, rotating refresh tokens, scopes read/control/admin).
+- **Papercliped accounts**: choose a unique username (6–32 chars, at least one number or `. # _`) and get a secret key. Sign in with the key, or reconnect by approving in your Paperclip — you keep your account and a live connection.
+- **Anonymous mode**: show as an alias (e.g. `Ann02`) in logs and the operator panel.
+- **SSRF-hardened egress** for user-supplied Paperclip URLs; sealed (AES-256-GCM) stored credentials with key rotation.
+- **Operator panel — a separate program** (`papercliped-panel`) reading a read-only database role: latency, system faults, success rate, user count, and the community log (`09:25:30 og.kpnwrld - joined cliped`).
+- Free-tier friendly: keep-alive worker, database heartbeat, auto-migrate; one-paste Supabase schema (`docs/supabase-schema.sql`).
+
+Known limits: not yet validated against live Render / Supabase / claude.ai / ChatGPT; code has not had an independent security audit. See `docs/SECURITY.md`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KpnWorld
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# papercliped — Claude & ChatGPT plugin for Paperclip
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Drive a [Paperclip](https://github.com/paperclipai/paperclip) instance (AI-agent company orchestrator) from Claude or ChatGPT through Paperclip's REST API.
+
+| Goal | How |
+| --- | --- |
+| Control Paperclip and agents | pause / resume / wake / clear-error / terminate agents, set budgets, create & assign issues, manage goals, decide approvals |
+| Sync with agents | `paperclip_sync_snapshot` (state now), `paperclip_sync_changes` (cursor-based "what changed"), `paperclip_wait_for_agent` (follow a run to completion) |
+| Reports | status, costs, agent performance, activity digest — markdown for people plus structured data |
+| Use the API | every tool is a thin call to Paperclip's `/api`; `paperclip_api_request` reaches anything without a dedicated tool |
+
+One tool catalogue (`src/tools.ts`, 29 tools) feeds three surfaces, so they cannot drift:
+
+```
+Claude Code / Claude Desktop ──stdio──▶ ┐
+Any MCP client ──Streamable HTTP /mcp─▶ ├─ tools ─▶ Paperclip /api
+ChatGPT Custom GPT ──/actions/* + /openapi.json─▶ ┘
+```
+
+> Paperclip already ships `@paperclipai/mcp-server` for issues/goals/approvals *from inside an agent run*. This bridge is the **operator-side** complement: agent lifecycle control, dashboard/cost/activity reports, sync, and an HTTP transport. They can be installed side by side.
+
+## Install
+
+```sh
+git clone https://github.com/OpenSourcx/papercliped && cd papercliped
+npm install        # also builds (prepare script)
+npm test
+```
+
+### Credentials (read this first)
+
+Pause/resume/wake/approve are **board-only** in Paperclip, so an agent API key will get `403`s. Use a **board API token**:
+
+```sh
+paperclipai auth login      # then copy the board token, or use your instance's token flow
+export PAPERCLIP_API_URL=http://localhost:3100
+export PAPERCLIP_API_KEY=<board token>      # not needed in local_trusted mode
+export PAPERCLIP_COMPANY_ID=<optional default company>
+export PAPERCLIP_READ_ONLY=1                # optional: reports + sync only, no writes
+```
+
+## Claude Code (plugin)
+
+```
+/plugin marketplace add OpenSourcx/papercliped
+/plugin install paperclip@papercliped
+```
+
+You get the MCP tools, a `paperclip` skill (sync-first workflow + confirm-before-destructive rules) and `/paperclip-status`, `/paperclip-sync`, `/paperclip-report`.
+The env vars above are read from your shell. Or without the plugin: `claude mcp add paperclip -- node /path/to/papercliped/dist/stdio.js`.
+
+## Claude Desktop
+
+```json
+{ "mcpServers": { "paperclip": {
+  "command": "node", "args": ["/path/to/papercliped/dist/stdio.js"],
+  "env": { "PAPERCLIP_API_URL": "http://localhost:3100", "PAPERCLIP_API_KEY": "…" } } } }
+```
+
+## ChatGPT (Custom GPT Actions)
+
+Run the HTTP bridge somewhere ChatGPT can reach over HTTPS, then import its OpenAPI. Step-by-step: [docs/chatgpt.md](docs/chatgpt.md).
+
+```sh
+export BRIDGE_TOKEN=$(openssl rand -hex 32)     # required; the bridge refuses to start without it
+export BRIDGE_PUBLIC_URL=https://bridge.example.com
+npm run start:http                               # 127.0.0.1:3939 — put TLS in front (Caddy, Cloudflare Tunnel, …)
+```
+
+Endpoints (all but `/healthz`, `/openapi.json` and the OAuth endpoints need `Authorization: Bearer <BRIDGE_TOKEN or OAuth access token>`): `POST /mcp` (MCP Streamable HTTP, stateless), `POST /actions/{tool}` (JSON in/out), `GET /openapi.json`. With `BRIDGE_OAUTH=1`: `/.well-known/oauth-*`, `/register`, `/authorize`, `/token`, `/revoke`.
+
+### Three ways to run it
+
+| Mode | For | Auth | State |
+| --- | --- | --- | --- |
+| **stdio** (`node dist/stdio.js`) | you, on your machine (Claude Code/Desktop) | your env vars | none |
+| **HTTP + `BRIDGE_TOKEN`** | ChatGPT Actions, Claude Code headers, one instance | static bearer | none |
+| **HTTP + OAuth, `BRIDGE_MODE=single`** | a team fronting *their one* Paperclip | OAuth 2.1, scoped | JSON file or Postgres |
+| **HTTP + OAuth, `BRIDGE_MODE=multi`** | **a public service**: every user connects their own (publicly reachable, https) Paperclip | OAuth 2.1, scoped | Postgres (required) |
+
+**Operator panel** (a separate program, `papercliped-panel`): latency, system faults, success rate, user count and a community log — see [docs/LAUNCH.md §7](docs/LAUNCH.md); preview with `npm run demo`. **Supabase schema:** paste [docs/supabase-schema.sql](docs/supabase-schema.sql) into the SQL editor. **Launch guide (Render free, domain, marketplaces, npm):** [docs/LAUNCH.md](docs/LAUNCH.md).
+
+Public hosting on Render + Supabase: **[docs/DEPLOY-RENDER.md](docs/DEPLOY-RENDER.md)** · threat model and residual risks: **[docs/SECURITY.md](docs/SECURITY.md)** · policy templates: [docs/legal/](docs/legal/).
+
+### Connect claude.ai / Claude Desktop / ChatGPT apps (OAuth)
+
+Set `BRIDGE_OAUTH=1`, `BRIDGE_PUBLIC_URL`, `BRIDGE_SECRET`, `BRIDGE_DATA_FILE` (see [.env.example](.env.example)), then add `https://<your bridge>/mcp` as a custom connector. Users sign in through Paperclip's own approval page and choose Read / Control / Admin. Full guide, scopes and security model: [docs/oauth.md](docs/oauth.md).
+
+## Safety model
+
+- OAuth connections get scoped tokens (read/control/admin), enforced in the bridge, with every call audit-logged. See [docs/oauth.md](docs/oauth.md).
+- `PAPERCLIP_READ_ONLY=1` blocks every mutating tool (and non-GET `paperclip_api_request`) before anything is sent to Paperclip.
+- `paperclip_terminate_agent` needs `confirm: true`; non-GET raw API calls need it too. Tools carry MCP `destructiveHint`/`readOnlyHint`, and OpenAPI `x-openai-isConsequential`, so clients prompt before consequential calls.
+- The HTTP bridge binds to loopback by default, uses constant-time token comparison, caps bodies at 1 MB, and times out upstream calls (30 s).
+- The bridge holds a powerful credential. Anyone with `BRIDGE_TOKEN` controls your agents; scope the Paperclip token and use read-only mode where you can.
+
+## Known limits — please read
+
+- **Tested against a mock of Paperclip's documented API, not a live instance.** Endpoint paths and fields were taken from Paperclip's docs and server source (`docs/api/*`, `server/src/routes/*`); report/sync code reads response fields defensively. Run it against your instance with `PAPERCLIP_READ_ONLY=1` first.
+- **claude.ai web / Desktop / mobile connectors and ChatGPT MCP apps** need OAuth: set `BRIDGE_OAUTH=1` (see [docs/oauth.md](docs/oauth.md)). OAuth scopes limit *what* a connection may do, not *which company* it may touch (Paperclip board keys are user-wide; verified in its source). Not yet implemented: CIMD, a grant-admin web UI (use `npm run admin`).
+- **A public bridge holds other people's Paperclip keys.** A bridge compromise exposes all of them until revoked. Read [docs/SECURITY.md](docs/SECURITY.md) before opening it up. The code is unaudited and the Render/Supabase/claude.ai/ChatGPT specifics are untested against the live services.
+- **Hosted mode only reaches Paperclips on the public internet over https.** `localhost`/private-network instances use the local stdio plugin.
+- `paperclip_sync_changes` polls the activity log (no push). Activity has no server-side `since` filter, so it fetches up to `limit` recent entries and filters locally; raise `limit` if you poll infrequently on a busy company.
+- ChatGPT Actions allow ~30 operations per GPT; the catalogue is at 29. Adding tools means removing some for that surface.
+
+## Layout
+
+```
+src/tools.ts      tool catalogue (schemas + Paperclip calls)     src/reports.ts  report builders
+src/execute.ts    validation, read-only enforcement, errors      src/openapi.ts  OpenAPI from the catalogue
+src/mcp.ts        MCP server    src/stdio.ts   src/server.ts + http.ts  HTTP bridge
+src/oauth/        OAuth 2.1 server: provider, stores (memory/JSON + Postgres), crypto/key ring, scopes, consent pages, Paperclip login adapter
+src/telemetry/    audit events, batching recorder, system sampler, timing   src/panel/  separate operator panel (routes, page, config, server)
+src/net/          SSRF-safe fetch + instance URL validation (multi-tenant egress guard)
+migrations/       Postgres schema (dedicated `bridge` schema, RLS)   Dockerfile   container image (Render free web service)   src/cli.ts  admin CLI
+.claude-plugin/ .mcp.json skills/ commands/    Claude Code plugin
+test/             end-to-end tests against a mock Paperclip
+```
+
+## Privacy
+
+Local modes: no telemetry and no backend; the bridge sends requests only to the Paperclip instance you configure and returns responses to the AI client that called it. Your credential lives in environment variables on your machine. Hosted mode (OAuth) additionally stores, per connection, an encrypted Paperclip key, hashed tokens and an audit log — see [docs/legal/PRIVACY.md](docs/legal/PRIVACY.md) (template) and [docs/SECURITY.md](docs/SECURITY.md). Data you expose to Claude or ChatGPT is then subject to that provider's own terms and privacy policy. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the security model and distribution plan.

package/commands/paperclip-report.md

@@ -0,0 +1,5 @@
+---
+description: Produce a Paperclip report — status, costs, performance or activity
+argument-hint: "[status|costs|performance|activity]"
+---
+Produce the report named in "$ARGUMENTS" (default `status`): `status` → `paperclip_report_status`, `costs` → `paperclip_report_costs`, `performance` → `paperclip_report_agent_performance`, `activity` → `paperclip_report_activity` (since the start of today, UTC). Present the markdown, then add 2–3 sentences of analysis: what looks off and what you would do about it.

package/commands/paperclip-status.md

@@ -0,0 +1,4 @@
+---
+description: Show a Paperclip status report (agents, tasks, spend, approvals)
+---
+Call `paperclip_report_status` and present the result. Then list any agents in error or paused and any pending approvals, and suggest next steps — but do not take any action without asking.

package/commands/paperclip-sync.md

@@ -0,0 +1,5 @@
+---
+description: Sync with Paperclip agents — current state plus what changed since last sync
+argument-hint: "[cursor from previous sync]"
+---
+Call `paperclip_sync_snapshot`. If a cursor was given ($ARGUMENTS), also call `paperclip_sync_changes` with it. Summarise what each agent is doing, what changed, and end with the new cursor so the next sync can continue from it.

package/dist/accounts/alias.js

@@ -0,0 +1,28 @@
+import { randomInt } from "node:crypto";
+import { createHmac } from "node:crypto";
+/**
+ * Anonymous display names: a short first name + two digits ("Ann02", "Kai47").
+ *
+ * They are deliberately SHORTER than the minimum username length (6), so an alias can never be a valid username and the two
+ * can't be confused in a log line. Names are 2–3 letters; with ~120 names × 100 numbers there are ~12,000 aliases.
+ */
+const NAMES = [
+    "Abe", "Ace", "Ada", "Al", "Ali", "Amy", "Ann", "Art", "Ava", "Bea", "Ben", "Bo", "Bud", "Cal", "Cat", "Cy", "Dan", "Dee", "Di", "Don",
+    "Eda", "Ed", "Eli", "Eva", "Eve", "Fay", "Flo", "Fox", "Gia", "Gil", "Gus", "Hal", "Hui", "Ian", "Ida", "Ira", "Ivy", "Jan", "Jay", "Jo",
+    "Joy", "Kai", "Kim", "Kit", "Lea", "Lee", "Leo", "Lin", "Liv", "Lou", "Lu", "Max", "May", "Mei", "Mia", "Moe", "Nat", "Ned", "Nia", "Noa",
+    "Oli", "Ola", "Ona", "Ora", "Pam", "Pat", "Pip", "Raj", "Ray", "Rex", "Rio", "Rob", "Roy", "Rue", "Sal", "Sam", "Sia", "Sol", "Sue", "Taj",
+    "Tia", "Tim", "Tom", "Tye", "Uma", "Una", "Val", "Van", "Vic", "Vin", "Wes", "Wil", "Xia", "Xan", "Yan", "Yen", "Zac", "Zed", "Zoe", "Zia",
+    "Bay", "Cai", "Dev", "Eli", "Gwen".slice(0, 3), "Hoa", "Isa", "Jin", "Kay", "Lex", "Mac", "Nox", "Ozu", "Pru", "Quo", "Rae", "Sky", "Teo", "Uri", "Vee",
+];
+const POOL = [...new Set(NAMES)];
+/** Shape of every alias; usernames (≥6 chars) can never match this. */
+export const ALIAS_RE = /^[A-Z][a-z]{1,2}\d{2}$/;
+export const generateAlias = (rand = (n) => randomInt(n)) => `${POOL[rand(POOL.length)]}${String(rand(100)).padStart(2, "0")}`;
+export const isAlias = (s) => !!s && ALIAS_RE.test(s);
+/** The name that appears in logs, the panel and audit rows. */
+export const displayName = (a) => (a.anonymous && a.alias ? a.alias : a.username);
+/**
+ * A stable label standing in for a tenant's Paperclip hostname when its owner is anonymous ("anon-3f9a1c"). It keeps one tenant's
+ * activity grouped (so slow-instance debugging still works) without putting the hostname in logs. Keyed so it can't be reversed by guessing hosts.
+ */
+export const anonInstanceLabel = (key, accountId) => `anon-${createHmac("sha256", key).update(`instance|${accountId}`).digest("hex").slice(0, 6)}`;

package/dist/accounts/secret.js

@@ -0,0 +1,65 @@
+import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+/**
+ * The account "secret key": generated by us (never user-chosen, so no weak or reused passwords), 160 bits, shown once.
+ * Looks like  pcs_ABCD-EFGH-JKMN-PQRS-TVWX-YZ23-4567-89AB  (Crockford base32: no I, L, O, U).
+ * Only a salted scrypt hash is stored.
+ */
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const SECRET_CHARS = 32;
+function base32(buf) {
+    let bits = 0;
+    let value = 0;
+    let out = "";
+    for (const byte of buf) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    return out;
+}
+export function generateSecretKey() {
+    const raw = base32(randomBytes(20)); // 20 bytes = 160 bits = exactly 32 base32 chars
+    return `pcs_${raw.match(/.{4}/g).join("-")}`;
+}
+/** Forgiving about what people type: case, dashes, spaces, the pcs_ prefix, and Crockford look-alikes (O→0, I/L→1). Null if malformed. */
+export function normalizeSecretKey(input) {
+    if (typeof input !== "string")
+        return null;
+    let s = input.trim().toUpperCase().replace(/^PCS[_-]?/, "").replace(/[\s-]/g, "");
+    s = s.replace(/O/g, "0").replace(/[IL]/g, "1");
+    return s.length === SECRET_CHARS && [...s].every((c) => ALPHABET.includes(c)) ? s : null;
+}
+const N = 16384; // 16 MiB: affordable on a small free instance, and the key has 160 bits of entropy anyway
+const R = 8;
+const P = 1;
+const KEYLEN = 32;
+const scryptAsync = (secret, salt, n = N, r = R, p = P) => new Promise((resolve, reject) => scrypt(secret, salt, KEYLEN, { N: n, r, p, maxmem: 64 * 1024 * 1024 }, (e, k) => (e ? reject(e) : resolve(k))));
+/** Hashes a (normalized) secret key. Runs on the libuv threadpool, so it doesn't block the event loop. */
+export async function hashSecretKey(normalized) {
+    const salt = randomBytes(16);
+    const hash = await scryptAsync(normalized, salt);
+    return `scrypt$${N}$${R}$${P}$${salt.toString("base64")}$${hash.toString("base64")}`;
+}
+export async function verifySecretKey(input, stored) {
+    const normalized = normalizeSecretKey(input);
+    const parts = stored.split("$");
+    if (parts.length !== 6 || parts[0] !== "scrypt")
+        return false;
+    const [n, r, p] = [Number(parts[1]), Number(parts[2]), Number(parts[3])];
+    if (![n, r, p].every(Number.isInteger))
+        return false;
+    // Always do the work, even for a malformed guess, so timing doesn't reveal which check failed.
+    const expected = Buffer.from(parts[5], "base64");
+    const got = await scryptAsync(normalized ?? "invalid", Buffer.from(parts[4], "base64"), n, r, p);
+    return normalized !== null && got.length === expected.length && timingSafeEqual(got, expected);
+}
+let dummy;
+/** Verify against a throwaway hash when the username doesn't exist, so "unknown user" costs the same as "wrong key". */
+export async function burnVerify(input) {
+    dummy ??= hashSecretKey("0".repeat(SECRET_CHARS));
+    await verifySecretKey(input, await dummy);
+}
+export const maskSecretKey = (s) => `${s.slice(0, 8)}…`;

package/dist/accounts/types.js

@@ -0,0 +1,2 @@
+export class AliasTakenError extends Error {
+}

package/dist/accounts/username.js

@@ -0,0 +1,38 @@
+/**
+ * Papercliped usernames.
+ *
+ * Rules (from the product spec):
+ *  - unique, compared case-insensitively ("OG.kpnwrld" and "og.kpnwrld" are the same name)
+ *  - at least 6 characters (assumption: the spec says "up to 6" but its own example `og.kpnwrld` is 10 — see USERNAME_MIN)
+ *  - must contain at least one number or symbol
+ *  - the only allowed symbols are  .  #  _   (letters and digits otherwise; ASCII only, so no look-alike characters)
+ * Extra, to keep names usable in logs: at most 32 characters, must start with a letter or digit, and a few
+ * impersonation-prone names are reserved.
+ */
+export const USERNAME_MIN = 6;
+export const USERNAME_MAX = 32;
+export const USERNAME_SYMBOLS = [".", "#", "_"];
+const ALLOWED = /^[A-Za-z0-9._#]+$/;
+const STARTS_OK = /^[A-Za-z0-9]/;
+const HAS_NUMBER_OR_SYMBOL = /[0-9._#]/;
+/** Compared against the letters-only form of a name, so "admin.1" and "root_9" are caught too. */
+const RESERVED = new Set(["admin", "administrator", "root", "system", "support", "staff", "official", "moderator", "papercliped", "paperclip", "cliped", "kpnworld", "kpnsolute", "anthropic", "claude", "openai", "chatgpt"]);
+export const usernameKey = (username) => username.toLowerCase();
+export function validateUsername(raw) {
+    if (typeof raw !== "string")
+        return { ok: false, reason: "Choose a username." };
+    const u = raw.trim();
+    if (u.length < USERNAME_MIN)
+        return { ok: false, reason: `Usernames need at least ${USERNAME_MIN} characters.` };
+    if (u.length > USERNAME_MAX)
+        return { ok: false, reason: `Usernames can be at most ${USERNAME_MAX} characters.` };
+    if (!ALLOWED.test(u))
+        return { ok: false, reason: "Use only letters, numbers and these symbols: . # _" };
+    if (!STARTS_OK.test(u))
+        return { ok: false, reason: "Start your username with a letter or number." };
+    if (!HAS_NUMBER_OR_SYMBOL.test(u))
+        return { ok: false, reason: "Include at least one number or one of these symbols: . # _" };
+    if (RESERVED.has(u.toLowerCase().replace(/[^a-z]/g, "")))
+        return { ok: false, reason: "That name is reserved. Please pick another." };
+    return { ok: true, username: u, key: usernameKey(u) };
+}

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { readConfig, readDatabase, readHttpConfig } from "./config.js";
+import { consolidatedSql, migrate } from "./migrate.js";
+import { OAuthProvider } from "./oauth/provider.js";
+import { createStore } from "./store-factory.js";
+const USAGE = `paperclip-bridge-admin <command>
+
+  schema-sql     print ONE paste-able SQL script (all migrations) for the Supabase SQL editor
+  migrate        apply database migrations (uses DATABASE_MIGRATE_URL if set, else DATABASE_URL; needs a direct/session connection)
+  users          list accounts: real username, alias (if anonymous), when last signed in (OPERATOR ONLY: this un-masks aliases)
+  delete-user <username>  delete an account, its stored credential and grants (asks that Paperclip to revoke the key)
+  grants         list live grants (no secrets are shown)
+  revoke <id>    revoke one grant and delete its stored credential
+  sweep          revoke grants idle longer than BRIDGE_IDLE_REVOKE_DAYS
+  revoke-all --yes  incident response: revoke EVERY grant, delete all stored credentials, ask each tenant's Paperclip to revoke its key
+  rotate-keys    re-seal stored credentials with the current BRIDGE_SECRET (put the old one in BRIDGE_SECRET_PREVIOUS first)
+`;
+async function main() {
+    const [cmd, arg] = process.argv.slice(2);
+    if (cmd === "schema-sql") {
+        process.stdout.write(consolidatedSql());
+        return;
+    }
+    if (cmd === "migrate") {
+        const url = process.env.DATABASE_MIGRATE_URL?.trim();
+        const db = readDatabase(url ? { ...process.env, DATABASE_URL: url } : process.env);
+        if (!db)
+            throw new Error("DATABASE_URL (or DATABASE_MIGRATE_URL) is not set");
+        const applied = await migrate(db);
+        console.log(applied.length ? `applied: ${applied.join(", ")}` : "database is up to date");
+        return;
+    }
+    if (!["users", "delete-user", "grants", "revoke", "revoke-all", "sweep", "rotate-keys"].includes(cmd ?? "")) {
+        console.error(USAGE);
+        process.exit(cmd ? 2 : 0);
+    }
+    const http = readHttpConfig();
+    if (!http.oauth)
+        throw new Error("BRIDGE_OAUTH=1 and its settings are required for this command");
+    const provider = new OAuthProvider({ config: readConfig(), oauth: http.oauth, bridgeToken: http.bridgeToken, store: createStore(http.oauth) });
+    try {
+        if (cmd === "users") {
+            for (const a of await provider.store.listAccounts(1000)) {
+                console.log([a.username, a.anonymous ? `anonymous as ${a.alias}` : "public", a.disabled ? "disabled" : "active", a.lastLoginAt ? `last login ${new Date(a.lastLoginAt).toISOString()}` : "never signed in"].join("\t"));
+            }
+        }
+        else if (cmd === "delete-user") {
+            if (!arg)
+                throw new Error("usage: delete-user <username>");
+            console.log((await provider.deleteUser(arg)) ? `deleted ${arg}` : `no such user: ${arg}`);
+        }
+        else if (cmd === "grants") {
+            for (const g of await provider.listGrants()) {
+                console.log([g.id, g.clientName, g.instanceUrl ?? "-", g.scopes.join(","), `last used ${new Date(g.lastUsedAt).toISOString()}`].join("\t"));
+            }
+        }
+        else if (cmd === "revoke") {
+            if (!arg)
+                throw new Error("usage: revoke <grant id>");
+            await provider.revokeGrant(arg);
+            console.log(`revoked ${arg}`);
+        }
+        else if (cmd === "revoke-all") {
+            if (arg !== "--yes")
+                throw new Error("this revokes every connection; re-run with --yes");
+            const live = await provider.listGrants();
+            for (const g of live)
+                await provider.revokeGrant(g.id);
+            console.log(`revoked ${live.length} grant(s)`);
+        }
+        else if (cmd === "sweep") {
+            console.log(`revoked ${await provider.sweep()} idle grant(s)`);
+        }
+        else if (cmd === "rotate-keys") {
+            console.log(`re-sealed ${await provider.rotateKeys()} credential(s)`);
+        }
+        // give best-effort upstream revocations a moment to leave
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    finally {
+        await provider.store.close();
+    }
+}
+main().catch((e) => {
+    console.error(`error: ${e.message}`);
+    process.exit(1);
+});

package/dist/client.js

@@ -0,0 +1,83 @@
+import { ToolInputError } from "./errors.js";
+import { trackUpstream } from "./telemetry/timing.js";
+export class PaperclipApiError extends Error {
+    status;
+    method;
+    path;
+    body;
+    constructor(status, method, path, body) {
+        const detail = body && typeof body === "object" && "error" in body && typeof body.error === "string"
+            ? `: ${body.error}`
+            : "";
+        super(`${method} ${path} failed with ${status}${detail}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.body = body;
+        this.name = "PaperclipApiError";
+    }
+}
+export class PaperclipClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    resolveCompanyId(explicit) {
+        const id = explicit?.trim() || this.config.companyId;
+        if (!id) {
+            throw new ToolInputError("companyId is required: pass it, or set PAPERCLIP_COMPANY_ID (use paperclip_list_companies to find one)");
+        }
+        return id;
+    }
+    async request(method, path, opts = {}) {
+        if (!path.startsWith("/"))
+            throw new ToolInputError(`API path must start with "/": ${path}`);
+        if (path.includes(".."))
+            throw new ToolInputError("API path must not contain '..'");
+        const url = new URL(`${this.config.apiUrl}${path}`);
+        for (const [k, v] of Object.entries(opts.query ?? {})) {
+            if (v !== undefined && v !== null && v !== "")
+                url.searchParams.set(k, String(v));
+        }
+        const headers = { Accept: "application/json" };
+        if (this.config.apiKey)
+            headers.Authorization = `Bearer ${this.config.apiKey}`;
+        if (opts.body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let res;
+        let text;
+        try {
+            // Time headers AND body transfer as "upstream": that is the wait the caller experiences.
+            ({ res, text } = await trackUpstream(async () => {
+                const r = await this.fetchImpl(url, {
+                    method,
+                    headers,
+                    body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+                    signal: AbortSignal.timeout(this.config.timeoutMs),
+                });
+                return { res: r, text: await r.text() };
+            }));
+        }
+        catch (err) {
+            const why = err instanceof Error ? err.cause?.message ?? err.message : String(err);
+            throw new Error(`Cannot reach Paperclip at ${this.config.apiUrl} (${why}). Check PAPERCLIP_API_URL and that the server is running.`);
+        }
+        let parsed = null;
+        if (text) {
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = text;
+            }
+        }
+        if (!res.ok)
+            throw new PaperclipApiError(res.status, method, path, parsed);
+        return parsed;
+    }
+    get = (path, query) => this.request("GET", path, { query });
+    post = (path, body) => this.request("POST", path, { body: body ?? {} });
+    patch = (path, body) => this.request("PATCH", path, { body });
+}