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
8.7 KB
Raw Blame
"""The artifact registry, and the gates that keep it honest.

Two rules a later tool inherits without doing anything:

- whatever it files, deleting it leaves the case as it was born — no orphan
  beside a deleted proof, no folder nothing points at;
- whatever entity type it introduces has said what it owns on disk, or said it
  owns nothing and why.

Both read `tests/fullcase.py`, so a new tool is covered by adding its artifact
there.
"""

from pathlib import Path

import fullcase
from azimut import layout
from azimut.engine import artifacts, bundles
from azimut.workspace import Case

# The thumbnail cache is content-addressed, budgeted and regenerated on demand,
# and the bundle leaves it out for the same reason: it is not case content. The
# tree comparison below skips it rather than pretending it is.
CACHE = "media/.thumbs"


def tree(root: Path) -> set[str]:
    """Every path under a case directory, as case-relative posix strings."""
    out = set()
    for path in root.rglob("*"):
        rel = path.relative_to(root).as_posix()
        if rel == CACHE or rel.startswith(CACHE + "/"):
            continue
        out.add(rel)
    return out


def delete_everything(client, case_id: str) -> None:
    """Delete every entity through the chokepoint, cascades included."""
    for _ in range(50):
        entities = client.get(
            f"/api/cases/{case_id}/catalog/entities", params={"limit": 500}
        ).json()["items"]
        if not entities:
            return
        for entity in entities:
            # A cascade may already have taken it; a 404 is that, not a failure.
            client.delete(f"/api/cases/{case_id}/entities/{entity['id']}")
    raise AssertionError("entities kept coming back")


STORAGE_DOC = Path(__file__).resolve().parent.parent / "docs" / "STORAGE_AND_PERFORMANCE.md"


def documented_tree() -> set[str]:
    """The directories the published case tree draws, relative to `azimut/`."""
    text = STORAGE_DOC.read_text(encoding="utf-8")
    block = text.split("## The shape of a case", 1)[1].split("```text\n", 1)[1]
    block = block.split("```", 1)[0]
    stack: list[tuple[int, str]] = []
    out = set()
    for line in block.splitlines():
        name = line.split("#", 1)[0].strip()
        if not name.endswith("/"):
            continue
        depth = len(line) - len(line.lstrip())
        while stack and stack[-1][0] >= depth:
            stack.pop()
        stack.append((depth, name.rstrip("/")))
        parts = [part for _, part in stack]
        if parts[:2] == ["<case>", layout.TOOL_DIR] and len(parts) > 2:
            out.add("/".join(parts[2:]))
    return out


def test_the_published_case_tree_draws_every_directory_a_case_is_born_with(tmp_path):
    born = {
        path.relative_to(layout.tool_root(tmp_path)).as_posix()
        for path in layout.content_dirs(tmp_path)
    }
    assert born - documented_tree() == set()


def test_deleting_everything_returns_the_case_to_its_birth_state(client):
    """The gate. One artifact per tool goes in, everything is deleted, and what
    is left has to be a fresh case — byte-for-byte in shape, if not in content.

    This is what catches the file a later tool forgets to declare: an orphan is
    invisible in the UI and shows up here as one extra path.
    """
    full = fullcase.build_full_case(client)
    born = Case.open(client.post("/api/cases", json={"name": "Newborn"}).json()["id"])

    delete_everything(client, full.case_id)
    # Grids are not entities, so nothing deletes them for us (a gap the trash
    # work records rather than closes).
    client.delete(f"/api/cases/{full.case_id}/search-grids/north-sweep")
    # Nor is Horizon's bench: it is the tab's work in progress, emptied by the tab itself.
    client.delete(f"/api/cases/{full.case_id}/horizon/work")
    # Deleting is reversible now, so the bytes are still in the trash: this is
    # the second half of the gate, and where they are actually reclaimed.
    client.delete(f"/api/cases/{full.case_id}/trash")

    emptied = Case.open(full.case_id)
    # The tool root, not the case folder: what the analyst keeps beside it is
    # theirs, and a gate on files Azimut never wrote would be meaningless.
    assert tree(emptied.tool_root) == tree(born.tool_root)
    assert emptied.entity_redirects() == {}
    with emptied._graph()._connect() as conn:
        assert conn.execute('SELECT COUNT(*) FROM entity_merges').fetchone()[0] == 0


def test_deleting_a_proof_takes_its_pasted_images(client):
    """The leak this registry closed: the sidebar delete knew the spec and the
    export, and left ``proofs/<name>.assets/`` behind with the pastes inside."""
    full = fullcase.build_full_case(client)
    case = Case.open(full.case_id)
    assets = case.resolve_inside(full.proof_asset).parent
    assert assets.is_dir()

    entity = client.get(
        f"/api/cases/{full.case_id}/entities/lookup",
        params={"attr": "spec", "value": full.proof},
    ).json()["entity"]
    client.delete(f"/api/cases/{full.case_id}/entities/{entity['id']}")

    assert not assets.exists()
    assert not case.resolve_inside(full.proof).exists()


def test_a_collage_owns_its_preview_but_not_its_exported_picture(client):
    full = fullcase.build_full_case(client)
    case = Case.open(full.case_id)
    entity = case.find_entity(attr="spec", value=full.collage_doc)

    assert set(artifacts.owned(case, entity)) == {full.collage_doc, full.collage_thumb}
    assert artifacts.caches(case, entity) == []


def test_a_horizon_view_owns_its_preview_but_not_the_photo_it_was_matched_on(client):
    full = fullcase.build_full_case(client)
    case = Case.open(full.case_id)
    entity = case.find_entity(attr="spec", value=full.horizon_view)

    assert set(artifacts.owned(case, entity)) == {full.horizon_view, full.horizon_thumb}
    assert full.photo not in artifacts.owned(case, entity)


def test_every_type_in_a_full_case_declares_what_it_owns(client):
    """A type in neither table is not a decision, it is an oversight — the next
    tool declares its files in ``KINDS`` or declares it has none in ``NO_FILES``,
    with the reason beside it."""
    full = fullcase.build_full_case(client)

    undeclared = {t for t in full.entity_types if not artifacts.declares(t)}
    assert not undeclared, f"entity types that never say what they own: {sorted(undeclared)}"
    assert all(reason for reason in artifacts.NO_FILES.values())


def test_every_kind_that_owns_files_is_a_type_the_vocabulary_knows():
    """A kind filed without its type is a free type: drawn in every reading of the case,
    with no icon and nothing that opens it, which a Horizon search once was."""
    from azimut.engine import entities

    assert sorted(kind for kind in artifacts.KINDS if entities.entity_type(kind) is None) == []


def test_a_full_case_comes_back_whole_from_its_bundle(client):
    """Every file a full case's entities own and the bundle carries lands in the case
    the bundle imports into, so a new kind cannot travel half."""
    full = fullcase.build_full_case(client)
    case = Case.open(full.case_id)
    carried = {
        rel
        for entity in case.list_entities()
        for rel in artifacts.owned(case, entity)
        if bundles.classify_case_entry(rel) == "bundled"
    }
    assert {full.map_plate, full.horizon_view, full.horizon_find, full.editable_layer} <= carried

    exported = bundles.export_case(case)
    destination = Case.create(bundles.imported_name(case.id))
    landed = Case.open(bundles.import_into(destination, exported)["case_id"])

    assert sorted(rel for rel in carried if not landed.resolve_inside(rel).exists()) == []
    assert landed.resolve_inside(full.horizon_work).is_file()
    plate = client.get(f"/api/cases/{landed.id}/map-plates/{Path(full.map_plate).stem}")
    assert plate.status_code == 200, plate.text


def test_the_registry_answers_for_one_media_and_its_companions(client):
    """What ``owned`` returns is what moves; what ``caches`` returns is what is
    dropped and regenerated. A media has all three."""
    full = fullcase.build_full_case(client)
    case = Case.open(full.case_id)
    entity = client.get(
        f"/api/cases/{full.case_id}/entities/lookup",
        params={"attr": "path", "value": full.photo},
    ).json()["entity"]

    owned = artifacts.owned(case, entity)
    assert owned[0] == full.photo
    assert layout.sidecar_rel(full.photo) in owned
    assert all(not rel.startswith(CACHE) for rel in owned)
    assert all(rel.startswith(CACHE) for rel in artifacts.caches(case, entity))


def test_private_entity_photos_are_owned_by_their_entity(client):
    full = fullcase.build_full_case(client)
    case = Case.open(full.case_id)
    entity = case.get_entity(full.org_id)

    assert entity is not None
    assert set(artifacts.owned(case, entity)) == {
        full.entity_photo,
        full.entity_photo_thumb,
    }