@redact-secret/core 0.1.0-beta.1

package/dist/errors.js

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+/** The fixed message for every code, mirroring the core's own strings. */
+const ERROR_MESSAGES = {
+    INVALID_INPUT: "Secret scan input must be a string.",
+    INVALID_OPTIONS: "Secret scan options are invalid.",
+    INVALID_DETECTOR: "Invalid detector registration.",
+    DETECTOR_FAILURE: "A secret detector failed.",
+    INVALID_CANDIDATE: "A secret detector returned an invalid candidate.",
+    POLICY_FAILURE: "The secret policy failed.",
+    INVALID_POLICY_ACTION: "The secret policy returned an invalid action.",
+    INVALID_FINDINGS: "Redaction findings are invalid.",
+    PLACEHOLDER_FAILURE: "The placeholder formatter failed.",
+    INVALID_PLACEHOLDER: "The placeholder formatter returned an invalid value.",
+    INVALID_LIMITS: "Incremental sanitizer limits are invalid.",
+    INPUT_LIMIT_EXCEEDED: "Incremental sanitizer input limit exceeded.",
+    BUFFER_LIMIT_EXCEEDED: "Incremental sanitizer buffer limit exceeded.",
+    TOKEN_LIMIT_EXCEEDED: "Incremental sanitizer token limit exceeded.",
+    MULTILINE_LIMIT_EXCEEDED: "Incremental sanitizer multiline limit exceeded.",
+    INVALID_STATE: "The incremental sanitizer is no longer accepting input.",
+    NOT_INITIALIZED: "redact-secret is not initialized; await initialize() before this call.",
+    INITIALIZATION_FAILED: "redact-secret failed to initialize.",
+    INVALID_CHUNK: "Stream sanitizer input must contain bytes.",
+    INVALID_UTF8: "Stream sanitizer input is not valid UTF-8.",
+    UNPAIRED_SURROGATE: "Secret scan input contains an unpaired UTF-16 surrogate.",
+    INCREMENTAL_UNAVAILABLE: "Incremental sanitization is not available on this runtime.",
+};
+const ERROR_CODES = new Set(Object.keys(ERROR_MESSAGES));
+/** A sanitized failure. It carries nothing but its fixed code and message. */
+export class SecretScanError extends Error {
+    code;
+    constructor(code) {
+        super(ERROR_MESSAGES[code]);
+        this.name = "SecretScanError";
+        this.code = code;
+    }
+}
+function nativeErrorCode(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const { code } = value;
+    return typeof code === "string" && ERROR_CODES.has(code)
+        ? code
+        : undefined;
+}
+/**
+ * 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 function toSecretScanError(thrown, fallback) {
+    if (thrown instanceof SecretScanError)
+        return thrown;
+    return new SecretScanError(nativeErrorCode(thrown) ?? fallback);
+}

package/dist/formatters.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The supported placeholder formatter helpers.
+ *
+ * Both are pure functions of safe finding metadata: they never see the input
+ * or the matched value, and the binding validates whatever they return. Pass
+ * {@link defaultPlaceholderFormatter} to name the built-in behavior
+ * explicitly — the runtime recognizes it and lets the Rust core apply its own
+ * formatter rather than calling back into JavaScript per placeholder.
+ *
+ * There is deliberately no exported default *policy*: the built-in policy's
+ * type table lives in Rust, and re-declaring it here would create a second
+ * source of truth (`decision-govern-cross-language-conformance`). Omit
+ * `policy` to use it.
+ */
+import type { PlaceholderFormatter } from "./types.js";
+/** Formats `<SECRET_1>`, `<SECRET_2>`, ... in replacement order. */
+export declare const defaultPlaceholderFormatter: PlaceholderFormatter;
+/**
+ * Formats `<JWT_1>`, `<AWS_ACCESS_KEY_ID_2>`, ... naming the finding type,
+ * upper-cased with `.` and `-` mapped to `_`, matching the core's own typed
+ * formatter.
+ */
+export declare const typedPlaceholderFormatter: PlaceholderFormatter;

package/dist/formatters.js

@@ -0,0 +1,22 @@
+/**
+ * The supported placeholder formatter helpers.
+ *
+ * Both are pure functions of safe finding metadata: they never see the input
+ * or the matched value, and the binding validates whatever they return. Pass
+ * {@link defaultPlaceholderFormatter} to name the built-in behavior
+ * explicitly — the runtime recognizes it and lets the Rust core apply its own
+ * formatter rather than calling back into JavaScript per placeholder.
+ *
+ * There is deliberately no exported default *policy*: the built-in policy's
+ * type table lives in Rust, and re-declaring it here would create a second
+ * source of truth (`decision-govern-cross-language-conformance`). Omit
+ * `policy` to use it.
+ */
+/** Formats `<SECRET_1>`, `<SECRET_2>`, ... in replacement order. */
+export const defaultPlaceholderFormatter = (_finding, context) => `<SECRET_${context.placeholderIndex}>`;
+/**
+ * Formats `<JWT_1>`, `<AWS_ACCESS_KEY_ID_2>`, ... naming the finding type,
+ * upper-cased with `.` and `-` mapped to `_`, matching the core's own typed
+ * formatter.
+ */
+export const typedPlaceholderFormatter = (finding, context) => `<${finding.type.toUpperCase().replace(/[.-]/g, "_")}_${context.placeholderIndex}>`;

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+/**
+ * `@redact-secret/core`: deterministic secret detection and redaction, one
+ * API across Node.js and the browser.
+ *
+ * The package's `exports` map selects the N-API addon on Node and the
+ * WebAssembly build in the browser (`decision-define-runtime-bindings`).
+ * Every runtime uses the same contract:
+ *
+ * ```ts
+ * import { initialize, scanAndRedact } from "@redact-secret/core";
+ *
+ * await initialize();
+ * const { text, findings } = scanAndRedact(input);
+ * ```
+ *
+ * `await initialize()` must succeed exactly once before any synchronous
+ * operation; calling it again is free. Node's own loading has nothing to
+ * await, but the call stays part of the contract so the usage model does not
+ * vary by runtime.
+ *
+ * Every range this module reports is a `[start, end)` pair of UTF-16
+ * code-unit offsets ({@link RANGE_UNIT}), and every finding it returns is
+ * frozen. Every failure is a {@link SecretScanError} carrying nothing but a
+ * fixed code and message.
+ *
+ * Built-in detectors all run in Rust; there is no custom detector callback in
+ * this API, and no internal module of this package is reachable through its
+ * `exports` map.
+ *
+ * Byte streams are served by the two adapter subpaths,
+ * `@redact-secret/core/node-stream` and
+ * `@redact-secret/core/web-stream`, each of which drives one incremental
+ * session per stream. This root module never resolves a `node:` module.
+ */
+import type { RangeUnit } from "./types.js";
+/**
+ * Loads this runtime's binding and prepares it for use.
+ *
+ * Idempotent: the artifact is loaded at most once no matter how many callers
+ * await it. A rejected attempt is not cached, so a caller may retry. Rejects
+ * with `INITIALIZATION_FAILED` when the artifact is missing, unusable, or
+ * built from a different product version than this package.
+ */
+export declare const initialize: () => Promise<void>;
+/** Scans `input` and returns every finding, in input order. */
+export declare const scan: (input: string, options?: import("./types.js").ScanOptions) => readonly import("./types.js").SecretFinding[];
+/**
+ * Replaces the `redact` and `block` findings in `input` with placeholders,
+ * leaving `warn` and `allow` findings untouched.
+ *
+ * `findings` must be the findings {@link scan} returned for this same input.
+ */
+export declare const redact: (input: string, findings: readonly import("./types.js").SecretFinding[], options?: import("./types.js").RedactOptions) => string;
+/** Scans and redacts in one call, so text and findings cannot disagree. */
+export declare const scanAndRedact: (input: string, options?: import("./types.js").ScanAndRedactOptions) => import("./types.js").ScanResult;
+/** Opens a bounded incremental session over text supplied in chunks. */
+export declare const createIncrementalSanitizer: (options: import("./types.js").IncrementalSanitizerOptions) => import("./types.js").IncrementalSanitizer;
+export { defaultPlaceholderFormatter, typedPlaceholderFormatter, } from "./formatters.js";
+export { SecretScanError } from "./errors.js";
+export type { SecretScanErrorCode } from "./errors.js";
+export { VERSION } from "./version.js";
+/** The string-index unit of every range this package reports. */
+export declare const RANGE_UNIT: RangeUnit;
+export type { DetectedSecretFinding, IncrementalLimits, IncrementalPolicyContext, IncrementalSanitizer, IncrementalSanitizerOptions, IncrementalSanitizerResult, IncrementalSanitizerState, IncrementalSecretPolicy, PlaceholderContext, PlaceholderFormatter, PolicyContext, RangeUnit, RedactOptions, ScanAndRedactOptions, ScanOptions, ScanResult, SecretAction, SecretConfidence, SecretFinding, SecretPolicy, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,62 @@
+/**
+ * `@redact-secret/core`: deterministic secret detection and redaction, one
+ * API across Node.js and the browser.
+ *
+ * The package's `exports` map selects the N-API addon on Node and the
+ * WebAssembly build in the browser (`decision-define-runtime-bindings`).
+ * Every runtime uses the same contract:
+ *
+ * ```ts
+ * import { initialize, scanAndRedact } from "@redact-secret/core";
+ *
+ * await initialize();
+ * const { text, findings } = scanAndRedact(input);
+ * ```
+ *
+ * `await initialize()` must succeed exactly once before any synchronous
+ * operation; calling it again is free. Node's own loading has nothing to
+ * await, but the call stays part of the contract so the usage model does not
+ * vary by runtime.
+ *
+ * Every range this module reports is a `[start, end)` pair of UTF-16
+ * code-unit offsets ({@link RANGE_UNIT}), and every finding it returns is
+ * frozen. Every failure is a {@link SecretScanError} carrying nothing but a
+ * fixed code and message.
+ *
+ * Built-in detectors all run in Rust; there is no custom detector callback in
+ * this API, and no internal module of this package is reachable through its
+ * `exports` map.
+ *
+ * Byte streams are served by the two adapter subpaths,
+ * `@redact-secret/core/node-stream` and
+ * `@redact-secret/core/web-stream`, each of which drives one incremental
+ * session per stream. This root module never resolves a `node:` module.
+ */
+import { runtime } from "./session.js";
+/**
+ * Loads this runtime's binding and prepares it for use.
+ *
+ * Idempotent: the artifact is loaded at most once no matter how many callers
+ * await it. A rejected attempt is not cached, so a caller may retry. Rejects
+ * with `INITIALIZATION_FAILED` when the artifact is missing, unusable, or
+ * built from a different product version than this package.
+ */
+export const initialize = runtime.initialize;
+/** Scans `input` and returns every finding, in input order. */
+export const scan = runtime.scan;
+/**
+ * Replaces the `redact` and `block` findings in `input` with placeholders,
+ * leaving `warn` and `allow` findings untouched.
+ *
+ * `findings` must be the findings {@link scan} returned for this same input.
+ */
+export const redact = runtime.redact;
+/** Scans and redacts in one call, so text and findings cannot disagree. */
+export const scanAndRedact = runtime.scanAndRedact;
+/** Opens a bounded incremental session over text supplied in chunks. */
+export const createIncrementalSanitizer = runtime.createIncrementalSanitizer;
+export { defaultPlaceholderFormatter, typedPlaceholderFormatter, } from "./formatters.js";
+export { SecretScanError } from "./errors.js";
+export { VERSION } from "./version.js";
+/** The string-index unit of every range this package reports. */
+export const RANGE_UNIT = "utf16-code-units";

package/dist/native.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The internal contract every runtime adapter must satisfy.
+ *
+ * `runtime/node.ts` builds it from the N-API addon and `runtime/browser.ts`
+ * from the WebAssembly build; nothing here is part of the published API, and
+ * the package's `exports` map makes this module unreachable from outside
+ * (`decision-define-runtime-bindings`).
+ *
+ * Every offset crossing this boundary is already a UTF-16 code-unit offset:
+ * each binding converts from the core's UTF-8 byte offsets on its own side,
+ * without changing the selected span.
+ */
+import type { IncrementalPolicyContext, IncrementalSanitizerState, PlaceholderContext, PolicyContext } from "./types.js";
+/**
+ * Carries a binding-private handle alongside a public finding.
+ *
+ * The WebAssembly binding returns opaque `Finding` objects that its `redact`
+ * must receive back unchanged; the property is a symbol and non-enumerable, so
+ * it never appears in `Object.keys`, `JSON.stringify`, or a structural
+ * comparison of a public finding.
+ */
+export declare const NATIVE_HANDLE: unique symbol;
+export interface NativeFinding {
+    readonly id: string;
+    readonly type: string;
+    readonly detector: string;
+    readonly confidence: string;
+    readonly action: string;
+    readonly start: number;
+    readonly end: number;
+    readonly [NATIVE_HANDLE]?: unknown;
+}
+export interface NativeDetectedFinding {
+    readonly id: string;
+    readonly type: string;
+    readonly detector: string;
+    readonly confidence: string;
+    readonly start: number;
+    readonly end: number;
+}
+export type NativePolicyCallback = (finding: NativeDetectedFinding, context: PolicyContext) => string;
+export type NativeIncrementalPolicyCallback = (finding: NativeDetectedFinding, context: IncrementalPolicyContext) => string;
+export type NativeFormatterCallback = (finding: NativeFinding, context: PlaceholderContext) => string;
+export interface NativeScanAndRedactResult {
+    readonly text: string;
+    readonly findings: readonly NativeFinding[];
+}
+export interface NativeIncrementalLimits {
+    readonly maxInputCodeUnits: number;
+    readonly maxBufferedCodeUnits: number;
+    readonly maxTokenCodeUnits: number;
+    readonly maxMultilineCodeUnits: number;
+}
+export interface NativeIncrementalOptions {
+    readonly limits: NativeIncrementalLimits;
+    readonly policy?: NativeIncrementalPolicyCallback;
+    readonly formatter?: NativeFormatterCallback;
+}
+export interface NativeIncrementalResult {
+    readonly text: string;
+    readonly findings: readonly NativeFinding[];
+}
+export interface NativeIncrementalSanitizer {
+    readonly state: IncrementalSanitizerState;
+    append(chunk: string): NativeIncrementalResult;
+    finalize(): NativeIncrementalResult;
+    abort(): void;
+}
+export interface NativeBinding {
+    /** The shared product version this artifact was built from. */
+    version(): string;
+    /** Idempotent native setup. May be a no-op, as it is on Node. */
+    initialize(): void;
+    scan(input: string, policy: NativePolicyCallback | undefined): readonly NativeFinding[];
+    redact(input: string, findings: readonly NativeFinding[], formatter: NativeFormatterCallback | undefined): string;
+    scanAndRedact(input: string, policy: NativePolicyCallback | undefined, formatter: NativeFormatterCallback | undefined): NativeScanAndRedactResult;
+    createIncrementalSanitizer(options: NativeIncrementalOptions): NativeIncrementalSanitizer;
+}
+/** Loads and prepares this runtime's binding. Called at most once. */
+export type NativeBindingLoader = () => Promise<NativeBinding>;

package/dist/native.js

@@ -0,0 +1,21 @@
+/**
+ * The internal contract every runtime adapter must satisfy.
+ *
+ * `runtime/node.ts` builds it from the N-API addon and `runtime/browser.ts`
+ * from the WebAssembly build; nothing here is part of the published API, and
+ * the package's `exports` map makes this module unreachable from outside
+ * (`decision-define-runtime-bindings`).
+ *
+ * Every offset crossing this boundary is already a UTF-16 code-unit offset:
+ * each binding converts from the core's UTF-8 byte offsets on its own side,
+ * without changing the selected span.
+ */
+/**
+ * Carries a binding-private handle alongside a public finding.
+ *
+ * The WebAssembly binding returns opaque `Finding` objects that its `redact`
+ * must receive back unchanged; the property is a symbol and non-enumerable, so
+ * it never appears in `Object.keys`, `JSON.stringify`, or a structural
+ * comparison of a public finding.
+ */
+export const NATIVE_HANDLE = Symbol.for("@redact-secret/core.native-handle");

package/dist/runtime/browser.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The browser adapter: the `wasm-bindgen` build, normalized to the internal
+ * binding contract (`decision-define-runtime-bindings`).
+ *
+ * The package's `imports` map reaches this module under the `browser`
+ * condition and by default. It imports nothing from `node:` and touches no
+ * Node global, so a bundle produced for the browser resolves only this file
+ * and the WebAssembly artifact it loads.
+ *
+ * There are two distinct setup steps behind one `await initialize()`: the
+ * generated `init()` that fetches and instantiates the `.wasm` binary, and the
+ * binding's own idempotent `initialize()` that builds the detector registry.
+ * Wrapping both is exactly this adapter's job.
+ *
+ * `bindings/wasm` does not export a `createIncrementalSanitizer` (see its
+ * `README.md`): incremental sanitization is deliberately unavailable on this
+ * runtime, so this adapter's `createIncrementalSanitizer` always rejects with
+ * the fixed `INCREMENTAL_UNAVAILABLE` code. `./web-stream` rejects the same
+ * way, through this same binding, and `initialize()` itself still resolves.
+ */
+import { type NativeBinding } from "../native.js";
+import type { PlaceholderContext, PolicyContext } from "../types.js";
+/** One opaque finding handle, as `scan`/`redact`/`scanAndRedact` return it. */
+export interface WasmFinding {
+    readonly id: string;
+    readonly type: string;
+    readonly detector: string;
+    readonly confidence: string;
+    readonly action: string;
+    readonly range: {
+        readonly start: number;
+        readonly end: number;
+    };
+}
+/**
+ * The safe metadata a `policy` callback is actually invoked with
+ * (`bindings/wasm/src/metadata.rs`'s `policy_finding`): the same fields as
+ * {@link WasmFinding} minus `action`, with the range still nested rather than
+ * flattened onto the object.
+ */
+export interface WasmDetectedFindingMetadata {
+    readonly id: string;
+    readonly type: string;
+    readonly detector: string;
+    readonly confidence: string;
+    readonly range: {
+        readonly start: number;
+        readonly end: number;
+    };
+}
+/**
+ * The safe metadata a `formatter` callback is actually invoked with
+ * (`metadata.rs`'s `formatter_finding`): adds the `action` the policy already
+ * chose.
+ */
+export interface WasmFindingMetadata extends WasmDetectedFindingMetadata {
+    readonly action: string;
+}
+type WasmPolicyCallback = (finding: WasmDetectedFindingMetadata, context: PolicyContext) => string;
+type WasmFormatterCallback = (finding: WasmFindingMetadata, context: PlaceholderContext) => string;
+export interface WasmModule {
+    default(): Promise<unknown>;
+    version(): string;
+    initialize(): void;
+    scan(input: string, policy?: WasmPolicyCallback): readonly WasmFinding[];
+    redact(input: string, findings: readonly WasmFinding[], formatter?: WasmFormatterCallback): string;
+    scanAndRedact(input: string, policy?: WasmPolicyCallback, formatter?: WasmFormatterCallback): {
+        readonly text: string;
+        readonly findings: readonly WasmFinding[];
+    };
+}
+/**
+ * Builds the internal binding contract from an already-loaded WebAssembly
+ * module.
+ *
+ * Exported so a test double can exercise this exact normalization — the
+ * nested-metadata flattening above and the fixed `INCREMENTAL_UNAVAILABLE`
+ * rejection below — against a fake module shaped like the real artifact,
+ * without loading the artifact itself.
+ */
+export declare function createBindingFromWasmModule(wasm: WasmModule): NativeBinding;
+export declare const loadNativeBinding: () => Promise<NativeBinding>;
+export {};

package/dist/runtime/browser.js

@@ -0,0 +1,143 @@
+/**
+ * The browser adapter: the `wasm-bindgen` build, normalized to the internal
+ * binding contract (`decision-define-runtime-bindings`).
+ *
+ * The package's `imports` map reaches this module under the `browser`
+ * condition and by default. It imports nothing from `node:` and touches no
+ * Node global, so a bundle produced for the browser resolves only this file
+ * and the WebAssembly artifact it loads.
+ *
+ * There are two distinct setup steps behind one `await initialize()`: the
+ * generated `init()` that fetches and instantiates the `.wasm` binary, and the
+ * binding's own idempotent `initialize()` that builds the detector registry.
+ * Wrapping both is exactly this adapter's job.
+ *
+ * `bindings/wasm` does not export a `createIncrementalSanitizer` (see its
+ * `README.md`): incremental sanitization is deliberately unavailable on this
+ * runtime, so this adapter's `createIncrementalSanitizer` always rejects with
+ * the fixed `INCREMENTAL_UNAVAILABLE` code. `./web-stream` rejects the same
+ * way, through this same binding, and `initialize()` itself still resolves.
+ */
+import { SecretScanError } from "../errors.js";
+import { NATIVE_HANDLE, } from "../native.js";
+/**
+ * Flattens an opaque handle into the contract's shape while keeping the handle
+ * itself, because the WebAssembly `redact` only accepts the objects its own
+ * `scan` returned.
+ */
+function toNativeFinding(finding) {
+    const { start, end } = finding.range;
+    return {
+        id: finding.id,
+        type: finding.type,
+        detector: finding.detector,
+        confidence: finding.confidence,
+        action: finding.action,
+        start,
+        end,
+        [NATIVE_HANDLE]: finding,
+    };
+}
+/** Recovers the handle `scan` produced, refusing a foreign finding. */
+function toWasmFinding(finding) {
+    const handle = finding[NATIVE_HANDLE];
+    if (handle === undefined)
+        throw new SecretScanError("INVALID_FINDINGS");
+    return handle;
+}
+/**
+ * Flattens and freezes the nested-`range` metadata a `policy` callback is
+ * actually invoked with, so a callback crossing this boundary sees the same
+ * numeric `start`/`end` fields it sees on Node, matching `types.ts`.
+ */
+function toNativeDetectedFinding(finding) {
+    const { start, end } = finding.range;
+    return Object.freeze({
+        id: finding.id,
+        type: finding.type,
+        detector: finding.detector,
+        confidence: finding.confidence,
+        start,
+        end,
+    });
+}
+/** As {@link toNativeDetectedFinding}, plus the `action` a formatter sees. */
+function toNativeFormatterMetadata(finding) {
+    const { start, end } = finding.range;
+    return Object.freeze({
+        id: finding.id,
+        type: finding.type,
+        detector: finding.detector,
+        confidence: finding.confidence,
+        action: finding.action,
+        start,
+        end,
+    });
+}
+function toWasmPolicyCallback(policy) {
+    if (policy === undefined)
+        return undefined;
+    return (finding, context) => policy(toNativeDetectedFinding(finding), context);
+}
+function toWasmFormatterCallback(formatter) {
+    if (formatter === undefined)
+        return undefined;
+    return (finding, context) => formatter(toNativeFormatterMetadata(finding), context);
+}
+/**
+ * Loads the WebAssembly artifact published in lockstep with this package.
+ *
+ * The specifier is a literal so a bundler can resolve and include the glue and
+ * the `.wasm` binary it references, and the import is dynamic so nothing is
+ * fetched until a caller awaits `initialize()`.
+ */
+async function loadWasmModule() {
+    const module = (await import("@redact-secret/wasm"));
+    for (const name of [
+        "default",
+        "version",
+        "initialize",
+        "scan",
+        "redact",
+        "scanAndRedact",
+    ]) {
+        if (typeof module[name] !== "function") {
+            throw new SecretScanError("INITIALIZATION_FAILED");
+        }
+    }
+    return module;
+}
+/**
+ * Builds the internal binding contract from an already-loaded WebAssembly
+ * module.
+ *
+ * Exported so a test double can exercise this exact normalization — the
+ * nested-metadata flattening above and the fixed `INCREMENTAL_UNAVAILABLE`
+ * rejection below — against a fake module shaped like the real artifact,
+ * without loading the artifact itself.
+ */
+export function createBindingFromWasmModule(wasm) {
+    return {
+        version: () => wasm.version(),
+        initialize: () => {
+            wasm.initialize();
+        },
+        scan: (input, policy) => wasm.scan(input, toWasmPolicyCallback(policy)).map(toNativeFinding),
+        redact: (input, findings, formatter) => wasm.redact(input, findings.map(toWasmFinding), toWasmFormatterCallback(formatter)),
+        scanAndRedact: (input, policy, formatter) => {
+            const result = wasm.scanAndRedact(input, toWasmPolicyCallback(policy), toWasmFormatterCallback(formatter));
+            return {
+                text: result.text,
+                findings: result.findings.map(toNativeFinding),
+            };
+        },
+        createIncrementalSanitizer: () => {
+            throw new SecretScanError("INCREMENTAL_UNAVAILABLE");
+        },
+    };
+}
+export const loadNativeBinding = async () => {
+    const wasm = await loadWasmModule();
+    await wasm.default();
+    return createBindingFromWasmModule(wasm);
+};

package/dist/runtime/node.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The Node.js adapter: the N-API native addon, normalized to the internal
+ * binding contract (`decision-define-runtime-bindings`).
+ *
+ * The package's `imports` map reaches this module only under the `node`
+ * condition, so a browser build never resolves it and never pulls in the
+ * `node:` module below.
+ *
+ * Node's own loading has nothing to await, so `initialize()` here is a fast
+ * idempotent no-op in the addon. It stays part of the contract regardless, so
+ * the usage model does not vary by runtime.
+ */
+import type { NativeBinding, NativeFinding, NativeFormatterCallback, NativeIncrementalOptions, NativeIncrementalSanitizer, NativePolicyCallback } from "../native.js";
+/**
+ * The addon's own exported shape. `scanAndRedact` names its text `redacted`,
+ * which this adapter renames to the contract's `text`; everything else is
+ * already the documented UTF-16 shape.
+ *
+ * `createIncrementalSanitizer` is optional: `bindings/node` does not implement
+ * it yet (unlike `bindings/python`, which wraps the same core
+ * `IncrementalSanitizer`), so this adapter treats its absence the same way
+ * `runtime/browser.ts` treats `bindings/wasm`'s documented non-support —
+ * `INCREMENTAL_UNAVAILABLE` at call time, not a load-time failure.
+ */
+interface NodeAddon {
+    version(): string;
+    initialize(): void;
+    scan(input: string, policy?: NativePolicyCallback): readonly NativeFinding[];
+    redact(input: string, findings: readonly NativeFinding[], formatter?: NativeFormatterCallback): string;
+    scanAndRedact(input: string, policy?: NativePolicyCallback, formatter?: NativeFormatterCallback): {
+        readonly findings: readonly NativeFinding[];
+        readonly redacted: string;
+    };
+    createIncrementalSanitizer?(options: NativeIncrementalOptions): NativeIncrementalSanitizer;
+}
+/**
+ * The addon package this host should have installed, or `undefined` on a
+ * platform/architecture this package ships no addon for at all — the
+ * runtime fallback that keeps an unsupported host's failure identical to a
+ * supported host whose optional dependency did not install: both reach
+ * `loadAddon`'s own `INITIALIZATION_FAILED`, never a raw `require` error.
+ *
+ * Exported so `scripts/qualify-node-addon.mjs` and
+ * `scripts/qualify-package-consumer.mjs` compute the same host-to-package
+ * mapping this module actually loads from, instead of restating it.
+ */
+export declare function resolveAddonSpecifier(): string | undefined;
+/**
+ * Builds the internal binding contract from an already-loaded addon.
+ *
+ * Exported so a test double can exercise this exact normalization —
+ * including the `createIncrementalSanitizer` fallback — without loading the
+ * real addon, the way `runtime/browser.ts`'s
+ * `createBindingFromWasmModule` does for the WebAssembly artifact.
+ */
+export declare function createBindingFromAddon(addon: NodeAddon): NativeBinding;
+export declare const loadNativeBinding: () => Promise<NativeBinding>;
+export {};