← Files Codex SecurityARCHIVED FILE

scripts/workbench_target_state.py

43.5 KB · Nov 18, 2026 · 06:11 UTC

↓ Download file

See the change to this file →

"""Persist stable Codex Security target identities."""

from __future__ import annotations

import argparse
import ctypes
import hashlib
import os
import platform
import re
import sqlite3
import stat
import sys
from dataclasses import dataclass, replace
from datetime import datetime, timezone
from decimal import Decimal
from fractions import Fraction
from pathlib import Path
from urllib.parse import urlsplit

# Some plugin hosts launch Python with safe-path isolation enabled.
sys.path.insert(0, str(Path(__file__).resolve().parent))
from filesystem_identity import (
    serialize_filesystem_identity,
    stored_filesystem_identity_matches,
)
from workbench_target import (
    _protected_repository_root,
    git_bytes,
    git_output,
    git_worktree_context,
    pin_scoped_git,
)


def stable_target_id(target: Path) -> str:
    """Hash the supplied path spelling into the workbench ID for a local workspace."""
    digest = hashlib.sha256(f"local-workspace\0{target}".encode()).hexdigest()
    return f"target_sha256_{digest}"


def repository_relative_path(target: Path) -> str | None:
    """Return the target's normalized location within its own Git worktree."""
    worktree = _repository_worktree(target)
    return worktree[1] if worktree is not None else None


def _repository_worktree(target: Path) -> tuple[Path, str] | None:
    try:
        return git_worktree_context(target)
    except SystemExit:
        return None


def _path_from_git_bytes(
    value: bytes, relative_to: Path, *, strip_line_feed: bool = True
) -> Path | None:
    if strip_line_feed and value.endswith(b"\n"):
        value = value[:-2] if sys.platform == "win32" and value.endswith(b"\r\n") else value[:-1]
    if not value or b"\0" in value:
        return None
    path = Path(os.fsdecode(value))
    return Path(os.path.realpath(path if path.is_absolute() else relative_to / path))


def _git_path(target: Path, *args: str) -> Path | None:
    value = git_bytes(target, *args)
    return _path_from_git_bytes(value, target) if value is not None else None


def _same_existing_path(first: Path | None, second: Path | None) -> bool:
    if first is None or second is None:
        return False
    try:
        return first.samefile(second)
    except OSError:
        return False


def _registered_worktree(target: Path, root: Path, common: Path) -> bool:
    registered = git_bytes(target, "worktree", "list", "--porcelain", "-z")
    if registered is not None:
        return any(
            os.path.realpath(os.fsdecode(record[len(b"worktree ") :])) == str(root)
            for record in registered.split(b"\0")
            if record.startswith(b"worktree ")
        )
    # Git before 2.36 emits unquoted newline-delimited paths. Repository-side
    # ownership records are unambiguous even when a checkout path has newlines.
    gitdir = _git_path(target, "rev-parse", "--absolute-git-dir")
    dotgit = root / ".git"
    try:
        mode = dotgit.lstat().st_mode
        if stat.S_ISDIR(mode):
            return _same_existing_path(gitdir, common) and _same_existing_path(gitdir, dotgit)
        if not stat.S_ISREG(mode) or gitdir is None or not gitdir.is_dir():
            return False
        forward = dotgit.read_bytes()
        if not forward.startswith(b"gitdir: ") or not _same_existing_path(
            _path_from_git_bytes(forward[len(b"gitdir: ") :], root), gitdir
        ):
            return False
        if _same_existing_path(gitdir, common):
            configured = git_bytes(
                target,
                "config",
                "--null",
                "--show-scope",
                "--no-includes",
                "--get",
                "core.worktree",
            )
            fields = configured.split(b"\0") if configured is not None else []
            if (
                len(fields) != 3
                or fields[0] not in (b"local", b"worktree")
                or not fields[1]
                or fields[2]
            ):
                return False
            configured_root = _path_from_git_bytes(fields[1], gitdir, strip_line_feed=False)
            return _same_existing_path(configured_root, root)
        return _same_existing_path(gitdir.parent, common / "worktrees") and _same_existing_path(
            _path_from_git_bytes((gitdir / "gitdir").read_bytes(), gitdir), dotgit
        )
    except (OSError, ValueError):
        return False


class _LinuxStatxTimestamp(ctypes.Structure):
    _fields_ = (
        ("seconds", ctypes.c_int64),
        ("nanoseconds", ctypes.c_uint32),
        ("_reserved", ctypes.c_int32),
    )


class _LinuxStatx(ctypes.Structure):
    # Linux's statx UAPI keeps birth time at offset 0x50 in a 0x100-byte buffer.
    _fields_ = (
        ("mask", ctypes.c_uint32),
        ("_before_birth_time", ctypes.c_ubyte * 76),
        ("birth_time", _LinuxStatxTimestamp),
        ("_after_birth_time", ctypes.c_ubyte * 160),
    )


def _linux_repository_birth_time_ns(path: str) -> int | None:
    if ctypes.sizeof(_LinuxStatx) != 256 or _LinuxStatx.birth_time.offset != 80:
        return None
    metadata = _LinuxStatx()
    birth_time_mask = 0x800
    arguments = (-100, os.fsencode(path), 0, birth_time_mask, ctypes.byref(metadata))
    try:
        libc = ctypes.CDLL(None, use_errno=True)
        try:
            statx = libc.statx
        except AttributeError:
            # Older musl has the syscall but no statx wrapper. Only use known LP64 ABIs.
            if ctypes.sizeof(ctypes.c_void_p) != 8 or ctypes.sizeof(ctypes.c_long) != 8:
                return None
            number = {"x86_64": 332, "aarch64": 291}.get(platform.machine())
            if number is None:
                return None
            statx = libc.syscall
            statx.argtypes = (
                ctypes.c_long,
                ctypes.c_long,
                ctypes.c_char_p,
                ctypes.c_long,
                ctypes.c_ulong,
                ctypes.POINTER(_LinuxStatx),
            )
            statx.restype = ctypes.c_long
            status = statx(number, *arguments)
        else:
            statx.argtypes = (
                ctypes.c_int,
                ctypes.c_char_p,
                ctypes.c_int,
                ctypes.c_uint,
                ctypes.POINTER(_LinuxStatx),
            )
            statx.restype = ctypes.c_int
            status = statx(*arguments)
    except (AttributeError, OSError):
        return None
    birth_time = metadata.birth_time
    if (
        status != 0
        or not metadata.mask & birth_time_mask
        or not 0 <= birth_time.nanoseconds < 1_000_000_000
    ):
        return None
    birth_time_ns = birth_time.seconds * 1_000_000_000 + birth_time.nanoseconds
    return birth_time_ns if birth_time_ns > 0 else None


def _repository_birth_time_ns(path: str, metadata: os.stat_result) -> int | None:
    birth_time_ns = getattr(metadata, "st_birthtime_ns", None)
    if birth_time_ns is not None:
        return birth_time_ns if birth_time_ns > 0 else None
    if os.name == "nt":
        return metadata.st_ctime_ns if metadata.st_ctime_ns > 0 else None
    birth_time = getattr(metadata, "st_birthtime", None)
    if birth_time is not None:
        return int(birth_time * 1_000_000_000) if birth_time > 0 else None
    if not sys.platform.startswith("linux"):
        return None
    return _linux_repository_birth_time_ns(path)


@dataclass(frozen=True)
class GitRepositoryIdentity:
    value: str
    relative_path: str
    common_directory: str
    device: int | str
    inode: int | str
    birth_time_ns: int
    object_birth_time_ns: int
    previous_value: str | None = None

    @property
    def legacy_value(self) -> str:
        return _identity_digest(
            f"git-common-dir\0{self.common_directory}\0{self.device}\0{self.inode}\0"
            f"{self.birth_time_ns}\0{self.relative_path}"
        )


def _identity_digest(material: str, prefix: str = "repository_sha256_") -> str:
    return f"{prefix}{hashlib.sha256(material.encode(errors='surrogateescape')).hexdigest()}"


def _repository_worktree_location(target: Path) -> tuple[Path, str] | None:
    common_directory = _git_path(target, "rev-parse", "--path-format=absolute", "--git-common-dir")
    worktree = _repository_worktree(target)
    if common_directory is None or worktree is None:
        return None
    worktree_root, relative = worktree
    if not _registered_worktree(target, worktree_root, common_directory):
        return None
    return common_directory, relative


def same_repository_worktree(before: Path, after: Path) -> bool:
    before_location = _repository_worktree_location(before)
    after_location = _repository_worktree_location(after)
    return (
        before_location is not None
        and after_location is not None
        and before_location[1] == after_location[1]
        and _same_existing_path(before_location[0], after_location[0])
    )


def _repository_identity_details(target: Path | str) -> GitRepositoryIdentity | None:
    target = Path(target)
    location = _repository_worktree_location(target)
    if location is None:
        return None
    common_directory, relative = location
    object_directory = _git_path(
        target, "rev-parse", "--path-format=absolute", "--git-path", "objects"
    )
    if object_directory is None:
        return None
    canonical_directory = str(common_directory)
    try:
        metadata = common_directory.stat()
        object_metadata = object_directory.stat()
    except OSError:
        return None
    if not stat.S_ISDIR(metadata.st_mode) or not stat.S_ISDIR(object_metadata.st_mode):
        return None
    birth_time_ns = _repository_birth_time_ns(canonical_directory, metadata)
    object_birth_time_ns = _repository_birth_time_ns(str(object_directory), object_metadata)
    if birth_time_ns is None or object_birth_time_ns is None:
        return None
    device = serialize_filesystem_identity(metadata.st_dev)
    inode = serialize_filesystem_identity(metadata.st_ino)
    material = (
        f"git-generation-v2\0{canonical_directory}\0{device}\0{inode}\0"
        f"{birth_time_ns}\0{object_directory}\0"
        f"{serialize_filesystem_identity(object_metadata.st_dev)}\0"
        f"{serialize_filesystem_identity(object_metadata.st_ino)}\0"
        f"{object_birth_time_ns}\0{relative}"
    )
    previous_value = None
    value = _identity_digest(material)
    if sys.platform == "linux":
        try:
            common_filesystem = os.statvfs(common_directory).f_fsid
            object_filesystem = os.statvfs(object_directory).f_fsid
        except OSError:
            return None
        previous_value = value
        value = _identity_digest(
            f"git-generation-v3\0{canonical_directory}\0{common_filesystem}\0{inode}\0"
            f"{birth_time_ns}\0{object_directory}\0{object_filesystem}\0"
            f"{serialize_filesystem_identity(object_metadata.st_ino)}\0"
            f"{object_birth_time_ns}\0{relative}",
            "repository_v3_sha256_",
        )
    return GitRepositoryIdentity(
        value,
        relative,
        canonical_directory,
        device,
        inode,
        birth_time_ns,
        object_birth_time_ns,
        previous_value,
    )


def repository_identity(target: Path | str) -> str | None:
    """Identify matching Git worktree targets without storing remote credentials."""
    identity = _repository_identity_details(target)
    return identity.value if identity is not None else None


def repository_origin(target: Path) -> tuple[str, str] | None:
    remote = git_output(target, "remote", "get-url", "origin")
    if remote is None:
        return None
    if "://" in remote:
        try:
            parsed = urlsplit(remote)
            port = parsed.port
        except ValueError:
            return None
        if parsed.scheme not in {"https", "ssh"} or parsed.hostname is None:
            return None
        if parsed.query or parsed.fragment:
            return None
        host = parsed.hostname
        if port is not None and port != {"https": 443, "ssh": 22}[parsed.scheme]:
            host = f"{host}:{port}"
        path = parsed.path
    else:
        authority, separator, path = remote.partition(":")
        if not separator or "?" in path or "#" in path:
            return None
        host = authority.rsplit("@", 1)[-1]
    path = path.strip("/").removesuffix(".git")
    return (host.lower(), path) if host and path else None


def supports_repository_identity(connection: sqlite3.Connection) -> bool:
    return any(
        row["name"] == "repository_identity"
        for row in connection.execute("PRAGMA table_info(security_targets)")
    )


@dataclass(frozen=True)
class RepositoryTargetState:
    target_id: str
    target_path: str
    stored_identity: str | None
    resolved_path: str | None = None
    metadata: os.stat_result | None = None
    repository: GitRepositoryIdentity | None = None
    ownership_matches: bool = False
    strict_owner_matches: bool = False
    generation_predates_history: bool = False
    has_historical_scans: bool = False
    missing: bool = False
    previous_generation: str | None = None

    @property
    def live_identity(self) -> str | None:
        return (
            self.previous_generation or self.repository.value
            if self.repository is not None
            else None
        )

    @property
    def verified_identity(self) -> str | None:
        if not self.ownership_matches or self.repository is None:
            return None
        if self.stored_identity is None:
            # Checkout ownership and repository age cannot identify an older Git generation.
            return (
                self.live_identity
                if self.strict_owner_matches
                and self.generation_predates_history
                and not self.has_historical_scans
                else None
            )
        return self.live_identity if self.live_identity == self.stored_identity else None

    def require_owner(self) -> None:
        if not self.ownership_matches:
            raise SystemExit(
                f"The repository checkout at {self.target_path} no longer matches its recorded "
                "security scan history; refusing to reuse its target."
            )


def _inspect_repository_target(
    connection: sqlite3.Connection,
    target_id: str,
    target_path: str,
    stored_identity: str | None,
    *,
    scan_columns: set[str] | None = None,
) -> RepositoryTargetState:
    target = Path(target_path)
    try:
        resolved_path = str(target.resolve())
    except (OSError, RuntimeError):
        return RepositoryTargetState(target_id, target_path, stored_identity)
    try:
        metadata = target.stat()
    except (FileNotFoundError, NotADirectoryError):
        return RepositoryTargetState(
            target_id,
            target_path,
            stored_identity,
            resolved_path=resolved_path,
            ownership_matches=True,
            missing=True,
        )
    except OSError:
        return RepositoryTargetState(
            target_id, target_path, stored_identity, resolved_path=resolved_path
        )
    repository = _repository_identity_details(target)
    if scan_columns is None:
        scan_columns = {row["name"] for row in connection.execute("PRAGMA table_info(scans)")}
    historical_scan = False
    recorded_owner = False
    malformed_owner = False
    mismatch = False
    strict_owner_matches = False
    generation_predates_history = False
    ownership_matches = True
    if {"target_id", "target_path"} <= scan_columns:
        recorded_generations = (
            {
                row[0]
                for row in connection.execute(
                    "SELECT DISTINCT repository_generation FROM scans "
                    "WHERE (target_id = ? OR target_path = ?) AND repository_generation IS NOT NULL",
                    (target_id, target_path),
                )
            }
            if "repository_generation" in scan_columns
            else set()
        )
        generation_conflict = bool(recorded_generations) and (
            repository is None
            or recorded_generations not in ({repository.value}, {repository.previous_value})
        )
        if not {"target_device", "target_inode"} <= scan_columns:
            historical_scan = (
                connection.execute(
                    "SELECT 1 FROM scans WHERE target_id = ? OR target_path = ? LIMIT 1",
                    (target_id, target_path),
                ).fetchone()
                is not None
            )
            strict_owner_matches = not historical_scan
            generation_predates_history = repository is not None and not historical_scan
        else:
            strict_owner_matches = True
            timestamps = (
                ", started_at, created_at" if {"started_at", "created_at"} <= scan_columns else ""
            )
            revisions = ", target_revision" if "target_revision" in scan_columns else ""
            scans = connection.execute(
                f"""
                SELECT target_device, target_inode{timestamps}{revisions} FROM scans
                WHERE target_id = ? OR target_path = ?
                """,
                (target_id, target_path),
            ).fetchall()
            git_scans = [
                scan
                for scan in scans
                if "target_revision" not in scan.keys() or scan["target_revision"] != "unversioned"
            ]
            generation_predates_history = repository is not None and _repository_predates_history(
                repository, git_scans
            )
            for scan in scans:
                historical_scan = True
                device, inode = scan["target_device"], scan["target_inode"]
                if device is None and inode is None:
                    strict_owner_matches = False
                    continue
                if device is None or inode is None:
                    malformed_owner = True
                    strict_owner_matches = False
                    continue
                recorded_owner = True
                if not stored_filesystem_identity_matches(device, metadata.st_dev):
                    strict_owner_matches = False
                    mismatch = mismatch or sys.platform != "linux"
                if not stored_filesystem_identity_matches(inode, metadata.st_ino):
                    mismatch = True
                    strict_owner_matches = False
            stored_matches = repository is not None and (
                stored_identity
                in {
                    repository.value,
                    repository.legacy_value,
                    repository.previous_value or repository.value,
                }
                or (
                    repository.value.startswith("repository_v3_sha256_")
                    and recorded_generations == {repository.value}
                    and isinstance(stored_identity, str)
                    and re.fullmatch(r"repository_sha256_[0-9a-f]{64}", stored_identity) is not None
                )
            )
            verified_repository = repository is not None and (
                stored_matches
                or recorded_generations in ({repository.value}, {repository.previous_value})
            )
            ownership_matches = not (
                malformed_owner
                or mismatch
                and (
                    not verified_repository or repository is None or repository.relative_path == "."
                )
                or stored_identity is not None
                and (not stored_matches or historical_scan and not recorded_owner)
                or stored_identity is None
                and repository is not None
                and historical_scan
                and not verified_repository
                and not generation_predates_history
            )
        ownership_matches = ownership_matches and not generation_conflict
    previous_generation = None
    if (
        ownership_matches
        and repository is not None
        and repository.previous_value is not None
        and supports_repository_identity(connection)
        and "repository_generation" in scan_columns
        and connection.execute(
            "SELECT 1 FROM security_targets WHERE repository_identity = ? "
            "UNION ALL SELECT 1 FROM scans WHERE repository_generation = ? LIMIT 1",
            (repository.previous_value, repository.previous_value),
        ).fetchone()
        is not None
    ):
        previous_generation = repository.previous_value
    return RepositoryTargetState(
        target_id,
        target_path,
        stored_identity,
        resolved_path,
        metadata,
        repository,
        ownership_matches,
        strict_owner_matches,
        generation_predates_history,
        historical_scan,
        previous_generation=previous_generation,
    )


def verified_repository_identity(
    connection: sqlite3.Connection,
    target_id: str,
    target_path: str,
    *,
    stored_identity: str | None = None,
) -> str | None:
    try:
        return _inspect_repository_target(
            connection, target_id, target_path, stored_identity
        ).verified_identity
    except SystemExit:
        # Historical identity enrichment is optional; active registration stays strict.
        return None


def scan_repository_generation(scan: sqlite3.Row | dict) -> str | None:
    return scan["repository_generation"] if "repository_generation" in scan.keys() else None


def scan_repository_group(scan: sqlite3.Row | dict) -> tuple[str, str]:
    generation = scan_repository_generation(scan)
    return ("repository", generation) if generation is not None else ("target", scan["target_id"])


@dataclass(frozen=True)
class RepositoryScanScope:
    """A verified generation and, separately, its exact target's legacy scans."""

    generation: str | None = None
    target_id: str | None = None
    exact_target: bool = False
    available: bool = True

    def sql(
        self, alias: str = "scans", *, supports_generation: bool = True
    ) -> tuple[str, tuple[str, ...]]:
        if not self.available:
            return "0", ()
        if self.exact_target:
            return (f"{alias}.target_id = ?", (self.target_id,)) if self.target_id else ("0", ())
        clauses, values = [], []
        if self.generation is not None and supports_generation:
            clauses.append(f"{alias}.repository_generation = ?")
            values.append(self.generation)
        if self.target_id:
            legacy = f"{alias}.repository_generation IS NULL AND " if supports_generation else ""
            clauses.append(f"({legacy}{alias}.target_id = ?)")
            values.append(self.target_id)
        return (f"({' OR '.join(clauses)})", tuple(values)) if clauses else ("0", ())

    def contains(self, scan: sqlite3.Row | dict) -> bool:
        if not self.available:
            return False
        if self.exact_target:
            return bool(self.target_id) and scan["target_id"] == self.target_id
        generation = scan_repository_generation(scan)
        if generation is not None:
            return generation == self.generation
        return bool(self.target_id) and scan["target_id"] == self.target_id


class RepositoryIdentityCache:
    """One request's saved identities and verified live aliases."""

    def __init__(self, connection: sqlite3.Connection) -> None:
        self.connection = connection
        self.supports_identity = supports_repository_identity(connection)
        self.scan_columns = {row["name"] for row in connection.execute("PRAGMA table_info(scans)")}
        self.supports_generation = "repository_generation" in self.scan_columns
        identity_column = "repository_identity" if self.supports_identity else "NULL"
        self.targets = {
            row["target_id"]: row
            for row in connection.execute(
                "SELECT id AS target_id, current_path AS target_path, "
                f"{identity_column} AS repository_identity FROM security_targets"
            )
        }
        self.targets_by_path = {row["target_path"]: row for row in self.targets.values()}
        self._states: dict[tuple[str, str, str | None], RepositoryTargetState] = {}
        self._origins: dict[str, tuple[str, str] | None] = {}

    def for_row(self, row: sqlite3.Row | dict) -> RepositoryTargetState:
        target = self.targets.get(row["target_id"])
        stored = (
            row["repository_identity"]
            if "repository_identity" in row.keys()
            else target["repository_identity"]
            if target is not None
            else None
        )
        key = (
            row["target_id"] or "",
            row["target_path"],
            stored,
        )
        if key not in self._states:
            self._states[key] = _inspect_repository_target(
                self.connection, *key, scan_columns=self.scan_columns
            )
        return self._states[key]

    def for_path(self, target_path: str) -> RepositoryTargetState:
        path = Path(target_path)
        if os.name != "nt" and ".." in path.parts:
            last_parent = len(path.parts) - 1 - path.parts[::-1].index("..")
            try:
                # A missing final checkout can retain history. Every component
                # traversed before a parent segment must still exist.
                Path(*path.parts[: last_parent + 1]).stat()
            except (OSError, RuntimeError):
                return RepositoryTargetState("", target_path, None)
        row = self.targets_by_path.get(target_path)
        if row is None:
            try:
                canonical = str(Path(target_path).resolve())
            except (OSError, RuntimeError):
                canonical = None
            row = self.targets_by_path.get(canonical)
        if row is None:
            row = next(
                (
                    target
                    for target in self.targets.values()
                    if _same_existing_path(Path(target["target_path"]), Path(target_path))
                ),
                None,
            )
        return self.for_row(
            row
            if row is not None
            else {
                "target_id": "",
                "target_path": target_path,
                "repository_identity": None,
            }
        )

    def scope(self, target_id: str) -> RepositoryScanScope:
        target = self.targets.get(target_id)
        return (
            self._scope_for_state(self.for_row(target))
            if target is not None
            else RepositoryScanScope(target_id=target_id)
        )

    def history_path(self, target_path: str) -> str:
        """Use the worktree root when a subdirectory has no saved history of its own."""
        requested = self.for_path(target_path)
        if (
            not requested.ownership_matches
            or requested.target_id
            or requested.repository is None
            or requested.repository.relative_path == "."
        ):
            return target_path
        if (
            self.supports_generation
            and self.connection.execute(
                "SELECT 1 FROM scans WHERE repository_generation = ? LIMIT 1",
                (requested.live_identity,),
            ).fetchone()
        ):
            return target_path
        worktree = _repository_worktree(Path(target_path))
        return str(worktree[0]) if worktree is not None else target_path

    def scope_for_path(self, target_path: str) -> RepositoryScanScope:
        return self._scope_for_state(self.for_path(target_path))

    def scope_for_scan(self, scan: sqlite3.Row | dict) -> RepositoryScanScope:
        requested = self.for_row(scan)
        generation = scan_repository_generation(scan)
        if not requested.ownership_matches or (
            generation is not None and generation != requested.live_identity
        ):
            return RepositoryScanScope(available=False)
        return RepositoryScanScope(generation, requested.target_id)

    def _scope_for_state(self, requested: RepositoryTargetState) -> RepositoryScanScope:
        if not requested.ownership_matches:
            return RepositoryScanScope(available=False)
        return RepositoryScanScope(
            requested.live_identity if not requested.missing else None,
            requested.target_id or None,
            exact_target=requested.missing,
        )

    def origin(self, state: RepositoryTargetState) -> tuple[str, str] | None:
        if state.target_path not in self._origins:
            self._origins[state.target_path] = repository_origin(Path(state.target_path))
        return self._origins[state.target_path]


def require_scan_checkout_owner(connection: sqlite3.Connection, scan: sqlite3.Row | dict) -> None:
    identities = RepositoryIdentityCache(connection)
    owner = identities.for_row(scan)
    owner.require_owner()
    if owner.missing or not identities.scope_for_scan(scan).contains(scan):
        raise SystemExit("The saved scan no longer matches the selected repository checkout.")


def upgrade_linux_repository_generations(connection: sqlite3.Connection) -> None:
    """Convert only old digests authenticated before their device evidence changes."""
    if sys.platform != "linux":
        return
    targets = connection.execute(
        "SELECT id, current_path, repository_identity FROM security_targets "
        "WHERE repository_identity GLOB 'repository_sha256_*' OR EXISTS ("
        "SELECT 1 FROM scans WHERE (scans.target_id = security_targets.id "
        "OR scans.target_path = security_targets.current_path) "
        "AND repository_generation GLOB 'repository_sha256_*')"
    ).fetchall()
    for target in targets:
        try:
            state = _inspect_repository_target(
                connection, target["id"], target["current_path"], target["repository_identity"]
            )
        except SystemExit:
            continue
        _upgrade_repository_generation(connection, state)


def _upgrade_repository_generation(
    connection: sqlite3.Connection, state: RepositoryTargetState
) -> RepositoryTargetState:
    identity = state.repository
    if (
        identity is None
        or identity.previous_value is None
        or state.stored_identity not in (None, identity.value, identity.previous_value)
        or not state.ownership_matches
        or not state.strict_owner_matches
    ):
        return state
    connection.execute(
        "UPDATE security_targets SET repository_identity = ? WHERE repository_identity = ?",
        (identity.value, identity.previous_value),
    )
    connection.execute(
        "UPDATE scans SET repository_generation = ? WHERE repository_generation = ?",
        (identity.value, identity.previous_value),
    )
    return replace(
        state,
        stored_identity=(
            identity.value
            if state.stored_identity == identity.previous_value
            else state.stored_identity
        ),
        previous_generation=None,
    )


def _pre_release_repository_identities(identity: GitRepositoryIdentity) -> set[str]:
    directory = os.path.normcase(identity.common_directory)
    relative = os.path.normcase(os.fspath(Path(identity.relative_path))).replace(os.sep, "/")
    prefix = f"git-common-dir\0{directory}\0{identity.device}\0{identity.inode}\0"
    identities = {_identity_digest(f"{prefix}{relative}")}
    try:
        generation = (Path(identity.common_directory) / "description").lstat()
    except OSError:
        return identities
    if stat.S_ISREG(generation.st_mode):
        identities.add(
            _identity_digest(
                f"{prefix}git-description\0"
                f"{serialize_filesystem_identity(generation.st_dev)}\0"
                f"{serialize_filesystem_identity(generation.st_ino)}\0"
                f"{generation.st_ctime_ns}\0{relative}"
            )
        )
    return identities


def _timestamp_ns(value: str) -> int | Fraction | None:
    try:
        # Python 3.10 requires three or six fractional digits; stored timestamps
        # can come from newer runtimes that accept any RFC 3339 precision.
        fraction = re.search(r"\.(\d+)(?:[Zz]|[+-]\d{2}:\d{2})$", value)
        normalized = value
        if (
            fraction is not None
            and fraction[1].isascii()
            and re.search(r"[0-9]{2}:[0-9]{2}:[0-9]{2}$", value[: fraction.start()]) is not None
        ):
            normalized = (
                value[: fraction.start(1)]
                + fraction[1][:6].ljust(6, "0")
                + value[fraction.end(1) :]
            )
        if normalized.endswith(("Z", "z")):
            normalized = normalized[:-1] + "+00:00"
        timestamp = datetime.fromisoformat(normalized)
    except (TypeError, ValueError):
        return None
    if timestamp.tzinfo is None:
        return None
    delta = timestamp - datetime(1970, 1, 1, tzinfo=timezone.utc)
    nanoseconds = (delta.days * 86400 + delta.seconds) * 1_000_000_000 + delta.microseconds * 1000
    # datetime truncates RFC 3339 fractions after six digits; sealed timestamps retain them.
    if fraction is not None and len(fraction[1]) > 6:
        return nanoseconds + Fraction(Decimal("0." + fraction[1][6:])) * 1000
    return nanoseconds


def _repository_predates_history(
    identity: GitRepositoryIdentity,
    scans: list[sqlite3.Row],
    *,
    empty_timestamp: str | None = None,
) -> bool:
    if not scans and empty_timestamp is None:
        return True
    if any(not {"started_at", "created_at"} <= set(scan.keys()) for scan in scans):
        return False
    timestamps = (
        [_timestamp_ns(scan[column]) for scan in scans for column in ("started_at", "created_at")]
        if scans
        else [_timestamp_ns(empty_timestamp)]
    )
    repository_birth = max(identity.birth_time_ns, identity.object_birth_time_ns)
    return all(value is not None for value in timestamps) and repository_birth <= min(timestamps)


def normalize_pre_release_repository_identities(connection: sqlite3.Connection) -> None:
    """Retain only individually established pre-release identity bindings."""
    if not supports_repository_identity(connection):
        return
    identities = RepositoryIdentityCache(connection)
    targets = connection.execute(
        "SELECT id AS target_id, current_path AS target_path, created_at, repository_identity "
        "FROM security_targets WHERE repository_identity IS NOT NULL"
    ).fetchall()
    states = {target["target_id"]: identities.for_row(target) for target in targets}
    anchors = {
        state.stored_identity: state.repository
        for state in states.values()
        if state.repository is not None
        and state.ownership_matches
        and state.stored_identity
        in {
            state.repository.value,
            state.repository.legacy_value,
            state.repository.previous_value or state.repository.value,
        }
    }
    for target in targets:
        stored = target["repository_identity"]
        state = states[target["target_id"]]
        scans = connection.execute(
            "SELECT started_at, created_at FROM scans WHERE target_id = ? OR target_path = ?",
            (target["target_id"], target["target_path"]),
        ).fetchall()
        anchor = anchors.get(stored)
        identity = state.repository
        replacement = None
        if anchor is not None:
            if _repository_predates_history(anchor, scans, empty_timestamp=target["created_at"]):
                replacement = stored
        elif (
            identity is not None
            and state.strict_owner_matches
            and stored in _pre_release_repository_identities(identity)
            and _repository_predates_history(identity, scans, empty_timestamp=target["created_at"])
        ):
            replacement = identity.legacy_value
        if replacement != stored:
            connection.execute(
                "UPDATE security_targets SET repository_identity = ? "
                "WHERE id = ? AND repository_identity = ?",
                (replacement, target["target_id"], stored),
            )


def _bind_unscanned_repository_identity(
    connection: sqlite3.Connection,
    target_id: str,
    target_path: str,
    identity: str | None,
    *,
    previous_identity: str | None = None,
) -> bool:
    return (
        connection.execute(
            """
        UPDATE security_targets
        SET repository_identity = ?
        WHERE id = ? AND current_path = ? AND repository_identity IS ?
            AND NOT EXISTS (
                SELECT 1 FROM scans
                WHERE scans.target_id = security_targets.id
                    OR scans.target_path = security_targets.current_path
            )
        """,
            (identity, target_id, target_path, previous_identity),
        ).rowcount
        == 1
    )


def backfill_repository_identities(connection: sqlite3.Connection) -> None:
    if not supports_repository_identity(connection):
        return
    targets = connection.execute(
        """
        SELECT targets.id, targets.current_path
        FROM security_targets AS targets
        WHERE targets.repository_identity IS NULL
            AND NOT EXISTS (
                SELECT 1 FROM scans
                WHERE scans.target_id = targets.id OR scans.target_path = targets.current_path
            )
        """
    ).fetchall()
    for target in targets:
        identity = verified_repository_identity(
            connection, str(target["id"]), target["current_path"]
        )
        if identity is not None:
            _bind_unscanned_repository_identity(
                connection, str(target["id"]), target["current_path"], identity
            )


def backfill_security_targets(connection: sqlite3.Connection) -> None:
    """Fill missing target IDs on scans and workspaces in the caller’s transaction."""
    workspace_columns = {row["name"] for row in connection.execute("PRAGMA table_info(workspaces)")}
    validated_workspace = (
        " AND target_path_unvalidated = 0" if "target_path_unvalidated" in workspace_columns else ""
    )
    rows = connection.execute(
        f"""
        SELECT target_path FROM workspaces WHERE target_path IS NOT NULL{validated_workspace}
        UNION
        SELECT target_path FROM scans
        """
    ).fetchall()
    for row in rows:
        target_path = row["target_path"]
        target_id = ensure_security_target(connection, target_path, verify_ownership=False)
        connection.execute(
            "UPDATE workspaces SET target_id = ? WHERE target_path = ? AND target_id IS NULL"
            + validated_workspace,
            (target_id, target_path),
        )
        connection.execute(
            "UPDATE scans SET target_id = ? WHERE target_path = ? AND target_id IS NULL",
            (target_id, target_path),
        )
    backfill_repository_identities(connection)


@dataclass(frozen=True)
class RegisteredRepositoryTarget:
    target_id: str
    repository_generation: str | None


def _record_checkout_root(
    connection: sqlite3.Connection, row: sqlite3.Row, state: RepositoryTargetState, inserted: bool
) -> None:
    if "git_checkout_root" not in row.keys():
        return
    previous = row["git_checkout_root"]
    # Migrations and old rows cannot attest to the former boundary of a checkout.
    if previous is None and (not inserted or state.has_historical_scans):
        return
    target = Path(state.target_path)
    if (
        state.metadata is None
        or not stat.S_ISDIR(state.metadata.st_mode)
        or state.resolved_path != state.target_path
    ):
        return
    try:
        root = _protected_repository_root(target)
    except (OSError, RuntimeError):
        return
    if previous is None or root in Path(previous).parents:
        connection.execute(
            "UPDATE security_targets SET git_checkout_root = ? "
            "WHERE id = ? AND current_path = ? AND git_checkout_root IS ?",
            (str(root), state.target_id, state.target_path, previous),
        )


def register_security_target(
    connection: sqlite3.Connection, target_path: str, *, verify_ownership: bool = True
) -> RegisteredRepositoryTarget:
    target_query = "SELECT * FROM security_targets WHERE current_path = ?"
    existing = connection.execute(target_query, (target_path,)).fetchone()
    inserted = False
    if existing is None:
        if verify_ownership:
            # Pin ambient Git before the new row temporarily lacks a checkout boundary.
            pin_scoped_git(Path(target_path))
        target_id = stable_target_id(Path(target_path))
        timestamp = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
        # Leave repository_identity NULL until the guarded binding below succeeds.
        insert = connection.execute(
            """
            INSERT OR IGNORE INTO security_targets (
                id, current_path, display_name, created_at, updated_at
            ) VALUES (?, ?, ?, ?, ?)
            """,
            (target_id, target_path, Path(target_path).name, timestamp, timestamp),
        )
        inserted = insert.rowcount == 1
        existing = connection.execute(target_query, (target_path,)).fetchone()
        if existing is None:
            existing = connection.execute(
                "SELECT * FROM security_targets WHERE id = ?", (target_id,)
            ).fetchone()
            if existing is None or Path(existing["current_path"]) != Path(target_path):
                raise SystemExit("The repository target changed while it was being registered.")
            target_path = existing["current_path"]
    target_id = str(existing["id"])
    if "repository_identity" not in existing.keys():
        return RegisteredRepositoryTarget(target_id, None)
    try:
        state = _inspect_repository_target(
            connection, target_id, target_path, existing["repository_identity"]
        )
    except SystemExit:
        if verify_ownership:
            raise
        return RegisteredRepositoryTarget(target_id, None)
    if not state.has_historical_scans and state.live_identity != state.stored_identity:
        _bind_unscanned_repository_identity(
            connection,
            target_id,
            target_path,
            state.live_identity,
            previous_identity=existing["repository_identity"],
        )
        existing = connection.execute(target_query, (target_path,)).fetchone()
        if existing is None:
            raise SystemExit("The repository target changed while it was being registered.")
        target_id = str(existing["id"])
        state = _inspect_repository_target(
            connection, target_id, target_path, existing["repository_identity"]
        )
    state = _upgrade_repository_generation(connection, state)
    if verify_ownership:
        state.require_owner()
    if existing["repository_identity"] is None:
        identity = state.verified_identity
        if identity is not None and not _bind_unscanned_repository_identity(
            connection, target_id, target_path, identity
        ):
            # A writer may have registered history or bound this target after inspection.
            existing = connection.execute(target_query, (target_path,)).fetchone()
            if existing is None:
                raise SystemExit("The repository target changed while it was being registered.")
            target_id = str(existing["id"])
            state = _inspect_repository_target(
                connection, target_id, target_path, existing["repository_identity"]
            )
            if verify_ownership:
                state.require_owner()
    if verify_ownership:
        _record_checkout_root(connection, existing, state, inserted)
    return RegisteredRepositoryTarget(
        target_id, state.live_identity if state.ownership_matches and not state.missing else None
    )


def ensure_security_target(
    connection: sqlite3.Connection, target_path: str, *, verify_ownership: bool = True
) -> str:
    """Return the stable ID for the registered target and its verified ownership."""
    return register_security_target(
        connection, target_path, verify_ownership=verify_ownership
    ).target_id


if __name__ == "__main__":
    argparse.ArgumentParser(description=__doc__).parse_args()

SHA-256: 5471646ac8fe3f62d358c49ee2c0f0833ae14f57affe4bb9cea855158d0d6d1c