Skip to content

Commit 99bd67e

Browse files
authored
Enhance security model documentation
Expanded the security model section detailing the Hub owner to enrolled machine boundary, connection and execution gates, tests, and residual limitations.
1 parent f4a345d commit 99bd67e

1 file changed

Lines changed: 76 additions & 0 deletions

File tree

‎docs/security-model.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,82 @@ per-authenticated-session RPC bandwidth/request budget, remote execution custody
5959
not fully persisted, and public deployment still depends on correctly configured
6060
TLS/reverse-proxy infrastructure. Prefer loopback or a trusted tailnet.
6161

62+
## Hub owner -> enrolled machine boundary
63+
64+
**Boundary:** signing into the Hub must not silently enroll a machine or grant remote
65+
execution. A stolen/replayed enrollment link, database disclosure, cross-site
66+
request, or revoked machine credential must not produce lasting machine presence.
67+
68+
**Enforcement:** only a valid owner browser session plus its rotated CSRF secret can
69+
issue an enrollment token. Tokens contain 256 bits of random secret, live only in
70+
Hub memory, expire after ten minutes, are single-use, and are consumed after a failed
71+
secret presentation for a known id. Issuance/enrollment requests are bounded by a
72+
per-peer limiter. Enrollment creates an Ed25519 identity on the brain and a separate
73+
256-bit bearer credential; the brain stores both in an owner-only atomic file while
74+
the Hub stores the public key and only SHA-256 of the bearer secret. Heartbeats are
75+
outbound HTTPS requests. Presence goes offline after 90 seconds without a successful
76+
heartbeat, and owner revocation immediately makes the bearer credential fail closed.
77+
Browser mutations retain exact-origin and CSRF enforcement. The explicitly labeled
78+
first-owner QR carries the same short-lived, single-use bootstrap fragment already
79+
printed to the trusted terminal; it expires in ten minutes and is removed after
80+
registration. Normal mobile QR codes encode only the stable validated HTTPS Hub
81+
origin and are rendered in the authenticated dashboard; they contain no browser
82+
session, enrollment secret, or Brain ticket. Phone-approved enrollment keeps its
83+
Ed25519 private key on the PC, uses the short code only for human comparison, and
84+
protects polling/credential delivery with a separate 256-bit request secret. Pending
85+
requests are memory-only, bounded, rate-limited, ten-minute, owner-approved with
86+
CSRF, one-time on delivery, and audited.
87+
Tailscale setup refuses to overwrite an existing Serve configuration without an
88+
explicit replacement flag. QR transfer does not weaken normal passkey sign-in.
89+
90+
**Connection and execution gates:** only an authenticated Hub browser session plus
91+
CSRF can issue a 60-second memory-only ticket for one owned, active, relay-connected
92+
machine. Ticket ids are one-shot even after a wrong-secret guess. The authenticated
93+
outbound Brain WebSocket and exact-origin browser WebSocket are paired only for that
94+
machine; the relay bounds frame size and buffered output, applies a shared per-connection
95+
token bucket (240-frame/8 MiB burst, refilling at 60 frames and 2 MiB per second),
96+
and never accepts arbitrary destinations. Browser and Brain then use ephemeral P-256 ECDH. The Brain signs the
97+
handshake transcript with its enrolled Ed25519 key, and ordered application frames
98+
use direction-separated HKDF/AES-256-GCM keys. The Hub sees routing metadata and
99+
handshake public values, but not RPC, source, terminal, prompt, or response plaintext.
100+
101+
Hub identity still does not grant execution. `crewcode hub --local-brain` enrolls
102+
the Hub host only after the owner passkey exists, then spawns a sibling Brain;
103+
it does not skip Brain-local scope checks or write workspace roots into Hub SQLite.
104+
The first `crewcode brain` start grants
105+
no RPC scope by default and seeds an owner-only persisted policy from explicit local
106+
`--workspace-root` and repeatable `--allow-scope` settings. Thereafter Settings →
107+
Brain Access manages it only through E2EE owner RPC. Reductions apply immediately,
108+
stop affected agents/terminals, and remove scopes from existing sessions; additions
109+
require a fresh ticket and handshake. Each decrypted method must be included in both
110+
the ticket request and current local grant. The backend revalidates live workspace
111+
roots for filesystem, Git, PTY, attachments, and agent calls.
112+
113+
**Tests:** `hub-server.test.ts` covers CSRF, issue/enroll, local-brain owner gating,
114+
replay rejection, stale
115+
presence, heartbeat, and revocation. `hub-local-brain.test.ts` covers sibling spawn
116+
plans, loopback origin matching, credential reuse, and supervisor stop. `hub-machine-enrollment.test.ts` covers URL
117+
policy, argument-secret avoidance, credential validation, owner-only file mode, and
118+
Brain CLI grants. `hub-relay.test.ts` covers ticket expiry/one-shot behavior,
119+
authenticated relay routing, Ed25519-authenticated E2EE, scoped read success, local
120+
scope denial, per-connection traffic rejection, and ticket replay rejection.
121+
`hub-relay-client.test.ts` covers explicit fresh-ticket reconnect without RPC replay.
122+
123+
**Residual limitation:** machine credential rotation/logout and recovery are not yet
124+
implemented. Relay traffic is bounded per connection, but durable bandwidth metrics
125+
and broader aggregate abuse accounting are not implemented. Browser relay loss now
126+
detaches Brain-owned terminals and agents instead of stopping them. A fresh encrypted
127+
connection can explicitly reclaim stable resource ids, with up to 100 owned resources
128+
per user and 1,000 events / 1 MiB of detached evidence buffered per resource;
129+
interrupted RPCs are never replayed.
130+
Execution custody is still process-resident rather than crash durable: Brain process,
131+
VPS, revocation, or persistent Brain-to-Hub relay loss can stop execution without a
132+
complete remote halt journal. Attachments are tunneled as ordered chunks inside the
133+
E2EE relay: Hub receives ciphertext only, while Brain enforces `workspace:write`, a
134+
25 MiB file limit, registered-root and symlink containment, strict sequence and
135+
size bounds, SHA-256 integrity, active-upload limits, and temporary-file cleanup.
136+
137+
62138
## Hop 1 — untrusted content -> agent
63139

64140
**Boundary:** injected instructions in scraped/file/MCP content must not gain

0 commit comments

Comments
 (0)