npm package: @futurespeak-ai/privacy-shield
Description: Strip PII from LLM prompts. Restore it in responses. Zero cloud dependency.
Author: FutureSpeak.AI
Latest version: 1.0.0

# Privacy Shield

**Strip PII from LLM prompts. Restore it in responses. Zero cloud dependency.**

---

## The Problem

Every API call to an LLM can leak sensitive data. API keys, email addresses, credit card numbers, Social Security numbers, file paths with your username in them. Once those tokens hit an external server, you have lost control of them. Most developers do not realize how much PII flows through their prompts until it is too late.

Privacy Shield sits between your application and the LLM. It detects PII using regex pattern matching, replaces each match with a deterministic placeholder, and stores the mapping locally. When the response comes back, it rehydrates the placeholders with the original values. The LLM never sees your secrets. Your output is fully restored.

## How It Works

1. **Detection** -- Regex patterns scan text across 10 PII categories
2. **Replacement** -- Each match gets a deterministic placeholder using FNV-1a hashing scoped to your session nonce
3. **Round-trip** -- Rehydration restores placeholders to original values with perfect fidelity

Placeholders look like `<<PII:SECRET:a3f8b2c1>>`. They are deterministic within a session, so the same value always produces the same placeholder. Different sessions produce different placeholders.

## PII Categories

| Category | What it catches | Example |
|---|---|---|
| **SECRET** | Anthropic keys, OpenAI keys, AWS keys, GitHub PATs, Slack tokens, Google API keys, JWTs, generic secrets | `sk-ant-api03-...`, `AKIA...`, `ghp_...` |
| **CREDIT_CARD** | Visa, Mastercard, Amex, Discover | `4111111111111111` |
| **SSN** | US Social Security numbers | `123-45-6789` |
| **EMAIL** | Email addresses | `alice@example.com` |
| **PHONE** | US phone numbers (various formats) | `(512) 555-0199` |
| **IP** | Public IP addresses (preserves private/loopback) | `203.0.113.42` (scrubbed), `192.168.1.1` (kept) |
| **PATH** | File paths containing your OS username | `C:\Users\you\secret.txt` |

Private IPs (`192.168.x`, `10.x`, `172.16-31.x`) and loopback (`127.0.0.1`) are intentionally preserved. They are not externally identifying.

## Install

```bash
npm install @asimov-federation/privacy-shield
```

## Quick Start

```javascript
import { createShield } from '@asimov-federation/privacy-shield';

const shield = createShield();

const clean = shield.scrub('My key is sk-ant-api03-secret123456789012345 and email is me@corp.com');
// Send `clean` to your LLM -- no secrets leave your machine

const restored = shield.rehydrate(llmResponse);
// Original values are back
```

## API Reference

### `createShield(config?)`

Creates an isolated Privacy Shield instance.

**Config options:**

| Option | Type | Default | Description |
|---|---|---|---|
| `nonce` | `string` | Random hex | Session nonce for deterministic hashing |
| `patterns` | `object` | `{}` | Additional regex patterns keyed by category |
| `username` | `string` | `process.env.USERNAME` or `USER` | OS username for path scrubbing |

**Returns** an object with four methods:

#### `shield.scrub(text)`

Scans text for PII, replaces matches with placeholders, returns scrubbed text.

```javascript
const scrubbed = shield.scrub('Contact jane@acme.com about invoice 4111111111111111');
// 'Contact <<PII:EMAIL:f3a1b2c4>> about invoice <<PII:CREDIT_CARD:d9e8f7a6>>'
```

#### `shield.rehydrate(text)`

Restores PII placeholders to their original values.

```javascript
const restored = shield.rehydrate(scrubbed);
// 'Contact jane@acme.com about invoice 4111111111111111'
```

#### `shield.stats()`

Returns scrubbing statistics for the current session.

```javascript
shield.stats();
// { categories: { EMAIL: 1, CREDIT_CARD: 1 }, total: 2 }
```

#### `shield.reset()`

Clears all stored mappings, generates a new session nonce, and zeros the stats. Previously scrubbed placeholders will no longer rehydrate.

### Exported Utilities

```javascript
import { PII_PATTERNS, scrubPii, rehydratePii, fnv1a, escapeRegex } from '@asimov-federation/privacy-shield';
```

These are the lower-level building blocks if you need to integrate with custom storage or build your own shield implementation.

## Integration with LLM Libraries

### Wrapping fetch calls

```javascript
import { createShield } from '@asimov-federation/privacy-shield';

const shield = createShield();

async function safeLlmCall(prompt) {
  const scrubbed = shield.scrub(prompt);

  const response = await fetch('https://api.anthropic.com/v1/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.ANTHROPIC_API_KEY,
      'anthropic-version': '2023-06-01'
    },
    body: JSON.stringify({
      model: 'claude-sonnet-4-20250514',
      max_tokens: 1024,
      messages: [{ role: 'user', content: scrubbed }]
    })
  });

  const data = await response.json();
  const rawAnswer = data.content[0].text;

  return shield.rehydrate(rawAnswer);
}
```

### Per-request isolation

If you need separate PII mappings per request (for example, in a multi-tenant server), create a shield per request:

```javascript
app.post('/chat', async (req, res) => {
  const shield = createShield();
  const clean = shield.scrub(req.body.prompt);
  const answer = await callLlm(clean);
  res.json({ response: shield.rehydrate(answer) });
});
```

## Custom Patterns

Add your own PII categories by extending an existing category:

```javascript
const shield = createShield({
  patterns: {
    SECRET: [/\bEMP-\d{6}\b/g],       // Employee IDs as secrets
    EMAIL: [/\b[A-Z0-9]+@internal\b/g] // Internal shorthand addresses
  }
});
```

## Running Tests

```bash
node test.js
```

25 tests covering all categories, round-trip rehydration, stats tracking, session determinism, reset behavior, custom patterns, and a real-world mixed-PII scenario.

## Credits

Built by [FutureSpeak.AI](https://futurespeak.ai) with [Claude Opus 4.6](https://anthropic.com) as part of the [Asimov Federation](https://github.com/asimov-federation).

Part of the Privacy Shield from Asimov's cLaws: data sovereignty means your secrets never leave your machine unmasked.

## Related

- [Agent Friday](https://github.com/asimov-federation/agent-friday) -- AI OS with voice portal, Claude Code backbone, and privacy-first architecture
- [Asimov's cLaw Spec](https://github.com/asimov-federation/claw-framework) -- Constraint framework for AI agents: safety, sovereignty, transparency

## License

MIT