@amg555/frameforge-mcp 2.7.6 → 2.7.8

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

@@ -1,124 +0,0 @@
-/**
- * Factory for expiring session-cookie registries.
- *
- * pty-session-cookie.ts and sse-session-cookie.ts were byte-identical modulo
- * the cookie name — a security-critical parser/TTL/prune implementation that
- * had to be fixed in two places (and a third hand-rolled copy of the cookie
- * parse had already diverged in terminal-agent.ts). One implementation now;
- * the two modules are thin instantiations that keep their names and their
- * distinct threat-model docstrings.
- *
- * Deliberately NOT unified here: pty-session-lease.ts — that's a different
- * contract (sessionId/secret separation, refresh, env-overridable TTL).
- *
- * SECURITY INVARIANT: this module must never import token-registry — cookie
- * session tokens must not be valid as scoped tokens (the
- * cookie-picker-auth-isolation pattern). Pinned by sse-session-cookie.test.ts.
- */
-import * as crypto from 'crypto';
-
-interface Session {
-  createdAt: number;
-  expiresAt: number;
-}
-
-export interface SessionCookieStore {
-  mint(): { token: string; expiresAt: number };
-  validate(token: string | null | undefined): boolean;
-  revoke(token: string | null | undefined): void;
-  extract(req: Request): string | null;
-  buildSetCookie(token: string): string;
-  /** Test-only reset. */
-  __reset(): void;
-}
-
-export function createSessionCookieStore(opts: {
-  cookieName: string;
-  ttlMs: number;
-  maxSessions?: number;
-}): SessionCookieStore {
-  const { cookieName, ttlMs } = opts;
-  const maxSessions = opts.maxSessions ?? 10_000;
-  const sessions = new Map<string, Session>();
-
-  function pruneExpired(now: number): void {
-    // Opportunistic cleanup: check up to 20 entries per call so we don't
-    // stall on a massive registry. O(1) amortized. Runs on every mint AND
-    // on every validate so a steady reconnect flow can't outpace it.
-    let checked = 0;
-    for (const [token, session] of sessions) {
-      if (checked++ >= 20) break;
-      if (session.expiresAt <= now) sessions.delete(token);
-    }
-    // Hard cap as a backstop — if something still gets past opportunistic
-    // cleanup (e.g., all unexpired but registry enormous), drop the oldest.
-    while (sessions.size > maxSessions) {
-      const first = sessions.keys().next().value;
-      if (!first) break;
-      sessions.delete(first);
-    }
-  }
-
-  return {
-    mint() {
-      // 32 random bytes → 43-char URL-safe base64 (no padding). 256 bits.
-      const token = crypto.randomBytes(32).toString('base64url');
-      const now = Date.now();
-      const expiresAt = now + ttlMs;
-      sessions.set(token, { createdAt: now, expiresAt });
-      pruneExpired(now);
-      return { token, expiresAt };
-    },
-
-    validate(token) {
-      if (!token) return false;
-      const s = sessions.get(token);
-      if (!s) {
-        pruneExpired(Date.now());
-        return false;
-      }
-      if (Date.now() > s.expiresAt) {
-        sessions.delete(token);
-        pruneExpired(Date.now());
-        return false;
-      }
-      return true;
-    },
-
-    revoke(token) {
-      if (!token) return;
-      sessions.delete(token);
-    },
-
-    extract(req) {
-      const cookieHeader = req.headers.get('cookie');
-      if (!cookieHeader) return null;
-      for (const part of cookieHeader.split(';')) {
-        const [name, ...valueParts] = part.trim().split('=');
-        if (name === cookieName) {
-          return valueParts.join('=') || null;
-        }
-      }
-      return null;
-    },
-
-    /**
-     * Set-Cookie value:
-     * - HttpOnly: not readable from JS (mitigates XSS exfiltration).
-     * - SameSite=Strict: not sent on cross-site requests (mitigates
-     *   CSRF/CSWSH).
-     * - Path=/: scope to the whole origin.
-     * - Max-Age matches the TTL.
-     * Secure is intentionally omitted: the daemon binds 127.0.0.1 over plain
-     * HTTP; Secure would prevent the browser from ever sending it back.
-     */
-    buildSetCookie(token) {
-      const maxAge = Math.floor(ttlMs / 1000);
-      return `${cookieName}=${token}; HttpOnly; SameSite=Strict; Path=/; Max-Age=${maxAge}`;
-    },
-
-    __reset() {
-      sessions.clear();
-    },
-  };
-}

package/.agent/skills/gstack-browse/src/session-persist.ts

@@ -1,178 +0,0 @@
-/**
- * Opt-in session-state persistence (#778, #2193, #1128, #1129).
- *
- * Portions copyright (c) 2026 Sina Matian, time-attack/gstack (GStack 2), MIT.
- *
- * With BROWSE_PERSIST_STATE=1, the headless daemon snapshots cookies +
- * per-tab URL/localStorage/sessionStorage to <stateDir>/session-state.json
- * on an interval and at clean shutdown, and restores it on the next launch.
- * Kills the auth-lost-on-restart class: a crash or binary-version
- * auto-restart no longer silently logs the user out of everything.
- *
- * Default OFF: cookies on disk (0600) are a real cost the user must opt
- * into. Headed mode is excluded — the persistent Chromium profile already
- * owns that state, and replaying tabs would clobber the user's window.
- *
- * Disk shape (version 1): { version, savedAt, cookies, pages[{url,
- * isActive, storage}] }. loadedHtml and owner are NEVER persisted — same
- * in-memory-only invariant as `state save|load` (meta-commands.ts): a
- * tampered file must not smuggle HTML past load-html's checks or forge tab
- * ownership.
- */
-
-import * as fs from 'fs';
-import type { BrowserManager, BrowserState } from './browser-manager';
-import { writeSecureFile } from './file-permissions';
-import { safeUnlinkQuiet } from './error-handling';
-import { classifyAddress } from './url-validation';
-
-/** Rename a corrupt state file to .corrupt (forensic artifact) — best effort. */
-function quarantineCorrupt(filePath: string): void {
-  try {
-    fs.renameSync(filePath, `${filePath}.corrupt`);
-  } catch {
-    safeUnlinkQuiet(filePath);
-  }
-}
-
-export const SESSION_STATE_FILE = 'session-state.json';
-export const SESSION_STATE_VERSION = 1;
-
-/** Config gate. Documented in browse/SKILL.md ("Session persistence"). */
-export function isSessionPersistEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
-  return env.BROWSE_PERSIST_STATE === '1';
-}
-
-/** Persist interval (ms). Env override exists for tests. */
-export function sessionPersistIntervalMs(env: NodeJS.ProcessEnv = process.env): number {
-  const parsed = parseInt(env.BROWSE_PERSIST_INTERVAL_MS || '', 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : 30_000;
-}
-
-/**
- * Serialize a BrowserState to the on-disk v1 shape. Strips loadedHtml,
- * loadedHtmlWaitUntil, and owner (in-memory-only invariants).
- */
-export function serializeSessionState(state: BrowserState): string {
-  return JSON.stringify({
-    version: SESSION_STATE_VERSION,
-    savedAt: new Date().toISOString(),
-    cookies: state.cookies,
-    pages: state.pages.map((p) => ({
-      url: p.url,
-      isActive: p.isActive,
-      storage: p.storage,
-    })),
-  }, null, 2);
-}
-
-/**
- * True when a cookie domain points at an internal-network target a tampered
- * state file could use to reach localhost services, *.internal hosts, or
- * cloud metadata: `localhost`, `*.internal`, and any address literal that
- * url-validation's classifyAddress calls loopback or blocked (127.0.0.0/8,
- * ::1, 169.254.0.0/16, 100.100.100.200, fe80::/10, fc00::/7, and their
- * mapped and numeric spellings). Leading-dot domain
- * variants (`.127.0.0.1`) are normalized before matching. Single source of
- * truth for the persistence restore path here AND `state load`
- * (meta-commands.ts).
- */
-export function isInternalCookieDomain(domain: string): boolean {
-  const d = domain.startsWith('.') ? domain.slice(1) : domain;
-  if (d === 'localhost' || d.endsWith('.internal')) return true;
-  const kind = classifyAddress(d);
-  return kind === 'blocked' || kind === 'loopback';
-}
-
-/**
- * Cookie hygiene shared with `state load` (meta-commands.ts): drop malformed
- * cookies and internal-network domains (see isInternalCookieDomain).
- */
-export function filterSessionCookies(cookies: unknown[]): BrowserState['cookies'] {
-  return cookies.filter((c: any) => {
-    if (typeof c !== 'object' || !c) return false;
-    if (typeof c.name !== 'string' || typeof c.value !== 'string') return false;
-    if (typeof c.domain !== 'string' || !c.domain) return false;
-    return !isInternalCookieDomain(c.domain);
-  }) as BrowserState['cookies'];
-}
-
-/**
- * Parse + validate the on-disk shape into a BrowserState. Returns null for
- * anything malformed (corrupt JSON, wrong version, missing arrays).
- * loadedHtml/owner are stripped unconditionally even if present on disk.
- */
-export function deserializeSessionState(raw: string): BrowserState | null {
-  let data: any;
-  try {
-    data = JSON.parse(raw);
-  } catch {
-    return null;
-  }
-  if (!data || data.version !== SESSION_STATE_VERSION) return null;
-  if (!Array.isArray(data.cookies) || !Array.isArray(data.pages)) return null;
-  return {
-    cookies: filterSessionCookies(data.cookies),
-    pages: data.pages.map((p: any) => ({
-      url: typeof p?.url === 'string' ? p.url : '',
-      isActive: Boolean(p?.isActive),
-      storage: p?.storage && typeof p.storage === 'object'
-        ? {
-            localStorage: typeof p.storage.localStorage === 'object' && p.storage.localStorage ? p.storage.localStorage : {},
-            sessionStorage: typeof p.storage.sessionStorage === 'object' && p.storage.sessionStorage ? p.storage.sessionStorage : {},
-          }
-        : null,
-      // NEVER accept loadedHtml / loadedHtmlWaitUntil / owner from disk.
-    })),
-  };
-}
-
-/**
- * Snapshot the live session to disk (0600). No-op outside launched
- * (headless) mode — the headed persistent profile owns its own state.
- */
-export async function persistSessionState(bm: BrowserManager, filePath: string): Promise<void> {
-  if (bm.getConnectionMode() !== 'launched') return;
-  const state = await bm.saveState();
-  // Atomic replace: stage the new snapshot beside the target, then rename
-  // over it. A crash mid-write must never destroy the previous good
-  // snapshot — surviving crashes is the point of this feature.
-  const tmpPath = `${filePath}.tmp`;
-  writeSecureFile(tmpPath, serializeSessionState(state));
-  try {
-    fs.renameSync(tmpPath, filePath);
-  } catch (err) {
-    safeUnlinkQuiet(tmpPath);
-    throw err;
-  }
-}
-
-/**
- * Restore a persisted session into a freshly launched manager. Returns the
- * restored (already-filtered) state so callers can log counts without an
- * extra saveState() round-trip, or null when there was nothing to restore
- * (missing file, or corrupt data — which is warned, quarantined, and skipped
- * rather than blocking launch). restoreState re-validates every URL before
- * navigating.
- */
-export async function restoreSessionState(bm: BrowserManager, filePath: string): Promise<BrowserState | null> {
-  let raw: string;
-  try {
-    raw = fs.readFileSync(filePath, 'utf-8');
-  } catch (err: any) {
-    if (err?.code === 'ENOENT') return null;
-    throw err;
-  }
-  const state = deserializeSessionState(raw);
-  if (!state) {
-    // Boot fresh, keep the evidence: the corrupt file moves to .corrupt so a
-    // 3-week-later bug report is reconstructable from the artifact.
-    console.warn(`[browse] SESSION_STATE_INVALID: corrupt ${filePath} moved to .corrupt; starting fresh`);
-    quarantineCorrupt(filePath);
-    return null;
-  }
-  // launch() opens one blank tab; replace it rather than restoring alongside.
-  await bm.closeAllPages();
-  await bm.restoreState(state);
-  return state;
-}

package/.agent/skills/gstack-browse/src/skill-token.ts

@@ -1,91 +0,0 @@
-/**
- * Skill-token — scoped tokens minted per `$B skill run` invocation.
- *
- * Why this exists:
- *   When `$B skill run <name>` spawns a browser-skill script, the script needs
- *   to call back into the daemon over loopback HTTP. It MUST NOT receive the
- *   daemon root token — a script that gets the root token can call any endpoint
- *   with full authority, defeating the trusted/untrusted distinction.
- *
- *   This module wraps `token-registry.ts` to mint per-spawn session tokens
- *   bound to read+write scope (the 17-cmd browser-driving surface, minus the
- *   `eval`/`js`/admin commands that live in the admin scope). The token's
- *   clientId encodes the skill name and spawn id, so revocation is
- *   deterministic when the script exits or times out.
- *
- * Lifecycle:
- *   spawn start → mintSkillToken() → set GSTACK_SKILL_TOKEN in child env
- *                                  ↓
- *   script makes HTTP calls       /command with Bearer <skill-token>
- *                                  ↓
- *   spawn exit / timeout         → revokeSkillToken() → token invalidated
- *
- * Why scopes = ['read', 'write']:
- *   These map to SCOPE_READ + SCOPE_WRITE in token-registry.ts and cover
- *   navigation, reading, and interaction commands the bulk of skills need.
- *   Excludes admin (eval/js/cookies/storage) deliberately — agent-authored
- *   skills should not get arbitrary JS execution. Phase 2 may add an opt-in
- *   `admin: true` frontmatter flag for cases that genuinely need it, gated
- *   by stronger review at skillify time.
- *
- * Zero side effects on import. Safe to import from tests.
- */
-
-import * as crypto from 'crypto';
-import { createToken, revokeToken, type ScopeCategory, type TokenInfo } from './token-registry';
-
-/** Length of TTL slack (in seconds) past the spawn timeout. */
-const TOKEN_TTL_SLACK = 30;
-
-/** Default scopes for skill tokens. Excludes `admin` (eval/js) and `control`. */
-const DEFAULT_SKILL_SCOPES: ScopeCategory[] = ['read', 'write'];
-
-/** Generate a fresh spawn id. Caller passes this to spawn AND revoke. */
-export function generateSpawnId(): string {
-  return crypto.randomBytes(8).toString('hex');
-}
-
-/** Build the canonical clientId for a skill spawn. */
-export function skillClientId(skillName: string, spawnId: string): string {
-  return `skill:${skillName}:${spawnId}`;
-}
-
-export interface MintSkillTokenOptions {
-  skillName: string;
-  spawnId: string;
-  /** Spawn timeout in seconds. Token TTL = timeout + 30s slack. */
-  spawnTimeoutSeconds: number;
-  /**
-   * Override the default scopes. Phase 1 callers should not pass this; reserved
-   * for future opt-in flags (e.g. an `admin: true` frontmatter for trusted
-   * human-authored skills that need eval/js).
-   */
-  scopes?: ScopeCategory[];
-}
-
-/**
- * Mint a fresh scoped token for a skill spawn.
- *
- * Returns the token info; the caller passes `info.token` to the child via the
- * GSTACK_SKILL_TOKEN env var. The clientId is deterministic from skillName +
- * spawnId so the corresponding `revokeSkillToken()` always finds the right
- * record.
- */
-export function mintSkillToken(opts: MintSkillTokenOptions): TokenInfo {
-  const clientId = skillClientId(opts.skillName, opts.spawnId);
-  return createToken({
-    clientId,
-    scopes: opts.scopes ?? DEFAULT_SKILL_SCOPES,
-    tabPolicy: 'shared',          // skill scripts may switch tabs as needed
-    rateLimit: 0,                  // skill scripts can run as fast as the daemon allows
-    expiresSeconds: opts.spawnTimeoutSeconds + TOKEN_TTL_SLACK,
-  });
-}
-
-/**
- * Revoke the token for a finished spawn. Idempotent — revoking an already-revoked
- * token returns false but is not an error.
- */
-export function revokeSkillToken(skillName: string, spawnId: string): boolean {
-  return Boolean(revokeToken(skillClientId(skillName, spawnId)));
-}

package/.agent/skills/gstack-browse/src/snapshot-flags.ts

@@ -1,30 +0,0 @@
-export interface SnapshotOptions {
-  interactive?: boolean;
-  compact?: boolean;
-  depth?: number;
-  selector?: string;
-  diff?: boolean;
-  annotate?: boolean;
-  outputPath?: string;
-  cursorInteractive?: boolean;
-  heatmap?: string;
-}
-
-export const SNAPSHOT_FLAGS: Array<{
-  short: string;
-  long: string;
-  description: string;
-  takesValue?: boolean;
-  valueHint?: string;
-  optionKey: keyof SnapshotOptions;
-}> = [
-  { short: '-i', long: '--interactive', description: 'Interactive elements only (buttons, links, inputs) with @e refs. Also auto-enables cursor-interactive scan (-C) to capture dropdowns and popovers.', optionKey: 'interactive' },
-  { short: '-c', long: '--compact', description: 'Compact (no empty structural nodes)', optionKey: 'compact' },
-  { short: '-d', long: '--depth', description: 'Limit tree depth (0 = root only, default: unlimited)', takesValue: true, valueHint: '<N>', optionKey: 'depth' },
-  { short: '-s', long: '--selector', description: 'Scope to CSS selector', takesValue: true, valueHint: '<sel>', optionKey: 'selector' },
-  { short: '-D', long: '--diff', description: 'Unified diff against previous snapshot (first call stores baseline)', optionKey: 'diff' },
-  { short: '-a', long: '--annotate', description: 'Annotated screenshot with red overlay boxes and ref labels', optionKey: 'annotate' },
-  { short: '-o', long: '--output', description: 'Output path for annotated screenshot (default: <temp>/browse-annotated.png)', takesValue: true, valueHint: '<path>', optionKey: 'outputPath' },
-  { short: '-C', long: '--cursor-interactive', description: 'Cursor-interactive elements (@c refs — divs with pointer, onclick). Auto-enabled when -i is used.', optionKey: 'cursorInteractive' },
-  { short: '-H', long: '--heatmap', description: 'Color-coded overlay screenshot from JSON map: \'{"@e1":"green","@e3":"red"}\'. Valid colors: green, yellow, red, blue, orange, gray.', takesValue: true, valueHint: '<json>', optionKey: 'heatmap' },
-];