PII Protection

The wrapper pseudonymises PII before any event leaves your runtime. Pseudonyms are derived from HMAC-SHA256 with a customer-held secret, so the same value always produces the same token. An encrypted token map is attached to each event — only the holder of your X25519 private key can reverse it. Wytness is zero-knowledge by construction.

How it works

1. Structured PII (emails, phones, SSN, AU TFN, credit cards) is detected by regex and replaced with typed HMAC tokens — EMAIL_3c866e6f, PHONE_9a3c5f78, etc.
2. Declared fields listed in pii_fields / piiFields are pseudonymised regardless of content — PII_a4f2e1c8. Use these for free-form fields the regexes can't catch: names, addresses, internal IDs.
3. The data payload of every event is walked recursively. Anywhere a declared dotted path matches (e.g. customer.email), the value is replaced with its pseudonym.
4. An encrypted token map is attached to each event, mapping pseudonyms back to originals. Encrypted with ChaCha20-Poly1305 using a fresh ephemeral X25519 keypair per event — forward secrecy means compromising one event doesn't expose others.

Setup

Pseudonymisation is on by default — the wrapper SDK requires the X25519 public key and the HMAC secret to init(). Generate both in the Keys page (browser-only, never seen by Wytness), set them as env vars, then declare any custom dotted paths in pii_fields / piiFields.

Env vars

1WYTNESS_PII_PUBKEY=<base64 X25519 public key, 32 bytes decoded>
2WYTNESS_PII_SECRET=<base64 HMAC secret, >= 16 bytes decoded>

Python

1import wytness_ai
2 
3# WYTNESS_PII_PUBKEY + WYTNESS_PII_SECRET read from env by default.
4wytness_ai.init(
5    pii_fields=[
6        "customer.email",
7        "customer.full_name",
8        "billing.address",
9    ],
10)

TypeScript

1import { init } from "@wytness/ai";
2 
3// WYTNESS_PII_PUBKEY + WYTNESS_PII_SECRET read from env by default.
4await init({
5  piiFields: [
6    "customer.email",
7    "customer.fullName",
8    "billing.address",
9  ],
10});

Auto-detected patterns

Regardless of pii_fields, the SDK pseudonymises these patterns wherever they appear in the data payload:

Tokens are deterministic — the same value always produces the same token across sessions, agents, and time. This lets you correlate events involving the same person without ever storing their actual data.

Generating keys

The recommended path is the dashboard Keys page — both keys are generated in your browser using crypto.getRandomValues() + TweetNaCl, downloaded as a bundle, and stored in your secrets manager. The X25519 public key is registered with the Wytness backend so the dashboard knows which event maps to which keypair on reveal.

If you'd rather generate them yourself:

1# HMAC secret (32 bytes, base64-encoded)
2python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"
3 
4# X25519 keypair
5python3 -c "
6from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
7import base64
8priv = X25519PrivateKey.generate()
9pub_bytes = priv.public_key().public_bytes_raw()
10priv_bytes = priv.private_bytes_raw()
11print('PII_PUBKEY (SDK env var):', base64.b64encode(pub_bytes).decode())
12print('PII_PRIVATE (dashboard reveal — keep safe):', base64.b64encode(priv_bytes).decode())
13"

Register the X25519 public key against your org on the Keys page so the dashboard knows which key maps to your events. Store the X25519 private key somewhere you can paste into the dashboard when you need to reveal pseudonyms.

Revealing PII in the dashboard

When pseudonymisation is active, the dashboard shows tokens like EMAIL_3c866e6f by default. To see the originals:

1. Go to Keys → PII Reveal Key.
2. Paste your X25519 private key (base64, 32 bytes decoded).
3. Navigate to Events or Sessions — pseudonymised events now show a reveal toggle.
4. Click the toggle to render original values, highlighted in amber.

Security architecture

Related

• SDK API reference — full config + env-var table
• Security model
• Keys & signing — how the customer-held primitives compose with AGT identity