@jinn-network/core 0.1.2-canary.2b991f91 → 0.1.2-canary.402cd81b

package/dist/captured-task.d.ts

@@ -2,7 +2,7 @@
  * Captured-task schema — the raw, pre-scrub input to the harness capture path.
  *
  * Extracted from the former client harness layer in C2 (#1833):
- * the parse half of capture.ts has no scrub / `client/src` dependency (only
+ * the parse half of capture.ts has no scrub / `operator/src` dependency (only
  * zod + the two envelope enums), so it moved into `@jinn-network/core`.
  * C5 subsequently moved the scrub implementation alongside it while leaving
  * capture orchestration in the layer.

package/dist/captured-task.js

@@ -2,7 +2,7 @@
  * Captured-task schema — the raw, pre-scrub input to the harness capture path.
  *
  * Extracted from the former client harness layer in C2 (#1833):
- * the parse half of capture.ts has no scrub / `client/src` dependency (only
+ * the parse half of capture.ts has no scrub / `operator/src` dependency (only
  * zod + the two envelope enums), so it moved into `@jinn-network/core`.
  * C5 subsequently moved the scrub implementation alongside it while leaving
  * capture orchestration in the layer.

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

@@ -3,6 +3,12 @@
  *
  * Always hash-verifies before persisting to cache.
  *
+ * The two *network* legs — the donated IPFS mirror and the operator origin —
+ * are not implemented here: they are `fetchVerifiedArtifact`, the keyless
+ * retrieval primitive (#4179). What remains in this file is the store-aware
+ * composition around it: the cache read, the self-store mirror, the route
+ * resolver, and the cache writes whose ordering the daemon owns.
+ *
  * Spec §2.3 step 4-6.
  */
 import { type AcquireResult } from './fetch-artifact.js';

package/dist/corpus-read/acquire.js

@@ -3,34 +3,34 @@
  *
  * Always hash-verifies before persisting to cache.
  *
+ * The two *network* legs — the donated IPFS mirror and the operator origin —
+ * are not implemented here: they are `fetchVerifiedArtifact`, the keyless
+ * retrieval primitive (#4179). What remains in this file is the store-aware
+ * composition around it: the cache read, the self-store mirror, the route
+ * resolver, and the cache writes whose ordering the daemon owns.
+ *
  * Spec §2.3 step 4-6.
  */
-import { createHash } from 'node:crypto';
 import { fetchArtifactContent } from './fetch-artifact.js';
+import { fetchVerifiedArtifact, verifyArtifactDigest } from './artifact-retrieval.js';
 import { AcquireError, HashMismatchError } from './types.js';
-import { fetchFromIpfs as defaultFetchFromIpfs } from './ipfs.js';
-const DONATION_ARTIFACT_ENCODING = 'jinn.artifact.donation.v1';
-function sha256Hex(buf) {
-    return createHash('sha256').update(buf).digest('hex');
-}
-function decodeDonationArtifact(raw, expectedSha256) {
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
-        throw new Error('donation artifact payload is not an object');
-    }
-    const record = raw;
-    if (record['schemaVersion'] !== DONATION_ARTIFACT_ENCODING || record['encoding'] !== DONATION_ARTIFACT_ENCODING) {
-        throw new Error('donation artifact payload has unexpected encoding');
-    }
-    if (record['sha256'] !== expectedSha256) {
-        throw new Error('donation artifact sha256 does not match requested artifact');
-    }
-    if (typeof record['data'] !== 'string') {
-        throw new Error('donation artifact payload is missing base64 data');
-    }
-    return Buffer.from(record['data'], 'base64');
+/**
+ * Adapt a legacy `AcquireFn` to the primitive's clean seam. The legacy shape —
+ * a third `privateKey` parameter and a `Buffer | null` return — exists for
+ * older test fakes and stays confined to this file.
+ */
+function toAcquireResultFn(acquireFn, privateKey) {
+    return async (endpoint, sha256) => {
+        const raw = await acquireFn(endpoint, sha256, privateKey);
+        if (raw === null)
+            return { ok: false, reason: 'not_found', message: 'origin returned null (404 / not found)' };
+        if (Buffer.isBuffer(raw))
+            return { ok: true, content: raw };
+        return raw;
+    };
 }
 export async function acquireArtifactContent(args) {
-    const { sha256, artifactType, access, store, selfSafeAddress, privateKey, routeResolver, envelopeCid, sources = [], ipfsGatewayUrl, ownerSafe, acquireFn = (endpoint, sha256) => fetchArtifactContent(endpoint, sha256), fetchFromIpfs = defaultFetchFromIpfs, } = args;
+    const { sha256, artifactType, access, store, selfSafeAddress, privateKey, routeResolver, envelopeCid, sources = [], ipfsGatewayUrl, ownerSafe, acquireFn = (endpoint, sha256) => fetchArtifactContent(endpoint, sha256), fetchFromIpfs, } = args;
     const now = () => new Date().toISOString();
     // 1. Cache hit
     const cached = store.getNetworkArtifact(sha256);
@@ -46,16 +46,14 @@ export async function acquireArtifactContent(args) {
             sourceOperator: cached.sourceOperator ?? undefined,
         };
     }
-    // 2. Public IPFS donation source.
+    // 2. Public IPFS donation source. The primitive owns the fetch, the decode,
+    // the verification, and the #3441 fall-through warning; the cache write and
+    // the mismatch-is-fatal decision stay here, where the store lives.
     const ipfsSource = sources.find((source) => source.kind === 'ipfs');
     if (ipfsSource && ipfsGatewayUrl) {
-        try {
-            const raw = await fetchFromIpfs(ipfsGatewayUrl, ipfsSource.cid);
-            const bytes = decodeDonationArtifact(raw, sha256);
-            const actualSha = sha256Hex(bytes);
-            if (actualSha !== sha256) {
-                throw new HashMismatchError(sha256, actualSha, 'ipfs', ownerSafe);
-            }
+        const retrieved = await fetchVerifiedArtifact({ sha256, artifactType }, { sources, ipfsGatewayUrl, ownerSafe, envelopeCid }, { deps: { fetchFromIpfs } });
+        if (retrieved.ok) {
+            const bytes = retrieved.artifact.bytes;
             const ts = now();
             store.saveNetworkArtifact({
                 sha256,
@@ -78,13 +76,13 @@ export async function acquireArtifactContent(args) {
                 sourceOperator: ownerSafe,
             };
         }
-        catch (err) {
-            if (err instanceof HashMismatchError)
-                throw err;
-            // Donated IPFS is an opportunistic fast path. Gateway failures and
-            // malformed donation payloads should not block the acquisition chain;
-            // only verified byte hash mismatches remain fatal.
+        if (retrieved.reason === 'digest_mismatch') {
+            throw new HashMismatchError(sha256, retrieved.mismatch.actualSha256, 'ipfs', ownerSafe);
         }
+        // Donated IPFS is an opportunistic fast path: gateway failures and
+        // malformed donation payloads fall through to the next source. Anything
+        // that was not proven absence has already reached the operator as a
+        // warning from inside the primitive (#3441).
     }
     // 3. Self-store fast path
     if (ownerSafe && ownerSafe.toLowerCase() === selfSafeAddress.toLowerCase()) {
@@ -95,9 +93,9 @@ export async function acquireArtifactContent(args) {
             // propagate the bad bytes into network_artifacts where peers can
             // fetch them. Throwing closes the cache-poisoning gap; the self-store
             // path is now hash-equivalent to origin / route-resolver.
-            const actualSha = sha256Hex(own.content);
-            if (actualSha !== sha256) {
-                throw new HashMismatchError(sha256, actualSha, 'self-store', selfSafeAddress);
+            const verified = verifyArtifactDigest(sha256, own.content);
+            if (!verified.ok) {
+                throw new HashMismatchError(sha256, verified.actualSha256, 'self-store', selfSafeAddress);
             }
             // Mirror into cache so peer asks for the same content can hit cache (provenance: self-store-mirror).
             const ts = now();
@@ -125,9 +123,9 @@ export async function acquireArtifactContent(args) {
         try {
             const out = await routeResolver.resolve({ sha256, access, requesterSafe: selfSafeAddress });
             if (out) {
-                const actualSha = sha256Hex(out.bytes);
-                if (actualSha !== sha256) {
-                    throw new HashMismatchError(sha256, actualSha, 'route-resolver', out.sourceOperator);
+                const verified = verifyArtifactDigest(sha256, out.bytes);
+                if (!verified.ok) {
+                    throw new HashMismatchError(sha256, verified.actualSha256, 'route-resolver', out.sourceOperator);
                 }
                 const ts = now();
                 store.saveNetworkArtifact({
@@ -158,36 +156,17 @@ export async function acquireArtifactContent(args) {
         }
     }
     // 5. Origin fetch
-    let bytes;
-    try {
-        const raw = await acquireFn(access.endpoint, sha256, privateKey);
-        // Accept both the legacy `Buffer | null` shape and the discriminated
-        // union from fetchArtifactContent. Buffer.isBuffer guards before we
-        // duck-type into the union.
-        if (raw === null || Buffer.isBuffer(raw)) {
-            bytes = raw;
-        }
-        else if (raw.ok === true) {
-            bytes = raw.content;
+    const retrieved = await fetchVerifiedArtifact({ sha256, artifactType }, { endpoint: access.endpoint, ownerSafe, envelopeCid }, { deps: { fetchArtifact: toAcquireResultFn(acquireFn, privateKey) } });
+    if (!retrieved.ok) {
+        if (retrieved.reason === 'digest_mismatch') {
+            throw new HashMismatchError(sha256, retrieved.mismatch.actualSha256, 'origin', ownerSafe);
         }
-        else {
-            // ok: false — preserve the reason so the caller / daemon route can
-            // surface it via AcquireError.cause.
-            throw new AcquireError(sha256, `origin fetch failed: ${raw.reason}${raw.message ? ` (${raw.message})` : ''}`, raw);
-        }
-    }
-    catch (err) {
-        if (err instanceof AcquireError)
-            throw err;
-        throw new AcquireError(sha256, 'origin fetch failed', err);
-    }
-    if (!bytes) {
-        throw new AcquireError(sha256, 'origin returned null (404 / not found)');
-    }
-    const actualSha = sha256Hex(bytes);
-    if (actualSha !== sha256) {
-        throw new HashMismatchError(sha256, actualSha, 'origin', ownerSafe);
+        // Preserve the reason token in the message so callers and the daemon route
+        // can surface which failure this was.
+        const attempt = retrieved.attempts.find((entry) => entry.leg === 'origin');
+        throw new AcquireError(sha256, `origin fetch failed: ${retrieved.reason}${attempt?.message ? ` (${attempt.message})` : ''}`, retrieved);
     }
+    const bytes = retrieved.artifact.bytes;
     const ts = now();
     store.saveNetworkArtifact({
         sha256,

package/dist/corpus-read/artifact-retrieval.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Artifact retrieval primitive — fetch by content address, verify, return bytes.
+ *
+ * One function fetches an artifact from the network legs an envelope names and
+ * hands back its bytes only after they hash to the recorded sha256, together
+ * with the provenance of the leg that produced them. A digest mismatch fails
+ * closed: the failure arm of the result union has no bytes on it at all.
+ *
+ * Keyless and filesystem-neutral by construction. The primitive itself neither
+ * accepts nor touches key material or the filesystem: it takes no store, no
+ * signer, no private key, and no path, and it performs no write of any kind.
+ * The one channel through which such material can reach a call is the caller's
+ * own `deps` seam closure — `acquire.ts` legitimately supplies one that holds a
+ * private key — and that closure is opaque here: it is invoked, never read,
+ * never logged, and never surfaced in provenance.
+ * `test/architecture/keyless-primitive.test.ts` holds the module graph to the
+ * same promise.
+ *
+ * Where the returned bytes land is the caller's decision. The daemon chain
+ * (`acquire.ts`) composes this with its byte cache; the CLI hands them to the
+ * operator; the MCP handler proxies to a daemon that runs it. None of that is
+ * this function's business.
+ *
+ * Issue #4179 (umbrella #2448 / journey spec B0c).
+ */
+import { type AcquireResult } from './fetch-artifact.js';
+import type { ArtifactSource } from './types.js';
+/**
+ * Content address of a corpus artifact: the sha256 of the bytes themselves, as
+ * recorded in the envelope's `artifact.sha256` — never an IPFS CID (artifacts
+ * stopped having CIDs post jinn-mono-vy37.1.2).
+ */
+export interface ArtifactAddress {
+    /** 64-char lowercase hex. The one thing that is trusted. */
+    sha256: string;
+    /**
+     * Declared type from the envelope. Carried into the result for the caller's
+     * convenience and never consulted during verification — an attacker-supplied
+     * label cannot influence whether bytes are admitted.
+     */
+    artifactType?: string;
+}
+/**
+ * Where the bytes might be. Every field is manifest-supplied and therefore
+ * attacker-controlled; the destination policy and the byte/redirect/deadline
+ * caps in `fetch-artifact.ts` and `ipfs.ts` are what make that safe.
+ */
+export interface ArtifactLocators {
+    /** Donated IPFS sources — the envelope's `artifact.sources` entries. */
+    sources?: readonly ArtifactSource[];
+    /** Gateway base for the IPFS leg. The leg is skipped when this is absent. */
+    ipfsGatewayUrl?: string;
+    /** HTTP origin — the envelope's `artifact.access.endpoint`. */
+    endpoint?: string;
+    /** Envelope CID this artifact was named by. Provenance only. */
+    envelopeCid?: string;
+    /** Publishing operator's Safe, when known. Provenance and attribution only. */
+    ownerSafe?: string;
+}
+export interface FetchVerifiedArtifactOptions {
+    /**
+     * Injection seams, mirroring the `acquire.ts` precedent so tests need no
+     * module mock. A caller that needs to bound or redirect a leg replaces the
+     * leg — there is no separate options passthrough, because no call site wants
+     * the default transport with different bounds.
+     */
+    deps?: {
+        fetchArtifact?: (endpoint: string, sha256: string) => Promise<AcquireResult>;
+        fetchFromIpfs?: (gatewayUrl: string, cid: string) => Promise<unknown>;
+        /** Clock seam for `fetchedAt`. */
+        now?: () => string;
+    };
+}
+/** One leg's outcome, recorded whether it succeeded, was skipped, or failed. */
+export interface ArtifactFetchAttempt {
+    readonly leg: 'ipfs' | 'origin';
+    /** `ipfs://<cid>` or the exact URL `buildArtifactUrl` produced; empty when skipped. */
+    readonly sourceUri: string;
+    readonly outcome: 'verified' | 'skipped' | 'failed' | 'digest_mismatch';
+    /** Present on `failed`; the classified reason, never a raw string match. */
+    readonly reason?: ArtifactFetchFailureReason;
+    readonly message?: string;
+}
+export interface ArtifactProvenance {
+    /** Which leg produced the admitted bytes. */
+    readonly source: 'ipfs' | 'origin';
+    readonly sourceUri: string;
+    /** Always 'sha256'. Explicit so the record does not silently mean "some digest". */
+    readonly digestAlgorithm: 'sha256';
+    /** ISO-8601 instant the bytes were verified, not when they were requested. */
+    readonly fetchedAt: string;
+    readonly sourceOperator?: string;
+    readonly envelopeCid?: string;
+    /** Every leg tried, in order. Legible even on the happy path. */
+    readonly attempts: readonly ArtifactFetchAttempt[];
+}
+export interface VerifiedArtifact {
+    readonly sha256: string;
+    /** Verified bytes, in memory. Never a path, never a handle. */
+    readonly bytes: Buffer;
+    readonly artifactType: string;
+    readonly provenance: ArtifactProvenance;
+}
+export type ArtifactFetchFailureReason = 
+/** Bytes arrived and did not hash to the address. */
+'digest_mismatch'
+/** Every attempted leg answered, and every answer was absence. */
+ | 'not_found'
+/** Nothing was supplied to try. */
+ | 'no_locator'
+/** Destination policy refused an origin or a redirect hop. */
+ | 'blocked' | 'too_large' | 'timeout'
+/** Transport failure — nothing was learned about whether the content exists. */
+ | 'unavailable';
+export interface FetchVerifiedArtifactFailure {
+    readonly ok: false;
+    readonly sha256: string;
+    readonly reason: ArtifactFetchFailureReason;
+    /** Derived from `reason`, never caller-supplied. */
+    readonly retryable: boolean;
+    readonly message: string;
+    readonly attempts: readonly ArtifactFetchAttempt[];
+    /** Present only on `digest_mismatch`. Evidence, not content. */
+    readonly mismatch?: {
+        readonly expectedSha256: string;
+        readonly actualSha256: string;
+        readonly sourceUri: string;
+        readonly sourceOperator?: string;
+    };
+}
+export type FetchVerifiedArtifactResult = {
+    readonly ok: true;
+    readonly artifact: VerifiedArtifact;
+} | FetchVerifiedArtifactFailure;
+/**
+ * The one digest check in the system. Legs that already hold bytes — the byte
+ * cache, the self-store, a route resolver, the MCP daemon proxy — call this
+ * rather than writing `createHash('sha256')` out again.
+ */
+export declare function verifyArtifactDigest(expectedSha256: string, bytes: Buffer): {
+    ok: true;
+} | {
+    ok: false;
+    actualSha256: string;
+};
+/**
+ * Fetch an artifact by content address and return its bytes only after they
+ * hash to that address.
+ *
+ * Legs run in the order the daemon chain has always used: the free donated IPFS
+ * mirror first, the operator's HTTP origin second. A leg with no locator is
+ * *skipped*, not failed. A digest mismatch on any leg fails the whole call and
+ * does not fall through — the bytes are wrong or hostile, and the next locator
+ * cannot make them right.
+ */
+export declare function fetchVerifiedArtifact(address: ArtifactAddress, locators: ArtifactLocators, options?: FetchVerifiedArtifactOptions): Promise<FetchVerifiedArtifactResult>;

package/dist/corpus-read/artifact-retrieval.js

@@ -0,0 +1,246 @@
+/**
+ * Artifact retrieval primitive — fetch by content address, verify, return bytes.
+ *
+ * One function fetches an artifact from the network legs an envelope names and
+ * hands back its bytes only after they hash to the recorded sha256, together
+ * with the provenance of the leg that produced them. A digest mismatch fails
+ * closed: the failure arm of the result union has no bytes on it at all.
+ *
+ * Keyless and filesystem-neutral by construction. The primitive itself neither
+ * accepts nor touches key material or the filesystem: it takes no store, no
+ * signer, no private key, and no path, and it performs no write of any kind.
+ * The one channel through which such material can reach a call is the caller's
+ * own `deps` seam closure — `acquire.ts` legitimately supplies one that holds a
+ * private key — and that closure is opaque here: it is invoked, never read,
+ * never logged, and never surfaced in provenance.
+ * `test/architecture/keyless-primitive.test.ts` holds the module graph to the
+ * same promise.
+ *
+ * Where the returned bytes land is the caller's decision. The daemon chain
+ * (`acquire.ts`) composes this with its byte cache; the CLI hands them to the
+ * operator; the MCP handler proxies to a daemon that runs it. None of that is
+ * this function's business.
+ *
+ * Issue #4179 (umbrella #2448 / journey spec B0c).
+ */
+import { createHash } from 'node:crypto';
+import { buildArtifactUrl, fetchArtifactContent, } from './fetch-artifact.js';
+import { classifyIpfsFetchFailure, fetchFromIpfs as defaultFetchFromIpfs } from './ipfs.js';
+const DONATION_ARTIFACT_ENCODING = 'jinn.artifact.donation.v1';
+/** Nothing that was learned tells us to stop; everything else does. */
+const RETRYABLE_REASONS = new Set([
+    'timeout',
+    'unavailable',
+]);
+/**
+ * The one digest check in the system. Legs that already hold bytes — the byte
+ * cache, the self-store, a route resolver, the MCP daemon proxy — call this
+ * rather than writing `createHash('sha256')` out again.
+ */
+export function verifyArtifactDigest(expectedSha256, bytes) {
+    const actualSha256 = createHash('sha256').update(bytes).digest('hex');
+    return actualSha256 === expectedSha256 ? { ok: true } : { ok: false, actualSha256 };
+}
+/**
+ * Log an IPFS read the retrieval is about to fall through, unless the gateway
+ * actually answered "not there" (#3441). A cap refusal is positive evidence the
+ * content exists, so it must not read like an ordinary miss.
+ */
+function warnIpfsFallThrough(subject, error) {
+    const classification = classifyIpfsFetchFailure(error);
+    if (classification === 'not-found')
+        return;
+    const detail = error instanceof Error ? error.message : String(error);
+    console.warn(`[corpus-read] IPFS source for ${subject} could not be used (${classification}), `
+        + `falling through to the next source: ${detail}`);
+}
+/**
+ * Decode a `jinn.artifact.donation.v1` payload into its raw bytes.
+ *
+ * Moved verbatim from `acquire.ts`. The `schemaVersion` check compares against
+ * the encoding constant — the published fixtures set both fields to that same
+ * string, so the comparison is load-bearing as written and is not "corrected"
+ * here.
+ */
+function decodeDonationArtifact(raw, expectedSha256) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('donation artifact payload is not an object');
+    }
+    const record = raw;
+    if (record['schemaVersion'] !== DONATION_ARTIFACT_ENCODING || record['encoding'] !== DONATION_ARTIFACT_ENCODING) {
+        throw new Error('donation artifact payload has unexpected encoding');
+    }
+    if (record['sha256'] !== expectedSha256) {
+        throw new Error('donation artifact sha256 does not match requested artifact');
+    }
+    if (typeof record['data'] !== 'string') {
+        throw new Error('donation artifact payload is missing base64 data');
+    }
+    return Buffer.from(record['data'], 'base64');
+}
+/** `fetchArtifactContent`'s vocabulary → the primitive's. */
+function originReason(reason) {
+    return reason === 'network_error' ? 'unavailable' : reason;
+}
+/** `classifyIpfsFetchFailure`'s hyphenated vocabulary → the primitive's. */
+function ipfsReason(classification) {
+    if (classification === 'too-large')
+        return 'too_large';
+    if (classification === 'not-found')
+        return 'not_found';
+    return 'unavailable';
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Fetch an artifact by content address and return its bytes only after they
+ * hash to that address.
+ *
+ * Legs run in the order the daemon chain has always used: the free donated IPFS
+ * mirror first, the operator's HTTP origin second. A leg with no locator is
+ * *skipped*, not failed. A digest mismatch on any leg fails the whole call and
+ * does not fall through — the bytes are wrong or hostile, and the next locator
+ * cannot make them right.
+ */
+export async function fetchVerifiedArtifact(address, locators, options) {
+    const { sha256, artifactType } = address;
+    const { sources = [], ipfsGatewayUrl, endpoint, envelopeCid, ownerSafe } = locators;
+    const fetchIpfs = options?.deps?.fetchFromIpfs ?? defaultFetchFromIpfs;
+    const fetchOrigin = options?.deps?.fetchArtifact ?? fetchArtifactContent;
+    const now = options?.deps?.now ?? (() => new Date().toISOString());
+    const attempts = [];
+    const admit = (source, sourceUri, bytes) => {
+        attempts.push({ leg: source, sourceUri, outcome: 'verified' });
+        return {
+            ok: true,
+            artifact: {
+                sha256,
+                bytes,
+                artifactType: artifactType ?? 'unknown',
+                provenance: {
+                    source,
+                    sourceUri,
+                    digestAlgorithm: 'sha256',
+                    fetchedAt: now(),
+                    ...(ownerSafe ? { sourceOperator: ownerSafe } : {}),
+                    ...(envelopeCid ? { envelopeCid } : {}),
+                    attempts,
+                },
+            },
+        };
+    };
+    const refuse = (leg, sourceUri, actualSha256) => {
+        attempts.push({ leg, sourceUri, outcome: 'digest_mismatch' });
+        return {
+            ok: false,
+            sha256,
+            reason: 'digest_mismatch',
+            retryable: false,
+            message: `artifact ${sha256} from ${sourceUri} hashed to ${actualSha256}; `
+                + 'the bytes were discarded',
+            attempts,
+            mismatch: {
+                expectedSha256: sha256,
+                actualSha256,
+                sourceUri,
+                ...(ownerSafe ? { sourceOperator: ownerSafe } : {}),
+            },
+        };
+    };
+    // 1. Donated IPFS mirror — free and public, so it goes first.
+    const ipfsSource = sources.find((source) => source.kind === 'ipfs');
+    if (ipfsSource && ipfsGatewayUrl) {
+        const sourceUri = `ipfs://${ipfsSource.cid}`;
+        try {
+            const raw = await fetchIpfs(ipfsGatewayUrl, ipfsSource.cid);
+            const bytes = decodeDonationArtifact(raw, sha256);
+            const verified = verifyArtifactDigest(sha256, bytes);
+            if (!verified.ok)
+                return refuse('ipfs', sourceUri, verified.actualSha256);
+            return admit('ipfs', sourceUri, bytes);
+        }
+        catch (err) {
+            // A gateway failure or a malformed donation payload is opportunistic
+            // noise, not a verdict on the artifact: classify, warn unless it was
+            // proven absence, and let the next locator answer.
+            warnIpfsFallThrough(`donation artifact ${sha256}`, err);
+            attempts.push({
+                leg: 'ipfs',
+                sourceUri,
+                outcome: 'failed',
+                reason: ipfsReason(classifyIpfsFetchFailure(err)),
+                message: errorMessage(err),
+            });
+        }
+    }
+    else {
+        attempts.push({ leg: 'ipfs', sourceUri: '', outcome: 'skipped' });
+    }
+    // 2. Operator HTTP origin.
+    if (endpoint) {
+        const sourceUri = buildArtifactUrl(endpoint, sha256);
+        let outcome;
+        try {
+            outcome = await fetchOrigin(endpoint, sha256);
+        }
+        catch (err) {
+            outcome = { ok: false, reason: 'network_error', message: errorMessage(err) };
+        }
+        if (outcome.ok) {
+            const verified = verifyArtifactDigest(sha256, outcome.content);
+            if (!verified.ok)
+                return refuse('origin', sourceUri, verified.actualSha256);
+            return admit('origin', sourceUri, outcome.content);
+        }
+        attempts.push({
+            leg: 'origin',
+            sourceUri,
+            outcome: 'failed',
+            reason: originReason(outcome.reason),
+            ...(outcome.message ? { message: outcome.message } : {}),
+        });
+    }
+    else {
+        attempts.push({ leg: 'origin', sourceUri: '', outcome: 'skipped' });
+    }
+    // Nothing verified. Absence is only claimed when every attempted leg said so:
+    // one inconclusive leg means we learned nothing about existence (#3441).
+    const failures = attempts.filter((attempt) => attempt.outcome === 'failed');
+    if (failures.length === 0) {
+        // Name why each leg was skipped rather than assuming both locators were
+        // absent: donated sources with no gateway to read them through is its own
+        // case, and reporting it as "no donated IPFS source" is simply wrong.
+        const missing = [
+            ipfsSource
+                ? 'a donated IPFS source but no gateway URL to read it through'
+                : 'no donated IPFS source',
+            'no origin endpoint',
+        ];
+        return {
+            ok: false,
+            sha256,
+            reason: 'no_locator',
+            retryable: false,
+            message: `artifact ${sha256} has no locator to try: ${missing.join(', and ')}`,
+            attempts,
+        };
+    }
+    // When more than one leg fails inconclusively, the last one wins. Legs run
+    // cheapest-first — the opportunistic donated mirror, then the operator's own
+    // origin — so the last leg to answer is the artifact's actual home, and its
+    // reason is the one the operator can act on.
+    const inconclusive = failures.filter((attempt) => attempt.reason !== 'not_found');
+    const reason = inconclusive.length > 0
+        ? inconclusive[inconclusive.length - 1].reason
+        : 'not_found';
+    return {
+        ok: false,
+        sha256,
+        reason,
+        retryable: RETRYABLE_REASONS.has(reason),
+        message: `artifact ${sha256} could not be retrieved (${reason}) from `
+            + failures.map((attempt) => `${attempt.sourceUri}: ${attempt.reason}`).join('; '),
+        attempts,
+    };
+}

package/dist/corpus-read/fetch-artifact.d.ts

@@ -8,14 +8,59 @@
  *
  * Keys artifacts by sha256 (not IPFS CID) — artifacts no longer have IPFS
  * CIDs (post jinn-mono-vy37.1.2).
+ *
+ * The endpoint is manifest-supplied and therefore attacker-controlled (#1901),
+ * so this fetch is both destination-restricted and resource-bounded *before*
+ * the hash check in `acquire.ts` ever runs:
+ *
+ * - every destination — the origin and each redirect hop — must pass
+ *   `resolvePublicHttpDestination` (see `origin-guard.ts`), and the socket is
+ *   pinned to the exact address that check approved, so a name whose DNS
+ *   answer flips between validation and connect cannot escape the policy;
+ * - redirects are followed manually and capped;
+ * - one deadline bounds the whole chain, including the body read, so a
+ *   stalled peer cannot hold a worker;
+ * - the body is streamed through a byte counter and abandoned the moment it
+ *   exceeds the cap, so an oversized response is never fully buffered.
  */
+import { type HostnameResolver } from './origin-guard.js';
+import { type PinnedFetch } from './pinned-fetch.js';
 export type AcquireResult = {
     ok: true;
     content: Buffer;
 } | {
     ok: false;
-    reason: 'not_found' | 'network_error';
+    /**
+     * `blocked` — destination policy refused the origin or a redirect hop.
+     * `too_large` — the response exceeded the byte cap.
+     * `timeout` — the response stalled past the deadline.
+     */
+    reason: 'not_found' | 'network_error' | 'blocked' | 'too_large' | 'timeout';
     message?: string;
 };
+export interface FetchArtifactOptions {
+    /**
+     * Injection seam for tests. The default connects over `node:http(s)` with
+     * the socket pinned to the guard-approved address; a plain `fetch` fake is
+     * accepted here but does not pin, so production must not supply one.
+     */
+    fetchImpl?: PinnedFetch;
+    /** Injection seam for tests; defaults to `dns.lookup(..., { all: true })`. */
+    resolveHostname?: HostnameResolver;
+    /**
+     * Permit loopback/private destinations, and skip address pinning with them.
+     * Off by default and set nowhere in-repo; it exists for an operator running
+     * against a local origin, because `operator.publicEndpoint` falls back to
+     * `http://localhost:<apiPort>` when unset. Scheme and credential checks
+     * still apply. Env: `JINN_CORPUS_ALLOW_PRIVATE_ORIGINS`.
+     */
+    allowPrivateDestinations?: boolean;
+    /** Byte cap. Env: `JINN_CORPUS_ARTIFACT_MAX_BYTES`. */
+    maxBytes?: number;
+    /** Whole-operation deadline in ms; `0` disables. Env: `JINN_CORPUS_ARTIFACT_FETCH_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /** Redirect hop cap. Env: `JINN_CORPUS_ARTIFACT_MAX_REDIRECTS`. */
+    maxRedirects?: number;
+}
 export declare function buildArtifactUrl(endpoint: string, sha256: string): string;
-export declare function fetchArtifactContent(endpoint: string, sha256: string): Promise<AcquireResult>;
+export declare function fetchArtifactContent(endpoint: string, sha256: string, options?: FetchArtifactOptions): Promise<AcquireResult>;