@monoes/monobrowse 1.0.6 → 1.0.7

package/src/__tests__/frame-command.test.ts

@@ -0,0 +1,98 @@
+/**
+ * frame command (#97) — switching to an iframe must retain the OOPIF
+ * sessionId returned by switchToFrame so subsequent commands act on the
+ * frame, and `frame main` must detach the frame session and restore the
+ * page session. The browser engine is mocked; no real Chrome.
+ */
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import type { Command, CommandContext } from '../cli/types.js';
+
+const mocks = vi.hoisted(() => {
+  const send = vi.fn(async (_method: string, _params?: unknown, _sid?: string) => ({}));
+  const client = { send, isConnected: () => true, close: vi.fn() };
+  return {
+    send,
+    client,
+    browser: {
+      launchBrowser: vi.fn(async () => 9222),
+      connectToTarget: vi.fn(async () => ({
+        client,
+        sessionId: 'S-PAGE',
+        target: { id: 'T-PAGE', url: 'https://x.test' },
+      })),
+      loadActivePortInfo: vi.fn(async () => null),
+      loadRefCache: vi.fn(async () => null),
+      switchToFrame: vi.fn(async (): Promise<{ url: string | null; sessionId: string | null }> => ({ url: 'https://f.test/frame', sessionId: 'S-FRAME' })),
+      enableSessionDomains: vi.fn(async () => {}),
+      teardownRouteInterception: vi.fn(),
+      stopRequestCapture: vi.fn(),
+      teardownDialogHandling: vi.fn(),
+      teardownConsoleCapture: vi.fn(),
+    },
+  };
+});
+
+vi.mock('../index.js', () => mocks.browser);
+
+async function loadFrameCommand(): Promise<Command> {
+  const mod = (await import('../cli/commands.js')).default;
+  const cmd = mod.subcommands!.find((c) => c.name === 'frame');
+  if (!cmd?.action) throw new Error('frame command not found');
+  return cmd;
+}
+
+const ctx = (args: string[]): CommandContext => ({
+  args,
+  flags: { _: [] },
+  cwd: process.cwd(),
+  interactive: false,
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.browser.loadActivePortInfo.mockResolvedValue(null);
+  mocks.browser.loadRefCache.mockResolvedValue(null);
+  mocks.browser.switchToFrame.mockResolvedValue({ url: 'https://f.test/frame', sessionId: 'S-FRAME' });
+  mocks.browser.connectToTarget.mockResolvedValue({
+    client: mocks.client,
+    sessionId: 'S-PAGE',
+    target: { id: 'T-PAGE', url: 'https://x.test' },
+  });
+});
+
+describe('browse frame command (#97)', () => {
+  it('stores the OOPIF sessionId, enables its domains, and `frame main` detaches it and restores the page session', async () => {
+    vi.resetModules();
+    const frame = await loadFrameCommand();
+
+    // Enter the frame — engine reports the OOPIF session
+    await frame.action!(ctx(['iframe']));
+    expect(mocks.browser.switchToFrame).toHaveBeenCalledWith(mocks.client, 'S-PAGE', 'iframe');
+    expect(mocks.browser.enableSessionDomains).toHaveBeenCalledWith(mocks.client, 'S-FRAME');
+
+    // Back to main — must detach the FRAME session (proves _sessionId was updated)
+    await frame.action!(ctx(['main']));
+    const detach = mocks.send.mock.calls.find(
+      ([m]) => m === 'Target.detachFromTarget'
+    );
+    expect(detach).toBeDefined();
+    expect(detach![1]).toEqual({ sessionId: 'S-FRAME' });
+
+    // Entering a frame again must start from the restored page session
+    await frame.action!(ctx(['iframe']));
+    expect(mocks.browser.switchToFrame).toHaveBeenLastCalledWith(mocks.client, 'S-PAGE', 'iframe');
+  });
+
+  it('keeps the page session when the frame has no OOPIF target', async () => {
+    vi.resetModules();
+    mocks.browser.switchToFrame.mockResolvedValue({ url: 'https://f.test/frame', sessionId: null });
+    const frame = await loadFrameCommand();
+
+    await frame.action!(ctx(['iframe']));
+    expect(mocks.browser.enableSessionDomains).not.toHaveBeenCalled();
+
+    // `frame main` with no stored parent session must not detach anything
+    await frame.action!(ctx(['main']));
+    expect(mocks.send.mock.calls.some(([m]) => m === 'Target.detachFromTarget')).toBe(false);
+  });
+});

package/src/__tests__/ref-cache.test.ts

@@ -138,13 +138,13 @@ describe('active-port persistence', () => {
     const mod = await importRefCache();
     await mod.saveActivePort(9333);
     expect(await mod.loadActivePort()).toBe(9333);
-    expect(await mod.loadActivePortInfo()).toEqual({ port: 9333, launched: true });
+    expect(await mod.loadActivePortInfo()).toEqual({ port: 9333, launched: true, savedAt: expect.any(Number) });
   });
 
   it('connect provenance: launched:false survives the round-trip', async () => {
     const mod = await importRefCache();
     await mod.saveActivePort(9229, { launched: false });
-    expect(await mod.loadActivePortInfo()).toEqual({ port: 9229, launched: false });
+    expect(await mod.loadActivePortInfo()).toEqual({ port: 9229, launched: false, savedAt: expect.any(Number) });
   });
 
   it('clear removes the file; load returns null afterwards', async () => {
@@ -161,6 +161,51 @@ describe('active-port persistence', () => {
     await expect(mod.clearActivePort()).resolves.toBeUndefined();
   });
 
+  it('#115: pid and userDataDir persist and round-trip so a later process can kill an orphaned launch', async () => {
+    const mod = await importRefCache();
+    await mod.saveActivePort(9333, { pid: 54321, userDataDir: '/tmp/monomind-browser-9333' });
+    expect(await mod.loadActivePortInfo()).toEqual({
+      port: 9333,
+      launched: true,
+      pid: 54321,
+      userDataDir: '/tmp/monomind-browser-9333',
+      savedAt: expect.any(Number),
+    });
+  });
+
+  it('#115: an attached (launched:false) session with no pid argument persists none', async () => {
+    const mod = await importRefCache();
+    await mod.saveActivePort(9229, { launched: false });
+    const info = await mod.loadActivePortInfo();
+    expect(info!.launched).toBe(false);
+    expect(info!.pid).toBeUndefined();
+  });
+
+  it('#124-review: saveActivePort does NOT strip pid when launched:false — callers must not pass one for an attach', async () => {
+    // The property above (attach sessions have no pid) is caller discipline,
+    // not something this function enforces — the one production caller
+    // (commands.ts's `connect` action) simply never passes a pid alongside
+    // launched:false. This test documents that explicitly so it can't be
+    // mistaken for an invariant the code itself guarantees.
+    const mod = await importRefCache();
+    await mod.saveActivePort(9229, { launched: false, pid: 4242 });
+    const info = await mod.loadActivePortInfo();
+    expect(info!.launched).toBe(false);
+    expect(info!.pid).toBe(4242);
+  });
+
+  it('#115: a non-numeric or non-positive persisted pid is dropped, not trusted', async () => {
+    const mod = await importRefCache();
+    const { writeFile, mkdir } = await import('fs/promises');
+    const dir = join(process.cwd(), '.monomind', 'monobrowse');
+    await mkdir(dir, { recursive: true });
+    for (const badPid of ['54321', -1, 0, 1.5, null]) {
+      await writeFile(join(dir, 'active-port.json'), JSON.stringify({ port: 9333, launched: true, pid: badPid }));
+      const info = await mod.loadActivePortInfo();
+      expect(info!.pid).toBeUndefined();
+    }
+  });
+
   it('rejects out-of-range or non-integer persisted ports', async () => {
     const mod = await importRefCache();
     const { writeFile, mkdir } = await import('fs/promises');

package/src/__tests__/session-state.test.ts

@@ -0,0 +1,251 @@
+/**
+ * session.ts — the path-safety guards and the state-file round trip.
+ *
+ * Session files hold cookies and localStorage, so the traversal guards and the
+ * 0600/0700 permission bits are security-relevant. All of it is filesystem +
+ * validation logic: the CdpClient is a stub that answers the handful of CDP
+ * commands the round trip issues.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtemp, rm, readFile, stat, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import type { CdpClient } from '../browser/cdp.js';
+import {
+  saveStateFile,
+  loadStateFile,
+  saveSession,
+  loadSession,
+  listSessions,
+} from '../browser/session.js';
+
+const COOKIES = [{ name: 'sid', value: 'abc', domain: 'x.test', path: '/' }];
+
+/** Records every CDP command and answers the ones session.ts depends on. */
+function stubClient(): { client: CdpClient; calls: Array<{ method: string; params: unknown; sid?: string }> } {
+  const calls: Array<{ method: string; params: unknown; sid?: string }> = [];
+  const client = {
+    send: vi.fn(async (method: string, params: unknown, sid?: string) => {
+      calls.push({ method, params, sid });
+      if (method === 'Network.getCookies') return { cookies: COOKIES };
+      if (method === 'Runtime.evaluate') {
+        const expr = (params as { expression: string }).expression;
+        if (expr.includes('Object.entries(localStorage)')) return { result: { value: '{"k":"v"}' } };
+        if (expr.includes('Object.entries(sessionStorage)')) return { result: { value: '{"s":"1"}' } };
+      }
+      return {};
+    }),
+  } as unknown as CdpClient;
+  return { client, calls };
+}
+
+let dir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'monobrowse-session-'));
+});
+
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('validateSessionName (via saveSession/loadSession)', () => {
+  const { client } = stubClient();
+
+  // Rejection happens before any filesystem or CDP work, so these never touch
+  // the real ~/.monomind directory.
+  const bad: Array<[string, string]> = [
+    ['empty', ''],
+    ['forward slash', 'a/b'],
+    ['backslash', 'a\\b'],
+    ['NUL byte', 'a\x00b'],
+    ['dot', '.'],
+    ['dot-dot', '..'],
+    ['dot-dot prefix', '..evil'],
+    ['traversal', '../../etc/passwd'],
+  ];
+
+  for (const [label, name] of bad) {
+    it(`rejects ${label}`, async () => {
+      await expect(saveSession(client, 'S1', 'T1', name, 'https://x.test', 'T')).rejects.toThrow(
+        /Invalid session name/
+      );
+      await expect(loadSession(client, 'S1', name)).rejects.toThrow(/Invalid session name/);
+    });
+  }
+
+  it('accepts an ordinary name (fails later, on the missing file, not on validation)', async () => {
+    await expect(loadSession(client, 'S1', 'no-such-session-xyz')).rejects.toThrow(
+      'Session not found: no-such-session-xyz'
+    );
+  });
+
+  it('does not issue a single CDP command for a rejected name', async () => {
+    const { client: c, calls } = stubClient();
+    await expect(saveSession(c, 'S1', 'T1', '../x', 'https://x.test', 'T')).rejects.toThrow();
+    expect(calls).toEqual([]);
+  });
+});
+
+describe('validateFilePath (via saveStateFile/loadStateFile)', () => {
+  const { client } = stubClient();
+
+  const bad: Array<[string, string]> = [
+    ['empty', ''],
+    ['NUL byte', '/tmp/a\x00b.json'],
+    ['embedded ..', '/tmp/a/../../etc/passwd'],
+    ['leading ../', '../secret.json'],
+    ['trailing /..', '/tmp/state/..'],
+    ['backslash', 'C:\\Windows\\state.json'],
+  ];
+
+  for (const [label, filePath] of bad) {
+    it(`rejects ${label}`, async () => {
+      await expect(
+        saveStateFile(client, 'S1', 'T1', filePath, 'https://x.test', 'T')
+      ).rejects.toThrow(/Invalid file path/);
+      await expect(loadStateFile(client, 'S1', filePath)).rejects.toThrow(/Invalid file path/);
+    });
+  }
+
+  it('allows a plain absolute path', async () => {
+    const p = join(dir, 'state.json');
+    await expect(saveStateFile(client, 'S1', 'T1', p, 'https://x.test', 'T')).resolves.toBeUndefined();
+  });
+});
+
+describe('state file round trip', () => {
+  it('captures cookies plus local/session storage and writes owner-only (0600)', async () => {
+    const { client, calls } = stubClient();
+    const p = join(dir, 'nested', 'state.json');
+    await saveStateFile(client, 'S1', 'T1', p, 'https://x.test', 'Page Title');
+
+    const state = JSON.parse(await readFile(p, 'utf8'));
+    expect(state).toEqual({
+      targetId: 'T1',
+      sessionId: 'S1',
+      url: 'https://x.test',
+      title: 'Page Title',
+      cookies: COOKIES,
+      localStorage: { k: 'v' },
+      sessionStorage: { s: '1' },
+    });
+
+    expect((await stat(p)).mode & 0o777).toBe(0o600);
+    // Parent directory created owner-only too.
+    expect((await stat(join(dir, 'nested'))).mode & 0o777).toBe(0o700);
+
+    // Cookies were scoped to the page URL, not fetched globally.
+    expect(calls.find((c) => c.method === 'Network.getCookies')?.params).toEqual({
+      urls: ['https://x.test'],
+    });
+  });
+
+  it('replays cookies and both storages back into the page on load', async () => {
+    const saver = stubClient();
+    const p = join(dir, 'state.json');
+    await saveStateFile(saver.client, 'S1', 'T1', p, 'https://x.test', 'T');
+
+    const loader = stubClient();
+    const state = await loadStateFile(loader.client, 'S2', p);
+    expect(state.cookies).toEqual(COOKIES);
+
+    const setCookies = loader.calls.find((c) => c.method === 'Network.setCookies');
+    expect(setCookies).toMatchObject({ params: { cookies: COOKIES }, sid: 'S2' });
+
+    const scripts = loader.calls
+      .filter((c) => c.method === 'Runtime.evaluate')
+      .map((c) => (c.params as { expression: string }).expression);
+    expect(scripts).toContain('localStorage.setItem("k", "v")');
+    expect(scripts).toContain('sessionStorage.setItem("s", "1")');
+  });
+
+  it('rejects a state file whose cookies field is not an array', async () => {
+    const { client } = stubClient();
+    const p = join(dir, 'bad.json');
+    const { writeFile } = await import('fs/promises');
+    await writeFile(p, JSON.stringify({ cookies: { name: 'sid' } }));
+    await expect(loadStateFile(client, 'S1', p)).rejects.toThrow(
+      'Invalid state file: cookies is not an array'
+    );
+  });
+
+  it('rejects a state file whose localStorage is an array rather than an object', async () => {
+    const { client } = stubClient();
+    const p = join(dir, 'bad2.json');
+    const { writeFile } = await import('fs/promises');
+    await writeFile(p, JSON.stringify({ cookies: [], localStorage: ['nope'] }));
+    await expect(loadStateFile(client, 'S1', p)).rejects.toThrow(
+      'Invalid state file: localStorage is not a plain object'
+    );
+  });
+
+  it('rejects a state file whose sessionStorage is an array', async () => {
+    const { client } = stubClient();
+    const p = join(dir, 'bad3.json');
+    const { writeFile } = await import('fs/promises');
+    await writeFile(p, JSON.stringify({ cookies: [], sessionStorage: ['nope'] }));
+    await expect(loadStateFile(client, 'S1', p)).rejects.toThrow(
+      'Invalid state file: sessionStorage is not a plain object'
+    );
+  });
+
+  it('accepts a state file with neither storage map present', async () => {
+    const { client, calls } = stubClient();
+    const p = join(dir, 'minimal.json');
+    const { writeFile } = await import('fs/promises');
+    await writeFile(p, JSON.stringify({ targetId: 'T', sessionId: 'S', url: '', title: '', cookies: [] }));
+    await expect(loadStateFile(client, 'S1', p)).resolves.toMatchObject({ cookies: [] });
+    expect(calls.filter((c) => c.method === 'Runtime.evaluate')).toEqual([]);
+  });
+});
+
+describe('listSessions', () => {
+  // SESSION_DIR is computed from homedir() at module load, so each case
+  // re-imports session.js with 'os' mocked to point at a temp home.
+  async function withHome(home: string): Promise<typeof import('../browser/session.js')> {
+    vi.resetModules();
+    const actualOs = await vi.importActual<typeof import('os')>('os');
+    vi.doMock('os', () => ({ ...actualOs, default: actualOs, homedir: () => home }));
+    return import('../browser/session.js');
+  }
+
+  afterEach(() => {
+    vi.doUnmock('os');
+    vi.resetModules();
+  });
+
+  it('returns [] when the session directory does not exist', async () => {
+    const mod = await withHome(join(dir, 'no-such-home'));
+    await expect(mod.listSessions()).resolves.toEqual([]);
+  });
+
+  it('lists only .json files, with the extension stripped', async () => {
+    const sessionDir = join(dir, '.monomind', 'browser-sessions');
+    await mkdir(sessionDir, { recursive: true });
+    const { writeFile } = await import('fs/promises');
+    await writeFile(join(sessionDir, 'alpha.json'), '{}');
+    await writeFile(join(sessionDir, 'beta.json'), '{}');
+    await writeFile(join(sessionDir, 'notes.txt'), 'ignore me');
+
+    const mod = await withHome(dir);
+    await expect(mod.listSessions()).resolves.toEqual(['alpha', 'beta']);
+  });
+
+  it('saveSession writes into the session dir and loadSession reads it back', async () => {
+    const mod = await withHome(dir);
+    const saver = stubClient();
+    const filePath = await mod.saveSession(saver.client, 'S1', 'T1', 'my-session', 'https://x.test', 'T');
+    expect(filePath).toBe(join(dir, '.monomind', 'browser-sessions', 'my-session.json'));
+    expect((await stat(filePath)).mode & 0o777).toBe(0o600);
+    expect((await stat(join(dir, '.monomind', 'browser-sessions'))).mode & 0o777).toBe(0o700);
+
+    const loader = stubClient();
+    await expect(mod.loadSession(loader.client, 'S2', 'my-session')).resolves.toMatchObject({
+      cookies: COOKIES,
+      url: 'https://x.test',
+    });
+    await expect(mod.listSessions()).resolves.toEqual(['my-session']);
+  });
+});