@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/gstack-browse/src/proxy-config.ts

@@ -1,283 +0,0 @@
-/**
- * Parse + validate proxy config from CLI flags and environment.
- *
- * Used by:
- *   cli.ts    — to resolve the proxy (resolveProxy), detect cred-mixing and
- *               daemon-mismatch, and forward to server
- *   server.ts — to spawn the bridge and pass proxy to chromium.launch
- *
- * Proxy precedence (#915): --proxy, then BROWSE_PROXY_URL, then HTTPS_PROXY,
- * HTTP_PROXY and ALL_PROXY (upper case first, then lower case), then direct.
- * BROWSE_PROXY_URL=direct opts out of the standard variables.
- *
- * Cred policy (D9): if BOTH the URL embeds creds AND the env vars
- * BROWSE_PROXY_USER/PASS are set, refuse with a clear error. No silent
- * override — debugging confusion is worse than a one-time setup error.
- */
-
-import { createHash } from 'crypto';
-import type { UpstreamConfig } from './socks-bridge';
-
-export interface ParsedProxyConfig {
-  /** Original scheme: 'socks5' | 'http' | 'https' */
-  scheme: 'socks5' | 'http' | 'https';
-  host: string;
-  port: number;
-  userId?: string;
-  password?: string;
-  /** True if creds are present (from URL or env). */
-  hasAuth: boolean;
-}
-
-export class ProxyConfigError extends Error {
-  constructor(public readonly hint: string, message: string) {
-    super(message);
-    this.name = 'ProxyConfigError';
-  }
-}
-
-/**
- * Parse the BROWSE_PROXY_URL string and merge env-supplied creds.
- *
- * @throws ProxyConfigError on malformed URL, unsupported scheme, or
- *   ambiguous credentials (set in both URL and env).
- */
-export function parseProxyConfig(opts: {
-  proxyUrl: string;
-  envUser?: string;
-  envPass?: string;
-  /** Where proxyUrl came from, named in the cred-mixing hint. */
-  source?: string;
-}): ParsedProxyConfig {
-  let url: URL;
-  try {
-    url = new URL(opts.proxyUrl);
-  } catch {
-    throw new ProxyConfigError(
-      'expected scheme://[user:pass@]host:port',
-      `invalid proxy URL — could not parse`,
-    );
-  }
-
-  // socks5h (remote DNS) is what Chromium's socks5 already does.
-  const scheme = url.protocol === 'socks5h:' ? 'socks5' : url.protocol.replace(':', '');
-  if (scheme !== 'socks5' && scheme !== 'http' && scheme !== 'https') {
-    throw new ProxyConfigError(
-      'use socks5://, http://, or https://',
-      `unsupported proxy scheme '${scheme}'`,
-    );
-  }
-
-  if (!url.hostname) {
-    throw new ProxyConfigError(
-      'expected scheme://[user:pass@]host:port',
-      `invalid proxy URL — missing host`,
-    );
-  }
-
-  const port = url.port
-    ? parseInt(url.port, 10)
-    : (scheme === 'http' ? 80 : scheme === 'https' ? 443 : 1080);
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw new ProxyConfigError(
-      'expected scheme://[user:pass@]host:port',
-      `invalid proxy URL — bad port`,
-    );
-  }
-
-  const urlHasUser = !!url.username;
-  const urlHasPass = !!url.password;
-  const envHasUser = !!opts.envUser;
-  const envHasPass = !!opts.envPass;
-  const urlHasCreds = urlHasUser || urlHasPass;
-  const envHasCreds = envHasUser || envHasPass;
-
-  // D9 (codex correction): refuse on mixed sources. Silent override is a
-  // debugging trap — when a stale BROWSE_PROXY_USER from a prior session
-  // wins over a fresh --proxy URL, the user can't tell why.
-  if (urlHasCreds && envHasCreds) {
-    throw new ProxyConfigError(
-      `unset BROWSE_PROXY_USER/PASS or remove user:pass@ from ${opts.source ?? '--proxy'}`,
-      `proxy creds set in both env (BROWSE_PROXY_USER) and URL — pick one source`,
-    );
-  }
-
-  let userId: string | undefined;
-  let password: string | undefined;
-  if (urlHasCreds) {
-    userId = decodeURIComponent(url.username);
-    password = url.password ? decodeURIComponent(url.password) : undefined;
-  } else if (envHasCreds) {
-    userId = opts.envUser;
-    password = opts.envPass;
-  }
-
-  return {
-    scheme: scheme as 'socks5' | 'http' | 'https',
-    host: url.hostname,
-    port,
-    ...(userId ? { userId } : {}),
-    ...(password ? { password } : {}),
-    hasAuth: !!(userId || password),
-  };
-}
-
-/** Convert a ParsedProxyConfig to the UpstreamConfig shape socks-bridge wants. */
-export function toUpstreamConfig(cfg: ParsedProxyConfig): UpstreamConfig {
-  return {
-    host: cfg.host,
-    port: cfg.port,
-    ...(cfg.userId ? { userId: cfg.userId } : {}),
-    ...(cfg.password ? { password: cfg.password } : {}),
-  };
-}
-
-/**
- * Compute a stable hash of (proxyUrl + headed flag) for daemon-mismatch
- * detection (D2). The hash is deterministic across CLI invocations on the
- * same machine and survives daemon restarts via the state file.
- *
- * NEVER include resolved creds — the hash compares config intent, not
- * specific credential values, and we don't want creds in any persisted form.
- */
-export function computeConfigHash(opts: {
-  proxyUrl: string | null | undefined;
-  headed: boolean;
-  /** Bypass rules derived from NO_PROXY (resolveProxy's noProxyRules). */
-  noProxyRules?: string | null;
-}): string {
-  const proxyKey = canonicalizeProxyUrl(opts.proxyUrl);
-  const input = JSON.stringify({
-    proxy: proxyKey,
-    headed: opts.headed,
-    ...(proxyKey && opts.noProxyRules ? { noProxy: opts.noProxyRules } : {}),
-  });
-  return createHash('sha256').update(input).digest('hex').slice(0, 16);
-}
-
-/** Strip creds from a proxy URL for hashing. Returns null for empty input. */
-function canonicalizeProxyUrl(input: string | null | undefined): string | null {
-  if (!input) return null;
-  try {
-    const u = new URL(input);
-    u.username = '';
-    u.password = '';
-    return `${u.protocol}//${u.host}`;
-  } catch {
-    return '<unparseable>';
-  }
-}
-
-export const STANDARD_PROXY_VARS = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy'] as const;
-const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '[::1]'];
-export const PROXY_TROUBLESHOOTING = 'https://github.com/garrytan/gstack/blob/main/BROWSER.md#proxy-from-environment';
-
-export interface ResolvedProxy {
-  /** Proxy URL with resolved creds embedded, or null for a direct connection. */
-  url: string | null;
-  /** '--proxy' or the env var the proxy came from; null when direct. */
-  source: string | null;
-  /** NO_PROXY translated to Chromium bypass rules (sorted, comma-separated), or null. */
-  noProxyRules: string | null;
-  /** Rules Chromium receives: noProxyRules plus loopback; null when direct. */
-  bypass: string | null;
-  /** Set when a standard proxy variable was ignored because it does not parse. */
-  warning: string | null;
-}
-
-/**
- * Translate a curl-style NO_PROXY list to Chromium bypass rules: `example.com`
- * and `.example.com` cover the domain and its subdomains, `*` bypasses all,
- * CIDR blocks and `host:port` pass through, and bare IPv6 gets brackets.
- * Loopback names are left out: withLoopbackBypass always adds them, and the
- * CLI appends them to NO_PROXY for its own daemon calls (#494).
- */
-export function noProxyToChromiumRules(noProxy: string | undefined): string[] {
-  const rules = new Set<string>();
-  for (const raw of (noProxy ?? '').toLowerCase().split(/[\s,]+/)) {
-    if (!raw) continue;
-    if (raw === '*' || raw.includes('/')) { rules.add(raw); continue; }
-    let host = raw;
-    let port = '';
-    const bracket = raw.match(/^(\[[0-9a-f:.]+\])(:\d+)?$/);
-    if (bracket) [host, port] = [bracket[1], bracket[2] ?? ''];
-    else if (raw.split(':').length > 2) {
-      if (!/^[0-9a-f:.]+$/.test(raw)) continue;
-      host = `[${raw}]`;
-    }
-    else if (raw.includes(':')) [host, port] = [raw.slice(0, raw.lastIndexOf(':')), raw.slice(raw.lastIndexOf(':'))];
-    if (port && !/^:\d+$/.test(port)) continue;
-    if (!port && LOOPBACK_HOSTS.includes(host)) continue;
-    if (host.startsWith('*.')) { rules.add(host + port); continue; }
-    host = host.replace(/^\./, '');
-    if (!host) continue;
-    rules.add(host + port);
-    if (!host.startsWith('[') && !/^\d+(\.\d+){3}$/.test(host)) rules.add(`*.${host}${port}`);
-  }
-  return [...rules].sort();
-}
-
-/**
- * Chromium bypass rules for a proxied session: the NO_PROXY rules plus
- * loopback. Naming loopback also stops Playwright from adding `<-loopback>`,
- * which would send localhost through the proxy.
- */
-export function withLoopbackBypass(rules: string[]): string {
-  return [...new Set([...rules, ...LOOPBACK_HOSTS])].join(',');
-}
-
-/**
- * The daemon's view of the proxy the CLI resolved: BROWSE_PROXY_URL ('direct'
- * means none), its source, and the bypass rules (computed from NO_PROXY when
- * a caller other than the CLI set only BROWSE_PROXY_URL).
- */
-export function serverProxyEnv(env: NodeJS.ProcessEnv): { url: string | undefined; source: string; bypass: string } {
-  return {
-    url: env.BROWSE_PROXY_URL === 'direct' ? undefined : env.BROWSE_PROXY_URL || undefined,
-    source: env.BROWSE_PROXY_SOURCE || 'BROWSE_PROXY_URL',
-    bypass: env.BROWSE_PROXY_BYPASS || withLoopbackBypass(noProxyToChromiumRules(env.NO_PROXY || env.no_proxy)),
-  };
-}
-
-/**
- * Resolve the proxy for this invocation (#915). Env URLs go through
- * parseProxyConfig, so the cred policy applies. A standard variable that does
- * not parse (curl-style `host:port`, an unsupported scheme) is ignored with a
- * warning instead of failing every command; --proxy and BROWSE_PROXY_URL are
- * explicit browse settings and still fail closed.
- */
-export function resolveProxy(flagUrl: string | null, env: NodeJS.ProcessEnv): ResolvedProxy {
-  const direct = (warning: string | null = null): ResolvedProxy => ({ url: null, source: null, noProxyRules: null, bypass: null, warning });
-  let source: string;
-  let raw: string;
-  if (flagUrl) {
-    [source, raw] = ['--proxy', flagUrl];
-  } else if (env.BROWSE_PROXY_URL) {
-    if (env.BROWSE_PROXY_URL === 'direct') return direct();
-    [source, raw] = ['BROWSE_PROXY_URL', env.BROWSE_PROXY_URL];
-  } else {
-    const name = STANDARD_PROXY_VARS.find(key => env[key]);
-    if (!name) return direct();
-    [source, raw] = [name, env[name]!];
-    try {
-      parseProxyConfig({ proxyUrl: raw });
-    } catch (err) {
-      if (!(err instanceof ProxyConfigError)) throw err;
-      return direct(`${source} is not a proxy URL browse can use (${err.message}; ${err.hint}), so browse connects directly. ` +
-        `fix: export ${source}=http://host:port (or socks5://), or set BROWSE_PROXY_URL=direct to silence this. see ${PROXY_TROUBLESHOOTING}`);
-    }
-  }
-  const parsed = parseProxyConfig({ proxyUrl: raw, envUser: env.BROWSE_PROXY_USER, envPass: env.BROWSE_PROXY_PASS, source });
-  const url = new URL(raw);
-  if (url.protocol === 'socks5h:') url.protocol = 'socks5:';
-  url.username = parsed.userId ? encodeURIComponent(parsed.userId) : '';
-  url.password = parsed.password ? encodeURIComponent(parsed.password) : '';
-  const rules = noProxyToChromiumRules(env.NO_PROXY || env.no_proxy);
-  return {
-    url: url.toString(),
-    source,
-    noProxyRules: rules.length ? rules.join(',') : null,
-    bypass: withLoopbackBypass(rules),
-    warning: null,
-  };
-}

package/.agent/skills/gstack-browse/src/proxy-redact.ts

@@ -1,46 +0,0 @@
-/**
- * Single source of truth for redacting proxy credentials in log lines.
- *
- * Anywhere browse logs a proxy URL (startup banner, error messages, debug
- * output), it MUST go through redactProxyUrl first. Tests assert this for
- * every log path that prints proxy config.
- */
-
-const REDACTED = '***';
-
-/**
- * Redact creds in a proxy URL string. Returns the URL with username and
- * password replaced by '***'. If the input isn't parseable as a URL, returns
- * a generic placeholder rather than echoing it back (input may be malformed
- * AND contain creds).
- */
-export function redactProxyUrl(input: string | null | undefined): string {
-  if (!input) return '<no proxy>';
-  let url: URL;
-  try {
-    url = new URL(input);
-  } catch {
-    return '<malformed proxy url>';
-  }
-  if (url.username) url.username = REDACTED;
-  if (url.password) url.password = REDACTED;
-  return url.toString();
-}
-
-/**
- * Redact creds in an upstream config object (host/port/userId/password).
- * Returns a plain object suitable for logging.
- */
-export function redactUpstream(upstream: {
-  host: string;
-  port: number;
-  userId?: string;
-  password?: string;
-}): { host: string; port: number; userId?: string; password?: string } {
-  return {
-    host: upstream.host,
-    port: upstream.port,
-    ...(upstream.userId ? { userId: REDACTED } : {}),
-    ...(upstream.password ? { password: REDACTED } : {}),
-  };
-}

package/.agent/skills/gstack-browse/src/pty-session-cookie.ts

@@ -1,64 +0,0 @@
-/**
- * Session cookie registry for the Terminal sidebar tab's PTY WebSocket.
- *
- * Why this exists: WebSocket clients in browsers cannot send Authorization
- * headers on the upgrade request. The terminal-agent's /ws upgrade therefore
- * authenticates via cookie. We never put the PTY token in /health (codex
- * outside-voice finding #2: /health already leaked AUTH_TOKEN to any
- * localhost caller in headed mode; reusing that path for shell access would
- * widen an existing bug). Instead, the extension does an authenticated
- * POST /pty-session with the bootstrap AUTH_TOKEN; the server mints a
- * short-lived cookie scoped to this terminal session and pushes it to the
- * agent via loopback. The browser then carries the cookie automatically on
- * the WS upgrade.
- *
- * Shares the registry implementation with sse-session-cookie.ts via
- * createSessionCookieStore. Two INSTANCES instead of one because the cookie
- * names are different (`gstack_sse` vs `gstack_pty`) and the token spaces
- * must not overlap — an SSE-read cookie must never grant PTY access, and
- * vice versa.
- */
-import { createSessionCookieStore } from './session-cookie-store';
-
-const TTL_MS = 30 * 60 * 1000; // 30 minutes — matches SSE cookie
-
-export const PTY_COOKIE_NAME = 'gstack_pty';
-
-const store = createSessionCookieStore({ cookieName: PTY_COOKIE_NAME, ttlMs: TTL_MS });
-
-/** Mint a fresh PTY session token. */
-export function mintPtySessionToken(): { token: string; expiresAt: number } {
-  return store.mint();
-}
-
-/**
- * Validate a token. Returns true only if the token exists AND is not expired.
- * Lazily removes expired entries; opportunistically prunes a few more on
- * every call so the registry stays bounded under reconnect pressure.
- */
-export function validatePtySessionToken(token: string | null | undefined): boolean {
-  return store.validate(token);
-}
-
-/**
- * Drop a session token (called on WS close so a leaked cookie can't be
- * replayed against a new PTY).
- */
-export function revokePtySessionToken(token: string | null | undefined): void {
-  store.revoke(token);
-}
-
-/** Parse the PTY session token from a Cookie header. */
-export function extractPtyCookie(req: Request): string | null {
-  return store.extract(req);
-}
-
-/** Build the Set-Cookie header value for the PTY session cookie. */
-export function buildPtySetCookie(token: string): string {
-  return store.buildSetCookie(token);
-}
-
-// Test-only reset.
-export function __resetPtySessions(): void {
-  store.__reset();
-}

package/.agent/skills/gstack-browse/src/pty-session-lease.ts

@@ -1,137 +0,0 @@
-/**
- * PTY session lease registry (v1.44+).
- *
- * Separates two concerns that pre-v1.44 were conflated under one token:
- *
- *  - **sessionId** — stable, non-secret identifier for a single PTY session.
- *    Safe to log, safe to include in URLs and server access logs, safe to
- *    keep in DevTools. Identifies "this terminal," not "you're allowed to
- *    use this terminal."
- *
- *  - **attachToken** — secret, short-lived (30 s) bearer credential that
- *    grants the WS upgrade for ONE attach attempt against a session. Minted
- *    on every /pty-session and /pty-session/reattach call; revoked when
- *    the WS upgrade consumes it. Kept out of logs.
- *
- *  - **lease** — server-side bookkeeping that maps sessionId → expiresAt.
- *    Re-attach within the lease window resumes the same PTY (and replays
- *    the ring buffer from terminal-agent). Lease expiry tears down the
- *    session.
- *
- * Codex outside-voice (T1 of the eng review) pushed for this separation:
- * "the auth token IS the session id" collapsed identity into a secret,
- * meaning re-attach URLs and logs carry the bearer credential. The lease
- * model fixes that without changing the user experience.
- *
- * Mint cadence:
- *  - Initial /pty-session: mint sessionId + lease + attachToken (one round trip).
- *  - /pty-session/reattach: validate sessionId/lease, mint fresh attachToken.
- *  - /pty-restart: revoke old lease, mint fresh sessionId + lease + attachToken.
- *  - /pty-dispose: revoke lease (and the terminal-agent disposes the PTY).
- *
- * Lease TTL is env-overridable so v1.44 e2e tests can compress detach
- * windows to 1 s instead of waiting 30 minutes per assertion.
- */
-import * as crypto from 'crypto';
-
-interface Lease {
-  createdAt: number;
-  expiresAt: number;
-}
-
-const LEASE_TTL_MS = parseInt(
-  process.env.GSTACK_PTY_LEASE_TTL_MS || `${30 * 60 * 1000}`,
-  10,
-); // 30 minutes default; covers idle-but-engaged user sessions
-const MAX_LEASES = 10_000;
-const leases = new Map<string, Lease>();
-
-/**
- * Mint a fresh sessionId + lease. Returns the non-secret sessionId and
- * the expiry timestamp (caller surfaces both to the client). Never throws.
- */
-export function mintLease(): { sessionId: string; expiresAt: number } {
-  const sessionId = crypto.randomBytes(32).toString('base64url');
-  const now = Date.now();
-  const expiresAt = now + LEASE_TTL_MS;
-  leases.set(sessionId, { createdAt: now, expiresAt });
-  pruneExpired(now);
-  return { sessionId, expiresAt };
-}
-
-/**
- * Check whether a lease is still valid (exists AND not expired). Returns
- * the current expiresAt for valid leases; null otherwise. Lazily prunes
- * stale entries.
- */
-export function validateLease(sessionId: string | null | undefined): { ok: true; expiresAt: number } | { ok: false } {
-  if (!sessionId) return { ok: false };
-  const lease = leases.get(sessionId);
-  if (!lease) {
-    pruneExpired(Date.now());
-    return { ok: false };
-  }
-  if (Date.now() > lease.expiresAt) {
-    leases.delete(sessionId);
-    pruneExpired(Date.now());
-    return { ok: false };
-  }
-  return { ok: true, expiresAt: lease.expiresAt };
-}
-
-/**
- * Extend the lease's expiresAt to `now + LEASE_TTL_MS`. Caller should
- * gate refresh on `expiresAt - now < REFRESH_THRESHOLD` (D10 lazy
- * refresh: avoid refreshing on every keepalive when the lease is
- * comfortably far from expiry).
- *
- * Returns `{ ok: true, expiresAt }` on success, `{ ok: false }` if the
- * lease is unknown or already expired (the agent must close the WS and
- * surface auth-invalid). Critical security invariant: never resurrect
- * an expired lease — the 30-min TTL is what bounds blast radius for a
- * leaked attach token whose lease should have been GC'd.
- */
-export function refreshLease(sessionId: string | null | undefined): { ok: true; expiresAt: number } | { ok: false } {
-  if (!sessionId) return { ok: false };
-  const lease = leases.get(sessionId);
-  if (!lease) return { ok: false };
-  const now = Date.now();
-  if (now > lease.expiresAt) {
-    leases.delete(sessionId);
-    return { ok: false };
-  }
-  lease.expiresAt = now + LEASE_TTL_MS;
-  return { ok: true, expiresAt: lease.expiresAt };
-}
-
-/**
- * Drop a lease. Called on explicit dispose (/pty-dispose, /pty-restart,
- * WS close with code 4001) and on session timeout in terminal-agent.
- */
-export function revokeLease(sessionId: string | null | undefined): void {
-  if (!sessionId) return;
-  leases.delete(sessionId);
-}
-
-/** Returns the lease count — test + observability helper. */
-export function leaseCount(): number {
-  return leases.size;
-}
-
-/** Test-only reset. */
-export function __resetLeases(): void {
-  leases.clear();
-}
-
-function pruneExpired(now: number): void {
-  let checked = 0;
-  for (const [sessionId, lease] of leases) {
-    if (checked++ >= 20) break;
-    if (lease.expiresAt <= now) leases.delete(sessionId);
-  }
-  while (leases.size > MAX_LEASES) {
-    const first = leases.keys().next().value;
-    if (!first) break;
-    leases.delete(first);
-  }
-}