papercliped 1.1.0-beta.2 → 2.2.0

package/docs/oauth.md

@@ -1,62 +1,61 @@
-# OAuth (Phase 2): connect claude.ai, Claude Desktop/mobile and ChatGPT apps
-
-With `BRIDGE_OAUTH=1` the bridge is an OAuth 2.1 authorization server **and** the protected resource (`/mcp`). Clients discover it, register themselves, and send the user through a consent page. The user signs in with **Paperclip's own approval flow**, so the bridge never handles their password.
-
-```
-client ──401 + resource_metadata──▶ bridge /mcp
-client ──DCR /register──────────────▶ bridge
-client ──/authorize (PKCE S256)─────▶ bridge ──create challenge──▶ Paperclip /api/cli-auth/challenges
-user   ── opens approvalUrl, signs in to Paperclip, approves ─────▶ Paperclip
-user   ── picks Read / Control / Admin, presses Allow ───────────▶ bridge (verifies approval, checks token)
-client ──/token (code + verifier)───▶ bridge ──▶ opaque access + rotating refresh token
-client ──/mcp  Bearer pcb_at_…──────▶ bridge ──user's board token──▶ Paperclip
-```
-
-## Setup (self-hosted)
-
-```sh
-export PAPERCLIP_API_URL=http://localhost:3100
-export PAPERCLIP_PUBLIC_URL=https://paperclip.example.com   # where the USER's browser reaches Paperclip
-export BRIDGE_OAUTH=1
-export BRIDGE_PUBLIC_URL=https://bridge.example.com          # https origin, no path
-export BRIDGE_SECRET=$(openssl rand -hex 32)                 # keep it; losing/rotating it disconnects everyone
-export BRIDGE_DATA_FILE=/var/lib/paperclip-bridge/state.json # omit = memory only (restart disconnects everyone)
-npm run start:http                                           # put TLS in front (Caddy / Cloudflare Tunnel / …)
-```
-
-- **claude.ai / Desktop / mobile:** Settings → Connectors → *Add custom connector* → `https://bridge.example.com/mcp`. Leave client ID/secret empty (Claude registers itself). Allow Anthropic's egress range `160.79.104.0/21` if you firewall.
-- **Claude Code:** `claude mcp add --transport http paperclip https://bridge.example.com/mcp`, then `/mcp` to sign in. (Or keep using stdio.)
-- **ChatGPT MCP app (developer mode):** point at the same `/mcp` URL. **[unverified]** ChatGPT's redirect hosts are in the default allow-list from secondary sources; if sign-in is refused with "redirect host … not allowed", add the host to `BRIDGE_OAUTH_REDIRECT_HOSTS`.
-- **Instances without the approval flow** (or `local_trusted` with remote clients): `BRIDGE_LOGIN=static` + `BRIDGE_TOKEN`. The consent page then asks the operator for `BRIDGE_TOKEN` and the bridge uses `PAPERCLIP_API_KEY` for upstream calls. Everyone who connects shares that one Paperclip identity.
-
-## Scopes (enforced by the bridge — Paperclip's keys have none)
-
-| Scope | Allows |
-| --- | --- |
-| `paperclip:read` | lists, reports, sync, raw GET |
-| `paperclip:control` | + pause/resume/wake/clear-error, create/update issues & goals, comments |
-| `paperclip:admin` | + decide approvals, set budgets, terminate agents, raw non-GET |
-
-Each includes the lower ones. The user picks a level on the consent page (never above what the client asked for; admin is never preselected). Tools above the grant aren't even advertised to the model, and a call is refused with `403 insufficient_scope`.
-**What scopes do not do:** limit *which company* or agent a grant can touch. The underlying Paperclip board key is user-wide, and the bridge cannot tell which company an agent/issue id belongs to. Per-company scoping needs scoped board keys upstream (Phase 3).
-
-## Security properties (each covered by a test in `test/oauth.test.ts`)
-
-- PKCE `S256` mandatory; single-use 60 s codes; **code replay revokes the tokens it produced**; `client_id`/`redirect_uri` re-checked at exchange.
-- Never redirects to an unregistered `redirect_uri`; registration only accepts allow-listed https hosts + loopback (port-agnostic per RFC 8252); public clients only.
-- Opaque tokens, only SHA-256 hashes stored; refresh tokens rotate and **reuse revokes the whole grant** and the Paperclip key (`revoke-current`).
-- The Paperclip credential is sealed with AES-256-GCM (key derived from `BRIDGE_SECRET`) and deleted on revoke; it is never returned to any client.
-- Consent page: CSRF token, CSP (`frame-ancestors 'none'`), escaped client names, loopback warning, rate limits on authorize/decision/token/register and on admin-token guesses.
-- Every tool call is audit-logged as a JSON line (tool, mutation, ok/status, grant id, client name, Paperclip user id) — never tokens or arguments.
-- Access tokens last 1 h, refresh 30 d (sliding). Operators can revoke a grant via `OAuthProvider.revokeGrant`; users via the client's "disconnect" (`/revoke`).
-
-## Single vs multi-tenant, and storage
-
-- `BRIDGE_MODE=single` (default): the bridge fronts the one Paperclip at `PAPERCLIP_API_URL`. State: a JSON file (`BRIDGE_DATA_FILE`, single process) or Postgres (`DATABASE_URL`).
-- `BRIDGE_MODE=multi`: a **public** service. The consent page first asks the user for *their* Paperclip address; the bridge validates it (https, public DNS name only — see `src/net/safe-fetch.ts`), probes `/api/health`, starts the Paperclip approval flow **on that instance**, and binds the grant to it. Requires Postgres, `BRIDGE_LOGIN=paperclip`, and no `BRIDGE_TOKEN`. Deployment: [DEPLOY-RENDER.md](DEPLOY-RENDER.md). Threat model: [SECURITY.md](SECURITY.md).
-- The Postgres store (`src/oauth/pg-store.ts`) is multi-process safe: consuming a code/refresh token and rate-limit counting are single atomic statements, and consent state lives in the database too. Migrations: `npm run migrate`.
-- FastAPI/Python: not needed — the Node service is the tested implementation; rewriting would duplicate the security-critical logic.
-
-## Not implemented yet
-
-CIMD (Client ID Metadata Documents; the new SSRF-safe fetch makes it feasible), per-company scoping (blocked on Paperclip), a grant-admin web UI (CLI exists), and Anthropic-held client credentials. DCR is the only registration path, so very busy public deployments will accumulate registered clients (idle ones are pruned after 7 days; capped at 1000).
+# OAuth (Phase 2): connect claude.ai, Claude Desktop/mobile and ChatGPT apps
+
+With `BRIDGE_OAUTH=1` the bridge is an OAuth 2.1 authorization server **and** the protected resource (`/mcp`). Clients discover it, register themselves, and send the user through a consent page. The user signs in with **Paperclip's own approval flow**, so the bridge never handles their password.
+
+```
+client ──401 + resource_metadata──▶ bridge /mcp
+client ──DCR /register──────────────▶ bridge
+client ──/authorize (PKCE S256)─────▶ bridge ──create challenge──▶ Paperclip /api/cli-auth/challenges
+user   ── opens approvalUrl, signs in to Paperclip, approves ─────▶ Paperclip
+user   ── picks Read only / Full control, presses Allow ────────▶ bridge (verifies approval, checks token)
+client ──/token (code + verifier)───▶ bridge ──▶ opaque access + rotating refresh token
+client ──/mcp  Bearer pcb_at_…──────▶ bridge ──user's board token──▶ Paperclip
+```
+
+## Setup (self-hosted)
+
+```sh
+export PAPERCLIP_API_URL=http://localhost:3100
+export PAPERCLIP_PUBLIC_URL=https://paperclip.example.com   # where the USER's browser reaches Paperclip
+export BRIDGE_OAUTH=1
+export BRIDGE_PUBLIC_URL=https://bridge.example.com          # https origin, no path
+export BRIDGE_SECRET=$(openssl rand -hex 32)                 # keep it; losing/rotating it disconnects everyone
+export BRIDGE_DATA_FILE=/var/lib/paperclip-bridge/state.json # omit = memory only (restart disconnects everyone)
+npm run start:http                                           # put TLS in front (Caddy / Cloudflare Tunnel / …)
+```
+
+- **claude.ai / Desktop / mobile:** Settings → Connectors → *Add custom connector* → `https://bridge.example.com/mcp`. Leave client ID/secret empty (Claude registers itself). Allow Anthropic's egress range `160.79.104.0/21` if you firewall.
+- **Claude Code:** `claude mcp add --transport http paperclip https://bridge.example.com/mcp`, then `/mcp` to sign in. (Or keep using stdio.)
+- **ChatGPT MCP app (developer mode):** point at the same `/mcp` URL. **[unverified]** ChatGPT's redirect hosts are in the default allow-list from secondary sources; if sign-in is refused with "redirect host … not allowed", add the host to `BRIDGE_OAUTH_REDIRECT_HOSTS`.
+- **Instances without the approval flow** (or `local_trusted` with remote clients): `BRIDGE_LOGIN=static` + `BRIDGE_TOKEN`. The consent page then asks the operator for `BRIDGE_TOKEN` and the bridge uses `PAPERCLIP_API_KEY` for upstream calls. Everyone who connects shares that one Paperclip identity.
+
+## Scopes (enforced by the bridge — Paperclip's keys have none)
+
+| Scope | Allows |
+| --- | --- |
+| `paperclip:read` | lists, reports, sync, raw GET |
+| `paperclip:control` | every tool: + pause/resume/wake/terminate, issues & goals, comments, approvals, budgets, raw non-GET |
+
+Control includes read. The user picks a level on the consent page (Read only is preselected unless the app asked for control). The retired `paperclip:admin` scope is accepted as an alias for `paperclip:control`. Tools above the grant aren't even advertised to the model, and a call is refused with `403 insufficient_scope`.
+**What scopes do not do:** limit *which company* or agent a grant can touch. The underlying Paperclip board key is user-wide, and the bridge cannot tell which company an agent/issue id belongs to. Per-company scoping needs scoped board keys upstream (Phase 3).
+
+## Security properties (each covered by a test in `test/oauth.test.ts`)
+
+- PKCE `S256` mandatory; single-use 60 s codes; **code replay revokes the tokens it produced**; `client_id`/`redirect_uri` re-checked at exchange.
+- Never redirects to an unregistered `redirect_uri`; registration only accepts allow-listed https hosts + loopback (port-agnostic per RFC 8252); public clients only.
+- Opaque tokens, only SHA-256 hashes stored; refresh tokens rotate and **reuse revokes the whole grant** and the Paperclip key (`revoke-current`).
+- The Paperclip credential is sealed with AES-256-GCM (key derived from `BRIDGE_SECRET`) and deleted on revoke; it is never returned to any client.
+- Consent page: CSRF token, CSP (`frame-ancestors 'none'`), escaped client names, loopback warning, rate limits on authorize/decision/token/register and on admin-token guesses.
+- Every tool call is audit-logged as a JSON line (tool, mutation, ok/status, grant id, client name, Paperclip user id) — never tokens or arguments.
+- Access tokens last 1 h, refresh 30 d (sliding). Operators can revoke a grant via `OAuthProvider.revokeGrant`; users via the client's "disconnect" (`/revoke`).
+
+## Single vs multi-tenant, and storage
+
+- `BRIDGE_MODE=single` (default): the bridge fronts the one Paperclip at `PAPERCLIP_API_URL`. State: a JSON file (`BRIDGE_DATA_FILE`, single process) or Postgres (`DATABASE_URL`).
+- `BRIDGE_MODE=multi`: a **public** service. The consent page first asks the user for *their* Paperclip address; the bridge validates it (https, public DNS name only — see `src/net/safe-fetch.ts`), probes `/api/health`, starts the Paperclip approval flow **on that instance**, and binds the grant to it. Requires Postgres, `BRIDGE_LOGIN=paperclip`, and no `BRIDGE_TOKEN`. Deployment: [DEPLOY-RENDER.md](DEPLOY-RENDER.md). Threat model: [SECURITY.md](SECURITY.md).
+- The Postgres store (`src/oauth/pg-store.ts`) is multi-process safe: consuming a code/refresh token and rate-limit counting are single atomic statements, and consent state lives in the database too. Migrations: `npm run migrate`.
+- FastAPI/Python: not needed — the Node service is the tested implementation; rewriting would duplicate the security-critical logic.
+
+## Not implemented yet
+
+CIMD (Client ID Metadata Documents; the new SSRF-safe fetch makes it feasible), per-company scoping (blocked on Paperclip), a grant-admin web UI (CLI exists), and Anthropic-held client credentials. DCR is the only registration path, so very busy public deployments will accumulate registered clients (idle ones are pruned after 7 days; capped at 1000).

package/docs/supabase-schema.sql

@@ -267,6 +267,13 @@ end $$;
 -- Beta opt-in: accounts that join the beta get the connection manager (/manage) and its management API.
 alter table bridge.accounts add column if not exists beta boolean not null default false;
 
+-- ───── 006_two_levels.sql ─────
+-- Two access levels: Read only and Full control. The old third level (paperclip:admin) is folded into Full control,
+-- which now covers every tool. Existing grants keep working; this only tidies the stored scope lists.
+update bridge.grants
+   set scopes = array(select distinct s from unnest(array_replace(scopes, 'paperclip:admin', 'paperclip:control')) as s order by s desc)
+ where 'paperclip:admin' = any(scopes);
+
 -- ───── migration bookkeeping ─────
 create table if not exists bridge.schema_migrations (version text primary key, applied_at timestamptz not null default now());
 alter table bridge.schema_migrations enable row level security;
@@ -276,6 +283,6 @@ do $$ declare r text; begin
     if exists (select 1 from pg_roles where rolname = r) then execute format('revoke all on bridge.schema_migrations from %I', r); end if;
   end loop;
 end $$;
-insert into bridge.schema_migrations (version) values ('001_init.sql'), ('002_audit.sql'), ('003_accounts.sql'), ('004_privacy_panel.sql'), ('005_beta.sql') on conflict (version) do nothing;
+insert into bridge.schema_migrations (version) values ('001_init.sql'), ('002_audit.sql'), ('003_accounts.sql'), ('004_privacy_panel.sql'), ('005_beta.sql'), ('006_two_levels.sql') on conflict (version) do nothing;
 
 commit;

package/migrations/001_init.sql

@@ -1,84 +1,84 @@
--- Paperclip Bridge schema. Run with a direct/session connection (see docs/DEPLOY-RENDER.md).
--- Everything lives in its own schema, which Supabase does NOT expose through its REST/GraphQL Data API,
--- and is additionally locked down with RLS (no policies = deny) and revoked grants, so the public `anon`
--- key can never read it. The bridge connects as a privileged role over a normal Postgres connection.
-
-create schema if not exists bridge;
-
-create table if not exists bridge.clients (
-  id           text primary key,
-  name         text   not null,
-  redirect_uris text[] not null,
-  created_at   bigint not null,
-  last_used_at bigint not null
-);
-
-create table if not exists bridge.grants (
-  id                text primary key,
-  client_id         text   not null,
-  client_name       text   not null,
-  user_id           text,
-  scopes            text[] not null,
-  resource          text   not null,
-  instance_url      text,
-  sealed_credential text,           -- AES-256-GCM sealed in the app; the key never touches the database
-  created_at        bigint not null,
-  last_used_at      bigint not null,
-  revoked           boolean not null default false
-);
-create index if not exists grants_idle_idx on bridge.grants (last_used_at) where not revoked;
-
-create table if not exists bridge.tokens (
-  hash       text primary key,       -- sha256 of the raw token; raw tokens are never stored
-  kind       text   not null check (kind in ('access', 'refresh')),
-  grant_id   text   not null,
-  expires_at bigint not null,
-  consumed   boolean not null default false
-);
-create index if not exists tokens_grant_idx on bridge.tokens (grant_id);
-create index if not exists tokens_expiry_idx on bridge.tokens (expires_at);
-
-create table if not exists bridge.pending (
-  rid        text primary key,
-  data       jsonb  not null,        -- sensitive parts already sealed by the app
-  expires_at bigint not null
-);
-create index if not exists pending_expiry_idx on bridge.pending (expires_at);
-
-create table if not exists bridge.codes (
-  hash       text primary key,
-  data       jsonb  not null,
-  expires_at bigint not null,
-  used       boolean not null default false,
-  grant_id   text
-);
-create index if not exists codes_expiry_idx on bridge.codes (expires_at);
-
-create table if not exists bridge.rate_limits (
-  key      text primary key,
-  n        integer not null,
-  reset_at bigint  not null
-);
-
--- Defence in depth: deny by default for every non-owner role.
-alter table bridge.clients     enable row level security;
-alter table bridge.grants      enable row level security;
-alter table bridge.tokens      enable row level security;
-alter table bridge.pending     enable row level security;
-alter table bridge.codes       enable row level security;
-alter table bridge.rate_limits enable row level security;
-
-revoke all on schema bridge from public;
-revoke all on all tables in schema bridge from public;
-
-do $$
-declare r text;
-begin
-  foreach r in array array['anon', 'authenticated'] loop
-    if exists (select 1 from pg_roles where rolname = r) then
-      execute format('revoke all on schema bridge from %I', r);
-      execute format('revoke all on all tables in schema bridge from %I', r);
-      execute format('alter default privileges in schema bridge revoke all on tables from %I', r);
-    end if;
-  end loop;
-end $$;
+-- Paperclip Bridge schema. Run with a direct/session connection (see docs/DEPLOY-RENDER.md).
+-- Everything lives in its own schema, which Supabase does NOT expose through its REST/GraphQL Data API,
+-- and is additionally locked down with RLS (no policies = deny) and revoked grants, so the public `anon`
+-- key can never read it. The bridge connects as a privileged role over a normal Postgres connection.
+
+create schema if not exists bridge;
+
+create table if not exists bridge.clients (
+  id           text primary key,
+  name         text   not null,
+  redirect_uris text[] not null,
+  created_at   bigint not null,
+  last_used_at bigint not null
+);
+
+create table if not exists bridge.grants (
+  id                text primary key,
+  client_id         text   not null,
+  client_name       text   not null,
+  user_id           text,
+  scopes            text[] not null,
+  resource          text   not null,
+  instance_url      text,
+  sealed_credential text,           -- AES-256-GCM sealed in the app; the key never touches the database
+  created_at        bigint not null,
+  last_used_at      bigint not null,
+  revoked           boolean not null default false
+);
+create index if not exists grants_idle_idx on bridge.grants (last_used_at) where not revoked;
+
+create table if not exists bridge.tokens (
+  hash       text primary key,       -- sha256 of the raw token; raw tokens are never stored
+  kind       text   not null check (kind in ('access', 'refresh')),
+  grant_id   text   not null,
+  expires_at bigint not null,
+  consumed   boolean not null default false
+);
+create index if not exists tokens_grant_idx on bridge.tokens (grant_id);
+create index if not exists tokens_expiry_idx on bridge.tokens (expires_at);
+
+create table if not exists bridge.pending (
+  rid        text primary key,
+  data       jsonb  not null,        -- sensitive parts already sealed by the app
+  expires_at bigint not null
+);
+create index if not exists pending_expiry_idx on bridge.pending (expires_at);
+
+create table if not exists bridge.codes (
+  hash       text primary key,
+  data       jsonb  not null,
+  expires_at bigint not null,
+  used       boolean not null default false,
+  grant_id   text
+);
+create index if not exists codes_expiry_idx on bridge.codes (expires_at);
+
+create table if not exists bridge.rate_limits (
+  key      text primary key,
+  n        integer not null,
+  reset_at bigint  not null
+);
+
+-- Defence in depth: deny by default for every non-owner role.
+alter table bridge.clients     enable row level security;
+alter table bridge.grants      enable row level security;
+alter table bridge.tokens      enable row level security;
+alter table bridge.pending     enable row level security;
+alter table bridge.codes       enable row level security;
+alter table bridge.rate_limits enable row level security;
+
+revoke all on schema bridge from public;
+revoke all on all tables in schema bridge from public;
+
+do $$
+declare r text;
+begin
+  foreach r in array array['anon', 'authenticated'] loop
+    if exists (select 1 from pg_roles where rolname = r) then
+      execute format('revoke all on schema bridge from %I', r);
+      execute format('revoke all on all tables in schema bridge from %I', r);
+      execute format('alter default privileges in schema bridge revoke all on tables from %I', r);
+    end if;
+  end loop;
+end $$;

package/migrations/002_audit.sql

@@ -1,41 +1,41 @@
--- Audit & latency telemetry. One row per tool call and per OAuth/MCP HTTP request.
--- NEVER contains tool arguments, tool results, tokens or credentials: only who/what/how-long/outcome.
--- Retention is enforced by the app (BRIDGE_AUDIT_RETENTION_DAYS, default 30); rows hold the user id and tenant host, so keep it short.
-
-create table if not exists bridge.audit_events (
-  id             bigint generated always as identity primary key,
-  ts             bigint  not null,                      -- ms since epoch (UTC)
-  node           text    not null,                      -- which bridge instance wrote it
-  kind           text    not null check (kind in ('tool', 'http')),
-  name           text    not null,                      -- tool name, or route group such as 'oauth.token'
-  mutation       boolean not null default false,
-  ok             boolean not null,
-  status         integer,
-  error_class    text,                                  -- invalid_input | insufficient_scope | read_only | upstream_4xx | upstream_5xx | upstream_unreachable | rate_limited | unauthorized | internal
-  total_ms       integer not null,                      -- end to end inside the bridge
-  upstream_ms    integer,                               -- of which: waiting on the user's Paperclip (union of parallel requests)
-  upstream_calls integer,
-  scope          text,                                  -- scope the call required
-  grant_id       text,
-  client         text,
-  instance       text,                                  -- tenant Paperclip host
-  user_id        text
-);
-
-create index if not exists audit_ts_idx          on bridge.audit_events (ts desc);
-create index if not exists audit_kind_name_idx   on bridge.audit_events (kind, name, ts desc);
-create index if not exists audit_instance_idx    on bridge.audit_events (instance, ts desc) where instance is not null;
-create index if not exists audit_errors_idx      on bridge.audit_events (ts desc) where not ok;
-
-alter table bridge.audit_events enable row level security;
-revoke all on bridge.audit_events from public;
-
-do $$
-declare r text;
-begin
-  foreach r in array array['anon', 'authenticated'] loop
-    if exists (select 1 from pg_roles where rolname = r) then
-      execute format('revoke all on bridge.audit_events from %I', r);
-    end if;
-  end loop;
-end $$;
+-- Audit & latency telemetry. One row per tool call and per OAuth/MCP HTTP request.
+-- NEVER contains tool arguments, tool results, tokens or credentials: only who/what/how-long/outcome.
+-- Retention is enforced by the app (BRIDGE_AUDIT_RETENTION_DAYS, default 30); rows hold the user id and tenant host, so keep it short.
+
+create table if not exists bridge.audit_events (
+  id             bigint generated always as identity primary key,
+  ts             bigint  not null,                      -- ms since epoch (UTC)
+  node           text    not null,                      -- which bridge instance wrote it
+  kind           text    not null check (kind in ('tool', 'http')),
+  name           text    not null,                      -- tool name, or route group such as 'oauth.token'
+  mutation       boolean not null default false,
+  ok             boolean not null,
+  status         integer,
+  error_class    text,                                  -- invalid_input | insufficient_scope | read_only | upstream_4xx | upstream_5xx | upstream_unreachable | rate_limited | unauthorized | internal
+  total_ms       integer not null,                      -- end to end inside the bridge
+  upstream_ms    integer,                               -- of which: waiting on the user's Paperclip (union of parallel requests)
+  upstream_calls integer,
+  scope          text,                                  -- scope the call required
+  grant_id       text,
+  client         text,
+  instance       text,                                  -- tenant Paperclip host
+  user_id        text
+);
+
+create index if not exists audit_ts_idx          on bridge.audit_events (ts desc);
+create index if not exists audit_kind_name_idx   on bridge.audit_events (kind, name, ts desc);
+create index if not exists audit_instance_idx    on bridge.audit_events (instance, ts desc) where instance is not null;
+create index if not exists audit_errors_idx      on bridge.audit_events (ts desc) where not ok;
+
+alter table bridge.audit_events enable row level security;
+revoke all on bridge.audit_events from public;
+
+do $$
+declare r text;
+begin
+  foreach r in array array['anon', 'authenticated'] loop
+    if exists (select 1 from pg_roles where rolname = r) then
+      execute format('revoke all on bridge.audit_events from %I', r);
+    end if;
+  end loop;
+end $$;

package/migrations/003_accounts.sql

@@ -1,66 +1,66 @@
--- Papercliped accounts: username + secret key, one stored Paperclip connection per account, and the user event log.
--- Nothing here stores a plaintext secret: `secret_hash` is a salted scrypt hash, `sealed_credential` is AES-GCM sealed in the app.
-
-create table if not exists bridge.accounts (
-  id            text   primary key,
-  username      text   not null,               -- as typed; shown only in the operator's logs
-  username_key  text   not null,               -- lowercased; unique
-  secret_hash   text   not null,               -- scrypt$N$r$p$salt$hash of the generated secret key
-  created_at    bigint not null,
-  last_login_at bigint,
-  disabled      boolean not null default false
-);
-create unique index if not exists accounts_username_key_idx on bridge.accounts (username_key);
-
--- One connection per account. A given Paperclip identity (instance + user id) can belong to only one account.
-create table if not exists bridge.account_links (
-  account_id         text   primary key references bridge.accounts (id) on delete cascade,
-  instance_url       text   not null,
-  paperclip_user_id  text,
-  sealed_credential  text,                      -- null once dropped (idle expiry / disconnect)
-  created_at         bigint not null,
-  connected_at       bigint not null,
-  last_used_at       bigint not null
-);
-create unique index if not exists account_links_identity_idx on bridge.account_links (instance_url, paperclip_user_id) where paperclip_user_id is not null;
-create index if not exists account_links_idle_idx on bridge.account_links (last_used_at) where sealed_credential is not null;
-
--- The community log: joined / left / updated / login / ... (see src/accounts/types.ts). `detail` is a short non-sensitive reason.
-create table if not exists bridge.user_events (
-  id          bigint generated always as identity primary key,
-  ts          bigint not null,
-  account_id  text,
-  username    text,
-  kind        text   not null,
-  detail      text
-);
-create index if not exists user_events_ts_idx   on bridge.user_events (ts desc);
-create index if not exists user_events_kind_idx on bridge.user_events (kind, ts desc);
-
--- A row the app rewrites on a timer so a free-tier Supabase project always sees recent write activity.
-create table if not exists bridge.heartbeat (
-  id integer primary key,
-  at bigint  not null
-);
-
-alter table bridge.grants       add column if not exists account_id text;
-alter table bridge.grants       add column if not exists username   text;
-alter table bridge.audit_events add column if not exists username   text;
-create index if not exists grants_account_idx on bridge.grants (account_id) where not revoked;
-create index if not exists audit_username_idx on bridge.audit_events (username, ts desc) where username is not null;
-
-alter table bridge.accounts      enable row level security;
-alter table bridge.account_links enable row level security;
-alter table bridge.user_events   enable row level security;
-alter table bridge.heartbeat     enable row level security;
-revoke all on bridge.accounts, bridge.account_links, bridge.user_events, bridge.heartbeat from public;
-
-do $$
-declare r text;
-begin
-  foreach r in array array['anon', 'authenticated'] loop
-    if exists (select 1 from pg_roles where rolname = r) then
-      execute format('revoke all on bridge.accounts, bridge.account_links, bridge.user_events, bridge.heartbeat from %I', r);
-    end if;
-  end loop;
-end $$;
+-- Papercliped accounts: username + secret key, one stored Paperclip connection per account, and the user event log.
+-- Nothing here stores a plaintext secret: `secret_hash` is a salted scrypt hash, `sealed_credential` is AES-GCM sealed in the app.
+
+create table if not exists bridge.accounts (
+  id            text   primary key,
+  username      text   not null,               -- as typed; shown only in the operator's logs
+  username_key  text   not null,               -- lowercased; unique
+  secret_hash   text   not null,               -- scrypt$N$r$p$salt$hash of the generated secret key
+  created_at    bigint not null,
+  last_login_at bigint,
+  disabled      boolean not null default false
+);
+create unique index if not exists accounts_username_key_idx on bridge.accounts (username_key);
+
+-- One connection per account. A given Paperclip identity (instance + user id) can belong to only one account.
+create table if not exists bridge.account_links (
+  account_id         text   primary key references bridge.accounts (id) on delete cascade,
+  instance_url       text   not null,
+  paperclip_user_id  text,
+  sealed_credential  text,                      -- null once dropped (idle expiry / disconnect)
+  created_at         bigint not null,
+  connected_at       bigint not null,
+  last_used_at       bigint not null
+);
+create unique index if not exists account_links_identity_idx on bridge.account_links (instance_url, paperclip_user_id) where paperclip_user_id is not null;
+create index if not exists account_links_idle_idx on bridge.account_links (last_used_at) where sealed_credential is not null;
+
+-- The community log: joined / left / updated / login / ... (see src/accounts/types.ts). `detail` is a short non-sensitive reason.
+create table if not exists bridge.user_events (
+  id          bigint generated always as identity primary key,
+  ts          bigint not null,
+  account_id  text,
+  username    text,
+  kind        text   not null,
+  detail      text
+);
+create index if not exists user_events_ts_idx   on bridge.user_events (ts desc);
+create index if not exists user_events_kind_idx on bridge.user_events (kind, ts desc);
+
+-- A row the app rewrites on a timer so a free-tier Supabase project always sees recent write activity.
+create table if not exists bridge.heartbeat (
+  id integer primary key,
+  at bigint  not null
+);
+
+alter table bridge.grants       add column if not exists account_id text;
+alter table bridge.grants       add column if not exists username   text;
+alter table bridge.audit_events add column if not exists username   text;
+create index if not exists grants_account_idx on bridge.grants (account_id) where not revoked;
+create index if not exists audit_username_idx on bridge.audit_events (username, ts desc) where username is not null;
+
+alter table bridge.accounts      enable row level security;
+alter table bridge.account_links enable row level security;
+alter table bridge.user_events   enable row level security;
+alter table bridge.heartbeat     enable row level security;
+revoke all on bridge.accounts, bridge.account_links, bridge.user_events, bridge.heartbeat from public;
+
+do $$
+declare r text;
+begin
+  foreach r in array array['anon', 'authenticated'] loop
+    if exists (select 1 from pg_roles where rolname = r) then
+      execute format('revoke all on bridge.accounts, bridge.account_links, bridge.user_events, bridge.heartbeat from %I', r);
+    end if;
+  end loop;
+end $$;