@runchr/gstack-antigravity 0.1.1 → 0.1.3

package/.agents/skills/gstack/browse/src/commands.ts

@@ -0,0 +1,111 @@
+/**
+ * Command registry — single source of truth for all browse commands.
+ *
+ * Dependency graph:
+ *   commands.ts ──▶ server.ts (runtime dispatch)
+ *                ──▶ gen-skill-docs.ts (doc generation)
+ *                ──▶ skill-parser.ts (validation)
+ *                ──▶ skill-check.ts (health reporting)
+ *
+ * Zero side effects. Safe to import from build scripts and tests.
+ */
+
+export const READ_COMMANDS = new Set([
+  'text', 'html', 'links', 'forms', 'accessibility',
+  'js', 'eval', 'css', 'attrs',
+  'console', 'network', 'cookies', 'storage', 'perf',
+  'dialog', 'is',
+]);
+
+export const WRITE_COMMANDS = new Set([
+  'goto', 'back', 'forward', 'reload',
+  'click', 'fill', 'select', 'hover', 'type', 'press', 'scroll', 'wait',
+  'viewport', 'cookie', 'cookie-import', 'cookie-import-browser', 'header', 'useragent',
+  'upload', 'dialog-accept', 'dialog-dismiss',
+]);
+
+export const META_COMMANDS = new Set([
+  'tabs', 'tab', 'newtab', 'closetab',
+  'status', 'stop', 'restart',
+  'screenshot', 'pdf', 'responsive',
+  'chain', 'diff',
+  'url', 'snapshot',
+  'handoff', 'resume',
+]);
+
+export const ALL_COMMANDS = new Set([...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS]);
+
+export const COMMAND_DESCRIPTIONS: Record<string, { category: string; description: string; usage?: string }> = {
+  // Navigation
+  'goto':    { category: 'Navigation', description: 'Navigate to URL', usage: 'goto <url>' },
+  'back':    { category: 'Navigation', description: 'History back' },
+  'forward': { category: 'Navigation', description: 'History forward' },
+  'reload':  { category: 'Navigation', description: 'Reload page' },
+  'url':     { category: 'Navigation', description: 'Print current URL' },
+  // Reading
+  'text':    { category: 'Reading', description: 'Cleaned page text' },
+  'html':    { category: 'Reading', description: 'innerHTML of selector (throws if not found), or full page HTML if no selector given', usage: 'html [selector]' },
+  'links':   { category: 'Reading', description: 'All links as "text → href"' },
+  'forms':   { category: 'Reading', description: 'Form fields as JSON' },
+  'accessibility': { category: 'Reading', description: 'Full ARIA tree' },
+  // Inspection
+  'js':      { category: 'Inspection', description: 'Run JavaScript expression and return result as string', usage: 'js <expr>' },
+  'eval':    { category: 'Inspection', description: 'Run JavaScript from file and return result as string (path must be under /tmp or cwd)', usage: 'eval <file>' },
+  'css':     { category: 'Inspection', description: 'Computed CSS value', usage: 'css <sel> <prop>' },
+  'attrs':   { category: 'Inspection', description: 'Element attributes as JSON', usage: 'attrs <sel|@ref>' },
+  'is':      { category: 'Inspection', description: 'State check (visible/hidden/enabled/disabled/checked/editable/focused)', usage: 'is <prop> <sel>' },
+  'console': { category: 'Inspection', description: 'Console messages (--errors filters to error/warning)', usage: 'console [--clear|--errors]' },
+  'network': { category: 'Inspection', description: 'Network requests', usage: 'network [--clear]' },
+  'dialog':  { category: 'Inspection', description: 'Dialog messages', usage: 'dialog [--clear]' },
+  'cookies': { category: 'Inspection', description: 'All cookies as JSON' },
+  'storage': { category: 'Inspection', description: 'Read all localStorage + sessionStorage as JSON, or set <key> <value> to write localStorage', usage: 'storage [set k v]' },
+  'perf':    { category: 'Inspection', description: 'Page load timings' },
+  // Interaction
+  'click':   { category: 'Interaction', description: 'Click element', usage: 'click <sel>' },
+  'fill':    { category: 'Interaction', description: 'Fill input', usage: 'fill <sel> <val>' },
+  'select':  { category: 'Interaction', description: 'Select dropdown option by value, label, or visible text', usage: 'select <sel> <val>' },
+  'hover':   { category: 'Interaction', description: 'Hover element', usage: 'hover <sel>' },
+  'type':    { category: 'Interaction', description: 'Type into focused element', usage: 'type <text>' },
+  'press':   { category: 'Interaction', description: 'Press key — Enter, Tab, Escape, ArrowUp/Down/Left/Right, Backspace, Delete, Home, End, PageUp, PageDown, or modifiers like Shift+Enter', usage: 'press <key>' },
+  'scroll':  { category: 'Interaction', description: 'Scroll element into view, or scroll to page bottom if no selector', usage: 'scroll [sel]' },
+  'wait':    { category: 'Interaction', description: 'Wait for element, network idle, or page load (timeout: 15s)', usage: 'wait <sel|--networkidle|--load>' },
+  'upload':  { category: 'Interaction', description: 'Upload file(s)', usage: 'upload <sel> <file> [file2...]' },
+  'viewport':{ category: 'Interaction', description: 'Set viewport size', usage: 'viewport <WxH>' },
+  'cookie':  { category: 'Interaction', description: 'Set cookie on current page domain', usage: 'cookie <name>=<value>' },
+  'cookie-import': { category: 'Interaction', description: 'Import cookies from JSON file', usage: 'cookie-import <json>' },
+  'cookie-import-browser': { category: 'Interaction', description: 'Import cookies from Comet, Chrome, Arc, Brave, or Edge (opens picker, or use --domain for direct import)', usage: 'cookie-import-browser [browser] [--domain d]' },
+  'header':  { category: 'Interaction', description: 'Set custom request header (colon-separated, sensitive values auto-redacted)', usage: 'header <name>:<value>' },
+  'useragent': { category: 'Interaction', description: 'Set user agent', usage: 'useragent <string>' },
+  'dialog-accept': { category: 'Interaction', description: 'Auto-accept next alert/confirm/prompt. Optional text is sent as the prompt response', usage: 'dialog-accept [text]' },
+  'dialog-dismiss': { category: 'Interaction', description: 'Auto-dismiss next dialog' },
+  // Visual
+  'screenshot': { category: 'Visual', description: 'Save screenshot (supports element crop via CSS/@ref, --clip region, --viewport)', usage: 'screenshot [--viewport] [--clip x,y,w,h] [selector|@ref] [path]' },
+  'pdf':     { category: 'Visual', description: 'Save as PDF', usage: 'pdf [path]' },
+  'responsive': { category: 'Visual', description: 'Screenshots at mobile (375x812), tablet (768x1024), desktop (1280x720). Saves as {prefix}-mobile.png etc.', usage: 'responsive [prefix]' },
+  'diff':    { category: 'Visual', description: 'Text diff between pages', usage: 'diff <url1> <url2>' },
+  // Tabs
+  'tabs':    { category: 'Tabs', description: 'List open tabs' },
+  'tab':     { category: 'Tabs', description: 'Switch to tab', usage: 'tab <id>' },
+  'newtab':  { category: 'Tabs', description: 'Open new tab', usage: 'newtab [url]' },
+  'closetab':{ category: 'Tabs', description: 'Close tab', usage: 'closetab [id]' },
+  // Server
+  'status':  { category: 'Server', description: 'Health check' },
+  'stop':    { category: 'Server', description: 'Shutdown server' },
+  'restart': { category: 'Server', description: 'Restart server' },
+  // Meta
+  'snapshot':{ category: 'Snapshot', description: 'Accessibility tree with @e refs for element selection. Flags: -i interactive only, -c compact, -d N depth limit, -s sel scope, -D diff vs previous, -a annotated screenshot, -o path output, -C cursor-interactive @c refs', usage: 'snapshot [flags]' },
+  'chain':   { category: 'Meta', description: 'Run commands from JSON stdin. Format: [["cmd","arg1",...],...]' },
+  // Handoff
+  'handoff': { category: 'Server', description: 'Open visible Chrome at current page for user takeover', usage: 'handoff [message]' },
+  'resume':  { category: 'Server', description: 'Re-snapshot after user takeover, return control to AI', usage: 'resume' },
+};
+
+// Load-time validation: descriptions must cover exactly the command sets
+const allCmds = new Set([...READ_COMMANDS, ...WRITE_COMMANDS, ...META_COMMANDS]);
+const descKeys = new Set(Object.keys(COMMAND_DESCRIPTIONS));
+for (const cmd of allCmds) {
+  if (!descKeys.has(cmd)) throw new Error(`COMMAND_DESCRIPTIONS missing entry for: ${cmd}`);
+}
+for (const key of descKeys) {
+  if (!allCmds.has(key)) throw new Error(`COMMAND_DESCRIPTIONS has unknown command: ${key}`);
+}

package/.agents/skills/gstack/browse/src/config.ts

@@ -0,0 +1,150 @@
+/**
+ * Shared config for browse CLI + server.
+ *
+ * Resolution:
+ *   1. BROWSE_STATE_FILE env → derive stateDir from parent
+ *   2. git rev-parse --show-toplevel → projectDir/.gstack/
+ *   3. process.cwd() fallback (non-git environments)
+ *
+ * The CLI computes the config and passes BROWSE_STATE_FILE to the
+ * spawned server. The server derives all paths from that env var.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface BrowseConfig {
+  projectDir: string;
+  stateDir: string;
+  stateFile: string;
+  consoleLog: string;
+  networkLog: string;
+  dialogLog: string;
+}
+
+/**
+ * Detect the git repository root, or null if not in a repo / git unavailable.
+ */
+export function getGitRoot(): string | null {
+  try {
+    const proc = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: 2_000, // Don't hang if .git is broken
+    });
+    if (proc.exitCode !== 0) return null;
+    return proc.stdout.toString().trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve all browse config paths.
+ *
+ * If BROWSE_STATE_FILE is set (e.g. by CLI when spawning server, or by
+ * tests for isolation), all paths are derived from it. Otherwise, the
+ * project root is detected via git or cwd.
+ */
+export function resolveConfig(
+  env: Record<string, string | undefined> = process.env,
+): BrowseConfig {
+  let stateFile: string;
+  let stateDir: string;
+  let projectDir: string;
+
+  if (env.BROWSE_STATE_FILE) {
+    stateFile = env.BROWSE_STATE_FILE;
+    stateDir = path.dirname(stateFile);
+    projectDir = path.dirname(stateDir); // parent of .gstack/
+  } else {
+    projectDir = getGitRoot() || process.cwd();
+    stateDir = path.join(projectDir, '.gstack');
+    stateFile = path.join(stateDir, 'browse.json');
+  }
+
+  return {
+    projectDir,
+    stateDir,
+    stateFile,
+    consoleLog: path.join(stateDir, 'browse-console.log'),
+    networkLog: path.join(stateDir, 'browse-network.log'),
+    dialogLog: path.join(stateDir, 'browse-dialog.log'),
+  };
+}
+
+/**
+ * Create the .gstack/ state directory if it doesn't exist.
+ * Throws with a clear message on permission errors.
+ */
+export function ensureStateDir(config: BrowseConfig): void {
+  try {
+    fs.mkdirSync(config.stateDir, { recursive: true });
+  } catch (err: any) {
+    if (err.code === 'EACCES') {
+      throw new Error(`Cannot create state directory ${config.stateDir}: permission denied`);
+    }
+    if (err.code === 'ENOTDIR') {
+      throw new Error(`Cannot create state directory ${config.stateDir}: a file exists at that path`);
+    }
+    throw err;
+  }
+
+  // Ensure .gstack/ is in the project's .gitignore
+  const gitignorePath = path.join(config.projectDir, '.gitignore');
+  try {
+    const content = fs.readFileSync(gitignorePath, 'utf-8');
+    if (!content.match(/^\.gstack\/?$/m)) {
+      const separator = content.endsWith('\n') ? '' : '\n';
+      fs.appendFileSync(gitignorePath, `${separator}.gstack/\n`);
+    }
+  } catch (err: any) {
+    if (err.code !== 'ENOENT') {
+      // Write warning to server log (visible even in daemon mode)
+      const logPath = path.join(config.stateDir, 'browse-server.log');
+      try {
+        fs.appendFileSync(logPath, `[${new Date().toISOString()}] Warning: could not update .gitignore at ${gitignorePath}: ${err.message}\n`);
+      } catch {
+        // stateDir write failed too — nothing more we can do
+      }
+    }
+    // ENOENT (no .gitignore) — skip silently
+  }
+}
+
+/**
+ * Derive a slug from the git remote origin URL (owner-repo format).
+ * Falls back to the directory basename if no remote is configured.
+ */
+export function getRemoteSlug(): string {
+  try {
+    const proc = Bun.spawnSync(['git', 'remote', 'get-url', 'origin'], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: 2_000,
+    });
+    if (proc.exitCode !== 0) throw new Error('no remote');
+    const url = proc.stdout.toString().trim();
+    // SSH:   git@github.com:owner/repo.git → owner-repo
+    // HTTPS: https://github.com/owner/repo.git → owner-repo
+    const match = url.match(/[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
+    if (match) return `${match[1]}-${match[2]}`;
+    throw new Error('unparseable');
+  } catch {
+    const root = getGitRoot();
+    return path.basename(root || process.cwd());
+  }
+}
+
+/**
+ * Read the binary version (git SHA) from browse/dist/.version.
+ * Returns null if the file doesn't exist or can't be read.
+ */
+export function readVersionHash(execPath: string = process.execPath): string | null {
+  try {
+    const versionFile = path.resolve(path.dirname(execPath), '.version');
+    return fs.readFileSync(versionFile, 'utf-8').trim() || null;
+  } catch {
+    return null;
+  }
+}

package/.agents/skills/gstack/browse/src/cookie-import-browser.ts

@@ -0,0 +1,417 @@
+/**
+ * Chromium browser cookie import — read and decrypt cookies from real browsers
+ *
+ * Supports macOS Chromium-based browsers: Comet, Chrome, Arc, Brave, Edge.
+ * Pure logic module — no Playwright dependency, no HTTP concerns.
+ *
+ * Decryption pipeline (Chromium macOS "v10" format):
+ *
+ *   ┌──────────────────────────────────────────────────────────────────┐
+ *   │ 1. Keychain: `security find-generic-password -s "<svc>" -w`     │
+ *   │    → base64 password string                                     │
+ *   │                                                                  │
+ *   │ 2. Key derivation:                                               │
+ *   │    PBKDF2(password, salt="saltysalt", iter=1003, len=16, sha1)  │
+ *   │    → 16-byte AES key                                            │
+ *   │                                                                  │
+ *   │ 3. For each cookie with encrypted_value starting with "v10":    │
+ *   │    - Ciphertext = encrypted_value[3:]                           │
+ *   │    - IV = 16 bytes of 0x20 (space character)                    │
+ *   │    - Plaintext = AES-128-CBC-decrypt(key, iv, ciphertext)       │
+ *   │    - Remove PKCS7 padding                                       │
+ *   │    - Skip first 32 bytes (HMAC-SHA256 authentication tag)       │
+ *   │    - Remaining bytes = cookie value (UTF-8)                     │
+ *   │                                                                  │
+ *   │ 4. If encrypted_value is empty but `value` field is set,        │
+ *   │    use value directly (unencrypted cookie)                      │
+ *   │                                                                  │
+ *   │ 5. Chromium epoch: microseconds since 1601-01-01                │
+ *   │    Unix seconds = (epoch - 11644473600000000) / 1000000         │
+ *   │                                                                  │
+ *   │ 6. sameSite: 0→"None", 1→"Lax", 2→"Strict", else→"Lax"        │
+ *   └──────────────────────────────────────────────────────────────────┘
+ */
+
+import { Database } from 'bun:sqlite';
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// ─── Types ──────────────────────────────────────────────────────
+
+export interface BrowserInfo {
+  name: string;
+  dataDir: string;        // relative to ~/Library/Application Support/
+  keychainService: string;
+  aliases: string[];
+}
+
+export interface DomainEntry {
+  domain: string;
+  count: number;
+}
+
+export interface ImportResult {
+  cookies: PlaywrightCookie[];
+  count: number;
+  failed: number;
+  domainCounts: Record<string, number>;
+}
+
+export interface PlaywrightCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  expires: number;
+  secure: boolean;
+  httpOnly: boolean;
+  sameSite: 'Strict' | 'Lax' | 'None';
+}
+
+export class CookieImportError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public action?: 'retry',
+  ) {
+    super(message);
+    this.name = 'CookieImportError';
+  }
+}
+
+// ─── Browser Registry ───────────────────────────────────────────
+// Hardcoded — NEVER interpolate user input into shell commands.
+
+const BROWSER_REGISTRY: BrowserInfo[] = [
+  { name: 'Comet',  dataDir: 'Comet/',                       keychainService: 'Comet Safe Storage',          aliases: ['comet', 'perplexity'] },
+  { name: 'Chrome', dataDir: 'Google/Chrome/',                keychainService: 'Chrome Safe Storage',         aliases: ['chrome', 'google-chrome'] },
+  { name: 'Arc',    dataDir: 'Arc/User Data/',                keychainService: 'Arc Safe Storage',            aliases: ['arc'] },
+  { name: 'Brave',  dataDir: 'BraveSoftware/Brave-Browser/',  keychainService: 'Brave Safe Storage',          aliases: ['brave'] },
+  { name: 'Edge',   dataDir: 'Microsoft Edge/',               keychainService: 'Microsoft Edge Safe Storage', aliases: ['edge'] },
+];
+
+// ─── Key Cache ──────────────────────────────────────────────────
+// Cache derived AES keys per browser. First import per browser does
+// Keychain + PBKDF2. Subsequent imports reuse the cached key.
+
+const keyCache = new Map<string, Buffer>();
+
+// ─── Public API ─────────────────────────────────────────────────
+
+/**
+ * Find which browsers are installed (have a cookie DB on disk).
+ */
+export function findInstalledBrowsers(): BrowserInfo[] {
+  const appSupport = path.join(os.homedir(), 'Library', 'Application Support');
+  return BROWSER_REGISTRY.filter(b => {
+    const dbPath = path.join(appSupport, b.dataDir, 'Default', 'Cookies');
+    try { return fs.existsSync(dbPath); } catch { return false; }
+  });
+}
+
+/**
+ * List unique cookie domains + counts from a browser's DB. No decryption.
+ */
+export function listDomains(browserName: string, profile = 'Default'): { domains: DomainEntry[]; browser: string } {
+  const browser = resolveBrowser(browserName);
+  const dbPath = getCookieDbPath(browser, profile);
+  const db = openDb(dbPath, browser.name);
+  try {
+    const now = chromiumNow();
+    const rows = db.query(
+      `SELECT host_key AS domain, COUNT(*) AS count
+       FROM cookies
+       WHERE has_expires = 0 OR expires_utc > ?
+       GROUP BY host_key
+       ORDER BY count DESC`
+    ).all(now) as DomainEntry[];
+    return { domains: rows, browser: browser.name };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Decrypt and return Playwright-compatible cookies for specific domains.
+ */
+export async function importCookies(
+  browserName: string,
+  domains: string[],
+  profile = 'Default',
+): Promise<ImportResult> {
+  if (domains.length === 0) return { cookies: [], count: 0, failed: 0, domainCounts: {} };
+
+  const browser = resolveBrowser(browserName);
+  const derivedKey = await getDerivedKey(browser);
+  const dbPath = getCookieDbPath(browser, profile);
+  const db = openDb(dbPath, browser.name);
+
+  try {
+    const now = chromiumNow();
+    // Parameterized query — no SQL injection
+    const placeholders = domains.map(() => '?').join(',');
+    const rows = db.query(
+      `SELECT host_key, name, value, encrypted_value, path, expires_utc,
+              is_secure, is_httponly, has_expires, samesite
+       FROM cookies
+       WHERE host_key IN (${placeholders})
+         AND (has_expires = 0 OR expires_utc > ?)
+       ORDER BY host_key, name`
+    ).all(...domains, now) as RawCookie[];
+
+    const cookies: PlaywrightCookie[] = [];
+    let failed = 0;
+    const domainCounts: Record<string, number> = {};
+
+    for (const row of rows) {
+      try {
+        const value = decryptCookieValue(row, derivedKey);
+        const cookie = toPlaywrightCookie(row, value);
+        cookies.push(cookie);
+        domainCounts[row.host_key] = (domainCounts[row.host_key] || 0) + 1;
+      } catch {
+        failed++;
+      }
+    }
+
+    return { cookies, count: cookies.length, failed, domainCounts };
+  } finally {
+    db.close();
+  }
+}
+
+// ─── Internal: Browser Resolution ───────────────────────────────
+
+function resolveBrowser(nameOrAlias: string): BrowserInfo {
+  const needle = nameOrAlias.toLowerCase().trim();
+  const found = BROWSER_REGISTRY.find(b =>
+    b.aliases.includes(needle) || b.name.toLowerCase() === needle
+  );
+  if (!found) {
+    const supported = BROWSER_REGISTRY.flatMap(b => b.aliases).join(', ');
+    throw new CookieImportError(
+      `Unknown browser '${nameOrAlias}'. Supported: ${supported}`,
+      'unknown_browser',
+    );
+  }
+  return found;
+}
+
+function validateProfile(profile: string): void {
+  if (/[/\\]|\.\./.test(profile) || /[\x00-\x1f]/.test(profile)) {
+    throw new CookieImportError(
+      `Invalid profile name: '${profile}'`,
+      'bad_request',
+    );
+  }
+}
+
+function getCookieDbPath(browser: BrowserInfo, profile: string): string {
+  validateProfile(profile);
+  const appSupport = path.join(os.homedir(), 'Library', 'Application Support');
+  const dbPath = path.join(appSupport, browser.dataDir, profile, 'Cookies');
+  if (!fs.existsSync(dbPath)) {
+    throw new CookieImportError(
+      `${browser.name} is not installed (no cookie database at ${dbPath})`,
+      'not_installed',
+    );
+  }
+  return dbPath;
+}
+
+// ─── Internal: SQLite Access ────────────────────────────────────
+
+function openDb(dbPath: string, browserName: string): Database {
+  try {
+    return new Database(dbPath, { readonly: true });
+  } catch (err: any) {
+    if (err.message?.includes('SQLITE_BUSY') || err.message?.includes('database is locked')) {
+      return openDbFromCopy(dbPath, browserName);
+    }
+    if (err.message?.includes('SQLITE_CORRUPT') || err.message?.includes('malformed')) {
+      throw new CookieImportError(
+        `Cookie database for ${browserName} is corrupt`,
+        'db_corrupt',
+      );
+    }
+    throw err;
+  }
+}
+
+function openDbFromCopy(dbPath: string, browserName: string): Database {
+  const tmpPath = `/tmp/browse-cookies-${browserName.toLowerCase()}-${crypto.randomUUID()}.db`;
+  try {
+    fs.copyFileSync(dbPath, tmpPath);
+    // Also copy WAL and SHM if they exist (for consistent reads)
+    const walPath = dbPath + '-wal';
+    const shmPath = dbPath + '-shm';
+    if (fs.existsSync(walPath)) fs.copyFileSync(walPath, tmpPath + '-wal');
+    if (fs.existsSync(shmPath)) fs.copyFileSync(shmPath, tmpPath + '-shm');
+
+    const db = new Database(tmpPath, { readonly: true });
+    // Schedule cleanup after the DB is closed
+    const origClose = db.close.bind(db);
+    db.close = () => {
+      origClose();
+      try { fs.unlinkSync(tmpPath); } catch {}
+      try { fs.unlinkSync(tmpPath + '-wal'); } catch {}
+      try { fs.unlinkSync(tmpPath + '-shm'); } catch {}
+    };
+    return db;
+  } catch {
+    // Clean up on failure
+    try { fs.unlinkSync(tmpPath); } catch {}
+    throw new CookieImportError(
+      `Cookie database is locked (${browserName} may be running). Try closing ${browserName} first.`,
+      'db_locked',
+      'retry',
+    );
+  }
+}
+
+// ─── Internal: Keychain Access (async, 10s timeout) ─────────────
+
+async function getDerivedKey(browser: BrowserInfo): Promise<Buffer> {
+  const cached = keyCache.get(browser.keychainService);
+  if (cached) return cached;
+
+  const password = await getKeychainPassword(browser.keychainService);
+  const derived = crypto.pbkdf2Sync(password, 'saltysalt', 1003, 16, 'sha1');
+  keyCache.set(browser.keychainService, derived);
+  return derived;
+}
+
+async function getKeychainPassword(service: string): Promise<string> {
+  // Use async Bun.spawn with timeout to avoid blocking the event loop.
+  // macOS may show an Allow/Deny dialog that blocks until the user responds.
+  const proc = Bun.spawn(
+    ['security', 'find-generic-password', '-s', service, '-w'],
+    { stdout: 'pipe', stderr: 'pipe' },
+  );
+
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => {
+      proc.kill();
+      reject(new CookieImportError(
+        `macOS is waiting for Keychain permission. Look for a dialog asking to allow access to "${service}".`,
+        'keychain_timeout',
+        'retry',
+      ));
+    }, 10_000),
+  );
+
+  try {
+    const exitCode = await Promise.race([proc.exited, timeout]);
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    if (exitCode !== 0) {
+      // Distinguish denied vs not found vs other
+      const errText = stderr.trim().toLowerCase();
+      if (errText.includes('user canceled') || errText.includes('denied') || errText.includes('interaction not allowed')) {
+        throw new CookieImportError(
+          `Keychain access denied. Click "Allow" in the macOS dialog for "${service}".`,
+          'keychain_denied',
+          'retry',
+        );
+      }
+      if (errText.includes('could not be found') || errText.includes('not found')) {
+        throw new CookieImportError(
+          `No Keychain entry for "${service}". Is this a Chromium-based browser?`,
+          'keychain_not_found',
+        );
+      }
+      throw new CookieImportError(
+        `Could not read Keychain: ${stderr.trim()}`,
+        'keychain_error',
+        'retry',
+      );
+    }
+
+    return stdout.trim();
+  } catch (err) {
+    if (err instanceof CookieImportError) throw err;
+    throw new CookieImportError(
+      `Could not read Keychain: ${(err as Error).message}`,
+      'keychain_error',
+      'retry',
+    );
+  }
+}
+
+// ─── Internal: Cookie Decryption ────────────────────────────────
+
+interface RawCookie {
+  host_key: string;
+  name: string;
+  value: string;
+  encrypted_value: Buffer | Uint8Array;
+  path: string;
+  expires_utc: number | bigint;
+  is_secure: number;
+  is_httponly: number;
+  has_expires: number;
+  samesite: number;
+}
+
+function decryptCookieValue(row: RawCookie, key: Buffer): string {
+  // Prefer unencrypted value if present
+  if (row.value && row.value.length > 0) return row.value;
+
+  const ev = Buffer.from(row.encrypted_value);
+  if (ev.length === 0) return '';
+
+  const prefix = ev.slice(0, 3).toString('utf-8');
+  if (prefix !== 'v10') {
+    throw new Error(`Unknown encryption prefix: ${prefix}`);
+  }
+
+  const ciphertext = ev.slice(3);
+  const iv = Buffer.alloc(16, 0x20); // 16 space characters
+  const decipher = crypto.createDecipheriv('aes-128-cbc', key, iv);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+
+  // First 32 bytes are HMAC-SHA256 authentication tag; actual value follows
+  if (plaintext.length <= 32) return '';
+  return plaintext.slice(32).toString('utf-8');
+}
+
+function toPlaywrightCookie(row: RawCookie, value: string): PlaywrightCookie {
+  return {
+    name: row.name,
+    value,
+    domain: row.host_key,
+    path: row.path || '/',
+    expires: chromiumEpochToUnix(row.expires_utc, row.has_expires),
+    secure: row.is_secure === 1,
+    httpOnly: row.is_httponly === 1,
+    sameSite: mapSameSite(row.samesite),
+  };
+}
+
+// ─── Internal: Chromium Epoch Conversion ────────────────────────
+
+const CHROMIUM_EPOCH_OFFSET = 11644473600000000n;
+
+function chromiumNow(): bigint {
+  // Current time in Chromium epoch (microseconds since 1601-01-01)
+  return BigInt(Date.now()) * 1000n + CHROMIUM_EPOCH_OFFSET;
+}
+
+function chromiumEpochToUnix(epoch: number | bigint, hasExpires: number): number {
+  if (hasExpires === 0 || epoch === 0 || epoch === 0n) return -1; // session cookie
+  const epochBig = BigInt(epoch);
+  const unixMicro = epochBig - CHROMIUM_EPOCH_OFFSET;
+  return Number(unixMicro / 1000000n);
+}
+
+function mapSameSite(value: number): 'Strict' | 'Lax' | 'None' {
+  switch (value) {
+    case 0: return 'None';
+    case 1: return 'Lax';
+    case 2: return 'Strict';
+    default: return 'Lax';
+  }
+}