@jinn-network/core 0.1.0 → 0.1.1-canary.7b188db5

package/dist/corpus-read/ipfs.d.ts

@@ -1,5 +1,14 @@
 export declare function normalizeIpfsGatewayBase(gatewayUrl: string): string;
 export declare function buildIpfsHexCidCandidatesFromPartialHex(hex: string): string[];
 export declare function buildIpfsFetchCidPathCandidates(cidOrPath: string): string[];
+export type FetchFromIpfsOptions = {
+    /**
+     * Extra gateway base after the primary fails.
+     * - omit / undefined → production default `https://ipfs.io/ipfs/`
+     * - false → primary gateway only (hermetic / pinned rigs)
+     * - string → alternate fallback (normalized via `normalizeIpfsGatewayBase`)
+     */
+    fallbackGatewayBase?: string | false;
+};
 /** Read-only multi-codec, primary-plus-fallback IPFS JSON fetch. */
-export declare function fetchFromIpfs(gatewayUrl: string, cid: string): Promise<unknown>;
+export declare function fetchFromIpfs(gatewayUrl: string, cid: string, opts?: FetchFromIpfsOptions): Promise<unknown>;

package/dist/corpus-read/ipfs.js

@@ -45,15 +45,24 @@ async function fetchJson(url, signal) {
         throw new Error(`IPFS response is not JSON (content-type: ${contentType || 'none'})`);
     }
 }
+function resolveFallbackGatewayBases(opts) {
+    if (opts?.fallbackGatewayBase === false)
+        return [];
+    if (typeof opts?.fallbackGatewayBase === 'string') {
+        return [['fallback', normalizeIpfsGatewayBase(opts.fallbackGatewayBase)]];
+    }
+    return [['fallback', FALLBACK_IPFS_GATEWAY_BASE]];
+}
 /** Read-only multi-codec, primary-plus-fallback IPFS JSON fetch. */
-export async function fetchFromIpfs(gatewayUrl, cid) {
+export async function fetchFromIpfs(gatewayUrl, cid, opts) {
     const primary = normalizeIpfsGatewayBase(gatewayUrl);
+    const gateways = [
+        ['primary', primary],
+        ...resolveFallbackGatewayBases(opts),
+    ];
     const errors = [];
     for (const cidPath of buildIpfsFetchCidPathCandidates(cid)) {
-        for (const [name, baseUrl] of [
-            ['primary', primary],
-            ['fallback', FALLBACK_IPFS_GATEWAY_BASE],
-        ]) {
+        for (const [name, baseUrl] of gateways) {
             const url = `${baseUrl}${cidPath}`;
             const controller = new AbortController();
             const timer = setTimeout(() => controller.abort(), IPFS_FETCH_TIMEOUT_MS);

package/dist/scrub/apply-dispositions.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Apply policy dispositions to an attribute bag after one detection pass
+ * (#1969 / design §6.5).
+ */
+import type { Finding } from './finding.js';
+import { type PolicyTable } from './policy.js';
+import { type ReviewQueueStore } from './review-queue.js';
+import type { Attributes, RedactionRecord } from './types.js';
+export { RejectPublishError, assertNoRejectPublish, rejectPublishFindings } from './reject-publish-error.js';
+export interface ApplyDispositionsOptions {
+    policy?: PolicyTable;
+    /**
+     * Check-mode consumers (layer-2 distill, episode refuse): any non-pass
+     * disposition rejects. Still applies redacts so the body change is visible.
+     */
+    checkMode?: boolean;
+    /**
+     * Optional review-queue store. When provided, resolved flags are honored
+     * (`approve-instance` → pass, `redact-instance` → redact, allowlist /
+     * identity-pack → pass). Unresolved flags stay as `flag` and are listed in
+     * {@link ApplyDispositionsResult.unresolvedFlags}.
+     */
+    reviewStore?: ReviewQueueStore;
+}
+export interface ApplyDispositionsResult {
+    attributes: Attributes;
+    redactions: RedactionRecord[];
+    findings: Finding[];
+    /** True when a reject-publish disposition fired, or check-mode saw a non-pass. */
+    rejected: boolean;
+    /** Flag findings that remain unresolved after consulting the review queue. */
+    unresolvedFlags: Finding[];
+    /**
+     * Applied disposition counts keyed `${ScrubClass}:${redact|flag|reject}`
+     * (#1974). Pass dispositions are omitted.
+     */
+    perClassCounts: Record<string, number>;
+}
+/** Stub text for a redact disposition, keyed by class (+ optional evidence hint). */
+export declare function stubForFinding(finding: Finding, occurrenceIndex: number): string;
+/**
+ * Apply dispositions. Span redacts are applied right-to-left per key so earlier
+ * offsets stay valid. A5 reject-publish on a drop-key finding removes the key.
+ */
+export declare function applyDispositions(attributes: Attributes, findings: Finding[], opts?: ApplyDispositionsOptions): ApplyDispositionsResult;
+/**
+ * Allowlist-pass records are auditable Legibility receipts, not detections.
+ * They must not trip refuse-on-detection / distill check-mode gates.
+ */
+export declare function countsTowardRefusal(record: RedactionRecord): boolean;
+/** Redaction records that imply content was scrubbed or must refuse. */
+export declare function refusalRedactions(redactions: RedactionRecord[]): RedactionRecord[];
+/**
+ * True when publish/check should refuse the item.
+ *
+ * Prefer the explicit `rejected` bit (set by dispositions / check-mode).
+ * Fall back to refusal-relevant redaction records only — never `allowlist-pass`.
+ * For reject-publish classes (A4/A5 content), prefer
+ * {@link assertNoRejectPublish} so the abort is a loud class-named error.
+ * For unresolved flags, prefer {@link assertNoUnresolvedFlags} from
+ * `review-queue.ts`.
+ */
+export declare function shouldRejectPublish(result: {
+    rejected?: boolean;
+    redactions: RedactionRecord[];
+    findings?: Finding[];
+    unresolvedFlags?: Finding[];
+}): boolean;
+/**
+ * Apply dispositions, then abort loudly when a reject-publish class fired.
+ * Use at publish altitude (capture/emit) — not for check-mode distill, which
+ * maps redactions to rejection reasons without throwing.
+ */
+export declare function applyDispositionsOrReject(attributes: Attributes, findings: Finding[], opts?: ApplyDispositionsOptions): ApplyDispositionsResult;

package/dist/scrub/apply-dispositions.js

@@ -0,0 +1,309 @@
+/**
+ * Apply policy dispositions to an attribute bag after one detection pass
+ * (#1969 / design §6.5).
+ */
+import { DEFAULT_POLICY, checkModeRejects, resolveDisposition, } from './policy.js';
+import { incrementPerClassCount } from './provenance.js';
+import { assertNoRejectPublish } from './reject-publish-error.js';
+import { findingFingerprint, } from './review-queue.js';
+export { RejectPublishError, assertNoRejectPublish, rejectPublishFindings } from './reject-publish-error.js';
+/** Stub text for a redact disposition, keyed by class (+ optional evidence hint). */
+export function stubForFinding(finding, occurrenceIndex) {
+    const hint = finding.evidence[0] ?? '';
+    switch (finding.class) {
+        case 'B1':
+            return '[EMAIL]';
+        case 'B2':
+            // Joint carrier: user.email values stub as email; names as NAME.
+            if (hint.includes('email'))
+                return '[EMAIL]';
+            return '[NAME]';
+        case 'D1':
+            return '/users/anon';
+        case 'C1':
+            return `[ETH_ADDR_${occurrenceIndex}]`;
+        case 'B3':
+            return '[NAME]';
+        case 'B4':
+            return '[USERNAME]';
+        case 'D2':
+            return '[IP]';
+        case 'D3':
+            return '[HOSTNAME]';
+        case 'A1':
+            if (hint.includes('aws-access-key-id'))
+                return '[SECRET:aws-access-key-id]';
+            if (hint.includes('gcp-api-key'))
+                return '[SECRET:gcp-api-key]';
+            if (hint.startsWith('secret:'))
+                return `[SECRET:${hint.slice('secret:'.length)}]`;
+            return '[SECRET:redacted]';
+        case 'A2':
+            return '[SECRET:high-entropy]';
+        case 'A3':
+            return '[SECRET:url-credential]';
+        case 'B7':
+            if (hint.includes('iban'))
+                return '[IBAN]';
+            return '[CARD]';
+        default: {
+            if (hint.startsWith('ml:')) {
+                return `[PII:${hint.slice('ml:'.length)}]`;
+            }
+            if (hint.startsWith('gitleaks:')) {
+                return `[SECRET:${hint.slice('gitleaks:'.length)}]`;
+            }
+            const label = hint || finding.class;
+            return `[PII:${label}]`;
+        }
+    }
+}
+function redactionKind(scrubClass, _finding) {
+    if (scrubClass.startsWith('A'))
+        return 'secret';
+    return 'pii';
+}
+function redactionDetail(finding) {
+    const hint = finding.evidence[0] ?? finding.class;
+    if (hint === 'drop-key' || hint === 'machine-identity-key')
+        return undefined;
+    // Normalize C1 to the shipped detail id so seed/trace/layer2 records match.
+    if (finding.class === 'C1')
+        return 'eth-address';
+    if (hint.startsWith('secret:'))
+        return hint.slice('secret:'.length);
+    if (hint.startsWith('gitleaks:'))
+        return hint.slice('gitleaks:'.length);
+    if (hint.startsWith('ml:'))
+        return hint.slice('ml:'.length);
+    return hint;
+}
+function isKeyDropFinding(finding) {
+    return (finding.evidence.includes('drop-key') ||
+        finding.evidence.includes('machine-identity-key'));
+}
+function decisionOverridesFlag(decision) {
+    if (decision === 'redact-instance')
+        return 'redact';
+    if (decision === 'approve-instance' ||
+        decision === 'add-to-allowlist' ||
+        decision === 'add-to-identity-pack') {
+        return 'pass';
+    }
+    return undefined;
+}
+function effectiveDisposition(finding, policy, checkMode, reviewStore) {
+    let disposition = resolveDisposition(finding.class, finding.confidence, policy);
+    if (disposition === 'flag' && reviewStore) {
+        const override = decisionOverridesFlag(reviewStore.resolutionFor(finding));
+        if (override)
+            disposition = override;
+    }
+    if (checkMode && disposition !== 'pass') {
+        // Check-mode still applies the underlying redact/reject action; the
+        // rejected bit is set separately via checkModeRejects.
+        return disposition;
+    }
+    return disposition;
+}
+/**
+ * Apply dispositions. Span redacts are applied right-to-left per key so earlier
+ * offsets stay valid. A5 reject-publish on a drop-key finding removes the key.
+ */
+export function applyDispositions(attributes, findings, opts = {}) {
+    const policy = opts.policy ?? DEFAULT_POLICY;
+    const checkMode = opts.checkMode ?? false;
+    const reviewStore = opts.reviewStore;
+    const out = { ...attributes };
+    const redactions = [];
+    const unresolvedFlags = [];
+    const perClassCounts = {};
+    let rejected = false;
+    // Key-drop findings first (A5 structural drop-key, D3 machine-identity).
+    // Structural key drops remove the attribute; they do NOT reject-publish in
+    // redact-mode (content-level A4/A5 spans own the loud abort). Check-mode
+    // still rejects so distill stays fail-closed on any non-pass.
+    for (const finding of findings) {
+        if (!isKeyDropFinding(finding))
+            continue;
+        const disposition = effectiveDisposition(finding, policy, checkMode, reviewStore);
+        if (disposition === 'pass')
+            continue;
+        delete out[finding.span.key];
+        redactions.push({
+            key: finding.span.key,
+            stage: finding.detector.name,
+            kind: 'dropped-key',
+        });
+        // Structural drops are applied as redacts (key removed), even when the
+        // policy row for A5 content is reject-publish.
+        incrementPerClassCount(perClassCounts, finding.class, 'redact');
+        if (checkMode)
+            rejected = true;
+    }
+    // Group remaining span findings by key, apply right-to-left.
+    const byKey = new Map();
+    for (const finding of findings) {
+        if (isKeyDropFinding(finding))
+            continue;
+        if (!(finding.span.key in out))
+            continue;
+        const list = byKey.get(finding.span.key) ?? [];
+        list.push(finding);
+        byKey.set(finding.span.key, list);
+    }
+    for (const [key, keyFindings] of byKey) {
+        const value = out[key];
+        if (typeof value !== 'string')
+            continue;
+        const sorted = [...keyFindings].sort((a, b) => b.span.start - a.span.start);
+        const covered = [];
+        let text = value;
+        // Collect redact records left-to-right (unshift while applying right-to-left)
+        // so callers that pin redaction order keep a stable, start-ascending list.
+        const redactRecords = [];
+        for (const finding of sorted) {
+            const disposition = effectiveDisposition(finding, policy, checkMode, reviewStore);
+            if (disposition === 'pass') {
+                // Auditable allowlist hit (§6.4): record "we saw it and passed it on
+                // purpose". These must NOT count toward refuse-on-detection /
+                // check-mode rejection (kind `allowlist-pass` is filtered by
+                // {@link countsTowardRefusal}).
+                const allowEvidence = finding.evidence.find((e) => e.startsWith('allowlist:'));
+                if (allowEvidence) {
+                    redactions.push({
+                        key,
+                        stage: finding.detector.name,
+                        kind: 'allowlist-pass',
+                        detail: allowEvidence.slice('allowlist:'.length),
+                    });
+                }
+                continue;
+            }
+            if (disposition === 'reject-publish') {
+                // Always stub the span so A4/A5 plaintext never survives into
+                // check-mode / in-memory capture envelopes; abort is still signaled
+                // via `rejected` + assertNoRejectPublish at publish altitude.
+                rejected = true;
+                const { start, end } = finding.span;
+                if (start >= 0 && end <= text.length && start < end &&
+                    !covered.some((c) => start < c.end && end > c.start)) {
+                    const leftIndex = keyFindings.filter((f) => {
+                        const d = effectiveDisposition(f, policy, checkMode, reviewStore);
+                        return (d === 'redact' || d === 'reject-publish') && f.span.start < start;
+                    }).length;
+                    const stub = stubForFinding(finding, leftIndex);
+                    text = text.slice(0, start) + stub + text.slice(end);
+                    covered.push({ start, end });
+                }
+                redactRecords.unshift({
+                    key,
+                    stage: finding.detector.name,
+                    kind: redactionKind(finding.class, finding),
+                    detail: redactionDetail(finding),
+                });
+                incrementPerClassCount(perClassCounts, finding.class, disposition);
+                continue;
+            }
+            if (disposition === 'flag') {
+                unresolvedFlags.push(finding);
+                incrementPerClassCount(perClassCounts, finding.class, disposition);
+                // In redact-mode leave text (review queue owns the hold). In check-mode,
+                // record so consumers reject.
+                if (checkMode) {
+                    rejected = true;
+                    redactions.push({
+                        key,
+                        stage: finding.detector.name,
+                        kind: 'flag',
+                        detail: redactionDetail(finding),
+                    });
+                }
+                continue;
+            }
+            // redact
+            const { start, end } = finding.span;
+            if (start < 0 || end > text.length || start >= end)
+                continue;
+            if (covered.some((c) => start < c.end && end > c.start))
+                continue;
+            const leftIndex = keyFindings.filter((f) => {
+                if (effectiveDisposition(f, policy, checkMode, reviewStore) !== 'redact')
+                    return false;
+                return f.span.start < start;
+            }).length;
+            const stub = stubForFinding(finding, leftIndex);
+            text = text.slice(0, start) + stub + text.slice(end);
+            covered.push({ start, end });
+            redactRecords.unshift({
+                key,
+                stage: finding.detector.name,
+                kind: redactionKind(finding.class, finding),
+                detail: redactionDetail(finding),
+            });
+            incrementPerClassCount(perClassCounts, finding.class, disposition);
+            if (checkMode)
+                rejected = true;
+        }
+        redactions.push(...redactRecords);
+        out[key] = text;
+    }
+    if (checkMode && checkModeRejects(findings, policy)) {
+        rejected = true;
+    }
+    // Dedupe unresolved flags by fingerprint (nested walks can re-emit).
+    const seen = new Set();
+    const uniqueUnresolved = unresolvedFlags.filter((f) => {
+        const fp = findingFingerprint(f);
+        if (seen.has(fp))
+            return false;
+        seen.add(fp);
+        return true;
+    });
+    return {
+        attributes: out,
+        redactions,
+        findings,
+        rejected,
+        unresolvedFlags: uniqueUnresolved,
+        perClassCounts,
+    };
+}
+/**
+ * Allowlist-pass records are auditable Legibility receipts, not detections.
+ * They must not trip refuse-on-detection / distill check-mode gates.
+ */
+export function countsTowardRefusal(record) {
+    return record.kind !== 'allowlist-pass';
+}
+/** Redaction records that imply content was scrubbed or must refuse. */
+export function refusalRedactions(redactions) {
+    return redactions.filter(countsTowardRefusal);
+}
+/**
+ * True when publish/check should refuse the item.
+ *
+ * Prefer the explicit `rejected` bit (set by dispositions / check-mode).
+ * Fall back to refusal-relevant redaction records only — never `allowlist-pass`.
+ * For reject-publish classes (A4/A5 content), prefer
+ * {@link assertNoRejectPublish} so the abort is a loud class-named error.
+ * For unresolved flags, prefer {@link assertNoUnresolvedFlags} from
+ * `review-queue.ts`.
+ */
+export function shouldRejectPublish(result) {
+    if (result.rejected)
+        return true;
+    if (result.unresolvedFlags && result.unresolvedFlags.length > 0)
+        return true;
+    return refusalRedactions(result.redactions).length > 0;
+}
+/**
+ * Apply dispositions, then abort loudly when a reject-publish class fired.
+ * Use at publish altitude (capture/emit) — not for check-mode distill, which
+ * maps redactions to rejection reasons without throwing.
+ */
+export function applyDispositionsOrReject(attributes, findings, opts = {}) {
+    const applied = applyDispositions(attributes, findings, opts);
+    assertNoRejectPublish(applied, opts.policy ?? DEFAULT_POLICY);
+    return applied;
+}

package/dist/scrub/build.d.ts

@@ -1,6 +1,8 @@
 import { ScrubPipeline } from './pipeline.js';
 import { type KeyPolicy } from './key-policy.js';
 import { type PiiDetector } from './ml-pii-stage.js';
+import { type AssembleKnownIdentityOptions, type AssembledKnownIdentity } from './known-identity-detector.js';
+import type { Detector } from './finding.js';
 /**
  * Default key policy. `jinn.*` identity/chain attributes are structural and pass
  * raw. The `drop` tier deletes the spec's stage-1 high-confidence keys outright
@@ -8,45 +10,66 @@ import { type PiiDetector } from './ml-pii-stage.js';
  * these never carry sellable content and are never safe to publish. Globs use the
  * trailing-`*` prefix form `classifyKey` supports; the HTTP header keys are listed
  * per request/response direction (a leading `*.header.…` glob is not matched, so
- * we enumerate the concrete keys). Everything else is `content` and flows through
- * the value-scrubbing stages.
+ * we enumerate the concrete keys). Machine-identity keys (D3 carrier) drop
+ * attempt-manifest `host` / hostname telemetry. Everything else is `content` and
+ * flows through the value-scrubbing detectors.
  */
 export declare const DEFAULT_KEY_POLICY: KeyPolicy;
 export interface BuildScrubPipelineOptions {
     policy?: KeyPolicy;
-    /** When provided, the ML PII (GLiNER) stage is appended. */
+    /** When provided, the ML PII (GLiNER) detector is appended. */
     piiDetector?: PiiDetector;
+    /** Known-identity pack + non-address allowlist (#1971). */
+    knownIdentity?: AssembleKnownIdentityOptions | AssembledKnownIdentity;
+    /** Review-queue store for flag resolutions (#1973). */
+    reviewStore?: import('./review-queue.js').ReviewQueueStore;
+    /**
+     * When false, unresolved flags do not abort (tests). Default true for
+     * redact-mode publish lanes.
+     */
+    failClosedOnUnresolvedFlags?: boolean;
 }
+export declare function resolveKnownIdentity(opts?: AssembleKnownIdentityOptions | AssembledKnownIdentity): AssembledKnownIdentity;
+/** Build provenance extras from known-identity + optional ML detector (#1974). */
+export declare function buildProvenanceExtras(knownIdentity: AssembledKnownIdentity, piiDetector?: PiiDetector): {
+    modelId: string | null;
+    labels: readonly string[];
+    allowlistDigest: string;
+};
 /**
- * Assembles the seller-side scrub pipeline (cost-ascending): structural key
- * policy → openredaction (structured PII) → secretlint + entropy (secrets) →
- * optional GLiNER (ML PII). The GLiNER stage is added only when a detector is
- * supplied, so the daemon degrades gracefully (regex + secrets still scrub) when
- * the ML model is unavailable.
+ * Shared detector inventory (#1969 / #1970 / #1971 / #1972 / #1973). Every
+ * publish/check consumer runs the same owned detectors (key-policy,
+ * plain-patterns including C1 wallet + A1 credential IDs, git-identity B2
+ * carriers, known-identity pack + non-address allowlist, Tier-1
+ * reject/URL/IP/instruments/gitleaks, secretlint). What varies is disposition /
+ * check-mode and whether an ML PII detector is injected. Seed keeps the entropy
+ * fallback off until A2 mid-band flags are absorbed without refuse-on-detection
+ * (#1409 shipped behavior). openredaction was retired in #1973.
+ */
+export declare function sharedDetectorInventory(policy: KeyPolicy, opts?: {
+    entropyFallback?: boolean;
+    piiDetector?: PiiDetector;
+    knownIdentity?: AssembleKnownIdentityOptions | AssembledKnownIdentity;
+}): Detector[];
+/**
+ * Trace / redact-mode preset over the shared inventory.
+ *
+ * @deprecated Prefer thinking in terms of one inventory + policy; this builder
+ * remains as a compatibility preset through the migration (#1969).
  */
 export declare function buildScrubPipeline(opts?: BuildScrubPipelineOptions): ScrubPipeline;
+export interface BuildSeedScrubPipelineOptions {
+    policy?: KeyPolicy;
+    knownIdentity?: AssembleKnownIdentityOptions | AssembledKnownIdentity;
+    piiDetector?: PiiDetector;
+    reviewStore?: import('./review-queue.js').ReviewQueueStore;
+    failClosedOnUnresolvedFlags?: boolean;
+}
 /**
- * Seed-profile scrub pipeline (#1409). Seeds are public, transformed or
- * otherwise human-curated content — not operator trace data — so the
- * probabilistic stages (openredaction, secretlint's pass-2 entropy fallback,
- * ML PII) that exist to catch unknown-shape PII/secrets in private traces are
- * dropped: on prose they false-positive (trigger words, dated env-var slugs,
- * long camelCase identifiers) and deface the corpus. The deterministic
- * detectors stay:
- * structural key policy, plain-patterns (emails, home paths, and — seed-only,
- * #1415 — bare AWS access-key IDs and GCP `AIza…` API keys, deterministic
- * prefix shapes secretlint pass-1 does not cover), and secretlint's pass-1
- * preset rules (AWS secret-key assignments, GitHub / Slack / npm token
- * shapes, GCP service-account JSON). Accepted residual: JWTs and unprefixed
- * high-entropy blobs (trace profile catches them via the entropy fallback),
- * plus every structured identifier or PII class detected only by the omitted
- * openredaction stage, pass unredacted. The latter is a 570+ pattern surface;
- * payment cards, phone numbers, SSNs, medical or health-plan identifiers,
- * government identity documents, and financial account references are
- * examples, not an exhaustive allowlist. This is acceptable only for public
- * seed material that a curator has transformed and reviewed for those classes.
- * The reduced stage list is inspectable locally through the pipeline's
- * `components` surface. `TraceEnvelopeV0` does not publish that list, so a
- * fetched envelope cannot by itself prove which scrub profile ran.
+ * Seed / redact-mode preset (#1409 / #1969). Same owned inventory as layer-2.
+ * Entropy fallback stays off to preserve the shipped zero-corruption seed
+ * behavior until A2 mid-band can flag without tripping refuse-on-detection.
+ *
+ * @deprecated Compatibility preset over the one inventory + policy table.
  */
-export declare function buildSeedScrubPipeline(policy?: KeyPolicy): ScrubPipeline;
+export declare function buildSeedScrubPipeline(policyOrOpts?: KeyPolicy | BuildSeedScrubPipelineOptions): ScrubPipeline;