Skip to content

The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.

JavaScript
9.1 KB
Raw Blame
"""The capture extension's own folder: the copy the app writes and can rewrite.

The interesting cases are all failure shapes, and one of them only happens on
Windows: a browser holding a file open while the app tries to replace it. That
one is forced here rather than waited for, because the invariant it protects —
never a half-written extension — is the whole reason the install is staged.
"""

from __future__ import annotations

import json
import os
from pathlib import Path

import pytest

from azimut import config
from azimut.engine import dirswap, extinstall


@pytest.fixture()
def folder(tmp_workspace) -> Path:
    """The app-owned extension folder, in a throwaway workspace root — nothing
    here touches a real installation."""
    return config.extension_dir()


def stamp_of(folder: Path) -> dict:
    return json.loads((folder / extinstall.STAMP_NAME).read_text(encoding="utf-8"))


# -- installing ---------------------------------------------------------------


def test_install_writes_every_shipped_file_and_stamps_it(folder):
    state = extinstall.install()

    src = extinstall.source_dir()
    assert src is not None
    for name, _ in extinstall.shipped_files(src):
        assert (folder / name).is_file(), f"{name} was not written"
    assert state["staged"] is False
    assert state["path"] == str(folder)
    # The stamp answers "is this the copy the app controls", so it carries an id,
    # and "is it behind", so it carries the digest.
    stamp = stamp_of(folder)
    assert stamp["payload"] == extinstall.payload_digest()
    assert stamp["version"] == extinstall.bundled_version()
    assert len(stamp["install_id"]) == 32
    assert state["folder"] == stamp


def test_the_stamp_is_never_part_of_the_payload(folder):
    """It is per-install, so shipping it would make every install differ from
    every other — and the digest gate would never settle."""
    extinstall.install()
    src = extinstall.source_dir()
    assert src is not None
    assert extinstall.STAMP_NAME not in {name for name, _ in extinstall.shipped_files(src)}
    # Nor does installing leave one behind in the source tree (a checkout is the
    # repo's own extension/, which devext.py loads straight into a dev browser).
    assert not (src / extinstall.STAMP_NAME).exists()


def test_a_second_pass_keeps_the_install_id(folder):
    """The id belongs to the folder, not to a payload. Chrome keys storage to the
    extension and the extension to the folder, so an id that moved would read as
    a different install and the analyst would be asked to pair again."""
    first = stamp_of(folder) if folder.exists() else None
    assert first is None
    extinstall.install()
    original = stamp_of(folder)["install_id"]
    extinstall.install()
    assert stamp_of(folder)["install_id"] == original


def test_install_removes_what_the_payload_no_longer_ships(folder):
    extinstall.install()
    stale = folder / "gone.js"
    stale.write_text("old content script", encoding="utf-8")
    nested = folder / "icons" / "gone.png"
    nested.write_bytes(b"stale")

    extinstall.install()

    assert not stale.exists()
    assert not nested.exists()
    assert (folder / "manifest.json").is_file()  # the real payload is untouched


def test_state_reads_without_installing(folder):
    state = extinstall.state()
    assert state["folder"] is None
    assert state["staged"] is False
    assert state["bundled"]["payload"] == extinstall.payload_digest()
    assert not folder.exists()  # a read must not create anything


def test_a_foreign_folder_reports_no_stamp(folder):
    """Someone else's unzip, or a checkout: files are there, the stamp is not, so
    the app knows it does not own this copy."""
    folder.mkdir(parents=True)
    (folder / "manifest.json").write_text('{"version": "0.0.1"}', encoding="utf-8")
    assert extinstall.state()["folder"] is None


def test_an_unreadable_stamp_reads_as_no_stamp(folder):
    extinstall.install()
    (folder / extinstall.STAMP_NAME).write_text("{ not json", encoding="utf-8")
    assert extinstall.state()["folder"] is None


# -- a browser holding the files (Windows) ------------------------------------


def _refuse_after(count: int, monkeypatch: pytest.MonkeyPatch) -> dict:
    """Let `count` replacements through, then refuse every one — the shape of a
    browser holding a file open on Windows.

    Returns a switch to turn the refusal off again. Not ``monkeypatch.undo()``:
    that also reverts the ``AZIMUT_HOME`` the workspace fixture set, so the next
    pass would write into the developer's real workspace.
    """
    real = os.replace
    gate = {"n": 0, "refusing": True}

    def fake(src, dst, *args, **kwargs):
        gate["n"] += 1
        if gate["refusing"] and gate["n"] > count:
            raise PermissionError(32, "being used by another process")
        return real(src, dst, *args, **kwargs)

    monkeypatch.setattr(dirswap.os, "replace", fake)
    # The retry ladder sleeps between attempts; there is nothing to wait for here.
    monkeypatch.setattr(dirswap.time, "sleep", lambda _s: None)
    return gate


def test_a_refused_replace_is_staged_not_half_written(folder, monkeypatch):
    extinstall.install()
    before = stamp_of(folder)

    _refuse_after(2, monkeypatch)
    state = extinstall.install()

    assert state["staged"] is True
    # The manifest is written last, so an interrupted pass leaves one that still
    # describes a loadable extension.
    manifest = json.loads((folder / "manifest.json").read_text(encoding="utf-8"))
    assert manifest["version"] == before["version"]
    # And the stamp still describes what is actually loadable, never the payload
    # that failed to land.
    assert stamp_of(folder) == before


def test_the_next_pass_finishes_a_staged_one(folder, monkeypatch):
    extinstall.install()
    gate = _refuse_after(1, monkeypatch)
    assert extinstall.install()["staged"] is True

    gate["refusing"] = False  # the browser let go
    state = extinstall.install()

    assert state["staged"] is False
    assert state["folder"]["payload"] == extinstall.payload_digest()
    # Exactly one staging directory can exist, and a finished pass leaves none —
    # otherwise "staged" would stay true forever after one refusal.
    assert not [p for p in folder.iterdir() if p.name.startswith(".staging-")]


def test_a_rename_aside_covers_a_replace_windows_refuses(folder, tmp_path):
    """os.replace onto an open file fails on Windows where a rename still works,
    so the ladder tries that before giving up."""
    target = tmp_path / "held.js"
    target.write_text("old", encoding="utf-8")
    source = tmp_path / "new.js"
    source.write_text("new", encoding="utf-8")

    calls = {"n": 0}
    real = os.replace

    def only_direct_replace_fails(src, dst, *args, **kwargs):
        calls["n"] += 1
        if Path(dst) == target and calls["n"] <= dirswap.REPLACE_ATTEMPTS:
            raise PermissionError(32, "being used by another process")
        return real(src, dst, *args, **kwargs)

    original_sleep = dirswap.time.sleep
    dirswap.time.sleep = lambda _s: None
    dirswap.os.replace = only_direct_replace_fails
    try:
        dirswap.replace_file(source, target)
    finally:
        dirswap.os.replace = real
        dirswap.time.sleep = original_sleep

    assert target.read_text(encoding="utf-8") == "new"
    assert not source.exists()


def test_leftovers_are_swept_and_never_reported_as_content(folder):
    extinstall.install()
    (folder / ".old-manifest.json-abcd").write_text("litter", encoding="utf-8")
    (folder / ".trash-icons-abcd").mkdir()

    state = extinstall.state()

    assert state["staged"] is False
    assert not (folder / ".old-manifest.json-abcd").exists()
    assert not (folder / ".trash-icons-abcd").exists()


# -- the routes ---------------------------------------------------------------


def test_the_install_route_takes_nothing_and_reports_the_folder(client):
    body = client.post("/api/settings/extension/install").json()
    assert body["staged"] is False
    assert body["folder"]["payload"] == body["bundled"]["payload"]
    assert Path(body["path"]).is_dir()


def test_the_state_route_reads_without_writing(client):
    body = client.get("/api/settings/extension").json()
    assert body["folder"] is None
    assert body["bundled"]["version"] == extinstall.bundled_version()
    assert not Path(body["path"]).exists()


def test_revealing_before_installing_is_a_404(client):
    assert client.post("/api/settings/extension/reveal").status_code == 404


def test_the_install_route_is_not_in_the_extension_cors_island(client):
    """/api/ingest/* is opened to any extension origin on purpose. A route that
    writes to disk must not inherit that, so it lives on the settings router and
    the browser's same-origin default is what guards it."""
    for path in ("/api/settings/extension", "/api/settings/extension/install"):
        response = client.options(
            path,
            headers={
                "Origin": "chrome-extension://abcdefghijklmnopabcdefghijklmnop",
                "Access-Control-Request-Method": "POST",
            },
        )
        assert "access-control-allow-origin" not in {k.lower() for k in response.headers}