# teodorofodocrispin-cmyk/trustboost-pii-sanitizer [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/teodorofodocrispin-cmyk/trustboost-api  
**GitHub Stars:** 2  
**npm Downloads (last month):** 4046  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/teodorofodocrispin-cmyk-trustboost-pii-sanitizer

## Description
PII sanitization layer for autonomous AI agent pipelines. Detects and redacts emails, phone numbers, national IDs, private keys, and financial data before text reaches LLMs. Supports EN, ES (LATAM), PT (BR/PT), DE, JA. Solana-native payments via Helius oracle.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "trustboost-pii-sanitizer": {
    "command": "uvx",
    "args": ["pytest"]
  }
}
```

## Documentation & README

# TrustBoost PII Sanitizer

A precision PII redaction layer for autonomous AI agent pipelines.
Detects and redacts personally identifiable information **before** it reaches
LLM providers, across English, Spanish (LATAM), Portuguese (BR/PT), German,
Japanese, French, Italian, and Korean.

- **Endpoint:** `https://api.trustboost.dev/sanitize`
- **Stack:** FastAPI · OpenAI `gpt-4o-mini` (temperature 0) · Supabase · Solana payments via Helius

## 🛡️ Live Demo — no registration required

**Try TrustBoost instantly in your browser:**
👉 https://huggingface.co/spaces/TrustBoost/pii-sanitizer

## Try it in 10 seconds — no wallet needed

```bash
curl -X POST https://api.trustboost.dev/sanitize/preview \
  -H "Content-Type: application/json" \
  -d '{"text": "My name is John Doe, email john@gmail.com, SSN 123-45-6789"}'
```

```json
{
  "sanitized_content": "My name is [REDACTED], email [REDACTED], SSN [REDACTED]",
  "safety_score": 0.6,
  "risk_category": "PRIVATE",
  "demo": true,
  "requests_remaining": 2,
  "next": "https://github.com/teodorofodocrispin-cmyk/TrustBoost-PII-Sanitizer#trial"
}
```

3 free previews per IP · no account · no wallet · no setup.
Ready for more? See [Trial mode](#trial) below — 50 free sanitizations with a Solana wallet.

---

## Pay-per-call — /sanitize/quick (recommended for M2M agents)

The lightest-weight entry point for autonomous agents: pay $0.01 USDC per call,
no TRIAL, no tx_hash, no prepaid bundle.

```bash
curl -X POST https://api.trustboost.dev/sanitize/quick \
  -H "Content-Type: application/json" \
  -H "PAYMENT-SIGNATURE: <base64-encoded x402 v2 signature>" \
  -d '{"text": "Contact John at john@company.com, SSN 123-45-6789"}'
```

- Networks: Base (`eip155:8453`, preferred) or Solana (`solana:5eykt4...`) — auto-detected
- Verified + settled via [PayAI facilitator](https://facilitator.payai.network)
- `X-PAYMENT` header also accepted (x402 v1, legacy)
- No text or no payment header yet? Returns a standard x402 v2 402 with payment instructions
- For 10,000+ calls, the [prepaid bundle](#quick-start) (149 USDC) is cheaper per call

---

## MCP Server — Claude, Cursor & Windsurf native integration

TrustBoost is available as an MCP (Model Context Protocol) server.
Add it to any MCP-compatible agent in one line:

```json
{
  "mcpServers": {
    "trustboost": {
      "url": "https://api.trustboost.dev/mcp"
    }
  }
}
```

Once connected, your agent can call `sanitize_pii` automatically
before sending any text to an LLM:

```bash
# Manifest
curl https://api.trustboost.dev/mcp

# Execute
curl -X POST https://api.trustboost.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"tool": "sanitize_pii", "input": {"text": "My email is john@gmail.com"}}'
```

Compatible with: Claude Code · Cursor · Windsurf · Any MCP-compatible agent

---

## Quick start

```bash
curl -X POST https://api.trustboost.dev/sanitize \
  -H 'Content-Type: application/json' \
  -d '{
    "text": "My email is jane@example.com and my AWS key is AKIAIOSFODNN7EXAMPLE",
    "tx_hash": "TRIAL",
    "wallet_address": "your-agent-id"
  }'
```

Trial mode (`tx_hash="TRIAL"`) gives 50 free sanitizations per `wallet_address`.
Paid mode requires 149 USDC on Solana to the configured payment wallet, which
unlocks 10,000 sanitizations per transaction signature.

## Response schema (v2.6.0)

```json
{
  "status": "success",
  "request_id": "TRIAL",
  "data": {
    "message": "Content successfully sanitized and logged.",
    "sanitized_content": "My email is [REDACTED] and my AWS key is [REDACTED]",
    "safety_score": 0.6,
    "risk_category": "CRITICAL",
    "entities_removed": true,
    "entities": [
      { "type": "email",          "category": "PRIVATE",  "redacted_text": "jane@example.com" },
      { "type": "aws_access_key", "category": "CRITICAL", "redacted_text": "AKIAIOSFODNN7EXAMPLE" }
    ],
    "redaction_source": "server",
    "timestamp": "2026-05-03T23:48:14.500705+00:00",
    "usage_metrics": { "quota_remaining": 48, "quota_limit": 50 }
  },
  "billing": { "license_type": "TRIAL", "status": "active" }
}
```

### Field guide

| Field              | Type                 | Notes                                                                   |
| ------------------ | -------------------- | ----------------------------------------------------------------------- |
| `sanitized_content`| `string`             | Same language and structure as input, with PII replaced by `[REDACTED]`. |
| `entities`         | `Entity[]`           | One element per `[REDACTED]` tag. Stable, machine-friendly.              |
| `safety_score`     | `float` 0.0 – 1.0    | **Server-side, deterministic.** Computed from `entities`, not the model. |
| `risk_category`    | `CRITICAL`/`PRIVATE`/`SENSITIVE`/`CLEAN` | Highest tier present in `entities`.                  |
| `entities_removed` | `bool`               | Convenience: `true` iff `entities` is non-empty.                         |
| `redaction_source` | `"model" \| "server" \| "fallback_full_redaction"` | Telemetry: who actually performed the redaction (see below).                 |
| `unmatched_entities` | `Entity[]` (optional) | Entities the model reported but whose `redacted_text` wasn't found verbatim in the input. Omitted when empty. |

### Risk weights

`safety_score` is the sum of per-entity weights, capped at 1.0:

- `CRITICAL` → 0.40 (API keys, private keys, seed phrases, credentials, card numbers, …)
- `PRIVATE`  → 0.20 (emails, phone numbers, national IDs, addresses, names, …)
- `SENSITIVE`→ 0.05 (handles, partial identifiers, DOB, …)

`risk_category` is the highest-severity tier with at least one entity, or
`"CLEAN"` if `entities` is empty.

## Server-side redaction enforcement (v2.6.0)

The model returns two things that have to agree: `cleaned_text` and
`entities`. In practice they sometimes disagree — the model can correctly
identify an entity in `entities` but fail to actually replace it in
`cleaned_text`. That produces a `sanitized_content` that still leaks PII
while the audit trail says everything is fine, which is worse than no audit
trail.

v2.2 fixes this structurally. The model is now treated purely as a
*detector*: it returns the entity list. The server is the *redactor*: for
every entity whose `redacted_text` is a non-empty substring of the original
input, the server replaces **all** occurrences with `[REDACTED]`. Long
entities are processed before short ones to avoid partial overlap.

Conservative redaction by design: if the same value (e.g. `田中太郎`)
appears twice in the input, both occurrences are scrubbed.

The `redaction_source` field tells you what happened:

- `"model"` — the model's `cleaned_text` already matched the entity list,
  so server-side enforcement was a no-op (the model did its job).
- `"server"` — the server-side enforcer replaced one or more entities the
  model failed to remove. Track this metric over time as a model-reliability
  signal: a rising `server` rate means the prompt or model is drifting.
- `"fallback_full_redaction"` — the model returned malformed JSON; the
  failsafe parser triggered and the entire input was redacted as a single
  `CRITICAL` entity. Should be near-zero in steady state.

When the model's `redacted_text` does not appear verbatim in the input
(paraphrasing, normalization, or hallucination), the entity is preserved in
`entities` (and counts toward `safety_score`) but is also returned in
`unmatched_entities` so callers can audit it.

## Failure mode: fail-safe, not fail-open

If the upstream model returns malformed JSON, the response degrades to a
single `CRITICAL` entity covering the entire input rather than risking a
silent leak. Over-redaction is always preferred over under-redaction.

## Languages and patterns

The system prompt covers, among others:

- **English (global):** emails, phones, SSN, credit cards, IBAN, IPs, addresses, and provider-specific API keys (OpenAI, Anthropic, GitHub, AWS, Google, Slack, HuggingFace, Stripe), private keys, crypto wallets, seed phrases.
- **Spanish (LATAM):** RFC, CURP, CUIT/CUIL, RUT, DNI, RUC, NIT, Cédula, country phones.
- **Portuguese (BR/PT):** CPF, CNPJ, RG, NIF, NUS, CEP, country phones.
- **German (DE/AT/CH):** Personalausweis, Steuer-IDs, Sozialversicherungsnummer, IBAN DE, addresses.
- **Japanese:** マイナンバー, 法人番号, 運転免許証, パスポート, 健康保険証, 電話番号, 住所, and 氏名 (full names in kanji, mixed scripts, katakana, or hiragana).
- **French (FR/BE/CH/CA):** NIR (Numéro de Sécurité Sociale), SIRET, SIREN, Carte Vitale, IBAN FR, Numéro fiscal, country phones +33/+32/+41.
- **Italian (IT):** Codice Fiscale, Partita IVA, Carta d'Identità (CIE), Tessera Sanitaria, IBAN IT, Patente di Guida, country phone +39.
- **Korean (KR):** 주민등록번호 (RRN), 사업자등록번호, 여권번호, 운전면허번호, 건강보험번호, 외국인등록번호, country phone +82.

## Running locally

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env  # then fill in real keys
uvicorn main:app --reload
```

Required environment variables:

- `OPENAI_API_KEY`
- `SUPABASE_URL`, `SUPABASE_KEY`
- `HELIUS_API_KEY`, `PAYMENT_WALLET`
- Optional: `TRIAL_QUOTA` (default 50), `PAID_QUOTA` (default 10000), `REQUIRED_PAYMENT_USDC` (default 149)

## Tests

```bash
pip install pytest
python -m pytest tests/test_sanitize.py -v          # unit tests, no creds needed
TRUSTBOOST_LIVE=1 python -m pytest tests/test_live.py -v   # hits real /sanitize
```

The live tests consume TRIAL quota; set `TRUSTBOOST_WALLET` to a CI-specific
identifier so they don't share quota with developer wallets.

## Versioning

- **2.6** — Proof of Sanitization on Solana via Helius. Every paid sanitization anchored on-chain. Verifiable at `/verify/{anchor_tx}`. x402 native — HTTP 402 with autonomous payment instructions. CORS for browser agents. agent-card.json for Circle Agent Stack discovery.
- **2.5** — Context-Aware Sanitization, Privacy Budget per Agent, TrustBoost Score M2M.
- **2.2** — server-side redaction enforcer, `redaction_source` telemetry, `unmatched_entities` audit field.
- **2.3** — Context-Aware Sanitization: `context` field in `/sanitize` (legal/financial/medical/code/general). Adjusts sanitization depth per context type. Adds `context_applied` to response.
- **2.4** — Privacy Budget per Agent: `agent_budgets` table in Supabase. Operators configure daily limits once, agents operate autonomously within them.
- **2.5** — TrustBoost Score: `/score/{wallet}` endpoint. M2M trust verification with trust tier (TRUSTED/VERIFIED/ACTIVE/NEW). Aggregated from audit_log.
- **2.6** — Proof of Sanitization on Solana: every paid sanitization is anchored on-chain via Helius Memo transaction. Verifiable by anyone at `/verify/{anchor_tx}`. Returns `proof_of_sanitization` object with Solscan link.
- **2.1** — structured `entities` array, server-side deterministic scoring, hardened JSON parsing, improved Japanese 氏名 detection.
- **2.0** — multilingual prompt rewrite.