# ScrubGuard - Deterministic PII & Secret Scrubber + Reversible LLM Tokenizer

Sub-millisecond, zero-dependency PII & secret redaction with **mathematical checksum verification** (Luhn Credit Cards, ISO 7064 Mod-97 IBANs, SSA US SSN rules) and **Reversible LLM Tokenization**.

Strip sensitive data before sending prompts to OpenAI, Anthropic, or logs, and rehydrate `[EMAIL_1]` / `[CREDIT_CARD_1]` placeholders in the LLM's response automatically.

- **Live API & Playground:** https://scrubguard-api.scrubguard.workers.dev
- **GitHub Repository:** https://github.com/scrubguard-dev/scrubguard
- **Support:** scrubguard@fastmail.com

---

## Features

- **Mathematical Checksum Validation:** Cuts false positives on order IDs and random numbers using Luhn (Credit Cards), ISO 7064 Mod-97 (IBANs), and SSA Area/Group/Serial validation (US SSNs).
- **Secret & API Key Detection:** Scrubs leaked OpenAI (`sk-proj-...`), Anthropic (`sk-ant-...`), Stripe (`sk_live_...`, `sk_test_...`, `whsec_...`), AWS (`AKIA...`), GitHub PAT (`ghp_...`, `github_pat_...`), Slack, Google API, JWT, and PEM Private Keys.
- **Reversible LLM Tokenization:** Replaces PII with consistent placeholders (`[EMAIL_1]`, `[US_SSN_1]`) and returns a `vault` map so LLM outputs can be restored via `rehydrateText` or `POST /v1/rehydrate`.
- **Deep JSON Sanitizer:** Recursively scrubs strings and sensitive keys (`password`, `secret`, `api_key`, `ssn`) up to 32 levels deep without breaking JSON schemas.
- **Linear-Time Regex Engine:** Disjoint character classes and bounded repetitions prevent catastrophic backtracking (ReDoS).

---

## Quick Start (Hosted Edge API)

### 1. Scrub & Tokenize Prompt Before Sending to an LLM (`POST /v1/scrub`)

```bash
curl -X POST https://scrubguard-api.scrubguard.workers.dev/v1/scrub \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Refund customer sarah@acme.io on card 4532 0151 1283 0366 (SSN 412-55-9821)",
    "mode": "tokenize"
  }'
```

**Response:**
```json
{
  "output": "Refund customer [EMAIL_1] on card [CREDIT_CARD_1] (SSN [US_SSN_1])",
  "findings_count": 3,
  "findings_by_type": {
    "CREDIT_CARD": 1,
    "US_SSN": 1,
    "EMAIL": 1
  },
  "vault": {
    "[CREDIT_CARD_1]": "4532 0151 1283 0366",
    "[US_SSN_1]": "412-55-9821",
    "[EMAIL_1]": "sarah@acme.io"
  }
}
```

### 2. Rehydrate LLM Output (`POST /v1/rehydrate`)

```bash
curl -X POST https://scrubguard-api.scrubguard.workers.dev/v1/rehydrate \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Processed refund for [EMAIL_1] ending in [CREDIT_CARD_1].",
    "vault": {
      "[CREDIT_CARD_1]": "4532 0151 1283 0366",
      "[EMAIL_1]": "sarah@acme.io"
    }
  }'
```

---

## Node.js / Edge SDK (`ScrubGuardClient`)

```javascript
import { ScrubGuardClient } from 'scrubguard-mcp'; // npm install scrubguard-mcp

const guard = new ScrubGuardClient({
  apiKey: process.env.SCRUBGUARD_API_KEY, // Optional: uses hosted Pro Edge API (100k req/mo)
});

// 1. Scrub user prompt
const { output: safePrompt, vault } = await guard.scrub(
  'Email alice@company.com with key AKIAIOSFODNN7EXAMPLE'
);

// 2. Send `safePrompt` to OpenAI / Anthropic...
const llmResponse = `Sent confirmation to ${safePrompt.match(/\[EMAIL_\d+\]/)[0]}.`;

// 3. Restore original values
const { output: finalReply } = await guard.rehydrate(llmResponse, vault);
```

---

## Model Context Protocol (MCP) Server for Claude Desktop & Cursor

ScrubGuard runs locally by default with no network calls. Add it to your `claude_desktop_config.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "scrubguard": {
      "command": "npx",
      "args": ["-y", "scrubguard-mcp"]
    }
  }
}
```

To use the optional hosted Pro API, or to run from a local clone:

```json
{
  "mcpServers": {
    "scrubguard": {
      "command": "node",
      "args": ["/path/to/scrubguard/mcp/index.js"],
      "env": {
        "SCRUBGUARD_API_KEY": "sg_live_optional_pro_key"
      }
    }
  }
}
```

Exposes three MCP tools to your AI assistant:
- `scrub_text`: Scrub or reversibly tokenize PII & secrets in text.
- `rehydrate_text`: Restore `[TOKEN_1]` placeholders using the vault map.
- `scrub_json`: Recursively sanitize nested JSON objects and logs.

---

## Support & Contact

Questions, bug reports, or higher volume plans: **scrubguard@fastmail.com**