@jinn-network/core 0.1.0-canary.3afae198

package/dist/scrub/review-queue.js

@@ -0,0 +1,259 @@
+/**
+ * Operator-local review queue for scrub `flag` dispositions (#1973 / design §6.6).
+ *
+ * Persistence: `~/.jinn-client/scrub-review/queue.jsonl` (one JSON object per
+ * line). Traces never leave the machine — this queue is local-only.
+ *
+ * Unattended publish lanes fail closed while any matching flag remains
+ * `pending` (see {@link assertNoUnresolvedFlags}).
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { resolveDisposition } from './policy.js';
+import { DEFAULT_POLICY } from './policy.js';
+export const DEFAULT_REVIEW_QUEUE_PATH = join(homedir(), '.jinn-client', 'scrub-review', 'queue.jsonl');
+/** Stable fingerprint for matching a finding across scrub runs. */
+export function findingFingerprint(finding) {
+    const payload = [
+        finding.class,
+        finding.span.key,
+        String(finding.span.start),
+        String(finding.span.end),
+        finding.evidence.join('|'),
+        finding.detector.name,
+    ].join('\0');
+    return createHash('sha256').update(payload).digest('hex').slice(0, 24);
+}
+function readAll(path) {
+    if (!existsSync(path))
+        return [];
+    const text = readFileSync(path, 'utf8');
+    const items = [];
+    for (const line of text.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            items.push(JSON.parse(trimmed));
+        }
+        catch {
+            // skip corrupt lines
+        }
+    }
+    return items;
+}
+function writeAll(path, items) {
+    mkdirSync(dirname(path), { recursive: true });
+    const body = items.map((i) => JSON.stringify(i)).join('\n');
+    writeFileSync(path, body.length > 0 ? `${body}\n` : '', 'utf8');
+}
+/** In-memory review queue for unit tests (no disk I/O). */
+export function createMemoryReviewQueueStore(seed = []) {
+    let items = [...seed];
+    return {
+        listFlagged(filter) {
+            if (!filter?.status)
+                return [...items];
+            return items.filter((i) => i.status === filter.status);
+        },
+        enqueue(rawItems) {
+            const pendingFingerprints = new Set(items.filter((i) => i.status === 'pending').map((i) => findingFingerprint(i.finding)));
+            const created = [];
+            for (const raw of rawItems) {
+                const fp = findingFingerprint(raw.finding);
+                if (pendingFingerprints.has(fp))
+                    continue;
+                const prior = [...items]
+                    .reverse()
+                    .find((i) => findingFingerprint(i.finding) === fp && i.status === 'resolved');
+                if (prior)
+                    continue;
+                const item = {
+                    id: randomUUID(),
+                    finding: raw.finding,
+                    context: raw.context,
+                    createdAt: new Date().toISOString(),
+                    status: 'pending',
+                };
+                items.push(item);
+                pendingFingerprints.add(fp);
+                created.push(item);
+            }
+            return created;
+        },
+        resolveFlag(id, decision) {
+            const idx = items.findIndex((i) => i.id === id);
+            if (idx < 0)
+                throw new Error(`review queue: unknown flag id ${id}`);
+            const item = items[idx];
+            if (item.status === 'resolved') {
+                throw new Error(`review queue: flag ${id} is already resolved`);
+            }
+            const updated = {
+                ...item,
+                status: 'resolved',
+                resolution: { decision, resolvedAt: new Date().toISOString() },
+            };
+            items = items.map((i, iidx) => (iidx === idx ? updated : i));
+            return updated;
+        },
+        resolutionFor(finding) {
+            const fp = findingFingerprint(finding);
+            const match = [...items]
+                .reverse()
+                .find((i) => findingFingerprint(i.finding) === fp && i.status === 'resolved');
+            return match?.resolution?.decision;
+        },
+    };
+}
+/**
+ * File-backed review queue. Latest write wins per id; fingerprints look at the
+ * newest resolved entry.
+ */
+export function createReviewQueueStore(path = DEFAULT_REVIEW_QUEUE_PATH) {
+    return {
+        listFlagged(filter) {
+            const all = readAll(path);
+            if (!filter?.status)
+                return all;
+            return all.filter((i) => i.status === filter.status);
+        },
+        enqueue(rawItems) {
+            mkdirSync(dirname(path), { recursive: true });
+            const existing = readAll(path);
+            const pendingFingerprints = new Set(existing
+                .filter((i) => i.status === 'pending')
+                .map((i) => findingFingerprint(i.finding)));
+            const created = [];
+            for (const raw of rawItems) {
+                const fp = findingFingerprint(raw.finding);
+                if (pendingFingerprints.has(fp))
+                    continue;
+                // Skip if already resolved for this fingerprint.
+                const prior = [...existing]
+                    .reverse()
+                    .find((i) => findingFingerprint(i.finding) === fp && i.status === 'resolved');
+                if (prior)
+                    continue;
+                const item = {
+                    id: randomUUID(),
+                    finding: raw.finding,
+                    context: raw.context,
+                    createdAt: new Date().toISOString(),
+                    status: 'pending',
+                };
+                appendFileSync(path, `${JSON.stringify(item)}\n`, 'utf8');
+                pendingFingerprints.add(fp);
+                created.push(item);
+            }
+            return created;
+        },
+        resolveFlag(id, decision) {
+            const all = readAll(path);
+            const idx = all.findIndex((i) => i.id === id);
+            if (idx < 0) {
+                throw new Error(`review queue: unknown flag id ${id}`);
+            }
+            const item = all[idx];
+            if (item.status === 'resolved') {
+                throw new Error(`review queue: flag ${id} is already resolved`);
+            }
+            const updated = {
+                ...item,
+                status: 'resolved',
+                resolution: { decision, resolvedAt: new Date().toISOString() },
+            };
+            all[idx] = updated;
+            writeAll(path, all);
+            return updated;
+        },
+        resolutionFor(finding) {
+            const fp = findingFingerprint(finding);
+            const match = [...readAll(path)]
+                .reverse()
+                .find((i) => findingFingerprint(i.finding) === fp && i.status === 'resolved');
+            return match?.resolution?.decision;
+        },
+    };
+}
+/** Convenience exports bound to the default operator-local path. */
+const defaultStore = createReviewQueueStore();
+export function listFlagged(filter) {
+    return defaultStore.listFlagged(filter);
+}
+export function resolveFlag(id, decision) {
+    return defaultStore.resolveFlag(id, decision);
+}
+export function enqueueFlags(items, store = defaultStore) {
+    return store.enqueue(items);
+}
+/**
+ * Thrown when redact-mode scrub leaves unresolved `flag` dispositions.
+ * Unattended publish must not proceed over an open flag (design §6.5).
+ */
+export class UnresolvedFlagError extends Error {
+    findings;
+    queueIds;
+    constructor(findings, queueIds = []) {
+        const n = findings.length;
+        super(`unresolved-flag: ${n} scrub finding(s) require review — publish aborted ` +
+            `(run \`jinn scrub review\` to resolve; ids: ${queueIds.slice(0, 5).join(', ') || 'n/a'})`);
+        this.name = 'UnresolvedFlagError';
+        this.findings = findings;
+        this.queueIds = queueIds;
+    }
+}
+/**
+ * Apply review-queue resolutions to flag findings, enqueue new pending flags,
+ * and optionally fail closed.
+ *
+ * - `approve-instance` / allowlist / identity-pack → treat as pass (no throw)
+ * - `redact-instance` → caller should promote to redact (returned in `toRedact`)
+ * - unresolved → enqueue + throw when `failClosed`
+ */
+export function processFlagFindings(findings, opts = {}) {
+    const policy = opts.policy ?? DEFAULT_POLICY;
+    const store = opts.store ?? defaultStore;
+    const attributes = opts.attributes ?? {};
+    const flagged = findings.filter((f) => resolveDisposition(f.class, f.confidence, policy) === 'flag');
+    const unresolved = [];
+    const toRedact = [];
+    const toPass = [];
+    const toEnqueue = [];
+    for (const finding of flagged) {
+        const decision = store.resolutionFor(finding);
+        if (decision === 'redact-instance') {
+            toRedact.push(finding);
+            continue;
+        }
+        if (decision === 'approve-instance' ||
+            decision === 'add-to-allowlist' ||
+            decision === 'add-to-identity-pack') {
+            toPass.push(finding);
+            continue;
+        }
+        unresolved.push(finding);
+        const value = attributes[finding.span.key];
+        const text = typeof value === 'string' ? value : '';
+        const snippet = text.slice(Math.max(0, finding.span.start - 40), Math.min(text.length, finding.span.end + 40));
+        toEnqueue.push({
+            finding,
+            context: { attributeKey: finding.span.key, snippet },
+        });
+    }
+    const enqueued = toEnqueue.length > 0 ? store.enqueue(toEnqueue) : [];
+    return { unresolved, toRedact, toPass, enqueued };
+}
+/**
+ * Fail closed when unresolved flags remain after {@link processFlagFindings}.
+ */
+export function assertNoUnresolvedFlags(findings, opts = {}) {
+    if (opts.failClosed === false)
+        return;
+    const { unresolved, enqueued } = processFlagFindings(findings, opts);
+    if (unresolved.length === 0)
+        return;
+    throw new UnresolvedFlagError(unresolved, enqueued.map((e) => e.id));
+}

package/dist/scrub/secretlint-stage.d.ts

@@ -0,0 +1,21 @@
+import type { Detector } from './finding.js';
+import { type KeyPolicy } from './key-policy.js';
+import type { ScrubStage } from './types.js';
+/**
+ * Secrets detector. Two passes over each `content`-classified string value:
+ *  1. secretlint preset-recommend rules → A1 findings
+ *  2. Shannon-entropy + secret-shape fallback → A2 findings
+ *
+ * Emits findings only; disposition owns stubs (#1969).
+ */
+export interface SecretlintStageOptions {
+    /**
+     * Gate for the pass-2 Shannon-entropy fallback. Default true. Under the
+     * one-inventory redesign (#1969) every builder leaves this on; the option
+     * remains for unit tests that pin the fallback in isolation.
+     */
+    entropyFallback?: boolean;
+}
+export declare function secretlintDetector(policy: KeyPolicy, opts?: SecretlintStageOptions): Detector;
+/** Legacy ScrubStage wrapper around {@link secretlintDetector}. */
+export declare function secretlintStage(policy: KeyPolicy, opts?: SecretlintStageOptions): ScrubStage;

package/dist/scrub/secretlint-stage.js

@@ -0,0 +1,264 @@
+import { lintSource } from '@secretlint/core';
+import { creator } from '@secretlint/secretlint-rule-preset-recommend';
+import { applyDispositions } from './apply-dispositions.js';
+import { classifyKey } from './key-policy.js';
+const VERSION = '0.5.0'; // 0.5.0: emit findings (#1969); disposition owns stubs
+const PRESET_RULE_ID = '@secretlint/secretlint-rule-preset-recommend';
+// Entropy fallback thresholds. Conservative on purpose: a long token whose
+// character distribution is near-random is almost certainly a key/token, not
+// prose. Tunable; raise the bar if legitimate high-entropy content over-redacts.
+//
+// `ENTROPY_MIN_BITS` stays at 4.0: English prose sits ~4.0–4.5 bits/char, so
+// lowering it below 4.0 globally nukes legitimate prose. `ENTROPY_MIN_LEN` is
+// lowered from 20 → 16 so secret-shaped tokens in the 16–19 char band (which
+// the old 20-char floor never even considered) are caught — but only when they
+// ALSO pass the structural shape gate below, so the longer tail of legit
+// identifiers/words in that band is not swept in. Tokens of length ≥ 20 keep
+// the original entropy-only behaviour (the shape gate does not narrow it).
+const ENTROPY_MIN_LEN = 16;
+const ENTROPY_MIN_BITS = 4.0;
+// Above this length the entropy bar alone decides (original behaviour). Between
+// ENTROPY_MIN_LEN and here the structural shape gate is additionally required.
+const ENTROPY_STRICT_LEN = 20;
+// A "secret-shaped" token: a single run of base64 / base64url / hex charset
+// characters only (letters, digits, and the `+/=_-` set), with NO natural-language
+// punctuation or spaces.
+const SECRET_CHARSET = /^[A-Za-z0-9+/=_-]+$/;
+// Tuning note (#1348): a path-shaped token — slug segments joined by `/`,
+// e.g. `obra/superpowers/skills/test-driven-development` — is judged
+// per-SEGMENT, not whole-token, but ONLY when the whole token mixes at most
+// 2 character classes. Concatenating several short human-readable slugs
+// inflates whole-token Shannon entropy past 4.0 bits/char purely by
+// length/variety, which was redacting seed-import task summaries as
+// `[SECRET:high-entropy]`; real slugs are overwhelmingly lowercase (1–2
+// classes), while secrets that merely contain `/` or `.` (AWS-style base64
+// keys, `dir/<blob>.tar.gz` filenames) almost always mix 3 classes and keep
+// the original whole-token entropy behaviour. The segment charset excludes
+// `+` and `=`, so base64 blobs containing either are never path-shaped.
+// Residual exposure: a secret with ≤ 2 whole-token character classes whose
+// every `[/.]`-split segment is under 16 chars (or below the entropy bar)
+// qualifies as a path and escapes the fallback.
+const PATH_SHAPED = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)+$/;
+// SWE-rebench instance ids are public corpus identifiers (`owner__repo-PR`),
+// not key material. Some short bridge summaries repeat them and otherwise cross
+// the defacement gate after entropy redaction.
+const SWE_REBENCH_INSTANCE_ID = /^[a-z0-9][a-z0-9._-]*__[a-z0-9][a-z0-9._-]*-\d+$/;
+// Tuning note (#1391): the entropy fallback's threat model is ASCII key
+// material — base64 / base64url / hex runs. Natural-language text outside the
+// Latin script (CJK especially) has char-level Shannon entropy far above 4.0
+// bits/char (most characters in a sentence are unique), so whole-token entropy
+// classified ordinary Chinese skill prose as secrets and shredded it. A token
+// whose non-ASCII share exceeds this threshold skips the entropy fallback
+// entirely; the pass-1 secretlint preset rules still run on everything.
+// Residual exposure: a generic (rule-less) secret glued WITHOUT whitespace
+// into a majority-non-ASCII token escapes the fallback — prefixed keys
+// (ghp_…, AKIA…, sk-…) are still caught by pass 1, and CJK prose separates
+// embedded ASCII material with spacing or punctuation in practice.
+const NON_ASCII_MAX_SHARE = 0.3;
+// Tuning note (#1391): a STRUCTURED token — one containing characters outside
+// SECRET_CHARSET, i.e. URLs (`://`, `?`, `&`, `#`), markdown links (`](`),
+// shell interpolations (`${…}`), serialised code — cannot itself be a
+// contiguous key: real key material never contains brackets, quotes or `?`.
+// A key can only be EMBEDDED in such a token as a delimited segment, so the
+// token is judged per-segment (mirroring the #1348 PATH_SHAPED carve-out)
+// instead of by whole-token entropy, which URLs and markdown links inflate
+// past 4.0 bits/char purely by punctuation/length variety (every seed
+// envelope's attribution URL published as [SECRET:high-entropy]).
+// Segments split on everything outside `[A-Za-z0-9+=_-]`: `/` and `.` split
+// (slug and query-string segments stay short and human-readable — matching
+// the PATH gate's `[/.]` split), while `-`, `_`, `+`, `=` stay inside a
+// segment because base64url alphabets and key=value pairs use them
+// (`?key=<blob>` gates as one segment; a JWT's `.`-separated base64url
+// segments gate individually). Residual exposure, same shape as the #1348
+// note: a secret whose every delimited segment falls under 16 chars (or the
+// entropy bar, or a single character class) escapes — e.g. a base64 blob
+// with `/` every few chars additionally wrapped in punctuation.
+const STRUCTURED_SEGMENT_DELIMITER = /[^A-Za-z0-9+=_-]+/;
+// Tuning note (#1391): a "wordish" segment — two or more purely-alphabetic
+// runs joined by `_` or `-` (`Microsoft_Azure_Capacity`, `backend-refactor`)
+// — is an identifier, not key material, even when its length and character
+// variety clear the entropy bar (the Azure portal URL's
+// `Microsoft_Azure_Capacity` sits at 4.002 bits/char). Key material of
+// segment-gate length (≥ 16 chars) drawn from a base64/base64url alphabet
+// contains a digit with ~94% probability and separator-split all-alphabetic
+// runs almost never; the residual all-alpha, separator-structured key is
+// accepted as out of the fallback's reach.
+const WORDISH_SEGMENT = /^[A-Za-z]+([_-][A-Za-z]+)+$/;
+function shannonEntropy(s) {
+    const freq = {};
+    for (const ch of s)
+        freq[ch] = (freq[ch] ?? 0) + 1;
+    let e = 0;
+    for (const count of Object.values(freq)) {
+        const p = count / s.length;
+        e -= p * Math.log2(p);
+    }
+    return e;
+}
+/** Count distinct character classes present (lowercase / uppercase / digit). */
+function charClassCount(s) {
+    let n = 0;
+    if (/[a-z]/.test(s))
+        n += 1;
+    if (/[A-Z]/.test(s))
+        n += 1;
+    if (/[0-9]/.test(s))
+        n += 1;
+    return n;
+}
+function isSweRebenchInstanceId(token) {
+    return SWE_REBENCH_INSTANCE_ID.test(token);
+}
+/**
+ * Decide whether a single whitespace-delimited token should be redacted as a
+ * high-entropy / secret-shaped value. Purely additive over the original rule:
+ *  - length ≥ ENTROPY_STRICT_LEN (20): entropy bar alone (unchanged behaviour),
+ *  - ENTROPY_MIN_LEN (16) ≤ length < 20: entropy bar AND the structural shape
+ *    gate — the token must be a single secret-charset run mixing ≥ 2 character
+ *    classes (so dictionary words + a trailing suffix like `authentication123`,
+ *    which sit below 4.0 bits/char anyway, are not swept in).
+ * Never fires below ENTROPY_MIN_LEN.
+ *
+ * Path carve-out (#1348): a PATH_SHAPED token whose WHOLE-token character-
+ * class count is ≤ 2 is redacted only when at least one `[/.]`-delimited
+ * segment independently passes the strict shape gate (length ≥
+ * ENTROPY_MIN_LEN, entropy ≥ ENTROPY_MIN_BITS, secret charset, ≥ 2 character
+ * classes) — applied at ALL lengths, so a long path of short slugs never
+ * trips the whole-token entropy bar, while a real key embedded as a path
+ * segment (`api/v1/ghp_…`) still redacts. A path-shaped token mixing ≥ 3
+ * whole-token classes never takes the carve-out — real slugs are 1–2
+ * classes, and 3-class "paths" are secrets wearing slashes/dots (#1348
+ * review finding) — it falls through to the whole-token logic below.
+ * Splitting on dots as well as slashes means a sentence full stop or a file
+ * extension yields its own (failing) segment instead of poisoning the
+ * secret blob next to it. Non-path tokens are unaffected.
+ *
+ * #1391 additions, checked in order:
+ *  - a non-ASCII-dominant token (share > NON_ASCII_MAX_SHARE) is prose in a
+ *    non-Latin script, not ASCII key material — never entropy-gated;
+ *  - a structured token (any character outside SECRET_CHARSET: URLs,
+ *    markdown links, shell interpolations) is judged per delimited segment
+ *    via the same strict gate as path segments — see the
+ *    STRUCTURED_SEGMENT_DELIMITER tuning note.
+ * Pure SECRET_CHARSET runs keep the original whole-token behaviour.
+ */
+function isSecretShapedToken(token) {
+    if (token.length < ENTROPY_MIN_LEN)
+        return false;
+    if (nonAsciiShare(token) > NON_ASCII_MAX_SHARE)
+        return false;
+    if (isSweRebenchInstanceId(token))
+        return false;
+    if (PATH_SHAPED.test(token) && charClassCount(token) <= 2) {
+        return token.split(/[/.]/).some(passesStrictSegmentGate);
+    }
+    if (!SECRET_CHARSET.test(token)) {
+        // Structured token (#1391) — URL, markdown link, shell interpolation…
+        // A contiguous key can only live inside a delimited segment.
+        return token.split(STRUCTURED_SEGMENT_DELIMITER).some(passesStrictSegmentGate);
+    }
+    if (shannonEntropy(token) < ENTROPY_MIN_BITS)
+        return false;
+    if (token.length >= ENTROPY_STRICT_LEN)
+        return true;
+    return charClassCount(token) >= 2;
+}
+/**
+ * The strict per-segment gate shared by the PATH_SHAPED (#1348) and
+ * structured-token (#1391) carve-outs: a segment is secret-shaped only when
+ * it is ≥ ENTROPY_MIN_LEN chars, clears the entropy bar, is a single
+ * secret-charset run, and mixes ≥ 2 character classes.
+ */
+function passesStrictSegmentGate(segment) {
+    return (segment.length >= ENTROPY_MIN_LEN &&
+        !WORDISH_SEGMENT.test(segment) &&
+        shannonEntropy(segment) >= ENTROPY_MIN_BITS &&
+        SECRET_CHARSET.test(segment) &&
+        charClassCount(segment) >= 2);
+}
+/** Share of characters outside the 7-bit ASCII range (by code point). */
+function nonAsciiShare(s) {
+    let n = 0;
+    let total = 0;
+    for (const ch of s) {
+        total += 1;
+        if ((ch.codePointAt(0) ?? 0) > 0x7f)
+            n += 1;
+    }
+    return total === 0 ? 0 : n / total;
+}
+/** Short label from a secretlint ruleId, e.g. `@secretlint/secretlint-rule-github` → `github`. */
+function shortRule(ruleId) {
+    return ruleId.replace(/^@secretlint\/secretlint-rule-/, '').replace(/^@secretlint\//, '');
+}
+// #1378 cosmetic: a `\S+` token inside serialised JSON drags its wrapping
+// delimiters along (`"…/blob",` is one whitespace-delimited token), so
+// replacing the whole token swallowed the quotes/comma and left malformed
+// JSON (`"resolved_path": [SECRET:high-entropy] "files_modified": …`). Split
+// each token into leading punctuation / core / trailing punctuation, gate on
+// the core, and reattach the punctuation around the placeholder. None of the
+// stripped characters belong to SECRET_CHARSET (`=` deliberately excluded —
+// base64 padding), so no secret material is ever preserved; if anything,
+// stripping the wrapper improves detection (the 16–19 char shape gate
+// previously failed on quoted tokens because the quotes broke the charset).
+const TOKEN_WRAPPING = /^([("'`[{,;:]*)([\s\S]*?)([)"'`\]},;:.]*)$/;
+export function secretlintDetector(policy, opts = {}) {
+    const entropyFallback = opts.entropyFallback ?? true;
+    const config = { rules: [{ id: PRESET_RULE_ID, rule: creator }] };
+    const meta = { name: 'secretlint', version: VERSION };
+    return {
+        ...meta,
+        async detect(attributes) {
+            const findings = [];
+            for (const [key, value] of Object.entries(attributes)) {
+                if (typeof value !== 'string' || classifyKey(key, policy) !== 'content')
+                    continue;
+                const result = await lintSource({
+                    source: { filePath: '/span', content: value, ext: '.txt', contentType: 'text' },
+                    options: { config },
+                });
+                for (const m of result.messages) {
+                    const label = shortRule(m.ruleId);
+                    findings.push({
+                        class: 'A1',
+                        span: { key, start: m.range[0], end: m.range[1] },
+                        confidence: 'VERY_HIGH',
+                        evidence: [`secret:${label}`],
+                        detector: meta,
+                    });
+                }
+                if (!entropyFallback)
+                    continue;
+                const tokenRe = /\S+/g;
+                let tokenMatch;
+                while ((tokenMatch = tokenRe.exec(value)) !== null) {
+                    const token = tokenMatch[0];
+                    const [, lead = '', core = token] = TOKEN_WRAPPING.exec(token) ?? [];
+                    if (!isSecretShapedToken(core))
+                        continue;
+                    const coreStart = tokenMatch.index + lead.length;
+                    findings.push({
+                        class: 'A2',
+                        span: { key, start: coreStart, end: coreStart + core.length },
+                        confidence: 'HIGH',
+                        evidence: ['secret:high-entropy'],
+                        detector: meta,
+                    });
+                }
+            }
+            return findings;
+        },
+    };
+}
+/** Legacy ScrubStage wrapper around {@link secretlintDetector}. */
+export function secretlintStage(policy, opts = {}) {
+    const detector = secretlintDetector(policy, opts);
+    return {
+        name: detector.name,
+        version: detector.version,
+        async scrub(attributes) {
+            const findings = await detector.detect(attributes);
+            return applyDispositions(attributes, findings);
+        },
+    };
+}

package/dist/scrub/transformers-detector.d.ts

@@ -0,0 +1,41 @@
+import type { PiiDetector, PiiEntity } from './ml-pii-stage.js';
+/**
+ * Legacy Transformers.js NER model. Retired as the default ML path in #1973
+ * (replaced by GLiNER via {@link GlinerPiiDetector}). Kept for unit tests and
+ * explicit opt-in via a custom {@link PiiDetectorFactoryPort}.
+ */
+export declare const DEFAULT_NER_MODEL = "Xenova/bert-base-NER";
+/**
+ * Entity groups treated as PII. Deterministic detectors own email/card/SSN
+ * shapes; this legacy NER tier only covers free-text PER/ORG/LOC. MISC is
+ * excluded (noisy).
+ */
+export declare const DEFAULT_PII_ENTITY_GROUPS: string[];
+export interface TransformersPiiDetectorOptions {
+    model?: string;
+    /** Minimum NER confidence to redact (0–1). */
+    threshold?: number;
+    /** Entity groups to treat as PII. */
+    entityGroups?: string[];
+}
+/**
+ * Legacy Transformers.js NER detector (bert-base-NER). Not the default path —
+ * production uses {@link GlinerPiiDetector}. Retained for tests and explicit
+ * factory injection.
+ */
+export declare class TransformersPiiDetector implements PiiDetector {
+    private pipe;
+    private initPromise;
+    private readonly model;
+    private readonly threshold;
+    private readonly entityGroups;
+    constructor(opts?: TransformersPiiDetectorOptions);
+    /** Model id for the policy hash (#1974). */
+    get modelId(): string;
+    /** Entity-group label set for the policy hash (#1974). */
+    get labelSet(): readonly string[];
+    /** Eagerly load the model (e.g. at daemon boot) so the first publish isn't slow. */
+    init(): Promise<void>;
+    private ensureReady;
+    detect(text: string): Promise<PiiEntity[]>;
+}

package/dist/scrub/transformers-detector.js

@@ -0,0 +1,77 @@
+/**
+ * Legacy Transformers.js NER model. Retired as the default ML path in #1973
+ * (replaced by GLiNER via {@link GlinerPiiDetector}). Kept for unit tests and
+ * explicit opt-in via a custom {@link PiiDetectorFactoryPort}.
+ */
+export const DEFAULT_NER_MODEL = 'Xenova/bert-base-NER';
+/**
+ * Entity groups treated as PII. Deterministic detectors own email/card/SSN
+ * shapes; this legacy NER tier only covers free-text PER/ORG/LOC. MISC is
+ * excluded (noisy).
+ */
+export const DEFAULT_PII_ENTITY_GROUPS = ['PER', 'ORG', 'LOC'];
+/**
+ * Legacy Transformers.js NER detector (bert-base-NER). Not the default path —
+ * production uses {@link GlinerPiiDetector}. Retained for tests and explicit
+ * factory injection.
+ */
+export class TransformersPiiDetector {
+    pipe;
+    initPromise;
+    model;
+    threshold;
+    entityGroups;
+    constructor(opts = {}) {
+        this.model = opts.model ?? DEFAULT_NER_MODEL;
+        this.threshold = opts.threshold ?? 0.6;
+        this.entityGroups = new Set(opts.entityGroups ?? DEFAULT_PII_ENTITY_GROUPS);
+    }
+    /** Model id for the policy hash (#1974). */
+    get modelId() {
+        return this.model;
+    }
+    /** Entity-group label set for the policy hash (#1974). */
+    get labelSet() {
+        return [...this.entityGroups].sort((a, b) => a.localeCompare(b));
+    }
+    /** Eagerly load the model (e.g. at daemon boot) so the first publish isn't slow. */
+    async init() {
+        await this.ensureReady();
+    }
+    ensureReady() {
+        if (this.pipe)
+            return Promise.resolve(this.pipe);
+        if (!this.initPromise) {
+            this.initPromise = (async () => {
+                const { pipeline } = await import('@huggingface/transformers');
+                const pipe = (await pipeline('token-classification', this.model));
+                this.pipe = pipe;
+                return pipe;
+            })();
+        }
+        return this.initPromise;
+    }
+    async detect(text) {
+        if (!text.trim())
+            return [];
+        const pipe = await this.ensureReady();
+        const results = await pipe(text, { aggregation_strategy: 'simple' });
+        const out = [];
+        const seen = new Set();
+        for (const r of results) {
+            if (r.score < this.threshold)
+                continue;
+            if (!this.entityGroups.has(r.entity_group))
+                continue;
+            const t = r.word.trim();
+            if (!t)
+                continue;
+            const key = `${r.entity_group}:${t}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ label: r.entity_group, text: t, score: r.score });
+        }
+        return out;
+    }
+}