CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-07-13 03:06:36 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Terminal flow + threat model + v1.1 follow-ups

Browse Source 
SIDEBAR_MESSAGE_FLOW.md: new "Terminal flow" section. Documents the WS
upgrade path (/pty-session cookie mint → /ws Origin + cookie gate →
lazy claude spawn), the dual-token model (AUTH_TOKEN for /pty-session,
gstack_pty cookie for /ws, INTERNAL_TOKEN for server↔agent loopback),
and the threat-model boundary — the Terminal tab bypasses the entire
prompt-injection security stack on purpose; user keystrokes are the
trust source. That trust assumption is load-bearing on three transport
guarantees: local-only listener, Origin gate, cookie auth. Drop any
one of those three and the tab becomes unsafe.

CLAUDE.md: extends the "Sidebar architecture" note to include
terminal-agent.ts in the read-this-first list. Adds a "Terminal tab is
its own process" note so a future contributor doesn't bolt PTY logic
onto sidebar-agent.ts.

TODOS.md: three new follow-ups under a new "Sidebar Terminal" section:
  - v1.1: PTY session survives sidebar reload (Issue 1C deferred).
  - v1.1+: audit /health AUTH_TOKEN distribution (codex finding #2 —
    a pre-existing soft leak that cc-pty-import sidesteps but doesn't
    fix).
  - v1.1+: apply terminal-agent's process.on exception handlers to
    sidebar-agent.ts (codex finding #4 — chat path has no fatal
    handlers).
This commit is contained in:
Garry Tan
2026-04-25 12:34:43 -07:00
parent 55a0f0e469
commit 0361acfb6a
3 changed files with 222 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+17 -5
View File
@@ -225,13 +225,25 @@ When you need to interact with a browser (QA, dogfooding, cookie setup), use the
project uses.
**Sidebar architecture:** Before modifying `sidepanel.js`, `background.js`,
`content.js`, `sidebar-agent.ts`, or sidebar-related server endpoints, read
`docs/designs/SIDEBAR_MESSAGE_FLOW.md`. It documents the full initialization
timeline, message flow, auth token chain, tab concurrency model, and known
failure modes. The sidebar spans 5 files across 2 codebases (extension + server)
with non-obvious ordering dependencies. The doc exists to prevent the kind of
`content.js`, `sidebar-agent.ts`, `terminal-agent.ts`, or sidebar-related
server endpoints, read `docs/designs/SIDEBAR_MESSAGE_FLOW.md`. It documents
the full initialization timeline, message flow, auth token chain, tab
concurrency model, the Terminal-tab PTY flow, and known failure modes.
The sidebar spans 6 files across 2 codebases (extension + server) with
non-obvious ordering dependencies. The doc exists to prevent the kind of
silent failures that come from not understanding the cross-component flow.
**Terminal tab is its own process.** `terminal-agent.ts` is a separate
non-compiled bun process from `sidebar-agent.ts`. Do not bolt PTY logic
onto sidebar-agent — codex confirmed it would couple chat reliability to
PTY framing bugs. Cookie minting (`pty-session-cookie.ts`) lives in the
server; the cookie travels via `Set-Cookie` and back via `Cookie:` on the
WebSocket upgrade. The WS upgrade gates on Origin AND cookie; both are
load-bearing for the Terminal tab to be safe. `/health` MUST NOT surface
the cookie value or any shell-grant token (codex finding: existing
`AUTH_TOKEN` is already exposed there in headed mode; that's a separate
v1.1+ TODO, not something to widen).
**Transport-layer security** (v1.6.0.0+). When `pair-agent` starts an ngrok tunnel,
the daemon binds two HTTP listeners: a local listener (127.0.0.1, full command
surface, never forwarded) and a tunnel listener (locked allowlist: `/connect`,