Guarded file, fetch and exec IO that strips secrets, hash-only receipts.

python -m pip install "secret-redact-io @ git+https://github.com/HarperZ9/secret-redact-io.git@v0.1.0"

Brand assets: docs/art/ (hero, social preview) and docs/brand/ (mark, lockups).

The animated explainer walks through the seven redaction rules, an in-memory redaction, guarded reads, dry-run writes and subprocess output, a receipt that holds no secret, and a credential in plain words that no rule can catch. Every value on it is output from this repository. Its source is docs/explainer/index.html.

Install it, run it once, then use the main feature. Each command below is real, and so is its output.

1. Install. Install the pinned release from GitHub. Python 3.10 or newer; it is not on PyPI.

   $ python -m pip install "secret-redact-io @ git+https://github.com/HarperZ9/secret-redact-io.git@v0.1.0"
   

2. First run: redact text. In Python, redact a token and a password before the text goes anywhere.

   >>> policy.redact_text("token=ghp_bbbb...b\npassword=hunter2")
   token=[REDACTED:github_token] | password=[REDACTED:credential_field]
   counts: {'github_token': 1, 'credential_field': 1}
   total:  2
   

3. Guard a write. A guarded write in dry-run mode shows what it would write, redacted, and writes nothing.

   >>> write_text_guarded(target, "api_key: ...", dry_run=True)
   text:     api_key: [REDACTED:credential_field]
   operation: write.dry_run
   written:  False
   file exists on disk: False
   

4. Guard a command's output. A guarded run redacts what the command prints.

   >>> run_guarded(["python", "-c", "print('token=ghp_bbbb...b')"])
   returncode: 0
   stdout:     token=[REDACTED:github_token]
   redactions: {'github_token': 1}
   

Agents need IO, but raw IO can leak credentials or private payloads into logs and model context. Secret Redact IO gives tools a small guarded boundary: outputs are redacted, receipts are hash-only, and the original secret-shaped values are not archived.

• Read a file that contains a fake token and confirm the returned text is redacted.
• Run the dry-run write path and inspect the receipt before anything is persisted.
• Execute a subprocess that prints a fake secret and confirm stdout is redacted.

Stdlib-only guarded file/fetch/subprocess IO: strips API keys, tokens, and PEM keys; emits hash-only receipts.

secret-redact-io is a small Python SDK and CLI for guarded IO. It wraps file reads, file writes, HTTP fetches, and subprocess execution with redaction and hash-only audit receipts.

The default posture is conservative:

• user-facing output is redacted before it is returned;
• guarded writes persist redacted content by default;
• receipts store byte counts, hashes, status metadata, and redaction counts;
• receipts do not archive raw input or raw secret values.

secret-redact-io is not currently published on PyPI. A bare python -m pip install secret-redact-io will fail until a package registry release exists.

For a pinned release install, use the GitHub release tag:

python -m pip install "secret-redact-io @ git+https://github.com/HarperZ9/secret-redact-io.git@v0.1.0"

For local examples and tests, use a source checkout:

git clone https://github.com/HarperZ9/secret-redact-io
cd secret-redact-io
python -m pip install -e ".[dev]"

secret-redact-io read README.md --json
secret-redact-io write out.txt --content "note=hello" --dry-run --json
secret-redact-io fetch https://example.com --json
secret-redact-io exec --json -- python -c "print('hello')"

from secret_redact_io import read_text_guarded, run_guarded

read_result = read_text_guarded("README.md")
print(read_result.text)
print(read_result.receipt.to_json())

exec_result = run_guarded(["python", "-c", "print('hello')"])
print(exec_result.stdout)

Nine keys, and seven of them are a hash, a count, or a name the tool trimmed itself. target keeps a path, a host and path, or a program name, and drops arguments and query strings before it is set. metadata is the exception: it holds what the caller handed over, and nothing redacts it.

See USAGE.md for an install line, the full CLI and Python API surface, and worked examples with expected output. A runnable end-to-end demo lives in examples/demo.py.

This package is a public, self-contained guardrail utility. It does not include credentials, secrets, or any deployment-specific configuration.

The policy is seven patterns and stays seven. Each one matches a shape, so a private key block, a key carrying a known prefix, or a value beside the word password is caught. A credential that reads as ordinary prose has no shape to match and survives the pass. That is the honest edge of the tool, and it is why the receipt reports which rules fired rather than claiming the text is clean.

Zain Dana Harper -- small tools with explicit edges. Portfolio · HarperZ9 _{Built with Claude Code; reviewed, tested, and owned by me.}

Keep the public README, package metadata, and examples aligned with current behavior. Before opening a PR or pushing a release, run the local package verification path.

python -m pip install -e ".[dev]"
python -m pytest
python scripts/check_public_surface.py
python -m build

See AGENTS.md for the repo-specific operating boundary and CHANGELOG.md for current delivery status.

Built by Zain Dana Harper in Seattle: evidence-first tools that leave a re-checkable artifact behind. The full workbench is at Project Telos.