spanguard 0.1.0__tar.gz

spanguard-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,87 @@
+name: Bug report
+description: Report a problem with spanguard (detector miss, incorrect redaction, streaming/CLI bug, etc.)
+title: "bug: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug.
+
+        **IMPORTANT — do not paste real PII/PHI or other sensitive data into this
+        issue.** GitHub issues are public. Please reproduce the problem using
+        synthetic/fake data only, e.g. `jane@example.com`, `555-123-4567`,
+        `123-45-6789`. If the bug is a security-sensitive redaction bypass or a
+        way sensitive data can leak (rather than a general correctness bug),
+        please use [private vulnerability reporting](https://github.com/Clufy/spanguard/security/advisories/new)
+        instead of a public issue — see [SECURITY.md](https://github.com/Clufy/spanguard/blob/master/SECURITY.md).
+
+  - type: checkboxes
+    id: no-real-pii
+    attributes:
+      label: Confirmation
+      options:
+        - label: I have NOT included any real PII/PHI or other sensitive data in this report — all examples below use synthetic/fake data.
+          required: true
+        - label: This is a general bug, not a security-sensitive leak or detector bypass (if it is, I will use private vulnerability reporting instead).
+          required: true
+
+  - type: input
+    id: spanguard-version
+    attributes:
+      label: spanguard version
+      description: Output of `pip show spanguard` (or `uv pip show spanguard`), or the git commit if installed from source.
+      placeholder: "0.1.0"
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`.
+      placeholder: "3.12.4"
+    validations:
+      required: true
+
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: >
+        A minimal, self-contained code snippet that reproduces the issue, using
+        synthetic data only. Include the `Policy`/`Redactor` configuration you
+        used.
+      render: python
+      placeholder: |
+        from spanguard import Redactor, Policy
+
+        policy = Policy(mode="placeholder", entities=("EMAIL",))
+        result = Redactor(policy).redact("Contact: jane@example.com")
+        print(result.text)
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: What actually happened? Include the full output/traceback if relevant (with any sensitive data replaced by synthetic placeholders).
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Anything else relevant — e.g. whether the `[ner]` extra is installed, whether this happens in streaming mode, OS, etc.
+    validations:
+      required: false

spanguard-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Documentation
+    url: https://clufy.github.io/spanguard
+    about: Check the docs (quickstart, recognizers, streaming, CLI, known limitations) before filing an issue — your question may already be answered there.
+  - name: Report a security vulnerability
+    url: https://github.com/Clufy/spanguard/security/advisories/new
+    about: For redaction bypasses, audit-record leaks, or other security-sensitive issues, please use private vulnerability reporting instead of a public issue.

spanguard-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,59 @@
+name: Feature request
+description: Suggest a new detector, redaction mode, or other enhancement for spanguard
+title: "feat: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement to spanguard.
+
+        As with bug reports: please describe your use case using synthetic
+        examples only — do not paste real PII/PHI into this issue.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / use case
+      description: >
+        What problem are you trying to solve? What's missing today? If this is
+        about a new entity type or detector, describe the format(s) you need
+        to detect (with synthetic examples).
+      placeholder: |
+        I need to detect [entity type] in my data, e.g. text like
+        "example-synthetic-value-123" — spanguard currently has no recognizer
+        for this format.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed solution
+      description: >
+        How would you like this to work? If you're proposing a new detector,
+        note whether it could be a regex `Recognizer`, whether it needs
+        context-anchoring (like `MRN`), or whether it needs NER/model-based
+        detection.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: >
+        Have you considered writing a custom `Recognizer` for this yourself
+        (see the docs on Recognizers)? If so, why doesn't that work for your
+        case — e.g. does it need to be a built-in default, or shared across
+        projects?
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Anything else — links, related issues, references to similar detectors in other tools, etc.
+    validations:
+      required: false

spanguard-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+## Summary
+
+<!-- What does this change do, and why? Link any related issue. -->
+
+## Checklist
+
+- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) (`feat: ...`, `fix: ...`, `docs: ...`, `refactor: ...`, `chore: ...`, `ci: ...`, `test: ...`).
+- [ ] Tests added/updated for the change, including **both positive and negative cases** if this touches a `Recognizer` (see `CONTRIBUTING.md`).
+- [ ] `uv run ruff check .` passes clean.
+- [ ] `uv run mypy` passes clean (`strict = true` — no new untyped defs or `Any` leaks).
+- [ ] `uv run pytest --cov=spanguard --cov-report=term-missing --cov-fail-under=90` passes and coverage is maintained (currently 96.92%; gate is 90%).
+- [ ] Docs updated under `docs/` if this changes or adds user-facing behavior (new detector, new CLI flag, new redaction mode, etc.), including `docs/known-limitations.md` if this introduces a deliberate precision/recall trade-off.
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` if this is a user-visible change.
+- [ ] **No real PII/PHI in tests, examples, fixtures, or this PR description** — synthetic data only (e.g. `jane@example.com`, `555-123-4567`, `123-45-6789`).
+- [ ] If this touches redaction, audit records, or streaming: confirmed no raw matched value can reach `RedactionResult.audit`, redacted output (when it shouldn't), or CLI `scan` output.
+
+## Additional context
+
+<!-- Anything a reviewer needs to know: design trade-offs, alternatives considered, follow-up work, etc. -->

spanguard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+on:
+  push: { branches: [master, main] }
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv venv --python 3.12
+      - run: uv pip install -e ".[ner]" pytest pytest-cov ruff mypy
+      - run: uv run ruff check .
+      - run: uv run mypy
+      - run: uv run pytest --cov=spanguard --cov-report=term-missing --cov-fail-under=90
+
+  secrets:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }   # full history so gitleaks scans every commit
+      - uses: gitleaks/gitleaks-action@v2

spanguard-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,32 @@
+name: Docs
+on:
+  push: { branches: [master, main] }
+  workflow_dispatch:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+concurrency:
+  group: pages
+  cancel-in-progress: true   # newer docs push supersedes an in-flight deploy; avoids Pages collisions
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv venv --python 3.12
+      - run: uv pip install -e ".[docs]"
+      - run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

spanguard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,16 @@
+name: Publish
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  id-token: write        # OIDC; NO PyPI token stored
+  contents: read
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

spanguard-0.1.0/.gitignore

@@ -0,0 +1,52 @@
+# Python bytecode / caches
+__pycache__/
+*.py[cod]
+*$py.class
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Packaging / build artifacts
+*.egg-info/
+*.egg
+dist/
+build/
+wheels/
+pip-wheel-metadata/
+
+# Test / coverage output
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+
+# Docs build output
+site/
+
+# Secrets / environment
+.env
+.env.*
+!.env.example
+
+# Superpowers workflow scratch (task briefs, reports, review diffs, ledger)
+.superpowers/
+
+# OS / editor cruft
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*~
+
+# Internal design/plan/spec docs (not part of the public site or repo)
+docs/superpowers/

spanguard-0.1.0/.gitleaks.toml

@@ -0,0 +1,13 @@
+# Extend gitleaks' default rules; only add an allowlist for known-safe fixtures.
+[extend]
+useDefault = true
+
+# ponytail: allowlist the synthetic secrets in the recognizer test suite.
+# These are non-credentials — AWS's own docs placeholder and a fabricated sk- string —
+# used to verify detection. Add real exceptions here (by regex) only when equally certain.
+[allowlist]
+description = "Synthetic test fixtures, not real credentials"
+regexes = [
+  '''AKIAIOSFODNN7EXAMPLE''',
+  '''sk-abcDEF0123456789abcDEF0123''',
+]

spanguard-0.1.0/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to spanguard will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-12
+
+Initial release.
+
+### Added
+
+- **Entity detection** for `EMAIL` (Unicode-aware local part and domain),
+  `PHONE` (NANP-style, multiple separator conventions), `SSN`, `MRN`
+  (context-anchored on an `MRN` prefix), `DOB` (`mm/dd/yyyy` and ISO
+  `yyyy-mm-dd`), `CREDIT_CARD` (regex plus Luhn checksum validation across
+  standard printed groupings), and `API_KEY` (known-prefix formats such as
+  `sk-`, `AKIA`, `ghp_`, plus a high-entropy generic fallback).
+- **Four redaction modes** on every `Policy`: `mask` (fixed-character
+  replacement, length-preserving), `placeholder` (`[TYPE]` tags), `hash`
+  (deterministic HMAC digest, reproducible with a shared key), and
+  `tokenize` (reversible placeholder tokens).
+- **Reversible tokenization and reveal** — `Redactor.reveal()` restores the
+  original text from `tokenize`-mode output via an in-memory `Keyring`,
+  scoped to a single process/key.
+- **`StreamRedactor`** for chunked/streaming input (e.g. live call
+  transcripts or log tails), with a documented split-equals-one-shot
+  guarantee: concatenating every `feed()` call's output plus a final
+  `flush()` equals exactly what a one-shot `redact()` on the full text would
+  produce, even when an entity straddles a chunk boundary. Enforces a
+  minimum `tail` buffer of 64 characters to prevent sub-threshold entity
+  leakage.
+- **Optional NER extra** (`pip install spanguard[ner]`) adding a
+  spaCy-backed `SpacyRecognizer` for `PERSON` and `LOCATION` detection,
+  imported lazily so the core install stays dependency-light and fast to
+  import.
+- **`spanguard` CLI** with `scan` (report entity-type counts only, never raw
+  values) and `redact` (write redacted text to stdout or a file, with an
+  optional `--audit-json` audit record on stderr) subcommands.
+  `-` reads stdin as UTF-8. An unknown `--entities` name, an unreadable,
+  undecodable or missing input (including closed stdin), or an unwritable
+  `--out` path exits with code 2 and a one-line `error:` message that names
+  only the path or label, never input content.
+- **Unknown-entity warning**: `Redactor` warns (`UserWarning`, entity labels
+  only) when `Policy.entities` names a type with no recognizer, such as
+  `PERSON` without `SpacyRecognizer` or a typo like `EMIAL`, instead of
+  silently detecting nothing for it.
+- **`StreamRedactor(max_buffer=N)`** and `StreamBufferFullError`: an opt-in
+  cap on held-back text for streams that never offer a safe split point.
+  Uncapped by default.
+- **Leak-free audit records** — every `RedactionResult.audit` contains only
+  entity-type counts, a policy hash, and a timestamp, never a raw matched
+  value or span text; this guarantee is enforced directly by the test suite
+  (`tests/test_audit_safety.py`), not just documented.
+- **Pluggable `Recognizer` protocol** for adding custom, domain-specific
+  detectors without forking the library.
+- Full documentation site (mkdocs-material) covering quickstart, streaming,
+  the CLI, recognizers, and an honest known-limitations page, published to
+  [clufy.github.io/spanguard](https://clufy.github.io/spanguard).
+- CI pipeline (ruff, mypy `--strict`, pytest with a 90% coverage gate) on
+  every push and pull request; 128 tests at 97.92% coverage as of this
+  release. Published to PyPI from GitHub Actions via OIDC Trusted
+  Publishing on `v*` tags; no PyPI token is stored anywhere.
+
+### Performance
+
+Measured against the July 2026 pre-release build. Redaction output is
+byte-identical; each change is pinned by a differential test against the
+earlier algorithm.
+
+| Path | Pre-release | 0.1.0 |
+|---|---|---|
+| `Redactor.redact`, 40k spans | 84.6 s | 0.84 s |
+| `EmailRecognizer`, 8k-char token with no spaces | 844 ms (quadratic) | 0.6 ms (linear) |
+| `Keyring.reveal`, 30k issued tokens | 11.2 s | 44 ms |
+| `StreamRedactor`, 200 KB in 4 KB chunks | 304 ms | 194 ms |
+| `StreamRedactor`, 1 MB with no whitespace | quadratic | linear |
+| `StreamRedactor`, 200 KB whose only whitespace is inside a phone number | 8.49 s | 0.08 s |
+| `benchmarks/throughput.py` (1 MB corpus) | 1.54 MB/s | 2.15 MB/s |
+
+Overlap resolution is O(n log n), email detection cannot backtrack
+quadratically on long whitespace-free runs (a denial-of-service vector),
+`Keyring.reveal` is linear in the text, and `StreamRedactor` never re-detects
+text it has already verified or split points it has already tried.
+
+[unreleased]: https://github.com/Clufy/spanguard/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Clufy/spanguard/releases/tag/v0.1.0

spanguard-0.1.0/CITATION.cff

@@ -0,0 +1,22 @@
+cff-version: 1.2.0
+message: "If you use spanguard in your work, please cite it using the metadata below."
+type: software
+title: spanguard
+abstract: >-
+  Detect and redact PII/PHI in text and streaming transcripts, with leak-free
+  audit records, reversible tokenization, an optional NER extra, and a CLI.
+authors:
+  - name: "spanguard authors"
+    alias: "Clufy"
+repository-code: "https://github.com/Clufy/spanguard"
+url: "https://clufy.github.io/spanguard"
+license: MIT
+version: 0.1.0
+date-released: "2026-07-06"
+keywords:
+  - pii
+  - phi
+  - redaction
+  - privacy
+  - compliance
+  - nlp

spanguard-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,142 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic
+status, nationality, personal appearance, race, caste, color, religion, or
+sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+  of any kind
+* Trolling, insulting or derogatory comments, and personal or political
+  attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards
+of acceptable behavior and will take appropriate and fair corrective action
+in response to any behavior that they deem inappropriate, threatening,
+offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, and will communicate reasons
+for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies
+when an individual is officially representing the community in public
+spaces. Examples of representing our community include using an official
+e-mail address, posting via an official social media account, or acting as
+an appointed representative at an online or offline event.
+
+## Enforcement
+
+spanguard does not currently publish a dedicated enforcement email address.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by:
+
+* Opening a private [Security Advisory](https://github.com/Clufy/spanguard/security/advisories/new)
+  on the repository (via the **Security** tab → **Report a vulnerability**),
+  which is visible only to the maintainer and is not public — this mechanism
+  works for conduct reports as well as security reports; or
+* Contacting the maintainer directly via their GitHub account,
+  [@Clufy](https://github.com/Clufy).
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of
+the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in
+determining the consequences for any action they deem in violation of this
+Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders,
+providing clarity around the nature of the violation and an explanation of
+why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external
+channels like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public
+or private interaction with the people involved, including unsolicited
+interaction with those enforcing the Code of Conduct, is allowed during this
+period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
+at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations