Obfuscating & Restoring Text

Replace PII with realistic fake data and restore originals using session-based mappings.

Overview

obfuscate() detects PII in a string and replaces each sensitive entity with a realistic fake value. Every substitution is recorded in a session so you can restore the original text at any time using restore().

This makes @secured-ai/core suitable for workflows where you need to send text to an external service (an LLM API, a third-party analytics pipeline, etc.) without exposing real user data, then restore the original on the way back.

Obfuscating text

import { PrivacyClient } from '@secured-ai/core'

const client = new PrivacyClient({
  baseUrl: 'https://dev-api.securedai.com',
  sdkAccessToken: import.meta.env.VITE_SECURED_SDK_ACCESS_TOKEN,
})
await client.initialize()

const result = await client.obfuscate(
  'Please contact Dr. Alice Brown at alice@clinic.com about patient ID 7734.'
)

`ObfuscationResult`

interface ObfuscationResult {
  processed: string         // text with PII replaced
  sessionId: string         // UUID — use this to restore later
  hasSensitiveData: boolean // false if no PII was found
}

console.log(result.processed)
// 'Please contact Dr. Emily Carter at sarah.n@webmail.org about patient ID 7734.'

console.log(result.sessionId)       // 'a3f2c1d0-...'
console.log(result.hasSensitiveData) // true

Even when hasSensitiveData is false, a session is still created so restore() works consistently regardless of whether PII was present.

Consistent replacements

The same entity appearing multiple times in the same text is always replaced with the same fake value. This keeps the output coherent and avoids leaking identity through inconsistency:

const { processed } = await client.obfuscate(
  'Alice Brown called. Alice Brown left a voicemail. Call Alice Brown back.'
)

// 'Emily Carter called. Emily Carter left a voicemail. Call Emily Carter back.'
// — not three different names

Consistency is keyed on the normalised entity text and type. Two different entities of the same type (e.g. two different emails) will get different replacements.

Restoring original text

Pass the obfuscated text and the sessionId to restore():

const restoration = await client.restore(result.processed, result.sessionId)

`RestorationResult`

interface RestorationResult {
  restored: string         // original text with PII put back
  mappingsApplied: number  // how many substitutions were reversed
  success: boolean         // false if sessionId was not found
}

console.log(restoration.restored)
// 'Please contact Dr. Alice Brown at alice@clinic.com about patient ID 7734.'

console.log(restoration.mappingsApplied) // 2
console.log(restoration.success)         // true

If success is false, the session was not found (it may have been cleared). Always check success before using restored.

Customising replacement values

By default, replacements are generated by @faker-js/faker. You can supply your own replacement pools per entity type in PrivacyClientConfig. The library cycles through your pool values sequentially and falls back to faker when the pool is exhausted.

const client = new PrivacyClient({
  baseUrl: 'https://dev-api.securedai.com',
  sdkAccessToken: import.meta.env.VITE_SECURED_SDK_ACCESS_TOKEN,
  replacementPools: {
    PERSON: ['Alex Taylor', 'Jordan Lee', 'Morgan Smith'],
    EMAIL: ['user@redacted.example', 'contact@anon.example'],
    PHONE: ['800-555-0100', '800-555-0101'],
  },
})

This is useful when you need replacements that fit a specific format, pass downstream validation, or match your test data conventions.

Replacement pools are set at construction time and apply to all obfuscate() calls on that client instance. They cannot be changed after the client is created.

Session lifecycle

Sessions are stored in memory on the PrivacyClient instance. They persist for the lifetime of the instance unless explicitly cleared.

// Retrieve a specific session
const session = client.getSession(result.sessionId)

// List all active sessions
const sessions = client.getSessions()

// Remove a specific session (frees memory)
client.clearSession(result.sessionId)

// Remove all sessions
client.clearAllSessions()

For cross-context restoration (e.g. restoring in a different browser tab or after a page reload), see Sessions and the standalone deobfuscate() function.

Obfuscating & Restoring Text

On this page