papercliped 1.1.0-beta.2 → 2.1.0

package/docs/LAUNCH.md

@@ -1,16 +1,15 @@
-# Launch guide — Papercliped v1.0.0-beta.1
+# Launch guide — Papercliped v2
 
 Everything here costs **$0/month** (Render free, Supabase free, Cloudflare free). Do the steps in order. Nothing in this repo has been run against a live Render, Supabase, claude.ai or ChatGPT yet — treat the first pass as a staging run and finish with the smoke test (§8).
 
 Never paste database passwords, `service_role` keys or `BRIDGE_SECRET` into chats, issues or commits. They go only into the host's environment settings.
 
 ## 1. Supabase (database)
-1. Open your project → **SQL Editor** → paste all of [`docs/supabase-schema.sql`](supabase-schema.sql) → Run. (This is the full schema: accounts, grants, tokens, audit log, community log, node health, privacy, panel views.)
-2. Create the two least-privilege roles. Edit the passwords, then run [`docs/least-privilege.sql`](least-privilege.sql) (role `bridge_app`, used by the bridge) and [`docs/panel-role.sql`](panel-role.sql) (role `panel_ro`, **read-only**, used by the panel).
+1. Open your project → **SQL Editor** → paste all of [`docs/supabase-schema.sql`](supabase-schema.sql) → Run. (This is the full schema: accounts, grants, tokens, audit log, community log, node health, privacy, and the read-only `panel_*` views used by the separate operator dashboard.)
+2. Create the least-privilege role for the bridge: edit the password, then run [`docs/least-privilege.sql`](least-privilege.sql) (role `bridge_app`). The read-only role for the operator dashboard is set up from that dashboard's own (private) repository.
 3. **Project Settings → Database**: copy the **Transaction pooler** (port 6543) and **Session pooler** (port 5432) host/user details and the **SSL certificate** (CA). Build:
    - `DATABASE_URL` = transaction pooler as `bridge_app`
    - `DATABASE_MIGRATE_URL` = session pooler as the admin (`postgres.<ref>`) role — used only to apply future migrations at start
-   - `PANEL_DATABASE_URL` = transaction pooler as `panel_ro`
 4. Free projects pause after about a week of inactivity. The bridge writes a heartbeat every 10 min while awake and the keep-alive in §5 touches `/readyz` (a database query) every 5 min, so it never goes quiet.
 
 ## 2. Render (the bridge) — Docker web service, no Blueprint
@@ -23,7 +22,7 @@ Blueprints are not needed (and the paid features are not used). The repo ships a
 |---|---|
 | `BRIDGE_OAUTH` | `1` |
 | `BRIDGE_MODE` | `multi` |
-| `BRIDGE_PUBLIC_URL` | `https://papercliped.kpnsolute.com` |
+| `BRIDGE_PUBLIC_URL` | `https://mcp.papercliped.co` (the OAuth issuer; see [DOMAINS.md](DOMAINS.md)) |
 | `BRIDGE_SECRET` | output of `openssl rand -hex 32` — **back it up now**; losing it disconnects every user |
 | `DATABASE_URL` | transaction pooler as `bridge_app` (§1) |
 | `DATABASE_MIGRATE_URL` | session pooler, admin role |
@@ -39,16 +38,44 @@ Blueprints are not needed (and the paid features are not used). The repo ships a
 
 You can test the image anywhere with Docker: `docker build -t papercliped . && docker run --rm -p 10000:10000 -e PORT=10000 -e BRIDGE_TOKEN=$(openssl rand -hex 32) papercliped`.
 
-## 3. Domain: papercliped.kpnsolute.com (Cloudflare)
-1. Render → your service → **Settings → Custom Domains → Add** `papercliped.kpnsolute.com`. Render shows the CNAME target.
-2. Cloudflare → `kpnsolute.com` → **DNS → Add record**: Type `CNAME`, Name `papercliped`, Target `<service>.onrender.com`, **Proxy status: DNS only (grey cloud)** at first.
-3. Back in Render click **Verify**; it issues the TLS certificate (a few minutes). When `https://papercliped.kpnsolute.com/healthz` answers, you may turn the orange cloud on (SSL/TLS mode **Full (strict)**). If you do, set `BRIDGE_PROXY_HOPS=2` (Cloudflare + Render) and re-test sign-in rate limiting.
-4. `BRIDGE_PUBLIC_URL` is the OAuth issuer and is baked into every token. **Set it to the final domain before connecting any client**; changing it later disconnects everyone.
+## 3. Domain: papercliped.co (Cloudflare, free plan)
+The bridge answers at the root of the domain: `https://papercliped.co`.
+
+**A. Put the domain on Cloudflare**
+1. Cloudflare dashboard → **Add a domain** → `papercliped.co` → choose the **Free** plan. Let it import any existing DNS records, then delete ones you don't recognise.
+2. Cloudflare shows two nameservers. At the company you bought the domain from, replace the domain's nameservers with those two. Turn off DNSSEC at the registrar first if it is on (re-enable it from Cloudflare later).
+3. Wait until Cloudflare says the domain is **Active** (minutes to a few hours).
+
+**B. Connect it to Render**
+1. Render → your service → **Settings → Custom Domains → Add** `papercliped.co` (and `www.papercliped.co` if you want it). Render shows the target, `<service>.onrender.com`.
+2. Cloudflare → `papercliped.co` → **DNS → Records → Add record**:
+   - Type `CNAME`, Name `@`, Target `<service>.onrender.com`, **Proxy status: DNS only (grey cloud)**. (Cloudflare allows a CNAME at the root; it flattens it automatically.)
+   - Optional: Type `CNAME`, Name `www`, Target `<service>.onrender.com`, DNS only.
+3. Back in Render click **Verify**. Render issues the TLS certificate (a few minutes). Wait until Render shows the certificate as issued and `https://papercliped.co/healthz` answers.
+4. Cloudflare → **SSL/TLS → Overview**: set encryption mode to **Full (strict)**.
+5. Optional, after the certificate is issued: switch the records to **Proxied (orange cloud)**. If you do, set `BRIDGE_PROXY_HOPS=2` on Render (Cloudflare + Render) and re-test sign-in rate limiting. Grey cloud (DNS only) is fine and simpler.
+
+**C. Don't let Cloudflare block AI apps**
+Claude's and ChatGPT's servers call the bridge directly, so a challenge page breaks them. If the records are proxied:
+- Leave **Bot Fight Mode** off, and don't use "I'm Under Attack" mode.
+- If you add WAF or challenge rules, skip them for `/mcp`, `/actions/*`, `/openapi.json`, `/register`, `/token`, `/revoke`, `/authorize*`, `/.well-known/*`, `/api/manage/*` and `/healthz`, `/readyz`.
+- Don't put Cloudflare Access in front of the bridge.
+
+**D. Contact address (optional, free)**
+Cloudflare → `papercliped.co` → **Email → Email Routing**: create `support@papercliped.co` forwarding to your inbox and verify the destination address (Cloudflare adds the MX, SPF and DKIM records; leave them alone, they sit beside the root CNAME/A record). Email Routing only receives and forwards; replying *as* support@ needs a separate sending service. Add a DMARC record (`_dmarc` TXT) so the domain can't be spoofed. support@ is also the security contact (docs/SECURITY.md). Then set `SITE_CONTACT=support@papercliped.co` on Render.
+
+**More hosts (docs., mcp., api., forum.):** see [DOMAINS.md](DOMAINS.md) for the DNS records, Render domains, `PUBLIC_HOSTS` and the OAuth issuer decision.
+
+**E. Point the bridge at the new domain**
+1. Render → Environment: `BRIDGE_PUBLIC_URL=https://mcp.papercliped.co` (where AI apps connect; the website stays on `papercliped.co`), then redeploy.
+2. `BRIDGE_PUBLIC_URL` is the OAuth issuer and is baked into every token. Changing it disconnects every app that connected under the old address; those users connect again with `https://mcp.papercliped.co/mcp`. Set it to the final domain before inviting more users.
+3. Keep-alive worker (§5): `deploy/wrangler.toml` already targets `https://papercliped.co/readyz`; redeploy it with `npx wrangler deploy`.
+4. Paperclip plugin: its default bridge URL is `https://papercliped.co` (instances that changed the setting keep their own value).
 
 ## 4. Check it works
 ```bash
-curl https://papercliped.kpnsolute.com/readyz                      # {"ok":true,...}
-curl https://papercliped.kpnsolute.com/.well-known/oauth-authorization-server | head
+curl https://papercliped.co/readyz                      # {"ok":true,...}
+curl https://papercliped.co/.well-known/oauth-authorization-server | head
 ```
 
 ## 5. Keep it awake (Cloudflare Worker, free)
@@ -59,39 +86,28 @@ cd deploy && npx wrangler login && npx wrangler deploy      # edit TARGET_URL in
 It runs every 5 minutes (cron `*/5 * * * *`) against `/readyz`. Open the worker's URL once to see the last result. Alternative: a free UptimeRobot HTTP monitor on `/readyz` at a 5-minute interval. Free hosting can still have occasional cold starts — the first request after a platform restart may take about a minute.
 
 ## 6. Install paths for users
-- **Claude (claude.ai / Desktop / mobile):** Settings → Connectors → *Add custom connector* → `https://papercliped.kpnsolute.com/mcp`. Claude opens the Papercliped sign-in page.
-- **Claude Code:** `claude mcp add --transport http papercliped https://papercliped.kpnsolute.com/mcp`, or install the plugin: `/plugin marketplace add OpenSourcx/papercliped` then `/plugin install papercliped@papercliped`.
+- **Claude (claude.ai / Desktop / mobile):** Settings → Connectors → *Add custom connector* → `https://mcp.papercliped.co/mcp`. Claude opens the Papercliped sign-in page.
+- **Claude Code:** `claude mcp add --transport http papercliped https://mcp.papercliped.co/mcp`, or install the plugin: `/plugin marketplace add OpenSourcx/papercliped` then `/plugin install papercliped@papercliped`.
 - **npm / local stdio:** `npx papercliped` with `PAPERCLIP_API_URL` and `PAPERCLIP_API_KEY` set.
-- **ChatGPT:** custom MCP app with the same `/mcp` URL (where your plan offers it), or import `https://papercliped.kpnsolute.com/openapi.json` as a GPT Action (see [chatgpt.md](chatgpt.md)).
+- **ChatGPT:** custom MCP app with the same `/mcp` URL (where your plan offers it), or import `https://mcp.papercliped.co/openapi.json` as a GPT Action (see [chatgpt.md](chatgpt.md)).
 
 First sign-in: pick a username (6–32 characters, at least one number or `.` `#` `_`), connect your Paperclip (public https URL; approve in Paperclip), and **save the secret key shown once**. Later: sign in with username + key, or reconnect through Paperclip approval and keep the same account. Tick *Appear anonymously* to be shown as an alias like `Ann02`.
 
-## 7. The operator panel (separate program)
-The panel never sees bridge secrets and only has read access (`panel_ro`). Its environment is exactly:
-```
-PANEL_ADMIN_TOKEN=<openssl rand -hex 32>
-PANEL_DATABASE_URL=<panel_ro URL>   PANEL_DATABASE_SSL=verify   PANEL_DATABASE_CA=<PEM>
-PANEL_ALLOWED_IPS=<your IP>         # strongly recommended
-```
-It refuses to start if `BRIDGE_SECRET` or `DATABASE_URL` is present.
-- **Easiest ($0, no extra hours):** run it on your own machine — `npx papercliped-panel` — and open http://127.0.0.1:3940.
-- **Always-on:** a second free Render service shares the 750 free hours and could suspend the bridge, so don't. Use another free host (Fly.io, Koyeb, a home server) or put it behind Cloudflare Tunnel + Cloudflare Access.
-- Preview with fake data: `PANEL_DEMO=1 PANEL_ADMIN_TOKEN=<24+ chars> npx papercliped-panel`.
-
-The panel shows system health (and turns critical if the bridge stops reporting — asleep, crashed or cut off from the database), latency percentiles, bridge-vs-Paperclip time, faults vs. caller errors, user count, flow success rate and the live log:
-`09:25:30 og.kpnwrld - joined cliped` · `… - left cliped` · `… - updated cliped`.
-Anonymous users appear as their alias. Operator commands: `npx papercliped-admin users | delete-user <name> | grants | revoke <id> | revoke-all --yes`.
+## 7. Watching the service
+- **Public stats (no sign-in):** `https://papercliped.co/api/public/v1/status` and `/api/public/v1/stats?window=24h` give aggregate users, connections, sign-in success, request success rate, latency, error mix and load. The website's `/status` page shows them with charts. Nothing identifying is published (see the public API docs).
+- **Operator dashboard:** lives in a separate, access-controlled service (its own private repository), not in this repo. It reads the same telemetry tables (`audit_events`, `user_events`, `node_samples`) and the read-only `panel_*` views, which the bridge keeps writing and the migrations keep providing.
+- **Operator commands** (on a machine with the bridge's environment): `npx papercliped-admin users | delete-user <name> | grants | revoke <id> | revoke-all --yes`.
 
 ## 8. Smoke test (before announcing)
 1. Add the connector in claude.ai, create an account, connect a real Paperclip, ask "list my agents".
 2. Disconnect, reconnect with the secret key; reconnect again through Paperclip approval (same account).
-3. Toggle anonymity; confirm the panel shows the alias for old and new entries.
-4. Stop traffic for 20 min; confirm the Cloudflare worker keeps the service answering and the panel shows it healthy.
+3. Toggle anonymity; confirm the operator dashboard shows the alias for old and new entries.
+4. Stop traffic for 20 min; confirm the Cloudflare worker keeps the service answering and `/api/public/v1/status` says `ok`.
 
 ## 9. Marketplaces — submit only after the smoke test passes
 Requirements change; confirm each against the current official page before submitting.
 
-**Claude directory (connectors / plugins)** — have ready: public GitHub repo (done), plugin manifest [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json), the remote MCP URL `https://papercliped.kpnsolute.com/mcp`, OAuth callbacks (`https://claude.ai/api/mcp/auth_callback`, Claude Code's localhost loopback), privacy policy and terms (served by the bridge at `https://papercliped.kpnsolute.com/privacy` and `/terms`; set `SITE_CONTACT` to a real contact address), a support contact, tool descriptions with read/write annotations, and a **test account** with a demo Paperclip for reviewers. Submit through Anthropic's connector/plugin submission form linked from the Claude docs. Until listed, users install through the custom-connector or `/plugin marketplace add` paths above.
+**Claude directory (connectors / plugins)** — have ready: public GitHub repo (done), plugin manifest [`.claude-plugin/plugin.json`](../.claude-plugin/plugin.json), the remote MCP URL `https://mcp.papercliped.co/mcp`, OAuth callbacks (`https://claude.ai/api/mcp/auth_callback`, Claude Code's localhost loopback), privacy policy and terms (served by the bridge at `https://papercliped.co/privacy` and `/terms`; set `SITE_CONTACT` to a real contact address), a support contact, tool descriptions with read/write annotations, and a **test account** with a demo Paperclip for reviewers. Submit through Anthropic's connector/plugin submission form linked from the Claude docs. Until listed, users install through the custom-connector or `/plugin marketplace add` paths above.
 
 **ChatGPT (apps / GPT Store)** — an MCP app needs a public https MCP endpoint with OAuth (you have it), a privacy policy URL, and domain verification in the OpenAI developer dashboard; a GPT with Actions needs the OpenAPI URL and OAuth settings (see [chatgpt.md](chatgpt.md)). Submission details for the apps directory are still moving — follow OpenAI's current "apps SDK / submit your app" guide.
 
@@ -101,7 +117,7 @@ npm login                      # account with 2FA
 npm run build && npm test
 npm publish --tag beta         # first publish of "papercliped"; check the name is free first: npm view papercliped
 ```
-Users run `npx papercliped@beta`. With the repo secret `NPM_TOKEN` set, pushing a `v*` tag runs [`release.yml`](../.github/workflows/release.yml), which publishes with provenance and creates the GitHub release. If the name `papercliped` is taken, use a scope (`@kpnworld/papercliped`) and change `name` in `package.json`.
+Users run `npx papercliped@beta`. Pushing a new version to `main` runs [`release.yml`](../.github/workflows/release.yml), which publishes with npm trusted publishing (no token) and creates the GitHub release; one-time setup is in [RELEASING.md](RELEASING.md). If the name `papercliped` is taken, use a scope (`@kpnworld/papercliped`) and change `name` in `package.json`.
 
 ## 11. GitHub release "v1.0.0-beta.1"
 Releases → **Draft a new release** → tag `v1.0.0-beta.1` (target `main`) → title *Papercliped v1.0.0-beta.1* → paste [`CHANGELOG.md`](../CHANGELOG.md) → tick **Set as a pre-release** → Publish.

package/docs/RELEASING.md

@@ -0,0 +1,37 @@
+# Releasing
+
+Two npm packages ship from one version: `papercliped` (the bridge, repo root) and `papercliped-paperclip-plugin` (`plugin/`). Publishing uses **npm trusted publishing** (OIDC) from `.github/workflows/release.yml`: no npm token is stored in GitHub, and provenance is attached automatically.
+
+Requirements: the repository is public, the workflow runs on GitHub-hosted runners, and GitHub Actions is enabled (and billable, if needed) for the `OpenSourcx` organization.
+
+## One-time setup (npmjs.com)
+Trusted publishing can only be configured on a package that already exists.
+
+**State as of v2.1.0:** both packages exist on npm (`papercliped` 1.1.0-beta.2, `papercliped-paperclip-plugin` 2.0.0), so step 1 is done. `papercliped-paperclip-plugin@2.0.0` predates the move of account management into the plugin and links with the old one-time codes, which the bridge no longer accepts: v2.1.0 replaces it. Do step 2 for the plugin before tagging if you want the workflow to publish it; otherwise publish 2.1.0 by hand and the workflow skips it.
+
+1. Publish the first version by hand, with 2FA (the plugin needs Node 24.11 or newer):
+   ```sh
+   npm login
+   npm --prefix plugin ci
+   cd plugin && npm publish --otp=<code>        # builds first (prepublishOnly); publishes papercliped-paperclip-plugin@2.0.0
+   ```
+   If you publish the plugin by hand at 2.0.0, the release run skips it (that version already exists) and publishes only `papercliped`.
+2. For **each** package on npmjs.com: open the package → **Settings** → **Trusted publishing** → **GitHub Actions** and enter:
+   - Organization or user: `OpenSourcx`
+   - Repository: `papercliped`
+   - Workflow filename: `release.yml`
+   - Allow `npm publish`
+3. For each package, set **Publishing access** to *Require two-factor authentication and disallow tokens*, then revoke any old automation tokens.
+
+`repository.url` in both `package.json` files must stay exactly `git+https://github.com/OpenSourcx/papercliped.git` (npm checks it against the workflow's repository), and `publishConfig` must stay `{ "access": "public" }`.
+
+## The website
+The website (`web/`) is **not** in the npm package. The Docker image builds it (a separate stage) and the bridge serves it from `/app/web/dist`. The npm package's `papercliped-bridge` serves its built-in Markdown pages instead, unless you point `WEB_DIST` at a built copy (`npm --prefix web ci && npm --prefix web run build`).
+
+## Each release
+Releases are automatic: **every push to `main` whose version isn't released yet becomes a release.** Nobody pushes tags.
+
+1. Add what changed under `## Unreleased` in `CHANGELOG.md`, then run `node scripts/version.mjs <major|minor|patch> "<title>"`. It bumps every file listed in `.release.json` (`package.json`, `plugin/package.json`, `.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, `plugin/src/manifest.ts`, the lockfiles), turns `## Unreleased` into `## vX.Y.Z — <title>` and records the date. Which number to bump, and how to write the commit description, is in the release skill (`.agents/skills/release/SKILL.md`).
+2. Push to `main`.
+
+On every push to `main`, `.github/workflows/release.yml` reads the version. If the tag `vX.Y.Z` already exists it stops (an ordinary commit). Otherwise it checks that every version string and the changelog section agree, builds and tests the root and the plugin, packs and installs both packages as a user would (`scripts/check-packages.mjs`), publishes `papercliped` and `papercliped-paperclip-plugin` (a version with `-`, like `2.2.0-beta.1`, goes to the `beta` dist-tag, otherwise `latest`), and only then creates the tag `vX.Y.Z` on that exact commit together with the GitHub release, whose notes are the changelog section followed by every commit description since the previous release. A push that doesn't bump the version ships nothing and gets a warning in the run. Each publish step skips a version already on npm, and the tag is made last, so a failed run can be re-run from the Actions tab (or with **Run workflow**) once the cause is fixed.

package/docs/SECURITY.md

@@ -1,65 +1,82 @@
-# Security model (public / multi-tenant deployment)
-
-Read this before running the bridge for people other than yourself.
-
-## What you are holding
-For every connected user the bridge stores a **Paperclip board API key**. In Paperclip that key is bound to the *user*, not to a company, and carries **all** of that user's board power (verified in Paperclip's source: `board_api_keys` has no scope column, and the challenge's `requestedCompanyId` is only used to attribute activity-log entries, not to restrict the key). The bridge's scopes (read/control/admin) limit what *connected AI clients* may do through the bridge. They do **not** limit what the stored key can do if the bridge itself is compromised.
-
-> **Headline risk:** a full compromise of the running bridge (code execution on the Render service *and* access to its environment) exposes every connected user's Paperclip with full board access, until those keys are revoked. Everything below reduces the likelihood or blast radius; none of it removes that risk. Until Paperclip offers scoped/short-lived keys, tell users plainly, encourage a dedicated Paperclip user for the connection, and keep the user base small enough to be comfortable with that.
-
-## Trust boundaries
-```
-AI client (claude.ai, ChatGPT)  ──OAuth, scoped, opaque tokens──▶  Bridge  ──user's board key, https only──▶  User's Paperclip (stranger-controlled)
-                                                                     │
-                                                                     └──▶ Postgres (sealed credentials, token hashes)
-```
-
-## Threats and mitigations (each marked with where it is tested)
-| # | Threat | Mitigation | Test |
-| - | --- | --- | --- |
-| 1 | **SSRF**: a user types an internal/metadata address as their "Paperclip" | https-only DNS names, no IP literals (incl. decimal/hex/IPv6/Unicode-dot forms), port allow-list (443), no `.local/.internal/.lan/…`, bridge's own host denied; **the resolved address is validated inside the connection's DNS lookup**, so there's no check-then-connect gap for DNS rebinding; any non-public answer refuses the whole name; no redirects; 20 s / 2 MB caps | `safe-fetch.test.ts`, `multitenant.test.ts` (nothing leaves the bridge for 15 hostile inputs) |
-| 2 | Hostile "Paperclip" returns crafted data (bad ids, `@evil.com` approval link, non-JSON, huge bodies) | every field validated (uuid ids, strict approval-path pattern, token charset/length, bounded expiry); only whitelisted statuses honoured; `local_trusted` refused; body capped | `multitenant.test.ts` (hostile cases) |
-| 3 | Probing the network through the instance step | per-request attempt cap (5), per-IP rate limit, no error detail from resolution/connection leaks to the user | same |
-| 4 | Cross-tenant mix-up (user A's token sent to B's host) | each grant stores its own instance; the client is built per request from that grant only; the instance is re-validated on **every** call (tampered/newly denied hosts are cut off); the raw-API tool takes only a path | `tenant isolation`, `re-validates the stored instance` |
-| 5 | Database leak | credentials sealed in the app with AES-256-GCM (key from `BRIDGE_SECRET`, never in the DB); tokens stored as SHA-256 only; consumed authorization codes are scrubbed; **the database alone yields nothing usable** | `multitenant.test.ts` (Postgres at-rest check) |
-| 6 | Supabase Data API exposes the tables | dedicated `bridge` schema (not exposed by default), RLS on with no policies, grants revoked from `anon`/`authenticated`; app uses a role that can touch only these tables | `store.test.ts` (anon/authenticated denied; least-privilege role) |
-| 7 | OAuth attacks: code interception, replay, CSRF, open redirect, mix-up | PKCE S256 mandatory; single-use 60 s codes (atomic in SQL; replay revokes the grant it created); CSRF token on every form; never redirects to an unregistered `redirect_uri`; allow-listed redirect hosts; `iss` in responses | `oauth.test.ts`, `store.test.ts` (races) |
-| 8 | Token theft | opaque tokens, 1 h access / 30 d refresh; refresh rotation with **reuse detection** (revokes the grant and the Paperclip key); atomic consume so a race can't mint two | `oauth.test.ts`, `store.test.ts` |
-| 9 | Over-privileged AI client / prompt injection into the model | read/control/admin enforced by the bridge, admin never preselected, out-of-scope tools hidden and refused; confirm gates on destructive calls; per-grant call budget (120/min) | `oauth.test.ts`, `multitenant.test.ts` |
-| 10 | Stale credentials linger after a user "disconnects" in the client (clients often just forget tokens) | hourly sweep revokes grants idle > 30 days and deletes the credential; `/revoke` honoured; Paperclip key revoked upstream (`revoke-current`). The key's name in the user's Paperclip is `<client> (via bridge, returns to <host>) (board)` so they can see/revoke it themselves | `multitenant.test.ts` (sweep) |
-| 11 | Phishing via a malicious OAuth client claiming to be "Claude" | clients register only allow-listed redirect hosts; the Paperclip approval page shows the real redirect host in the key label; the consent page shows the redirect host and the instance host | `oauth.test.ts` |
-| 12 | Brute force of the instance/consent/token endpoints | per-IP and per-grant limits in the shared store (work across several instances); client IP taken from the trusted-proxy position, not the forgeable left side of `X-Forwarded-For` | `multitenant.test.ts` |
-| 13 | Clickjacking / XSS on consent pages | CSP (`frame-ancestors 'none'`, nonce'd script, restricted `form-action`), `X-Frame-Options`, all dynamic text escaped | `oauth.test.ts` |
-| 14 | Operator error: unsafe public config | the process refuses to start for: http issuer, short secret, `BRIDGE_TOKEN` set in multi mode, static login in multi mode, no database in multi mode | `multitenant.test.ts` |
-| 16 | Telemetry becoming a data leak / a side door | audit rows hold only tool name, outcome, timings, grant id, client name, tenant host, user id (never arguments, results, tokens or credentials); retention 30 days; recorder can't block or fail a request; the panel is a SEPARATE process with its own token (cannot call tools), a read-only database role limited to safe views (no secret hashes, sealed credentials or tokens), refuses to start with bridge secrets in its environment, optional IP allow-list, signed HttpOnly SameSite=Strict sessions, rate-limited sign-in, strict CSP (no external loads), and renders all data with `textContent` | `audit.test.ts` |
-| 15 | Key compromise / rotation | key ring (`BRIDGE_SECRET_PREVIOUS`), `rotate-keys`, `revoke-all --yes` | `multitenant.test.ts` |
-
-## Residual risks (not mitigated here)
-1. **Bridge compromise = access to all connected Paperclips** (headline risk above). Reduce: minimal dependencies, pinned versions, 2FA on Render/GitHub/Supabase, no shell access to the service, alerts on unusual `audit` volume.
-2. **A user's own Paperclip can feed prompt-injected text to the AI client.** The skill instructs the model to treat tool output as data, but that is not a hard boundary. Scopes bound the damage (a read-only connection can't change anything).
-3. **No per-company limits.** A grant reaches every company that user can reach (Paperclip limitation, see above).
-4. **DNS rebinding after connect, TLS interception by a hostile network between Render and a tenant:** TLS verification is on; we do not pin certificates.
-5. **Single database, single region, single secret.** Losing `BRIDGE_SECRET` disconnects everyone (by design: it cannot be recovered).
-6. **Not independently audited.** Treat this as unreviewed code. Before a wide public launch, get an external review of `src/net/safe-fetch.ts`, `src/oauth/*` and the migrations.
-7. DCR clients accumulate (idle ones are pruned after 7 days; capped at 1000).
-8. ChatGPT's real redirect hosts and Claude's directory-review requirements were taken from documentation/secondary sources, not tested.
-
-## Operational checklist
-- [ ] `BRIDGE_SECRET` stored in a password manager, separate from the database backups
-- [ ] `DATABASE_SSL=verify` with the Supabase CA (not `require`)
-- [ ] App uses the `bridge_app` role; admin role only in `DATABASE_MIGRATE_URL`
-- [ ] `bridge` schema not in Supabase's exposed schemas; anon-key read of `bridge.grants` fails
-- [ ] 2FA on Render, Supabase, GitHub, npm
-- [ ] Log retention ≤ 30 days; confirm logs contain no tokens (audit lines hold tool, grant id, client, instance host, user id only)
-- [ ] Privacy policy + terms published; support and security contact set
-- [ ] `revoke-all --yes` rehearsed on staging
-- [ ] External security review done (before >~50 users or any directory listing)
-
-## Reporting a vulnerability
-Email **[SECURITY CONTACT — set before launch]** with details; please don't open public issues for security reports. We aim to acknowledge within 3 business days.
-
-## Accounts, secret keys and anonymity (v1.0.0-beta.1)
-
-- A user's **secret key** is shown once, stored only as a salted scrypt hash, and works like a password for *their Paperclip connection*: anyone holding it can sign in as them. Users can replace it by reconnecting through Paperclip approval.
-- Usernames appear only in the operator's logs and panel. With **anonymous mode** on, logs, grants and audit rows show an alias (`Ann02`) and a masked instance label instead; toggling rewrites history. This is **pseudonymity, not anonymity from the operator**: someone with base-table database access (the bridge role, the Supabase admin) can still map alias → account. The panel role cannot.
-- Account actions are rate-limited per username and per address; failed sign-ins never reveal whether a username exists beyond what registration already shows.
+# Security model (public / multi-tenant deployment)
+
+Read this before running the bridge for people other than yourself.
+
+## What you are holding
+For every connected user the bridge stores a **Paperclip board API key**. In Paperclip that key is bound to the *user*, not to a company, and carries **all** of that user's board power (verified in Paperclip's source: `board_api_keys` has no scope column, and the challenge's `requestedCompanyId` is only used to attribute activity-log entries, not to restrict the key). The bridge's scopes (read/control/admin) limit what *connected AI clients* may do through the bridge. They do **not** limit what the stored key can do if the bridge itself is compromised.
+
+> **Headline risk:** a full compromise of the running bridge (code execution on the Render service *and* access to its environment) exposes every connected user's Paperclip with full board access, until those keys are revoked. Everything below reduces the likelihood or blast radius; none of it removes that risk. Until Paperclip offers scoped/short-lived keys, tell users plainly, encourage a dedicated Paperclip user for the connection, and keep the user base small enough to be comfortable with that.
+
+## Trust boundaries
+```
+AI client (claude.ai, ChatGPT)  ──OAuth, scoped, opaque tokens──▶  Bridge  ──user's board key, https only──▶  User's Paperclip (stranger-controlled)
+                                                                     │
+                                                                     └──▶ Postgres (sealed credentials, token hashes)
+```
+
+## Threats and mitigations (each marked with where it is tested)
+| # | Threat | Mitigation | Test |
+| - | --- | --- | --- |
+| 1 | **SSRF**: a user types an internal/metadata address as their "Paperclip" | https-only DNS names, no IP literals (incl. decimal/hex/IPv6/Unicode-dot forms), port allow-list (443), no `.local/.internal/.lan/…`, bridge's own host denied; **the resolved address is validated inside the connection's DNS lookup**, so there's no check-then-connect gap for DNS rebinding; any non-public answer refuses the whole name; no redirects; 20 s / 2 MB caps | `safe-fetch.test.ts`, `multitenant.test.ts` (nothing leaves the bridge for 15 hostile inputs) |
+| 2 | Hostile "Paperclip" returns crafted data (bad ids, `@evil.com` approval link, non-JSON, huge bodies) | every field validated (uuid ids, strict approval-path pattern, token charset/length, bounded expiry); only whitelisted statuses honoured; `local_trusted` refused; body capped | `multitenant.test.ts` (hostile cases) |
+| 3 | Probing the network through the instance step | per-request attempt cap (5), per-IP rate limit, no error detail from resolution/connection leaks to the user | same |
+| 4 | Cross-tenant mix-up (user A's token sent to B's host) | each grant stores its own instance; the client is built per request from that grant only; the instance is re-validated on **every** call (tampered/newly denied hosts are cut off); the raw-API tool takes only a path | `tenant isolation`, `re-validates the stored instance` |
+| 5 | Database leak | credentials sealed in the app with AES-256-GCM (key from `BRIDGE_SECRET`, never in the DB); tokens stored as SHA-256 only; consumed authorization codes are scrubbed; **the database alone yields nothing usable** | `multitenant.test.ts` (Postgres at-rest check) |
+| 6 | Supabase Data API exposes the tables | dedicated `bridge` schema (not exposed by default), RLS on with no policies, grants revoked from `anon`/`authenticated`; app uses a role that can touch only these tables | `store.test.ts` (anon/authenticated denied; least-privilege role) |
+| 7 | OAuth attacks: code interception, replay, CSRF, open redirect, mix-up | PKCE S256 mandatory; single-use 60 s codes (atomic in SQL; replay revokes the grant it created); CSRF token on every form; never redirects to an unregistered `redirect_uri`; allow-listed redirect hosts; `iss` in responses | `oauth.test.ts`, `store.test.ts` (races) |
+| 8 | Token theft | opaque tokens, 1 h access / 30 d refresh; refresh rotation with **reuse detection** (revokes the grant and the Paperclip key); atomic consume so a race can't mint two | `oauth.test.ts`, `store.test.ts` |
+| 9 | Over-privileged AI client / prompt injection into the model | read/control enforced by the bridge, read preselected, out-of-scope tools hidden and refused; confirm gates on destructive calls; per-grant call budget (120/min) | `oauth.test.ts`, `multitenant.test.ts` |
+| 10 | Stale credentials linger after a user "disconnects" in the client (clients often just forget tokens) | hourly sweep revokes grants idle > 30 days and deletes the credential; `/revoke` honoured; Paperclip key revoked upstream (`revoke-current`). The key's name in the user's Paperclip is `<client> (via bridge, returns to <host>) (board)` so they can see/revoke it themselves | `multitenant.test.ts` (sweep) |
+| 11 | Phishing via a malicious OAuth client claiming to be "Claude" | clients register only allow-listed redirect hosts; the Paperclip approval page shows the real redirect host in the key label; the consent page shows the redirect host and the instance host | `oauth.test.ts` |
+| 12 | Brute force of the instance/consent/token endpoints | per-IP and per-grant limits in the shared store (work across several instances); client IP taken from the trusted-proxy position, not the forgeable left side of `X-Forwarded-For` | `multitenant.test.ts` |
+| 13 | Clickjacking / XSS on consent pages | CSP (`frame-ancestors 'none'`, nonce'd script, restricted `form-action`), `X-Frame-Options`, all dynamic text escaped | `oauth.test.ts` |
+| 14 | Operator error: unsafe public config | the process refuses to start for: http issuer, short secret, `BRIDGE_TOKEN` set in multi mode, static login in multi mode, no database in multi mode | `multitenant.test.ts` |
+| 16 | Telemetry becoming a data leak / a side door | audit rows hold only tool name, outcome, timings, grant id, client name, tenant host, user id (never arguments, results, tokens or credentials); retention 30 days; recorder can't block or fail a request; the operator dashboard is a SEPARATE, access-controlled service outside this repo (cannot call tools) with a read-only database role limited to safe views (no secret hashes, sealed credentials or tokens); the public stats API returns aggregates only, never identities | `audit.test.ts`, `public-api.test.ts`, `store.test.ts` |
+| 15 | Key compromise / rotation | key ring (`BRIDGE_SECRET_PREVIOUS`), `rotate-keys`, `revoke-all --yes` | `multitenant.test.ts` |
+
+## Residual risks (not mitigated here)
+1. **Bridge compromise = access to all connected Paperclips** (headline risk above). Reduce: minimal dependencies, pinned versions, 2FA on Render/GitHub/Supabase, no shell access to the service, alerts on unusual `audit` volume.
+2. **A user's own Paperclip can feed prompt-injected text to the AI client.** The skill instructs the model to treat tool output as data, but that is not a hard boundary. Scopes bound the damage (a read-only connection can't change anything).
+3. **No per-company limits.** A grant reaches every company that user can reach (Paperclip limitation, see above).
+4. **DNS rebinding after connect, TLS interception by a hostile network between Render and a tenant:** TLS verification is on; we do not pin certificates.
+5. **Single database, single region, single secret.** Losing `BRIDGE_SECRET` disconnects everyone (by design: it cannot be recovered).
+6. **Not independently audited.** Treat this as unreviewed code. Before a wide public launch, get an external review of `src/net/safe-fetch.ts`, `src/oauth/*` and the migrations.
+7. DCR clients accumulate (idle ones are pruned after 7 days; capped at 1000).
+8. ChatGPT's real redirect hosts and Claude's directory-review requirements were taken from documentation/secondary sources, not tested.
+
+## Operational checklist
+- [ ] `BRIDGE_SECRET` stored in a password manager, separate from the database backups
+- [ ] `DATABASE_SSL=verify` with the Supabase CA (not `require`)
+- [ ] App uses the `bridge_app` role; admin role only in `DATABASE_MIGRATE_URL`
+- [ ] `bridge` schema not in Supabase's exposed schemas; anon-key read of `bridge.grants` fails
+- [ ] 2FA on Render, Supabase, GitHub, npm
+- [ ] Log retention ≤ 30 days; confirm logs contain no tokens (audit lines hold tool, grant id, client, instance host, user id only)
+- [ ] Privacy policy + terms published; support and security contact set
+- [ ] `revoke-all --yes` rehearsed on staging
+- [ ] External security review done (before >~50 users or any directory listing)
+
+## Reporting a vulnerability
+Email **support@papercliped.co** with details (put "security" in the subject), or open a private GitHub security advisory on `OpenSourcx/papercliped`; please don't open public issues for security reports. We aim to acknowledge within 3 business days.
+
+## Accounts, secret keys and anonymity (v1.0.0-beta.1)
+
+- A user's **secret key** is shown once, stored only as a salted scrypt hash, and works like a password for *their Paperclip connection*: anyone holding it can sign in as them. Users can replace it by reconnecting through Paperclip approval.
+- Usernames appear only in the operator's logs and the private operator dashboard. With **anonymous mode** on, logs, grants and audit rows show an alias (`Ann02`) and a masked instance label instead; toggling rewrites history. This is **pseudonymity, not anonymity from the operator**: someone with base-table database access (the bridge role, the Supabase admin) can still map alias → account. A read-only dashboard role over the safe views cannot.
+- Account actions are rate-limited per username and per address; failed sign-ins never reveal whether a username exists beyond what registration already shows.
+
+## Account management through the Paperclip plugin
+
+- There is no browser page or cookie session any more: the manage API accepts only bearer plugin tokens, which a cross-site page cannot attach without a CORS preflight (never approved), so there is no CSRF surface. `GET /manage` redirects to the plugin docs.
+- **Linking:** the plugin sends username + secret key once to `POST /api/manage/plugin-link/sign-in`, throttled with the same per-address and per-account counters as the sign-in page. The answer is a long-lived token (`pcb_pl_…`, stored hashed on a grant with **no scopes**, 180-day expiry). The key is not stored by the plugin or the bridge (only its hash, as before).
+- A plugin token opens only the manage API for its own account. It can **not** call the MCP or Actions endpoints. Sensitive actions (new secret key, disconnect Paperclip, delete account) need the secret key in that request and share the sign-in throttle; deleting also needs the username typed. A new secret key revokes every plugin link and issues one fresh token to the plugin that asked. Tests: `test/manage.test.ts`.
+- The plugin runs as trusted, same-origin code inside Paperclip and is installed only by the instance admin. Its worker keeps each person's token in plugin state keyed by a hash of the host-verified user id, never returns it to the page, and talks only to an `https` bridge URL. Residual risk: anyone able to read the plugin's state storage (the Paperclip server operator) can use a linked token for the manage API; remove that link from another Paperclip, or make a new secret key, if the Paperclip host is not trusted.
+- The plugin has not been run in a live Paperclip; see `plugin/README.md`.
+
+## Planned (v2): managed subdomains
+See `docs/V3-SUBDOMAINS.md` §7a for the hardening list and the threats to add here when it is built.
+
+## Public stats API and the operator dashboard (v2)
+
+- `GET /api/public/v1/*` publishes **aggregate numbers only**: counts, rates, latency percentiles, fixed error and sign-in failure categories, and tool-name call counts from the public catalogue. It never returns usernames, aliases, account or grant ids, Paperclip hosts, app names, IP addresses, tokens or free-text details, and never breaks numbers down per user or per tenant. Unknown categories are counted as `other` rather than echoed. Tests: `test/public-api.test.ts` seeds recognisable names, hosts and aliases and asserts none appear in any response (memory and Postgres).
+- It is GET-only, CORS-open without credentials or cookies, cached 30 s and rate-limited to 60 requests per minute per address.
+- The **operator dashboard** (per-user and per-tenant views, the community log with usernames) is **not in this repository**. It runs as a separate, access-controlled service with its own credentials and a read-only database role over the `panel_*` views and telemetry tables. `test/store.test.ts` keeps proving that such a role can read nothing sensitive.

package/docs/SITEMAP.md

@@ -0,0 +1,92 @@
+# Site map: every page and endpoint
+
+Current as of v2.0.0 (read from the route code). Items marked **(planned v3)** do not exist yet. `{{URL}}` is the bridge's public address (today `https://papercliped.co`).
+
+## 0. Hosts
+One service, routed by host (`PUBLIC_HOSTS`, `src/web/`): `papercliped.co` the website, `docs.papercliped.co` the docs (landing at `/`, pages at `/<page>`), `mcp.`/`api.papercliped.co` the protocol and APIs, `forum.` a redirect, `www.` a redirect to the apex. See `docs/DOMAINS.md`. Below, docs paths are shown as `/docs/<page>`; on the docs host they are `/<page>`.
+
+## 1. Public website (React, `web/`; the bridge's Markdown pages in `src/site/` are the fallback)
+| Path | Page |
+| --- | --- |
+| `/` | Landing page ("Papercliped, not Paperclipped."), live user count |
+| `/status` | Live status page (public API) |
+| `/changelog` | Changelog (and `/changelog.xml` feed) |
+| `/community` | Community |
+| `/brand` | Brand assets |
+| `/kit` | Design kit (not indexed) |
+| `/docs` | Redirects to `/docs/getting-started` |
+| `/docs/getting-started` | Getting started |
+| `/docs/what-is-papercliped` | What is Papercliped? (overview and glossary) |
+| `/docs/self-hosting` | Run it yourself |
+| `/docs/tools` | Tool reference (generated from `src/tools.ts`) |
+| `/docs/manage-api` | Manage API |
+| `/docs/environment` | Environment variables |
+| `/docs/cli` | Command line |
+| `/docs/limits-and-errors` | Limits and errors |
+| `/docs/faq` | FAQ |
+| `/docs/signup` | Create your account |
+| `/docs/connect-your-paperclip` | Set up your Paperclip (public address, tunnels, domains) |
+| `/docs/manage` | Manage connections |
+| `/docs/paperclip-plugin` | Paperclip plugin |
+| `/docs/permissions` | Permissions |
+| `/docs/anonymous-mode` | Anonymous mode |
+| `/docs/public-api` | Public API and status |
+| `/docs/security` | Security |
+| `/docs/other-ai-apps` | Any AI app (MCP) |
+| `/docs/chatgpt` | ChatGPT setup |
+| `/docs/troubleshooting` | Troubleshooting |
+| `/privacy` | Privacy policy |
+| `/terms` | Terms of service |
+| `/favicon.svg`, `/favicon.ico` | Favicon |
+| `/api/public/stats` | JSON: user and connection counts only (legacy; see section 6) |
+| `/domain` **(planned v3)** | Get a public address: guide, own domain, or the paid managed subdomain |
+| `/docs/subdomain-terms` **(planned v3)** | Subdomain Terms (drafted separately) |
+
+## 2. Sign-in and consent (OAuth screens, shown inside Claude/ChatGPT flows) — `src/oauth/`
+| Path | Purpose |
+| --- | --- |
+| `GET /authorize` | Start: sign in with username and secret key, or connect your Paperclip |
+| `GET /authorize/status` | Polling while the user approves in Paperclip |
+| `POST /authorize/login`, `/connect`, `/instance`, `/approved`, `/username`, `/welcome`, `/continue`, `/decision` | The steps of the screens above (login, enter address, approve, pick username, secret key shown once, consent: Read only / Full control, Appear anonymously) |
+| `/authorize` link "No public address?" **(planned v3)** | Links to `/domain` |
+
+## 3. Account management (inside Paperclip, via the plugin) — `src/manage/`
+| Path | Purpose |
+| --- | --- |
+| `GET /manage` | Old address: redirects to `/docs/paperclip-plugin` |
+| `/api/manage/*` | JSON API used by the Paperclip plugin (bearer token only, no cookies): `plugin-link/sign-in`, `me`, `connections`, `connections/:id`, `privacy`, `plugin-links`, `plugin-links/:id`, `secret/rotate`, `paperclip/disconnect`, `account/delete` (the last three need the secret key again) |
+| Domain section in the plugin **(planned v3)** | Pro members: address, tunnel status, token, port, release |
+
+## 4. AI client endpoints
+| Path | Purpose |
+| --- | --- |
+| `/mcp` | MCP over Streamable HTTP (Claude and other MCP clients) |
+| `/actions/<tool>` | ChatGPT Actions, one per tool |
+| `/openapi.json` | OpenAPI description for GPT Actions |
+| `/register`, `/token`, `/revoke` | OAuth 2.1 dynamic client registration, tokens, revocation |
+| `/.well-known/oauth-authorization-server` | OAuth server metadata |
+| `/.well-known/oauth-protected-resource`, `/.well-known/oauth-protected-resource/mcp` | Protected-resource metadata |
+
+## 5. Operations
+| Path | Purpose |
+| --- | --- |
+| `/healthz` | Liveness |
+| `/readyz` | Readiness (database ping) |
+
+## 6. Public stats API (no sign-in, aggregate only) — `src/public-api/`
+| Path | Purpose |
+| --- | --- |
+| `GET /api/public/v1/info` | Version, endpoints, limits |
+| `GET /api/public/v1/status` | ok / degraded / down |
+| `GET /api/public/v1/stats?window=1h\|24h\|7d` | Users, connections, sign-ins, requests, errors, load |
+| `GET /api/public/v1/series?window=…` | The same over time |
+| `GET /api/public/v1/errors?window=…` | Error mix and sign-in failure reasons |
+| `GET /api/public/v1/repo` | GitHub stars, forks and open issues (cached hourly, fetched by the bridge) |
+| `GET /api/public/v1/openapi.json` | OpenAPI for this API (separate from the Actions document) |
+
+The operator dashboard is a separate, access-controlled service and is not part of this repository.
+
+## 7. Not web pages
+- **Paperclip plugin** (`plugin/`, runs inside Paperclip): sidebar entry "Papercliped" and page at `/<company>/papercliped`.
+- **Home-server provisioner** **(planned v3)**: no pages; polls the bridge's job queue.
+- **Repo docs** (`docs/`, not served): ARCHITECTURE, SECURITY, LAUNCH, DEPLOY-RENDER, RELEASING, SITEMAP, V3-SUBDOMAINS, oauth, chatgpt, legal templates, SQL files.

package/docs/V3-SUBDOMAINS.md

@@ -0,0 +1,106 @@
+# v3 plan: managed subdomains, pricing and legal (paid)
+
+Status: **plan, nothing built.** Versions: **v2** is the current free, open-source build (the bridge, the Claude/MCP connector and the Paperclip plugin); **v3** adds this subdomain system together with pricing and the legal documents. Written from the product discussion of 2026-10-06. Items marked **DECIDED** came from the owner; items marked **PROPOSED** are recommendations awaiting a decision; **OPEN** needs an answer. Legal documents (Subdomain Terms, refund and tax wording) are **out of scope here** and will be drafted separately; section 9 lists what they must cover.
+
+## 1. Goal
+Users who cannot get a public `https://` address for their Paperclip can pay **$5 once** to get one: `https://<their-username>.<our-domain>`, tunnelled to their local Paperclip. We provision it; they run one command on their Paperclip machine. Using their own domain stays the encouraged path (see `site/docs/connect-your-paperclip.md`).
+
+## 2. Decisions (DECIDED)
+- **Price:** $5, one-time, for the subdomain name and its setup. It is not hosting and not ownership.
+- **The name is the user's username.** Usernames cannot be changed, so the subdomain label never changes. We never create domains for users, only a subdomain under our domain.
+- **Base domain may change** (today `papercliped.co`). The registry stores the **label**, not the full address; the base domain is configuration. The label stays registered to the user across any domain change.
+- **Purpose is limited:** the subdomain is an access address for the user's own Paperclip, like a handle on a platform, not a place to run a business's public site.
+- **Open to everyone at launch (not beta-only).** Paying the $5 makes the user a **pro member**: they get everything beta accounts get (the connection manager at `/manage` and the plugin) plus **management of their domain** (see 4a). Beta stays a separate, free opt-in. The manager's gate changes from `beta` to `beta OR pro`; store a `pro_since` timestamp on the account, set by the paid order.
+- **Symbols are remapped, not refused.** The username stays the user's identity; only the hostname is derived from it by replacing the symbols with hyphens (rules in 6.2).
+- **Anonymous mode does not affect the subdomain.** Anonymous only hides a user from the public live log and the operator panel (it shows an alias there). The username is still the username, so anonymous users get the same `<username>.<domain>` as everyone else.
+- **Cloudflare terms (checked by the owner, not re-verified by us):** the service is fine as long as users do not use the subdomains for actual business uses. The Subdomain Terms and the abuse checks in section 7 must enforce this. **For the legal drafting:** decide exactly where "business use" starts. Working line so far: reaching your own Paperclip through the name is allowed even if that Paperclip supports a business; using the name as a public site, API, storefront or brand, or serving anyone else's service, is not.
+- **Entry point:** a link on the connect screen ("No public address? We've got you covered.") to `/domain` on the bridge site. `/domain` offers: (1) buy a domain yourself and follow the guide, (2) use a domain you own and follow the guide, (3) let us do it ($5).
+- **Provisioner runs on the owner's home server**, using Cloudflare.
+- Legal documents are drafted later (not in this doc).
+
+## 3. Architecture
+```
+user's browser/Claude ──https──▶ Cloudflare edge ──tunnel──▶ cloudflared on user's machine ──▶ localhost:3100 (Paperclip)
+
+bridge (Render) ── job queue (Postgres) ◀── polls (outbound HTTPS only) ── home server ── Cloudflare API
+```
+- Remotely managed Cloudflare Tunnel **per user**. We set the ingress (one hostname → `http://localhost:<port>`) and the DNS record through the Cloudflare API. The user only runs the connector with their tunnel token.
+- **The home server is not in the data path.** If it is down, new orders wait; existing tunnels keep working.
+- **The Cloudflare API token lives only on the home server**, scoped to the one zone and to tunnels. It is never on the hosted bridge. The home server polls the bridge for jobs over outbound HTTPS, so no ports are opened at home.
+- A provider interface (Cloudflare now, a fake for tests) so another backend can replace it.
+
+## 4. User flow
+1. Connect screen link → `/domain` → choose "let us do it".
+2. **Register first** (see 6.4): choose a username, get the secret key, no Paperclip needed yet.
+3. Enter the local address (normally `localhost:3100`; only `localhost`/`127.0.0.1` plus a port are accepted, since we configure where the user's own connector forwards).
+4. Accept the Subdomain Terms (acceptance recorded: version + timestamp + account), pay $5 with Stripe Checkout.
+5. A signed Stripe webhook confirms the order → job queued → home server provisions → bridge stores the tunnel and shows one command to run (`cloudflared service install <token>`; exact per-OS steps to be taken from Cloudflare's docs).
+6. Back to signup with the address filled in: Connect your Paperclip → approve in Paperclip.
+7. `/manage` and the plugin show the tunnel's online status.
+
+## 4a. Pro members: domain management (in `/manage` and the plugin)
+- See the address (`label + base domain`), the tunnel status (online/offline, last seen) and the "is it Paperclip?" check result.
+- Re-show the connect command and rotate the tunnel token (invalidates the old one; needs the secret key, like other sensitive actions).
+- Change the local port the tunnel forwards to (still limited to `localhost`/`127.0.0.1` plus a port).
+- Release the name (needs the secret key; starts the quarantine; does not refund).
+- The label itself cannot be changed (it is derived from the username).
+- Plugin tokens stay unable to do secret-key actions, so rotate/release remain browser-only.
+
+## 4b. Later: slots (about two months after launch)
+Pro members will be able to buy **3 slots for $10**. Each slot is an extra subdomain, so the first one stays "the username" and the extra ones are **user-chosen labels** under the same naming rules, uniqueness and quarantine. **Design now so this is not a rewrite:** do not make `subdomains.account_id` unique (allow many per account, with a `slot` number and a per-account limit), keep the Paperclip-verification and abuse checks per subdomain, and keep pricing in config. Pro members still cannot change the label of an existing name.
+
+## 5. Data model (sketch)
+- `accounts.pro_since` (nullable timestamp; set when the paid order completes).
+- `subdomains`: `account_id`, `slot` (1 for the username label; more later), `label` (unique, lowercase), `tunnel_id`, `local_port`, `status` (`pending` | `active` | `suspended` | `released`), `terms_version`, `paid_at`, `order_id`, `created_at`, `released_at`.
+- `subdomain_jobs`: `id`, `kind` (`provision` | `suspend` | `release` | `repoint`), `payload`, `state`, `attempts`, `claimed_by`, `claimed_until`, `result`, timestamps.
+- `base_domains`: `domain`, `active`, `primary` (supports several at once during a change).
+- `label_quarantine`: `label`, `released_at`, `until`.
+- Address shown to users = `label + primary base domain`. The stored Paperclip instance URL for the account is updated centrally on a domain change.
+
+## 6. Hard problems and proposed answers
+1. **Anonymous mode (resolved).** It only hides the user from the public live log and counts, so it does not block the subdomain. Two guardrails: (a) never write a user's label or hostname into public events or the live log, so an alias can't be matched to a username (the live log and panel keep showing only the alias); (b) the order screen tells anonymous users that their subdomain is public and shows their username.
+2. **Usernames are not valid hostnames (resolved: remap).** Derivation, applied in this order: lowercase; replace every run of `.` `#` `_` with a single `-` (a run collapses so a label never contains `--`, which is reserved for `xn--`); trim leading/trailing `-` (usernames already start with a letter or digit). Example: `OG.kpnwrld` → `og-kpnwrld`, `river#2026` → `river-2026`. The derived label is stored in `subdomains.label` and never changes. Different usernames can derive the same label (`og_dev7`, `og.dev7`, `og-dev7`), so uniqueness is enforced **on the label** at claim time, first come first served. A user whose label is already held cannot buy the managed subdomain (their username cannot change): show this **before** payment, charge nothing, and point them to the own-domain guide. Also add a reserved-label list (www, api, mail, admin and similar) on top of the existing username reserved list in `src/accounts/username.ts`.
+3. **Released names can be re-taken.** Deleting an account currently frees its username. **PROPOSED:** quarantine a released label for about 12 months, and delete its DNS record and tunnel on release (prevents subdomain takeover).
+4. **Signup order.** Today an account exists only after the user approves in their Paperclip (`src/oauth/provider.ts`, account creation at the pending-approval step), which a user with no public address cannot do. A **register-first path** is needed: username + secret key without a Paperclip link, then pay, then connect. This touches the account model and the recovery-by-approval path, and is the largest piece of v3.
+5. **Changing the base domain** is not free for users: their Paperclip must accept the new hostname (a setting on their machine). Keep both hostnames live for a long overlap; keep renewing the old domain for as long as users depend on it. If the domain lapses, every user breaks at once.
+6. **Shared registrable domain.** The main domain is now `papercliped.co`, which also serves the bridge, the docs and `/manage`. Putting users at `<name>.papercliped.co` shares the domain's reputation with the bridge, and a user's site could try to set cookies for `.papercliped.co`. Mitigations that already hold: the manager and OAuth cookies are host-only (no `Domain=` attribute), so subdomains never receive them. **OPEN:** use `papercliped.co` for user names (simplest, one level so the free certificate should cover it, **unverified**) or a separate domain just for user names (safer isolation); also reserve labels that collide with our own hosts (`www`, `api`, `app`, `docs`, `status`, `mail`, `panel`).
+
+## 7. Abuse and operations
+- **One service per name:** ingress is set by us (one hostname, one local port); users cannot reconfigure it.
+- **Verify the address and port really are a Paperclip (required, at three points):**
+  1. **Before activation:** the order's job only marks the name active after the tunnel is up and `GET https://<label>.<domain>/api/health` returns the Paperclip shape (`status`, `deploymentMode`, `deploymentExposure`). Until then the name is `pending`, and unverified names are cleaned up after a short timeout.
+  2. **When the user connects:** the existing "Connect your Paperclip" step (the user approving the request inside their own Paperclip) already proves the address is a Paperclip they can sign in to. Bind the subdomain to the Paperclip user and instance id from that step; if the instance later reports a different identity, suspend and review.
+  3. **Continuously:** a scheduled check (for example every few hours, with jitter) repeats the health probe. Failing or non-Paperclip responses get a warning, then suspension; the result is shown to the user in `/manage`.
+  - **Port and routing rules:** the ingress target is only `localhost`/`127.0.0.1` plus one port set by us; users cannot add rules. Consider limiting what the public hostname forwards (for example only the Paperclip API and its UI paths) once Paperclip's required paths are confirmed.
+  - **Probe safety:** the probes go through the same SSRF-hardened fetch as the rest of the bridge, with short timeouts and a response size cap.
+- **Suspension** is one switch (job `suspend`): remove ingress/DNS, keep the label reserved.
+- Rate-limit orders and provisioning; reconcile Cloudflare state against the database on a schedule (orphaned tunnels/records are deleted).
+- Refund automatically if provisioning fails.
+- Idle reclaim: **PROPOSED** only after about 12 months with the tunnel offline, with notices.
+
+## 7a. Security hardening to do with v3
+- Home-server worker: outbound-only polling with a signed per-worker credential; jobs are idempotent and carry no secrets other than what the provider needs; the Cloudflare token is least-privilege (one zone, tunnels), stored only on the home server, rotated on a schedule.
+- Webhooks: verify the Stripe signature, reject replays, process each order once.
+- Tunnel tokens: shown only to the owner, re-showing or rotating needs the secret key, never written to logs or the public events.
+- Label rules: reserved list, impersonation/brand blocklist, quarantine, DNS and tunnel deleted on release; reconcile Cloudflare against the database on a schedule.
+- Public events and live log never contain labels or hostnames (anonymous users included).
+- Rate limits on order, claim, probe and token endpoints; audit every provisioning action.
+- Extend `docs/SECURITY.md` and its threat table for: provisioner compromise, Cloudflare token theft, label squatting/takeover, abuse of the tunnel for non-Paperclip traffic, payment fraud and refunds.
+
+## 8. Payments
+Stripe Checkout (no card data on our side); orders confirmed only by a verified webhook signature; idempotent on order id; the label is held for ~15 minutes during checkout so two people cannot pay for one name. Tax and refund handling to be decided with the legal drafting.
+
+## 9. For the later legal drafting (Subdomain Terms)
+Cover: purpose limit (access address for your own Paperclip; internal use that supports a business is fine, using the name as the public face of a business or hosting other services is not); the name is a revocable licence tied to the account, not property, not transferable, one per account; our rights to suspend/reclaim for abuse or breach and to change base domains with notice; no uptime promise (depends on Cloudflare and the user's machine); refunds only if provisioning fails; conduct and impersonation/trademark rules; what metadata we keep (hostname, tunnel status, not traffic content); acceptance recorded at checkout. Needs a lawyer's review before taking payments, including sales tax.
+
+## 10. Open questions
+1. 12-month quarantine and idle-reclaim periods?
+2. Which domain (dedicated, one level)?
+3. If a name is suspended for abuse or reclaimed, does the account keep pro? (Proposal: pro ends only if the name is suspended for breaking the terms; a released name keeps pro status.)
+4. Still to verify with Cloudflare's current docs: tunnels per account, DNS records per zone, certificate coverage for subdomains, per-OS service install steps.
+
+## 11. Phases
+1. **Provisioning core:** migration, provider interface + fake, job queue, home-server worker, claim/release/suspend, label rules.
+2. **Register-first account path** and the Stripe order flow.
+3. **Connect UX:** `/domain` page, the link on the connect screen, tunnel status in `/manage` and the plugin, docs.
+4. **Hardening:** health check, suspension, reconcile, quarantine, domain-change tooling.