@amg555/frameforge-mcp 2.7.6 → 2.7.8

package/.agent/skills/gstack-browse/src/socks-bridge.ts

@@ -1,314 +0,0 @@
-/**
- * Local SOCKS5 bridge — accepts unauthenticated connections on 127.0.0.1:<ephemeral>
- * and relays them through an authenticated upstream SOCKS5 proxy.
- *
- * Why this exists: Chromium does not prompt for SOCKS5 auth at launch. To use
- * an auth-required upstream (residential SOCKS5 from a VPN provider, for
- * example), we run a no-auth listener locally that the browser talks to, and
- * the bridge handles the auth handshake with upstream.
- *
- * Architecture:
- *   Chromium  →  socks5://127.0.0.1:<ephemeral>  (this bridge, no auth)
- *                  └→ authenticated SOCKS5 to upstream  →  destination
- *
- * Ported from wintermute's scripts/socks-bridge.mjs with TS types, ephemeral
- * port (no hardcoded 1090), 127.0.0.1-only bind, and a stream-error policy
- * that closes the affected client connection without transport retries (a
- * SOCKS bridge is transport, not request-aware — retries can corrupt browser
- * traffic mid-stream).
- */
-
-import * as net from 'net';
-import { SocksClient, type SocksProxy } from 'socks';
-
-export interface UpstreamConfig {
-  host: string;
-  port: number;
-  userId?: string;
-  password?: string;
-}
-
-export interface BridgeHandle {
-  /** Local port the bridge is listening on (ephemeral). */
-  port: number;
-  /** Underlying server. Exposed for tests; production code uses close(). */
-  server: net.Server;
-  /** Close the listener and all in-flight client sockets. */
-  close: () => Promise<void>;
-}
-
-const SOCKS5_VERSION = 0x05;
-const NO_AUTH_METHOD = 0x00;
-const CMD_CONNECT = 0x01;
-const ATYP_IPV4 = 0x01;
-const ATYP_DOMAINNAME = 0x03;
-const ATYP_IPV6 = 0x04;
-const REPLY_SUCCESS = 0x00;
-const REPLY_GENERAL_FAILURE = 0x01;
-const REPLY_HOST_UNREACHABLE = 0x04;
-const UPSTREAM_CONNECT_TIMEOUT_MS = 15000;
-
-function buildUpstream(upstream: UpstreamConfig): SocksProxy {
-  return {
-    host: upstream.host,
-    port: upstream.port,
-    type: 5,
-    ...(upstream.userId ? { userId: upstream.userId } : {}),
-    ...(upstream.password ? { password: upstream.password } : {}),
-  };
-}
-
-function parseConnectRequest(reqData: Buffer): { host: string; port: number } | null {
-  if (reqData.length < 7 || reqData[0] !== SOCKS5_VERSION || reqData[1] !== CMD_CONNECT) {
-    return null;
-  }
-  const atyp = reqData[3];
-  if (atyp === ATYP_IPV4) {
-    if (reqData.length < 10) return null;
-    const host = `${reqData[4]}.${reqData[5]}.${reqData[6]}.${reqData[7]}`;
-    const port = reqData.readUInt16BE(8);
-    return { host, port };
-  }
-  if (atyp === ATYP_DOMAINNAME) {
-    const len = reqData[4];
-    if (reqData.length < 5 + len + 2) return null;
-    const host = reqData.subarray(5, 5 + len).toString('utf8');
-    const port = reqData.readUInt16BE(5 + len);
-    return { host, port };
-  }
-  if (atyp === ATYP_IPV6) {
-    if (reqData.length < 22) return null;
-    const parts: string[] = [];
-    for (let i = 4; i < 20; i += 2) parts.push(reqData.readUInt16BE(i).toString(16));
-    const host = parts.join(':');
-    const port = reqData.readUInt16BE(20);
-    return { host, port };
-  }
-  return null;
-}
-
-function writeReply(sock: net.Socket, code: number): void {
-  // SOCKS5 reply: VER REP RSV ATYP BND.ADDR(0.0.0.0) BND.PORT(0)
-  const reply = Buffer.from([SOCKS5_VERSION, code, 0x00, ATYP_IPV4, 0, 0, 0, 0, 0, 0]);
-  try { sock.write(reply); } catch { /* peer already gone */ }
-}
-
-/**
- * Start a local SOCKS5 bridge that relays to an authenticated upstream.
- * Listens on 127.0.0.1 only (never 0.0.0.0). port: 0 picks an ephemeral port.
- *
- * Stream-error policy: on any error during a relayed connection, the affected
- * client socket and its upstream pair are destroyed. No transport retries.
- * Browser sees a proxy/connection error and surfaces it as such.
- */
-export async function startSocksBridge(opts: {
-  upstream: UpstreamConfig;
-  port?: number;
-}): Promise<BridgeHandle> {
-  const upstreamProxy = buildUpstream(opts.upstream);
-  const requestedPort = opts.port ?? 0;
-  const inFlight = new Set<net.Socket>();
-
-  // Frame-size predicates for the two SOCKS5 messages we read from the
-  // client. Both return null when we don't yet have enough bytes to know
-  // the frame size, or a positive integer when we do.
-  function greetingSize(buf: Buffer): number | null {
-    if (buf.length < 2) return null;
-    return 2 + buf[1]; // VER NMETHODS + N method bytes
-  }
-  function connectSize(buf: Buffer): number | null {
-    if (buf.length < 5) return null;
-    const atyp = buf[3];
-    if (atyp === ATYP_IPV4) return 10;        // VER CMD RSV ATYP + 4 + 2
-    if (atyp === ATYP_IPV6) return 22;        // VER CMD RSV ATYP + 16 + 2
-    if (atyp === ATYP_DOMAINNAME) return 7 + buf[4]; // VER CMD RSV ATYP LEN + N + 2
-    return null;
-  }
-
-  type State = 'greeting' | 'connect' | 'connecting' | 'piped' | 'closed';
-
-  const server = net.createServer((clientSocket) => {
-    inFlight.add(clientSocket);
-    clientSocket.once('close', () => inFlight.delete(clientSocket));
-
-    let state: State = 'greeting';
-    let buf: Buffer = Buffer.alloc(0);
-    let upstreamSocket: net.Socket | null = null;
-
-    const killBoth = (reason?: string) => {
-      void reason;
-      state = 'closed';
-      try { clientSocket.destroy(); } catch { /* already gone */ }
-      if (upstreamSocket) {
-        try { upstreamSocket.destroy(); } catch { /* already gone */ }
-      }
-    };
-
-    const handshakeTimeout = setTimeout(() => {
-      if (state === 'greeting' || state === 'connect' || state === 'connecting') {
-        killBoth('handshake timeout');
-      }
-    }, 30000);
-    clientSocket.once('close', () => clearTimeout(handshakeTimeout));
-
-    const onData = (chunk: Buffer) => {
-      if (state === 'closed' || state === 'piped') return;
-      buf = buf.length === 0 ? chunk : Buffer.concat([buf, chunk]);
-
-      if (state === 'greeting') {
-        const sz = greetingSize(buf);
-        if (sz == null || buf.length < sz) return;
-        const greeting = buf.subarray(0, sz);
-        buf = buf.subarray(sz);
-        if (greeting[0] !== SOCKS5_VERSION) { killBoth('bad version'); return; }
-        try { clientSocket.write(Buffer.from([SOCKS5_VERSION, NO_AUTH_METHOD])); }
-        catch { killBoth('write greeting reply failed'); return; }
-        state = 'connect';
-        // Fall through — buf may already contain CONNECT bytes (coalesced).
-      }
-
-      if (state === 'connect') {
-        const sz = connectSize(buf);
-        if (sz == null || buf.length < sz) return;
-        const reqData = buf.subarray(0, sz);
-        const remainder = buf.subarray(sz);
-        const dest = parseConnectRequest(reqData);
-        if (!dest) {
-          writeReply(clientSocket, REPLY_GENERAL_FAILURE);
-          killBoth('bad connect request');
-          return;
-        }
-        state = 'connecting';
-        // Pause client reads so any post-handshake bytes don't get dropped.
-        // We replay `remainder` after upstream is established.
-        clientSocket.pause();
-        SocksClient.createConnection({
-          proxy: upstreamProxy,
-          command: 'connect',
-          destination: { host: dest.host, port: dest.port },
-          timeout: UPSTREAM_CONNECT_TIMEOUT_MS,
-        }).then((result) => {
-          if (state === 'closed') {
-            try { result.socket.destroy(); } catch { /* shutdown */ }
-            return;
-          }
-          upstreamSocket = result.socket;
-          writeReply(clientSocket, REPLY_SUCCESS);
-          // Replay any pre-buffered post-handshake bytes BEFORE we pipe.
-          if (remainder.length > 0) {
-            try { upstreamSocket.write(remainder); } catch { killBoth('replay write failed'); return; }
-          }
-          // Wire the rest of the connection through the pipe.
-          upstreamSocket.on('error', () => killBoth('upstream error'));
-          upstreamSocket.on('close', () => { try { clientSocket.destroy(); } catch { /* already gone */ } });
-          clientSocket.removeListener('data', onData);
-          clientSocket.pipe(upstreamSocket);
-          upstreamSocket.pipe(clientSocket);
-          clientSocket.resume();
-          state = 'piped';
-        }).catch(() => {
-          writeReply(clientSocket, REPLY_HOST_UNREACHABLE);
-          killBoth('upstream connect failed');
-        });
-        return;
-      }
-    };
-
-    clientSocket.on('data', onData);
-    clientSocket.on('error', () => killBoth('client error'));
-  });
-
-  await new Promise<void>((resolve, reject) => {
-    const onErr = (e: unknown) => { server.off('listening', onListen); reject(e); };
-    const onListen = () => { server.off('error', onErr); resolve(); };
-    server.once('error', onErr);
-    server.once('listening', onListen);
-    server.listen(requestedPort, '127.0.0.1');
-  });
-
-  const address = server.address();
-  if (!address || typeof address === 'string') {
-    throw new Error('socks-bridge: unexpected listener address');
-  }
-
-  return {
-    port: address.port,
-    server,
-    close: async () => {
-      for (const sock of inFlight) {
-        try { sock.destroy(); } catch { /* already gone */ }
-      }
-      inFlight.clear();
-      await new Promise<void>((resolve) => server.close(() => resolve()));
-    },
-  };
-}
-
-export interface UpstreamTestOpts {
-  upstream: UpstreamConfig;
-  /** Hostname to test connectivity to through the upstream. Default 1.1.1.1. */
-  testHost?: string;
-  /** Port. Default 443. */
-  testPort?: number;
-  /** Total time budget across all retries. Default 5000ms. */
-  budgetMs?: number;
-  /** Number of attempts. Default 3. */
-  retries?: number;
-  /** Backoff between attempts. Default 500ms. */
-  backoffMs?: number;
-}
-
-/**
- * Pre-flight: verify the upstream proxy actually accepts our credentials and
- * can reach a known endpoint. Called before chromium.launch so failures
- * surface as a clear startup error instead of a confusing 'connection
- * refused' on first navigation.
- *
- * Retries a few times with backoff because residential VPNs can take a
- * second to fully establish on first connect.
- *
- * Throws on final failure. Caller is responsible for redacting any error
- * that may leak credentials.
- */
-export async function testUpstream(opts: UpstreamTestOpts): Promise<{ ok: true; attempts: number; ms: number }> {
-  const upstreamProxy = buildUpstream(opts.upstream);
-  const testHost = opts.testHost ?? '1.1.1.1';
-  const testPort = opts.testPort ?? 443;
-  const budgetMs = opts.budgetMs ?? 5000;
-  const retries = opts.retries ?? 3;
-  const backoffMs = opts.backoffMs ?? 500;
-
-  const start = Date.now();
-  let lastErr: unknown;
-
-  for (let attempt = 1; attempt <= retries; attempt++) {
-    const elapsed = Date.now() - start;
-    const remaining = budgetMs - elapsed;
-    if (remaining <= 0) break;
-    const perAttempt = Math.min(remaining, Math.max(500, Math.floor(budgetMs / retries)));
-
-    try {
-      const result = await SocksClient.createConnection({
-        proxy: upstreamProxy,
-        command: 'connect',
-        destination: { host: testHost, port: testPort },
-        timeout: perAttempt,
-      });
-      try { result.socket.destroy(); } catch { /* test connection done */ }
-      return { ok: true, attempts: attempt, ms: Date.now() - start };
-    } catch (err) {
-      lastErr = err;
-      if (attempt < retries) {
-        const elapsedAfter = Date.now() - start;
-        if (elapsedAfter + backoffMs >= budgetMs) break;
-        await new Promise<void>((r) => setTimeout(r, backoffMs));
-      }
-    }
-  }
-
-  const reason = lastErr instanceof Error ? lastErr.message : String(lastErr);
-  const err = new Error(`SOCKS5 upstream rejected or unreachable after ${retries} attempts (${Date.now() - start}ms): ${reason}`);
-  (err as Error & { upstreamHost?: string; upstreamPort?: number }).upstreamHost = opts.upstream.host;
-  (err as Error & { upstreamHost?: string; upstreamPort?: number }).upstreamPort = opts.upstream.port;
-  throw err;
-}

package/.agent/skills/gstack-browse/src/sse-helpers.ts

@@ -1,147 +0,0 @@
-// SSE endpoint helper — shared cleanup contract for stream endpoints.
-//
-// Pre-helper, /activity/stream and /inspector/events implemented the same
-// pattern in parallel and both leaked subscribers when enqueue failed
-// without a corresponding abort signal (e.g. Chromium MV3 service-worker
-// suspend dropped the TCP without an abort edge). The subscriber closure
-// stayed in the Set, capturing the ReadableStreamDefaultController plus
-// any payloads queued behind it. Over a multi-day sidebar session this
-// compounded into multi-MB of retained controllers per dead connection.
-//
-// Centralizing the cleanup contract here means any future SSE endpoint
-// inherits the invariant — cleanup runs on abort, enqueue failure, AND
-// heartbeat failure, exactly once, regardless of which edge fires first.
-
-// sanitizeReplacer strips lone UTF-16 surrogates from string values before
-// they get escape-encoded — required at every SSE egress that ships
-// page-content-derived fields. See CLAUDE.md "Unicode sanitization at
-// server egress" and the canonical implementation in sanitize.ts.
-import { sanitizeReplacer } from './sanitize';
-
-/** Send an SSE event. Handles JSON encoding + lone-surrogate sanitization. */
-export type SseSender = (event: string, data: unknown) => void;
-
-export interface SseEndpointConfig<T> {
-  /**
-   * Optional. Runs once after the stream opens, before subscribing for live
-   * events. Use for initial event replay (activity gap detection, history
-   * burst) or a current-state snapshot (inspector). The `send` helper
-   * handles JSON encoding with sanitizeReplacer and SSE framing; pass
-   * any event name and any payload object.
-   */
-  initialReplay?: (send: SseSender) => void;
-
-  /**
-   * Subscribe to the live event source. Receives a `notify` callback;
-   * returns an unsubscribe function. The callback routes through the
-   * helper's safeEnqueue + cleanup-on-throw, so a dead consumer ends up
-   * removed from the subscriber set on the very next event (instead of
-   * waiting for an abort that may never fire).
-   */
-  subscribe: (notify: (entry: T) => void) => () => void;
-
-  /**
-   * SSE event name for live events. `data: <JSON.stringify(entry)>\n\n`
-   * is wrapped automatically. /activity/stream uses 'activity';
-   * /inspector/events uses 'inspector'.
-   */
-  liveEventName: string;
-
-  /** Heartbeat interval in ms. Default: 15000. */
-  heartbeatMs?: number;
-}
-
-/**
- * Build a streaming Response that owns the cleanup contract:
- *   - safeEnqueue catches enqueue throws → cleanup
- *   - 15s heartbeat catches dead peers; failure → cleanup
- *   - req.signal abort → cleanup
- *   - cleanup is idempotent (clearInterval + unsubscribe + try close)
- */
-export function createSseEndpoint<T>(
-  req: Request,
-  config: SseEndpointConfig<T>,
-): Response {
-  const heartbeatMs = config.heartbeatMs ?? 15000;
-  const encoder = new TextEncoder();
-
-  const stream = new ReadableStream({
-    start(controller) {
-      let cleanedUp = false;
-      let heartbeat: ReturnType<typeof setInterval> | null = null;
-      let unsubscribe: (() => void) | null = null;
-
-      const cleanup = (): void => {
-        if (cleanedUp) return;
-        cleanedUp = true;
-        if (heartbeat !== null) {
-          clearInterval(heartbeat);
-          heartbeat = null;
-        }
-        if (unsubscribe !== null) {
-          unsubscribe();
-          unsubscribe = null;
-        }
-        try {
-          controller.close();
-        } catch {
-          // Expected: stream already closed by the consumer.
-        }
-      };
-
-      const send: SseSender = (event, data) => {
-        if (cleanedUp) return;
-        try {
-          controller.enqueue(
-            encoder.encode(
-              `event: ${event}\ndata: ${JSON.stringify(data, sanitizeReplacer)}\n\n`,
-            ),
-          );
-        } catch {
-          // Consumer disconnected mid-write. Tear down so this subscriber
-          // doesn't sit in the set forever.
-          cleanup();
-        }
-      };
-
-      // Initial replay (caller-provided).
-      if (config.initialReplay) {
-        try {
-          config.initialReplay(send);
-        } catch {
-          cleanup();
-          return;
-        }
-        if (cleanedUp) return;
-      }
-
-      // Subscribe for live events.
-      unsubscribe = config.subscribe((entry) => {
-        send(config.liveEventName, entry);
-      });
-
-      // Heartbeat keeps NAT boxes and proxies from dropping idle SSE,
-      // and serves as a liveness probe: an enqueue failure here is the
-      // cheapest way to learn the consumer is gone without waiting for
-      // an abort signal that may never arrive.
-      heartbeat = setInterval(() => {
-        if (cleanedUp) return;
-        try {
-          controller.enqueue(encoder.encode(`: heartbeat\n\n`));
-        } catch {
-          cleanup();
-        }
-      }, heartbeatMs);
-
-      req.signal.addEventListener('abort', cleanup);
-    },
-  });
-
-  return new Response(stream, {
-    headers: {
-      'Content-Type': 'text/event-stream',
-      'Cache-Control': 'no-cache',
-      'Connection': 'keep-alive',
-    },
-  });
-}

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

@@ -1,65 +0,0 @@
-/**
- * View-only session cookie registry for SSE endpoints.
- *
- * Why this exists: EventSource cannot send Authorization headers, so
- * /activity/stream and /inspector/events historically took a `?token=`
- * query param with the root AUTH_TOKEN. URLs leak through browser history,
- * referer headers, server logs, crash reports, and refactoring accidents
- * (Codex's plan-review outside voice called this out). This module issues
- * a separate short-lived token, scoped to SSE reads only, delivered via
- * an HttpOnly SameSite=Strict cookie that EventSource can pick up with
- * `withCredentials: true`.
- *
- * Design notes:
- * - TTL 30 minutes. Long enough for a normal coding session; short enough
- *   that a leaked cookie expires quickly.
- * - Scope is implicit: validating a cookie only grants read access to
- *   /activity/stream and /inspector/events. The cookie is NEVER valid on
- *   /command, /token, or any mutating endpoint. Matches the
- *   cookie-picker-auth-isolation pattern (prior learning, 10/10 confidence):
- *   cookie-based session tokens must not be valid as scoped tokens.
- * - In-memory only. No persistence across daemon restarts — extension
- *   re-mints on reconnect.
- * - Tokens are 32 random bytes (URL-safe base64). 256 bits, unbruteforceable.
- *
- * Shares the registry implementation with pty-session-cookie.ts via
- * createSessionCookieStore; separate INSTANCE so the token spaces never
- * overlap.
- */
-import { createSessionCookieStore } from './session-cookie-store';
-
-const TTL_MS = 30 * 60 * 1000; // 30 minutes
-
-export const SSE_COOKIE_NAME = 'gstack_sse';
-
-const store = createSessionCookieStore({ cookieName: SSE_COOKIE_NAME, ttlMs: TTL_MS });
-
-/** Mint a fresh view-only SSE session token. */
-export function mintSseSessionToken(): { token: string; expiresAt: number } {
-  return store.mint();
-}
-
-/**
- * Validate a token. Returns true only if the token exists AND is not expired.
- * Expired tokens are lazily removed, and we opportunistically prune a few
- * additional expired entries on every validate so the registry can't grow
- * unboundedly under sustained mint + reconnect pressure.
- */
-export function validateSseSessionToken(token: string | null | undefined): boolean {
-  return store.validate(token);
-}
-
-/** Parse the SSE session token from a Cookie header. */
-export function extractSseCookie(req: Request): string | null {
-  return store.extract(req);
-}
-
-/** Build the Set-Cookie header value for the SSE session cookie. */
-export function buildSseSetCookie(token: string): string {
-  return store.buildSetCookie(token);
-}
-
-// Test-only reset.
-export function __resetSseSessions(): void {
-  store.__reset();
-}