content-guard 0.1.1__tar.gz

content_guard-0.1.1/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: content-guard
+Version: 0.1.1
+Summary: Policy-driven content scanning and redaction for public publishing and agent output.
+Author: Solomon Neas
+License: Apache-2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/assets/content-guard-banner.jpg" alt="Content Guard banner">
+</p>
+
+<h1 align="center">Content Guard</h1>
+
+<p align="center">
+  <strong>Policy-driven scanning and redaction for public content, publishing pipelines, and agent output.</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge" alt="Apache-2.0 license">
+  <img src="https://img.shields.io/badge/dependencies-zero_required-2ea44f?style=for-the-badge" alt="Zero required third-party dependencies">
+  <img src="https://img.shields.io/badge/OPF-optional-8A2BE2?style=for-the-badge" alt="Optional OPF backend">
+  <img src="https://img.shields.io/badge/markdown-aware-083344?style=for-the-badge&logo=markdown&logoColor=white" alt="Markdown aware">
+</p>
+
+Content Guard keeps private infrastructure, secrets, and personal context out of public surfaces before they ship. It is built for Markdown docs, PR bodies, social drafts, generated agent output, and automation pipelines where one sloppy paste can leak more than intended.
+
+It takes the practical parts of the local content scrubber and the useful model-backed idea behind Privacy Filter, then turns them into one maintainable system.
+
+## What It Checks
+
+- Deterministic rules for infrastructure, secrets, and high-confidence patterns
+- Optional OPF backend for model-based PII review and redaction
+- Custom policy files for private names, internal projects, unreleased plans, and environment-specific rules
+- Blocking, warning, redaction, and allow decisions from one report format
+- Markdown-aware scanning with frontmatter and allow-comment support
+
+The core package has no required third-party dependencies. OPF is optional and runs through its CLI when available.
+
+## Quick Start
+
+Install from a local clone:
+
+```bash
+python -m pip install -e .
+```
+
+Scan or redact a file:
+
+```bash
+content-guard scan examples/sample.md --policy policies/public-content.json
+content-guard redact examples/sample.md --policy policies/public-content.json
+content-guard scan examples/sample.md --json
+content-guard scan examples/ --policy policies/public-content.json
+```
+
+Use OPF if it is installed locally:
+
+```bash
+content-guard redact examples/sample.md --opf
+```
+
+By default, `--opf` looks for `~/.opf-venv/bin/opf`. Override it with:
+
+```bash
+CONTENT_GUARD_OPF_BIN=/path/to/opf content-guard scan file.md --opf
+```
+
+OPF can also be enabled from a policy file:
+
+```json
+{
+  "backends": {
+    "opf": {
+      "enabled": true,
+      "action": "warn",
+      "device": "cpu"
+    }
+  }
+}
+```
+
+## Policies
+
+Policies are JSON so the project stays dependency-free. A policy can set default actions by category, override individual rules, and add private custom regex rules.
+
+```json
+{
+  "name": "public-content",
+  "defaults": {
+    "infrastructure": "block",
+    "secret": "block",
+    "pii": "warn"
+  },
+  "rules": {
+    "email": "warn"
+  },
+  "custom_rules": [
+    {
+      "id": "internal-hostname-example",
+      "category": "infrastructure",
+      "pattern": "\\\\binternal-host\\\\b",
+      "replacement": "[redacted-host]"
+    }
+  ]
+}
+```
+
+Actions:
+
+- `block`: fail the scan, usually for publish gates
+- `redact`: rewrite matching content
+- `warn`: report without failing
+- `allow`: ignore matching findings
+
+### Bundled Policies
+
+Two bundled policies share the `infrastructure` category but treat it differently on purpose:
+
+- `policies/public-repo.json`: for technical docs repos. It keeps `private-ipv4` (RFC 1918), secrets, PII, and `Co-authored-by` trailers as hard blocks, but downgrades `loopback-ipv4` (127.x), `localhost-port`, `localhost-bare`, and `port-reference` to warnings. README and CONTRIBUTING files often need to discuss `localhost`, named ports, and `127.0.0.1` for setup instructions. See [policies/public-repo.md](policies/public-repo.md) for the long-form rationale.
+- `policies/public-content.json`: for blog posts and social drafts. It keeps the full infrastructure category at block because marketing surfaces have a higher leak risk and should not expose internal addresses or named ports.
+
+## Allow Comments
+
+Use a local allow comment on the same line or directly above a line:
+
+```md
+<!-- content-guard: allow localhost-bare -->
+This tutorial uses localhost as an example.
+```
+
+Use `content-guard: allow all` sparingly for examples where every finding is intentional.
+
+## PR and Git Guards
+
+PR bodies and public repository content are publishing boundaries too. Use stricter policies before copying generated summaries, dogfood notes, local test output, fixtures, or docs into public GitHub surfaces:
+
+```bash
+content-guard scan examples/pr-body.md --policy policies/pr-draft.json
+content-guard diff examples/pr-body.md --policy policies/pr-draft.json
+content-guard-pr examples/pr-body.md
+content-guard-pr-prepare examples/pr-body.md --json
+content-guard-publish-check --pr-body examples/pr-body.md --json
+content-guard-n8n-advisory < payload.json
+content-guard-n8n-validate --json
+content-guard-git --policy policies/public-repo.json
+content-guard-git --all-tracked --policy policies/public-repo.json
+content-guard-commits --range origin/main..HEAD --policy policies/public-repo.json
+```
+
+See [docs/PR_DRAFTS.md](docs/PR_DRAFTS.md) and [docs/GIT_PUBLIC_REPO_GUARD.md](docs/GIT_PUBLIC_REPO_GUARD.md).
+
+Use `content-guard-publish-check` as the practical local pre-publish wrapper. It prepares a sanitized PR body when `--pr-body` is provided, scans staged files, scans commit messages, and can optionally scan all tracked files:
+
+```bash
+content-guard-publish-check --pr-body pr-body.md --json
+content-guard-publish-check --pr-body pr-body.md --all-tracked
+```
+
+PR body findings are advisory by default because the wrapper writes a sanitized body and prints `publish_body_file`. Staged file, commit message, and optional all-tracked blockers fail the command unless `--advisory-only` is set.
+
+Use `content-guard-pr-prepare` when a later PR publishing step needs a stable sanitized body path:
+
+```bash
+content-guard-pr-prepare pr-body.md
+gh pr create --body-file .content-guard/pr-drafts/pr-body.public.md
+```
+
+For local run-alongside testing against the legacy scrubber, see [docs/DOGFOOD_TEST_REPO.md](docs/DOGFOOD_TEST_REPO.md).
+
+For n8n publish workflows, start with an advisory step that reports findings without mutating live publishes. See [docs/N8N_ADVISORY.md](docs/N8N_ADVISORY.md) and [docs/N8N_WORKFLOW_RECIPE.md](docs/N8N_WORKFLOW_RECIPE.md). Validate cloned workflow wiring with [docs/N8N_VALIDATION_PACK.md](docs/N8N_VALIDATION_PACK.md).
+
+## OpenClaw Plugin
+
+Content Guard can also run as an OpenClaw outbound message plugin. The plugin lives in `openclaw-plugin/` and shells out to the same Python engine, so OpenClaw messages use the same policy model as publish gates.
+
+See [docs/OPENCLAW_PLUGIN.md](docs/OPENCLAW_PLUGIN.md).
+
+## Design Notes
+
+Privacy Filter influenced the optional model-backed PII layer, especially the idea that some personal data detection benefits from context. Content Guard does not copy Privacy Filter code. OPF integration is a subprocess adapter so the deterministic engine remains portable and maintainable.
+
+The deterministic rules are intentionally conservative. Public publishing should fail loudly on infrastructure and secret leakage, while model findings are better treated as review signals until a local policy proves they are reliable enough to block.

content_guard-0.1.1/README.md

@@ -0,0 +1,176 @@
+<p align="center">
+  <img src="docs/assets/content-guard-banner.jpg" alt="Content Guard banner">
+</p>
+
+<h1 align="center">Content Guard</h1>
+
+<p align="center">
+  <strong>Policy-driven scanning and redaction for public content, publishing pipelines, and agent output.</strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python 3.11+">
+  <img src="https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge" alt="Apache-2.0 license">
+  <img src="https://img.shields.io/badge/dependencies-zero_required-2ea44f?style=for-the-badge" alt="Zero required third-party dependencies">
+  <img src="https://img.shields.io/badge/OPF-optional-8A2BE2?style=for-the-badge" alt="Optional OPF backend">
+  <img src="https://img.shields.io/badge/markdown-aware-083344?style=for-the-badge&logo=markdown&logoColor=white" alt="Markdown aware">
+</p>
+
+Content Guard keeps private infrastructure, secrets, and personal context out of public surfaces before they ship. It is built for Markdown docs, PR bodies, social drafts, generated agent output, and automation pipelines where one sloppy paste can leak more than intended.
+
+It takes the practical parts of the local content scrubber and the useful model-backed idea behind Privacy Filter, then turns them into one maintainable system.
+
+## What It Checks
+
+- Deterministic rules for infrastructure, secrets, and high-confidence patterns
+- Optional OPF backend for model-based PII review and redaction
+- Custom policy files for private names, internal projects, unreleased plans, and environment-specific rules
+- Blocking, warning, redaction, and allow decisions from one report format
+- Markdown-aware scanning with frontmatter and allow-comment support
+
+The core package has no required third-party dependencies. OPF is optional and runs through its CLI when available.
+
+## Quick Start
+
+Install from a local clone:
+
+```bash
+python -m pip install -e .
+```
+
+Scan or redact a file:
+
+```bash
+content-guard scan examples/sample.md --policy policies/public-content.json
+content-guard redact examples/sample.md --policy policies/public-content.json
+content-guard scan examples/sample.md --json
+content-guard scan examples/ --policy policies/public-content.json
+```
+
+Use OPF if it is installed locally:
+
+```bash
+content-guard redact examples/sample.md --opf
+```
+
+By default, `--opf` looks for `~/.opf-venv/bin/opf`. Override it with:
+
+```bash
+CONTENT_GUARD_OPF_BIN=/path/to/opf content-guard scan file.md --opf
+```
+
+OPF can also be enabled from a policy file:
+
+```json
+{
+  "backends": {
+    "opf": {
+      "enabled": true,
+      "action": "warn",
+      "device": "cpu"
+    }
+  }
+}
+```
+
+## Policies
+
+Policies are JSON so the project stays dependency-free. A policy can set default actions by category, override individual rules, and add private custom regex rules.
+
+```json
+{
+  "name": "public-content",
+  "defaults": {
+    "infrastructure": "block",
+    "secret": "block",
+    "pii": "warn"
+  },
+  "rules": {
+    "email": "warn"
+  },
+  "custom_rules": [
+    {
+      "id": "internal-hostname-example",
+      "category": "infrastructure",
+      "pattern": "\\\\binternal-host\\\\b",
+      "replacement": "[redacted-host]"
+    }
+  ]
+}
+```
+
+Actions:
+
+- `block`: fail the scan, usually for publish gates
+- `redact`: rewrite matching content
+- `warn`: report without failing
+- `allow`: ignore matching findings
+
+### Bundled Policies
+
+Two bundled policies share the `infrastructure` category but treat it differently on purpose:
+
+- `policies/public-repo.json`: for technical docs repos. It keeps `private-ipv4` (RFC 1918), secrets, PII, and `Co-authored-by` trailers as hard blocks, but downgrades `loopback-ipv4` (127.x), `localhost-port`, `localhost-bare`, and `port-reference` to warnings. README and CONTRIBUTING files often need to discuss `localhost`, named ports, and `127.0.0.1` for setup instructions. See [policies/public-repo.md](policies/public-repo.md) for the long-form rationale.
+- `policies/public-content.json`: for blog posts and social drafts. It keeps the full infrastructure category at block because marketing surfaces have a higher leak risk and should not expose internal addresses or named ports.
+
+## Allow Comments
+
+Use a local allow comment on the same line or directly above a line:
+
+```md
+<!-- content-guard: allow localhost-bare -->
+This tutorial uses localhost as an example.
+```
+
+Use `content-guard: allow all` sparingly for examples where every finding is intentional.
+
+## PR and Git Guards
+
+PR bodies and public repository content are publishing boundaries too. Use stricter policies before copying generated summaries, dogfood notes, local test output, fixtures, or docs into public GitHub surfaces:
+
+```bash
+content-guard scan examples/pr-body.md --policy policies/pr-draft.json
+content-guard diff examples/pr-body.md --policy policies/pr-draft.json
+content-guard-pr examples/pr-body.md
+content-guard-pr-prepare examples/pr-body.md --json
+content-guard-publish-check --pr-body examples/pr-body.md --json
+content-guard-n8n-advisory < payload.json
+content-guard-n8n-validate --json
+content-guard-git --policy policies/public-repo.json
+content-guard-git --all-tracked --policy policies/public-repo.json
+content-guard-commits --range origin/main..HEAD --policy policies/public-repo.json
+```
+
+See [docs/PR_DRAFTS.md](docs/PR_DRAFTS.md) and [docs/GIT_PUBLIC_REPO_GUARD.md](docs/GIT_PUBLIC_REPO_GUARD.md).
+
+Use `content-guard-publish-check` as the practical local pre-publish wrapper. It prepares a sanitized PR body when `--pr-body` is provided, scans staged files, scans commit messages, and can optionally scan all tracked files:
+
+```bash
+content-guard-publish-check --pr-body pr-body.md --json
+content-guard-publish-check --pr-body pr-body.md --all-tracked
+```
+
+PR body findings are advisory by default because the wrapper writes a sanitized body and prints `publish_body_file`. Staged file, commit message, and optional all-tracked blockers fail the command unless `--advisory-only` is set.
+
+Use `content-guard-pr-prepare` when a later PR publishing step needs a stable sanitized body path:
+
+```bash
+content-guard-pr-prepare pr-body.md
+gh pr create --body-file .content-guard/pr-drafts/pr-body.public.md
+```
+
+For local run-alongside testing against the legacy scrubber, see [docs/DOGFOOD_TEST_REPO.md](docs/DOGFOOD_TEST_REPO.md).
+
+For n8n publish workflows, start with an advisory step that reports findings without mutating live publishes. See [docs/N8N_ADVISORY.md](docs/N8N_ADVISORY.md) and [docs/N8N_WORKFLOW_RECIPE.md](docs/N8N_WORKFLOW_RECIPE.md). Validate cloned workflow wiring with [docs/N8N_VALIDATION_PACK.md](docs/N8N_VALIDATION_PACK.md).
+
+## OpenClaw Plugin
+
+Content Guard can also run as an OpenClaw outbound message plugin. The plugin lives in `openclaw-plugin/` and shells out to the same Python engine, so OpenClaw messages use the same policy model as publish gates.
+
+See [docs/OPENCLAW_PLUGIN.md](docs/OPENCLAW_PLUGIN.md).
+
+## Design Notes
+
+Privacy Filter influenced the optional model-backed PII layer, especially the idea that some personal data detection benefits from context. Content Guard does not copy Privacy Filter code. OPF integration is a subprocess adapter so the deterministic engine remains portable and maintainable.
+
+The deterministic rules are intentionally conservative. Public publishing should fail loudly on infrastructure and secret leakage, while model findings are better treated as review signals until a local policy proves they are reliable enough to block.

content_guard-0.1.1/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "content-guard"
+version = "0.1.1"
+description = "Policy-driven content scanning and redaction for public publishing and agent output."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Solomon Neas" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "License :: OSI Approved :: Apache Software License",
+]
+
+[project.scripts]
+content-guard = "content_guard.cli:main"
+content-guard-git = "content_guard.git_scan:main"
+content-guard-commits = "content_guard.git_commits:main"
+content-guard-publish-check = "content_guard.publish_check:main"
+content-guard-n8n-advisory = "content_guard.n8n_advisory:main"
+content-guard-n8n-validate = "content_guard.n8n_validate:main"
+content-guard-pr = "content_guard.pr_draft:main"
+content-guard-pr-prepare = "content_guard.pr_prepare:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+content_guard = ["policies/*.json"]

content_guard-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

content_guard-0.1.1/src/content_guard/__init__.py

@@ -0,0 +1,6 @@
+"""Policy-driven content scanning and redaction."""
+
+from .engine import GuardResult, scan_text, redact_text
+from .policy import Policy, load_policy
+
+__all__ = ["GuardResult", "Policy", "load_policy", "scan_text", "redact_text"]

content_guard-0.1.1/src/content_guard/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

content_guard-0.1.1/src/content_guard/cli.py

@@ -0,0 +1,176 @@
+from __future__ import annotations
+
+import argparse
+import difflib
+import json
+import sys
+from pathlib import Path
+
+from .engine import scan_text
+from .policy import load_policy
+from .report import to_json, to_payload, to_text
+from .types import ScanOptions
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "scan":
+        return _scan(args)
+    if args.command == "redact":
+        return _redact(args)
+    if args.command == "diff":
+        return _diff(args)
+
+    parser.error(f"unknown command: {args.command}")
+    return 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="content-guard",
+        description="Policy-driven content scanning and redaction.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    for name in ("scan", "redact", "diff"):
+        cmd = sub.add_parser(name)
+        cmd.add_argument("target", nargs="?", help="file to read, or stdin when omitted")
+        cmd.add_argument("--policy", help="JSON policy file")
+        cmd.add_argument("--opf", action="store_true", help="run optional OPF backend")
+        cmd.add_argument("--opf-bin", help="path to opf binary")
+        cmd.add_argument("--opf-device", help="OPF device, default comes from policy or cpu")
+        cmd.add_argument("--scan-frontmatter", action="store_true", help="scan YAML frontmatter")
+        cmd.add_argument("--skip-code-blocks", action="store_true", help="ignore fenced code blocks")
+        cmd.add_argument("--no-allow-comments", action="store_true", help="ignore content-guard allow comments")
+
+    sub.choices["scan"].add_argument("--json", action="store_true", help="emit JSON report")
+    sub.choices["redact"].add_argument("--in-place", action="store_true", help="rewrite the target file")
+    return parser
+
+
+def _options(args: argparse.Namespace) -> ScanOptions:
+    return ScanOptions(
+        scan_frontmatter=args.scan_frontmatter,
+        scan_code_blocks=not args.skip_code_blocks,
+        honor_allow_comments=not args.no_allow_comments,
+        include_opf=args.opf,
+        opf_device=args.opf_device,
+        opf_bin=args.opf_bin,
+    )
+
+
+def _read_target(target: str | None) -> tuple[str, str | None]:
+    if not target or target == "-":
+        return sys.stdin.read(), None
+    path = Path(target)
+    return path.read_text(), str(path)
+
+
+def _scan(args: argparse.Namespace) -> int:
+    policy = load_policy(args.policy)
+    options = _options(args)
+    target_path = Path(args.target) if args.target and args.target != "-" else None
+
+    if target_path and target_path.is_dir():
+        results = _scan_directory(target_path, policy, options)
+        blocked = any(result.blocked for _, result in results)
+        if args.json:
+            print(
+                json.dumps(
+                    {
+                        "ok": not blocked,
+                        "blocked": blocked,
+                        "files_scanned": len(results),
+                        "files": [
+                            {"path": str(path), **to_payload(result)}
+                            for path, result in results
+                            if result.findings
+                        ],
+                    },
+                    indent=2,
+                    sort_keys=True,
+                )
+            )
+        elif not any(result.findings for _, result in results):
+            print(f"Clean. {len(results)} file(s) checked.")
+        else:
+            for path, result in results:
+                if result.findings:
+                    print(to_text(result, path=str(path)))
+        return 1 if blocked else 0
+
+    text, path = _read_target(args.target)
+    result = scan_text(text, policy=policy, options=options)
+    if args.json:
+        print(to_json(result))
+    else:
+        print(to_text(result, path=path or "<stdin>"))
+    return 1 if result.blocked else 0
+
+
+def _redact(args: argparse.Namespace) -> int:
+    policy = load_policy(args.policy)
+    options = _options(args)
+    target_path = Path(args.target) if args.target and args.target != "-" else None
+
+    if target_path and target_path.is_dir():
+        if not args.in_place:
+            print("directory redact requires --in-place", file=sys.stderr)
+            return 2
+        results = _scan_directory(target_path, policy, options)
+        for path, result in results:
+            if result.changed:
+                path.write_text(result.redacted_text)
+        return 1 if any(result.blocked for _, result in results) else 0
+
+    text, path = _read_target(args.target)
+    result = scan_text(text, policy=policy, options=options)
+
+    if args.in_place:
+        if not path:
+            print("--in-place requires a file target", file=sys.stderr)
+            return 2
+        Path(path).write_text(result.redacted_text)
+    else:
+        sys.stdout.write(result.redacted_text)
+    return 1 if result.blocked else 0
+
+
+def _diff(args: argparse.Namespace) -> int:
+    policy = load_policy(args.policy)
+    options = _options(args)
+    target_path = Path(args.target) if args.target and args.target != "-" else None
+
+    if target_path and target_path.is_dir():
+        results = _scan_directory(target_path, policy, options)
+        for path, result in results:
+            if not result.changed:
+                continue
+            _write_diff(result.text, result.redacted_text, str(path))
+        return 1 if any(result.blocked for _, result in results) else 0
+
+    text, path = _read_target(args.target)
+    result = scan_text(text, policy=policy, options=options)
+    source_name = path or "<stdin>"
+    _write_diff(text, result.redacted_text, source_name)
+    return 1 if result.blocked else 0
+
+
+def _scan_directory(path: Path, policy, options: ScanOptions):
+    results = []
+    for file_path in sorted(path.rglob("*.md")):
+        text = file_path.read_text()
+        results.append((file_path, scan_text(text, policy=policy, options=options)))
+    return results
+
+
+def _write_diff(text: str, redacted_text: str, source_name: str) -> None:
+    diff = difflib.unified_diff(
+        text.splitlines(keepends=True),
+        redacted_text.splitlines(keepends=True),
+        fromfile=source_name,
+        tofile=f"{source_name} (redacted)",
+    )
+    sys.stdout.writelines(diff)

content_guard-0.1.1/src/content_guard/detectors/__init__.py

@@ -0,0 +1 @@
+"""Detector backends."""

content_guard-0.1.1/src/content_guard/detectors/opf.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class OpfResult:
+    available: bool
+    changed: bool
+    redacted_text: str
+    error: str = ""
+
+
+def default_opf_bin() -> str:
+    return os.environ.get("CONTENT_GUARD_OPF_BIN") or str(Path.home() / ".opf-venv" / "bin" / "opf")
+
+
+def run_opf(text: str, *, opf_bin: str | None = None, device: str = "cpu", timeout: int = 120) -> OpfResult:
+    opf = opf_bin or default_opf_bin()
+    if not os.path.exists(opf) or not os.access(opf, os.X_OK):
+        return OpfResult(False, False, text, f"opf binary not found: {opf}")
+
+    with tempfile.NamedTemporaryFile("w", suffix=".txt", delete=False) as handle:
+        handle.write(text)
+        path = handle.name
+
+    try:
+        proc = subprocess.run(
+            [opf, "--device", device, "-f", path],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        return OpfResult(True, False, text, str(exc))
+    finally:
+        try:
+            os.unlink(path)
+        except OSError:
+            pass
+
+    if proc.returncode != 0:
+        error = (proc.stderr or proc.stdout or "opf failed").strip()
+        return OpfResult(True, False, text, error)
+
+    redacted = proc.stdout
+    return OpfResult(True, redacted != text, redacted, "")