talax 0.1.0__py3-none-any.whl

talax/__init__.py

@@ -0,0 +1,48 @@
+"""Tala X — see beyond the pixel.
+
+from pathlib import Path
+from talax import analyze
+
+analysis = analyze(Path("photo.jpg"))
+print(analysis.integrity.verdict)
+for result in analysis.results:
+    print(result.signal_id, result.state, result.explanation)
+"""
+
+from importlib.metadata import version as _version
+
+from talax.analysis import analyze
+from talax.model import (
+    Analysis,
+    Context,
+    Declaration,
+    FileInfo,
+    IntegrityAssessment,
+    IntegrityVerdict,
+    Metadata,
+    Observation,
+    Result,
+    Sky,
+    State,
+)
+from talax.signals import Signal, run_signals
+
+__version__ = _version("talax")
+
+__all__ = [
+    "Analysis",
+    "Context",
+    "Declaration",
+    "FileInfo",
+    "IntegrityAssessment",
+    "IntegrityVerdict",
+    "Metadata",
+    "Observation",
+    "Result",
+    "Signal",
+    "Sky",
+    "State",
+    "__version__",
+    "analyze",
+    "run_signals",
+]

talax/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m talax` runs the same CLI as the `talax` command."""
+
+from talax.cli import app
+
+app()

talax/analysis.py

@@ -0,0 +1,52 @@
+"""Builds the context of a file and runs the signals on it."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from datetime import UTC, datetime
+from pathlib import Path
+
+from talax.extraction import read_metadata
+from talax.fileinfo import read_file_info
+from talax.integrity import assess_integrity
+from talax.jpeg import JpegError, JpegStructure, read_jpeg_structure
+from talax.model import Analysis, Context, Declaration, Observation
+from talax.provenance import read_c2pa
+from talax.signals import DEFAULT_SIGNALS, Signal, run_signals
+from talax.traits import read_traits
+
+
+def analyze(
+    path: Path,
+    declaration: Declaration | None = None,
+    observation: Observation | None = None,
+    signals: Iterable[Signal] = DEFAULT_SIGNALS,
+) -> Analysis:
+    file = read_file_info(path)
+    metadata = read_metadata(path)
+    traits = read_traits(file, metadata, _jpeg_structure(path, file.real_format))
+    ctx = Context(
+        file=file,
+        metadata=metadata,
+        integrity=assess_integrity(traits),
+        declaration=declaration,
+        c2pa=read_c2pa(path),
+        observation=observation,
+    )
+    return Analysis(
+        file=file,
+        integrity=ctx.integrity,
+        results=run_signals(ctx, signals),
+        created_at=datetime.now(UTC),
+    )
+
+
+def _jpeg_structure(path: Path, real_format: str | None) -> JpegStructure | None:
+    if real_format != "image/jpeg":
+        return None
+    try:
+        return read_jpeg_structure(path)
+    except JpegError:
+        # A damaged structure leaves the generic rules with less to go on;
+        # it is not a reason to stop the analysis.
+        return None

talax/cli.py

@@ -0,0 +1,140 @@
+"""Command-line interface: a thin adapter over the analysis core."""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from talax.analysis import analyze
+from talax.extraction import ExifToolError
+from talax.model import Analysis, Observation, Sky, State
+from talax.report import DISCLAIMER, STATE_LABELS, VERDICT_LABELS, render_html, to_dict
+
+BANNER = r"""
+ _____         _           __  __
+|_   _|  __ _ | |  __ _    \ \/ /
+  | |   / _` || | / _` |    \  /
+  | |  | (_| || || (_| |    /  \
+  |_|   \__,_||_| \__,_|   /_/\_\
+
+      See beyond the pixel
+"""
+
+_CONTROL = re.compile(r"[\x00-\x09\x0b-\x1f\x7f-\x9f]")
+
+_STYLES = {
+    State.CONSISTENT: "green",
+    State.TO_CHECK: "yellow",
+    State.SUSPICIOUS: "bold red",
+    State.UNVERIFIABLE: "dim",
+}
+
+app = typer.Typer(
+    help="Tala X: what can honestly be said about an image.",
+    add_completion=False,
+)
+out = Console()
+err = Console(stderr=True)
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context) -> None:
+    """Tala X: what can honestly be said about an image."""
+    if ctx.invoked_subcommand is None:
+        if sys.stdout.isatty():
+            out.print(BANNER, highlight=False, markup=False)
+        typer.echo(ctx.get_help())
+
+
+@app.command(name="analyze")
+def analyze_command(
+    file: Annotated[
+        Path,
+        typer.Argument(exists=True, dir_okay=False, readable=True, help="Image file."),
+    ],
+    sky: Annotated[
+        Sky | None,
+        typer.Option(help="What the photo shows, for the solar check."),
+    ] = None,
+    json_output: Annotated[
+        bool, typer.Option("--json", help="Print the analysis as JSON.")
+    ] = False,
+    html: Annotated[
+        Path | None,
+        typer.Option(dir_okay=False, help="Also write a self-contained HTML report."),
+    ] = None,
+) -> None:
+    """Analyse one file. Nothing is sent over the network."""
+    try:
+        analysis = analyze(file, observation=Observation(sky) if sky else None)
+    except (OSError, ExifToolError) as exc:
+        err.print(_safe(f"error: {exc}"), style="red")
+        raise typer.Exit(1) from exc
+
+    if html is not None:
+        html.write_text(render_html(analysis, file), encoding="utf-8")
+
+    if json_output:
+        print(json.dumps(to_dict(analysis, file.name), indent=2))
+    else:
+        _print_text(analysis, file, sky is not None)
+    if html is not None:
+        err.print(_safe(f"HTML report written to {html}"))
+
+
+@app.command()
+def version() -> None:
+    """Show the versions of Tala X and ExifTool."""
+    from talax.report import tool_versions
+
+    versions = tool_versions()
+    print(f"talax {versions['talax']} (ExifTool {versions['exiftool']})")
+
+
+def _safe(text: str) -> Text:
+    """File metadata is written by anyone: no markup, no terminal control codes."""
+    return Text(_CONTROL.sub("", text))
+
+
+def _print_text(analysis: Analysis, file: Path, sky_given: bool) -> None:
+    if sys.stdout.isatty():
+        out.print(BANNER, highlight=False, markup=False)
+    f = analysis.file
+    out.print(
+        _safe(f"{file.name}  {f.size:,} bytes  {f.real_format or ''}"), style="bold"
+    )
+    out.print(_safe(f"SHA-256 {f.sha256}"), style="dim")
+    out.print()
+    verdict = VERDICT_LABELS[analysis.integrity.verdict]
+    out.print(_safe(f"Integrity: {verdict}"), style="bold")
+    out.print(_safe(analysis.integrity.explanation))
+    out.print()
+
+    table = Table(box=None, show_header=False, padding=(0, 1, 1, 0), expand=True)
+    table.add_column(no_wrap=True)
+    table.add_column(ratio=1)
+    for r in analysis.results:
+        body = _safe(r.signal_id)
+        body.stylize("bold")
+        body.append("\n")
+        body.append_text(_safe(r.explanation))
+        table.add_row(Text(STATE_LABELS[r.state], style=_STYLES[r.state]), body)
+    out.print(table)
+
+    if not sky_given and any(
+        r.signal_id == "solar" and "sun was" in r.explanation for r in analysis.results
+    ):
+        out.print(
+            "Tip: add --sky day|twilight|night to check the sun against the photo.",
+            style="cyan",
+            markup=False,
+        )
+    out.print(_safe(DISCLAIMER), style="dim")

talax/clock.py

@@ -0,0 +1,72 @@
+"""Reading the date and time fields ExifTool returns."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta, timezone
+
+from talax.model import Metadata
+
+_STAMP = re.compile(
+    r"^(\d{4}):(\d{2}):(\d{2}) (\d{2}):(\d{2}):(\d{2})(\.\d+)?"
+    r"(Z|[+-]\d{2}:\d{2})?$"
+)
+
+
+def parse(value: object) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    m = _STAMP.match(value.strip())
+    if not m:
+        return None
+    y, mo, d, h, mi, s, frac, tz = m.groups()
+    try:
+        dt = datetime(int(y), int(mo), int(d), int(h), int(mi), int(s))
+    except ValueError:
+        return None
+    if frac:
+        dt += timedelta(seconds=float(frac))
+    if tz == "Z":
+        return dt.replace(tzinfo=UTC)
+    if tz:
+        return dt.replace(tzinfo=offset_from_text(tz))
+    return dt
+
+
+def local(tags: Metadata, key: str, subsec_key: str | None = None) -> datetime | None:
+    dt = parse(tags.get(key))
+    if dt is None:
+        return None
+    dt = dt.replace(tzinfo=None)
+    subsec = tags.get(subsec_key) if subsec_key else None
+    if isinstance(subsec, int | str) and str(subsec).isdigit():
+        dt += timedelta(seconds=float(f"0.{subsec}"))
+    return dt
+
+
+def recorded_offset(
+    tags: Metadata, vendor: datetime | None = None
+) -> tuple[timezone | None, str | None]:
+    """UTC offset recorded by the device, and where it was found."""
+    if vendor is None:
+        vendor = parse(tags.get("Samsung:TimeStamp"))
+    raw = tags.get("ExifIFD:OffsetTimeOriginal")
+    if isinstance(raw, str) and re.fullmatch(r"[+-]\d{2}:\d{2}", raw.strip()):
+        return offset_from_text(raw.strip()), "the EXIF offset"
+    if vendor is not None and isinstance(vendor.tzinfo, timezone):
+        return vendor.tzinfo, "the manufacturer's clock"
+    return None, None
+
+
+def offset_from_text(text: str) -> timezone:
+    sign = -1 if text[0] == "-" else 1
+    hours, minutes = int(text[1:3]), int(text[4:6])
+    return timezone(sign * timedelta(hours=hours, minutes=minutes))
+
+
+def format_offset(tz: timezone | None) -> str | None:
+    if tz is None:
+        return None
+    total = int(tz.utcoffset(None).total_seconds() // 60)
+    sign = "-" if total < 0 else "+"
+    return f"{sign}{abs(total) // 60:02d}:{abs(total) % 60:02d}"

talax/data/editors.yaml

@@ -0,0 +1,19 @@
+# Image editors recognised in software tags (IFD0:Software,
+# XMP-xmp:CreatorTool, XMP-xmpMM:HistorySoftwareAgent).
+# Matching is a case-insensitive substring search on each entry.
+# Add an editor only after seeing the exact string it writes.
+
+editors:
+  - Adobe Photoshop
+  - Adobe Lightroom
+  - Lightroom
+  - GIMP
+  - Snapseed
+  - PicsArt
+  - Canva
+  - Pixelmator
+  - Affinity Photo
+  - Paint.NET
+  - darktable
+  - Capture One
+  - Luminar

talax/data/fingerprints/samsung-gallery-edit.yaml

@@ -0,0 +1,36 @@
+# Fingerprint of a photo edited and saved in the Samsung Gallery app.
+# Format: see src/talax/fingerprints.py. Every field below is required.
+
+id: samsung-gallery-edit
+platform: Samsung Gallery
+route: photo edited and saved on the phone
+summary: >-
+  the camera metadata was kept, but the image was re-encoded by the Samsung
+  Gallery editor (JFIF header added, byte order changed, embedded preview and
+  network country code removed). The content may have been changed in any
+  way the editor allows: filters, stickers, text, object removal.
+verdict: undetermined
+
+match:
+  formats: [image/jpeg]
+  exif: present
+  vendor_data: present
+  progressive: false
+  segments: [SOI, APP1:Exif, APP0:JFIF, DQT, DQT, SOF0, DHT, DHT, DHT, DHT, DRI, SOS]
+  tags:
+    File:ExifByteOrder: MM
+
+# Not part of the match, but observed on all 4 samples: no IFD1 (embedded
+# preview removed), Samsung:MCCData removed, Samsung:TimeStamp kept, pixels
+# rotated upright (orientation normal). Originals from the same phone are
+# little-endian (II) and have no JFIF header.
+
+measured:
+  date: 2026-10-31
+  samples: 4
+  devices: [samsung Galaxy A34 5G]
+  app_versions: [unknown]
+  retrieval: bluetooth (2 files) and usb-cable (2 files)
+  corpus_sets: [2026-10-31-a34-edits]
+
+distinguished_from: []

talax/data/fingerprints/whatsapp-gallery.yaml

@@ -0,0 +1,39 @@
+# Fingerprint of a photo sent through WhatsApp as a gallery image.
+# Format: see src/talax/fingerprints.py. Every field below is required.
+
+id: whatsapp-gallery
+platform: WhatsApp
+route: photo sent from the gallery (standard quality)
+summary: >-
+  the camera metadata is gone and the image was re-encoded the way WhatsApp
+  does it.
+verdict: reprocessed
+
+# All conditions must hold for a file to match.
+match:
+  formats: [image/jpeg]
+  exif: absent
+  vendor_data: absent
+  progressive: true
+  segments: [SOI, APP0:JFIF, DQT, SOF2, DHT, SOS]
+  tags:
+    JFIF:JFIFVersion: "1 1"
+    JFIF:ResolutionUnit: 0
+    JFIF:XResolution: 1
+    JFIF:YResolution: 1
+
+# Not part of the match: quantisation tables differ between the two devices
+# measured (first coefficient 10 from the A34, 6 from the S22), and so do the
+# output dimensions (1000 or 1080 px long side from the A34, 1280 from the S22).
+
+measured:
+  date: 2026-10-31
+  samples: 13
+  devices: [samsung Galaxy A34 5G, samsung Galaxy S22 (SM-S901B)]
+  app_versions: [unknown]
+  retrieval: WhatsApp Web download
+  corpus_sets: [2026-10-31-a34, 2026-10-31-s22]
+
+# Platforms measured that do NOT match this fingerprint. Empty means no other
+# platform has been measured yet, and the report must say so.
+distinguished_from: []

talax/data/vendor_groups.yaml

@@ -0,0 +1,14 @@
+# ExifTool groups (-G1 names) that only a device manufacturer writes.
+# Their presence is one of the marks of a camera original.
+#
+# Listed only after being observed in a camera original of the corpus: an
+# unknown group is NOT treated as manufacturer data, so an unmeasured device
+# gives "undetermined", never a false "original". (Windows Photos adds the
+# generic XMP-rdf block, which an earlier "everything not standard" rule
+# wrongly counted.)
+
+vendor_groups:
+  - Samsung          # Samsung trailer (A34, S22)
+  - Google           # Google container data (S22 motion photo)
+  - XMP-GCamera      # S22
+  - XMP-GContainer   # S22

talax/extraction.py

@@ -0,0 +1,107 @@
+"""Metadata extraction through ExifTool, an external program."""
+
+from __future__ import annotations
+
+import functools
+import json
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from talax.model import Metadata
+
+MIN_EXIFTOOL_VERSION = (13, 0)
+_TIMEOUT_SECONDS = 60
+
+# -G1: precise group (`ExifIFD:DateTimeOriginal`), so a tag forged in another
+#      block shows up separately. -a: keep duplicates. -n: raw numeric values.
+# System tags (file name, directory, dates, permissions) describe the local
+# copy, not the content, and may leak private paths: excluded.
+_ARGS = ("-json", "-G1", "-a", "-n", "--System:all")
+
+
+class ExifToolError(RuntimeError):
+    pass
+
+
+class ExifToolMissingError(ExifToolError):
+    pass
+
+
+@functools.cache
+def exiftool_version() -> tuple[int, int]:
+    """Installed ExifTool version. Raises if missing or too old."""
+    if shutil.which("exiftool") is None:
+        raise ExifToolMissingError(
+            "ExifTool is required but was not found. Install it from "
+            "https://exiftool.org/ and make sure `exiftool` is on your PATH."
+        )
+    out = _run(["-ver"]).strip()
+    try:
+        major, minor = (int(part) for part in out.split(".")[:2])
+    except ValueError as exc:
+        raise ExifToolError(f"unexpected ExifTool version output: {out!r}") from exc
+    if (major, minor) < MIN_EXIFTOOL_VERSION:
+        wanted = ".".join(map(str, MIN_EXIFTOOL_VERSION))
+        raise ExifToolError(
+            f"ExifTool {out} is too old; Tala X needs {wanted} or newer. Older "
+            "versions miss vendor tags and would give different results."
+        )
+    return major, minor
+
+
+def read_metadata(path: Path) -> Metadata:
+    exiftool_version()
+    # An absolute path cannot be mistaken for an option (`-name.jpg`).
+    out = _run([*_ARGS, str(path.resolve())])
+    try:
+        (record,) = json.loads(out, object_pairs_hook=_keep_duplicates)
+    except ValueError as exc:
+        raise ExifToolError("could not parse ExifTool output") from exc
+    record.pop("SourceFile", None)  # local path: private, not content
+    return Metadata(record)
+
+
+def read_thumbnail(path: Path) -> bytes | None:
+    """Embedded EXIF preview image (IFD1), or None if the file has none."""
+    exiftool_version()
+    try:
+        proc = subprocess.run(
+            ["exiftool", "-b", "-ThumbnailImage", str(path.resolve())],
+            capture_output=True,
+            timeout=_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return None
+    return proc.stdout or None
+
+
+def _run(args: list[str]) -> str:
+    try:
+        proc = subprocess.run(
+            ["exiftool", *args],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            timeout=_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise ExifToolError(f"ExifTool timed out after {_TIMEOUT_SECONDS}s") from exc
+    if proc.returncode != 0 and not proc.stdout:
+        raise ExifToolError(proc.stderr.strip() or "ExifTool failed")
+    return proc.stdout
+
+
+def _keep_duplicates(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    """Same tag twice in the same group is itself evidence: never drop one."""
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        name, n = key, 1
+        while name in result:
+            n += 1
+            name = f"{key}#{n}"
+        result[name] = value
+    return result

talax/fileinfo.py

@@ -0,0 +1,90 @@
+"""File identity: hash, format implied by the name, format read from the bytes."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from talax.model import FileInfo
+
+_CHUNK = 1024 * 1024
+_SNIFF_SIZE = 32
+
+EXTENSIONS = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".jpe": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".tif": "image/tiff",
+    ".tiff": "image/tiff",
+    ".heic": "image/heic",
+    ".heif": "image/heif",
+    ".avif": "image/avif",
+    ".mp4": "video/mp4",
+    ".m4v": "video/mp4",
+    ".mov": "video/quicktime",
+}
+
+# ISO base media files (HEIC, AVIF, MP4, MOV) all start with an `ftyp` box;
+# its major brand tells them apart.
+_FTYP_BRANDS = {
+    b"heic": "image/heic",
+    b"heix": "image/heic",
+    b"heim": "image/heic",
+    b"heis": "image/heic",
+    b"hevc": "image/heic",
+    b"hevx": "image/heic",
+    b"mif1": "image/heif",
+    b"msf1": "image/heif",
+    b"avif": "image/avif",
+    b"avis": "image/avif",
+    b"qt  ": "video/quicktime",
+    b"isom": "video/mp4",
+    b"iso2": "video/mp4",
+    b"iso4": "video/mp4",
+    b"iso5": "video/mp4",
+    b"iso6": "video/mp4",
+    b"mp41": "video/mp4",
+    b"mp42": "video/mp4",
+    b"avc1": "video/mp4",
+    b"M4V ": "video/mp4",
+    b"3gp4": "video/3gpp",
+    b"3gp5": "video/3gpp",
+}
+
+
+def read_file_info(path: Path) -> FileInfo:
+    digest = hashlib.sha256()
+    size = 0
+    with path.open("rb") as f:
+        head = f.read(_SNIFF_SIZE)
+        digest.update(head)
+        size += len(head)
+        while chunk := f.read(_CHUNK):
+            digest.update(chunk)
+            size += len(chunk)
+    return FileInfo(
+        sha256=digest.hexdigest(),
+        size=size,
+        declared_format=EXTENSIONS.get(path.suffix.lower()),
+        real_format=sniff_format(head),
+    )
+
+
+def sniff_format(head: bytes) -> str | None:
+    """MIME type from the first bytes of a file, or None if unrecognised."""
+    if head.startswith(b"\xff\xd8\xff"):
+        return "image/jpeg"
+    if head.startswith(b"\x89PNG\r\n\x1a\n"):
+        return "image/png"
+    if head[:6] in (b"GIF87a", b"GIF89a"):
+        return "image/gif"
+    if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+        return "image/webp"
+    if head[:4] in (b"II*\x00", b"MM\x00*"):
+        return "image/tiff"
+    if head[4:8] == b"ftyp":
+        return _FTYP_BRANDS.get(head[8:12])
+    return None