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, …). What is actually benchmarked is narrower than what ships: the corpus scores 15 entity types, while the structured detector alone carries 99 rules over 96 distinct types. On those 15 the layer measures at precision/recall 1.000 with zero residual leak — that result covers about a sixth of the shipped rule surface, and says nothing about the rest.
• 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.

Benchmarks (reproduced from code)

Measured on the deterministic layer (structured identifiers + secrets) over a seeded, labelled, multilingual corpus with hard negatives, on the 15 entity types the corpus covers (seed 1234, core track). Full methodology and the honesty caveats (what is not measured) are in docs/BENCHMARKS.md, which is regenerated from code.

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

On the throughput figure. It is the only number here that is not deterministic, and it is hardware- and load-specific: the range above is twelve runs on an Apple M4 Pro (14 cores, 48 GB), macOS 15.7.4, CPython 3.13.7, and a run taken while that machine was at load average 15 fell to 192 k chars/s. This README previously advertised ~3.0 M chars/s (~6.9 k docs/s) — roughly 8× what the code measures anywhere we can reproduce it, and ~5.7× the figure docs/BENCHMARKS.md was itself generating, which is how the gap was found: the repo's own generated doc disagreed with its own front page. Do not quote a throughput number you have not run on your own hardware; run make benchmark-doc and read it out of the generated block.

The detection numbers are deterministic-layer numbers by design — checksum gating makes near perfect precision/recall achievable for IDs and secrets, on the types the corpus exercises. 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/pt/de (the Policy.languages default; the deterministic benchmark corpus, separately, is 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

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 ana@bivelio.com"}]},
    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

cp .env.example .env           # then set BPG_VAULT_SECRET to a strong value
docker compose up --build      # gateway + LiteLLM router (see docker-compose.yml)

The first line was missing, and without it a clean clone stops at required variable BPG_VAULT_SECRET is missing a value. The refusal is correct — the vault secret is what makes tokens unforgeable, so compose declines to invent one — but cp .env.example .env appeared in no document in the tree, so the quickstart was one line short of working.

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/            ~1,200 tests across every layer (gateway + CP-0) — `make test`
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 — 1,196 collected on 2026-08-09, and growing; the
                  # README used to claim 53, and elsewhere 74. Run it rather
                  # than quoting it: an exact count in prose is stale on arrival.
make benchmark    # JSON benchmark
make lint         # ruff (if installed)

Roadmap

• Presidio contextual-PII layer integrated (multilingual es/ca/fr/en/pt/de — six languages, the Policy.languages default) and evaluated — oracle recall 0.989 / auto F1 0.938, language detection 0.86, combined residual leak 4.9 % (39 of 800, seed 2026, re-measured 2026-08-09). See docs/BENCHMARKS.md. Next: evaluate on a real internal corpus and tune thresholds/allowlists — and fix the language guesser, which is what separates auto recall from oracle recall.
• 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.