@abhishekvardanbotta/mask 0.0.0-stage → 0.1.0

package/dist/privacy.d.ts

@@ -0,0 +1,152 @@
+import { type CompiledPolicy } from "./policy.js";
+import { type AuditEvent, type Detection, type EntityType, type PolicyConfig, type PrivacySummary, type ProtectOptions, type RestoreOptions } from "./types.js";
+import { type VaultStore } from "./vault.js";
+export interface PrivacyOptions extends PolicyConfig {
+    /**
+     * 256-bit master key (32 bytes, or base64 of 32 bytes). Omitted, a random key is generated per process: tokens then
+     * cannot be restored after a restart, which is the right default for an in-memory vault. Set it (for example from
+     * `KILN_PRIVACY_KEY`) when the store outlives the process.
+     */
+    key?: string | Uint8Array;
+    /** Where encrypted vault records live. Default: in-memory, process-lifetime. */
+    store?: VaultStore;
+    /** How long an idle scope stays restorable, in ms. Default one hour. Records get a matching `expiresAt`. */
+    retentionMs?: number;
+    /**
+     * How token ids look.
+     * - `"sequential"` (default): `[EMAIL_1]`, `[PERSON_2]` — numbered per type within the scope. Small models copy
+     *   these reliably; with random ids they were measured to splice one token's id onto another's type. The number says
+     *   nothing about the value, and scopes stay unlinkable, but ids are guessable within a scope.
+     * - `"opaque"`: `[EMAIL_3f9a1c0b7e]` — 40 bits of the keyed HMAC, so a model can only reference tokens it was shown.
+     */
+    tokenStyle?: "sequential" | "opaque";
+}
+interface Entry {
+    token: string;
+    type: EntityType;
+    classification: "PII" | "SENSITIVE";
+    value: string;
+    kind: "string" | "number";
+    fp: string;
+}
+/** Everything one scope knows: shared by every policy view of that scope. */
+declare class ScopeState {
+    readonly scope: string;
+    readonly byToken: Map<string, Entry>;
+    readonly byFingerprint: Map<string, string>;
+    /** Exact plaintexts already tokenized in this scope -> token, so later free-text mentions are caught too. */
+    readonly known: Map<string, string>;
+    knownVersion: number;
+    /** Last sequential id issued per type. */
+    readonly sequence: Map<string, number>;
+    private knownRegexCache?;
+    readonly pending: Promise<void>[];
+    readonly audit: AuditEvent[];
+    blocked: number;
+    restored: number;
+    denied: number;
+    lastUsed: number;
+    constructor(scope: string);
+    record(event: Omit<AuditEvent, "at">): void;
+    /** Two alternations over the known plaintexts: case-sensitive, and case-folded for emails. */
+    knownRegexes(): {
+        exact?: RegExp;
+        folded?: RegExp;
+        foldedMap: Map<string, string>;
+    };
+}
+/**
+ * The privacy engine: holds the keys, the vault store and the per-scope state. Create one per process (or per
+ * tenant, if tenants need separate keys) and open a session per conversation, run or request.
+ */
+export declare class Privacy {
+    private readonly keys;
+    private readonly store;
+    private readonly retentionMs;
+    private readonly tokenStyle;
+    private readonly baseConfig;
+    private readonly basePolicy;
+    private readonly scopes;
+    private readonly hydrating;
+    constructor(options?: PrivacyOptions);
+    /** Compiles a policy layered over this engine's own. Compile once and reuse it across sessions. */
+    policy(overrides?: PolicyConfig): CompiledPolicy;
+    /**
+     * A session over `scope`, without loading previously persisted records. Tokens are deterministic within a scope
+     * and unlinkable across scopes. Use `open()` instead when the scope may have records from an earlier process.
+     */
+    session(scope: string, policy?: CompiledPolicy | PolicyConfig): PrivacySession;
+    /** Like `session()`, but first loads and decrypts the scope's persisted records from the store. */
+    open(scope: string, policy?: CompiledPolicy | PolicyConfig): Promise<PrivacySession>;
+    /** Forgets a scope: drops its in-memory state and deletes its records from the store. Its tokens become unrestorable. */
+    destroy(scope: string): Promise<void>;
+    /** Runs detection only — what would be found in `text`, with confidences — without tokenizing anything. */
+    detect(text: string, policy?: CompiledPolicy | PolicyConfig): Detection[];
+    /** @internal */
+    tokenFor(state: ScopeState, type: EntityType, value: string, classification: "PII" | "SENSITIVE", kind: "string" | "number"): string;
+    private remember;
+    private persist;
+    private hydrate;
+    private resolvePolicy;
+    /** Drops in-memory scopes idle for longer than the retention period. Their store records expire on the same clock. */
+    private sweep;
+}
+export type ProtectResult<T> = T extends string ? string : unknown;
+/**
+ * A view over one scope, under one policy. `protect` replaces personal data with tokens before data leaves your
+ * trust boundary; `restore` puts it back, for exactly the types the principal is granted.
+ */
+export declare class PrivacySession {
+    private readonly engine;
+    private readonly state;
+    readonly policy: CompiledPolicy;
+    private readonly memo;
+    /** @internal — use `Privacy.session()` / `Privacy.open()`. */
+    constructor(engine: Privacy, state: ScopeState, policy: CompiledPolicy);
+    get scope(): string;
+    /**
+     * Replaces personal data in `value` (a string, or any JSON-shaped value) with vault tokens. Field classifications
+     * come from `options.schema`, the policy's `fields`, and key names; free text runs through every detector,
+     * including asynchronous ones. Idempotent: protecting already-protected data changes nothing.
+     */
+    protect<T>(value: T, options?: ProtectOptions): Promise<T extends string ? string : unknown>;
+    /** `protect()` without asynchronous detectors — for hot paths such as log lines. Values they found earlier in this scope are still caught. */
+    protectSync<T>(value: T, options?: ProtectOptions): T extends string ? string : unknown;
+    /**
+     * Replaces tokens in `value` with the original values the principal may see. Unknown tokens (another scope's, or
+     * made up by a model) are left exactly as they are. BLOCKed values were never stored and cannot come back.
+     */
+    restore<T>(value: T, options?: RestoreOptions): T extends string ? string : unknown;
+    /** Whether `text` contains a token issued in this scope. */
+    hasTokens(text: string): boolean;
+    /** Restores a streamed response chunk by chunk, holding back a possible partial token at each chunk's end. */
+    streamRestorer(options?: RestoreOptions): StreamRestorer;
+    /** Waits for vault writes to reach the store; rejects if any failed. */
+    flush(): Promise<void>;
+    summary(): PrivacySummary;
+    /** What happened in this scope — tokenizations, blocks, restorations, denials. Holds tokens and types, never plaintext. */
+    audit(): AuditEvent[];
+    private walk;
+    private fieldClass;
+    private classificationOf;
+    /** Tokenizes a field's entire value as one entity. */
+    private whole;
+    private block;
+    private protectText;
+    private restoreValue;
+    private restoreText;
+}
+/**
+ * Restores a stream without ever emitting half a token: text after an unclosed `[`, or a trailing run of token
+ * characters, is held back until the next chunk (or `flush()`) decides it.
+ */
+export declare class StreamRestorer {
+    private readonly restoreText;
+    private buffer;
+    constructor(restoreText: (text: string) => string);
+    push(delta: string): string;
+    flush(): string;
+}
+/** Creates a privacy engine. See `PrivacyOptions`. */
+export declare function createPrivacy(options?: PrivacyOptions): Privacy;
+export {};