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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
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);
});
});