Three security hardening fixes from /ship adversarial review:
1. AUTH_TOKEN unicode-whitespace bypass (server.ts:67-83).
Old: `process.env.AUTH_TOKEN?.trim() || randomUUID()` only stripped
ASCII whitespace. A misconfigured embedder shipping AUTH_TOKEN=$''
(BOM) or $'' (zero-width space) would silently get a
one-character bearer secret. New `sanitizeAuthToken()` strips all
unicode whitespace via regex and requires >= 16 chars after stripping;
anything shorter falls back to crypto.randomUUID(). Same sanitizer
used by `resolveConfigFromEnv()` so the embedder path is hardened too.
2. security-classifier.ts checkTranscript safety net.
`resolveClaudeCommand()` and `spawn()` can throw under transient
conditions (PATH probe failure, posix_spawn ENOMEM). Old code let the
throw propagate and rejected the Promise with a raw exception. Now
wrapped in try/catch that calls finish() with a degraded signal,
matching the graceful-degradation contract the layer already promises
for missing-CLI / exit-nonzero / parse-error.
3. cleanSingletonLocks defensive guard tightened (config.ts).
Old: basename === 'chromium-profile' OR userDataDir === $CHROMIUM_PROFILE.
The second branch was env-controlled and the first was bypassable by
passing a relative path that resolved to chromium-profile via CWD
drift. New guard: refuses relative paths outright, resolves both
sides via path.resolve(), and only accepts the env-match path when
$CHROMIUM_PROFILE is itself absolute.
Test updates: replace the old `.trim()` test with three new cases
covering unicode-whitespace stripping, short-token rejection, and
zero-width-only rejection (server-factory.test.ts).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Surfaces the embedder API gbrowser (phoenix) needs to consume gstack as a
submodule, and gates module-load side effects so the file is safe to
import without auto-starting a daemon.
Changes to browse/src/server.ts:
- AUTH_TOKEN now honors process.env.AUTH_TOKEN (trimmed) before falling
back to crypto.randomUUID(). Whitespace-only values are rejected so the
security boundary can't be silently weakened.
- New exported types: ServerConfig and ServerHandle. ServerConfig documents
the full factory contract (authToken, browsePort, idleTimeoutMs, config,
browserManager, chromiumProfile, xvfb, proxyBridge, startTime, beforeRoute).
ServerHandle documents the return shape (fetchLocal, fetchTunnel,
shutdown, stopListeners). Caller-owned lifecycle annotations on xvfb and
proxyBridge prevent double-close bugs from surprise ownership.
- New exported function: resolveConfigFromEnv() builds a ServerConfig-shaped
object from process.env for CLI use. Embedders construct their own
ServerConfig explicitly.
- start() is now exported. Embedders can call it with env vars set as a
v1 escape hatch until full buildFetchHandler extraction lands.
- Signal handlers (SIGINT, SIGTERM, Windows exit, uncaughtException,
unhandledRejection) and the auto-kickoff at module bottom are now wrapped
in `if (import.meta.main)`. CLI path is unchanged. Embedders register
their own handlers.
- shutdown() and emergencyCleanup() now call cleanSingletonLocks(
resolveChromiumProfile()) instead of inline path+loop. Single
implementation, defensive guard, honors per-workspace CHROMIUM_PROFILE.
New tests:
- browse/test/server-no-import-side-effects.test.ts: spawns a fresh Bun
subprocess that imports server.ts, asserts no signal handlers registered,
no state-dir populated. Guards the core refactor invariant from
regression.
- browse/test/server-factory.test.ts: 12 tests covering AUTH_TOKEN env
behavior (honored, whitespace-rejected, trimmed), preserved exports
(TUNNEL_COMMANDS, canDispatchOverTunnel), and ServerConfig/ServerHandle
type compatibility.
Deferred to follow-up PR: full buildFetchHandler extraction that hoists
the 13 module-level mutables + helpers into a factory closure. Phoenix
can ship v0.6.0.0 against the start()+env surface today; the cleaner
factory comes next.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Garry Tan