Skip to content

Security: copper-browser/copper-cloud

Security

docs/security.md

Security

Threat model (v1)

copper-cloud is a small self-hosted service on the public internet holding users' browsing data. Goals:

  1. Strangers on the internet cannot use the API at all (gate credential: instance key or a personal access key), nor read traffic (TLS). In directory mode the admin decides, per person, who may connect. With single sign-on the admin decides per email domain instead: whoever the company's identity provider vouches for gets in.
  2. Users of the same instance cannot see each other's data (every query is user-scoped).
  3. A stolen database dump / disk snapshot without the master key reveals no synced content.
  4. No secrets in logs.

Out of scope for v1: end-to-end encryption (the server can decrypt to serve clients), a compromised server process or host, key rotation, multi-instance HA.

Layers

Gate: instance key or access key

Every /v1 request except POST /v1/auth/pair (and the other ungated routes: single sign-on, POST /v1/agents/pair and the device agent relay's /v1/agent/*, each with its own credential) must carry X-Copper-Instance. Without an accepted credential the server answers 401 {"error":"instance_key"} for every /v1 path — unknown routes included — and never reads request bodies. Two kinds of credential:

  • Instance key — one shared secret per instance, ≥ 32 characters of [A-Za-z0-9-_.~] (generated: base64url of 32 random bytes), travelling inside the link code's URL fragment. The presented and configured keys are SHA-256'd and compared in constant time, so neither content nor length leaks. Accepted only while access_mode = open.
  • Access key — per person, minted by an admin in the portal (or by pairing, below): ck_ + 32 random bytes base64url. Only SHA-256(key) is stored (access_keys.key_sha256, unique index); the plaintext is shown once. Accepted in both modes while not revoked and not expired; revocation is immediate (keys are looked up per request, not cached). Optional email binding (signup must use that email) and max_uses (accounts that may be created with it). last_used_at is written at most once a minute.

access_mode (server_settings) is open or directory. Fresh installs (install.sh / Terraform) start in directory, so a leaked link code of one person can be revoked without re-keying everyone; instances that predate access keys stay open. The mode is cached in memory for 5 seconds (one query per 5 s) — a mode switch takes effect within that window (immediately on the server that handled the admin's change). If the database cannot be read and nothing is cached the gate fails closed (500).

Which credential a request used is attached as a GateIdentity request extension; signup uses it (access key → permitted, email binding enforced, one use consumed atomically in the signup transaction; instance key → allow_signup; directory mode without a key → 403).

Pairing codes

A signed-in Copper can mint a single-use code (cp_ + 24 random bytes base64url, SHA-256 stored, 10-minute TTL, ≤ 20 active per user) that signs another Copper into the same account. POST /v1/auth/pair is gate-free (like the SSO routes and POST /v1/agents/pair): the code is the credential. It is rate limited with /v1/auth/*, looked up by hash (an indexed equality on a 256-bit digest — no timing oracle on the code), and consumed with UPDATE … WHERE used_at IS NULL AND expires_at > now() RETURNING inside the transaction that creates the session, so two concurrent redemptions cannot both succeed. The response carries the gate credential the new device must use: the instance key in open mode, or — in directory mode — a fresh access key bound to the user's email (label "<device> via pairing"), so every paired device is individually revocable. Codes are revocable by their owner and by admins; used/expired rows are purged after a day. A code minted by agent pairing is bound to one device id (pairing_codes.device_id): redemption signs in that device, so a code stolen from the agent's side cannot sign in some other device id.

Admin accounts and the admin API

Admins (admins) are separate from users: they manage the instance from the web portal and /admin/api/*; they have no synced data. The admin API is not behind the instance gate.

  • Passwords: Argon2id like user passwords; login failures are constant-work and identical for unknown email vs wrong password. Login is rate limited per IP (own bucket, limits.auth_per_minute).
  • Sessions: cookie cc_admin = 32 random bytes base64url, SHA-256 stored, fixed 7-day lifetime, HttpOnly; SameSite=Strict; Path=/admin and Secure (omitted only with tls.mode = "off"). Changing the password revokes the admin's other sessions; admin reset-admin-password revokes all.
  • CSRF: SameSite=Strict plus a required X-Requested-With: copper-cloud-portal header on every non-GET request (a cross-site form or fetch cannot add it without a CORS preflight, which the server never grants). Missing → 403 {"error":"csrf"}.
  • Every admin mutation (including login/logout) is written to admin_audit (admin, action, target id, non-secret detail, time).
  • Admin responses are Cache-Control: no-store. Access-key plaintext appears only in the POST access-keys response; lists never contain secrets. Canvas content is never exposed.
  • The portal's static files are served with a strict CSP (default-src 'self', script-src 'self' + SHA-256 hashes of the export's own inline bootstrap scripts, computed per file at serve time; connect-src 'self'; frame-ancestors 'none'), nosniff, Referrer-Policy: same-origin and X-Frame-Options: DENY.
  • Initial credentials: install.sh generates a 24-character password (printed once, saved to /etc/copper-cloud/admin-credentials, 0600 root); Terraform generates it into SSM SecureString /copper-cloud/<name>/admin-password. Change it after first login.

TLS

Always on, except tls.mode = "off", which is only for deployments behind a TLS-terminating proxy (and should be paired with trust_proxy = true).

  • self-signed: the link code carries fp=<sha256 hex of the leaf certificate DER>. Clients must pin exactly that certificate (compare the presented leaf's DER hash; do not fall back to system trust). The certificate is valid 10 years so pins do not silently break; tls-init --force rotates it and every Copper must then re-link with the new code.
  • acme: a publicly trusted Let's Encrypt certificate; the link code has no fp and clients use normal WebPKI validation.
  • acme + fallback_self_signed (hybrid): the ACME certificate for clients that ask for tls.domain by SNI; the existing self-signed certificate (never regenerated) for everyone else (IP literal, no SNI), so Coppers pinned to it keep working. Link codes and pairing links keep the pinned public_url + fp. SSO join links, /start and agent-pairing links use the domain without fp.

rustls only (ring provider), TLS 1.2+ with rustls' safe defaults; HTTP/2 or HTTP/1.1 via ALPN.

Accounts and sessions

  • Passwords: Argon2id, m = 64 MiB, t = 3, p = 1, random salt, PHC string. ≥ 10 characters. Hashing runs on the blocking pool with bounded concurrency (memory stays bounded under a login flood).
  • Login failures are indistinguishable for unknown email vs wrong password, and do the same Argon2 work (a dummy hash is verified when the user does not exist).
  • Session tokens: 32 bytes from the OS CSPRNG, base64url. The database stores only SHA-256(token), so a DB leak does not yield usable sessions. Sliding 90-day expiry; expired rows are purged hourly. Password change revokes all other sessions; admin reset-password, admin disable-user and the portal's disable / reset-password revoke all (disable also disconnects the user's live canvas peers on the linked Canvas Cloud: at once from the portal, within 10 minutes — the reconcile loop — from the CLI).
  • Rate limiting: limits.auth_per_minute (10) per client IP on /v1/auth/* (signup, login, logout, password, pair; GET /v1/auth/me and pairing-code management are exempt because a 256-bit bearer token cannot be brute-forced and clients use them as status probes). IPv6 clients are keyed by /64. Admin login has a separate bucket of the same size. X-Forwarded-For is honored only with trust_proxy = true.
  • Signup: with the instance key (open mode) it follows allow_signup (admin disable-signup / the portal restricts it to the very first user, after which the admin creates accounts); with an access key it is permitted (subject to the key's email binding and max_uses).

Authorization

Every query that touches user data is filtered by the authenticated user_id (docs, history, devices, sessions); that includes history deletes, which also refuse unknown query parameters and malformed bodies so a typo cannot widen a delete to all of the caller's history. tabs:<device_id> docs are writable only by the owning device. Canvas access is checked per membership by the linked Canvas Cloud, for the Copper user that copper-cloud names in X-Canvas-User after verifying the session (see Canvas link). Share-link preview and join routes require an active session; disabled accounts have no valid sessions and cannot use links. Link joins are serialized on the link row, use the membership primary key for idempotency, and never replace an existing owner role.

GET /v1/people is intentionally a team-server directory: any signed-in user of an instance can list its active users (excluding themselves), optionally filtering by a case-insensitive substring of display name or email. Deleted accounts are absent and disabled accounts are excluded.

Share-link tokens

A random 32-byte secret is generated for every canvas share link, but only its SHA-256 digest is stored. The plaintext is returned only from link creation, never from list/preview responses and never in logs. Owners can revoke one or all links; deleting a canvas cascades its links. Email invite tokens follow the same digest-only storage rule. Since 0.11.0 both are stored by Canvas Cloud (the migration copies the digests, so existing tokens keep working).

Canvas link

Since 0.11.0 canvases are stored and served by a linked Canvas Cloud; copper-cloud proxies to it with one app key (canvas-link.md › Security model):

  • Coppers authenticate only to copper-cloud. Their session token, X-Copper-Instance and cookies are never forwarded; copper-cloud adds Authorization: Bearer <app key> and X-Canvas-User: <Copper user id>, which Canvas Cloud trusts for this app's users.
  • Whoever holds the app key can act as every Copper user on Canvas Cloud (read, edit and delete their canvases) and create, change or delete this app's users. It is stored in canvas_link.app_key_sealed under the KEK envelope below (AAD canvas_link:app_key), never returned by the admin API, shown only as its last four characters, read by the CLI from a file or stdin (never argv), and kept out of logs and audit details.
  • TLS to Canvas Cloud is verified against the web PKI (bundled Mozilla roots) or pinned to one leaf certificate SHA-256; plain http:// is accepted only for a loopback address.
  • A Canvas Cloud 401 is turned into 502 canvas_upstream, so an app-key problem never signs Coppers out.

Cloud-wide intelligence keys

An admin can store one Jev (TypeSafe) key and one LLM router (LiteLLM) key per instance; every signed-in user receives them in clear from GET /v1/intelligence. This is deliberate: the keys are shared credentials of the instance, so anyone who can sign in can use (and copy) them. Scope them accordingly — prefer a dedicated LiteLLM virtual key with its own budget per instance over a personal key, and rotate by setting a new key (Coppers pick it up on their next fetch; updated_at changes).

  • Storage: intelligence_settings (singleton row). A random 32-byte data key is wrapped by the KEK (data_key_wrapped); each API key is AES-256-GCM sealed under it with AAD intelligence:jev / intelligence:router. Endpoint, model and URL are plaintext, as is the org agent round budget (agent_max_turns, not a secret).
  • Reads require the gate credential and a valid user session (disabled users have none). The response is Cache-Control: no-store. The admin toggle enabled = false withholds the keys without deleting them.
  • Admin surfaces are write-only: the admin API, portal and copper-cloud intelligence show only ever show the last four characters (none for keys under 12 characters).
  • The CLI reads keys from files or stdin (--jev-key-file F, --router-key-file -), never from argv, so they stay out of shell history and ps.
  • Every change (intelligence.update / intelligence.clear, admin or CLI) and user reads (intelligence.read, at most once per user per hour) are written to admin_audit; audit details and logs never contain key material.

Encryption at rest

master_key (config, 32 B) ──HKDF-SHA256(salt "copper-cloud", info "copper-cloud/v1/key-encryption-key")──▶ KEK
KEK ──AES-256-GCM(aad "copper-cloud/v1/wrapped-key")──▶ users.data_key_wrapped, canvases.doc_key_wrapped,
                                                        intelligence_settings.data_key_wrapped,
                                                        canvas_link.data_key_wrapped
data_key ──AES-256-GCM(nonce 12 B random, aad "<user_id>:<domain>")──▶ sync_docs.payload, history.payload
intelligence data_key ──AES-256-GCM(aad "intelligence:jev" | "intelligence:router")──▶ jev_key_sealed, router_key_sealed
canvas_link data_key ──AES-256-GCM(aad "canvas_link:app_key")──▶ canvas_link.app_key_sealed
legacy (≤ 0.8) canvas doc_key ──AES-256-GCM(aad canvas id)──▶ canvas_updates."update", canvas_snapshots.state (incl. chat)
legacy (≤ 0.8) canvas doc_key ──AES-256-GCM(aad "copper-cloud/v1/mention:" ‖ mention id)──▶ canvas_mentions.excerpt_sealed

The legacy canvas rows are only read (by canvas migrate); new canvas content is encrypted by Canvas Cloud under its own master_key.

  • Sealed blob layout: nonce(12) ‖ ciphertext ‖ tag(16).
  • AAD binds each blob to its user and domain: copying a row to another user or domain makes it fail authentication.
  • The master key never leaves the config file / process memory; the derived KEK cipher is held in memory, raw key bytes are zeroized after derivation.
  • What is not encrypted: emails, display names, device names, timestamps, sizes, versions, domain names, history visited_at, canvas names, chat message ids and who mentioned whom. These are needed for indexing/ordering.
  • The server never inspects history to decide what to delete. DELETE /v1/sync/history and admin history delete select rows only by metadata stored in the clear — seq, visited_at, device — and never open a payload or unwrap a data key. Picking individual entries (a site, a page) is the user's choice and is made on their client, which sends the chosen seqs; an admin can only delete wholesale by time window and/or device. Logs carry counts only; the history_deleted event (to the user's own devices) carries the metadata filter or a seq count, never urls or hosts.

Back up the master key separately from database backups. Losing it makes all synced data unrecoverable; leaking it together with a DB dump exposes everything.

Key rotation (out of scope for v1)

There is no online rotation. Manual procedure if the master key must change: stop the service, run a one-off job that unwraps every data_key_wrapped/doc_key_wrapped with the old KEK and re-wraps with the new (data blobs themselves need no re-encryption), swap the key in the config, start. Rotating a user's data key would require re-encrypting their rows. Instance-key rotation is just a config change + new link codes for every Copper still on the instance key (Coppers on access keys are unaffected); a single person's access key is rotated by revoking it and minting a new one in the portal.

Logging

Request spans record method, path (never the query string), matched route, client IP, user_id, status and latency, plus the error code of an error response and — for 400s — the client-facing message with every double-quoted fragment (where serde echoes input values) replaced by "…". Never logged: tokens, passwords, instance/master keys, access keys, intelligence (Jev / router) keys, pairing codes, admin cookies, request or response bodies, payloads (access keys and pairing codes are logged by id only). Config's Debug redacts keys and the database password. 500s log the internal error chain server-side only; clients get {"error":"internal"}.

Process hardening (systemd unit)

Dedicated copper-cloud user; CAP_NET_BIND_SERVICE only; NoNewPrivileges, ProtectSystem=strict (config and certificate read-only, state in /var/lib/copper-cloud), ProtectHome, PrivateTmp, PrivateDevices, kernel/cgroup/clock protection, RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX, MemoryDenyWriteExecute, SystemCallFilter=@system-service ~@privileged, UMask=0077. Config file 0600 (copper-cloud), TLS key 0640 root:copper-cloud, link-code and admin-credentials files 0600 root.

Database

The installer's local Postgres listens on localhost only; the copper_cloud role gets a random 40-character password and scram-sha-256 auth on 127.0.0.1/::1 only. For RDS use ?sslmode=require (or stricter) in DATABASE_URL.

Single sign-on

See sso.md for setup. What the server trusts and why:

  • The gate is the identity provider's domain check. The ungated routes are GET /v1/auth/sso (public metadata: client id, endpoints, domains) and POST /v1/auth/sso/{id}. A sign-in succeeds only with a one-time authorization code the provider issued to this client id, plus the matching PKCE verifier. The join link and /start carry no secret. Anyone can start a sign-in, but only a verified account in an allowed domain finishes it. With Google, the Workspace hd claim must also be an allowed domain, so a personal Google account registered with a company address is refused. Use an Internal consent screen so Google itself only admits your organization.
  • Code exchange on the server. The client secret is stored AES-256-GCM-sealed under a per-provider data key wrapped by the KEK (AAD sso:<id>), like the intelligence keys. It is never returned by the admin API (has_secret only), never logged and not in the audit detail. It is read from stdin on the CLI. Codes and tokens are never logged.
  • ID token. It is fetched directly from the provider's token endpoint over TLS (https://; webpki roots; no redirects; 10 s timeouts). The server checks iss, aud/azp, exp (60 s skew), sub, email_verified and the domain. Its signature is not verified: the TLS channel to the token endpoint authenticates it (OpenID Connect Core, "ID Token Validation"). OIDC discovery documents must match the configured issuer exactly.
  • Redirect URIs are loopback only (127.0.0.1, [::1], localhost with a port). A code stolen in transit cannot be redeemed without the verifier.
  • Account linking by email trusts the provider's email_verified. An existing password account with the same address is linked on first SSO sign-in, so allow only domains your provider is authoritative for.
  • Rate limits. POST /v1/auth/sso/{id} shares the per-IP auth limiter. Failed OIDC discovery is cached for a minute, so the public GET /v1/auth/sso cannot be turned into a request flood against the issuer.
  • Password sign-in can be turned off (password_signin), leaving SSO as the only way in for people. Admin accounts are separate and unaffected. SSO-only accounts have no password hash, and password login for them does the same dummy Argon2 work as for an unknown email before answering sso_only.

Agent integrations

An agent-integration key (cai_ + 256 random bits, stored as SHA-256, shown once) lets a service mint a device-bound, single-use, 10-minute pairing code for any user in the integration's domains (POST /v1/agents/pair). With create_users, the service can also create those accounts. That is admin-level power over those domains: hand the key only to services trusted like an admin, narrow its domains, turn create_users off where possible, and rotate/revoke it from the portal or the CLI. Revocation also signs out every agent device the integration paired: their sessions are deleted and their gate keys revoked. Re-pairing a device replaces its previous session and gate key, so a leaked session for an agent device dies at the next pairing. Every pairing and every key change is audited. The route is not rate limited, because the key is unguessable, and it is checked by shape before any database lookup.

Device agent relay

An agent token (cat_ + 256 random bits, stored as SHA-256, shown once) lets an agent drive one person's Copper for iOS through /v1/agent/* (0.13.0): it acts as that person in their signed-in tabs, so it is as powerful as the phone's browser while Copper is open on screen.

  • Bound and narrow. A token is minted by a signed-in device for itself and works only for that user and device; it is not a session and opens no other route. The route is outside the instance gate (the token is the credential), checked by shape before any database lookup, and limited to 600 requests a minute per token. Tokens are read from the Authorization header only, never a query string.
  • The person stays in control. Calls reach the phone only while Copper is open on its screen and the person has turned agents on (the phone holds the stream); every call is announced on the page with Stop. Revoking a token, revoking the link or deleting the device takes effect at once: calls in flight fail and the device gets a cancel. A disabled account's tokens stop working; disabling or deleting a user also closes their phones' streams and fails their calls (at once from the admin API, within 10 s from copper-cloud admin). At most 8 calls are in flight per phone.
  • Devices only feed their own link. Only the link's own device (its session) may open or post to its frames; a reply is matched to the request id and the link it was sent to.
  • Nothing about calls is stored. One log line per call (token id, device id, tool, duration, outcome); arguments, results, progress text and tokens are never logged. Device log frames are written at debug level only.

Reporting

Security issues: contact the maintainers privately (do not open a public issue).

There aren't any published security advisories