papercliped 0.0.0-stage → 2.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "papercliped",
+  "owner": {
+    "name": "KpnWorld"
+  },
+  "plugins": [
+    {
+      "name": "papercliped",
+      "source": "./",
+      "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose."
+    }
+  ],
+  "description": "Papercliped: run your Paperclip from Claude Code."
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "papercliped",
+  "version": "2.1.0",
+  "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose.",
+  "author": {
+    "name": "KpnWorld"
+  },
+  "license": "MIT",
+  "keywords": [
+    "paperclip",
+    "agents",
+    "orchestration",
+    "mcp"
+  ],
+  "homepage": "https://papercliped.co",
+  "repository": "https://github.com/OpenSourcx/papercliped"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "paperclip": {
+      "type": "http",
+      "url": "https://mcp.papercliped.co/mcp"
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+## Unreleased
+
+## v2.1.0 — two access levels, manage in Paperclip, new website
+
+- **Dependencies up to date:** Zod 4 (tool schemas and the ChatGPT Actions OpenAPI now come from Zod's built-in JSON Schema; the published contract is unchanged), the latest MCP SDK, undici 8, TypeScript 7, Vitest 5, React 19 and esbuild 0.28 in the plugin, and GitHub Actions v7. No known vulnerabilities in either package. Dependabot now also watches the website and groups minor and patch updates into one pull request per package.
+
+- **Install in one step from Claude Code and Codex.** Both plugin marketplaces live in this repository: `/plugin marketplace add OpenSourcx/papercliped` in Claude Code, `codex plugin marketplace add OpenSourcx/papercliped` in Codex. The plugin now connects to the hosted server (`https://mcp.papercliped.co/mcp`) instead of a local build that wasn't in the repository; people running Paperclip on their own machine use `npx papercliped@latest` (see the README).
+- **A README that gets you running:** what Papercliped is and copy-paste setup for Claude, Claude Code, Codex, ChatGPT, any MCP app and local Paperclips, without visiting the docs.
+- **Every push is a release.** CI publishes both npm packages, tags the commit and writes the GitHub release from the changelog and the commit descriptions. `scripts/version.mjs` bumps Major.Minor.Patch in every file, and a release skill for Claude and Codex (`.claude/skills/release`, `.agents/skills/release`) explains when to use which, and how to adopt the same flow in other repositories.
+- **Ready for contributors:** `SECURITY.md` (private reporting, response times), a contributor guide with the path from first PR to maintainer, `CLAUDE.md`/`AGENTS.md` for AI coding agents, and a complete Discord setup in `docs/COMMUNITY.md`.
+
+- **New website, phase 1 (foundation):** `web/`, a static React + Tailwind site with self-hosted fonts (Bricolage Grotesque, Inter, JetBrains Mono), the mascot as an animated component (eyes follow the pointer, blinks; still with reduced motion), a component kit and a `/kit` showcase page. **Seasonal themes:** the default `clip` theme plus two palettes per season, each with light and dark, rotating on a schedule that is the same for everyone on a given day; visitors can pick a theme and light/dark/system mode. Every theme passes WCAG AA contrast (tested), every route is checked in headless Chromium under the strict CSP, and nothing is loaded from third parties. Not yet served by the bridge (phase 4).
+- **New website, phase 2 (pages):** a full landing page (live user count, an interactive how-it-works stepper, a permission playground generated from the real tool list, the two plugins, security highlights, FAQ), a **changelog page** built from this file with New/Improved/Fixed filters and an Atom feed (`/changelog.xml`), a **community page** (a suggest-a-feature form that pre-fills a GitHub issue, bug reports, contributing; social links only appear once they exist), a **brand page** with mascot and wordmark downloads and usage rules, and privacy and terms rendered from the same Markdown as the bridge. Playful but accessible interactions (lifting buttons, tilting cards, a mascot that hops), checked for sideways scrolling on a 375px phone. Also: `CODE_OF_CONDUCT.md`, issue and pull request templates, `docs/COMMUNITY.md` (forum and Discord plan), sitemap, robots.txt and a social preview image.
+
+- **Public stats API** (no sign-in): `GET /api/public/v1/info`, `status`, `stats`, `series` and `errors` (plus `openapi.json`) publish aggregate users, live connections, sign-in success and failure reasons, request success rate, latency percentiles, error mix and load. Aggregate only: no usernames, aliases, ids, Paperclip addresses, app names or IPs, and no per-user breakdown (tested against memory and Postgres). GET-only, CORS-open without credentials, cached 30 s, 60 requests per minute per address. Types in `src/public-api/types.ts`. New docs page: **Public API and status**.
+- **Status page** on the new website (`/status`): live status badge, people, connections, request and sign-in success, latency percentiles, and charts for requests and errors, response time and sign-ins, plus error-mix, sign-in-failure and top-tool bars. Every chart has a text summary and a table view and never relies on colour alone; it refreshes every 30 seconds.
+- **Removed the operator panel from this repository** (`papercliped-panel`, `src/panel/`, the demo, `PANEL_*` settings, `docs/panel-role.sql`). The operator dashboard now lives in a separate, access-controlled service. Nothing changed in the database: the telemetry tables and the read-only `panel_*` views are still written and kept for it. `npm run build` now cleans `dist/` first.
+
+- **New website, phase 3 (docs):** a docs site at `/docs` with a three-column layout (collapsible sections with counts, the article with breadcrumb, last-updated date, copy link and edit-on-GitHub, and an "On this page" outline that follows your scroll), previous/next links, copy buttons on code, and **Ctrl/Cmd-K search** built at compile time (no outside service). The **GitHub star count** shows in the header: the bridge fetches it from GitHub and caches it for an hour (`GET /api/public/v1/repo`), so browsers never call GitHub directly.
+- **Much more documentation:** new pages What is Papercliped? (with a glossary), Run it yourself, Tool reference (generated from the code), Manage API, Environment variables, Command line, Limits and errors, and FAQ. Docs now have 20 pages in five sections; the bridge serves the same pages until the new site goes live.
+
+- **The bridge serves the new website** (from `web/dist`, built into the Docker image) with **host routing** (`PUBLIC_HOSTS`): `papercliped.co` for the site, `docs.papercliped.co/topics` for the docs, `mcp.`/`api.papercliped.co` for MCP, OAuth and the APIs, `forum.` redirects to the forum, `www` redirects to the apex. Old `/docs/...` links redirect to the docs host. Every host still answers the protocol and API paths. Unknown pages return a real 404. Without the built site (e.g. the npm package), the bridge serves its Markdown pages as before. Setup and the issuer decision: `docs/DOMAINS.md`.
+- **Sign-in, consent and manage pages restyled** with the website's fonts (Bricolage Grotesque, Inter, JetBrains Mono) and colours, including dark mode. Still plain server-rendered HTML.
+- **New tool `papercliped_service_status`** (read only): the AI can check whether the hosted service is working, from the public status API. The catalogue is now 30 tools.
+- **Paperclip plugin:** a "Papercliped service" card shows the bridge's public status (no link needed).
+
+- **AI apps now connect at `https://mcp.papercliped.co/mcp`** (the OAuth issuer moves to `mcp.papercliped.co`; the website, docs and `/manage` stay on `papercliped.co`). Docs show the connector address through a new `{{MCP}}` placeholder, so self-hosted bridges show their own. Anyone connected before must remove the connector and add the new address.
+
+- **Website redesign:** a bolder homepage (a centred headline, pill buttons, a gradient pill hero with the mascot in the middle; click it for a wave), a shorter header (Product, Docs, Resources, Community, search, GitHub stars, Get started). The docs get their own header (links left, "papercliped Docs" centred, search and stars right), a sidebar grouped into Learn, Reference and Project with icons, counts and collapsible sections, and a page header with breadcrumb, tag and a Copy link menu (view the Markdown source, suggest an edit). The changelog moves into the docs layout as expandable release cards.
+- **Light and dark now follow your device automatically.** The manual System/Light/Dark switch is gone (an old saved choice is cleared); the seasonal palettes still rotate on their own.
+
+- **Two access levels: Read only and Full control.** Full control is now every tool (pause, wake, terminate, issues, goals, comments, approvals, budgets and raw API writes), so you can run your Paperclip from anywhere. The separate "Admin" level is gone; existing admin grants and apps that still ask for it get Full control (migration `006_two_levels.sql` tidies stored grants). The sign-in page, the manage page, the Paperclip plugin, the docs and the website playground all show the two levels.
+
+- **Managing your account moved into Paperclip.** The Papercliped plugin is now the connection manager: link it with your username and secret key (checked once, not stored), then change levels, disconnect apps, switch anonymity, see and remove linked Paperclips, make a new secret key (this Paperclip stays linked), disconnect your Paperclip or delete your account. The `/manage` web page, its cookie sign-in, one-time link codes and the beta opt-in are gone (`/manage` now points to the plugin docs); the manage API accepts plugin tokens only.
+
+- **Docs live at `docs.papercliped.co/<page>`** (for example `docs.papercliped.co/permissions`), with a real docs landing at `docs.papercliped.co/`: search, the connector address, four start-here cards and every topic. Old `/topics/...` and `papercliped.co/docs/...` links redirect.
+
+- **A cleaner homepage hero:** instead of decorative art, a live demo of the product. An AI app on the left steers a Paperclip on the right (pause an agent, weekly report, approve a request), using the real tool names, with tabs to replay each one. The footer gets X, GitHub and Discord icons (X and Discord point to the community page until their addresses are set).
+
+- **The Papercliped page in Paperclip, rebuilt** with Paperclip's own components (status badges, metric cards, tables, toasts) so it looks native: a service panel, an account summary, and tabs for Connected apps (level dropdown, two-step disconnect), Privacy, Linked Paperclips and Account (new secret key shown once with copy, disconnect Paperclip, delete account). Covered by UI tests against the real plugin actions.
+
+## v2.0.0 — stable open-source build
+
+Papercliped v2 is the free, open-source foundation: the bridge, the connector for Claude and any MCP app, and the Paperclip plugin. Paid features (managed subdomains, pricing, legal) are planned for v3 (`docs/V3-SUBDOMAINS.md`).
+
+- **New home: `https://papercliped.co`.** Every reference to the old domain is gone. The Paperclip plugin's default bridge URL is now `https://papercliped.co`. Operators: set `BRIDGE_PUBLIC_URL=https://papercliped.co`; apps connected under the old address must connect again (the OAuth issuer changed). Cloudflare + Render setup: `docs/LAUNCH.md` §3.
+- **Two plugins, documented side by side:** Papercliped for AI apps (Claude, ChatGPT, any MCP client) and the Papercliped plugin for Paperclip. New docs page: **Any AI app (MCP)**.
+- **Automated npm publishing** through GitHub Actions with npm trusted publishing (OIDC, no token): one tag publishes `papercliped` and `papercliped-paperclip-plugin` and creates the GitHub release (`docs/RELEASING.md`). CI now also packs both packages and installs them as a user would, and a test keeps every version string in step.
+- **Foundation:** CodeQL, Dependabot, dependency audit and read-only permissions in CI; `CONTRIBUTING.md`; `docs/SITEMAP.md` (every page and endpoint); new docs page **Set up your Paperclip** (public address with or without a domain); the security doc covers plugin links.
+- Fixed: the Claude Code install command in the README (`/plugin install papercliped@papercliped`).
+
+Not tested live: the Paperclip plugin has never run inside a real Paperclip, and the release workflow has not run yet (it can only run on GitHub).
+
+## v1.2.0-beta.1 — Paperclip plugin
+
+- **Paperclip plugin** (`plugin/`, npm `papercliped-paperclip-plugin`, a separate package built on `@paperclipai/plugin-sdk`): a **Papercliped** sidebar entry and page inside Paperclip to link your account, list connected apps, switch them between Read only and Full control (beta), disconnect them, toggle anonymity, and unlink. The bridge URL is configurable (https only).
+- **Plugin link API**: `POST /api/manage/plugin-link` (beta, browser session) makes a one-time `pcl_…` code (10 minutes, single use); `POST /api/manage/plugin-link/exchange` trades it for a long-lived `pcb_pl_…` token (rate-limited by address; wrong, used and expired codes answer identically); `GET /api/manage/plugin-links`; `DELETE /api/manage/plugin-links/:id`. The `/manage` page gains a **Link Paperclip plugin** section.
+- **Plugin tokens** are accepted as `Authorization: Bearer` on the manage API (no CSRF header needed). They hold no scopes, so they cannot call any Paperclip tool or the MCP endpoint, and they cannot mint codes, change the beta, sign out, or reach any action that needs the secret key (rotate key, disconnect Paperclip, delete account); those return 403 and need the browser. A token can remove only itself.
+- **Making a new secret key now also revokes every plugin link.**
+- New docs page: Paperclip plugin.
+- New docs page: **Set up your Paperclip**, a step-by-step guide to getting a public https address (Cloudflare Tunnel with your own domain, or Tailscale Funnel, ngrok or a Cloudflare quick tunnel without one).
+
+Not tested: the plugin has never run inside a live Paperclip. It is covered by unit tests against a fake bridge and the SDK's test harness only.
+
+## 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.
+
+
+## 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
 
-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.
+**Run your [Paperclip](https://github.com/paperclipai/paperclip) from any AI app.** Papercliped connects Claude, ChatGPT, Codex and any MCP app to your Paperclip, the open-source orchestrator for companies of AI agents. Check on agents, pause or wake them, assign issues, decide approvals and get status, cost and activity reports, without opening the dashboard.
+
+[![CI](https://github.com/OpenSourcx/papercliped/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenSourcx/papercliped/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/papercliped)](https://www.npmjs.com/package/papercliped)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Free and open source. Website: [papercliped.co](https://papercliped.co) · Docs: [docs.papercliped.co](https://docs.papercliped.co)
+
+> Papercliped is an independent community project, not made by the Paperclip team.
+
+## Add it to your AI app
+
+You need a Paperclip with a public `https` address ([no domain? see this](https://docs.papercliped.co/connect-your-paperclip)). The first time you connect, you approve the request inside your own Paperclip, pick a username, save the secret key you're shown once, and choose **Read only** or **Full control**.
+
+The connector address for every app is:
+
+```
+https://mcp.papercliped.co/mcp
+```
+
+### Claude (web, desktop and mobile)
+
+**Settings → Connectors → Add custom connector**, paste `https://mcp.papercliped.co/mcp`, then **Connect**.
+
+### Claude Code
+
+Install the plugin (adds the tools, a Paperclip skill and `/paperclip-status`, `/paperclip-sync`, `/paperclip-report`):
+
+```
+/plugin marketplace add OpenSourcx/papercliped
+/plugin install papercliped@papercliped
+```
+
+Or just the MCP server:
+
+```sh
+claude mcp add --transport http paperclip https://mcp.papercliped.co/mcp
+```
+
+Then run `/mcp` to sign in.
+
+### Codex
+
+Install the plugin:
+
+```sh
+codex plugin marketplace add OpenSourcx/papercliped
+codex plugin add papercliped@papercliped
+```
+
+Or just the MCP server (Codex starts the sign-in for you):
+
+```sh
+codex mcp add paperclip --url https://mcp.papercliped.co/mcp
+```
+
+### ChatGPT
+
+Turn on **Developer mode** (Settings → Apps → Advanced settings), choose **Create app**, paste `https://mcp.papercliped.co/mcp` and pick OAuth. Menu names change often; the [ChatGPT guide](https://docs.papercliped.co/chatgpt) has the current steps and the Custom GPT (Actions) option.
+
+### Any other MCP app
+
+Add a remote MCP server (Streamable HTTP, OAuth) at `https://mcp.papercliped.co/mcp`. See [Any AI app](https://docs.papercliped.co/other-ai-apps).
+
+### Paperclip on your own machine (no public address)
+
+Run Papercliped locally instead. It talks straight to your Paperclip; nothing goes through papercliped.co. Use a Paperclip **board** token (agent keys can't pause or approve):
+
+```sh
+# Claude Code
+claude mcp add paperclip --env PAPERCLIP_API_URL=http://localhost:3100 --env PAPERCLIP_API_KEY=<board token> -- npx -y papercliped@latest
+
+# Codex
+codex mcp add paperclip --env PAPERCLIP_API_URL=http://localhost:3100 --env PAPERCLIP_API_KEY=<board token> -- npx -y papercliped@latest
+```
+
+Add `--env PAPERCLIP_READ_ONLY=1` for reports and sync only.
+
+## What you can ask
+
+- "What are my agents working on?" · "Which agents are over budget?"
+- "Pause the Web Engineer." · "Wake the CEO and assign it the onboarding issue."
+- "Approve the hire request." · "Weekly cost report, please."
+
+There are 30 tools ([full list](https://docs.papercliped.co/tools)). **Read only** can look at agents, issues, goals, costs and reports. **Full control** can use every tool. The AI asks before anything that can't be undone, and you can change the level or disconnect at any time.
+
+## Manage your connections in Paperclip
+
+Install the **Papercliped plugin for Paperclip** (npm `papercliped-paperclip-plugin`, from **Settings → Plugins** in Paperclip). It adds a Papercliped page where you see every connected app, switch its level, disconnect it, go anonymous, and look after your account. [Plugin guide](https://docs.papercliped.co/paperclip-plugin).
+
+## Security and privacy
+
+- You approve every connection inside your own Paperclip; no passwords pass through Papercliped.
+- Levels are enforced by Papercliped on every call, and every call is audit-logged.
+- Paperclip keys are encrypted at rest; tokens and secret keys are stored only as one-way hashes.
+- Only public `https` Paperclip addresses are reachable from the hosted service.
+- No trackers or third-party scripts on the website.
+
+Threat model: [docs/SECURITY.md](docs/SECURITY.md). Report a vulnerability: [SECURITY.md](SECURITY.md). Privacy: [papercliped.co/privacy](https://papercliped.co/privacy).
+
+## Run it yourself
+
+The hosted service runs exactly this code. To host your own (for a team, or to keep everything on your infrastructure), see [Run it yourself](https://docs.papercliped.co/self-hosting), [docs/oauth.md](docs/oauth.md) and the [launch guide](docs/LAUNCH.md) (Render + Supabase, free tiers).
+
+```sh
+git clone https://github.com/OpenSourcx/papercliped && cd papercliped
+npm install && npm test
+```
+
+## Community and contributing
+
+- Questions and ideas: [GitHub Discussions](https://github.com/OpenSourcx/papercliped/discussions) and Discord ([papercliped.co/community](https://papercliped.co/community))
+- Bugs and feature requests: [issues](https://github.com/OpenSourcx/papercliped/issues/new/choose)
+- Contributing (setup, checks, the path from first PR to maintainer): [CONTRIBUTING.md](CONTRIBUTING.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
+- Every push to `main` is a release: [changelog](CHANGELOG.md) · [how releases work](docs/RELEASING.md)
+
+## License
+
+[MIT](LICENSE)

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