@redact-secret/core 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Omiologic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @redact-secret/core
+
+Deterministic secret detection and redaction for browser and server
+JavaScript/TypeScript applications.
+
+One typed API, two artifacts: the package's `exports` map selects the Node
+N-API addon on Node.js and the browser WebAssembly build everywhere else
+(`decision-define-runtime-bindings`). Every built-in detector runs in the Rust
+core, so both runtimes see the same findings for the same input.
+
+## Install
+
+```bash
+npm install @redact-secret/core
+```
+
+These registry instructions apply after an approved release is published.
+Node.js 20, 22, and 24 are supported, on glibc Linux, macOS, and Windows
+(x64 and arm64). npm does not ship a musl/Alpine addon. Browser applications
+need ES2022 and WebAssembly support. The package is ESM only.
+
+See the [JavaScript guide](https://github.com/redact-secret/redact-secret/blob/main/docs/guides/javascript.md)
+for browser asset loading and troubleshooting.
+
+## Initialize once, then work synchronously
+
+Every runtime requires one successful `await initialize()` before any
+synchronous operation. On Node the underlying setup has nothing to await, but
+the call stays part of the contract so the usage model does not vary by
+runtime. It is idempotent, so any number of call sites may await it; a failed
+attempt is not cached and may be retried.
+
+```ts
+import { initialize, scanAndRedact } from "@redact-secret/core";
+
+await initialize();
+
+const { text, findings } = scanAndRedact("API_KEY=SYNTHETIC_REVOKED_VALUE");
+
+if (findings.some((finding) => finding.action === "block")) {
+  throw new Error("Blocked sensitive input");
+}
+
+console.log(text);
+```
+
+Calling a synchronous operation first throws `SecretScanError` with code
+`NOT_INITIALIZED`, without inspecting the input.
+
+## Scan, redact, or both
+
+```ts
+import { initialize, redact, scan } from "@redact-secret/core";
+
+await initialize();
+
+const input = "API_KEY=SYNTHETIC_REVOKED_VALUE";
+const findings = scan(input);
+const redacted = redact(input, findings);
+```
+
+`scanAndRedact` does the same in one call, so the text and the findings cannot
+disagree. `redact` expects the findings `scan` returned for that same input.
+
+Every finding is frozen and carries only safe metadata — id, type, detector,
+confidence, action, and a range. It never carries the matched value.
+
+## Offsets are UTF-16 code units
+
+`start` and `end` index the JavaScript string you passed in, so
+`input.slice(start, end)` selects exactly the matched span. The exported
+`RANGE_UNIT` states this, and the Rust core's UTF-8 byte offsets are converted
+by each binding without changing the selected span.
+
+```ts
+import { initialize, RANGE_UNIT, scan } from "@redact-secret/core";
+
+await initialize();
+
+const input = "🔑 API_KEY=SYNTHETIC_REVOKED_VALUE";
+const [finding] = scan(input);
+
+if (finding !== undefined) {
+  console.log(RANGE_UNIT, finding.start, finding.end);
+  // Do not log input.slice(finding.start, finding.end): it is plaintext.
+}
+```
+
+## Custom policy and placeholder formatter
+
+The first stable extension surface is a policy and a placeholder formatter.
+Both receive safe metadata only, never the input or a matched value. Custom
+detector callbacks are not part of this API.
+
+```ts
+import {
+  initialize,
+  scanAndRedact,
+  typedPlaceholderFormatter,
+} from "@redact-secret/core";
+import type { SecretPolicy } from "@redact-secret/core";
+
+await initialize();
+
+const policy: SecretPolicy = {
+  evaluate: (finding) => (finding.confidence === "high" ? "block" : "warn"),
+};
+
+const result = scanAndRedact("api_key=SYNTHETIC_REVOKED_VALUE", {
+  policy,
+  placeholderFormatter: typedPlaceholderFormatter,
+});
+```
+
+Omit `policy` to use the built-in policy, which runs in Rust. Pass
+`defaultPlaceholderFormatter` to name the built-in placeholder format
+(`<SECRET_1>`, `<SECRET_2>`, ...) explicitly; `typedPlaceholderFormatter`
+names the finding type instead (`<JWT_1>`).
+
+## Incremental and stream availability
+
+The current Node and WebAssembly artifacts do not build incremental sessions.
+After initialization, `createIncrementalSanitizer`, `createNodeStreamSanitizer`,
+and `createWebStreamSanitizer` fail with `INCREMENTAL_UNAVAILABLE` when using
+these artifacts. Whole-input operations remain supported.
+
+The session types and stream subpaths are exported contracts, not evidence of
+runtime support. Adapter constructors accept a supplied session, but the
+package cannot create one with either current artifact. Use bounded whole-input
+scanning, or use Python, Rust, or CLI streaming. Do not scan chunks independently:
+a credential may cross a chunk boundary.
+
+See the [streaming guide](https://github.com/redact-secret/redact-secret/blob/main/docs/guides/streaming.md).
+
+## Errors
+
+Every failure is a `SecretScanError` carrying nothing but a fixed `code` and
+its fixed message — never the input, a matched value, a placeholder, or a
+failing callback's own message.
+
+```ts
+import { initialize, scan, SecretScanError } from "@redact-secret/core";
+import type { SecretScanErrorCode } from "@redact-secret/core";
+
+try {
+  await initialize();
+  scan("API_KEY=SYNTHETIC_REVOKED_VALUE");
+} catch (error) {
+  if (error instanceof SecretScanError) {
+    const code: SecretScanErrorCode = error.code;
+    console.error(code);
+  }
+}
+```
+
+`NOT_INITIALIZED` and `INITIALIZATION_FAILED` come from the binding layer,
+`INVALID_CHUNK` and `INVALID_UTF8` from the stream adapters,
+`UNPAIRED_SURROGATE` from this package's own input check — a JavaScript
+string may contain a lone UTF-16 surrogate, which has no UTF-8
+representation, so `scan`, `redact`, `scanAndRedact`, and an incremental
+sanitizer's `append` all reject one with this fixed code before it reaches
+either binding, identically on Node.js and in the browser — and
+`INCREMENTAL_UNAVAILABLE` from both current runtime adapters. Core failures
+are mapped to the same fixed error vocabulary.
+
+## Public API
+
+Runtime values: `initialize`, `scan`, `redact`, `scanAndRedact`,
+`createIncrementalSanitizer`, `defaultPlaceholderFormatter`,
+`typedPlaceholderFormatter`, `SecretScanError`, `RANGE_UNIT`, `VERSION`.
+
+Types: `DetectedSecretFinding`, `SecretFinding`, `SecretAction`,
+`SecretConfidence`, `SecretPolicy`, `PolicyContext`, `PlaceholderFormatter`,
+`PlaceholderContext`, `ScanOptions`, `RedactOptions`, `ScanAndRedactOptions`,
+`ScanResult`, `IncrementalSanitizer`, `IncrementalSanitizerOptions`,
+`IncrementalSanitizerResult`, `IncrementalSanitizerState`,
+`IncrementalLimits`, `IncrementalSecretPolicy`, `IncrementalPolicyContext`,
+`RangeUnit`, `SecretScanErrorCode`.
+
+Stream subpaths: `@redact-secret/core/node-stream` exports
+`createNodeStreamSanitizer`, `NodeStreamSanitizer`, and `SecretScanError`;
+`@redact-secret/core/web-stream` exports `createWebStreamSanitizer`,
+`WebStreamSanitizer`, and `SecretScanError`.
+
+The root export and those two stream subpaths are the executable public API.
+`@redact-secret/core/package.json` also exposes package metadata. Internal
+modules are unreachable through the `exports` map. `VERSION` is
+the shared product version; the Rust crate, this package, the Python package,
+and the CLI are released in lockstep
+(`decision-release-bindings-in-lockstep`), and `initialize()` refuses an
+artifact that reports a different one.
+
+## Security
+
+Client-side scanning is preventive UX; server-side scanning is the
+authoritative enforcement boundary. See
+[SECURITY.md](https://github.com/redact-secret/redact-secret/blob/main/SECURITY.md)
+for the security model and private vulnerability reporting.
+
+## License
+
+[MIT](https://github.com/redact-secret/redact-secret/blob/main/LICENSE)

package/dist/adapters/node-stream.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The Node.js stream adapter: a byte-to-byte `Transform` over one incremental
+ * session (`decision-define-runtime-bindings`).
+ *
+ * This module is reached only through the package's `./node-stream` subpath.
+ * It is the one published module that imports `node:stream`; the root export
+ * and `./web-stream` never resolve a Node-only module, so a browser bundle
+ * that uses them pulls none of this in.
+ *
+ * ```ts
+ * await initialize();
+ * await pipeline(source, createNodeStreamSanitizer({ limits }), destination);
+ * ```
+ *
+ * Backpressure, error propagation, and teardown are Node's own: the transform
+ * pushes into its readable side and lets the stream machinery stall the
+ * producer, and `_destroy` — which Node runs for `destroy()`, for a failed
+ * `pipeline`, and for a downstream error alike — aborts the session so the
+ * plaintext it was still deciding about is discarded rather than flushed.
+ */
+import { Transform } from "node:stream";
+import type { TransformCallback } from "node:stream";
+import type { IncrementalSanitizer, IncrementalSanitizerOptions, SecretFinding } from "../types.js";
+/** A byte-to-byte Node transform backed by one incremental session. */
+export declare class NodeStreamSanitizer extends Transform {
+    #private;
+    /**
+     * Wraps `session`, which this transform owns: it is finalized when the
+     * stream ends normally and aborted on every other exit.
+     */
+    constructor(session: IncrementalSanitizer);
+    /**
+     * Every finding the session has finalized so far, frozen, with absolute
+     * UTF-16 offsets into the logical whole-stream input. It stays empty when
+     * the stream is destroyed before anything settles.
+     */
+    get findings(): readonly SecretFinding[];
+    _transform(chunk: Uint8Array, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+    _destroy(error: Error | null, callback: (error?: Error | null) => void): void;
+}
+/**
+ * Opens one incremental session and wraps it in a Node transform.
+ *
+ * Requires a successful `await initialize()`, like every other synchronous
+ * operation in this package; it throws `NOT_INITIALIZED` otherwise.
+ */
+export declare function createNodeStreamSanitizer(options: IncrementalSanitizerOptions): NodeStreamSanitizer;
+export { SecretScanError } from "../errors.js";
+export type { SecretScanErrorCode } from "../errors.js";
+export type { IncrementalLimits, IncrementalSanitizer, IncrementalSanitizerOptions, IncrementalSecretPolicy, SecretFinding, } from "../types.js";

package/dist/adapters/node-stream.js

@@ -0,0 +1,79 @@
+/**
+ * The Node.js stream adapter: a byte-to-byte `Transform` over one incremental
+ * session (`decision-define-runtime-bindings`).
+ *
+ * This module is reached only through the package's `./node-stream` subpath.
+ * It is the one published module that imports `node:stream`; the root export
+ * and `./web-stream` never resolve a Node-only module, so a browser bundle
+ * that uses them pulls none of this in.
+ *
+ * ```ts
+ * await initialize();
+ * await pipeline(source, createNodeStreamSanitizer({ limits }), destination);
+ * ```
+ *
+ * Backpressure, error propagation, and teardown are Node's own: the transform
+ * pushes into its readable side and lets the stream machinery stall the
+ * producer, and `_destroy` — which Node runs for `destroy()`, for a failed
+ * `pipeline`, and for a downstream error alike — aborts the session so the
+ * plaintext it was still deciding about is discarded rather than flushed.
+ */
+import { Transform } from "node:stream";
+import { runtime } from "../session.js";
+import { createStreamSanitizerRuntime } from "./shared.js";
+/** A byte-to-byte Node transform backed by one incremental session. */
+export class NodeStreamSanitizer extends Transform {
+    #runtime;
+    /**
+     * Wraps `session`, which this transform owns: it is finalized when the
+     * stream ends normally and aborted on every other exit.
+     */
+    constructor(session) {
+        super();
+        this.#runtime = createStreamSanitizerRuntime(session);
+    }
+    /**
+     * Every finding the session has finalized so far, frozen, with absolute
+     * UTF-16 offsets into the logical whole-stream input. It stays empty when
+     * the stream is destroyed before anything settles.
+     */
+    get findings() {
+        return this.#runtime.findings;
+    }
+    _transform(chunk, _encoding, callback) {
+        try {
+            const { text } = this.#runtime.append(chunk);
+            if (text.length > 0)
+                this.push(text, "utf8");
+            callback();
+        }
+        catch (error) {
+            callback(error);
+        }
+    }
+    _flush(callback) {
+        try {
+            const { text } = this.#runtime.finalize();
+            if (text.length > 0)
+                this.push(text, "utf8");
+            callback();
+        }
+        catch (error) {
+            callback(error);
+        }
+    }
+    _destroy(error, callback) {
+        this.#runtime.abort();
+        callback(error);
+    }
+}
+/**
+ * Opens one incremental session and wraps it in a Node transform.
+ *
+ * Requires a successful `await initialize()`, like every other synchronous
+ * operation in this package; it throws `NOT_INITIALIZED` otherwise.
+ */
+export function createNodeStreamSanitizer(options) {
+    return new NodeStreamSanitizer(runtime.createIncrementalSanitizer(options));
+}
+export { SecretScanError } from "../errors.js";

package/dist/adapters/shared.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The runtime-neutral half of both stream adapters: one incremental session,
+ * one stateful UTF-8 decoder, and the finding list they produce together.
+ *
+ * Nothing here imports a `node:` module or touches a host global beyond
+ * `TextDecoder`, which both Node.js and browsers provide, so
+ * `web-stream.ts` can build on it unchanged (`decision-define-runtime-bindings`).
+ *
+ * The decoder is fatal and stateful: a chunk may end in the middle of a
+ * multibyte character, and the bytes that character continues into arrive in
+ * the next chunk. Malformed input is a hard failure rather than a replacement
+ * character, because a silent `U+FFFD` would change the text a detector sees.
+ *
+ * Retained plaintext — the tail the session is still deciding about — never
+ * leaves this module. Every termination that is not a normal finalization
+ * aborts the session, which discards it.
+ */
+import type { IncrementalSanitizer, IncrementalSanitizerResult, SecretFinding } from "../types.js";
+/** One incremental session wrapped as a byte sink. */
+export interface StreamSanitizerRuntime {
+    /**
+     * Every finding whose detection window has closed so far, frozen.
+     *
+     * Offsets are absolute UTF-16 code units into the logical whole-stream
+     * input, exactly as the session reported them; this module never rebases
+     * them onto a chunk or onto the sanitized output.
+     */
+    readonly findings: readonly SecretFinding[];
+    append(chunk: Uint8Array): IncrementalSanitizerResult;
+    finalize(): IncrementalSanitizerResult;
+    abort(): void;
+}
+export declare function createStreamSanitizerRuntime(session: IncrementalSanitizer): StreamSanitizerRuntime;

package/dist/adapters/shared.js

@@ -0,0 +1,81 @@
+/**
+ * The runtime-neutral half of both stream adapters: one incremental session,
+ * one stateful UTF-8 decoder, and the finding list they produce together.
+ *
+ * Nothing here imports a `node:` module or touches a host global beyond
+ * `TextDecoder`, which both Node.js and browsers provide, so
+ * `web-stream.ts` can build on it unchanged (`decision-define-runtime-bindings`).
+ *
+ * The decoder is fatal and stateful: a chunk may end in the middle of a
+ * multibyte character, and the bytes that character continues into arrive in
+ * the next chunk. Malformed input is a hard failure rather than a replacement
+ * character, because a silent `U+FFFD` would change the text a detector sees.
+ *
+ * Retained plaintext — the tail the session is still deciding about — never
+ * leaves this module. Every termination that is not a normal finalization
+ * aborts the session, which discards it.
+ */
+import { SecretScanError } from "../errors.js";
+export function createStreamSanitizerRuntime(session) {
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    const findings = [];
+    /** Idempotent, and safe after the session has already left `accepting`. */
+    function abort() {
+        if (session.state === "accepting")
+            session.abort();
+    }
+    function decode(chunk, stream = false) {
+        try {
+            return decoder.decode(chunk, { stream });
+        }
+        catch {
+            abort();
+            throw new SecretScanError("INVALID_UTF8");
+        }
+    }
+    function append(chunk) {
+        if (!(chunk instanceof Uint8Array)) {
+            abort();
+            throw new SecretScanError("INVALID_CHUNK");
+        }
+        const result = session.append(decode(chunk, true));
+        findings.push(...result.findings);
+        return result;
+    }
+    /**
+     * Flushes the decoder, then the session.
+     *
+     * A stream that ends mid-character fails here: the final `decode()` with
+     * `stream: false` rejects the truncated sequence rather than emitting a
+     * replacement character.
+     */
+    function finalize() {
+        const decoded = decode();
+        let decodedResult;
+        let finalResult;
+        try {
+            decodedResult = session.append(decoded);
+            finalResult = session.finalize();
+        }
+        catch (error) {
+            abort();
+            throw error;
+        }
+        findings.push(...decodedResult.findings, ...finalResult.findings);
+        return Object.freeze({
+            text: decodedResult.text + finalResult.text,
+            findings: Object.freeze([
+                ...decodedResult.findings,
+                ...finalResult.findings,
+            ]),
+        });
+    }
+    return Object.freeze({
+        get findings() {
+            return Object.freeze([...findings]);
+        },
+        append,
+        finalize,
+        abort,
+    });
+}

package/dist/adapters/web-stream.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The Web Streams adapter: a byte-to-string `TransformStream` over one
+ * incremental session (`decision-define-runtime-bindings`).
+ *
+ * This module is reached through the package's `./web-stream` subpath and
+ * imports nothing from `node:`, so a browser bundle resolves only it, the
+ * root module, and the WebAssembly artifact.
+ *
+ * ```ts
+ * await initialize();
+ * await response.body.pipeThrough(createWebStreamSanitizer({ limits }))
+ *   .pipeTo(destination);
+ * ```
+ *
+ * Backpressure is the platform's: writes stall while the readable side is
+ * full and resume when a reader pulls. The readable and writable sides are
+ * wrapped so that a reader's `cancel()` and a writer's `abort()` — the two
+ * ways a Web stream ends early — abort the session first, discarding the
+ * plaintext it was still deciding about, before the underlying stream is torn
+ * down.
+ */
+import type { IncrementalSanitizer, IncrementalSanitizerOptions, SecretFinding } from "../types.js";
+/** A byte-to-string Web transform backed by one incremental session. */
+export declare class WebStreamSanitizer extends TransformStream<Uint8Array, string> {
+    #private;
+    /**
+     * Wraps `session`, which this transform owns: it is finalized when the
+     * writable side closes normally and aborted on every other exit.
+     */
+    constructor(session: IncrementalSanitizer);
+    get readable(): ReadableStream<string>;
+    get writable(): WritableStream<Uint8Array>;
+    /**
+     * Every finding the session has finalized so far, frozen, with absolute
+     * UTF-16 offsets into the logical whole-stream input. It stays empty when
+     * the stream is cancelled or aborted before anything settles.
+     */
+    get findings(): readonly SecretFinding[];
+    /**
+     * Discards retained plaintext before explicit early termination.
+     *
+     * Idempotent, and safe after the session has already ended: a later
+     * `close()` on the writable side then fails with `INVALID_STATE` rather
+     * than flushing anything.
+     */
+    abort(): void;
+}
+/**
+ * Opens one incremental session and wraps it in a Web transform.
+ *
+ * Requires a successful `await initialize()`, like every other synchronous
+ * operation in this package; it throws `NOT_INITIALIZED` otherwise.
+ */
+export declare function createWebStreamSanitizer(options: IncrementalSanitizerOptions): WebStreamSanitizer;
+export { SecretScanError } from "../errors.js";
+export type { SecretScanErrorCode } from "../errors.js";
+export type { IncrementalLimits, IncrementalSanitizer, IncrementalSanitizerOptions, IncrementalSecretPolicy, SecretFinding, } from "../types.js";

package/dist/adapters/web-stream.js

@@ -0,0 +1,115 @@
+/**
+ * The Web Streams adapter: a byte-to-string `TransformStream` over one
+ * incremental session (`decision-define-runtime-bindings`).
+ *
+ * This module is reached through the package's `./web-stream` subpath and
+ * imports nothing from `node:`, so a browser bundle resolves only it, the
+ * root module, and the WebAssembly artifact.
+ *
+ * ```ts
+ * await initialize();
+ * await response.body.pipeThrough(createWebStreamSanitizer({ limits }))
+ *   .pipeTo(destination);
+ * ```
+ *
+ * Backpressure is the platform's: writes stall while the readable side is
+ * full and resume when a reader pulls. The readable and writable sides are
+ * wrapped so that a reader's `cancel()` and a writer's `abort()` — the two
+ * ways a Web stream ends early — abort the session first, discarding the
+ * plaintext it was still deciding about, before the underlying stream is torn
+ * down.
+ */
+import { runtime } from "../session.js";
+import { createStreamSanitizerRuntime } from "./shared.js";
+/** A byte-to-string Web transform backed by one incremental session. */
+export class WebStreamSanitizer extends TransformStream {
+    #runtime;
+    #readable;
+    #writable;
+    /**
+     * Wraps `session`, which this transform owns: it is finalized when the
+     * writable side closes normally and aborted on every other exit.
+     */
+    constructor(session) {
+        const sanitizer = createStreamSanitizerRuntime(session);
+        super({
+            transform(chunk, controller) {
+                const { text } = sanitizer.append(chunk);
+                if (text.length > 0)
+                    controller.enqueue(text);
+            },
+            flush(controller) {
+                const { text } = sanitizer.finalize();
+                if (text.length > 0)
+                    controller.enqueue(text);
+            },
+        });
+        this.#runtime = sanitizer;
+        const source = super.readable.getReader();
+        this.#readable = new ReadableStream({
+            async pull(controller) {
+                try {
+                    const result = await source.read();
+                    if (result.done)
+                        controller.close();
+                    else
+                        controller.enqueue(result.value);
+                }
+                catch (error) {
+                    controller.error(error);
+                }
+            },
+            async cancel(reason) {
+                sanitizer.abort();
+                await source.cancel(reason);
+            },
+        });
+        const sink = super.writable.getWriter();
+        this.#writable = new WritableStream({
+            write(chunk) {
+                return sink.write(chunk);
+            },
+            close() {
+                return sink.close();
+            },
+            async abort(reason) {
+                sanitizer.abort();
+                await sink.abort(reason);
+            },
+        });
+    }
+    get readable() {
+        return this.#readable;
+    }
+    get writable() {
+        return this.#writable;
+    }
+    /**
+     * Every finding the session has finalized so far, frozen, with absolute
+     * UTF-16 offsets into the logical whole-stream input. It stays empty when
+     * the stream is cancelled or aborted before anything settles.
+     */
+    get findings() {
+        return this.#runtime.findings;
+    }
+    /**
+     * Discards retained plaintext before explicit early termination.
+     *
+     * Idempotent, and safe after the session has already ended: a later
+     * `close()` on the writable side then fails with `INVALID_STATE` rather
+     * than flushing anything.
+     */
+    abort() {
+        this.#runtime.abort();
+    }
+}
+/**
+ * Opens one incremental session and wraps it in a Web transform.
+ *
+ * Requires a successful `await initialize()`, like every other synchronous
+ * operation in this package; it throws `NOT_INITIALIZED` otherwise.
+ */
+export function createWebStreamSanitizer(options) {
+    return new WebStreamSanitizer(runtime.createIncrementalSanitizer(options));
+}
+export { SecretScanError } from "../errors.js";

package/dist/errors.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The single sanitized error type this package throws.
+ *
+ * Every code and message below is fixed and input-free: no error carries the
+ * scanned input, a matched value, a placeholder, or a failing callback's own
+ * message (`decision-define-runtime-bindings`). Sixteen codes come from the
+ * Rust core; `NOT_INITIALIZED` and `INITIALIZATION_FAILED` are produced by the
+ * binding layer, `INVALID_CHUNK` and `INVALID_UTF8` by the stream adapters,
+ * `UNPAIRED_SURROGATE` by this package's own runtime-neutral input check, and
+ * `INCREMENTAL_UNAVAILABLE` by any binding that does not implement
+ * incremental sanitization — the browser binding always (`bindings/wasm` has
+ * no such export by design) and the Node binding until `bindings/node` gains
+ * one; and this package normalizes all of them into the same class so
+ * `instanceof SecretScanError` holds on every runtime and every subpath.
+ *
+ * `UNPAIRED_SURROGATE` resolves `B/F-10`
+ * (`docs/audits/deferred-quality-backlog.md`): a JavaScript string may hold a
+ * lone UTF-16 surrogate, which has no UTF-8 representation, so it cannot
+ * cross into the Rust core's `&str` without either a silent `U+FFFD`
+ * substitution (which would make `redact`'s output a transcoded copy, not the
+ * caller's input with only findings replaced) or a stable rejection. This
+ * package rejects, once, in `runtime.ts`'s `requireString`, before the string
+ * reaches either binding — so the error and this check are identical on the
+ * Node and browser runtimes by construction rather than by parallel
+ * implementation.
+ */
+export type SecretScanErrorCode = "INVALID_INPUT" | "INVALID_OPTIONS" | "INVALID_DETECTOR" | "DETECTOR_FAILURE" | "INVALID_CANDIDATE" | "POLICY_FAILURE" | "INVALID_POLICY_ACTION" | "INVALID_FINDINGS" | "PLACEHOLDER_FAILURE" | "INVALID_PLACEHOLDER" | "INVALID_LIMITS" | "INPUT_LIMIT_EXCEEDED" | "BUFFER_LIMIT_EXCEEDED" | "TOKEN_LIMIT_EXCEEDED" | "MULTILINE_LIMIT_EXCEEDED" | "INVALID_STATE" | "NOT_INITIALIZED" | "INITIALIZATION_FAILED" | "INVALID_CHUNK" | "INVALID_UTF8" | "UNPAIRED_SURROGATE" | "INCREMENTAL_UNAVAILABLE";
+/** A sanitized failure. It carries nothing but its fixed code and message. */
+export declare class SecretScanError extends Error {
+    readonly code: SecretScanErrorCode;
+    constructor(code: SecretScanErrorCode);
+}
+/**
+ * Rewrites whatever a binding threw as a {@link SecretScanError}.
+ *
+ * The Node addon throws an N-API error whose `code` is the core's fixed code;
+ * the WebAssembly binding throws a `js_sys::Error` with the same property. A
+ * value that carries no recognized code is replaced by `fallback` rather than
+ * surfaced, so a host-specific message can never reach a caller.
+ */
+export declare function toSecretScanError(thrown: unknown, fallback: SecretScanErrorCode): SecretScanError;