@@ -59,6 +59,82 @@ per-authenticated-session RPC bandwidth/request budget, remote execution custody
5959not fully persisted, and public deployment still depends on correctly configured
6060TLS/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