@secured-ai/core 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# @secured-ai/core
+
+Browser-first privacy tooling for detecting sensitive data, obfuscating it before it leaves the client, and restoring protected text with the original values when needed.
+
+## Install
+
+```sh
+npm install @secured-ai/core
+```
+
+## What it provides
+
+- `PrivacyClient` for local PII detection, obfuscation, restoration, text review, sessions, and vault-backed restoration.
+- Built-in detection engines for common sensitive data such as names, emails, phone numbers, addresses, account identifiers, government IDs, URLs, and custom patterns.
+- Browser file privacy helpers for supported documents and data files.
+- TypeScript types for scan results, detected entities, sessions, vault entries, and client configuration.
+
+## Basic usage
+
+```ts
+import { PrivacyClient } from '@secured-ai/core'
+
+const client = new PrivacyClient()
+await client.initialize()
+
+const result = await client.obfuscate('Email Jane at jane@example.com')
+
+console.log(result.processed)
+console.log(result.sessionId)
+
+const restored = await client.restore(result.processed, result.sessionId)
+console.log(restored.restored)
+```
+
+## Publishing contents
+
+The npm package is built from `dist` only. Source files, tests, coverage output, and source maps are not included in the published package.
+
+## Docs
+
+See the developer documentation at https://dev-docs.securedai.com/docs.

package/dist/index.d.ts

@@ -0,0 +1,529 @@
+declare const ENTITY_TYPES: readonly ["PERSON", "EMAIL", "PHONE", "SSN", "CREDIT_CARD", "CVV", "ORG", "GPE", "LOC", "ADDRESS", "ZIP_CODE", "DATE", "TAX_ID", "INVOICE_NUMBER", "REFERENCE_ID", "MEDICAL_ID", "INSURANCE_ID", "CASE_NUMBER", "LEGAL_CITATION", "DRIVER_LICENSE", "PASSPORT", "IP_ADDRESS", "MAC_ADDRESS", "URL", "ROUTING_NUMBER", "IBAN", "EIN", "ACCOUNT_NUMBER", "TIME", "NORP", "FAC", "PRODUCT", "EVENT", "WORK_OF_ART", "LAW", "LANGUAGE", "QUANTITY", "CARDINAL", "ORDINAL", "PERCENT", "MISC", "CREDIT_CARD_EXPIRY", "CUSTOM"];
+type EntityType = (typeof ENTITY_TYPES)[number];
+type DetectionSource = "regex-patterns" | "compromise-nlp" | "compromise-regex" | "huggingface" | "gliner" | "custom";
+interface SensitiveEntity {
+    text: string;
+    label?: string;
+    start: number;
+    end: number;
+    confidence: number;
+    type: EntityType;
+    source?: string;
+    fileId?: string;
+    fileName?: string;
+}
+interface ExtendedSensitiveEntity extends SensitiveEntity {
+    detectionSource: DetectionSource;
+    detectionMethod?: string;
+}
+interface DetectionResult {
+    entities: ExtendedSensitiveEntity[];
+    processingTime: number;
+    source: DetectionSource;
+}
+interface PrivacyScanResult {
+    entities: ExtendedSensitiveEntity[];
+    sensitiveEntities: SensitiveEntity[];
+    processingTime: number;
+    sourceStats: Record<DetectionSource, number>;
+    isClean: boolean;
+}
+interface SessionMapping {
+    id: string;
+    original: string;
+    replacement: string;
+    entityType: EntityType;
+    position: {
+        start: number;
+        end: number;
+    };
+    obfuscationMode?: ObfuscationMode | "custom";
+    replacementSource?: ReplacementSource;
+}
+interface PrivacySession {
+    sessionId: string;
+    mappings: SessionMapping[];
+    createdAt: Date;
+    processedText: string;
+    originalText: string;
+}
+interface SerializedPrivacySession {
+    sessionId: string;
+    mappings: SessionMapping[];
+    createdAt: string;
+    processedText: string;
+    originalText: string;
+}
+interface TextReviewOccurrence {
+    start: number;
+    end: number;
+    text: string;
+}
+interface TextReviewItem extends SensitiveEntity {
+    id: string;
+    replacement: string;
+    defaultReplacement: string;
+    obfuscationMode?: ObfuscationMode | "custom";
+    replacementSource?: ReplacementSource;
+    isRemoved: boolean;
+    isCustomAdded: boolean;
+    occurrences: TextReviewOccurrence[];
+}
+interface TextReview {
+    originalText: string;
+    items: TextReviewItem[];
+}
+interface FinalizedTextReview {
+    processedText: string;
+    entities: SensitiveEntity[];
+    mappings: SessionMapping[];
+    sessionId: string;
+    session: PrivacySession;
+    serializedSession: SerializedPrivacySession;
+    hasSensitiveData: boolean;
+}
+interface ObfuscationResult {
+    processed: string;
+    sessionId: string;
+    hasSensitiveData: boolean;
+}
+type ObfuscationMode = "detailed" | "neutral";
+type ReplacementSource = "generated" | "vault" | "thread" | "custom";
+interface ObfuscationOptions {
+    threadId?: string | null;
+    obfuscationMode?: ObfuscationMode;
+}
+interface TextReviewOptions {
+    obfuscationMode?: ObfuscationMode;
+    resolveReplacement?: (entity: SensitiveEntity) => string;
+}
+interface RestorationResult {
+    restored: string;
+    mappingsApplied: number;
+    success: boolean;
+}
+interface InitProgressEvent {
+    engine: string;
+    stage: "downloading" | "loading" | "ready";
+    percent: number;
+}
+interface InitProgress {
+    overall: number;
+    engines: Record<string, number>;
+}
+type PrivacyJobProgress = {
+    operation: "initialize";
+    event: InitProgressEvent;
+} | {
+    operation: "detect";
+    phase: "starting" | "running-engines" | "merging" | "done";
+    percent: number;
+    detail?: string;
+} | {
+    operation: "detectInFile";
+    phase: "starting" | "extracting-file" | "detecting" | "done";
+    percent: number;
+    detail?: string;
+} | {
+    operation: "obfuscateFile";
+    phase: "starting" | "extracting-file" | "resolving-replacements" | "rewriting-file" | "done";
+    percent: number;
+    detail?: string;
+};
+interface PrivacyJobProgressEvent {
+    requestId: string;
+    progress: PrivacyJobProgress;
+}
+interface CustomPattern {
+    name: string;
+    pattern: RegExp;
+    entityType: EntityType;
+    confidence?: number;
+}
+interface EngineConfig {
+    regex?: boolean;
+    nlp?: boolean;
+    ml?: boolean;
+    gliner?: boolean;
+    custom?: boolean;
+}
+interface ReplacementPoolConfig {
+    [entityType: string]: string[] | undefined;
+}
+interface PrivacyClientConfig {
+    engines?: EngineConfig;
+    sdkAccessToken?: string;
+    baseUrl?: string;
+    confidenceThreshold?: number;
+    maxProcessingTime?: number;
+    disableGLiNERChunking?: boolean;
+    replacementPools?: Partial<Record<EntityType, string[]>>;
+    debug?: boolean;
+    onInitProgress?: (event: InitProgressEvent) => void;
+    vault?: PrivacyVaultConfig;
+}
+interface FileProcessingResult {
+    entities: ExtendedSensitiveEntity[];
+    text: string;
+    processingTime: number;
+    fileType: SupportedFileType;
+}
+type SupportedFileType = "pdf" | "docx" | "xlsx" | "csv" | "txt" | "json" | "image";
+interface FileObfuscationOptions {
+    entities?: SensitiveEntity[];
+    extractedText?: string;
+}
+interface IDetectionEngine {
+    initialize(onProgress?: (event: InitProgressEvent) => void): Promise<void>;
+    detect(text: string): Promise<DetectionResult>;
+    isReady(): boolean;
+    getName(): string;
+}
+interface IEntityValidator {
+    validate(entityType: EntityType, text: string): boolean;
+}
+interface VaultEntry {
+    original: string;
+    replacement: string;
+    type: string;
+}
+interface EncryptedVaultPayload {
+    saltB64: string;
+    ivB64: string;
+    ciphertextB64: string;
+}
+interface EncryptedVaultSnapshot {
+    scope: "global" | "thread";
+    threadId?: string;
+    version: string;
+    updatedAt: string;
+    payload: EncryptedVaultPayload;
+}
+interface VaultSnapshot {
+    scope: "global" | "thread";
+    threadId?: string;
+    entries: VaultEntry[];
+    version: string;
+    updatedAt: string;
+}
+interface VaultSnapshotState extends VaultSnapshot {
+    fetchedAt: string;
+    isStale: boolean;
+}
+interface VaultRepositoryRequestContext {
+    cacheNamespace: string | null;
+}
+interface VaultRepository {
+    getGlobalSnapshot(context: VaultRepositoryRequestContext): Promise<EncryptedVaultSnapshot | null>;
+    getThreadSnapshot?(threadId: string, context: VaultRepositoryRequestContext): Promise<EncryptedVaultSnapshot | null>;
+}
+interface VaultCrypto {
+    encryptEntries(entries: VaultEntry[], masterKey: string): Promise<EncryptedVaultPayload>;
+    decryptEntries(payload: EncryptedVaultPayload, masterKey: string): Promise<VaultEntry[]>;
+}
+interface VaultCache {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+type RuntimeValue<T> = T | (() => Promise<T | null>);
+interface PrivacyVaultConfig {
+    repository: VaultRepository;
+    masterKey: RuntimeValue<string>;
+    cache?: VaultCache;
+    cacheNamespace?: RuntimeValue<string>;
+    crypto?: VaultCrypto;
+}
+interface VaultStatus {
+    isEnabled: boolean;
+    isInitialized: boolean;
+    activeThreadId: string | null;
+    cacheNamespace: string | null;
+    hasGlobalSnapshot: boolean;
+    isGlobalSnapshotStale: boolean;
+}
+interface VaultResolveOptions {
+    threadId?: string | null;
+}
+
+declare function deobfuscate(content: string, mappings: SessionMapping[]): string;
+
+declare class VaultManager {
+    private readonly enabled;
+    private readonly cache;
+    private readonly crypto;
+    private readonly repository;
+    private readonly masterKeyInput;
+    private readonly cacheNamespaceInput?;
+    private globalSnapshot;
+    private readonly threadSnapshots;
+    private readonly runtimeThreadEntries;
+    private activeThreadId;
+    private pendingEntries;
+    private resolvedNamespace;
+    private resolvedMasterKey;
+    private initialized;
+    constructor(config?: PrivacyVaultConfig | null);
+    initialize(): Promise<void>;
+    refreshContext(): Promise<void>;
+    clearCache(): Promise<void>;
+    setThreadContext(threadId: string | null): Promise<void>;
+    getGlobalSnapshot(): VaultSnapshotState | null;
+    getThreadSnapshot(threadId: string): VaultSnapshotState | null;
+    loadThreadSnapshot(threadId: string): Promise<VaultSnapshotState | null>;
+    getRuntimeThreadEntries(threadId: string): VaultEntry[];
+    getPendingEntries(): VaultEntry[];
+    getStatus(): VaultStatus;
+    resolveReplacement(entity: SensitiveEntity, options?: VaultResolveOptions): Promise<VaultEntry | null>;
+    rememberGeneratedEntry(entity: SensitiveEntity, replacement: string, options?: VaultResolveOptions): Promise<void>;
+    isReplacementInUse(replacement: string, options?: VaultResolveOptions): Promise<boolean>;
+    deobfuscate(text: string, options?: VaultResolveOptions): Promise<string>;
+    private ensureInitialized;
+    private loadGlobalSnapshot;
+    private loadThreadSnapshotInternal;
+    private loadRuntimeThreadEntries;
+    private loadPendingEntries;
+    private getCachedSnapshot;
+    private resolveMasterKey;
+    private getCacheKey;
+    private getThreadCacheKey;
+    private getRuntimeThreadCacheKey;
+    private getPendingCacheKey;
+    private getRepositoryContext;
+    private findEntry;
+    private deserializeEntries;
+    private upsertEntry;
+    private migratePendingEntries;
+    private upsertEntries;
+    private getEntriesForScope;
+    private getEntriesByPrecedence;
+}
+
+declare class PrivacyClient {
+    private readonly config;
+    private readonly engines;
+    private readonly customEngine;
+    private readonly sessionManager;
+    private readonly replacementPool;
+    private readonly filePrivacyService;
+    private readonly obfuscatedFileCreator;
+    private readonly logger;
+    private readonly vaultManager;
+    private readonly initProgress;
+    private readonly workerBridge;
+    private readonly workerProgressListeners;
+    private workerState;
+    private readonly workerFailureTimestamps;
+    private workerFallbackToLocal;
+    private slowEngineInitTimer;
+    private slowEngineInitInFlight;
+    private readonly isFirstPartyBrowserClient;
+    private initialized;
+    private initializing;
+    constructor(config?: PrivacyClientConfig);
+    initialize(): Promise<void>;
+    private verifyBrowserSdkAccessToken;
+    private bindVaultRepositoryBaseUrl;
+    detect(text: string): Promise<PrivacyScanResult>;
+    private detectLocally;
+    private tryDetectWithWorker;
+    private tryDetectInFileWithWorker;
+    private tryObfuscateFileWithWorker;
+    obfuscate(text: string, options?: ObfuscationOptions): Promise<ObfuscationResult>;
+    createTextReview(text: string, entities: SensitiveEntity[], optionsOrResolveReplacement?: TextReviewOptions | ((entity: SensitiveEntity) => string)): TextReview;
+    setTextReviewReplacement(review: TextReview, itemId: string, replacement: string): TextReview;
+    setTextReviewItemMode(review: TextReview, itemId: string, mode: NonNullable<SessionMapping["obfuscationMode"]>): TextReview;
+    removeTextReviewItem(review: TextReview, itemId: string): TextReview;
+    restoreTextReviewItem(review: TextReview, itemId: string): TextReview;
+    addTextReviewEntity(review: TextReview, entity: SensitiveEntity, replacement: string): TextReview;
+    previewTextReview(review: TextReview): Omit<FinalizedTextReview, "sessionId" | "session" | "serializedSession">;
+    finalizeTextReview(review: TextReview): FinalizedTextReview;
+    createSessionFromMappings(originalText: string, processedText: string, mappings: SessionMapping[]): PrivacySession;
+    get vault(): VaultManager;
+    subscribeToJobProgress(listener: (event: PrivacyJobProgressEvent) => void): () => void;
+    setThreadContext(threadId: string | null): Promise<void>;
+    refreshVaultContext(): Promise<void>;
+    clearVaultCache(): Promise<void>;
+    private createObfuscationResult;
+    private getGeneratedReplacement;
+    private getEntityOccurrenceKey;
+    private getReplacementKeysByOccurrence;
+    private getNeutralReplacementForReviewItem;
+    private resolveFileText;
+    restore(text: string, sessionId: string): Promise<RestorationResult>;
+    detectInFile(file: File): Promise<FileProcessingResult>;
+    private detectInFileLocally;
+    obfuscateFile(file: File, entitiesOrOptions?: SensitiveEntity[] | FileObfuscationOptions): Promise<Blob>;
+    getSession(sessionId: string): PrivacySession | undefined;
+    exportSession(sessionId: string): SerializedPrivacySession | undefined;
+    importSession(session: PrivacySession | SerializedPrivacySession): PrivacySession;
+    getSessions(): PrivacySession[];
+    clearSession(sessionId: string): void;
+    clearAllSessions(): void;
+    addPattern(pattern: CustomPattern): void;
+    removePattern(name: string): boolean;
+    get isReady(): boolean;
+    get isFullyReady(): boolean;
+    get readyEngines(): string[];
+    getInitProgress(): InitProgress;
+    clearModelCache(): void;
+    private runWithTimeout;
+    private detectWithChunking;
+    private initializeEngine;
+    private scheduleSlowEnginesForBackgroundInitialization;
+    private getPendingSlowEngines;
+    private handleInitProgress;
+    private handleWorkerProgress;
+    private shouldUseWorker;
+    private handleWorkerExecutionFailure;
+    private syncWorkerState;
+    private getEngineNames;
+    private getWorkerClientConfig;
+    private escapeRegex;
+    private restoreAmbiguousOccurrences;
+    private hasAmbiguousReplacements;
+    private wasMappingApplied;
+    private emptyResult;
+}
+
+declare function createTextReview(text: string, entities: SensitiveEntity[], resolveReplacement: (entity: SensitiveEntity) => string): TextReview;
+declare function setTextReviewReplacement(review: TextReview, itemId: string, replacement: string): TextReview;
+declare function setTextReviewItemMode(review: TextReview, itemId: string, mode: TextReviewItem['obfuscationMode'], replacement: string): TextReview;
+declare function removeTextReviewItem(review: TextReview, itemId: string): TextReview;
+declare function restoreTextReviewItem(review: TextReview, itemId: string): TextReview;
+declare function addTextReviewEntity(review: TextReview, entity: SensitiveEntity, replacement: string): TextReview;
+declare function finalizeTextReview(review: TextReview): {
+    processedText: string;
+    entities: SensitiveEntity[];
+    mappings: SessionMapping[];
+    hasSensitiveData: boolean;
+};
+
+interface EntityIdentityInput {
+    text: string;
+    type: EntityType | string;
+}
+interface EntityIdentityGroup<T extends EntityIdentityInput> {
+    representative: T;
+    entities: T[];
+}
+declare function getEntityIdentityKey(entity: EntityIdentityInput): string;
+declare function groupEntitiesByIdentity<T extends EntityIdentityInput>(entities: T[]): Array<EntityIdentityGroup<T>>;
+declare function entitiesShareIdentity(left: EntityIdentityInput, right: EntityIdentityInput): boolean;
+declare function normalizeEntityText(text: string): string;
+declare function canonicalizeEntityType(type: EntityType | string): string;
+declare function isFuzzyEligibleType(type: EntityType | string): boolean;
+
+interface MatchResult {
+    matched: boolean;
+    confidence: number;
+    matchType: 'exact' | 'case-insensitive' | 'fuzzy' | 'none';
+    suggestion?: string;
+}
+interface MatchConfig {
+    minConfidence: number;
+    maxEditDistance: number;
+    enableCaseInsensitive: boolean;
+    enableFuzzyMatching: boolean;
+}
+declare class StringMatcher {
+    private readonly config;
+    constructor(config?: Partial<MatchConfig>);
+    match(target: string, candidate: string): MatchResult;
+    private fuzzyMatch;
+    private levenshteinDistance;
+    private calculateLevenshteinDistance;
+    findBestMatch(target: string, candidates: string[]): MatchResult & {
+        candidate?: string;
+    };
+    similarity(str1: string, str2: string): number;
+    isLikelySameEntity(original: string, candidate: string): boolean;
+}
+declare const defaultStringMatcher: StringMatcher;
+declare const strictStringMatcher: StringMatcher;
+declare const lenientStringMatcher: StringMatcher;
+
+declare class MemoryVaultCache implements VaultCache {
+    private readonly records;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+type FetchLike = typeof fetch;
+interface DefaultVaultRepositoryOptions {
+    getAuthToken?: RuntimeValue<string | null>;
+    fetch?: FetchLike;
+    includeCredentials?: boolean;
+}
+declare class DefaultVaultRepository implements VaultRepository {
+    private baseUrl;
+    private readonly fetchImpl;
+    private readonly getAuthToken?;
+    private readonly includeCredentials;
+    constructor(options: DefaultVaultRepositoryOptions);
+    __setSdkBaseUrl(baseUrl: string): void;
+    getGlobalSnapshot(_context: VaultRepositoryRequestContext): Promise<EncryptedVaultSnapshot | null>;
+    getThreadSnapshot(threadId: string, _context: VaultRepositoryRequestContext): Promise<EncryptedVaultSnapshot | null>;
+    private request;
+}
+
+declare class IndexedDbVaultCache implements VaultCache {
+    private readonly dbName;
+    private readonly storeName;
+    private readonly factory;
+    constructor(dbName?: string, storeName?: string, factory?: IDBFactory);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    private openDatabase;
+}
+
+interface VaultEntryDeobfuscateOptions {
+    caseInsensitive?: boolean;
+    wordBoundaryTypes?: string[];
+    partialNameTypes?: string[];
+}
+declare function deobfuscateWithVaultEntries(text: string, entries: Array<Pick<VaultEntry, 'original' | 'replacement' | 'type'>>, options?: VaultEntryDeobfuscateOptions): string;
+
+declare function canonicalizeVaultEntityType(type: string): string;
+declare function vaultEntityTypesMatch(left: string, right: string): boolean;
+declare function normalizeVaultEntryKey(original: string, type: string): string;
+declare function vaultEntryMatchesEntity(entry: Pick<VaultEntry, 'original' | 'type'>, entity: Pick<SensitiveEntity, 'text'> & {
+    type: string;
+}): boolean;
+
+declare class WebCryptoVaultCrypto implements VaultCrypto {
+    encryptEntries(entries: VaultEntry[], masterKey: string): Promise<EncryptedVaultPayload>;
+    decryptEntries(payload: EncryptedVaultPayload, masterKey: string): Promise<VaultEntry[]>;
+}
+
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+declare class WebStorageVaultCache implements VaultCache {
+    private readonly storage;
+    constructor(storage: StorageLike);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+}
+declare class LocalStorageVaultCache extends WebStorageVaultCache {
+    constructor(storage?: StorageLike);
+}
+declare class SessionStorageVaultCache extends WebStorageVaultCache {
+    constructor(storage?: StorageLike);
+}
+
+declare function resolveRuntimeValue<T>(value: RuntimeValue<T> | null | undefined): Promise<T | null>;
+
+declare const version = "0.1.0";
+
+export { type CustomPattern, DefaultVaultRepository, type DefaultVaultRepositoryOptions, type DetectionResult, type DetectionSource, ENTITY_TYPES, type EncryptedVaultPayload, type EncryptedVaultSnapshot, type EngineConfig, type EntityIdentityGroup, type EntityIdentityInput, type EntityType, type ExtendedSensitiveEntity, type FileObfuscationOptions, type FileProcessingResult, type FinalizedTextReview, type IDetectionEngine, type IEntityValidator, IndexedDbVaultCache, type InitProgress, type InitProgressEvent, LocalStorageVaultCache, type MatchConfig, type MatchResult, MemoryVaultCache, type ObfuscationMode, type ObfuscationOptions, type ObfuscationResult, PrivacyClient, type PrivacyClientConfig, type PrivacyJobProgress, type PrivacyJobProgressEvent, type PrivacyScanResult, type PrivacySession, type PrivacyVaultConfig, type ReplacementPoolConfig, type ReplacementSource, type RestorationResult, type RuntimeValue, type SensitiveEntity, type SerializedPrivacySession, type SessionMapping, SessionStorageVaultCache, type StorageLike, StringMatcher, type SupportedFileType, type TextReview, type TextReviewItem, type TextReviewOccurrence, type TextReviewOptions, type VaultCache, type VaultCrypto, type VaultEntry, type VaultEntryDeobfuscateOptions, VaultManager, type VaultRepository, type VaultRepositoryRequestContext, type VaultResolveOptions, type VaultSnapshot, type VaultSnapshotState, type VaultStatus, WebCryptoVaultCrypto, WebStorageVaultCache, addTextReviewEntity, canonicalizeEntityType, canonicalizeVaultEntityType, createTextReview, defaultStringMatcher, deobfuscate, deobfuscateWithVaultEntries, entitiesShareIdentity, finalizeTextReview, getEntityIdentityKey, groupEntitiesByIdentity, isFuzzyEligibleType, lenientStringMatcher, normalizeEntityText, normalizeVaultEntryKey, removeTextReviewItem, resolveRuntimeValue, restoreTextReviewItem, setTextReviewItemMode, setTextReviewReplacement, strictStringMatcher, vaultEntityTypesMatch, vaultEntryMatchesEntity, version };