@jinn-network/core 0.1.2-canary.b91a66df → 0.1.2-canary.bebeb033

package/dist/corpus-read/acquire.js

@@ -8,11 +8,24 @@
 import { createHash } from 'node:crypto';
 import { fetchArtifactContent } from './fetch-artifact.js';
 import { AcquireError, HashMismatchError } from './types.js';
-import { fetchFromIpfs as defaultFetchFromIpfs } from './ipfs.js';
+import { classifyIpfsFetchFailure, fetchFromIpfs as defaultFetchFromIpfs } from './ipfs.js';
 const DONATION_ARTIFACT_ENCODING = 'jinn.artifact.donation.v1';
 function sha256Hex(buf) {
     return createHash('sha256').update(buf).digest('hex');
 }
+/**
+ * Log an IPFS read that the acquisition chain 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}`);
+}
 function decodeDonationArtifact(raw, expectedSha256) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
         throw new Error('donation artifact payload is not an object');
@@ -84,6 +97,11 @@ export async function acquireArtifactContent(args) {
             // 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.
+            //
+            // Swallowing the failure silently, though, turns a size-policy refusal or
+            // a blocked redirect into an invisible data gap (#3441). Classify before
+            // swallowing so anything that is not proven absence reaches the operator.
+            warnIpfsFallThrough(`donation artifact ${sha256}`, err);
         }
     }
     // 3. Self-store fast path

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

@@ -1,3 +1,63 @@
+/**
+ * Default cap on any single gateway response, JSON or raw; a caller that
+ * legitimately reads larger payloads may raise it per call through
+ * {@link FetchFromIpfsOptions.maxResponseBytes} (#3441). Corpus manifests and
+ * donation artifacts are JSON envelopes orders of magnitude smaller than this
+ * (#3410); the raw-bytes path added in #3438 also carries source-bundle files
+ * and sealed documents, which are larger but nowhere near this. A response
+ * above it is hostile or broken, and buffering it would exhaust memory — so
+ * size this against the largest legitimate *source file*, not against the
+ * JSON envelopes alone.
+ */
+export declare const DEFAULT_MAX_IPFS_RESPONSE_BYTES: number;
+/**
+ * A gateway response the byte cap refused. FAILURE IS NOT ABSENCE (#2647, #3451): the gateway
+ * answered FOR this content, so the refusal is positive evidence that it EXISTS and is merely
+ * larger than policy allows. (On the declared-`content-length` path the body is discarded unread,
+ * so the evidence is the headers rather than the bytes — still an answer, not a miss.) A caller
+ * that reports it as "not on IPFS" turns a size-policy decision into a silent data gap.
+ */
+export declare class IpfsResponseTooLargeError extends Error {
+    readonly limitBytes: number;
+    readonly declaredBytes?: number | undefined;
+    readonly name = "IpfsResponseTooLargeError";
+    constructor(limitBytes: number, declaredBytes?: number | undefined);
+}
+/**
+ * The gateway answered that this content is not there. The one failure mode that IS absence
+ * (#3451) — every other one leaves the question unanswered.
+ */
+export declare class IpfsContentNotFoundError extends Error {
+    readonly status: number;
+    readonly name = "IpfsContentNotFoundError";
+    constructor(message: string, status: number);
+}
+/**
+ * Every gateway x CID candidate failed. Carries the per-candidate causes so a caller can classify
+ * the whole operation with {@link classifyIpfsFetchFailure} instead of string-matching the joined
+ * message, which is a display artifact and not a contract.
+ */
+export declare class IpfsFetchFailedError extends Error {
+    readonly causes: readonly unknown[];
+    readonly name = "IpfsFetchFailedError";
+    constructor(message: string, causes: readonly unknown[]);
+}
+/**
+ * Classify a failed IPFS fetch into the three answers a caller can act on differently:
+ *
+ *   - `'too-large'` — at least one candidate served the content and the byte cap refused it. This
+ *     dominates: a size refusal is positive proof of presence, so it outranks any number of
+ *     not-found answers from other candidates.
+ *   - `'not-found'` — every candidate answered, and every answer was "not there". Genuine absence.
+ *   - `'unavailable'` — anything else (transport error, timeout, malformed candidate URL). Nothing
+ *     was learned about whether the content exists.
+ *
+ * `'not-found'` is deliberately strict, and in production it is therefore the rarest answer: a
+ * default fetch also tries the `ipfs.io` fallback, which typically stalls into a 504 or an abort
+ * for an unpinned digest rather than answering 404. Such a run classifies `'unavailable'` — the
+ * safe direction, since absence is never claimed without proof of it.
+ */
+export declare function classifyIpfsFetchFailure(error: unknown): 'too-large' | 'not-found' | 'unavailable';
 export declare function normalizeIpfsGatewayBase(gatewayUrl: string): string;
 export declare function buildIpfsHexCidCandidatesFromPartialHex(hex: string): string[];
 export declare function buildIpfsFetchCidPathCandidates(cidOrPath: string): string[];
@@ -9,6 +69,20 @@ export type FetchFromIpfsOptions = {
      * - string → alternate fallback (normalized via `normalizeIpfsGatewayBase`)
      */
     fallbackGatewayBase?: string | false;
+    /**
+     * Byte cap for one gateway response, defaulting to
+     * {@link DEFAULT_MAX_IPFS_RESPONSE_BYTES}. Raise it only for a call site that
+     * legitimately reads larger payloads (#3441) — the default is sized for JSON
+     * envelopes and source files, and a caller that raises it accepts buffering
+     * that many bytes. Values below 1 fall back to the default.
+     */
+    maxResponseBytes?: number;
 };
 /** Read-only multi-codec, primary-plus-fallback IPFS JSON fetch. */
 export declare function fetchFromIpfs(gatewayUrl: string, cid: string, opts?: FetchFromIpfsOptions): Promise<unknown>;
+/**
+ * Read-only multi-codec, primary-plus-fallback IPFS fetch returning the exact
+ * bytes stored at the CID — no JSON parse/re-encode roundtrip. Use this
+ * whenever the bytes will be hashed, or whenever the content is not JSON.
+ */
+export declare function fetchBytesFromIpfs(gatewayUrl: string, cid: string, opts?: FetchFromIpfsOptions): Promise<Uint8Array>;

package/dist/corpus-read/ipfs.js

@@ -1,9 +1,113 @@
 const IPFS_FETCH_TIMEOUT_MS = 15_000;
+/**
+ * Bound on one whole `fetchFromIpfs` / `fetchBytesFromIpfs` call. The
+ * per-attempt timer above is re-armed for every gateway x CID candidate, so
+ * without this a single call could legitimately run for the product of the
+ * two. Every candidate is still attempted: the per-attempt timer is clamped
+ * to an equal share of whatever budget remains.
+ */
+const IPFS_TOTAL_FETCH_TIMEOUT_MS = 45_000;
+/**
+ * Default cap on any single gateway response, JSON or raw; a caller that
+ * legitimately reads larger payloads may raise it per call through
+ * {@link FetchFromIpfsOptions.maxResponseBytes} (#3441). Corpus manifests and
+ * donation artifacts are JSON envelopes orders of magnitude smaller than this
+ * (#3410); the raw-bytes path added in #3438 also carries source-bundle files
+ * and sealed documents, which are larger but nowhere near this. A response
+ * above it is hostile or broken, and buffering it would exhaust memory — so
+ * size this against the largest legitimate *source file*, not against the
+ * JSON envelopes alone.
+ */
+export const DEFAULT_MAX_IPFS_RESPONSE_BYTES = 8 * 1024 * 1024;
+const MAX_IPFS_REDIRECT_HOPS = 3;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const FALLBACK_IPFS_GATEWAY_BASE = 'https://ipfs.io/ipfs/';
+/**
+ * A gateway response the byte cap refused. FAILURE IS NOT ABSENCE (#2647, #3451): the gateway
+ * answered FOR this content, so the refusal is positive evidence that it EXISTS and is merely
+ * larger than policy allows. (On the declared-`content-length` path the body is discarded unread,
+ * so the evidence is the headers rather than the bytes — still an answer, not a miss.) A caller
+ * that reports it as "not on IPFS" turns a size-policy decision into a silent data gap.
+ */
+export class IpfsResponseTooLargeError extends Error {
+    limitBytes;
+    declaredBytes;
+    name = 'IpfsResponseTooLargeError';
+    constructor(limitBytes, declaredBytes) {
+        super(`IPFS response exceeds the ${limitBytes}-byte cap`
+            + (declaredBytes === undefined ? '' : ` (content-length ${declaredBytes})`));
+        this.limitBytes = limitBytes;
+        this.declaredBytes = declaredBytes;
+    }
+}
+/**
+ * The gateway answered that this content is not there. The one failure mode that IS absence
+ * (#3451) — every other one leaves the question unanswered.
+ */
+export class IpfsContentNotFoundError extends Error {
+    status;
+    name = 'IpfsContentNotFoundError';
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Every gateway x CID candidate failed. Carries the per-candidate causes so a caller can classify
+ * the whole operation with {@link classifyIpfsFetchFailure} instead of string-matching the joined
+ * message, which is a display artifact and not a contract.
+ */
+export class IpfsFetchFailedError extends Error {
+    causes;
+    name = 'IpfsFetchFailedError';
+    constructor(message, causes) {
+        super(message);
+        this.causes = causes;
+    }
+}
+/**
+ * Classify a failed IPFS fetch into the three answers a caller can act on differently:
+ *
+ *   - `'too-large'` — at least one candidate served the content and the byte cap refused it. This
+ *     dominates: a size refusal is positive proof of presence, so it outranks any number of
+ *     not-found answers from other candidates.
+ *   - `'not-found'` — every candidate answered, and every answer was "not there". Genuine absence.
+ *   - `'unavailable'` — anything else (transport error, timeout, malformed candidate URL). Nothing
+ *     was learned about whether the content exists.
+ *
+ * `'not-found'` is deliberately strict, and in production it is therefore the rarest answer: a
+ * default fetch also tries the `ipfs.io` fallback, which typically stalls into a 504 or an abort
+ * for an unpinned digest rather than answering 404. Such a run classifies `'unavailable'` — the
+ * safe direction, since absence is never claimed without proof of it.
+ */
+export function classifyIpfsFetchFailure(error) {
+    const causes = error instanceof IpfsFetchFailedError ? error.causes : [error];
+    if (causes.some((cause) => cause instanceof IpfsResponseTooLargeError))
+        return 'too-large';
+    if (causes.length > 0 && causes.every((cause) => cause instanceof IpfsContentNotFoundError)) {
+        return 'not-found';
+    }
+    return 'unavailable';
+}
 export function normalizeIpfsGatewayBase(gatewayUrl) {
     let normalized = gatewayUrl.trim();
     if (normalized === '')
         normalized = 'https://gateway.autonolas.tech';
+    // Drop any userinfo at the source. `fetch` rejects a credentialed URL
+    // outright, and its own error message quotes the URL back — so a gateway
+    // configured Infura-style would otherwise put its secret into every
+    // aggregated fetch error, which callers log.
+    try {
+        const parsed = new URL(normalized);
+        if (parsed.username !== '' || parsed.password !== '') {
+            parsed.username = '';
+            parsed.password = '';
+            normalized = parsed.toString();
+        }
+    }
+    catch {
+        // Not an absolute URL; leave it to the caller's own failure path.
+    }
     normalized = normalized.replace(/\/+$/, '');
     if (!normalized.toLowerCase().endsWith('/ipfs'))
         normalized = `${normalized}/ipfs`;
@@ -29,15 +133,164 @@ export function buildIpfsFetchCidPathCandidates(cidOrPath) {
     }
     return [value];
 }
-async function fetchJson(url, signal) {
-    const response = await fetch(url, { method: 'GET', signal });
-    if (!response.ok) {
-        throw new Error(`IPFS fetch failed: ${response.status} ${response.statusText} (${url.slice(0, 80)}…)`);
+function isHostInGatewayFamily(host, gatewayHost) {
+    const candidate = host.toLowerCase();
+    const gateway = gatewayHost.toLowerCase();
+    return candidate === gateway || candidate.endsWith(`.${gateway}`);
+}
+/**
+ * The port a request to `url` actually reaches. `URL.port` is the empty string
+ * whenever the port is the scheme default, so comparing it raw makes
+ * `http://gw.example` (80) and `https://gw.example` (443) look identical
+ * (#3439). Resolving the default first keeps an http-to-https hop
+ * distinguishable, which the downgrade rule cannot catch because it only fires
+ * in the other direction.
+ */
+function effectivePort(url) {
+    if (url.port !== '')
+        return url.port;
+    return url.protocol === 'https:' ? '443' : '80';
+}
+/**
+ * A gateway may legitimately redirect the path form of a CID to its subdomain
+ * form, so hops are allowed inside the configured gateway's host family. They
+ * are never allowed to leave it, to reach a different port on it, to downgrade
+ * the transport, or to smuggle credentials.
+ */
+function assertRedirectAllowed(next, current, gateway) {
+    if (next.protocol !== 'http:' && next.protocol !== 'https:') {
+        throw new Error(`IPFS redirect uses an unsupported scheme (${next.protocol})`);
     }
+    if (current.protocol === 'https:' && next.protocol === 'http:') {
+        throw new Error('IPFS redirect downgrades https to http');
+    }
+    if (next.username !== '' || next.password !== '') {
+        throw new Error('IPFS redirect carries embedded credentials');
+    }
+    if (!isHostInGatewayFamily(next.hostname, gateway.hostname)) {
+        throw new Error(`IPFS redirect leaves the configured gateway (${next.hostname})`);
+    }
+    // Host family alone would let a self-hosted gateway (`http://127.0.0.1:8080/ipfs/`)
+    // pivot onto any other service on the same host. Compare the ports the
+    // requests actually reach, not the literal `URL.port` (#3439).
+    const nextPort = effectivePort(next);
+    if (nextPort !== effectivePort(gateway)) {
+        throw new Error(`IPFS redirect changes the gateway port (${nextPort})`);
+    }
+}
+/** Location for an error message, with any configured gateway credentials dropped. */
+function displayUrl(url) {
+    return `${url.origin}${url.pathname}`.slice(0, 100);
+}
+async function discardBody(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        // A body that refuses to cancel is not worth failing the request over.
+    }
+}
+/** Read a response body as bytes, refusing anything past `maxBytes`. */
+async function readBoundedBytes(response, maxBytes) {
+    const declared = Number(response.headers.get('content-length'));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        await discardBody(response);
+        throw new IpfsResponseTooLargeError(maxBytes, declared);
+    }
+    const body = response.body;
+    if (!body)
+        return new Uint8Array(0);
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                throw new IpfsResponseTooLargeError(maxBytes);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        try {
+            await reader.cancel();
+        }
+        catch {
+            // Already terminal; the read result (or throw) above is what matters.
+        }
+    }
+    const joined = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        joined.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return joined;
+}
+/** Read a response body as text, refusing anything past `maxBytes`. */
+async function readBoundedText(response, maxBytes) {
+    const joined = await readBoundedBytes(response, maxBytes);
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(joined);
+    }
+    catch {
+        throw new Error('IPFS response is not valid UTF-8');
+    }
+}
+/**
+ * Request `url`, resolving redirects here rather than in `fetch`, so every hop
+ * is revalidated against the configured gateway before it is requested.
+ * Returns the first non-redirect, ok response; its body is still unread.
+ */
+async function fetchThroughGateway(url, signal) {
+    const gateway = url;
+    let current = new URL(url);
+    for (let hop = 0;; hop += 1) {
+        const response = await fetch(current, { method: 'GET', redirect: 'manual', signal });
+        if (REDIRECT_STATUSES.has(response.status)) {
+            await discardBody(response);
+            if (hop >= MAX_IPFS_REDIRECT_HOPS) {
+                throw new Error(`IPFS fetch exceeded ${MAX_IPFS_REDIRECT_HOPS} redirects`);
+            }
+            const location = response.headers.get('location');
+            if (location === null || location.trim() === '') {
+                throw new Error(`IPFS gateway returned ${response.status} without a Location header`);
+            }
+            let next;
+            try {
+                next = new URL(location, current);
+            }
+            catch {
+                throw new Error('IPFS redirect Location is not a valid URL');
+            }
+            assertRedirectAllowed(next, current, gateway);
+            current = next;
+            continue;
+        }
+        if (!response.ok) {
+            await discardBody(response);
+            const message = `IPFS fetch failed: ${response.status} ${response.statusText} ` +
+                `(${displayUrl(current)}…)`;
+            // 404/410 is the gateway ANSWERING "not there" — the only status that carries absence.
+            // Every other one (429, 5xx, …) leaves the question open and stays a plain failure.
+            if (response.status === 404 || response.status === 410) {
+                throw new IpfsContentNotFoundError(message, response.status);
+            }
+            throw new Error(message);
+        }
+        return response;
+    }
+}
+async function fetchJson(url, signal, maxBytes) {
+    const response = await fetchThroughGateway(url, signal);
     const contentType = response.headers.get('content-type') ?? '';
-    if (contentType.includes('application/json'))
-        return response.json();
-    const text = await response.text();
+    const text = await readBoundedText(response, maxBytes);
     try {
         return JSON.parse(text);
     }
@@ -45,6 +298,16 @@ async function fetchJson(url, signal) {
         throw new Error(`IPFS response is not JSON (content-type: ${contentType || 'none'})`);
     }
 }
+async function fetchBytes(url, signal, maxBytes) {
+    return readBoundedBytes(await fetchThroughGateway(url, signal), maxBytes);
+}
+function resolveMaxResponseBytes(opts) {
+    const requested = opts?.maxResponseBytes;
+    if (typeof requested !== 'number' || !Number.isFinite(requested) || requested < 1) {
+        return DEFAULT_MAX_IPFS_RESPONSE_BYTES;
+    }
+    return Math.floor(requested);
+}
 function resolveFallbackGatewayBases(opts) {
     if (opts?.fallbackGatewayBase === false)
         return [];
@@ -53,29 +316,114 @@ function resolveFallbackGatewayBases(opts) {
     }
     return [['fallback', FALLBACK_IPFS_GATEWAY_BASE]];
 }
-/** Read-only multi-codec, primary-plus-fallback IPFS JSON fetch. */
-export async function fetchFromIpfs(gatewayUrl, cid, opts) {
+/**
+ * Resolve one CID path against its gateway base and refuse anything that leaves
+ * the base's `/ipfs/` prefix (#3440).
+ *
+ * The CID reaches this from a manifest, so plain interpolation let
+ * `../../evil` walk out of the prefix and issue `GET /evil` against the
+ * gateway. Resolving through `URL` normalizes the `..` segments; comparing the
+ * result back against the base then also rejects the absolute-path (`/admin`)
+ * and absolute-URL (`https://evil/`) shapes. A strict CID regex would be the
+ * wrong guard: `buildIpfsFetchCidPathCandidates` documents `<cid>/path/to/file`
+ * as a legitimate gateway path.
+ *
+ * `URL` does not decode percent-encoded segments, so a `%2e%2e%2f` spelling
+ * still leaves the prefix intact here and is resolved, if at all, by the
+ * gateway. That is unchanged from the pre-guard behaviour and stays bounded by
+ * the same two properties: the origin is pinned, and the bytes are sha256-gated
+ * downstream in `acquire.ts`.
+ */
+function resolveGatewayCandidateUrl(baseUrl, cidPath) {
+    let base;
+    let resolved;
+    try {
+        base = new URL(baseUrl);
+        resolved = new URL(cidPath, base);
+    }
+    catch {
+        return { reason: 'candidate URL could not be parsed' };
+    }
+    if (resolved.origin !== base.origin || !resolved.pathname.startsWith(base.pathname)) {
+        return { reason: 'candidate URL escapes the gateway path prefix' };
+    }
+    return { url: resolved };
+}
+/**
+ * Run every gateway x CID candidate through `read`, under one whole-operation
+ * deadline. Shared by the JSON and raw-bytes entry points so both inherit the
+ * same redirect revalidation, byte cap, and deadline (#3438).
+ */
+async function fetchCandidatesFromIpfs(gatewayUrl, cid, opts, read, failureLabel) {
     const primary = normalizeIpfsGatewayBase(gatewayUrl);
     const gateways = [
         ['primary', primary],
         ...resolveFallbackGatewayBases(opts),
     ];
-    const errors = [];
+    const maxBytes = resolveMaxResponseBytes(opts);
+    const attempts = [];
     for (const cidPath of buildIpfsFetchCidPathCandidates(cid)) {
-        for (const [name, baseUrl] of gateways) {
-            const url = `${baseUrl}${cidPath}`;
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), IPFS_FETCH_TIMEOUT_MS);
-            try {
-                return await fetchJson(url, controller.signal);
-            }
-            catch (error) {
-                errors.push(`${name}:${url.slice(0, 100)}: ${error instanceof Error ? error.message : String(error)}`);
-            }
-            finally {
-                clearTimeout(timer);
-            }
+        for (const [name, baseUrl] of gateways)
+            attempts.push([name, baseUrl, cidPath]);
+    }
+    const errors = [];
+    // Parallel to `errors`: the display message is for the operator, the cause is what
+    // `classifyIpfsFetchFailure` reads to tell a size refusal and a transport failure apart from
+    // genuine absence (#3451).
+    const causes = [];
+    const deadline = Date.now() + IPFS_TOTAL_FETCH_TIMEOUT_MS;
+    for (let index = 0; index < attempts.length; index += 1) {
+        const [name, baseUrl, cidPath] = attempts[index];
+        const remainingMs = deadline - Date.now();
+        if (remainingMs <= 0) {
+            const message = `whole-operation timeout after ${IPFS_TOTAL_FETCH_TIMEOUT_MS}ms`;
+            errors.push(message);
+            causes.push(new Error(message));
+            break;
+        }
+        // Share what is left of the budget across the candidates still to try, so a
+        // run of slow early candidates cannot starve a later one that would have
+        // succeeded. Without this the whole-operation bound would silently narrow
+        // the candidate matrix instead of only bounding it.
+        const attemptMs = Math.min(IPFS_FETCH_TIMEOUT_MS, Math.ceil(remainingMs / (attempts.length - index)));
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), attemptMs);
+        // Resolved once here rather than inside the catch, so a candidate that
+        // cannot be parsed or that escapes the gateway prefix is reported as a
+        // candidate failure instead of escaping as a bare throw that discards the
+        // other candidates' errors.
+        const candidate = resolveGatewayCandidateUrl(baseUrl, cidPath);
+        if (!('url' in candidate)) {
+            const message = `${name}: ${candidate.reason}`;
+            errors.push(message);
+            causes.push(new Error(message));
+            clearTimeout(timer);
+            continue;
+        }
+        const target = candidate.url;
+        try {
+            return await read(target, controller.signal, maxBytes);
+        }
+        catch (error) {
+            errors.push(`${name}:${displayUrl(target)}: ` +
+                `${error instanceof Error ? error.message : String(error)}`);
+            causes.push(error);
+        }
+        finally {
+            clearTimeout(timer);
         }
     }
-    throw new Error(`IPFS JSON fetch failed after all candidates: ${errors.join(' | ')}`);
+    throw new IpfsFetchFailedError(`${failureLabel}: ${errors.join(' | ')}`, causes);
+}
+/** Read-only multi-codec, primary-plus-fallback IPFS JSON fetch. */
+export async function fetchFromIpfs(gatewayUrl, cid, opts) {
+    return fetchCandidatesFromIpfs(gatewayUrl, cid, opts, fetchJson, 'IPFS JSON fetch failed after all candidates');
+}
+/**
+ * Read-only multi-codec, primary-plus-fallback IPFS fetch returning the exact
+ * bytes stored at the CID — no JSON parse/re-encode roundtrip. Use this
+ * whenever the bytes will be hashed, or whenever the content is not JSON.
+ */
+export async function fetchBytesFromIpfs(gatewayUrl, cid, opts) {
+    return fetchCandidatesFromIpfs(gatewayUrl, cid, opts, fetchBytes, 'IPFS raw bytes fetch failed after all candidates');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jinn-network/core",
-  "version": "0.1.2-canary.b91a66df",
+  "version": "0.1.2-canary.bebeb033",
   "description": "Domain core for Jinn — evidence/contribution stores, scrub, trajectory parsing, and corpus reads. Independent of operator/src.",
   "type": "module",
   "packageManager": "yarn@4.13.0",
@@ -43,7 +43,7 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",
-    "@jinn-network/plugin": "0.1.2-canary.b91a66df",
+    "@jinn-network/plugin": "0.1.2-canary.bebeb033",
     "@lmoe/gliner-onnx": "0.1.0",
     "@noble/hashes": "^2.2.0",
     "@secretlint/core": "^13.0.2",