llm-redact-proxy 1.0.0__py3-none-any.whl

llm_redact/__init__.py

@@ -0,0 +1,3 @@
+"""llm-redact: transparent redaction/rehydration proxy for LLM API traffic."""
+
+__version__ = "1.0.0"

llm_redact/__main__.py

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

llm_redact/audit.py

@@ -0,0 +1,135 @@
+"""Audit-log contract (the Free side of the open-core split).
+
+The audit log records metadata only — detector types and counts, paths,
+timestamps, durations. Never values, never placeholder ids, never headers or
+bodies. The concrete SQLite log, its tamper-evident hash chain, and the
+off-machine sinks are a paid subsystem (``llm_redact_pro.audit`` /
+``llm_redact_pro.audit_s3``). This module holds only what the Free core needs
+at the seam:
+
+- ``AuditRecord`` — the metadata row ``record_request`` builds and hands to the
+  log (kept here so ``proxy.py`` is unchanged),
+- the ``AuditLog`` **Protocol** the proxy calls,
+- the env-var name + key-resolution helper ``doctor`` uses for its posture
+  checks (generic env-reading glue, no paid secrecy value), and
+- the fail-closed ``build_audit`` default.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from .config import ConfigError
+
+if TYPE_CHECKING:
+    from .config import AuditConfig
+
+AUDIT_HMAC_ENV = "LLM_REDACT_AUDIT_HMAC_KEY"
+
+_PRO_HINT = "install the llm-redact-pro package to enable it"
+
+
+@dataclass
+class AuditRecord:
+    ts: str
+    session: str
+    provider: str | None
+    method: str
+    path: str
+    status: int | None
+    duration_ms: float
+    streamed: bool
+    detections: dict[str, int] = field(default_factory=dict)
+    rehydrations: dict[str, int] = field(default_factory=dict)
+    # Named-user attribution (2.0): the user NAME only, never keys. None on
+    # single-user deployments and rows recorded before 2.0.
+    user: str | None = None
+    # Warn-mode hits attributed to this request (3.3): types+counts of values
+    # FORWARDED upstream unredacted. None when nothing warned and on rows
+    # recorded before the column existed.
+    warned: dict[str, int] | None = None
+
+
+class AuditWriteError(RuntimeError):
+    """A required-mode audit row could not be durably committed.
+
+    Raised by write-ahead audit implementations (``[audit] required = true``,
+    llm-redact-pro) from ``begin``/``finalize``/``record`` when the row cannot
+    be committed. On the ``begin`` path the proxy answers a provider-shaped
+    503 WITHOUT contacting the upstream — no durably committed audit row, no
+    upstream contact; after a response has been committed the proxy can only
+    log the failure loudly. Never raised in the default fail-open mode, where
+    the concrete log swallows write faults by design.
+    """
+
+
+class AuditLog(Protocol):
+    """The audit-log surface the proxy depends on.
+
+    The concrete SQLite implementation (with the tamper-evident chain) is
+    ``llm_redact_pro.audit.AuditLog``; the Free core holds only this structural
+    contract. ``verify()`` — used by the offline ``audit verify`` CLI, not the
+    request path — lives on the concrete class only. The write-ahead pair for
+    ``[audit] required`` mode is the :class:`WriteAheadAudit` sub-Protocol —
+    kept out of this base so a pro package predating it still satisfies every
+    fail-open configuration, type contract included.
+    """
+
+    def record(self, entry: AuditRecord) -> None: ...
+
+    def recent(self, limit: int) -> list[dict[str, object]]: ...
+
+    def count(self) -> int: ...
+
+    def close(self) -> None: ...
+
+
+@runtime_checkable
+class WriteAheadAudit(AuditLog, Protocol):
+    """An audit log with the ``[audit] required`` write-ahead pair.
+
+    ``begin`` durably commits a START row BEFORE any upstream contact
+    (raising :class:`AuditWriteError` on failure) and returns an opaque
+    non-None token; ``finalize`` commits the matching END row at completion.
+    ``ProxyState`` resolves the capability once at startup (``isinstance``
+    checks method presence, the runtime-checkable contract) and refuses
+    required mode when the built log lacks the pair.
+    """
+
+    def begin(self, entry: AuditRecord) -> object: ...
+
+    def finalize(self, token: object, entry: AuditRecord) -> None: ...
+
+
+def default_audit_path() -> Path:
+    xdg = os.environ.get("XDG_DATA_HOME", str(Path.home() / ".local" / "share"))
+    return Path(xdg) / "llm-redact" / "audit.db"
+
+
+def audit_hmac_key_from_env() -> bytes | None:
+    """The tamper-evidence HMAC key, derived from LLM_REDACT_AUDIT_HMAC_KEY.
+
+    Env-only (never the config file, matching the vault key and S3
+    credentials). Any-length passphrase is hashed to 32 bytes. Returns None
+    when unset so the caller can fail closed with a clear message.
+    """
+    raw = os.environ.get(AUDIT_HMAC_ENV, "")
+    if not raw:
+        return None
+    return hashlib.sha256(raw.encode("utf-8")).digest()
+
+
+def build_audit(config: AuditConfig) -> AuditLog | None:
+    """Fail-closed Free default for the audit log.
+
+    The audit log — and its tamper-evident chain — is a paid subsystem whose
+    implementation lives in llm-redact-pro. Disabled is None; enabled without
+    the pro package fails closed rather than silently dropping the audit trail.
+    """
+    if not config.enabled:
+        return None
+    raise ConfigError(f"[audit] enabled = true requires an audit log; {_PRO_HINT}")

llm_redact/audit_s3.py

@@ -0,0 +1,97 @@
+"""Off-machine audit-sink contract (the Free side of the open-core split).
+
+The concrete S3/GCS and Azure Blob sinks — the hand-rolled SigV4 and Azure
+SharedKey signers, batch buffering, and client-side Fernet encryption — are a
+paid (Pro-tier) subsystem in ``llm_redact_pro.audit_s3``. This module holds
+only the seam:
+
+- the ``S3AuditSink`` / ``AzureAuditSink`` Protocols the proxy runs and reads
+  counters from,
+- the env-var names + key/credential helpers ``doctor`` uses for its posture
+  checks (generic env-reading glue, no paid secrecy value; credentials NEVER
+  come from the config file), and
+- the fail-closed ``build_audit_sinks`` default.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+from typing import TYPE_CHECKING, Any, Protocol
+
+from .config import ConfigError
+
+if TYPE_CHECKING:
+    from .config import AuditConfig
+
+_PRO_HINT = "install the llm-redact-pro package to enable it"
+
+# Client-side batch encryption ([audit.s3]/[audit.azure] encryption = "fernet").
+AUDIT_ENC_KEY_ENV = "LLM_REDACT_AUDIT_ENC_KEY"
+AZURE_STORAGE_KEY_ENV = "AZURE_STORAGE_KEY"
+
+
+def audit_enc_key_from_env() -> bytes | None:
+    """SHA-256 of the env passphrase, urlsafe-base64 — a valid Fernet key
+    (the audit_hmac_key_from_env recipe, shaped for Fernet)."""
+    raw = os.environ.get(AUDIT_ENC_KEY_ENV, "")
+    if not raw:
+        return None
+    return base64.urlsafe_b64encode(hashlib.sha256(raw.encode("utf-8")).digest())
+
+
+# Per-provider credential environment variables. GCS is reached through its
+# S3-compatible XML API (interoperability) with HMAC interoperability keys read
+# from GCS-specific vars. Credentials NEVER come from the config file.
+_CREDENTIAL_ENV: dict[str, tuple[str, str, str | None]] = {
+    "aws": ("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"),
+    "minio": ("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"),
+    "ceph": ("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_SESSION_TOKEN"),
+    "gcs": ("GCS_HMAC_ACCESS_ID", "GCS_HMAC_SECRET", None),
+}
+
+
+def credential_env_names(provider: str) -> tuple[str, str, str | None]:
+    """The (access, secret, session-token) env var names for a provider."""
+    return _CREDENTIAL_ENV.get(provider, _CREDENTIAL_ENV["aws"])
+
+
+class S3AuditSink(Protocol):
+    """The S3/GCS audit-sink surface the proxy runs (concrete impl in pro)."""
+
+    batches_uploaded: int
+    rows_dropped: int
+
+    def add(self, row: dict[str, Any]) -> None: ...
+
+    async def run(self) -> None: ...
+
+    async def aclose(self) -> None: ...
+
+
+class AzureAuditSink(Protocol):
+    """The Azure Blob audit-sink surface the proxy runs (concrete impl in pro)."""
+
+    batches_uploaded: int
+    rows_dropped: int
+
+    def add(self, row: dict[str, Any]) -> None: ...
+
+    async def run(self) -> None: ...
+
+    async def aclose(self) -> None: ...
+
+
+def build_audit_sinks(
+    config: AuditConfig,
+) -> tuple[S3AuditSink | None, AzureAuditSink | None]:
+    """Fail-closed Free default for the off-machine audit sinks.
+
+    Both sinks disabled is ``(None, None)``. Enabling either without the pro
+    package fails closed rather than silently dropping every batch — the sinks,
+    signers, and batch encryption are a paid subsystem.
+    """
+    if not config.s3.enabled and not config.azure.enabled:
+        return None, None
+    raise ConfigError(f"audit backup sinks require an off-machine sink; {_PRO_HINT}")

llm_redact/bench/__init__.py

@@ -0,0 +1,6 @@
+"""Detection quality benchmark: deterministic synthetic corpus + metrics.
+
+Run with ``python -m llm_redact.bench``. The corpus is generated at runtime
+(never committed — no realistic-looking secrets in the repository) from a
+fixed seed, so results are reproducible and rule regressions are diffable.
+"""

llm_redact/bench/__main__.py

@@ -0,0 +1,110 @@
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from llm_redact.bench.corpus import generate
+from llm_redact.bench.fp_scan import fp_failures, scan_fp_corpus, to_markdown_table
+from llm_redact.bench.latency import (
+    ceiling_failures,
+    run_latency,
+    to_json_list,
+)
+from llm_redact.bench.latency import (
+    to_markdown as latency_to_markdown,
+)
+from llm_redact.bench.metrics import evaluate, to_json_dict, to_markdown
+
+DEFAULT_FP_CORPUS = Path("bench/fp_corpus")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m llm_redact.bench")
+    parser.add_argument("--seed", type=int, default=42)
+    parser.add_argument("--samples", type=int, default=25, help="positives per rule")
+    parser.add_argument("--out", type=Path, default=None, help="write report files here")
+    parser.add_argument(
+        "--fp-corpus",
+        type=Path,
+        default=None,
+        help=f"false-positive corpus root (default: {DEFAULT_FP_CORPUS} when present)",
+    )
+    parser.add_argument(
+        "--latency",
+        action="store_true",
+        help="also run the in-process latency benchmark (adds ~1 minute)",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="exit 1 if any rule misses its own generated positives (recall < 1.0),"
+        " the fp corpus deviates from its manifest, or (with --latency) a p50"
+        " smoke ceiling is crossed",
+    )
+    args = parser.parse_args(argv)
+
+    corpus = generate(seed=args.seed, samples_per_rule=args.samples)
+    result = evaluate(corpus)
+    markdown = to_markdown(result, seed=args.seed)
+
+    fp_root = args.fp_corpus
+    if fp_root is None and DEFAULT_FP_CORPUS.is_dir():
+        fp_root = DEFAULT_FP_CORPUS
+    fp_results = None
+    if fp_root is not None:
+        fp_results = scan_fp_corpus(fp_root)
+        markdown += (
+            "\n## False-positive corpus\n\n"
+            f"Vendored negatives at `{fp_root}`, gated on exact per-file counts.\n\n"
+            + to_markdown_table(fp_results)
+            + "\n"
+        )
+
+    latency_stats = None
+    if args.latency:
+        latency_stats = run_latency(seed=args.seed)
+        markdown += "\n" + latency_to_markdown(latency_stats)
+
+    if args.out is not None:
+        args.out.mkdir(parents=True, exist_ok=True)
+        (args.out / "report.md").write_text(markdown)
+        report = to_json_dict(result, seed=args.seed)
+        if latency_stats is not None:
+            report["latency"] = to_json_list(latency_stats)
+        (args.out / "report.json").write_text(json.dumps(report, indent=2))
+        print(f"report written to {args.out}/report.md and report.json")
+    else:
+        print(markdown)
+
+    if args.check:
+        failed = False
+        # Functional regression gate: the corpus is generated to match each
+        # rule, so a missed positive is a code regression, not corpus noise.
+        misses = {name: s for name, s in result.per_type.items() if s.recall < 1.0}
+        for name, score in misses.items():
+            print(f"CHECK FAILED: {name} recall {score.recall:.3f} ({score.fn} missed)")
+            failed = True
+        # Precision gate: the vendored negatives must match their manifest
+        # exactly, in both directions.
+        if fp_results is not None:
+            for line in fp_failures(fp_results):
+                print(f"CHECK FAILED (fp corpus): {line}")
+                failed = True
+        # Latency smoke ceilings: generous p50-only bounds against
+        # accidental quadratic behavior, not perf tuning.
+        if latency_stats is not None:
+            for line in ceiling_failures(latency_stats):
+                print(f"CHECK FAILED (latency): {line}")
+                failed = True
+        if failed:
+            return 1
+        fp_note = f", fp corpus clean ({len(fp_results)} files)" if fp_results is not None else ""
+        latency_note = ", latency ceilings ok" if latency_stats is not None else ""
+        print(
+            f"check passed: recall 1.0 on all {len(result.per_type)} types{fp_note}{latency_note}"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())