@atomicmemory/core 1.0.0

package/dist/storage/providers/filecoin/synapse-readiness.js

@@ -0,0 +1,231 @@
+/**
+ * @file Real Synapse-backed readiness probes.
+ *
+ * Lives in its own module to keep `synapse-client.ts` under the
+ * workspace 400-LOC cap. Exports `synapseCheckReadiness(synapse,
+ * options, network)` which runs the non-mutating probes
+ * documented in `FILECOIN_READINESS_REQUIRED_CHECKS` and returns
+ * the closed-shape check list `FilecoinProviderClient.checkReadiness`
+ * promises.
+ *
+ * All probes are non-mutating SDK reads:
+ *   - `storage.getStorageInfo()`  — pricing / providers / allowances / service bounds
+ *   - `storage.getUploadCosts()`  — canonical "ready to upload at this size" probe
+ *   - `storage.findDataSets()`    — owned data-set inventory (no creation)
+ *   - `client.getChainId()`       — connected-chain id
+ *
+ * Sanitization rule: NO call inside this module ever lets a wallet
+ * address, balance numeric, allowance numeric, provider auth payload,
+ * or raw vendor error message escape. Every check carries a stable
+ * `errorCode` from the closed set documented inline below.
+ */
+import { calibration, mainnet } from '@filoz/synapse-sdk';
+/**
+ * Run the documented Synapse readiness probes. Returns the closed-
+ * shape check list in `FILECOIN_READINESS_REQUIRED_CHECKS` order.
+ * All calls are non-mutating: `getStorageInfo()`,
+ * `getUploadCosts()`, `findDataSets()`, `client.getChainId()`. No
+ * upload, no data-set creation, no payment side-effects.
+ */
+export async function synapseCheckReadiness(synapse, options, network) {
+    const storage = await fetchStorageInfo(synapse);
+    const chain = await chainCheck(synapse, network, storage.errorCode);
+    const payment = await paymentCheck(synapse, options, storage);
+    const dataSet = await dataSetCheck(synapse, storage.errorCode);
+    return [
+        networkReachableCheck(storage.errorCode),
+        keyLoadableCheck(),
+        chain,
+        payment,
+        providerIdsCheck(options.providerIds, storage.info, storage.errorCode),
+        dataSet,
+        retrievalAvailableCheck(),
+        uploadSizeBoundsCheck(options, storage.info, storage.errorCode),
+    ];
+}
+async function fetchStorageInfo(synapse) {
+    try {
+        const info = await synapse.storage.getStorageInfo();
+        return { info, errorCode: null };
+    }
+    catch {
+        return { info: null, errorCode: 'network_unreachable' };
+    }
+}
+async function chainCheck(synapse, network, storageError) {
+    if (storageError !== null)
+        return blockedByNetwork('account_on_expected_network');
+    const expected = expectedChainIdFor(network);
+    let actual;
+    try {
+        actual = await synapse.client.getChainId();
+    }
+    catch {
+        return failed('account_on_expected_network', 'network_unreachable');
+    }
+    if (BigInt(actual) === expected)
+        return passed('account_on_expected_network');
+    return failed('account_on_expected_network', 'chain_mismatch');
+}
+/**
+ * Map the AtomicMemory readiness network to the canonical Synapse
+ * chain id. The SDK exports the chain objects directly; importing
+ * them here means a future SDK that re-numbers calibration or
+ * adds a new network surfaces at the boundary, not silently.
+ */
+function expectedChainIdFor(network) {
+    switch (network) {
+        case 'calibration':
+            return BigInt(calibration.id);
+        case 'mainnet':
+            return BigInt(mainnet.id);
+    }
+}
+async function dataSetCheck(synapse, storageError) {
+    if (storageError !== null)
+        return blockedByNetwork('data_set_available');
+    try {
+        const sets = await synapse.storage.findDataSets();
+        if (sets.length === 0) {
+            // Cold-start state — first upload creates one. Reported as
+            // `'unknown'` rather than `'failed'` because the absence is
+            // expected before any upload.
+            return {
+                name: 'data_set_available',
+                status: 'unknown',
+                errorCode: 'data_set_not_yet_created',
+            };
+        }
+        return passed('data_set_available');
+    }
+    catch {
+        return failed('data_set_available', 'network_unreachable');
+    }
+}
+function networkReachableCheck(storageError) {
+    if (storageError === null)
+        return passed('network_reachable');
+    return failed('network_reachable', storageError);
+}
+function keyLoadableCheck() {
+    // The Synapse instance was constructed via `buildSynapse`, which
+    // calls `viem/accounts.privateKeyToAccount`. Reaching this code
+    // implies the key syntactically loaded; readiness reports the
+    // check as `'passed'` rather than re-probing the key material.
+    return passed('key_loadable');
+}
+/**
+ * Payment readiness in three layers:
+ *   1. If `getStorageInfo` failed upstream, cascade to
+ *      `blocked_by_network_unreachable`.
+ *   2. Use the cheap `allowances` snapshot to detect obvious
+ *      mis-configuration (null / not approved / exhausted) — fail
+ *      fast with a precise code.
+ *   3. If the snapshot looks OK, issue `getUploadCosts(minUploadSize)`
+ *      as the canonical "are you ready for a min-size upload"
+ *      probe. `result.ready === true` → passed;
+ *      `result.ready === false` →
+ *      `payment_min_upload_cost_insufficient`; throw →
+ *      `blocked_by_network_unreachable`. NEVER returns passed
+ *      without the SDK affirming `ready`.
+ */
+async function paymentCheck(synapse, options, storage) {
+    if (storage.errorCode !== null)
+        return blockedByNetwork('payment_covers_minimum_upload');
+    const info = storage.info;
+    if (info === null || info.allowances === null) {
+        return failed('payment_covers_minimum_upload', 'payment_allowance_not_configured');
+    }
+    const a = info.allowances;
+    if (!a.isApproved)
+        return failed('payment_covers_minimum_upload', 'payment_allowance_not_approved');
+    if (a.rateAllowance <= a.rateUsed) {
+        return failed('payment_covers_minimum_upload', 'payment_rate_allowance_exhausted');
+    }
+    if (a.lockupAllowance <= a.lockupUsed) {
+        return failed('payment_covers_minimum_upload', 'payment_lockup_allowance_exhausted');
+    }
+    return probeMinUploadCost(synapse, info, options);
+}
+async function probeMinUploadCost(synapse, info, options) {
+    const dataSize = BigInt(info.serviceParameters.minUploadSize);
+    let costs;
+    try {
+        costs = await synapse.storage.getUploadCosts({
+            dataSize,
+            ...(options.withCdn !== undefined ? { withCDN: options.withCdn } : {}),
+        });
+    }
+    catch {
+        return blockedByNetwork('payment_covers_minimum_upload');
+    }
+    if (costs.ready)
+        return passed('payment_covers_minimum_upload');
+    return failed('payment_covers_minimum_upload', 'payment_min_upload_cost_insufficient');
+}
+function providerIdsCheck(configured, info, storageError) {
+    if (storageError !== null)
+        return blockedByNetwork('provider_ids_reachable');
+    // If no operator-pinned providers, the SDK picks at upload time;
+    // we only verify the SDK saw at least one provider.
+    if (configured.length === 0) {
+        if (info && info.providers.length === 0) {
+            return failed('provider_ids_reachable', 'no_providers_listed');
+        }
+        return passed('provider_ids_reachable');
+    }
+    if (info === null)
+        return blockedByNetwork('provider_ids_reachable');
+    const listed = new Set(info.providers.map((p) => p.id.toString()));
+    for (const id of configured) {
+        if (!listed.has(id))
+            return failed('provider_ids_reachable', 'provider_id_not_listed');
+    }
+    return passed('provider_ids_reachable');
+}
+function retrievalAvailableCheck() {
+    // No non-mutating retrieval primitive exposed on `StorageManager`
+    // in this SDK release: `pieceStatus` is per-context, and the cheap
+    // "is the SDK retrieval path healthy" question has no SDK answer.
+    // Reported as
+    // `'unknown' / 'not_implemented'` (truly not yet implemented) so
+    // operators can distinguish this from cascade-blocked checks.
+    return notImplemented('retrieval_available');
+}
+function uploadSizeBoundsCheck(options, info, storageError) {
+    if (storageError !== null)
+        return blockedByNetwork('upload_size_bounds_compatible');
+    if (info === null)
+        return blockedByNetwork('upload_size_bounds_compatible');
+    const svcMin = info.serviceParameters.minUploadSize;
+    const svcMax = info.serviceParameters.maxUploadSize;
+    if (svcMin > svcMax) {
+        return failed('upload_size_bounds_compatible', 'upload_size_bounds_invalid');
+    }
+    if (options.maxUploadBytes !== null && options.maxUploadBytes > svcMax) {
+        return failed('upload_size_bounds_compatible', 'max_upload_exceeds_service');
+    }
+    if (options.minUploadBytes !== null && options.minUploadBytes < svcMin) {
+        return failed('upload_size_bounds_compatible', 'min_upload_below_service');
+    }
+    return passed('upload_size_bounds_compatible');
+}
+function passed(name) {
+    return { name, status: 'passed' };
+}
+function failed(name, errorCode) {
+    return { name, status: 'failed', errorCode };
+}
+/**
+ * Unknown because a more-fundamental upstream check failed (almost
+ * always `network_reachable`). Distinguished from `notImplemented`
+ * via the `blocked_by_network_unreachable` code so operators see
+ * "this couldn't be evaluated, not 'we haven't built it yet'".
+ */
+function blockedByNetwork(name) {
+    return { name, status: 'unknown', errorCode: 'blocked_by_network_unreachable' };
+}
+/** Unknown because the check itself is not wired yet. */
+function notImplemented(name) {
+    return { name, status: 'unknown', errorCode: 'not_implemented' };
+}

package/dist/storage/providers/filecoin/uri.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @file Canonical Filecoin storage URI helpers.
+ *
+ * The plan pins the URI shape at `filecoin://piece/<pieceCid>` —
+ * PieceCID-centered identity per the design doc's URI Contract
+ * section. No query string, no fragment, no compatibility shim
+ * for legacy `ipfs://` rows.
+ *
+ * Phase 3 hardening: both helpers validate the PieceCID portion
+ * using the LIVE Synapse SDK parser (`asPieceCID` from
+ * `@filoz/synapse-core/piece`, wrapped in `./piece-cid.js`). A
+ * PieceCID that does not round-trip through the SDK's
+ * codec-aware parser (CIDv1, raw codec 0x55, multihash 0x1011)
+ * is rejected here, BEFORE the URI ever flows to head/get/delete
+ * or to the sidecar persister — eliminating the class of bug
+ * where a regex-valid-but-codec-invalid CID would be persisted
+ * and then fail downstream with a vendor-shaped error. The
+ * shared structural regex (`filecoin-cid-validation.ts`) is NOT
+ * used here; it lives on the eager-import path and is the
+ * narrower belt-and-suspenders gate for the public projection.
+ *
+ * Errors are typed `FilecoinProviderError` with sanitized codes:
+ *
+ *   - `invalid_uri` — wrong scheme/host/shape (extra segments,
+ *     missing piece host, query, fragment, non-string input).
+ *   - `invalid_piece_cid` — shape OK but the trailing CID is
+ *     not a valid PieceCIDv2 per the SDK parser.
+ *
+ * Callers never see a raw `URL` parser stack or vendor-shaped
+ * error.
+ */
+/**
+ * Format a PieceCID into the canonical AtomicMemory storage URI.
+ * Throws `invalid_piece_cid` when the input is not a valid
+ * PieceCIDv2 (per the live Synapse SDK parser); throws
+ * `invalid_uri` when the input is empty or contains characters
+ * that aren't URI-safe. The returned URI carries the SDK's
+ * canonical string form of the PieceCID — non-canonical inputs
+ * either fail parsing or are normalized here.
+ */
+export declare function formatPieceUri(pieceCid: string): string;
+/**
+ * Parse a `filecoin://piece/<pieceCid>` URI and return the
+ * PieceCID in the SDK's canonical string form. Throws
+ * `invalid_uri` on a wrong scheme/host/shape; throws
+ * `invalid_piece_cid` when the URI shape is correct but the
+ * trailing CID is not a valid PieceCIDv2 per the SDK parser.
+ */
+export declare function parsePieceUri(uri: string): string;

package/dist/storage/providers/filecoin/uri.js

@@ -0,0 +1,84 @@
+/**
+ * @file Canonical Filecoin storage URI helpers.
+ *
+ * The plan pins the URI shape at `filecoin://piece/<pieceCid>` —
+ * PieceCID-centered identity per the design doc's URI Contract
+ * section. No query string, no fragment, no compatibility shim
+ * for legacy `ipfs://` rows.
+ *
+ * Phase 3 hardening: both helpers validate the PieceCID portion
+ * using the LIVE Synapse SDK parser (`asPieceCID` from
+ * `@filoz/synapse-core/piece`, wrapped in `./piece-cid.js`). A
+ * PieceCID that does not round-trip through the SDK's
+ * codec-aware parser (CIDv1, raw codec 0x55, multihash 0x1011)
+ * is rejected here, BEFORE the URI ever flows to head/get/delete
+ * or to the sidecar persister — eliminating the class of bug
+ * where a regex-valid-but-codec-invalid CID would be persisted
+ * and then fail downstream with a vendor-shaped error. The
+ * shared structural regex (`filecoin-cid-validation.ts`) is NOT
+ * used here; it lives on the eager-import path and is the
+ * narrower belt-and-suspenders gate for the public projection.
+ *
+ * Errors are typed `FilecoinProviderError` with sanitized codes:
+ *
+ *   - `invalid_uri` — wrong scheme/host/shape (extra segments,
+ *     missing piece host, query, fragment, non-string input).
+ *   - `invalid_piece_cid` — shape OK but the trailing CID is
+ *     not a valid PieceCIDv2 per the SDK parser.
+ *
+ * Callers never see a raw `URL` parser stack or vendor-shaped
+ * error.
+ */
+import { FilecoinProviderError } from './errors.js';
+import { requirePieceCid } from './piece-cid.js';
+const FILECOIN_URI_SCHEME = 'filecoin:';
+const FILECOIN_URI_PIECE_HOST = 'piece';
+const FILECOIN_URI_PREFIX = `${FILECOIN_URI_SCHEME}//${FILECOIN_URI_PIECE_HOST}/`;
+/**
+ * Format a PieceCID into the canonical AtomicMemory storage URI.
+ * Throws `invalid_piece_cid` when the input is not a valid
+ * PieceCIDv2 (per the live Synapse SDK parser); throws
+ * `invalid_uri` when the input is empty or contains characters
+ * that aren't URI-safe. The returned URI carries the SDK's
+ * canonical string form of the PieceCID — non-canonical inputs
+ * either fail parsing or are normalized here.
+ */
+export function formatPieceUri(pieceCid) {
+    const trimmed = pieceCid.trim();
+    if (trimmed.length === 0) {
+        throw new FilecoinProviderError('invalid_uri', 'Cannot format Filecoin URI: PieceCID is empty.');
+    }
+    if (/\s/.test(trimmed) || /[/?#]/.test(trimmed)) {
+        throw new FilecoinProviderError('invalid_uri', "PieceCID contains characters that are not URI-safe (whitespace or '/?#').");
+    }
+    // `requirePieceCid` runs the SDK's `asPieceCID` parser and
+    // returns the canonical string form. The error message is
+    // sanitized (no value echo) — malformed CIDs may encode
+    // adversarial bytes worth keeping out of log streams. The
+    // closed-set `errorCode` is the diagnostic surface.
+    const canonical = requirePieceCid(trimmed, 'PieceCID input');
+    return `${FILECOIN_URI_PREFIX}${canonical}`;
+}
+/**
+ * Parse a `filecoin://piece/<pieceCid>` URI and return the
+ * PieceCID in the SDK's canonical string form. Throws
+ * `invalid_uri` on a wrong scheme/host/shape; throws
+ * `invalid_piece_cid` when the URI shape is correct but the
+ * trailing CID is not a valid PieceCIDv2 per the SDK parser.
+ */
+export function parsePieceUri(uri) {
+    if (typeof uri !== 'string' || uri.length === 0) {
+        throw new FilecoinProviderError('invalid_uri', 'Filecoin storage URI is missing or not a string.');
+    }
+    if (!uri.startsWith(FILECOIN_URI_PREFIX)) {
+        throw new FilecoinProviderError('invalid_uri', `Filecoin storage URI must start with '${FILECOIN_URI_PREFIX}'.`);
+    }
+    const remainder = uri.slice(FILECOIN_URI_PREFIX.length);
+    if (remainder.length === 0) {
+        throw new FilecoinProviderError('invalid_uri', `Filecoin storage URI '${FILECOIN_URI_PREFIX}' has no PieceCID.`);
+    }
+    if (remainder.includes('/') || remainder.includes('?') || remainder.includes('#')) {
+        throw new FilecoinProviderError('invalid_uri', "Filecoin storage URI must not contain extra segments, query strings, or fragments.");
+    }
+    return requirePieceCid(remainder, 'storage URI');
+}

package/dist/storage/providers/filecoin/verified-fetch-lifecycle.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @file Bounded-lifecycle + body-reading helpers for the
+ * verified-fetch retriever.
+ *
+ * Lifted out of `verified-fetch-retriever.ts` so the retriever
+ * file stays focused on the `FilecoinRetriever` implementation
+ * and this file owns the (subtle) timer-lifetime + race-loser
+ * contracts. The retriever wires these helpers together; the
+ * helpers do not import the retriever or any optional vendor
+ * package. Source-build-safety invariant
+ * (`filecoin-pin-lazy-boundary.test.ts`) requires zero static
+ * imports of `@helia/verified-fetch` / `@helia/*` etc. from
+ * this file.
+ *
+ * Contract summary:
+ *
+ *   - `startLifecycle(timeoutMs)` builds an `AbortController` +
+ *     a `setTimeout` cleared by `cancel()`. The sentinel
+ *     promise rejects with `verified_fetch_timeout` on abort.
+ *   - `runBoundedRetrieval` wraps fetch + classify + body-read
+ *     in ONE `Promise.race` against the timeout sentinel.
+ *   - `readBoundedBody` synchronously short-circuits when
+ *     `signal.aborted` is already true (race-loser path) so a
+ *     late-resolving fetch cannot leak a hung `reader.read()`.
+ *   - `requireParsedCid` re-parses through `CID.parse`; an
+ *     attacker-controlled `{ toString: () => 'https://attacker' }`
+ *     is rejected.
+ *   - `mapVerifiedFetchFailure` collapses any non-typed throw
+ *     into the closed `verified_fetch_*` error-code set.
+ */
+import { FilecoinProviderError } from './errors.js';
+import type { MinimalVerifiedFetch } from './verified-fetch-vendor.js';
+/**
+ * Defence-in-depth runtime guard. The TS signature already
+ * requires a `CID`, but a JS caller bypassing the types must
+ * still be rejected. Critically, "looks like an object with a
+ * `toString()`" is NOT sufficient — an attacker-controlled
+ * `{ toString: () => 'https://attacker.example.com' }` would
+ * otherwise let an `ipfs://https://...` URL escape into
+ * verified-fetch. We re-parse the candidate's string form
+ * through `multiformats/cid.CID.parse`, which only accepts a
+ * real CID multibase string. Returns the canonical multibase
+ * form for the caller to consume.
+ */
+export declare function requireParsedCid(value: unknown): string;
+export interface RetrievalLifecycle {
+    readonly aborter: AbortController | null;
+    readonly timeoutRejection: Promise<never> | null;
+    cancel(): void;
+}
+/**
+ * Build the timeout + abort handle for a single retrieval. A
+ * non-null `aborter` is created only when `timeoutMs > 0`. The
+ * sentinel promise rejects with `verified_fetch_timeout` when
+ * the controller fires. `cancel()` clears the underlying timer
+ * on the success path so we don't leak a pending `setTimeout`
+ * past `get`'s lifetime.
+ */
+export declare function startLifecycle(timeoutMs: number | undefined): RetrievalLifecycle;
+/**
+ * Run the entire fetch + classify + bounded-body-read sequence
+ * inside ONE `Promise.race` against the timeout sentinel. Race
+ * coverage extends past the initial fetch into body consumption
+ * so a vendor whose `reader.read()` never settles still cannot
+ * outlast `timeoutMs`. The signal is also forwarded into the
+ * body reader so a real Web-Streams implementation cancels its
+ * pending read on abort — the race is the deterministic
+ * back-stop for mocks / vendors that do not.
+ */
+export declare function runBoundedRetrieval(args: {
+    readonly fetch: MinimalVerifiedFetch;
+    readonly url: string;
+    readonly maxBytes: number;
+    readonly signal: AbortSignal | undefined;
+    readonly timeoutRejection: Promise<never> | null;
+}): Promise<Buffer>;
+export declare function mapVerifiedFetchFailure(err: unknown, aborter: AbortController | null, timeoutMs: number | undefined): FilecoinProviderError;

package/dist/storage/providers/filecoin/verified-fetch-lifecycle.js

@@ -0,0 +1,196 @@
+/**
+ * @file Bounded-lifecycle + body-reading helpers for the
+ * verified-fetch retriever.
+ *
+ * Lifted out of `verified-fetch-retriever.ts` so the retriever
+ * file stays focused on the `FilecoinRetriever` implementation
+ * and this file owns the (subtle) timer-lifetime + race-loser
+ * contracts. The retriever wires these helpers together; the
+ * helpers do not import the retriever or any optional vendor
+ * package. Source-build-safety invariant
+ * (`filecoin-pin-lazy-boundary.test.ts`) requires zero static
+ * imports of `@helia/verified-fetch` / `@helia/*` etc. from
+ * this file.
+ *
+ * Contract summary:
+ *
+ *   - `startLifecycle(timeoutMs)` builds an `AbortController` +
+ *     a `setTimeout` cleared by `cancel()`. The sentinel
+ *     promise rejects with `verified_fetch_timeout` on abort.
+ *   - `runBoundedRetrieval` wraps fetch + classify + body-read
+ *     in ONE `Promise.race` against the timeout sentinel.
+ *   - `readBoundedBody` synchronously short-circuits when
+ *     `signal.aborted` is already true (race-loser path) so a
+ *     late-resolving fetch cannot leak a hung `reader.read()`.
+ *   - `requireParsedCid` re-parses through `CID.parse`; an
+ *     attacker-controlled `{ toString: () => 'https://attacker' }`
+ *     is rejected.
+ *   - `mapVerifiedFetchFailure` collapses any non-typed throw
+ *     into the closed `verified_fetch_*` error-code set.
+ */
+import { CID } from 'multiformats/cid';
+import { FilecoinProviderError } from './errors.js';
+/**
+ * Defence-in-depth runtime guard. The TS signature already
+ * requires a `CID`, but a JS caller bypassing the types must
+ * still be rejected. Critically, "looks like an object with a
+ * `toString()`" is NOT sufficient — an attacker-controlled
+ * `{ toString: () => 'https://attacker.example.com' }` would
+ * otherwise let an `ipfs://https://...` URL escape into
+ * verified-fetch. We re-parse the candidate's string form
+ * through `multiformats/cid.CID.parse`, which only accepts a
+ * real CID multibase string. Returns the canonical multibase
+ * form for the caller to consume.
+ */
+export function requireParsedCid(value) {
+    const shapedLikeCid = typeof value === 'object' &&
+        value !== null &&
+        typeof value.toString === 'function';
+    if (!shapedLikeCid)
+        throw invalidCidError();
+    const candidate = value.toString();
+    if (typeof candidate !== 'string')
+        throw invalidCidError();
+    try {
+        return CID.parse(candidate).toString();
+    }
+    catch {
+        throw invalidCidError();
+    }
+}
+function invalidCidError() {
+    return new FilecoinProviderError('verified_fetch_invalid_cid', 'Verified-fetch retriever requires a parsed CID instance, not a URL or arbitrary string.');
+}
+/**
+ * Build the timeout + abort handle for a single retrieval. A
+ * non-null `aborter` is created only when `timeoutMs > 0`. The
+ * sentinel promise rejects with `verified_fetch_timeout` when
+ * the controller fires. `cancel()` clears the underlying timer
+ * on the success path so we don't leak a pending `setTimeout`
+ * past `get`'s lifetime.
+ */
+export function startLifecycle(timeoutMs) {
+    if (timeoutMs === undefined || timeoutMs <= 0) {
+        return { aborter: null, timeoutRejection: null, cancel: () => undefined };
+    }
+    const aborter = new AbortController();
+    const timer = setTimeout(() => aborter.abort(), timeoutMs);
+    timer.unref?.();
+    const timeoutRejection = new Promise((_, reject) => {
+        aborter.signal.addEventListener('abort', () => {
+            reject(new FilecoinProviderError('verified_fetch_timeout', `Verified-fetch retrieval aborted after ${timeoutMs} ms.`));
+        }, { once: true });
+    });
+    timeoutRejection.catch(() => undefined);
+    return {
+        aborter,
+        timeoutRejection,
+        cancel() { clearTimeout(timer); },
+    };
+}
+/**
+ * Run the entire fetch + classify + bounded-body-read sequence
+ * inside ONE `Promise.race` against the timeout sentinel. Race
+ * coverage extends past the initial fetch into body consumption
+ * so a vendor whose `reader.read()` never settles still cannot
+ * outlast `timeoutMs`. The signal is also forwarded into the
+ * body reader so a real Web-Streams implementation cancels its
+ * pending read on abort — the race is the deterministic
+ * back-stop for mocks / vendors that do not.
+ */
+export async function runBoundedRetrieval(args) {
+    const operation = (async () => {
+        const response = await args.fetch(args.url, args.signal !== undefined ? { signal: args.signal } : undefined);
+        classifyResponse(response);
+        return readBoundedBody(response, args.maxBytes, args.signal);
+    })();
+    if (args.timeoutRejection !== null) {
+        // Attach a no-op tail to the operation promise so its
+        // race-loser rejection (e.g. the `verified_fetch_timeout`
+        // `readBoundedBody` throws when it sees an already-aborted
+        // signal) does NOT surface as `unhandledRejection`. Node's
+        // tracker is satisfied; the rejection has nowhere else to
+        // go because the outer race already chose the timeout.
+        operation.catch(() => undefined);
+        return Promise.race([operation, args.timeoutRejection]);
+    }
+    return operation;
+}
+function classifyResponse(response) {
+    if (response.status === 404) {
+        throw new FilecoinProviderError('verified_fetch_not_found', 'Verified-fetch retrieval returned 404 — content not available on the IPFS network.');
+    }
+    if (!response.ok) {
+        throw new FilecoinProviderError('verified_fetch_failed', `Verified-fetch retrieval failed with status ${response.status}.`);
+    }
+}
+export function mapVerifiedFetchFailure(err, aborter, timeoutMs) {
+    if (err instanceof FilecoinProviderError)
+        return err;
+    if (aborter?.signal.aborted) {
+        return new FilecoinProviderError('verified_fetch_timeout', `Verified-fetch retrieval aborted after ${timeoutMs} ms.`);
+    }
+    return new FilecoinProviderError('verified_fetch_failed', 'Verified-fetch retrieval failed.');
+}
+/**
+ * Read the response body, enforcing a size cap that protects
+ * against unbounded retrieval. Synchronous race-loser exit if
+ * `signal.aborted` is already true (the outer race has already
+ * chosen the timeout sentinel) — cancels the reader, throws
+ * `verified_fetch_timeout`. Otherwise dispatches to one of the
+ * two streaming/buffered readers.
+ */
+async function readBoundedBody(response, maxBytes, signal) {
+    const reader = response.body?.getReader();
+    if (signal?.aborted)
+        await bailAlreadyAborted(reader);
+    if (reader === undefined)
+        return readBufferedBody(response, maxBytes);
+    return readStreamingBody(reader, maxBytes, signal);
+}
+async function bailAlreadyAborted(reader) {
+    if (reader !== undefined) {
+        try {
+            await reader.cancel();
+        }
+        catch { /* tear-down only */ }
+    }
+    throw new FilecoinProviderError('verified_fetch_timeout', 'Verified-fetch retrieval aborted before body read began.');
+}
+async function readBufferedBody(response, maxBytes) {
+    const buf = Buffer.from(await response.arrayBuffer());
+    if (buf.length > maxBytes) {
+        throw new FilecoinProviderError('verified_fetch_body_too_large', `Verified-fetch body exceeded the ${maxBytes}-byte ceiling.`);
+    }
+    return buf;
+}
+async function readStreamingBody(reader, maxBytes, signal) {
+    const onAbort = () => {
+        void reader.cancel().catch(() => undefined);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value !== undefined) {
+                total += value.byteLength;
+                if (total > maxBytes) {
+                    throw new FilecoinProviderError('verified_fetch_body_too_large', `Verified-fetch body exceeded the ${maxBytes}-byte ceiling.`);
+                }
+                chunks.push(value);
+            }
+        }
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+        try {
+            await reader.cancel();
+        }
+        catch { /* tear-down only */ }
+    }
+    return Buffer.concat(chunks);
+}