Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

8.3 KB
Raw Blame
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import {
  approveInstall,
  blockInstall,
  blockOf,
  isApproved,
  labelSession,
  listBlocked,
  mintGrantCode,
  unblockInstall,
  claimSession,
  clearAuth,
  consumePairing,
  createPairing,
  createSession,
  hasPendingPairing,
  listSessions,
  pendingPairings,
  revokeSessions,
  sessionCandidates,
  sessionId,
  type Install,
} from './auth-store';
import { stateDir } from './lockfile';
import { bits, modeOf } from './test/modes';

const authPath = join(stateDir, 'auth.json');
const extension = 'chrome-extension://abcdefghijklmnopabcdefghijklmnop';

const chrome: Install = { installId: 'install-chrome-0001', origin: extension, extensionVersion: '0.6.2', browser: 'Google Chrome' };
const brave: Install = { installId: 'install-brave-00001', origin: extension, extensionVersion: '0.6.2', browser: 'Brave' };
const firefox: Install = { installId: 'install-firefox-001', origin: 'moz-extension://firefox-uuid', extensionVersion: '0.6.2' };

/** What auth.json holds for a browser paired before the extension sent an install id. */
function pairedBeforeInstallIds(origin: string): string {
  const key = 'k'.repeat(43);
  const legacy = { key, origin, extensionVersion: '0.6.1', pairedAt: '2026-09-01T00:00:00.000Z', lastSeenAt: '2026-09-01T00:00:00.000Z' };
  writeFileSync(authPath, JSON.stringify({ pairings: [], sessions: [legacy] }));
  return key;
}

beforeEach(() => {
  mkdirSync(stateDir, { recursive: true });
  clearAuth();
});

afterEach(() => {
  vi.useRealTimers();
});

describe('pairing codes', () => {
  test('a code is eight characters that cannot be misread, valid for ten minutes', () => {
    vi.useFakeTimers({ now: new Date('2026-09-21T10:00:00Z') });
    const { code, expiresAt } = createPairing();
    expect([/^[ABCDEFGHJKMNPQRSTWXYZ23456789]{8}$/.test(code), expiresAt - Date.now()]).toEqual([true, 10 * 60_000]);
  });

  test('a new code leaves the two before it working, and retires the oldest of four', () => {
    const codes = [createPairing(), createPairing(), createPairing(), createPairing()].map(({ code }) => code);
    expect(pendingPairings()).toEqual(codes.slice(1));
  });

  test('a code stops being pending once it expires', () => {
    vi.useFakeTimers({ now: new Date('2026-09-21T10:00:00Z') });
    createPairing();
    vi.setSystemTime(new Date('2026-09-21T10:10:01Z'));
    expect([pendingPairings(), hasPendingPairing()]).toEqual([[], false]);
  });

  test('a code can be used once', () => {
    const { code } = createPairing();
    consumePairing(code);
    expect(hasPendingPairing()).toBe(false);
  });
});

describe('sessions', () => {
  test('pairing gives the browser a 256-bit key, bound to its install id', () => {
    const session = createSession(chrome);
    expect([Buffer.from(session.key, 'base64url').length, sessionCandidates(chrome)]).toEqual([32, [session]]);
  });

  test('pairing the same browser again replaces its key rather than adding a second', () => {
    const first = createSession({ ...chrome, extensionVersion: '0.6.1' });
    const second = createSession(chrome);
    expect([listSessions(), first.key === second.key]).toEqual([[second], false]);
  });

  test('a second browser loading the same folder shares the origin and still pairs beside the first', () => {
    const first = createSession(chrome);
    const second = createSession(brave);
    expect([listSessions(), sessionCandidates(chrome), sessionCandidates(brave)]).toEqual([[first, second], [first], [second]]);
  });

  test('seeing a browser again updates when it was last seen and what it is running, and keeps its key', () => {
    vi.useFakeTimers({ now: new Date('2026-09-21T10:00:00Z') });
    const paired = createSession({ ...chrome, extensionVersion: '0.6.1' });
    vi.setSystemTime(new Date('2026-09-21T12:00:00Z'));
    claimSession(paired.key, chrome);
    expect(listSessions()).toEqual([{ ...paired, extensionVersion: '0.6.2', lastSeenAt: '2026-09-21T12:00:00.000Z' }]);
  });

  test('a key nobody holds claims nothing', () => {
    claimSession('no-such-key', chrome);
    expect(listSessions()).toEqual([]);
  });

  test('a browser paired before install ids is found by its origin, and named by it until it returns', () => {
    const key = pairedBeforeInstallIds(extension);
    expect([sessionCandidates(chrome).map((session) => session.key), listSessions().map(sessionId)]).toEqual([[key], [extension]]);
  });

  test('its first return claims that session, after which no other browser on the origin is offered it', () => {
    const key = pairedBeforeInstallIds(extension);
    claimSession(key, chrome);
    expect([listSessions().map(sessionId), sessionCandidates(brave)]).toEqual([[chrome.installId], []]);
  });

  test('revoking removes the sessions that match, and says how many', () => {
    createSession(chrome);
    createSession(firefox);
    expect([revokeSessions((session) => session.origin.startsWith('moz-')), listSessions().map((session) => session.origin)]).toEqual([1, [extension]]);
  });

  test('a revoked browser has no key left to present', () => {
    createSession(chrome);
    revokeSessions(() => true);
    expect(sessionCandidates(chrome)).toEqual([]);
  });
});

describe('the file', () => {
  test('is readable only by the user', () => {
    createSession(chrome);
    expect(modeOf(authPath)).toBe(bits(0o600));
  });

  test('a damaged file pairs nothing, and the next write replaces it', () => {
    writeFileSync(authPath, '{"sessions": [');
    const session = createSession(chrome);
    expect(JSON.parse(readFileSync(authPath, 'utf8'))).toEqual({ pairings: [], sessions: [session], approved: [], blocked: [] });
  });

  test('clearing it forgets every browser', () => {
    createSession(chrome);
    clearAuth();
    expect([existsSync(authPath), listSessions()]).toEqual([false, []]);
  });
});

describe('automatic pairing', () => {
  test('a grant is a long code in the typed alphabet', () => {
    expect(mintGrantCode()).toMatch(/^[ABCDEFGHJKMNPQRSTWXYZ23456789]{26}$/);
  });

  test('a session says how it was paired, by code unless told otherwise', () => {
    expect(createSession(chrome).pairedBy).toBe('code');
    expect(createSession(brave, 'auto').pairedBy).toBe('auto');
  });

  test('revoking keeps a browser out and forgets that it was allowed', () => {
    approveInstall(chrome);
    createSession(chrome);
    revokeSessions((session) => session.installId === chrome.installId);

    expect(blockOf(chrome.installId)).toMatchObject({ reason: 'revoked', origin: extension, browser: 'Google Chrome' });
    expect(isApproved(chrome.installId)).toBe(false);
  });

  test('a session paired before install ids is revoked without leaving a block nobody can name', () => {
    pairedBeforeInstallIds(extension);
    revokeSessions(() => true);
    expect(listBlocked()).toEqual([]);
  });

  test('pairing again, or allowing it, lifts a block', () => {
    blockInstall(chrome, 'denied');
    createSession(chrome);
    expect(blockOf(chrome.installId)).toBeUndefined();

    blockInstall(brave, 'revoked');
    approveInstall(brave);
    expect([blockOf(brave.installId), isApproved(brave.installId)]).toEqual([undefined, true]);
  });

  test('unblocking says whether there was a block', () => {
    blockInstall(chrome, 'revoked');
    expect([unblockInstall(chrome.installId), unblockInstall(chrome.installId)]).toEqual([true, false]);
  });

  test('keeps the newest two hundred blocks', () => {
    for (let index = 0; index < 205; index++) blockInstall({ ...chrome, installId: `install-block-${String(index).padStart(5, '0')}` }, 'revoked');
    const blocked = listBlocked();
    expect([blocked.length, blocked[0].installId]).toEqual([200, 'install-block-00005']);
  });

  test('a name chosen when allowing a browser is the name its session takes', () => {
    approveInstall({ ...chrome, label: 'Work Chrome' });
    expect(createSession(chrome).label).toBe('Work Chrome');
  });

  test('a paired browser can be named and the name cleared', () => {
    createSession(chrome);
    expect(labelSession(chrome.installId, '  Home\u0007 laptop ')).toBe(true);
    expect(listSessions()[0].label).toBe('Home laptop');
    expect(labelSession(chrome.installId, '')).toBe(true);
    expect(listSessions()[0].label).toBeUndefined();
    expect(labelSession('nobody', 'x')).toBe(false);
  });
});