mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-18 18:32:28 +08:00
docs: Terminal flow + threat model + v1.1 follow-ups
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:
74
TODOS.md
74
TODOS.md
@@ -1,5 +1,79 @@
|
||||
# TODOS
|
||||
|
||||
## Sidebar Terminal (cc-pty-import follow-ups)
|
||||
|
||||
### v1.1: PTY session survives sidebar reload
|
||||
|
||||
**What:** Today the Terminal tab's PTY dies with the WebSocket — sidebar
|
||||
reload, side-panel close, even a quick navigate-away in another tab close
|
||||
the session. v1.1 should key the PTY on a tab/session id so a reload
|
||||
reattaches to the existing claude process and you keep `/resume` history.
|
||||
|
||||
**Why:** Mid-task resilience. When you've been pair-programming with claude
|
||||
for 20 minutes and an accidental Cmd-R blows it away, the cost is real.
|
||||
|
||||
**Pros:** Better UX, fewer interrupted sessions. **Cons:** Session-tracking
|
||||
state, ghost-process risk, lifecycle bugs (when DOES the PTY actually go
|
||||
away?). v1 chose the simple "PTY dies with WS" model deliberately.
|
||||
|
||||
**Context:** /plan-eng-review Issue 1C decision (cc-pty-import branch,
|
||||
2026-04-25). v1 ships with phoenix's lifecycle. **Depends on:**
|
||||
cc-pty-import landed.
|
||||
|
||||
**Priority:** P2 (nice-to-have).
|
||||
**Effort:** M. Likely needs a per-tab session map keyed by chrome.tabs.id
|
||||
plus a TTL so abandoned PTYs eventually exit.
|
||||
|
||||
---
|
||||
|
||||
### v1.1+: Audit `/health` token distribution
|
||||
|
||||
**What:** Codex's outside-voice review on cc-pty-import flagged that
|
||||
`/health` already surfaces `AUTH_TOKEN` to any localhost caller in headed
|
||||
mode (`server.ts:1657`). That's a pre-existing soft leak — anything
|
||||
running on localhost gets the root token by hitting `/health`.
|
||||
|
||||
**Why:** cc-pty-import sidesteps it by NOT putting the PTY token there
|
||||
(uses an HttpOnly cookie path instead). But the underlying leak is still
|
||||
shippable surface. A second extension or a localhost web app could
|
||||
currently scrape `AUTH_TOKEN` and hit any browse-server endpoint.
|
||||
|
||||
**Pros:** Closes a real privilege-escalation path on multi-extension
|
||||
machines. **Cons:** Either we tighten the gate (Origin must be OUR
|
||||
extension id, not just any chrome-extension://) or we move bootstrap
|
||||
discovery off `/health` entirely. Either has migration cost for tests
|
||||
and the existing extension.
|
||||
|
||||
**Context:** codex finding #2 on cc-pty-import plan-eng review. Not in
|
||||
scope of that PR; deliberately deferred to keep PTY-import small.
|
||||
|
||||
**Priority:** P2.
|
||||
**Effort:** M.
|
||||
|
||||
---
|
||||
|
||||
### v1.1+: Apply terminal-agent's exception handlers to sidebar-agent
|
||||
|
||||
**What:** While reviewing cc-pty-import, codex noted that `sidebar-agent.ts`
|
||||
has no `process.on('uncaughtException'|'unhandledRejection')` handlers.
|
||||
A bug in claude stream parsing or queue I/O can take down the chat path
|
||||
silently. terminal-agent.ts ships with these handlers; sidebar-agent
|
||||
should get them too.
|
||||
|
||||
**Why:** Today a single uncaught exception in chat = entire sidebar chat
|
||||
dies and nothing tells the user. The CLI doesn't supervise the agent.
|
||||
|
||||
**Pros:** Chat survives transient bugs. **Cons:** Catching uncaught
|
||||
exceptions can hide real failures — pair the handlers with structured
|
||||
logging so we still see the bug.
|
||||
|
||||
**Context:** codex finding #4 on cc-pty-import plan-eng review.
|
||||
|
||||
**Priority:** P2.
|
||||
**Effort:** S.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
### Pre-existing test failures surfaced during v1.12.0.0 ship
|
||||
|
||||
Reference in New Issue
Block a user