Security
Anyone holding a panel token can read your sessions, answer their prompts,
start and stop sessions in your projects and, with the channel, prompt
them. They can also lock or suspend the machines that allow it
(power.lock, power.suspend) and wake machines over the LAN. Treat a
token like an SSH key and keep the hub on your LAN or VPN.
1. Tokens
| Token | Held by | Checked as |
|---|---|---|
| bootstrap | tokenFile on the hub | compared in constant time |
| device | each paired browser | random, stored as SHA-256, revocable |
| collector | each workstation (collectors) | names the machine; only /collect, /sync/, /git/, the report upload and the attachment fetch take it |
| notification key | one prompt’s buttons | random, dies with the prompt |
| view link | one report’s frame | HMAC-signed, an hour, key drawn at start (reports) |
| attachment link | one attached file | HMAC-signed, six hours, key drawn at start |
Rotating tokenFile (and restarting the hub) signs out only the devices
still on the bootstrap token.
2. Pairing a device
sudo -u ccdash ccdash url --hub --config /etc/ccdash/hub.toml --qr
or “Connect a phone” in Settings on a paired browser. Every link carries a token minted for that one device: good for an hour until the link is opened, then for as long as the device keeps it.
Settings › Devices lists them with their browser and last use; rename one with its pencil, or revoke it to sign it out at its next request and end its push notifications. A device still on the bootstrap token sees “shared token” there and can take one of its own.
3. What reaches the hub
- The API under
/api/v1needs a bearer token for everything. /act/<key>/<action>takes a notification button’s one-time key; the access token never goes into a notification./collectand/sync/take a collector’s token;/sync/paths are checked to stay inside the synced directories./reports/-/uploadtakes a collector’s token;/reports/-/view/<key>takes a signed view link and serves the report as a sandboxed, opaque origin that loads nothing from the network, so a report’s scripts never see the panel’s token (reports)./attachments/-/fetch/<id>takes a collector’s token;/attachments/-/view/<key>takes a signed link and serves the file with its kind read from its bytes,nosniffand a sandboxing policy: pictures, recordings and PDFs show in place, everything else is a download, so an uploaded page or SVG never runs in the panel’s origin. File names are reduced to letters, digits,.,_and-before they reach a disk or a prompt. On a workstation the fetched files are the owner’s alone (0600 under a 0700 directory).- The OpenTelemetry receiver on a workstation takes no token, so the collector binds it to loopback only.
- Lock and suspend reach only a machine whose collector has
power.lockorpower.suspendon; the collector checks that again itself. Magic packets go only to the broadcast address of a network the hub is on, or to awake.viaaddress in the hub’s own configuration (machines). - Nothing leaves the hub except Web Push to subscribed devices, encrypted for the device: the push service sees only ciphertext.
- The hub keeps the synced
~/.claudeas plain files: put its directory in an encrypted backup (state sync).