@atomicmemory/core 1.0.0

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

@@ -0,0 +1,275 @@
+/**
+ * @file Filecoin provider configuration.
+ *
+ * `parseFilecoinProviderConfig(env)` is the only env reader inside
+ * `src/storage/providers/filecoin/*`. Central `src/config.ts`
+ * collects `process.env` into a plain object and hands it to this
+ * function; the provider module never reaches for `process.env`
+ * itself, matching the workspace rule against direct env access in
+ * business code.
+ *
+ * The cross-provider guard — rejecting any `RAW_STORAGE_FILECOIN_*`
+ * environment variable when `RAW_STORAGE_PROVIDER` is non-filecoin —
+ * lives in central `src/config.ts`. Reason:
+ * `parseFilecoinProviderConfig` is only invoked when the provider IS
+ * filecoin, so the cross-provider rejection has to fire at the
+ * central seam to catch the misconfiguration. This module exports
+ * `collectFilecoinProviderEnvKeys` so the central code can compute
+ * which RAW_STORAGE_FILECOIN_* keys an operator set without
+ * embedding the prefix string in two places.
+ *
+ * v1 credential model: operator-owned deployment credentials.
+ * Storage-profile / per-org / per-user credential ownership is
+ * deferred to a future release. `RAW_STORAGE_FILECOIN_PRIVATE_KEY` is
+ * validated syntactically (`^0x[a-fA-F0-9]{64}$`) at startup. The
+ * value is NEVER logged on rejection; no account derivation, no
+ * chain, balance, and provider checks are handled by the readiness
+ * probes in `./readiness.ts`.
+ */
+import { FILECOIN_METADATA_RESERVED_PREFIXES, FILECOIN_METADATA_DENYLIST, } from './metadata.js';
+/** Prefix shared by every `RAW_STORAGE_FILECOIN_*` environment variable. */
+const FILECOIN_PROVIDER_ENV_PREFIX = 'RAW_STORAGE_FILECOIN_';
+const PRIVATE_KEY_PATTERN = /^0x[a-fA-F0-9]{64}$/;
+/**
+ * DATA_SET_METADATA constraints mirror the Synapse SDK's
+ * `METADATA_LIMITS` (docs.filecoin.cloud/reference/filoz/synapse-
+ * core/utils/variables/metadata_limits/): MAX_KEYS_PER_DATASET=10,
+ * MAX_KEY_LENGTH=32, MAX_VALUE_LENGTH=128. We enforce these
+ * server-side so a misconfigured operator can't get past startup
+ * with values Synapse would later reject. The key-charset
+ * allowlist (`[A-Za-z0-9_.:-]+`) and the credential-shape rejection
+ * are AtomicMemory-additional safety rails on top of the Synapse
+ * limits.
+ */
+const MAX_METADATA_KEYS = 10;
+const MAX_METADATA_KEY_LENGTH = 32;
+const MAX_METADATA_VALUE_LENGTH = 128;
+const METADATA_KEY_PATTERN = /^[A-Za-z0-9_.:-]+$/;
+/**
+ * Patterns rejected in both keys AND string values. Matches credential
+ * shapes (private keys, bearer tokens, UCAN proofs, signed requests,
+ * authorization headers). Match is case-insensitive on the raw input.
+ */
+const CREDENTIAL_VALUE_PATTERNS = [
+    /private[_-]?key/i,
+    /\bbearer\b/i,
+    /authorization/i,
+    /\bucan\b/i,
+    /signed[_-]?request/i,
+    /\bauth[_-]?header\b/i,
+    /\bsynapse[_-]?response\b/i,
+    /^0x[a-fA-F0-9]{64}$/,
+    /^eyJ[A-Za-z0-9_=-]+\.[A-Za-z0-9_.+/=-]+\.[A-Za-z0-9_.+/=-]+$/, // JWT-shaped
+];
+/**
+ * Syntactic-only validator for `RAW_STORAGE_FILECOIN_PRIVATE_KEY`.
+ * Accepts a 32-byte hex string with `0x` prefix (case-insensitive).
+ * Throws on any other shape WITHOUT echoing the value — the message
+ * names only the env var and the expected pattern.
+ */
+export function parseFilecoinPrivateKey(value) {
+    if (!PRIVATE_KEY_PATTERN.test(value)) {
+        throw new Error("RAW_STORAGE_FILECOIN_PRIVATE_KEY must match '^0x[a-fA-F0-9]{64}$' " +
+            "(0x-prefixed 32-byte hex).");
+    }
+    return value;
+}
+/**
+ * Return the names of every `RAW_STORAGE_FILECOIN_*` key the
+ * operator set to a non-empty value. Used by the central
+ * cross-provider guard in `src/config.ts` so non-filecoin
+ * deployments cannot accidentally carry Filecoin config.
+ */
+export function collectFilecoinProviderEnvKeys(env) {
+    const out = [];
+    for (const key of Object.keys(env)) {
+        if (!key.startsWith(FILECOIN_PROVIDER_ENV_PREFIX))
+            continue;
+        const value = env[key];
+        if (value !== undefined && value !== '')
+            out.push(key);
+    }
+    return out;
+}
+/**
+ * Parse + validate the Synapse-shaped Filecoin provider env block.
+ * Only invoked when `RAW_STORAGE_PROVIDER=filecoin`; the cross-
+ * provider guard runs in `src/config.ts` before this function.
+ */
+export function parseFilecoinProviderConfig(env) {
+    const driver = requireDriver(env['RAW_STORAGE_FILECOIN_DRIVER']);
+    const network = requireNetwork(env['RAW_STORAGE_FILECOIN_NETWORK']);
+    const privateKey = requirePrivateKey(env['RAW_STORAGE_FILECOIN_PRIVATE_KEY']);
+    const source = requireSource(env['RAW_STORAGE_FILECOIN_SOURCE']);
+    const withCdn = requireStrictBool(env['RAW_STORAGE_FILECOIN_WITH_CDN'], 'RAW_STORAGE_FILECOIN_WITH_CDN');
+    return {
+        driver,
+        network,
+        privateKey,
+        source,
+        withCdn,
+        providerIds: parseProviderIds(env['RAW_STORAGE_FILECOIN_PROVIDER_IDS']),
+        copies: parsePositiveIntOrNull(env['RAW_STORAGE_FILECOIN_COPIES'], 'RAW_STORAGE_FILECOIN_COPIES'),
+        dataSetMetadata: parseDataSetMetadata(env['RAW_STORAGE_FILECOIN_DATA_SET_METADATA']),
+        maxUploadBytes: parsePositiveIntOrNull(env['RAW_STORAGE_FILECOIN_MAX_UPLOAD_BYTES'], 'RAW_STORAGE_FILECOIN_MAX_UPLOAD_BYTES'),
+        minUploadBytes: parsePositiveIntOrNull(env['RAW_STORAGE_FILECOIN_MIN_UPLOAD_BYTES'], 'RAW_STORAGE_FILECOIN_MIN_UPLOAD_BYTES'),
+        uploadTimeoutMs: parsePositiveIntOrNull(env['RAW_STORAGE_FILECOIN_UPLOAD_TIMEOUT_MS'], 'RAW_STORAGE_FILECOIN_UPLOAD_TIMEOUT_MS'),
+        retrievalTimeoutMs: parsePositiveIntOrNull(env['RAW_STORAGE_FILECOIN_RETRIEVAL_TIMEOUT_MS'], 'RAW_STORAGE_FILECOIN_RETRIEVAL_TIMEOUT_MS'),
+    };
+}
+function requireDriver(value) {
+    if (value === 'synapse' || value === 'filecoin_pin')
+        return value;
+    throw new Error(`RAW_STORAGE_FILECOIN_DRIVER must equal 'synapse' or 'filecoin_pin' ` +
+        `(got '${value ?? '<unset>'}'). Phase 5 evaluation: 'synapse' is the ` +
+        "default direct driver; 'filecoin_pin' is the opt-in CAR-first driver " +
+        'backed by the `filecoin-pin` package. The driver choice is purely an ' +
+        'internal selector — neither value is exposed on any public surface.');
+}
+function requireNetwork(value) {
+    if (value === 'calibration' || value === 'mainnet')
+        return value;
+    throw new Error(`RAW_STORAGE_FILECOIN_NETWORK must be 'calibration' or 'mainnet' ` +
+        `(got '${value ?? '<unset>'}').`);
+}
+function requirePrivateKey(value) {
+    if (!value) {
+        throw new Error('RAW_STORAGE_FILECOIN_PRIVATE_KEY is required.');
+    }
+    return parseFilecoinPrivateKey(value);
+}
+function requireSource(value) {
+    const trimmed = value?.trim() ?? '';
+    if (trimmed.length === 0) {
+        throw new Error('RAW_STORAGE_FILECOIN_SOURCE is required (non-empty).');
+    }
+    return trimmed;
+}
+function requireStrictBool(value, name) {
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    throw new Error(`${name} must be 'true' or 'false' (got '${value ?? '<unset>'}').`);
+}
+/**
+ * Synapse SDK provider IDs are on-chain uint256 values; the wire
+ * encoding is a positive decimal bigint string. We validate the
+ * shape at startup (no leading zeros, no hex, no float, no zero,
+ * no negative) so the Synapse `BigInt(id)` cast inside
+ * `synapse-client.ts` can never throw a raw `SyntaxError` that
+ * escapes the provider boundary.
+ */
+const POSITIVE_DECIMAL_BIGINT = /^[1-9][0-9]*$/;
+function parseProviderIds(value) {
+    if (!value)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const raw of value.split(',')) {
+        const trimmed = raw.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (!POSITIVE_DECIMAL_BIGINT.test(trimmed)) {
+            throw new Error(`RAW_STORAGE_FILECOIN_PROVIDER_IDS entry '${trimmed}' is not a positive ` +
+                'decimal bigint (Synapse provider IDs are on-chain uint256 values).');
+        }
+        if (seen.has(trimmed)) {
+            throw new Error(`RAW_STORAGE_FILECOIN_PROVIDER_IDS contains duplicate entry '${trimmed}'.`);
+        }
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
+function parsePositiveIntOrNull(value, name) {
+    if (value === undefined || value === '')
+        return null;
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed < 1 || String(parsed) !== value.trim()) {
+        throw new Error(`${name} must be a positive integer (got '${value}').`);
+    }
+    return parsed;
+}
+function parseDataSetMetadata(raw) {
+    if (!raw)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('RAW_STORAGE_FILECOIN_DATA_SET_METADATA must be valid JSON.');
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('RAW_STORAGE_FILECOIN_DATA_SET_METADATA must be a JSON object.');
+    }
+    const obj = parsed;
+    const keys = Object.keys(obj);
+    if (keys.length > MAX_METADATA_KEYS) {
+        throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA exceeds ${MAX_METADATA_KEYS} keys.`);
+    }
+    const out = {};
+    for (const key of keys) {
+        rejectMetadataKey(key);
+        out[key] = coerceMetadataValue(key, obj[key]);
+    }
+    return out;
+}
+function rejectMetadataKey(key) {
+    rejectMetadataKeyShape(key);
+    rejectMetadataKeyReservedPrefix(key);
+    rejectMetadataKeyCredentialShape(key);
+}
+function rejectMetadataKeyShape(key) {
+    if (key.length === 0 || key.length > MAX_METADATA_KEY_LENGTH) {
+        throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA key length must be 1..${MAX_METADATA_KEY_LENGTH}.`);
+    }
+    if (!METADATA_KEY_PATTERN.test(key)) {
+        throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA key '${key}' contains disallowed characters. ` +
+            "Keys must match '[A-Za-z0-9_.:-]+'.");
+    }
+}
+function rejectMetadataKeyReservedPrefix(key) {
+    for (const prefix of FILECOIN_METADATA_RESERVED_PREFIXES) {
+        if (key.startsWith(prefix)) {
+            throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA key '${key}' uses reserved prefix '${prefix}'.`);
+        }
+    }
+}
+function rejectMetadataKeyCredentialShape(key) {
+    const lower = key.toLowerCase();
+    for (const denied of FILECOIN_METADATA_DENYLIST) {
+        if (lower === denied || lower.includes(denied)) {
+            throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA key '${key}' matches a denylisted credential shape.`);
+        }
+    }
+    for (const pattern of CREDENTIAL_VALUE_PATTERNS) {
+        if (pattern.test(key)) {
+            throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA key '${key}' matches a denylisted credential shape.`);
+        }
+    }
+}
+function coerceMetadataValue(key, value) {
+    if (typeof value === 'string') {
+        if (value.length > MAX_METADATA_VALUE_LENGTH) {
+            throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA value for '${key}' exceeds ` +
+                `${MAX_METADATA_VALUE_LENGTH} characters (got ${value.length}).`);
+        }
+        rejectCredentialShapedValue(key, value);
+        return value;
+    }
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'boolean')
+        return value;
+    throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA value for '${key}' must be a scalar ` +
+        '(string, finite number, or boolean).');
+}
+function rejectCredentialShapedValue(key, value) {
+    for (const pattern of CREDENTIAL_VALUE_PATTERNS) {
+        if (pattern.test(value)) {
+            throw new Error(`RAW_STORAGE_FILECOIN_DATA_SET_METADATA value for '${key}' matches a denylisted credential shape.`);
+        }
+    }
+}

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

@@ -0,0 +1,45 @@
+/**
+ * @file Filecoin provider error hierarchy.
+ *
+ * Every error thrown out of `src/storage/providers/filecoin/*` extends
+ * `FilecoinProviderError` so the route + reconciler layers can pattern
+ * match a single base class instead of probing for vendor-shaped
+ * variants. Two concrete cases are defined here:
+ *
+ * - `FilecoinNotImplementedError` — thrown by test-only provider
+ *   stubs. The route layer maps it onto a typed envelope so clients
+ *   see a stable code.
+ * - `FilecoinProviderNotConfiguredError` — thrown at construction
+ *   time when the test stub is asked to build a real client without
+ *   the operator having supplied the Synapse config (see
+ *   `./config.ts`). Surfaces at composition time, not first upload.
+ *
+ * Sanitization rule: any caller that wraps a vendor (Synapse, RPC,
+ * provider) error MUST replace the raw message with the public
+ * `errorCode` and discard the original `.message` / `.cause` chain
+ * before it crosses this boundary. Wallet addresses, private keys,
+ * provider IDs, balances, allowances, and signed-request payloads
+ * are not allowed in messages emitted from this module.
+ */
+export declare class FilecoinProviderError extends Error {
+    readonly errorCode: string;
+    constructor(errorCode: string, message: string);
+}
+/**
+ * Thrown by test-only provider stubs for provider operations
+ * (`put`, `get`, `head`, `delete`, `verify`). Carries a public
+ * `errorCode` so the route layer can map it onto a stable envelope
+ * without inspecting message strings.
+ */
+export declare class FilecoinNotImplementedError extends FilecoinProviderError {
+    constructor(operation: string);
+}
+/**
+ * Thrown at composition time when `createFilecoinStorageBackend` is
+ * called against a config that has not yet been populated with the
+ * Synapse fields. This error prevents a half-wired client from being
+ * built.
+ */
+export declare class FilecoinProviderNotConfiguredError extends FilecoinProviderError {
+    constructor(reason: string);
+}

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

@@ -0,0 +1,56 @@
+/**
+ * @file Filecoin provider error hierarchy.
+ *
+ * Every error thrown out of `src/storage/providers/filecoin/*` extends
+ * `FilecoinProviderError` so the route + reconciler layers can pattern
+ * match a single base class instead of probing for vendor-shaped
+ * variants. Two concrete cases are defined here:
+ *
+ * - `FilecoinNotImplementedError` — thrown by test-only provider
+ *   stubs. The route layer maps it onto a typed envelope so clients
+ *   see a stable code.
+ * - `FilecoinProviderNotConfiguredError` — thrown at construction
+ *   time when the test stub is asked to build a real client without
+ *   the operator having supplied the Synapse config (see
+ *   `./config.ts`). Surfaces at composition time, not first upload.
+ *
+ * Sanitization rule: any caller that wraps a vendor (Synapse, RPC,
+ * provider) error MUST replace the raw message with the public
+ * `errorCode` and discard the original `.message` / `.cause` chain
+ * before it crosses this boundary. Wallet addresses, private keys,
+ * provider IDs, balances, allowances, and signed-request payloads
+ * are not allowed in messages emitted from this module.
+ */
+export class FilecoinProviderError extends Error {
+    errorCode;
+    constructor(errorCode, message) {
+        super(message);
+        this.name = 'FilecoinProviderError';
+        this.errorCode = errorCode;
+    }
+}
+/**
+ * Thrown by test-only provider stubs for provider operations
+ * (`put`, `get`, `head`, `delete`, `verify`). Carries a public
+ * `errorCode` so the route layer can map it onto a stable envelope
+ * without inspecting message strings.
+ */
+export class FilecoinNotImplementedError extends FilecoinProviderError {
+    constructor(operation) {
+        super('filecoin_not_implemented', `Filecoin provider operation '${operation}' is not implemented in this build.`);
+        this.name = 'FilecoinNotImplementedError';
+    }
+}
+/**
+ * Thrown at composition time when `createFilecoinStorageBackend` is
+ * called against a config that has not yet been populated with the
+ * Synapse fields. This error prevents a half-wired client from being
+ * built.
+ */
+// fallow-ignore-next-line unused-export
+export class FilecoinProviderNotConfiguredError extends FilecoinProviderError {
+    constructor(reason) {
+        super('filecoin_provider_not_configured', `Filecoin provider not configured: ${reason}.`);
+        this.name = 'FilecoinProviderNotConfiguredError';
+    }
+}

package/dist/storage/providers/filecoin/filecoin-pin-car.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @file CAR-construction helpers for the filecoin-pin driver.
+ *
+ * The filecoin-pin path differs from the direct Synapse driver in
+ * one place: before handing bytes to the Synapse SDK it wraps them
+ * in a CAR file whose blocks form an IPFS UnixFS DAG. The Filecoin
+ * PieceCID is then computed over the CAR bytes (not the raw user
+ * content), and the IPFS root CID survives as a separate
+ * identifier — which is the value the Phase 4 `ipfs_cid` sidecar
+ * slot was designed to carry.
+ *
+ * Two seams live here:
+ *
+ *   - `buildCarFromBytes(body)` — convert a `Buffer` of raw user
+ *     bytes into a `{ carBytes, rootCid }` pair via Helia +
+ *     `@helia/unixfs`. Used by `FilecoinPinFilecoinProviderClient.put`
+ *     immediately before delegating to filecoin-pin's
+ *     `executeUpload`.
+ *
+ *   - `extractFileFromCar(carBytes, rootCid)` — the inverse:
+ *     parse a CAR by streaming its blocks back into an in-memory
+ *     blockstore, then unixfs-traverse from the root to materialise
+ *     the original bytes. Used by
+ *     `FilecoinPinFilecoinProviderClient.get` to reverse the CAR
+ *     wrapping the upload path applied.
+ *
+ * Vendor isolation. Every CAR / Helia / blockstore import lives
+ * inside the function bodies as a runtime `await import(...)`
+ * against a `const`-stored specifier. That makes this file
+ * source-build-safe without the `optionalDependencies` graph
+ * present — the production build path
+ * (`tsc -p tsconfig.build.json` / `npm run build`) compiles even
+ * when none of `@ipld/car`, `@helia/unixfs`, or `blockstore-core`
+ * are installed. Local minimal type aliases below mirror just
+ * the surface we consume. (Dev-mode `tsc --noEmit` against the
+ * full `tsconfig.json` still requires the optional packages
+ * because TEST files import them directly — tests never run on
+ * omit-optional production installs; `tsconfig.build.json`
+ * excludes `__tests__`.) The runtime dynamic-import is the only
+ * resolution call site, so a synapse-only install
+ * (`npm ci --legacy-peer-deps --omit=optional`) never touches
+ * the CAR-first modules.
+ *
+ * Errors are not thrown directly from this file. The driver
+ * client wraps any failure into a typed
+ * `FilecoinProviderError('filecoin_pin_car_*', sanitized)` at the
+ * call site so vendor stack traces never escape the boundary.
+ */
+import { CID } from 'multiformats/cid';
+export interface BuiltCar {
+    /** Serialized CAR bytes — what the upload path hands to Synapse. */
+    readonly carBytes: Buffer;
+    /** IPFS root CID (unixfs dag-pb / raw, CIDv1 base32). */
+    readonly rootCid: CID;
+}
+/**
+ * Build a single-file UnixFS DAG from `body`, then serialise it
+ * as a CAR with the file's root as the sole CAR root. The
+ * returned `rootCid` is the canonical IPFS identity for the
+ * bytes — pass it through to `FilecoinPutResult.ipfsCid` so the
+ * sidecar carries a stable IPFS handle alongside the Filecoin
+ * PieceCID.
+ */
+export declare function buildCarFromBytes(body: Buffer): Promise<BuiltCar>;
+/**
+ * Inverse of `buildCarFromBytes`: parse `carBytes` into an in-
+ * memory blockstore, then walk the UnixFS DAG from `rootCid` to
+ * recover the original file bytes. Returns a `Buffer` matching
+ * what was originally uploaded.
+ *
+ * `rootCid` may be passed as either a `multiformats/cid.CID`
+ * instance or its canonical string form. We accept the string
+ * form so callers that derived the root from `CarReader.getRoots()`
+ * (whose CID type lives in `@ipld/car`'s nested `multiformats`,
+ * not the top-level one) can interoperate without a manual
+ * cross-package cast.
+ */
+export declare function extractFileFromCar(carBytes: Buffer, rootCid: CID | string): Promise<Buffer>;

package/dist/storage/providers/filecoin/filecoin-pin-car.js

@@ -0,0 +1,155 @@
+/**
+ * @file CAR-construction helpers for the filecoin-pin driver.
+ *
+ * The filecoin-pin path differs from the direct Synapse driver in
+ * one place: before handing bytes to the Synapse SDK it wraps them
+ * in a CAR file whose blocks form an IPFS UnixFS DAG. The Filecoin
+ * PieceCID is then computed over the CAR bytes (not the raw user
+ * content), and the IPFS root CID survives as a separate
+ * identifier — which is the value the Phase 4 `ipfs_cid` sidecar
+ * slot was designed to carry.
+ *
+ * Two seams live here:
+ *
+ *   - `buildCarFromBytes(body)` — convert a `Buffer` of raw user
+ *     bytes into a `{ carBytes, rootCid }` pair via Helia +
+ *     `@helia/unixfs`. Used by `FilecoinPinFilecoinProviderClient.put`
+ *     immediately before delegating to filecoin-pin's
+ *     `executeUpload`.
+ *
+ *   - `extractFileFromCar(carBytes, rootCid)` — the inverse:
+ *     parse a CAR by streaming its blocks back into an in-memory
+ *     blockstore, then unixfs-traverse from the root to materialise
+ *     the original bytes. Used by
+ *     `FilecoinPinFilecoinProviderClient.get` to reverse the CAR
+ *     wrapping the upload path applied.
+ *
+ * Vendor isolation. Every CAR / Helia / blockstore import lives
+ * inside the function bodies as a runtime `await import(...)`
+ * against a `const`-stored specifier. That makes this file
+ * source-build-safe without the `optionalDependencies` graph
+ * present — the production build path
+ * (`tsc -p tsconfig.build.json` / `npm run build`) compiles even
+ * when none of `@ipld/car`, `@helia/unixfs`, or `blockstore-core`
+ * are installed. Local minimal type aliases below mirror just
+ * the surface we consume. (Dev-mode `tsc --noEmit` against the
+ * full `tsconfig.json` still requires the optional packages
+ * because TEST files import them directly — tests never run on
+ * omit-optional production installs; `tsconfig.build.json`
+ * excludes `__tests__`.) The runtime dynamic-import is the only
+ * resolution call site, so a synapse-only install
+ * (`npm ci --legacy-peer-deps --omit=optional`) never touches
+ * the CAR-first modules.
+ *
+ * Errors are not thrown directly from this file. The driver
+ * client wraps any failure into a typed
+ * `FilecoinProviderError('filecoin_pin_car_*', sanitized)` at the
+ * call site so vendor stack traces never escape the boundary.
+ */
+import { CID } from 'multiformats/cid';
+// The specifiers below are stored as runtime values rather than
+// inline string literals so `tsc` does NOT statically resolve the
+// optional modules at type-check time. A synapse-only install
+// (`npm ci --legacy-peer-deps --omit=optional`) successfully
+// runs `tsc -p tsconfig.build.json`; the dynamic import only
+// fails at runtime when an operator selects
+// `RAW_STORAGE_FILECOIN_DRIVER=filecoin_pin` without the optional
+// graph installed — which is the intended failure mode.
+const VENDOR_IPLD_CAR = '@ipld/car';
+const VENDOR_HELIA_UNIXFS = '@helia/unixfs';
+const VENDOR_BLOCKSTORE_MEMORY = 'blockstore-core/memory';
+async function loadCarWriter() {
+    const mod = (await import(VENDOR_IPLD_CAR));
+    return mod.CarWriter;
+}
+async function loadCarReader() {
+    const mod = (await import(VENDOR_IPLD_CAR));
+    return mod.CarReader;
+}
+async function loadUnixfs(blockstore) {
+    const mod = (await import(VENDOR_HELIA_UNIXFS));
+    return mod.unixfs({ blockstore });
+}
+async function loadMemoryBlockstore() {
+    const mod = (await import(VENDOR_BLOCKSTORE_MEMORY));
+    return new mod.MemoryBlockstore();
+}
+/**
+ * Flatten the blockstore's per-block byte iterable into a single
+ * `Uint8Array`. `MemoryBlockstore.getAll()` reports `bytes` as
+ * an `AwaitGenerator<Uint8Array>` even though concrete blocks are
+ * usually single-chunk; we collect whichever shape arrives.
+ */
+async function flattenBytes(value) {
+    if (value instanceof Uint8Array)
+        return new Uint8Array(value);
+    const chunks = [];
+    for await (const chunk of value)
+        chunks.push(chunk);
+    if (chunks.length === 1)
+        return new Uint8Array(chunks[0]);
+    return new Uint8Array(Buffer.concat(chunks));
+}
+/**
+ * Build a single-file UnixFS DAG from `body`, then serialise it
+ * as a CAR with the file's root as the sole CAR root. The
+ * returned `rootCid` is the canonical IPFS identity for the
+ * bytes — pass it through to `FilecoinPutResult.ipfsCid` so the
+ * sidecar carries a stable IPFS handle alongside the Filecoin
+ * PieceCID.
+ */
+export async function buildCarFromBytes(body) {
+    const blockstore = await loadMemoryBlockstore();
+    const fs = await loadUnixfs(blockstore);
+    const rootCid = await fs.addBytes(body);
+    const CarWriter = await loadCarWriter();
+    const { writer, out } = CarWriter.create([rootCid]);
+    const collected = [];
+    const collecting = (async () => {
+        for await (const chunk of out)
+            collected.push(chunk);
+    })();
+    try {
+        for await (const pair of blockstore.getAll()) {
+            const bytes = await flattenBytes(pair.bytes);
+            await writer.put({ cid: pair.cid, bytes });
+        }
+    }
+    finally {
+        await writer.close();
+    }
+    await collecting;
+    return { carBytes: Buffer.concat(collected), rootCid };
+}
+/**
+ * Inverse of `buildCarFromBytes`: parse `carBytes` into an in-
+ * memory blockstore, then walk the UnixFS DAG from `rootCid` to
+ * recover the original file bytes. Returns a `Buffer` matching
+ * what was originally uploaded.
+ *
+ * `rootCid` may be passed as either a `multiformats/cid.CID`
+ * instance or its canonical string form. We accept the string
+ * form so callers that derived the root from `CarReader.getRoots()`
+ * (whose CID type lives in `@ipld/car`'s nested `multiformats`,
+ * not the top-level one) can interoperate without a manual
+ * cross-package cast.
+ */
+export async function extractFileFromCar(carBytes, rootCid) {
+    const CarReader = await loadCarReader();
+    const reader = await CarReader.fromBytes(carBytes);
+    const blockstore = await loadMemoryBlockstore();
+    for await (const { cid, bytes } of reader.blocks()) {
+        await blockstore.put(cid, bytes);
+    }
+    // Re-parse the root through the canonical `multiformats/cid`
+    // so the unixfs walker receives an instance with the prototype
+    // methods the helia/unixfs side expects. Avoids a "method does
+    // not exist" runtime failure when callers hand us a CID from
+    // `@ipld/car`'s nested multiformats version.
+    const canonicalRoot = CID.parse(typeof rootCid === 'string' ? rootCid : rootCid.toString());
+    const fs = await loadUnixfs(blockstore);
+    const chunks = [];
+    for await (const chunk of fs.cat(canonicalRoot))
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}