Utilities & Adapters

These APIs are exported from @secured-ai/core for applications that need more control than the main PrivacyClient flow.

String matching utilities

StringMatcher

StringMatcher compares two strings using exact, case-insensitive, and optional fuzzy matching.

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

const matcher = new StringMatcher({
  minConfidence: 0.7,
  maxEditDistance: 2,
  enableCaseInsensitive: true,
  enableFuzzyMatching: true,
})

MatchConfig

interface MatchConfig {
  minConfidence: number
  maxEditDistance: number
  enableCaseInsensitive: boolean
  enableFuzzyMatching: boolean
}

MatchResult

interface MatchResult {
  matched: boolean
  confidence: number
  matchType: 'exact' | 'case-insensitive' | 'fuzzy' | 'none'
  suggestion?: string
}

Typical methods:

• match(target, candidate)
• findBestMatch(target, candidates)
• similarity(left, right)
• isLikelySameEntity(original, candidate)

Presets

The package also exports three presets:

• defaultStringMatcher
• strictStringMatcher
• lenientStringMatcher

Use strict mode when you want fewer false positives and lenient mode when you want more aggressive equivalence matching.

Vault repository helper

DefaultVaultRepository

DefaultVaultRepository is the built-in repository adapter for fetching encrypted persisted entity snapshots from a backend API.

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

const repository = new DefaultVaultRepository({
  getAuthToken: async () => accessToken,
  includeCredentials: false,
})

DefaultVaultRepositoryOptions

interface DefaultVaultRepositoryOptions {
  getAuthToken?: RuntimeValue<string | null>
  fetch?: typeof fetch
  includeCredentials?: boolean
}

DefaultVaultRepository uses the baseUrl configured on PrivacyClient.

Default behavior:

• fetches global snapshots from GET /ai/sensitive-keys
• fetches thread snapshots from GET /ai/threads/:threadId/sensitive-keys
• sends Accept: application/json
• adds Authorization: Bearer ... when getAuthToken resolves to a token
• treats 404 as "no snapshot exists"
• throws on non-404 failures so callers can fall back to cache or generated replacements

Vault cache adapters

The vault subsystem can use different storage backends for snapshot and runtime-entry caching.

MemoryVaultCache

Default in-memory cache. Good for:

• ephemeral single-tab usage
• tests
• flows where persistence across reloads is not needed

LocalStorageVaultCache

Persists cache entries in localStorage.

Good for:

• keeping cached snapshots across page reloads
• browser-only apps with small cache sizes

SessionStorageVaultCache

Persists cache entries in sessionStorage.

Good for:

• keeping cache for the current tab only
• dropping it automatically when the browser tab/session closes

IndexedDbVaultCache

Persists cache entries in IndexedDB.

Good for:

• larger cache footprints
• more durable browser storage
• apps that want async storage rather than synchronous Web Storage APIs

import {
  IndexedDbVaultCache,
  LocalStorageVaultCache,
  MemoryVaultCache,
  SessionStorageVaultCache,
} from '@secured-ai/core'

Vault crypto

WebCryptoVaultCrypto

Built-in crypto adapter for encrypting and decrypting persisted vault snapshots with browser Web Crypto.

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

The default implementation uses:

• PBKDF2 with SHA-256 for key derivation
• AES-GCM for encryption/decryption
• random salt and IV per encrypted payload

You usually do not need to construct this directly unless you are overriding the default crypto implementation in PrivacyVaultConfig.

Entry-level deobfuscation

deobfuscateWithVaultEntries()

Restores text directly from vault-style entries without using a PrivacyClient session.

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

const restored = deobfuscateWithVaultEntries(
  'PERSON_12 PERSON_1',
  [
    { original: 'Alice Example', replacement: 'PERSON_12', type: 'PERSON' },
    { original: 'Alice', replacement: 'PERSON_1', type: 'PERSON' },
  ],
)

This helper restores longer replacements first so shorter aliases do not clobber longer ones.

Options

interface VaultEntryDeobfuscateOptions {
  caseInsensitive?: boolean
  wordBoundaryTypes?: string[]
  partialNameTypes?: string[]
}

Use these options when:

• aliases should match case-insensitively
• some types must respect word boundaries
• partial person-name restoration should be attempted

Matching helpers

These helpers normalize and compare persisted entity records:

• canonicalizeVaultEntityType(type)
• normalizeVaultEntryKey(original, type)
• vaultEntityTypesMatch(left, right)
• vaultEntryMatchesEntity(entry, entity)

They are useful when your backend or surrounding systems use equivalent but differently named labels such as PER, PERSON_NAME, LOC, or ORGANIZATION.