browser-commander 0.17.2 → 0.18.0

package/tests/unit/downloads/naming.test.js

@@ -0,0 +1,174 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import path from 'node:path';
+
+import {
+  extensionFromContent,
+  isInsideRoot,
+  renamedCandidate,
+  resolveInsideRoot,
+  sanitizeDownloadName,
+  withExtension,
+} from '../../../src/downloads/naming.js';
+
+describe('download naming (issue #88)', () => {
+  describe('sanitizeDownloadName', () => {
+    it('should keep an ordinary name unchanged', () => {
+      assert.strictEqual(
+        sanitizeDownloadName('quarterly report.pdf'),
+        'quarterly report.pdf'
+      );
+    });
+
+    it('should refuse to let a page choose a directory', () => {
+      // A suggested filename is page-controlled input. `../../etc/passwd` is a
+      // request to write outside the download root, not a name.
+      assert.strictEqual(sanitizeDownloadName('../../etc/passwd'), 'passwd');
+      assert.strictEqual(
+        sanitizeDownloadName('C:\\Windows\\system32\\evil.exe'),
+        'evil.exe'
+      );
+      assert.strictEqual(sanitizeDownloadName('/etc/shadow'), 'shadow');
+    });
+
+    it('should strip control characters a name should never contain', () => {
+      assert.strictEqual(
+        sanitizeDownloadName('re\u0000port\u001f.pdf'),
+        'report.pdf'
+      );
+    });
+
+    it('should fall back when the page suggests nothing usable', () => {
+      assert.strictEqual(sanitizeDownloadName(''), 'download');
+      assert.strictEqual(sanitizeDownloadName('..'), 'download');
+      assert.strictEqual(sanitizeDownloadName('   '), 'download');
+      assert.strictEqual(sanitizeDownloadName(undefined), 'download');
+    });
+
+    it('should not slow down on a name padded with whitespace', () => {
+      // The padding used to be stripped with `/^\s+|[\s.]+$/`, whose second
+      // half retries from every position of a whitespace run that never
+      // reaches the end. A page chooses this string, so the cost is an
+      // attacker's to set: 40k spaces took 2.8 seconds before the trimming
+      // walked in from both ends instead, which takes under a millisecond.
+      const hostile = `report${' '.repeat(40_000)}x`;
+
+      const started = performance.now();
+      assert.strictEqual(sanitizeDownloadName(hostile), hostile);
+      assert.ok(performance.now() - started < 500);
+    });
+
+    it('should defuse reserved device names', () => {
+      // `con.txt` is unopenable on Windows, and a library that produces a file
+      // nobody can open has not really downloaded anything.
+      assert.strictEqual(sanitizeDownloadName('con.txt'), '_con.txt');
+      assert.strictEqual(sanitizeDownloadName('LPT1'), '_LPT1');
+    });
+  });
+
+  describe('withExtension', () => {
+    it('should leave a name that already has an extension alone', () => {
+      assert.strictEqual(
+        withExtension({ name: 'report.pdf', mimeType: 'text/csv' }),
+        'report.pdf'
+      );
+    });
+
+    it('should name a UUID-like download from its declared type', () => {
+      assert.strictEqual(
+        withExtension({
+          name: '3f2b7c1e-0a41-4f2a-9a55-7b1c2d3e4f50',
+          mimeType: 'application/pdf; charset=binary',
+        }),
+        '3f2b7c1e-0a41-4f2a-9a55-7b1c2d3e4f50.pdf'
+      );
+    });
+
+    it('should fall back to the bytes when the server declared nothing', () => {
+      assert.strictEqual(
+        withExtension({
+          name: 'mystery',
+          head: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2d]),
+        }),
+        'mystery.pdf'
+      );
+    });
+
+    it('should trust the bytes over a generic binary type', () => {
+      // `application/octet-stream` is what a server sends when it cannot name
+      // the format either, so it must not win over a PDF signature and leave
+      // the caller with a `.bin` file it cannot open.
+      assert.strictEqual(
+        withExtension({
+          name: '3f2b7c1e-0a41-4f2a-9a55-7b1c2d3e4f50',
+          mimeType: 'application/octet-stream',
+          head: Buffer.from([0x25, 0x50, 0x44, 0x46, 0x2d]),
+        }),
+        '3f2b7c1e-0a41-4f2a-9a55-7b1c2d3e4f50.pdf'
+      );
+    });
+
+    it('should still name a truly unidentifiable binary download', () => {
+      assert.strictEqual(
+        withExtension({
+          name: 'payload',
+          mimeType: 'application/octet-stream',
+          head: Buffer.from([0x01, 0x02]),
+        }),
+        'payload.bin'
+      );
+    });
+
+    it('should leave the name alone when nothing identifies the format', () => {
+      assert.strictEqual(
+        withExtension({ name: 'mystery', head: Buffer.from([0x01, 0x02]) }),
+        'mystery'
+      );
+    });
+  });
+
+  describe('extensionFromContent', () => {
+    it('should identify formats by their leading bytes', () => {
+      assert.strictEqual(
+        extensionFromContent(Buffer.from([0x89, 0x50, 0x4e, 0x47])),
+        '.png'
+      );
+      assert.strictEqual(
+        extensionFromContent(Buffer.from([0x50, 0x4b, 0x03, 0x04])),
+        '.zip'
+      );
+      assert.strictEqual(extensionFromContent(Buffer.alloc(0)), '');
+      assert.strictEqual(extensionFromContent(undefined), '');
+    });
+  });
+
+  describe('root containment', () => {
+    const root = path.resolve('/tmp/downloads');
+
+    it('should accept a file inside the root', () => {
+      assert.strictEqual(isInsideRoot(root, `${root}/report.pdf`), true);
+    });
+
+    it('should reject the root itself and anything outside it', () => {
+      assert.strictEqual(isInsideRoot(root, root), false);
+      assert.strictEqual(isInsideRoot(root, '/tmp/report.pdf'), false);
+      assert.strictEqual(isInsideRoot(root, `${root}/../report.pdf`), false);
+    });
+
+    it('should refuse to resolve a path that escapes the root', () => {
+      assert.throws(
+        () => resolveInsideRoot(root, '../escaped.pdf'),
+        /outside the download directory/
+      );
+    });
+  });
+
+  describe('renamedCandidate', () => {
+    it('should number collisions deterministically', () => {
+      assert.strictEqual(renamedCandidate('report.pdf', 0), 'report.pdf');
+      assert.strictEqual(renamedCandidate('report.pdf', 1), 'report (2).pdf');
+      assert.strictEqual(renamedCandidate('report.pdf', 2), 'report (3).pdf');
+      assert.strictEqual(renamedCandidate('archive', 1), 'archive (2)');
+    });
+  });
+});

package/tests/unit/downloads/store.test.js

@@ -0,0 +1,215 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+
+import {
+  cleanPartials,
+  DOWNLOAD_CONFLICT,
+  saveDownload,
+} from '../../../src/downloads/store.js';
+import { useTempDownloadDirectory } from '../../helpers/download-fixtures.js';
+import { assertMode } from '../../helpers/file-modes.js';
+
+/**
+ * A download source made of literal bytes.
+ *
+ * @param {string|Buffer} body - File contents
+ * @returns {Object} Source accepted by `saveDownload`
+ */
+const bytes = (body) => ({ stream: Readable.from([Buffer.from(body)]) });
+
+describe('download store (issue #88)', () => {
+  const directory = useTempDownloadDirectory();
+
+  /**
+   * List the files currently in the download root.
+   *
+   * @returns {Promise<string[]>} Sorted entry names
+   */
+  const listing = async () => (await fs.readdir(directory.path)).sort();
+
+  /**
+   * Save two downloads that suggest the same name.
+   *
+   * @param {string} [conflict] - Conflict policy for the second one
+   * @returns {Promise<Object>} What the second save reported
+   */
+  const saveTwice = async (conflict) => {
+    await saveDownload({
+      root: directory.path,
+      source: bytes('first'),
+      suggestedFilename: 'report.pdf',
+    });
+    return saveDownload({
+      root: directory.path,
+      source: bytes('second'),
+      suggestedFilename: 'report.pdf',
+      conflict,
+    });
+  };
+
+  it('should save a download under its suggested name', async () => {
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('report body'),
+      suggestedFilename: 'report.pdf',
+    });
+
+    assert.strictEqual(saved.path, path.join(directory.path, 'report.pdf'));
+    assert.strictEqual(saved.bytes, 11);
+    assert.strictEqual(
+      saved.checksum,
+      createHash('sha256').update('report body').digest('hex')
+    );
+    assert.strictEqual(await fs.readFile(saved.path, 'utf8'), 'report body');
+  });
+
+  it('should write the file with owner-only permissions', async () => {
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('secret'),
+      suggestedFilename: 'secret.txt',
+    });
+
+    await assertMode(saved.path, 0o600);
+  });
+
+  it('should number a colliding name instead of replacing the file', async () => {
+    const second = await saveTwice();
+
+    assert.strictEqual(path.basename(second.path), 'report (2).pdf');
+    assert.deepStrictEqual(await listing(), ['report (2).pdf', 'report.pdf']);
+    assert.strictEqual(
+      await fs.readFile(path.join(directory.path, 'report.pdf'), 'utf8'),
+      'first'
+    );
+  });
+
+  it('should replace the file when the caller asked for overwrite', async () => {
+    const second = await saveTwice(DOWNLOAD_CONFLICT.OVERWRITE);
+
+    assert.deepStrictEqual(await listing(), ['report.pdf']);
+    assert.strictEqual(await fs.readFile(second.path, 'utf8'), 'second');
+  });
+
+  it('should refuse a collision when the caller asked for error', async () => {
+    await assert.rejects(
+      saveTwice(DOWNLOAD_CONFLICT.ERROR),
+      /refusing to replace/
+    );
+    assert.deepStrictEqual(await listing(), ['report.pdf']);
+  });
+
+  it('should keep a traversal attempt inside the download root', async () => {
+    // A naming callback expresses a preference, not a grant of write access:
+    // the path part is dropped and only the leaf name survives.
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('payload'),
+      suggestedFilename: 'safe.txt',
+      filename: () => '../../escaped.txt',
+    });
+
+    assert.strictEqual(saved.path, path.join(directory.path, 'escaped.txt'));
+    const parent = await fs.readdir(path.dirname(directory.path));
+    assert.ok(!parent.includes('escaped.txt'));
+  });
+
+  it('should refuse a page-suggested name that points outside the root', async () => {
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('payload'),
+      suggestedFilename: '../../../etc/passwd',
+    });
+
+    assert.strictEqual(saved.path, path.join(directory.path, 'passwd'));
+  });
+
+  // Issue #88: "a half-written or invalid artifact must never appear under
+  // the final name". A validator rejects either by throwing or by answering
+  // `false`, and neither may leave anything behind.
+  const rejections = [
+    {
+      title: 'validation throws',
+      expected: /expected a PDF/,
+      validate: ({ bytes: size }) => {
+        if (size < 1000) {
+          throw new Error('expected a PDF, got a login page');
+        }
+      },
+    },
+    {
+      title: 'validation answers false',
+      expected: /rejected by the caller/,
+      validate: ({ mimeType }) => mimeType === 'application/pdf',
+    },
+  ];
+
+  for (const { title, expected, validate } of rejections) {
+    it(`should leave no file behind when ${title}`, async () => {
+      await assert.rejects(
+        saveDownload({
+          root: directory.path,
+          source: bytes('<html>login page</html>'),
+          suggestedFilename: 'invoice.pdf',
+          mimeType: 'text/html',
+          validate,
+        }),
+        expected
+      );
+
+      assert.deepStrictEqual(await listing(), []);
+    });
+  }
+
+  it('should hand validation the real bytes before publishing them', async () => {
+    const seen = [];
+    await saveDownload({
+      root: directory.path,
+      source: bytes('%PDF-1.7 body'),
+      suggestedFilename: 'invoice',
+      mimeType: 'application/pdf',
+      validate: async (details) => {
+        seen.push({
+          ...details,
+          head: (await fs.readFile(details.path)).subarray(0, 4).toString(),
+        });
+      },
+    });
+
+    assert.strictEqual(seen.length, 1);
+    assert.strictEqual(seen[0].head, '%PDF');
+    assert.strictEqual(seen[0].bytes, 13);
+    // Validation sees the partial file, never the published name.
+    assert.ok(seen[0].path.endsWith('.partial'));
+    assert.deepStrictEqual(await listing(), ['invoice.pdf']);
+  });
+
+  it('should let a caller name the file without losing the safety rules', async () => {
+    const saved = await saveDownload({
+      root: directory.path,
+      source: bytes('payload'),
+      suggestedFilename: '8d0f9e2c-4a11-4b22-9f00-1d2e3f405162',
+      mimeType: 'application/pdf',
+      filename: ({ suggestedFilename }) => `invoice-${suggestedFilename}`,
+    });
+
+    assert.strictEqual(
+      path.basename(saved.path),
+      'invoice-8d0f9e2c-4a11-4b22-9f00-1d2e3f405162.pdf'
+    );
+  });
+
+  it('should clean up partial files left by an interrupted run', async () => {
+    const stale = path.join(directory.path, 'report.pdf.1234.partial');
+    await fs.writeFile(stale, 'half');
+
+    const removed = await cleanPartials(directory.path);
+
+    assert.deepStrictEqual(removed, [stale]);
+    assert.deepStrictEqual(await listing(), []);
+  });
+});

package/tests/unit/interactions/click-activation.test.js

@@ -0,0 +1,283 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  CLICK_ACTIVATION,
+  CLICK_SCROLL,
+  CLICK_ACTIONABILITY,
+  ScrollConstraintError,
+  resolveActivationOptions,
+  measureClickPoint,
+  readScrollPosition,
+  restoreScrollPosition,
+  dispatchClick,
+} from '../../../src/interactions/click-activation.js';
+import { createMockLogger } from '../../helpers/mocks.js';
+import {
+  IN_VIEWPORT_POINT,
+  createScrollModel,
+} from '../../helpers/click-fixtures.js';
+
+/**
+ * Adapter stub that records what the engine was asked to do and models a
+ * scroll position the engine may move.
+ *
+ * @param {Object} [options] - Stub configuration
+ * @param {Object} [options.point] - Geometry returned by the click-point probe
+ * @param {number} [options.scrollOnClick] - Scroll position the engine click lands on
+ * @param {boolean} [options.hasEvaluateOnPage] - Whether the adapter exposes `evaluateOnPage`
+ * @returns {Object} Adapter stub
+ */
+function createAdapter(options = {}) {
+  const {
+    point = IN_VIEWPORT_POINT,
+    scrollOnClick = 0,
+    hasEvaluateOnPage = true,
+  } = options;
+
+  const calls = { click: [], domClick: 0 };
+  const scroll = createScrollModel();
+
+  const adapter = {
+    calls,
+    click: async (el, opts) => {
+      calls.click.push(opts);
+      scroll.set(scrollOnClick);
+    },
+    evaluateOnElement: async (el, fn) => {
+      if (typeof fn === 'function' && fn.length === 1) {
+        // The DOM-activation path passes `el => el.click()`.
+        const source = fn.toString();
+        if (source.includes('.click()')) {
+          calls.domClick += 1;
+          return undefined;
+        }
+      }
+      return { ...point, scroll: { x: 0, y: scroll.current() } };
+    },
+  };
+
+  if (hasEvaluateOnPage) {
+    adapter.evaluateOnPage = scroll.evaluateOnPage;
+  }
+
+  adapter.currentScrollY = scroll.current;
+  return adapter;
+}
+
+/**
+ * Page stub that records real pointer clicks.
+ *
+ * @returns {Object} Page stub
+ */
+function createPage() {
+  const clicks = [];
+  return { clicks, mouse: { click: async (x, y) => clicks.push({ x, y }) } };
+}
+
+/**
+ * Build the page/adapter pair and a `dispatchClick` invoker for one scenario.
+ *
+ * @param {Object} [options] - Scenario configuration
+ * @param {Object} [options.adapter] - Options forwarded to {@link createAdapter}
+ * @param {Object} [options.activation] - Options forwarded to `resolveActivationOptions`
+ * @returns {{page: Object, adapter: Object, dispatch: Function}} Scenario handle
+ */
+function scenario(options = {}) {
+  const page = createPage();
+  const adapter = createAdapter(options.adapter);
+
+  const dispatch = () =>
+    dispatchClick({
+      page,
+      adapter,
+      locatorOrElement: {},
+      activationOptions: resolveActivationOptions(options.activation),
+    });
+
+  return { page, adapter, dispatch };
+}
+
+describe('click activation', () => {
+  describe('resolveActivationOptions', () => {
+    it('should default to a pointer click that may scroll', () => {
+      const resolved = resolveActivationOptions();
+      assert.strictEqual(resolved.activation, CLICK_ACTIVATION.POINTER);
+      assert.strictEqual(resolved.scroll, CLICK_SCROLL.AUTO);
+      assert.strictEqual(resolved.actionability, CLICK_ACTIONABILITY.NORMAL);
+      assert.deepStrictEqual(resolved.deprecations, []);
+    });
+
+    it('should map the deprecated noAutoScroll onto scroll semantics', () => {
+      // Regression test for issue #89: noAutoScroll used to mean
+      // `{ force: true }`, which is an actionability flag, not a scroll flag.
+      const on = resolveActivationOptions({ noAutoScroll: true });
+      assert.strictEqual(on.scroll, CLICK_SCROLL.NONE);
+      assert.strictEqual(on.actionability, CLICK_ACTIONABILITY.NORMAL);
+      assert.strictEqual(on.deprecations.length, 1);
+      assert.ok(on.deprecations[0].includes('noAutoScroll is deprecated'));
+
+      const off = resolveActivationOptions({ noAutoScroll: false });
+      assert.strictEqual(off.scroll, CLICK_SCROLL.AUTO);
+    });
+
+    it('should let an explicit scroll option win over noAutoScroll', () => {
+      const resolved = resolveActivationOptions({
+        noAutoScroll: true,
+        scroll: CLICK_SCROLL.PRESERVE,
+      });
+      assert.strictEqual(resolved.scroll, CLICK_SCROLL.PRESERVE);
+    });
+
+    it('should log the deprecation notice when a logger is supplied', () => {
+      const log = createMockLogger({ collectLogs: true });
+      resolveActivationOptions({ noAutoScroll: true, log });
+      const messages = log.getLogs().map((entry) => entry.message);
+      assert.ok(messages.some((message) => message.includes('deprecated')));
+    });
+
+    it('should reject unknown values on every axis', () => {
+      assert.throws(
+        () => resolveActivationOptions({ activation: 'telepathy' }),
+        /activation must be one of/u
+      );
+      assert.throws(
+        () => resolveActivationOptions({ scroll: 'maybe' }),
+        /scroll must be one of/u
+      );
+      assert.throws(
+        () => resolveActivationOptions({ actionability: 'hard' }),
+        /actionability must be one of/u
+      );
+    });
+  });
+
+  describe('measureClickPoint', () => {
+    it('should report the element centre and hit-test result', async () => {
+      const adapter = createAdapter();
+      const point = await measureClickPoint({
+        adapter,
+        locatorOrElement: {},
+      });
+      assert.strictEqual(point.x, 50);
+      assert.strictEqual(point.y, 60);
+      assert.strictEqual(point.inViewport, true);
+      assert.strictEqual(point.hitsTarget, true);
+    });
+  });
+
+  describe('scroll position helpers', () => {
+    it('should tolerate an adapter without evaluateOnPage', async () => {
+      const adapter = createAdapter({ hasEvaluateOnPage: false });
+      assert.strictEqual(await readScrollPosition(adapter), null);
+      await restoreScrollPosition(adapter, { x: 0, y: 10 });
+    });
+
+    it('should tolerate an adapter that throws', async () => {
+      const adapter = {
+        evaluateOnPage: async () => {
+          throw new Error('context destroyed');
+        },
+      };
+      assert.strictEqual(await readScrollPosition(adapter), null);
+    });
+
+    it('should do nothing when there is no position to restore', async () => {
+      const adapter = createAdapter();
+      await restoreScrollPosition(adapter, null);
+      assert.strictEqual(adapter.currentScrollY(), 0);
+    });
+  });
+
+  describe('dispatchClick', () => {
+    it('should send force to the engine only for actionability: force', async () => {
+      const normal = scenario();
+      await normal.dispatch();
+      assert.deepStrictEqual(normal.adapter.calls.click, [{}]);
+
+      const forced = scenario({
+        activation: { actionability: CLICK_ACTIONABILITY.FORCE },
+      });
+      await forced.dispatch();
+      assert.deepStrictEqual(forced.adapter.calls.click, [{ force: true }]);
+    });
+
+    it('should restore the scroll position for scroll: preserve', async () => {
+      // The engine is free to scroll; the caller asked for the viewport to end
+      // up where it started.
+      const { adapter, dispatch } = scenario({
+        adapter: { scrollOnClick: 3911 },
+        activation: { scroll: CLICK_SCROLL.PRESERVE },
+      });
+
+      const detail = await dispatch();
+
+      assert.strictEqual(adapter.currentScrollY(), 0);
+      assert.strictEqual(detail.scrollAfter.y, 0);
+    });
+
+    it('should use a real pointer at the element point for scroll: none', async () => {
+      // Regression test for issue #89: `{ force: true }` still scrolled
+      // (scrollY 0 -> 3911 in the live repro). A mouse click at the measured
+      // point cannot scroll at all.
+      const { page, adapter, dispatch } = scenario({
+        adapter: { scrollOnClick: 3911 },
+        activation: { scroll: CLICK_SCROLL.NONE },
+      });
+
+      const detail = await dispatch();
+
+      assert.deepStrictEqual(page.clicks, [{ x: 50, y: 60 }]);
+      assert.deepStrictEqual(adapter.calls.click, []);
+      assert.strictEqual(adapter.currentScrollY(), 0);
+      assert.strictEqual(detail.scrollBefore.y, detail.scrollAfter.y);
+    });
+
+    it('should refuse scroll: none when the element is off-screen', async () => {
+      const { page, dispatch } = scenario({
+        adapter: {
+          point: {
+            ...IN_VIEWPORT_POINT,
+            y: 4000,
+            top: 3980,
+            inViewport: false,
+            hitsTarget: false,
+          },
+        },
+        activation: { scroll: CLICK_SCROLL.NONE },
+      });
+
+      await assert.rejects(dispatch, (error) => {
+        assert.ok(error instanceof ScrollConstraintError);
+        assert.ok(error.message.includes('outside the viewport'));
+        assert.ok(error.message.includes('scroll: "preserve"'));
+        assert.strictEqual(error.detail.inViewport, false);
+        return true;
+      });
+      assert.deepStrictEqual(page.clicks, []);
+    });
+
+    it('should refuse scroll: none when another element covers the target', async () => {
+      const { page, dispatch } = scenario({
+        adapter: { point: { ...IN_VIEWPORT_POINT, hitsTarget: false } },
+        activation: { scroll: CLICK_SCROLL.NONE },
+      });
+
+      await assert.rejects(dispatch, /covers the target/u);
+      assert.deepStrictEqual(page.clicks, []);
+    });
+
+    it('should dispatch an untrusted DOM click for activation: dom', async () => {
+      const { page, adapter, dispatch } = scenario({
+        activation: { activation: CLICK_ACTIVATION.DOM },
+      });
+
+      const detail = await dispatch();
+
+      assert.strictEqual(adapter.calls.domClick, 1);
+      assert.deepStrictEqual(adapter.calls.click, []);
+      assert.deepStrictEqual(page.clicks, []);
+      assert.strictEqual(detail.mode, CLICK_ACTIVATION.DOM);
+      assert.strictEqual(detail.point, null);
+    });
+  });
+});