@nationaldesignstudio/rampart 0.1.1

package/dist/src/guard.d.ts

@@ -0,0 +1,94 @@
+/**
+ * ChatGuard: per-conversation PII filter for wiring into a chat app.
+ *
+ *   const guard = await createGuard();
+ *   const safe = await guard.protect(userInput);
+ *   const reply = await llm(safe.text);
+ *   guard.reveal(reply);                    // non-streaming
+ *   stream.pipeThrough(guard.revealTransform()); // streaming
+ *
+ * The entity table lives only on the client; the real values never leave the
+ * device. Each guard keeps placeholder identity stable across every turn of a
+ * conversation.
+ *
+ *   user message
+ *     → heuristics (sync, structured PII)
+ *     → NER (optional, async, contextual PII)
+ *     → merge + default-deny policy (keep {city, state, zip})
+ *     → session table: replace with stable placeholders
+ *   assistant reply
+ *     → rehydrate placeholders → render to user
+ */
+import { type NerOptions } from "./ner/classifier";
+import { type PlaceholderAliases, type ScrubResult } from "./session";
+import { type PiiLabel, type Span } from "./types";
+/** An async contextual detector. Matches both the in-process and worker forms. */
+export type NerDetector = (text: string) => Promise<Span[]>;
+/**
+ * Default placeholder aliases. Empty: names are split into GIVEN_NAME/SURNAME
+ * and a household may share a surname, so each keeps its own typed token
+ * (`[GIVEN_NAME_1]`, `[SURNAME_1]`) rather than collapsing to a single `NAME`.
+ */
+export declare const DEFAULT_ALIASES: PlaceholderAliases;
+export interface GuardOptions {
+    /** Placeholder aliases. Defaults to `{}` — typed tokens like `[GIVEN_NAME_1]`. */
+    readonly aliases?: PlaceholderAliases;
+    /** Labels to preserve; defaults to `{CITY, STATE, ZIP_CODE}`. */
+    readonly keepLabels?: readonly PiiLabel[];
+    /**
+     * When `true`, skip the structured-PII premask before the model. Required for
+     * a model trained without prefilter (no-prefilter ablation) whose classes
+     * include SSN / CREDIT_CARD / IP_ADDRESS. Heuristic spans for those types
+     * still run as a safety net.
+     */
+    readonly noPrefilter?: boolean;
+    /** Pre-built NER detector. When set, `model` is ignored. */
+    readonly ner?: NerDetector;
+    /** When `true`, skip the classifier and run heuristics only. */
+    readonly heuristicsOnly?: boolean;
+    /**
+     * Hugging Face model id or local directory path (q4 ONNX). Defaults to
+     * {@link RAMPART_MODEL_ID}.
+     */
+    readonly model?: string;
+    /** Worker script URL. When set, NER runs off the main thread. */
+    readonly worker?: string | URL;
+    /** Backend. `"wasm"`/`"webgpu"` in browsers; `"cpu"` for Node. */
+    readonly device?: NerOptions["device"];
+    /** Spans below this score are discarded. */
+    readonly minScore?: number;
+}
+type ChatGuardConfig = Pick<GuardOptions, "ner" | "aliases" | "keepLabels" | "noPrefilter">;
+export declare class ChatGuard {
+    private readonly table;
+    private readonly ner?;
+    private readonly noPrefilter;
+    constructor(config?: ChatGuardConfig);
+    private detect;
+    /**
+     * Run this on the user's text *before* handing it to the AI SDK. Returns the
+     * placeholdered text to send plus the placeholders introduced this turn.
+     */
+    protect(text: string): Promise<ScrubResult>;
+    /** Restore real values in a complete (non-streaming) assistant reply. */
+    reveal(reply: string): string;
+    /**
+     * A Web Streams transform that reveals placeholders in a streamed reply,
+     * correctly handling placeholders split across chunks. Pipe an AI SDK
+     * `textStream` through it before rendering.
+     */
+    revealTransform(): TransformStream<string, string>;
+    /**
+     * Defense in depth: scrub the model's *output* before logging/persisting it,
+     * since a model can emit PII the user never typed. Returns placeholdered text.
+     */
+    protectReply(reply: string): Promise<ScrubResult>;
+}
+/**
+ * Build a conversation guard. Loads the Rampart classifier (q4 ONNX) by default.
+ * Pass `model` for a different Hugging Face id or local path, `heuristicsOnly:
+ * true` to skip NER, or `ner` to inject a custom detector.
+ */
+export declare function createGuard(options?: GuardOptions): Promise<ChatGuard>;
+export {};
+//# sourceMappingURL=guard.d.ts.map

package/dist/src/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAAkD,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInG,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAC1F,OAAO,EAAqB,KAAK,QAAQ,EAAE,KAAK,IAAI,EAAE,MAAM,SAAS,CAAC;AAEtE,kFAAkF;AAClF,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;AAE5D;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,kBAAuB,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,kFAAkF;IAClF,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IACtC,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC;IAC3B,gEAAgE;IAChE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,GAAG,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IACvC,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,KAAK,eAAe,GAAG,IAAI,CAAC,YAAY,EAAE,KAAK,GAAG,SAAS,GAAG,YAAY,GAAG,aAAa,CAAC,CAAC;AAE5F,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAU;gBAE1B,MAAM,GAAE,eAAoB;YAM1B,MAAM;IAiBpB;;;OAGG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAKjD,yEAAyE;IACzE,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAI7B;;;;OAIG;IACH,eAAe,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC;IAOlD;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAIxD;AAsBD;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,SAAS,CAAC,CAShF"}

package/dist/src/heuristics.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Heuristic detectors: the cheap, synchronous, zero-model first pass.
+ *
+ * Digit-bearing PII (SSN, card, phone, routing) is found over the *digit
+ * projection* (see normalize.ts) so every separator variant collapses to one
+ * rule: `888-88-8888`, `888 88 8888`, `888.88.8888`, and `888888888` all match.
+ * Text-shaped PII (email, URL, IP) is matched on the raw string where the
+ * structure lives in the punctuation.
+ */
+import type { Span } from "./types";
+/** Run all heuristic detectors over the raw input. Spans may overlap; the
+ * pipeline's merge step resolves conflicts before redaction. */
+export declare function detectHeuristics(raw: string): Span[];
+//# sourceMappingURL=heuristics.d.ts.map

package/dist/src/heuristics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heuristics.d.ts","sourceRoot":"","sources":["../../src/heuristics.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAY,IAAI,EAAE,MAAM,SAAS,CAAC;AA2H9C;gEACgE;AAChE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,CAKpD"}

package/dist/src/ner/classifier.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Contextual PII detection via a small token-classification model running in
+ * the browser (transformers.js → ONNX Runtime Web, wasm or WebGPU backend).
+ *
+ * This is the residual layer: it catches what the heuristics can't — people's
+ * names, organizations, and free-text identifiers — which is exactly the PII we
+ * never want in our logs. The model is intentionally tiny and int8-quantized so
+ * it loads once (cached in IndexedDB by the runtime) and runs on-device with no
+ * server round-trip and no shared queue to saturate.
+ *
+ * Label mapping: the fine-tuned model emits token-classification entity groups,
+ * which we map onto our {@link PiiLabel} set. CITY/STATE/ZIP_CODE are emitted
+ * too so the merge step can carry them through to the keep-set.
+ */
+import type { Span } from "../types";
+/** Minimal shape of a transformers.js token-classification result row. */
+interface RawEntity {
+    readonly entity_group?: string;
+    readonly entity?: string;
+    readonly score: number;
+    readonly start: number;
+    readonly end: number;
+    readonly word: string;
+}
+/** Counts the model tokens in a string, excluding the [CLS]/[SEP] specials. */
+export type TokenCounter = (text: string) => number;
+/**
+ * The callable returned by a token-classification pipeline. `countTokens` is
+ * attached when the classifier is backed by a real tokenizer (see
+ * {@link loadNerClassifier}); {@link detectNer} uses it to size windows by the
+ * model's token budget. Bare mocks may omit it, in which case detection runs the
+ * whole input as a single window.
+ */
+export interface TokenClassifier {
+    (text: string, options?: {
+        aggregation_strategy?: "simple" | "first" | "max";
+    }): Promise<RawEntity[]>;
+    countTokens?: TokenCounter;
+}
+/** The shipped Rampart token-classifier on Hugging Face (q4 ONNX only). */
+export declare const RAMPART_MODEL_ID = "nationaldesignstudio/rampart";
+export interface NerOptions {
+    /**
+     * Hugging Face model id or local directory path. Must be a token-classification
+     * ONNX export compatible with Rampart's label schema. Defaults to
+     * {@link RAMPART_MODEL_ID}.
+     */
+    readonly model?: string;
+    /** Backend. `"wasm"`/`"webgpu"` in browsers; `"cpu"` for Node (ORT). */
+    readonly device?: "wasm" | "webgpu" | "cpu";
+    /** Spans below this score are discarded. Low default → recall-biased. */
+    readonly minScore?: number;
+}
+/** Per-window content-token budget: the model max less specials and a safety margin. */
+export declare const NER_TOKEN_BUDGET: number;
+/**
+ * Tokens shared by consecutive NER windows. Long input slides a window of
+ * {@link NER_TOKEN_BUDGET} tokens; this overlap guarantees an entity landing on a
+ * window seam is still *wholly* inside a neighbouring window.
+ *
+ * The invariant: as long as the overlap is at least the longest entity we detect
+ * (names, orgs, street lines — all a handful of tokens), no entity is ever split
+ * across a boundary, so a window-edge name is never silently dropped. The generous
+ * margin over the longest entity also means a seam entity reappears deep inside its
+ * neighbour with ample context, which the classifier needs to label it confidently.
+ */
+export declare const NER_TOKEN_OVERLAP = 64;
+/**
+ * Lazily construct the token-classification pipeline. transformers.js is a peer
+ * dependency and a heavy import, so it is loaded on first use, not at module
+ * load — keeping the heuristic path dependency-free.
+ */
+export declare function loadNerClassifier(options?: NerOptions): Promise<TokenClassifier>;
+/**
+ * Detect contextual PII across the whole input, regardless of length.
+ *
+ * The model has a fixed token budget, so input longer than one window is scanned
+ * as a sliding window sized to {@link NER_TOKEN_BUDGET} *tokens* (measured by the
+ * classifier's own tokenizer) that overlaps its neighbour by {@link NER_TOKEN_OVERLAP}
+ * tokens. Each window's spans are shifted back into whole-text coordinates; because
+ * windows overlap, an entity on a seam is re-detected in both, so {@link mergeSpans}
+ * collapses the duplicates into the canonical disjoint set. Input that fits one
+ * window — or any classifier without a tokenizer, e.g. a bare test mock — takes a
+ * single-window fast path identical to scanning the text directly.
+ *
+ * Sizing by tokens rather than a char cap means a window holds exactly as much
+ * text as the model can attend to, and nothing past a fixed char count is silently
+ * dropped: the overlap keeps any entity from being split across a seam.
+ */
+export declare function detectNer(raw: string, classifier: TokenClassifier, minScore?: number): Promise<Span[]>;
+export {};
+//# sourceMappingURL=classifier.d.ts.map

package/dist/src/ner/classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifier.d.ts","sourceRoot":"","sources":["../../../src/ner/classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAY,IAAI,EAAE,MAAM,UAAU,CAAC;AAE/C,0EAA0E;AAC1E,UAAU,SAAS;IACjB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,+EAA+E;AAC/E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,oBAAoB,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;IACtG,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AA6BD,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,iCAAiC,CAAC;AAE/D,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAiBD,wFAAwF;AACxF,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAWpC;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,GAAE,UAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA0B1F;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,eAAe,EAC3B,QAAQ,GAAE,MAAiC,GAC1C,OAAO,CAAC,IAAI,EAAE,CAAC,CAoBjB"}

package/dist/src/ner/worker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Web Worker host for the NER classifier.
+ *
+ * Inference must not jank the chat UI, so the model lives on a worker thread.
+ * The main thread talks to it through {@link createWorkerClassifier}, which
+ * adapts the postMessage round-trip back into the {@link TokenClassifier}
+ * signature the pipeline expects — so the rest of the system is agnostic to
+ * whether detection runs on the main thread or off it.
+ *
+ * Bundle this file as the worker entry (it self-registers `onmessage`). The
+ * client is created on the main thread with `new Worker(new URL(...))`.
+ */
+import { type NerOptions } from "./classifier";
+interface InitMessage {
+    readonly kind: "init";
+    readonly options: NerOptions;
+}
+interface DetectMessage {
+    readonly kind: "detect";
+    readonly id: number;
+    readonly text: string;
+    readonly minScore?: number;
+}
+type InboundMessage = InitMessage | DetectMessage;
+type WorkerInboundEvent = {
+    data: InboundMessage;
+};
+export type WorkerMessagePort = {
+    onmessage: ((event: WorkerInboundEvent) => void) | null;
+    postMessage: (message: unknown) => void;
+};
+/** Register the worker message handler. Call from the worker entry module. */
+export declare function registerNerWorker(scope: WorkerMessagePort): void;
+/**
+ * Wrap a worker as a {@link TokenClassifier}-compatible async function. The
+ * detection contract is span-in/span-out, so callers use it exactly like the
+ * in-process classifier. Resolves once the worker reports `ready`.
+ */
+export declare function createWorkerClassifier(worker: WorkerMessagePort, options: NerOptions): {
+    ready: Promise<void>;
+    detect: (text: string, minScore?: number) => Promise<unknown>;
+};
+export {};
+//# sourceMappingURL=worker.d.ts.map

package/dist/src/ner/worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/ner/worker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAgC,KAAK,UAAU,EAAwB,MAAM,cAAc,CAAC;AAEnG,UAAU,WAAW;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;CAC9B;AACD,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AACD,KAAK,cAAc,GAAG,WAAW,GAAG,aAAa,CAAC;AAElD,KAAK,kBAAkB,GAAG;IACxB,IAAI,EAAE,cAAc,CAAC;CACtB,CAAC;AAMF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,CAAC,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACxD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACzC,CAAC;AAIF,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CA6BhE;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,UAAU,GAClB;IAAE,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CA6CzF"}