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

package/dist/scrub/provenance.js

@@ -0,0 +1,83 @@
+/**
+ * Scrub provenance for the published redaction manifest (#1974 / design §6.7).
+ *
+ * Locked Q5: additive optional fields on the existing redaction-manifest shape
+ * (`schemaVersion` 2) — no TraceEnvelope rev. Old envelopes remain readable.
+ */
+import { sha256 } from '@noble/hashes/sha2.js';
+import { bytesToHex } from '@noble/hashes/utils.js';
+import { canonicalJson } from '../canonical-json.js';
+/** Manifest schema version that includes optional provenance fields. */
+export const REDACTION_MANIFEST_SCHEMA_VERSION = 2;
+/**
+ * Stable key for one class × applied disposition in `perClassCounts`.
+ * Reject-publish dispositions are recorded as `reject`.
+ */
+export function perClassCountKey(scrubClass, disposition) {
+    return `${scrubClass}:${disposition}`;
+}
+/** Map a policy disposition onto the counted kind (or null for pass). */
+export function countedDisposition(disposition) {
+    if (disposition === 'pass')
+        return null;
+    if (disposition === 'reject-publish')
+        return 'reject';
+    return disposition;
+}
+/**
+ * sha256 hex over a canonical JSON of allowlist entries sorted by
+ * (value, kind). Provenance notes are excluded so the digest is about
+ * *what* is allowlisted, not the human rationale string.
+ */
+export function computeAllowlistDigest(entries) {
+    const normalized = [...entries]
+        .map((e) => ({ value: e.value.toLowerCase(), kind: e.kind }))
+        .sort((a, b) => {
+        const byValue = a.value.localeCompare(b.value);
+        return byValue !== 0 ? byValue : a.kind.localeCompare(b.kind);
+    });
+    return sha256Hex(canonicalJson(normalized));
+}
+/**
+ * Reproducible policy/composition hash: same inputs → same hex digest.
+ * Payload is RFC 8785 canonical JSON of policy + sorted detectors + model
+ * id + sorted labels + allowlist digest, then sha256.
+ */
+export function computePolicyHash(input) {
+    const detectors = [...input.detectors]
+        .map((d) => ({ name: d.name, version: d.version }))
+        .sort((a, b) => {
+        const byName = a.name.localeCompare(b.name);
+        return byName !== 0 ? byName : a.version.localeCompare(b.version);
+    });
+    const labels = [...input.labels].sort((a, b) => a.localeCompare(b));
+    const payload = {
+        allowlistDigest: input.allowlistDigest,
+        detectors,
+        labels,
+        modelId: input.modelId,
+        policy: input.policy,
+    };
+    return sha256Hex(canonicalJson(payload));
+}
+/** Increment one class:disposition counter (mutates `counts`). */
+export function incrementPerClassCount(counts, scrubClass, disposition) {
+    const kind = countedDisposition(disposition);
+    if (!kind)
+        return;
+    const key = perClassCountKey(scrubClass, kind);
+    counts[key] = (counts[key] ?? 0) + 1;
+}
+/** Sum two per-class count maps (missing → empty). */
+export function mergePerClassCounts(a, b) {
+    if (!a && !b)
+        return undefined;
+    const out = { ...(a ?? {}) };
+    for (const [key, n] of Object.entries(b ?? {})) {
+        out[key] = (out[key] ?? 0) + n;
+    }
+    return out;
+}
+function sha256Hex(utf8) {
+    return bytesToHex(sha256(new TextEncoder().encode(utf8)));
+}

package/dist/scrub/reject-classes-detector.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Reject-publish content detectors — A4 / content-A5 (#1972 / design §3.2).
+ *
+ * A4: 64-hex private-key material in key context; BIP-39 12/24-word mnemonic runs.
+ * A5: env-block dumps (`KEY=value` line runs inside tool output).
+ *
+ * Bare git SHAs (40-hex) and `0x`+64 tx digests are carved out — never swept.
+ */
+import { type KeyPolicy } from './key-policy.js';
+import type { Detector } from './finding.js';
+export declare function rejectClassesDetector(policy: KeyPolicy): Detector;

package/dist/scrub/reject-classes-detector.js

@@ -0,0 +1,195 @@
+/**
+ * Reject-publish content detectors — A4 / content-A5 (#1972 / design §3.2).
+ *
+ * A4: 64-hex private-key material in key context; BIP-39 12/24-word mnemonic runs.
+ * A5: env-block dumps (`KEY=value` line runs inside tool output).
+ *
+ * Bare git SHAs (40-hex) and `0x`+64 tx digests are carved out — never swept.
+ */
+import { BIP39_ENGLISH } from './data/bip39-english.js';
+import { classifyKey } from './key-policy.js';
+const VERSION = '1.0.0';
+let bip39Words = null;
+function loadBip39() {
+    if (bip39Words)
+        return bip39Words;
+    bip39Words = new Set(BIP39_ENGLISH);
+    return bip39Words;
+}
+/**
+ * Keywords that put a nearby 64-hex run in private-key context.
+ * Deliberately excludes bare "key" / "hash" / "digest" / "sha".
+ */
+const KEY_CONTEXT = /\b(?:private[_\s-]?key|privkey|secret[_\s-]?key|wallet[_\s-]?key|eth(?:ereum)?[_\s-]?private|signing[_\s-]?key|hex[_\s-]?(?:private|secret)|mnemonic|seed[_\s-]?phrase|xprv|wif)\b/i;
+/** Optional 0x-prefixed or bare 64-hex. */
+const HEX64 = /\b(?:0x)?([a-fA-F0-9]{64})\b/g;
+/** ENV-style assignment line. */
+const ENV_LINE = /^[A-Z][A-Z0-9_]*=.*$/;
+const ENV_KEY = /^([A-Z][A-Z0-9_]*)=/;
+/** Git's GIT_CONFIG_* override tutorial shape — not a secret dump (#2005). */
+const GIT_CONFIG_ENV_KEY = /^GIT_CONFIG(?:_|$)/i;
+const MIN_ENV_RUN = 3;
+export function rejectClassesDetector(policy) {
+    const meta = { name: 'reject-classes', version: VERSION };
+    const wordlist = loadBip39();
+    return {
+        ...meta,
+        detect(attributes) {
+            const findings = [];
+            for (const [key, value] of Object.entries(attributes)) {
+                if (typeof value !== 'string' || classifyKey(key, policy) !== 'content')
+                    continue;
+                findings.push(...scanPrivateKeys(value, key, meta));
+                findings.push(...scanMnemonics(value, key, meta, wordlist));
+                findings.push(...scanEnvBlocks(value, key, meta));
+            }
+            return findings;
+        },
+    };
+}
+function scanPrivateKeys(text, key, detector) {
+    if (!KEY_CONTEXT.test(text))
+        return [];
+    // Reset lastIndex after .test on global-less regex — KEY_CONTEXT has /i only.
+    const findings = [];
+    const re = new RegExp(HEX64.source, HEX64.flags);
+    let m;
+    while ((m = re.exec(text)) !== null) {
+        const full = m[0];
+        // Carve-out: 0x+64 is a tx digest (C2), not a private key span by shape alone.
+        // Only fire when the match is bare 64-hex (no 0x) — wallet hex keys are typically
+        // written without the 0x prefix next to "private key" context, while receipts use 0x.
+        if (full.startsWith('0x') || full.startsWith('0X'))
+            continue;
+        // Windowed context: require a key-context keyword within ±80 chars.
+        const windowStart = Math.max(0, m.index - 80);
+        const windowEnd = Math.min(text.length, m.index + full.length + 80);
+        const window = text.slice(windowStart, windowEnd);
+        if (!KEY_CONTEXT.test(window))
+            continue;
+        findings.push({
+            class: 'A4',
+            span: { key, start: m.index, end: m.index + full.length },
+            confidence: 'VERY_HIGH',
+            evidence: ['private-key-hex64'],
+            detector,
+        });
+    }
+    return findings;
+}
+function scanMnemonics(text, key, detector, wordlist) {
+    const findings = [];
+    // Tokenize on whitespace / commas / quotes while keeping offsets.
+    const tokenRe = /[A-Za-z]+/g;
+    const tokens = [];
+    let tm;
+    while ((tm = tokenRe.exec(text)) !== null) {
+        tokens.push({
+            word: tm[0].toLowerCase(),
+            start: tm.index,
+            end: tm.index + tm[0].length,
+        });
+    }
+    let i = 0;
+    while (i < tokens.length) {
+        if (!wordlist.has(tokens[i].word)) {
+            i += 1;
+            continue;
+        }
+        let j = i;
+        while (j < tokens.length && wordlist.has(tokens[j].word))
+            j += 1;
+        const runTokens = tokens.slice(i, j);
+        // Sliding windows: a longer wordlist run (e.g. "phrase" + 12 mnemonic words)
+        // still contains a 12/24 mnemonic.
+        for (const len of [24, 12]) {
+            if (runTokens.length < len)
+                continue;
+            for (let start = 0; start + len <= runTokens.length; start += 1) {
+                const window = runTokens.slice(start, start + len);
+                let contiguous = true;
+                for (let k = 0; k < window.length - 1; k += 1) {
+                    const gap = text.slice(window[k].end, window[k + 1].start);
+                    if (!/^[\s,;|"']+$/.test(gap)) {
+                        contiguous = false;
+                        break;
+                    }
+                }
+                if (!contiguous)
+                    continue;
+                findings.push({
+                    class: 'A4',
+                    span: { key, start: window[0].start, end: window[len - 1].end },
+                    confidence: 'VERY_HIGH',
+                    evidence: [`bip39-mnemonic-${len}`],
+                    detector,
+                });
+                // One hit per run length is enough — avoid overlapping spam.
+                break;
+            }
+        }
+        i = j;
+    }
+    return findings;
+}
+function scanEnvBlocks(text, key, detector) {
+    const findings = [];
+    const lines = text.split('\n');
+    let offset = 0;
+    let runStart = -1;
+    let runStartOffset = 0;
+    let runEndOffset = 0;
+    let runCount = 0;
+    const flush = () => {
+        if (runCount >= MIN_ENV_RUN && runStart >= 0) {
+            findings.push({
+                class: 'A5',
+                span: { key, start: runStartOffset, end: runEndOffset },
+                confidence: 'VERY_HIGH',
+                evidence: ['env-block'],
+                detector,
+            });
+        }
+        runStart = -1;
+        runCount = 0;
+    };
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        const lineLen = line.length + (i < lines.length - 1 ? 1 : 0); // +1 for \n except last
+        const trimmed = line.trim();
+        // Allow optional leading export / whitespace.
+        const candidate = trimmed.replace(/^export\s+/, '');
+        if (isEnvBlockAssignment(candidate)) {
+            if (runStart < 0) {
+                runStart = i;
+                runStartOffset = offset + (line.length - line.trimStart().length);
+            }
+            runCount += 1;
+            runEndOffset = offset + line.length;
+        }
+        else if ((trimmed === '' || isGitConfigEnvAssignment(candidate)) && runCount > 0) {
+            // Blank and GIT_CONFIG tutorial lines inside a dump keep the run open,
+            // but do not increment it — only flush on another non-env line.
+        }
+        else {
+            flush();
+        }
+        offset += lineLen;
+    }
+    flush();
+    return findings;
+}
+function isEnvBlockAssignment(candidate) {
+    if (!ENV_LINE.test(candidate))
+        return false;
+    const keyMatch = ENV_KEY.exec(candidate);
+    if (!keyMatch)
+        return false;
+    return !GIT_CONFIG_ENV_KEY.test(keyMatch[1]);
+}
+function isGitConfigEnvAssignment(candidate) {
+    if (!ENV_LINE.test(candidate))
+        return false;
+    const keyMatch = ENV_KEY.exec(candidate);
+    return keyMatch !== null && GIT_CONFIG_ENV_KEY.test(keyMatch[1]);
+}

package/dist/scrub/reject-publish-error.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Loud abort for reject-publish disposition (#1972 / design §3.2 A4/A5).
+ *
+ * Catastrophic content must fail closed with a class-named error — never
+ * silent redact-and-continue.
+ */
+import type { Finding, ScrubClass } from './finding.js';
+import { type PolicyTable } from './policy.js';
+export declare class RejectPublishError extends Error {
+    readonly scrubClass: ScrubClass;
+    readonly findings: Finding[];
+    constructor(scrubClass: ScrubClass, findings?: Finding[]);
+}
+/**
+ * Findings whose policy disposition is reject-publish.
+ *
+ * A5 `drop-key` findings are structural removals, not catastrophic content:
+ * the key-policy detector has already removed the entire attribute before
+ * this guard runs. Only content-level A5 findings (such as an env-block
+ * embedded in tool output) must abort the publish.
+ */
+export declare function rejectPublishFindings(findings: Finding[] | undefined, policy?: PolicyTable): Finding[];
+/**
+ * Throw a class-named {@link RejectPublishError} when reject-publish fired.
+ * No-op when the result only has ordinary redacts / check-mode rejects.
+ */
+export declare function assertNoRejectPublish(result: {
+    rejected?: boolean;
+    findings?: Finding[];
+}, policy?: PolicyTable): void;

package/dist/scrub/reject-publish-error.js

@@ -0,0 +1,47 @@
+/**
+ * Loud abort for reject-publish disposition (#1972 / design §3.2 A4/A5).
+ *
+ * Catastrophic content must fail closed with a class-named error — never
+ * silent redact-and-continue.
+ */
+import { resolveDisposition } from './policy.js';
+import { DEFAULT_POLICY } from './policy.js';
+export class RejectPublishError extends Error {
+    scrubClass;
+    findings;
+    constructor(scrubClass, findings = []) {
+        const evidence = findings[0]?.evidence?.join(', ') ?? scrubClass;
+        super(`reject-publish: scrub class ${scrubClass} — publish aborted (${evidence})`);
+        this.name = 'RejectPublishError';
+        this.scrubClass = scrubClass;
+        this.findings = findings;
+    }
+}
+/**
+ * Findings whose policy disposition is reject-publish.
+ *
+ * A5 `drop-key` findings are structural removals, not catastrophic content:
+ * the key-policy detector has already removed the entire attribute before
+ * this guard runs. Only content-level A5 findings (such as an env-block
+ * embedded in tool output) must abort the publish.
+ */
+export function rejectPublishFindings(findings, policy = DEFAULT_POLICY) {
+    if (!findings?.length)
+        return [];
+    return findings.filter((f) => !f.evidence.includes('drop-key') &&
+        resolveDisposition(f.class, f.confidence, policy) === 'reject-publish');
+}
+/**
+ * Throw a class-named {@link RejectPublishError} when reject-publish fired.
+ * No-op when the result only has ordinary redacts / check-mode rejects.
+ */
+export function assertNoRejectPublish(result, policy = DEFAULT_POLICY) {
+    const hits = rejectPublishFindings(result.findings, policy);
+    if (hits.length === 0)
+        return;
+    // Prefer A4 over A5 when both fire (funds-controlling material first).
+    const primary = hits.find((f) => f.class === 'A4') ??
+        hits.find((f) => f.class === 'A5') ??
+        hits[0];
+    throw new RejectPublishError(primary.class, hits.filter((f) => f.class === primary.class));
+}

package/dist/scrub/review-queue.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 type { Finding } from './finding.js';
+import { type PolicyTable } from './policy.js';
+export type ReviewDecision = 'approve-instance' | 'redact-instance' | 'add-to-allowlist' | 'add-to-identity-pack';
+export type ReviewItemStatus = 'pending' | 'resolved';
+export interface ReviewQueueItem {
+    id: string;
+    finding: Finding;
+    context: {
+        attributeKey: string;
+        snippet: string;
+    };
+    createdAt: string;
+    status: ReviewItemStatus;
+    resolution?: {
+        decision: ReviewDecision;
+        resolvedAt: string;
+    };
+}
+export interface ReviewQueueStore {
+    listFlagged(filter?: {
+        status?: ReviewItemStatus;
+    }): ReviewQueueItem[];
+    resolveFlag(id: string, decision: ReviewDecision): ReviewQueueItem;
+    enqueue(items: Array<Omit<ReviewQueueItem, 'id' | 'createdAt' | 'status'>>): ReviewQueueItem[];
+    /** Fingerprint → latest resolved decision (if any). */
+    resolutionFor(finding: Finding): ReviewDecision | undefined;
+}
+export declare const DEFAULT_REVIEW_QUEUE_PATH: string;
+/** Stable fingerprint for matching a finding across scrub runs. */
+export declare function findingFingerprint(finding: Finding): string;
+/** In-memory review queue for unit tests (no disk I/O). */
+export declare function createMemoryReviewQueueStore(seed?: ReviewQueueItem[]): ReviewQueueStore;
+/**
+ * File-backed review queue. Latest write wins per id; fingerprints look at the
+ * newest resolved entry.
+ */
+export declare function createReviewQueueStore(path?: string): ReviewQueueStore;
+export declare function listFlagged(filter?: {
+    status?: ReviewItemStatus;
+}): ReviewQueueItem[];
+export declare function resolveFlag(id: string, decision: ReviewDecision): ReviewQueueItem;
+export declare function enqueueFlags(items: Array<Omit<ReviewQueueItem, 'id' | 'createdAt' | 'status'>>, store?: ReviewQueueStore): ReviewQueueItem[];
+/**
+ * Thrown when redact-mode scrub leaves unresolved `flag` dispositions.
+ * Unattended publish must not proceed over an open flag (design §6.5).
+ */
+export declare class UnresolvedFlagError extends Error {
+    readonly findings: Finding[];
+    readonly queueIds: string[];
+    constructor(findings: Finding[], queueIds?: string[]);
+}
+export interface FlagDispositionOptions {
+    policy?: PolicyTable;
+    /** Attributes bag used to build review-queue context snippets. */
+    attributes?: Record<string, unknown>;
+    store?: ReviewQueueStore;
+    /**
+     * When true (default for redact-mode publish), enqueue + throw if any flag
+     * remains unresolved. Check-mode distill sets this false (rejection is via
+     * redactions / rejected bit instead).
+     */
+    failClosed?: boolean;
+}
+/**
+ * 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 declare function processFlagFindings(findings: Finding[], opts?: FlagDispositionOptions): {
+    unresolved: Finding[];
+    toRedact: Finding[];
+    toPass: Finding[];
+    enqueued: ReviewQueueItem[];
+};
+/**
+ * Fail closed when unresolved flags remain after {@link processFlagFindings}.
+ */
+export declare function assertNoUnresolvedFlags(findings: Finding[], opts?: FlagDispositionOptions): void;