Sessions
How @secured-ai/core tracks obfuscation mappings and enables cross-context restoration.
What is a session?
Every time you call obfuscate(), @secured-ai/core creates a session — an in-memory record of every substitution made. Sessions are the mechanism that makes obfuscation reversible: without the session, you cannot restore the original text.
interface PrivacySession {
sessionId: string // UUID — your handle to this session
mappings: SessionMapping[] // every substitution that was made
createdAt: Date
originalText: string // the input text before obfuscation
processedText: string // the output text after obfuscation
}Each mapping entry records one substitution:
interface SessionMapping {
id: string // UUID for this mapping
original: string // the real PII value
replacement: string // the fake value that replaced it
entityType: EntityType // e.g. 'EMAIL', 'PERSON'
position: { start: number; end: number } // character position in original text
}Session lifecycle
Sessions are stored in memory on the PrivacyClient instance. They persist until you explicitly clear them or the instance is garbage collected.
// Create a session via obfuscate()
const { sessionId } = await client.obfuscate('Alice at alice@example.com')
// Retrieve the session
const session = client.getSession(sessionId)
console.log(session?.mappings.length) // 2
// List all active sessions
const all = client.getSessions()
console.log(all.length) // 1
// Free a specific session
client.clearSession(sessionId)
// Free all sessions
client.clearAllSessions()A session is created even when no PII is detected — hasSensitiveData will be false and mappings will be empty. This keeps the restore() API consistent regardless of whether obfuscation was needed.
Restoring within the same client instance
The simplest restoration path — use restore() on the same PrivacyClient instance that created the session:
const client = new PrivacyClient({
baseUrl: 'https://dev-api.securedai.com',
sdkAccessToken: import.meta.env.VITE_SECURED_SDK_ACCESS_TOKEN,
})
await client.initialize()
const { processed, sessionId } = await client.obfuscate(
'Refer to case INV-2024-0042 filed by Jane Doe.'
)
// ... send `processed` to an external service ...
const { restored, success } = await client.restore(processed, sessionId)
// restored === 'Refer to case INV-2024-0042 filed by Jane Doe.'Cross-context restoration with deobfuscate()
Session data lives in memory. If you need to restore text in a different context — a different browser tab, after a page reload, on a server-side function, or in a completely different PrivacyClient instance — you need to serialise the session mappings and use the standalone deobfuscate() function.
Step 1: Serialise the mappings after obfuscation
const { processed, sessionId } = await client.obfuscate(sensitiveText)
const session = client.getSession(sessionId)!
// Serialise mappings to JSON — store in localStorage, a database, or send to your server
const serialisedMappings = JSON.stringify(session.mappings)Step 2: Restore using the serialised mappings
import { deobfuscate } from '@secured-ai/core'
// Later — in any context, no PrivacyClient needed
const mappings = JSON.parse(serialisedMappings)
const restored = deobfuscate(obfuscatedText, mappings)Session export and import
If you want to move a full session between contexts rather than passing only the raw mappings, use exportSession() and importSession().
Export a session
const { sessionId } = await client.obfuscate(sensitiveText)
const serialized = client.exportSession(sessionId)serialized is a JSON-safe SerializedPrivacySession that can be stored or transmitted.
Import a session elsewhere
const otherClient = new PrivacyClient({
baseUrl: 'https://dev-api.securedai.com',
sdkAccessToken: import.meta.env.VITE_SECURED_SDK_ACCESS_TOKEN,
})
const imported = otherClient.importSession(serialized!)
const restored = await otherClient.restore(obfuscatedText, imported.sessionId)This is the best fit when another browser context or client instance should be able to use the normal restore() API instead of the standalone deobfuscate() helper.
Full cross-context example
// --- Browser (send side) ---
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 text = 'Patient John Doe, DOB 01/15/1985, SSN 123-45-6789.'
const { processed, sessionId } = await client.obfuscate(text)
const session = client.getSession(sessionId)!
// Send obfuscated text to the API, along with mappings for later restoration
const response = await fetch('/api/process', {
method: 'POST',
body: JSON.stringify({
text: processed,
mappings: session.mappings, // serialise and send
}),
})
const { result, mappings } = await response.json()
// --- Browser (receive side) ---
import { deobfuscate } from '@secured-ai/core'
// No PrivacyClient needed here — just the mappings
const original = deobfuscate(result, mappings)
console.log(original) // 'Patient John Doe, DOB 01/15/1985, SSN 123-45-6789.'Treat mappings as sensitive data
Session mappings contain the original PII values in plain text. Treat them with the same care as the original data — do not log them, store them unencrypted, or include them in client-side error reports.
Memory management
Each session stores both the original and processed text plus all mappings. In high-throughput applications, clear sessions when they are no longer needed:
// After successful restoration, clean up
const { restored, success } = await client.restore(processed, sessionId)
if (success) {
client.clearSession(sessionId)
}