receipt-evidence 0.1.0__tar.gz

receipt_evidence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritish Saini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

receipt_evidence-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: receipt-evidence
+Version: 0.1.0
+Summary: Run a command, and get a receipt for what it actually touched -- not just what it was asked to do.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/receipt
+Project-URL: Source, https://github.com/MaXiMo000/receipt
+Project-URL: Issues, https://github.com/MaXiMo000/receipt/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/receipt/releases
+Keywords: verification,audit,agents,provenance,evidence
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# receipt
+
+**Run a command. Get a receipt for what it actually touched — not just what
+it was asked to do.**
+
+An AI agent (or a script, or a CI job) says it's going to fix a bug in one
+file. Nothing checks whether that's what it actually did until someone
+reviews the diff by hand, if they do at all. `receipt` snapshots the working
+directory before and after, and reports `pass`, `fail`, or `unverified` —
+same three-status shape as
+[invariant](https://github.com/MaXiMo000/invariant),
+[firedrill](https://github.com/MaXiMo000/firedrill), and
+[carabiner](https://github.com/MaXiMo000/carabiner).
+
+```
+$ receipt run --task "fix the auth bug" --declare app/auth.py \
+    -- python fix_auth.py
+[FAIL] touched 1 undeclared file(s): app/payments.py
+receipt written to receipts/20260908T121251Z-4f2c9a1b.json
+```
+
+## Three statuses, one of them meaning something different here
+
+`pass` — touched only what was declared. `fail` — touched something outside
+the declared scope, named exactly. `unverified` — no scope was declared for
+this run at all.
+
+That third one is a deliberate difference from invariant/firedrill/
+carabiner, where `unverified` means "a check that should have run, didn't."
+Here it means "no promise was made this time" — plain audit logging is a
+normal, legitimate use of this tool, not a degraded one. So `unverified`
+does **not** fail the build; only a broken declared promise (`fail`) does.
+
+## What it actually does
+
+1. Hashes and permission-bits every file under the watched directory (sha256
+   + mode, skipping `.git`, `__pycache__`, etc.).
+2. Runs the given command, captures stdout/stderr/exit code/timing, and
+   redacts secret-shaped text (env-var-style `API_KEY=...` assignments,
+   credentialed URLs, well-known token prefixes, PEM key blocks) before any
+   of it is stored — see "What redaction doesn't mean" below. A command that
+   never launches at all (bad `--dir`, missing binary) still produces a
+   receipt — `fail`, with the launch error as the detail — instead of a
+   Python traceback and no evidence.
+3. Snapshots the directory again, diffs the two. A removed path and an added
+   path with identical content are reported as one `renamed` pair, not an
+   unrelated delete-plus-create; a path whose content is byte-identical but
+   whose permission bits changed is reported as `mode_changed` — see "What
+   `touched` means" below.
+4. If a scope was declared (exact paths, or glob patterns like `app/*.py`),
+   checks the diff against it.
+5. Writes the whole thing — command, task, diff, declared scope, verdict —
+   to `receipts/<timestamp>-<random>.json` alongside a sha256 of the receipt
+   itself, same evidence-bundle idiom as invariant's `--evidence`.
+
+Zero dependencies — stdlib only (`hashlib`, `subprocess`, `argparse`,
+`fnmatch`).
+
+## Install
+
+```bash
+pip install receipt-evidence        # the command it installs is `receipt`
+```
+
+Or from a checkout, for development:
+
+```bash
+pip install -e .
+```
+
+## Use
+
+```bash
+receipt run --task "what this is supposed to do" \
+  --declare path/one.py,app/*.py \
+  --dir . --out receipts/ \
+  -- your-command --with --args
+```
+
+Omit `--declare` to just log what happened without a scope to check it
+against (`unverified`, still a written receipt, still exit 0).
+
+## Test
+
+```bash
+python tests/test_receipt.py
+```
+
+## What `touched` means
+
+`touched` is the union of every file that was added, removed, had its
+content modified, was renamed (a removed path and an added path sharing a
+content hash), or had its permission bits changed with content otherwise
+identical. A rename or a chmod on a path outside the declared scope is a
+real `fail`, named clearly — `sneaky.txt (renamed from output.txt)`, or
+`secret.env (permissions changed, content unchanged)` — not silently
+folded into "nothing happened" the way a plain content-hash diff would.
+
+## What `pass` doesn't mean
+
+`pass` only means "touched nothing outside the declared scope **within
+`--dir`**." A write anywhere outside that tree — `/tmp`, `~`, a sibling
+directory, an absolute path elsewhere in a monorepo — is invisible to
+`receipt` and won't affect the verdict. Point `--dir` at the smallest tree
+that actually bounds what the task could legitimately touch; don't read
+`pass` as "touched nothing on the filesystem."
+
+## What redaction doesn't mean
+
+Captured stdout/stderr and the command's own argv are swept for
+secret-shaped text (`receipt/redact.py`) before a receipt is written — this
+closes a real gap found during review: a wrapped command that echoed
+`API_KEY=sk-...` landed that value verbatim in the receipt JSON. The sweep
+is a regex net for common shapes, not a guarantee. It will not catch a
+secret with no recognizable shape (e.g. a bare 40-character hex string with
+no key name attached, split across two log lines, or base64-wrapped). If a
+command's output might contain something sensitive in an unusual shape,
+don't assume the receipt is safe to share as-is — read it first.
+
+## What's deliberately not here yet
+
+No network/API-call capture — only filesystem diffing. "What did this agent
+touch" is answerable this way; "what did this agent call" isn't, without
+hooking into a specific agent framework's own trace or intercepting
+traffic, which is a real, separate, much bigger project.
+
+No policy evaluation or rule composition beyond a flat declared-scope
+check — that's deliberately a different tool's job. `receipt` stays the
+evidence producer;
+[invariant](https://github.com/MaXiMo000/invariant) is where richer policy
+(is this evidence actually OK, across multiple runs, with other checks
+composed in) belongs.
+
+MIT licensed.

receipt_evidence-0.1.0/README.md

@@ -0,0 +1,134 @@
+# receipt
+
+**Run a command. Get a receipt for what it actually touched — not just what
+it was asked to do.**
+
+An AI agent (or a script, or a CI job) says it's going to fix a bug in one
+file. Nothing checks whether that's what it actually did until someone
+reviews the diff by hand, if they do at all. `receipt` snapshots the working
+directory before and after, and reports `pass`, `fail`, or `unverified` —
+same three-status shape as
+[invariant](https://github.com/MaXiMo000/invariant),
+[firedrill](https://github.com/MaXiMo000/firedrill), and
+[carabiner](https://github.com/MaXiMo000/carabiner).
+
+```
+$ receipt run --task "fix the auth bug" --declare app/auth.py \
+    -- python fix_auth.py
+[FAIL] touched 1 undeclared file(s): app/payments.py
+receipt written to receipts/20260908T121251Z-4f2c9a1b.json
+```
+
+## Three statuses, one of them meaning something different here
+
+`pass` — touched only what was declared. `fail` — touched something outside
+the declared scope, named exactly. `unverified` — no scope was declared for
+this run at all.
+
+That third one is a deliberate difference from invariant/firedrill/
+carabiner, where `unverified` means "a check that should have run, didn't."
+Here it means "no promise was made this time" — plain audit logging is a
+normal, legitimate use of this tool, not a degraded one. So `unverified`
+does **not** fail the build; only a broken declared promise (`fail`) does.
+
+## What it actually does
+
+1. Hashes and permission-bits every file under the watched directory (sha256
+   + mode, skipping `.git`, `__pycache__`, etc.).
+2. Runs the given command, captures stdout/stderr/exit code/timing, and
+   redacts secret-shaped text (env-var-style `API_KEY=...` assignments,
+   credentialed URLs, well-known token prefixes, PEM key blocks) before any
+   of it is stored — see "What redaction doesn't mean" below. A command that
+   never launches at all (bad `--dir`, missing binary) still produces a
+   receipt — `fail`, with the launch error as the detail — instead of a
+   Python traceback and no evidence.
+3. Snapshots the directory again, diffs the two. A removed path and an added
+   path with identical content are reported as one `renamed` pair, not an
+   unrelated delete-plus-create; a path whose content is byte-identical but
+   whose permission bits changed is reported as `mode_changed` — see "What
+   `touched` means" below.
+4. If a scope was declared (exact paths, or glob patterns like `app/*.py`),
+   checks the diff against it.
+5. Writes the whole thing — command, task, diff, declared scope, verdict —
+   to `receipts/<timestamp>-<random>.json` alongside a sha256 of the receipt
+   itself, same evidence-bundle idiom as invariant's `--evidence`.
+
+Zero dependencies — stdlib only (`hashlib`, `subprocess`, `argparse`,
+`fnmatch`).
+
+## Install
+
+```bash
+pip install receipt-evidence        # the command it installs is `receipt`
+```
+
+Or from a checkout, for development:
+
+```bash
+pip install -e .
+```
+
+## Use
+
+```bash
+receipt run --task "what this is supposed to do" \
+  --declare path/one.py,app/*.py \
+  --dir . --out receipts/ \
+  -- your-command --with --args
+```
+
+Omit `--declare` to just log what happened without a scope to check it
+against (`unverified`, still a written receipt, still exit 0).
+
+## Test
+
+```bash
+python tests/test_receipt.py
+```
+
+## What `touched` means
+
+`touched` is the union of every file that was added, removed, had its
+content modified, was renamed (a removed path and an added path sharing a
+content hash), or had its permission bits changed with content otherwise
+identical. A rename or a chmod on a path outside the declared scope is a
+real `fail`, named clearly — `sneaky.txt (renamed from output.txt)`, or
+`secret.env (permissions changed, content unchanged)` — not silently
+folded into "nothing happened" the way a plain content-hash diff would.
+
+## What `pass` doesn't mean
+
+`pass` only means "touched nothing outside the declared scope **within
+`--dir`**." A write anywhere outside that tree — `/tmp`, `~`, a sibling
+directory, an absolute path elsewhere in a monorepo — is invisible to
+`receipt` and won't affect the verdict. Point `--dir` at the smallest tree
+that actually bounds what the task could legitimately touch; don't read
+`pass` as "touched nothing on the filesystem."
+
+## What redaction doesn't mean
+
+Captured stdout/stderr and the command's own argv are swept for
+secret-shaped text (`receipt/redact.py`) before a receipt is written — this
+closes a real gap found during review: a wrapped command that echoed
+`API_KEY=sk-...` landed that value verbatim in the receipt JSON. The sweep
+is a regex net for common shapes, not a guarantee. It will not catch a
+secret with no recognizable shape (e.g. a bare 40-character hex string with
+no key name attached, split across two log lines, or base64-wrapped). If a
+command's output might contain something sensitive in an unusual shape,
+don't assume the receipt is safe to share as-is — read it first.
+
+## What's deliberately not here yet
+
+No network/API-call capture — only filesystem diffing. "What did this agent
+touch" is answerable this way; "what did this agent call" isn't, without
+hooking into a specific agent framework's own trace or intercepting
+traffic, which is a real, separate, much bigger project.
+
+No policy evaluation or rule composition beyond a flat declared-scope
+check — that's deliberately a different tool's job. `receipt` stays the
+evidence producer;
+[invariant](https://github.com/MaXiMo000/invariant) is where richer policy
+(is this evidence actually OK, across multiple runs, with other checks
+composed in) belongs.
+
+MIT licensed.

receipt_evidence-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+# The command stays `receipt`; the distribution cannot -- both "receipt" and
+# "receipt-verify" are already taken on PyPI (checked, not assumed). A
+# distribution name differing from the command it installs is ordinary
+# (python-dateutil installs `dateutil`).
+name = "receipt-evidence"
+version = "0.1.0"
+description = "Run a command, and get a receipt for what it actually touched -- not just what it was asked to do."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["verification", "audit", "agents", "provenance", "evidence"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = []
+
+urls.Homepage = "https://github.com/MaXiMo000/receipt"
+urls.Source = "https://github.com/MaXiMo000/receipt"
+urls.Issues = "https://github.com/MaXiMo000/receipt/issues"
+urls.Changelog = "https://github.com/MaXiMo000/receipt/releases"
+
+[project.scripts]
+receipt = "receipt.cli:main"
+
+[build-system]
+# 77 is the floor for PEP 639 (`license = "MIT"` as an SPDX expression) --
+# a lesson already paid for in a sibling project's own release workflow,
+# applied here before it bites this one too.
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["receipt*"]

receipt_evidence-0.1.0/receipt/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

receipt_evidence-0.1.0/receipt/cli.py

@@ -0,0 +1,52 @@
+"""receipt run --task "..." [--declare a.py,app/*.py] [--out receipts/] -- <command...>"""
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .core import run as run_task
+from .evidence import write as write_receipt
+from .model import FAIL
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if "--" in argv:
+        split = argv.index("--")
+        own_args, cmd = argv[:split], argv[split + 1:]
+    else:
+        own_args, cmd = argv, []
+
+    parser = argparse.ArgumentParser(prog="receipt")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_p = sub.add_parser("run", help="run a command and receipt what it touched")
+    run_p.add_argument("--task", required=True, help="what the command was asked to do")
+    run_p.add_argument("--dir", default=".", dest="watch_dir", help="directory to watch (default: .)")
+    run_p.add_argument("--declare", default=None,
+                        help="comma-separated relative paths (globs like app/*.py allowed) the "
+                             "task is allowed to touch; omit to record without a declared scope "
+                             "(status: unverified)")
+    run_p.add_argument("--out", default="receipts", help="directory to write the receipt into")
+
+    args = parser.parse_args(own_args)
+
+    if not cmd:
+        print("error: no command given -- pass it after `--`", file=sys.stderr)
+        return 2
+
+    declared = args.declare.split(",") if args.declare else None
+    result = run_task(args.task, cmd, watch_dir=args.watch_dir, declared_paths=declared)
+    path = write_receipt(result, args.out)
+
+    print(f"[{result['status'].upper()}] {result['detail']}")
+    print(f"receipt written to {path}")
+
+    # Unlike invariant, `unverified` here is not a failure to gain
+    # assurance -- it's "no scope was promised this run," a normal mode
+    # (plain audit logging). Only a broken promise (FAIL) fails the build.
+    return 1 if result["status"] == FAIL else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

receipt_evidence-0.1.0/receipt/core.py

@@ -0,0 +1,123 @@
+"""Run a command, snapshot its working directory before and after, and check
+what it actually touched against what it was declared to touch.
+
+This is the whole tool: everything else (CLI, evidence writer) is plumbing
+around this one function.
+"""
+from __future__ import annotations
+
+import fnmatch
+import subprocess
+import time
+
+from . import model
+from .redact import redact
+from .snapshot import diff as diff_snapshots
+from .snapshot import snapshot
+
+
+def _is_declared(path: str, declared: set[str]) -> bool:
+    """A path is covered if it's an exact declared entry, or matches one as
+    a glob (`fnmatch`, case-sensitive on every platform -- consistent
+    matching regardless of OS matters more here than following whatever
+    case convention the local filesystem happens to use).
+
+    Exact match is checked first and separately so a literal declared path
+    containing an unintentional glob character (`[`, `]`, `?`, `*` in a
+    real filename) still matches itself even if it also happens to be a
+    strange glob pattern -- globs are additive, not a replacement for
+    exact matching.
+    """
+    if path in declared:
+        return True
+    return any(fnmatch.fnmatchcase(path, pattern) for pattern in declared)
+
+
+def run(task: str, cmd: list[str], watch_dir: str = ".",
+        declared_paths: list[str] | None = None) -> dict:
+    """Execute `cmd` in `watch_dir`, and report what changed there.
+
+    declared_paths, if given, is the set of relative paths (or glob
+    patterns, e.g. `app/*.py`) the task claimed it would touch. Anything
+    touched that doesn't match one of them is a `fail`. If declared_paths
+    is None, no claim was made -- the receipt still records exactly what
+    happened, but the status is `unverified`: there's nothing to check the
+    touched files against.
+    """
+    before = snapshot(watch_dir)
+    started = time.monotonic()
+    try:
+        proc = subprocess.run(cmd, cwd=watch_dir, capture_output=True, text=True, errors="replace")
+    except OSError as exc:
+        # The command never ran at all -- `--dir` doesn't exist, the binary
+        # isn't found, no permission to execute it. The one promise this
+        # tool makes is "get a receipt for what actually happened," and
+        # that has to hold here too: report it as a receipt, don't crash
+        # before any evidence exists at all. Nothing ran, so nothing was
+        # touched -- but the declared promise clearly wasn't kept either,
+        # which is a fail, not "nothing to check" (that's what an absent
+        # --declare means, a different situation from this one).
+        return {
+            "task": task,
+            "command": [redact(part) for part in cmd],
+            "watch_dir": watch_dir,
+            "exit_code": None,
+            "seconds": round(time.monotonic() - started, 3),
+            "stdout": "",
+            "stderr": "",
+            "declared_paths": declared_paths,
+            "changes": {"added": [], "modified": [], "removed": [], "renamed": [], "mode_changed": []},
+            "unexpected": [],
+            "status": model.FAIL,
+            "detail": f"could not launch the command: {exc}",
+        }
+    seconds = time.monotonic() - started
+    after = snapshot(watch_dir)
+
+    changes = diff_snapshots(before, after)
+    renamed_endpoints = {r["from"] for r in changes["renamed"]} | {r["to"] for r in changes["renamed"]}
+    touched = sorted(set(changes["added"]) | set(changes["modified"]) | set(changes["removed"])
+                      | renamed_endpoints | set(changes["mode_changed"]))
+
+    rename_from_by_to = {r["to"]: r["from"] for r in changes["renamed"]}
+    mode_only_changed = set(changes["mode_changed"])
+
+    def _annotate(p: str) -> str:
+        if p in rename_from_by_to:
+            # Name a renamed file's origin too -- "touched b.txt" alone
+            # hides that it's actually the declared a.txt under a new
+            # name, which is exactly the context someone needs to see
+            # this isn't an undeclared *new* file appearing from nowhere.
+            return f"{p} (renamed from {rename_from_by_to[p]})"
+        if p in mode_only_changed:
+            return f"{p} (permissions changed, content unchanged)"
+        return p
+
+    if declared_paths is None:
+        status = model.UNVERIFIED
+        unexpected: list[str] = []
+        detail = f"{len(touched)} file(s) touched; no declared scope to check against"
+    else:
+        declared = set(declared_paths)
+        unexpected = [p for p in touched if not _is_declared(p, declared)]
+        if unexpected:
+            status = model.FAIL
+            detail = f"touched {len(unexpected)} undeclared file(s): {', '.join(_annotate(p) for p in unexpected)}"
+        else:
+            status = model.PASS
+            detail = f"touched only what was declared ({len(touched)} file(s))"
+
+    return {
+        "task": task,
+        "command": [redact(part) for part in cmd],
+        "watch_dir": watch_dir,
+        "exit_code": proc.returncode,
+        "seconds": round(seconds, 3),
+        "stdout": redact(proc.stdout),
+        "stderr": redact(proc.stderr),
+        "declared_paths": declared_paths,
+        "changes": changes,
+        "unexpected": unexpected,
+        "status": status,
+        "detail": detail,
+    }

receipt_evidence-0.1.0/receipt/evidence.py

@@ -0,0 +1,43 @@
+"""Write a receipt to disk: the full record plus a sha256, so it can be
+checked later without taking the run's word for it. Same idiom as
+invariant's evidence.py, one file per receipt instead of one per check.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import pathlib
+import secrets
+import time
+
+# Bump when the receipt dict's shape changes in a way a consumer parsing
+# the JSON would need to know about (a field renamed or removed -- adding
+# a new field is not a breaking change and doesn't need a bump).
+SCHEMA_VERSION = 1
+
+
+def write(result: dict, out_dir: str | pathlib.Path) -> pathlib.Path:
+    out_dir = pathlib.Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    stamp = time.strftime("%Y%m%dT%H%M%SZ", time.gmtime())
+    # A second-resolution timestamp alone collides silently: two runs
+    # started within the same second (a script looping `receipt run`, two
+    # parallel CI jobs sharing --out) would overwrite each other with no
+    # error -- confirmed live, not hypothetical. The random suffix costs
+    # nothing and makes every receipt's filename unique regardless of
+    # timing.
+    suffix = secrets.token_hex(4)
+    path = out_dir / f"{stamp}-{suffix}.json"
+
+    blob = json.dumps(result, indent=2, sort_keys=True, default=str)
+    digest = hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+    record = {
+        "schema_version": SCHEMA_VERSION,
+        "receipt": result,
+        "sha256": digest,
+        "written_at": time.time(),
+    }
+    path.write_text(json.dumps(record, indent=2, sort_keys=True, default=str), encoding="utf-8")
+    return path

receipt_evidence-0.1.0/receipt/model.py

@@ -0,0 +1,9 @@
+"""Three statuses, same shape as invariant/firedrill/carabiner.
+
+`unverified` here means "no scope was declared" -- the task ran and the
+receipt records exactly what it touched, but there was nothing to check that
+against, so calling it a pass would claim more than was actually verified.
+"""
+PASS = "pass"
+FAIL = "fail"
+UNVERIFIED = "unverified"

receipt_evidence-0.1.0/receipt/redact.py

@@ -0,0 +1,58 @@
+"""Best-effort redaction of secret-shaped text before it's written into a
+receipt.
+
+Not a guarantee -- a regex sweep can't catch every shape a secret takes --
+but it closes the exact failure mode found live during the portfolio audit:
+a wrapped command's own stdout/stderr echoing a real credential
+(`API_KEY=sk-supersecret12345`) landed verbatim in the receipt JSON on disk.
+Receipts are meant to be kept and handed to someone else as evidence; the
+evidence artifact itself must not be a credential-leak vector.
+"""
+from __future__ import annotations
+
+import re
+
+MASK = "[REDACTED]"
+
+# key=value / key: value pairs where the key name says "this is a secret" --
+# the most common real leak shape (the exact one confirmed live in the
+# audit: an env var echoed by the wrapped command).
+_KEYED = re.compile(
+    r"(?i)\b([A-Za-z0-9_]*(?:SECRET|TOKEN|API[_-]?KEY|ACCESS[_-]?KEY|"
+    r"PASSWORD|PASSWD|PWD|CREDENTIAL)[A-Za-z0-9_]*)(\s*[:=]\s*)(['\"]?)(\S+)\3"
+)
+
+# scheme://user:pass@host -- a DSN or an authenticated URL carrying a
+# credential in its userinfo component (the same shape as invariant's DSN
+# leak, in case a wrapped command prints a connection string).
+_URL_CRED = re.compile(r"([a-zA-Z][a-zA-Z0-9+.\-]*://)([^:/\s@]+):([^@/\s]+)@")
+
+# Recognizable provider token prefixes -- these are secrets on sight,
+# regardless of what surrounds them.
+_PREFIXED = re.compile(
+    r"\b(sk-[A-Za-z0-9]{10,}|ghp_[A-Za-z0-9]{20,}|gho_[A-Za-z0-9]{20,}|"
+    r"github_pat_[A-Za-z0-9_]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}|"
+    r"AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z\-_]{30,})\b"
+)
+
+_PEM_BLOCK = re.compile(
+    r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----",
+    re.DOTALL,
+)
+
+
+def redact(text: str) -> str:
+    """Returns `text` with secret-shaped substrings replaced by a mask.
+
+    Applied to captured stdout/stderr before a receipt is written. Best
+    effort, not exhaustive -- it catches the common shapes (env-var-style
+    key=value pairs, credentialed URLs, well-known token prefixes, PEM
+    private key blocks), not every possible one.
+    """
+    if not text:
+        return text
+    text = _PEM_BLOCK.sub(MASK, text)
+    text = _URL_CRED.sub(lambda m: f"{m.group(1)}{m.group(2)}:{MASK}@", text)
+    text = _KEYED.sub(lambda m: f"{m.group(1)}{m.group(2)}{MASK}", text)
+    text = _PREFIXED.sub(MASK, text)
+    return text