bivelio-privacy-gateway 0.2.0

BV-PRGA — fail-closed DLP frontier between BiVelio services and LLM providers

bivelio-privacy-gateway (BV-PRGA)

Commercial license — © 2026 BiVelio Inc. All Rights Reserved. Distributed under the BiVelio Shield — Gateway Commercial License. You may download, install, and run it; Evaluation Use is free, and Production Use requires a valid BV-LIC Seat License (USD 4.00 / Seat / month). Modifying, redistributing, reverse-engineering, or circumventing the BV-LIC licensing is not permitted; BiVelio reserves all copyright and patent rights. See LICENSE.

Part of BiVelio Shield. BiVelio Shield is the product brand for BiVelio's local-first privacy layer for AI. It ships in two form factors that share the same deterministic engine (@bivelio/redact-core / BV-PRGA): the browser extension (consumer, redacts your prompts to ChatGPT & Claude on your own machine) and this gateway / SDK (developer & enterprise, the server-side egress frontier). This package is BiVelio Shield — Gateway.

BV-PRGA (BiVelio Privacy Redaction & Gating Algorithm) is the fail-closed data-loss-prevention (DLP) frontier at the core of BiVelio Shield. It sits between BiVelio's internal services (Brain, document ingestion, RAG, agents, automations) and any external LLM provider (OpenAI, Anthropic, …). No prompt, tool call, document chunk or embedding reaches a third-party model without passing through it.

What it catches — and its documented limits

Honest scope (a DLP tool that overclaims is a liability):

• Strong, deterministic layer (always on): checksum-gated structured identifiers (credit cards via Luhn, IBAN mod-97, Spanish DNI/NIE/CIF, US SSN and more national IDs), emails, phones, and API keys / secrets (OpenAI, AWS, GitHub, Stripe, Slack, …). This layer benchmarks at high precision with zero residual leak on structured data.
• Names & free-form PII: covered only by the optional NLP layer (Presidio / GLiNER), not the deterministic core.
• Documented residuals (surfaced by adversarial review, tracked for a dedicated detector follow-up, NOT hidden): a credit card written with digits glued contiguously with no separator may be missed; a small number of streaming egress frame shapes were closed iteratively. See CHANGELOG / the hardening history. Treat the deterministic core as strong on structured data with known edges, not as total coverage of every possible input.

It is built to the principle that privacy cannot depend on every developer remembering to call a library: the gateway is the only egress path, it inspects every text-bearing field of the request (including data buried inside tool-call arguments), and anything it cannot inspect is denied — never forwarded.

---

Why this exists

Off-the-shelf proxies inspect messages[].content and little else. Sensitive data slips through the gaps: a DNI inside a tool call's JSON arguments, an API key in tool_use.input, an IBAN in an embeddings request, a secret split across streaming chunks, an image nobody redacted. BV-PRGA is designed to close those gaps explicitly and to fail closed when it can't.

Design rule	How BV-PRGA enforces it
No silent passthrough	Unknown endpoint → deny (no catch-all). New endpoint = new adapter + tests.
Cover every field	Recursive walk of content, tool-call arguments (parsed as JSON), tool_use.input, embeddings input, metadata, message names.
Low false positives	Every structured ID is checksum-gated (DNI mod-23, IBAN mod-97, Luhn, JWT header decode).
Secrets ≠ PII	Credentials are blocked and treated as compromised, never pseudonymised.
Fail closed	Detector error/timeout → block or route-local, never forward the original.
Reversible only inside the perimeter	Pseudonym tokens are per-tenant + per-session, TTL-bounded, restored only on the way back.
Auditable, not leaky	Audit events carry entity counts and decisions — never values, tokens or prompts.

---

Benchmarks (reproduced from code)

Measured on the deterministic layer (structured identifiers + secrets) over a seeded, labelled, multilingual corpus with hard negatives. Full methodology and the honesty caveats (what is not measured) are in docs/BENCHMARKS.md.

Metric	Value
Micro precision / recall / F1	1.000 / 1.000 / 1.000 (4522 entities, 1000 docs)
Residual leak rate (values still present after sanitisation)	0.0000 %
Pseudonymisation round-trip fidelity	100 % (1163/1163)
Irreversible-redaction leaks	0
Throughput (single-thread, pure-Python core)	~3.0 M chars/s (~6.9 k docs/s)

Reproduce: make benchmark (JSON) or make benchmark-doc (regenerates the doc).

These are deterministic-layer numbers by design — checksum gating makes near perfect precision/recall achievable for IDs and secrets. Free-text PII (names/addresses) is delegated to the optional NLP layer and is not claimed at 100 %. We do not overclaim.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     BiVelio services                        │
│  Brain · document ingestion · RAG · agents · automations    │
└──────────────────────────────┬──────────────────────────────┘
                               │  normalised internal contract
┌──────────────────────────────▼──────────────────────────────┐
│              BIVELIO PRIVACY GATEWAY  (BV-PRGA)              │
│  1. endpoint + schema validator   (unknown → deny)          │
│  2. protocol adapter (OpenAI Chat / Responses / Anthropic)  │
│  3. recursive field walk (tool args, tool_use.input, ...)   │
│  4. deterministic detectors  (regex + checksum)             │
│  5. optional NLP/NER layer   (Presidio, local models)       │
│  6. secret / credential detector                            │
│  7. per-tenant confidential dictionaries                    │
│  8. policy engine   (block / redact / pseudonymize / local) │
│  9. token vault     (per tenant+session, TTL, encrypted)    │
│ 10. value-free audit + synthetic canaries                   │
└──────────────┬────────────────┬────────────────┬────────────┘
        FORWARD│         ROUTE_LOCAL│           DENY│
        ┌──────▼──────┐   ┌────────▼─────┐   ┌─────▼──────┐
        │   LiteLLM   │   │ local model  │   │ 403 + audit│
        │  (router)   │   └──────────────┘   │  security  │
        └──────┬──────┘                       │   event    │
   OpenAI / Anthropic / …                     └────────────┘

LiteLLM is used after BV-PRGA, purely as a provider router — never as the privacy boundary. See docs/ARCHITECTURE.md.

The four detection layers

1. Structured identifiers — regex gated on checksums: Spanish DNI/NIE/NIF/CIF, IBAN (ES/AD/FR…, ISO 7064 mod-97), credit cards (Luhn), phones (ES/AD), email, IPv4.
2. Contextual PII (optional [nlp]) — Presidio + local spaCy/GLiNER for names, addresses, locations in es/ca/fr/en.
3. Secrets & credentials — provider keys (OpenAI/Anthropic), AWS, GCP, GitHub, Slack, Stripe, JWT (header-validated), PEM private keys, bearer tokens, connection strings, basic-auth URLs.
4. Tenant confidential — per-tenant dictionaries for codenames, unannounced clients, internal labels — the sensitive data no generic model knows about.

---

Field coverage matrix

Endpoint	Inspected surfaces
POST /v1/chat/completions	messages[].content (string + vision blocks), messages[].name, tool_calls[].function.arguments (JSON, recursive), function_call.arguments, tools[] descriptions, user, metadata
POST /v1/responses	instructions, input[] (recursive: content blocks, function args, tool outputs), user, metadata, tools[]
POST /v1/messages (Anthropic)	system (string + blocks), text, thinking/redacted_thinking, tool_use.input (recursive), tool_result.content, tools[], metadata
POST /v1/embeddings	input (string or list), user
any other path	denied — add an adapter + tests to support it

Image / audio / file blocks are reported as unsupported and denied under the fail-closed policy (they must be processed locally first).

---

Quickstart

The core has zero third-party dependencies. Extras are opt-in.

# core only (detection, redaction, policy, adapters, pipeline, benchmark, CLI)
pip install -e .

# with the HTTP server / NLP / YAML / crypto extras as needed
pip install -e '.[server]'      # FastAPI proxy
pip install -e '.[nlp]'         # Presidio contextual PII
pip install -e '.[dev]'         # pytest + pyyaml (tests & benchmark)

CLI

# scan text (exit code 3 if the request would be blocked)
echo "DNI 12345678Z, IBAN ES9121000418450200051332, key sk-ant-api03-…" | bpg scan

bpg scan --json report.txt          # machine-readable
bpg benchmark --markdown            # reproduce the benchmark
bpg policy config/policy.example.yaml   # show the effective policy
bpg serve --policy config/policy.example.yaml   # run the gateway (needs [server])

Python API

from bivelio_privacy_gateway.gateway.pipeline import Sanitizer
from bivelio_privacy_gateway.policy.engine import Policy

sanitizer = Sanitizer(Policy.default())

outcome = sanitizer.sanitize_request(
    "/v1/chat/completions",
    {"model": "gpt-4o", "messages": [
        {"role": "user", "content": "Mi DNI es 12345678Z y mail [e-mail]"}]},
    tenant="acme", session="conv-42", request_id="req-1",
)

outcome.decision          # "forward" | "route_local" | "deny"
outcome.body              # sanitised payload (safe to forward to LiteLLM)
outcome.audit.by_type     # {"SPANISH_DNI": 1, "EMAIL": 1}  -- counts, no values

# on the way back, restore reversible tokens inside the perimeter
reply = sanitizer.restore_response(provider_text, tenant="acme", session="conv-42")

Docker

docker compose up --build      # gateway + LiteLLM router (see docker-compose.yml)

---

Network egress control (mandatory)

Application-level inspection is necessary but not sufficient. At the infrastructure layer:

• BiVelio services have no direct outbound internet access.
• Only the gateway may reach provider domains / the LiteLLM router.
• LiteLLM accepts traffic only from the gateway.
• Provider credentials live only in the gateway / router, never in Brain.

This makes it technically impossible for a new SDK, script or dependency to call a provider directly and bypass BV-PRGA. See docs/THREAT_MODEL.md.

---

Policy

Policies are declarative (defaults in code, overridable via YAML). Example:

mode: fail_closed
unknown_endpoint: deny
unsupported_content: deny
actions:
  ANTHROPIC_API_KEY: block
  PRIVATE_KEY: block
  CREDIT_CARD: redact
  EMAIL: pseudonymize
  INTERNAL_CONFIDENTIAL: route_local
detectors:
  pii: { engine: presidio, enabled: false, languages: [es, ca, fr, en] }
  tenant_dictionaries:
    terms: { INTERNAL_CONFIDENTIAL: ["Proyecto Aurora"] }
storage:
  token_vault: { ttl_seconds: 900 }

Full action table and rationale in docs/POLICY.md.

---

Project layout

src/bivelio_privacy_gateway/
├── detectors/    checksums, structured IDs, secrets, tenant dicts, engine, presidio
├── redaction/    token vault (scoped/TTL) + transformer (redact/pseudonymize/block)
├── policy/       declarative entity→action engine
├── adapters/     recursive walker + OpenAI/Anthropic/embeddings + registry
├── audit/        value-free events + synthetic canaries
├── gateway/      fail-closed pipeline + FastAPI app + streaming restorer
├── benchmark/    seeded corpus + runner + markdown report
└── cli.py        bpg scan | benchmark | policy | serve
licensing/    BV-LIC: model, token codec, keys, verifier, enforcement, issuer
services/         CP-0 control plane (Hetzner side): common · licensing · metering
apps/web/         privacy.bivelio.com marketing site (Next.js → Vercel)
deploy/           control-plane Dockerfiles · compose · Keycloak realm notes
tests/            74 tests across every layer (gateway + CP-0)
docs/             ARCHITECTURE · THREAT_MODEL · POLICY · BENCHMARKS · LICENSING ·
                  ROADMAP · COMMERCIALIZATION-PLAN · CONTROL-PLANE · DEPLOYMENT-TOPOLOGY

---

Development

make install      # editable install with dev extras
make test         # pytest (53 tests)
make benchmark    # JSON benchmark
make lint         # ruff (if installed)

---

Roadmap

• Presidio contextual-PII layer integrated (multilingual es/ca/fr/en) and evaluated — oracle recall 0.99 / auto F1 0.94, combined residual leak ~3 %. See docs/BENCHMARKS.md. Next: evaluate on a real internal corpus and tune thresholds/allowlists.
• Output-side DLP (scan tool outputs / generated URLs before they reach tools).
• Clustered, encrypted vault backend.
• NeMo Guardrails integration inside Brain/RAG (retrieval + execution + output rails).
• Batch/Files/Vector-store adapters (currently denied).

---

Commercial model — BV-LIC

BV-PRGA is monetised as a self-hosted product: the gateway runs on the customer's infrastructure (their data never leaves their perimeter), and a signed BV-LIC license key unlocks paid capabilities. Key properties:

• Offline-verifiable Ed25519 licenses (work air-gapped); the customer embeds only BiVelio's public key.
• Fail-closed-safe enforcement: an expired/invalid/missing license degrades to Community (commercial features off) but never disables DLP protection.
• Privacy-safe metering: the value-free audit events (counts + decisions + license_id/tier, never content) are exactly what BiVelio's control plane ingests for usage-based billing — no sensitive data reaches BiVelio.

bpg license verify "$BPG_LICENSE_TOKEN" --tenant acme   # customer side
python scripts/bvlic_issue.py issue ...                  # BiVelio control plane

Data plane = customer infra. Control plane (licensing + metering + updates) = BiVelio Hetzner (shared Keycloak / Hyperswitch / Qdrant / Postgres). Full design in docs/COMMERCIALIZATION-PLAN.md and docs/LICENSING.md.

License

Commercial. © 2026 BiVelio Inc. All rights reserved. Distributed under the BiVelio Shield — Gateway Commercial License: download / install / run granted, Evaluation Use free, Production Use requires a valid BV-LIC Seat License (USD 4.00 / Seat / month); all other rights (modify, redistribute, reverse-engineer, circumvent BV-LIC) reserved. The BV-PRGA algorithm and all related inventions are the property of BiVelio Inc., which reserves all copyright and patent rights. See LICENSE, NOTICE, and THIRD-PARTY-NOTICES.md.