@arbiterforge/ca-pi 0.6.0

package/plugins/ca-pi/hooks/releasehash.py

@@ -0,0 +1,216 @@
+#!/usr/bin/env python3
+# codeArbiter — pre-tag content-hash confirmation (A-2.10).
+#
+# A row's `pre-tag` commands are operator-authored shell that `/ca:release`
+# EXECUTES before composing a tag. `.codearbiter/release-targets.md` is
+# marker-gated under H-22, so changing those commands already costs a fresh
+# authoring marker — but that gate is about WRITING the file. Nothing made the
+# release lane notice that the commands it is about to run are not the ones
+# anybody last looked at.
+#
+# This closes that: the lane records a hash of a row's pre-tag content when an
+# operator confirms it, and refuses to run silently once that hash changes. A
+# changed hash is not a block — it is a re-confirmation prompt. Per ADR-0010
+# this is COOPERATIVE-grade: an agent that skips the check is not stopped by
+# the operating system, only by the lane's own discipline. Stated plainly here
+# rather than implied, because a reader who mistakes it for enforcement would
+# over-trust it.
+#
+# WHY A PYTHON PRODUCER, not a shell redirect. H-19 (`pre-write.py`) blocks
+# Write-tool writes to `.codearbiter/.markers/*` outright, and
+# `_bashguardlib`'s companion rule blocks shell redirects and interpreter
+# invocations that name a gate marker. Both exist because a hand-forged marker
+# is a forged gate pass. The confirmation record therefore needs a sanctioned
+# producer, which is this module.
+#
+# Ships to every governance plugin byte-identically via tools/sync-core.py, so
+# it carries NO fact about any particular repository: the target name, the
+# commands, and the project root all arrive as arguments or from the declared
+# file.
+#
+# Public API:
+#   pre_tag_digest(commands) -> str
+#   confirmation_path(root, target) -> str
+#   read_confirmation(root, target) -> str | None
+#   record_confirmation(root, target, digest) -> str
+#   confirmation_state(root, target, commands) -> str
+#   main(argv) -> int
+#
+# CLI:
+#   releasehash.py digest <target>    print the current pre-tag digest
+#   releasehash.py check <target>     exit 0 confirmed, 1 changed, 2 never
+#                                     confirmed, 3/4 declared-file states
+#   releasehash.py record <target>    mint the confirmation (the sanctioned
+#                                     producer; run only after an operator has
+#                                     actually READ the commands)
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import _releaselib  # noqa: E402 — sibling module, flat hooks/ layout
+
+DIGEST_VERSION = "1"
+MARKER_DIRNAME = ".markers"
+CONFIRMED_PREFIX = "pre-tag-confirmed-"
+
+CONFIRMED = "confirmed"
+CHANGED = "changed"
+NEVER = "never-confirmed"
+NO_COMMANDS = "no-commands"
+
+
+def pre_tag_digest(commands):
+    """A stable digest of a row's `pre-tag` command list.
+
+    ORDER-SENSITIVE on purpose. The commands run in declared order and a
+    reordering can change what a release checks — a check that ran after a
+    rebuild is not the same check as one that ran before it — so swapping
+    two entries must invalidate the confirmation, not preserve it.
+
+    Each command is length-prefixed before joining, so `["ab", "c"]` and
+    `["a", "bc"]` cannot collide into one digest. Versioned, so a future
+    change to this construction cannot be mistaken for a content change
+    by an old recorded value.
+
+    Pure and non-raising: a non-list, or a list with non-string members,
+    degrades to the digest of an empty list rather than raising inside a
+    release lane.
+    """
+    if not isinstance(commands, (list, tuple)):
+        commands = []
+    parts = [DIGEST_VERSION]
+    for command in commands:
+        if not isinstance(command, str):
+            continue
+        parts.append(f"{len(command)}:{command}")
+    joined = "\n".join(parts)
+    return hashlib.sha256(joined.encode("utf-8")).hexdigest()
+
+
+def confirmation_path(root, target):
+    """Where `target`'s confirmation is recorded.
+
+    One marker PER TARGET, never a shared one: a multi-target repository
+    confirming `ca`'s commands must not thereby confirm `ca-pi`'s.
+    """
+    # The sanitized stem alone is NOT injective: every disallowed character
+    # folds to "_", so `a.b` and `a_b` -- two legal, distinct target names --
+    # would share one marker, and confirming either would silently confirm
+    # the other. That is precisely the cross-target confirmation this
+    # function promises not to do. A short digest of the RAW name restores
+    # the one-marker-per-target property while keeping the stem readable for
+    # whoever is looking in `.markers/` by eye.
+    raw = str(target)
+    safe = "".join(ch if (ch.isalnum() or ch in "-_") else "_" for ch in raw)
+    digest = hashlib.sha256(raw.encode("utf-8")).hexdigest()[:8]
+    return os.path.join(root, ".codearbiter", MARKER_DIRNAME,
+                        CONFIRMED_PREFIX + f"{safe}-{digest}")
+
+
+def read_confirmation(root, target):
+    """The recorded digest for `target`, or None when never confirmed.
+
+    Never raises: an unreadable or empty marker reads as "never confirmed",
+    which is the conservative answer — it prompts rather than admits.
+    """
+    try:
+        with open(confirmation_path(root, target), encoding="utf-8") as handle:
+            value = handle.read().strip()
+    except (OSError, UnicodeError):
+        return None
+    return value or None
+
+
+def record_confirmation(root, target, digest):
+    """Mint the confirmation marker. Returns the path written.
+
+    THE SANCTIONED PRODUCER. Call this only after an operator has actually
+    read the commands — recording a digest nobody looked at converts this
+    from a confirmation into a rubber stamp, which is worse than not
+    having it, because the lane then reports "confirmed" about content no
+    human has seen.
+    """
+    path = confirmation_path(root, target)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    with open(path, "w", encoding="utf-8", newline="\n") as handle:
+        handle.write(str(digest).strip() + "\n")
+    return path
+
+
+def confirmation_state(root, target, commands):
+    """One of `confirmed` / `changed` / `never-confirmed` / `no-commands`.
+
+    `no-commands` is deliberately distinct from `confirmed`: a row that
+    declares no pre-tag commands has nothing to confirm, and reporting it
+    as confirmed would claim an operator approved something that does not
+    exist. The lane treats both as "proceed", but only one of them is a
+    statement about human review.
+    """
+    if not commands:
+        return NO_COMMANDS
+    recorded = read_confirmation(root, target)
+    if recorded is None:
+        return NEVER
+    return CONFIRMED if recorded == pre_tag_digest(commands) else CHANGED
+
+
+def _row_commands(target, targets_path=None):
+    path = targets_path or _releaselib.default_targets_path()
+    rows = _releaselib.load_targets(path)
+    row = next((r for r in rows if r["target"] == target), None)
+    if row is None:
+        return None
+    return row.get("pre_tag") or []
+
+
+def main(argv=None):
+    """CLI. See the module header for subcommands and exit codes."""
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if len(argv) != 2 or argv[0] not in ("digest", "check", "record"):
+        sys.stderr.write("usage: releasehash.py {digest|check|record} <target>\n")
+        return 2
+    command, target = argv
+    root = os.path.dirname(os.path.dirname(_releaselib.default_targets_path()))
+
+    try:
+        commands = _row_commands(target)
+    except _releaselib.ReleaseTargetsError as error:
+        sys.stderr.write(f"{type(error).__name__}: {error}\n")
+        return _releaselib._targets_error_exit_code(error)
+    if commands is None:
+        sys.stderr.write(f"unknown release target: {target}\n")
+        return 2
+
+    if command == "digest":
+        print(pre_tag_digest(commands))
+        return 0
+
+    if command == "record":
+        path = record_confirmation(root, target, pre_tag_digest(commands))
+        print(f"recorded pre-tag confirmation for {target}: {path}")
+        return 0
+
+    state = confirmation_state(root, target, commands)
+    print(state)
+    if state in (CONFIRMED, NO_COMMANDS):
+        return 0
+    if state == CHANGED:
+        sys.stderr.write(
+            f"releasehash: {target}'s pre-tag commands have CHANGED since they "
+            "were last confirmed. Read them, and re-confirm with "
+            f"`releasehash.py record {target}` before releasing. These commands "
+            "are executed by the release lane, so a change nobody has read is "
+            "the case this check exists for.\n")
+        return 1
+    sys.stderr.write(
+        f"releasehash: {target}'s pre-tag commands have never been confirmed. "
+        f"Read them, then run `releasehash.py record {target}`.\n")
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugins/ca-pi/hooks/security-pass.py

@@ -0,0 +1,139 @@
+#!/usr/bin/env python3
+# codeArbiter v2 — record a security-gate pass BOUND to the lines it approved.
+#
+# The crypto-compliance / secret-handling skills (and /ca:override's heavier
+# security ceiling) run this ON PASS, replacing the old `touch` of an empty
+# marker. An empty marker only proved that *some* gate passed *recently*; any
+# different crypto/secret change committed inside the 30-minute freshness
+# window rode through on it (a TOCTOU hole). This helper hashes every added
+# line in the working tree (vs HEAD, plus untracked files) that matches the
+# shared CRYPTO_RE/SECRET_RE and writes the digests to
+# .codearbiter/.markers/security-gate-passed; pre-bash.py H-09b/H-10b then
+# admits a commit only when every sensitive line being committed is in the
+# recorded set.
+#
+# Invoked by skill prose as (interpreter resolved once by presence, never a
+# `python3 X || python X` fold -- #577; recording itself stays idempotent):
+#   "$PY" "<plugin>/hooks/security-pass.py"
+
+import os
+import subprocess
+
+from _gitexec import git_executable
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import hostapi  # noqa: E402 — host seam (ADR-0011)
+import _entrylib  # noqa: E402 — shared run() dispatch (jscpd dedup)
+from _hooklib import (  # noqa: E402
+    CRYPTO_RE, SECRET_RE, SECURITY_DIFF_GIT_ARGS, is_sensitive_scan_exempt,
+    line_digest, marker_root, project_root, sensitive_scan_added_lines,
+    set_host, utf8_stdio, warn, write_text_atomic,
+)
+
+MAX_UNTRACKED_BYTES = 1_000_000  # an untracked blob bigger than this is not reviewable prose
+
+
+def run_git(args, cwd):
+    return subprocess.run(
+        [git_executable()] + args, cwd=cwd, capture_output=True, text=True,
+        encoding="utf-8", errors="replace", timeout=30,
+    )
+
+
+def file_lines(root, rel):
+    p = os.path.join(root, rel)
+    try:
+        if os.path.getsize(p) > MAX_UNTRACKED_BYTES:
+            return []
+        with open(p, encoding="utf-8", errors="replace") as f:
+            return f.read().splitlines()
+    except Exception:  # noqa: BLE001
+        return []
+
+
+def candidate_lines(root):
+    """Every line the next commit could introduce: added lines of the
+    worktree-vs-HEAD diff (staged and unstaged alike), plus the full content
+    of untracked files — `git diff HEAD` never shows those, but they land in
+    the staged diff the moment commit-gate stages them.
+
+    Excludes gate-events.log (#279, is_sensitive_scan_exempt): the crypto/
+    secret gate's own machine-written audit sink, which structurally echoes
+    the detector's message text back at itself. The diff branch drops those
+    lines via the shared path-aware `sensitive_scan_added_lines`; the
+    unborn-branch and untracked-file branches skip the file outright since
+    they read whole-file content rather than a diff.
+
+    The diff is read via SECURITY_DIFF_GIT_ARGS (not a bare `["diff", ...]`):
+    it pins the `a/`/`b/` prefix format `sensitive_scan_added_lines` depends
+    on for path attribution, regardless of the caller's `diff.mnemonicPrefix`
+    / `diff.noprefix` / external-diff config (#279 review MEDIUM-1)."""
+    lines = []
+    diff = run_git([*SECURITY_DIFF_GIT_ARGS, "HEAD"], root)
+    if diff.returncode == 0:
+        lines += sensitive_scan_added_lines(diff.stdout)
+    else:
+        # Unborn branch (no HEAD yet): every tracked file is new content.
+        ls = run_git(["ls-files"], root)
+        for rel in ls.stdout.splitlines():
+            if is_sensitive_scan_exempt(rel):
+                continue
+            lines += file_lines(root, rel)
+    untracked = run_git(["ls-files", "--others", "--exclude-standard"], root)
+    for rel in untracked.stdout.splitlines():
+        if is_sensitive_scan_exempt(rel):
+            continue
+        lines += file_lines(root, rel)
+    return lines
+
+
+def main():
+    utf8_stdio()
+    root = project_root()
+    if not os.path.isdir(os.path.join(root, ".codearbiter")):
+        warn("no .codearbiter/ here — security-pass.py records nothing outside "
+             "an initialized repo")
+        sys.exit(1)
+    sensitive = [ln for ln in candidate_lines(root)
+                 if CRYPTO_RE.search(ln) or SECRET_RE.search(ln)]
+    # #604: the MARKER root is deliberately NOT `root` above. `root` (plain
+    # project_root()) must stay wherever this process is actually running —
+    # candidate_lines(root) just scanned exactly that tree's diff, and binding
+    # digests to a DIFFERENT tree would review lines nobody staged. But in a
+    # linked git worktree, `root` names the worktree's own (gitignored,
+    # never-checked-out) `.codearbiter/.markers/`, while the H-09b/H-10b
+    # guard reads the marker from the MAIN checkout (D-2) — marker_root()
+    # gives the write the same main-checkout answer the guard's read already
+    # has, without moving the scan.
+    write_root = marker_root()
+    marker_dir = os.path.join(write_root, ".codearbiter", ".markers")
+    os.makedirs(marker_dir, exist_ok=True)
+    marker = os.path.join(marker_dir, "security-gate-passed")
+    digests = sorted({line_digest(ln) for ln in sensitive})
+    # Atomic write (migration-002): a crash mid-write never leaves a half-written
+    # marker, which the backstop would read as an unrecognized digest and force a
+    # spurious gate re-run.
+    write_text_atomic(marker, "\n".join(digests) + ("\n" if digests else ""))
+    print(f"security-gate pass recorded: {len(digests)} sensitive line(s) "
+          f"bound to {os.path.relpath(marker, write_root)}")
+
+
+def run(host, argv=None):
+    """Host-seam entry point (ADR-0011): the __main__ guard calls this with the
+    plugin's loaded Host. Wraps main() unchanged — main() still communicates
+    via sys.exit/stdout/stderr, and its return value stays discarded exactly
+    as the old bare `main()` guard discarded it (so the process still exits 0
+    on a normal fall-through).
+
+    Wires `host` live (#257): primes `_hooklib`'s process-cached Host via
+    `set_host()` BEFORE main() runs, so any `get_host()` call downstream
+    resolves to the SAME instance the caller passed here — no second
+    `hostapi.load_host()`, and `run(fake_host)` genuinely exercises
+    `fake_host`."""
+    return _entrylib.dispatch(host, argv, main, set_host,
+                               pass_argv=False, propagate_result=False)
+
+
+if __name__ == "__main__":
+    sys.exit(run(hostapi.load_host()) or 0)