@atomicmemory/core 1.0.0

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

@@ -0,0 +1,87 @@
+/**
+ * @file Vendor-boundary helpers for the filecoin-pin driver.
+ *
+ * Encapsulates the surface that crosses from our code into
+ * `filecoin-pin/core/upload` + `@ipld/car`. The split exists so
+ * `filecoin-pin-client.ts` stays focused on the
+ * `FilecoinProviderClient` implementation while this file owns:
+ *
+ *   - The closed minimal type aliases that mirror just the bits
+ *     of the vendor shapes we consume.
+ *   - The runtime dynamic-import helpers
+ *     (`loadExecuteUpload` / `loadCarReader`).
+ *   - The noop `Logger`-shaped object we hand to
+ *     `executeUpload`'s required `logger` option (so we don't
+ *     pull `pino` into the production type graph).
+ *
+ * Source-build invariant. The production build path
+ * (`tsc -p tsconfig.build.json` / `npm run build`) compiles WITHOUT
+ * the `optionalDependencies` graph present. Two patterns enforce
+ * that here:
+ *
+ *   1. **Local minimal types.** We do NOT `import type { ... }`
+ *      from any optional package. Every shape we consume is
+ *      defined locally so `tsc` never has to resolve the vendor
+ *      type declarations.
+ *
+ *   2. **Non-literal dynamic-import specifiers.** Each
+ *      `await import(...)` call site uses a `VENDOR_*`
+ *      `const`-stored specifier. `tsc` does not statically
+ *      resolve a non-literal `import(specifier)` argument, so a
+ *      synapse-only install
+ *      (`npm ci --legacy-peer-deps --omit=optional`) successfully
+ *      runs `tsc -p tsconfig.build.json` even though the optional
+ *      modules are absent.
+ *
+ * The dev-mode `tsc --noEmit` (against `tsconfig.json`) still
+ * requires the optional packages because TEST files in
+ * `providers/filecoin/__tests__/` import them directly (e.g.
+ * `@ipld/car` for a hand-rolled multi-root CAR fixture). Tests
+ * never run on omit-optional production installs;
+ * `tsconfig.build.json` excludes `__tests__`. See
+ * `filecoin-pin-lazy-boundary.test.ts` for the static-import
+ * invariant that pins this split.
+ */
+// Specifiers stored as `const`s so `tsc` does not statically
+// resolve the optional modules. See file header for the
+// source-build-safety rationale.
+const VENDOR_FILECOIN_PIN_UPLOAD = 'filecoin-pin/core/upload';
+const VENDOR_IPLD_CAR = '@ipld/car';
+/**
+ * Lazy-load `executeUpload` from `filecoin-pin/core/upload`. The
+ * package is in `optionalDependencies`; if a synapse-only build
+ * was installed via `npm ci --legacy-peer-deps --omit=optional`,
+ * this resolution fails only when an operator selects
+ * `RAW_STORAGE_FILECOIN_DRIVER=filecoin_pin` — the intended
+ * failure mode.
+ */
+export async function loadExecuteUpload() {
+    const mod = (await import(VENDOR_FILECOIN_PIN_UPLOAD));
+    return mod.executeUpload;
+}
+/** Lazy-load `CarReader.fromBytes` from `@ipld/car`. */
+export async function loadCarReader(carBytes) {
+    const mod = (await import(VENDOR_IPLD_CAR));
+    return mod.CarReader.fromBytes(carBytes);
+}
+/**
+ * Pino-shape silent logger used to satisfy `executeUpload`'s
+ * required `logger` option without taking on `pino` as a runtime
+ * dep. The `MinimalUploadOptions.logger` field is `unknown` by
+ * design so we don't drag pino into the production type graph;
+ * the shape below mirrors the closed set of methods filecoin-pin's
+ * `executeUpload` actually invokes. If a future filecoin-pin
+ * upgrade widens that surface, the runtime call site fails with
+ * a clear vendor-side error rather than producing silent test
+ * passes against a stale shape.
+ */
+export function noopLogger() {
+    const noop = () => undefined;
+    const logger = {
+        level: 'silent',
+        fatal: noop, error: noop, warn: noop, info: noop, debug: noop, trace: noop,
+        silent: noop,
+        child: () => logger,
+    };
+    return logger;
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @file Strict readers for the `filecoin.*` hints adapters MAY
+ * consult to short-circuit lookups (`head`) and bypass the SDK's
+ * CID→active-piece resolution (`delete`).
+ *
+ * Source: `raw_storage_metadata.filecoin` sidecar that
+ * `FilecoinRawContentStore.put` wrote (`backend.ts`). The
+ * reconciler / cleanup loop read `raw_documents.raw_storage_metadata`
+ * straight out of the DB and pass it as the generic
+ * `RawContentHints` argument; this module is the only place that
+ * interprets it.
+ *
+ * Validation contract: every numeric id field MUST be a non-empty
+ * positive decimal `bigint` string (regex `^[1-9][0-9]*$`).
+ * Anything else — `0`, negative, hex/`0x...`, floats, scientific
+ * notation, surrounding whitespace, non-string types, missing
+ * keys, the `filecoin` sibling not being an object — is treated
+ * as **absent**. Malformed values NEVER throw; the helper returns
+ * `null` and emits a sanitized `filecoin.hint.malformed`
+ * diagnostic so an operator can see in observability that a hint
+ * was rejected without the malformed value itself crossing the
+ * boundary.
+ */
+import type { RawContentHints } from '../../raw-content-store.js';
+/**
+ * Bundled hints `delete` consumes. `dataSetId` locates the
+ * `StorageContext`; `pieceId` bypasses the CID-based active-piece
+ * lookup that fails for freshly-uploaded pieces (the live
+ * calibration smoke surfaced this failure mode). Either field
+ * may be `null` independently — the adapter MUST tolerate partial
+ * hints (data_set_id present + piece_id missing falls back to
+ * CID-based delete on the resolved context; both missing falls
+ * back to the scan path).
+ */
+export interface FilecoinDeleteHints {
+    readonly dataSetId: string | null;
+    readonly pieceId: string | null;
+}
+/**
+ * Returns the validated `data_set_id` string, or `null` when the
+ * hint is missing or malformed. Callers pass the result straight
+ * through to `FilecoinProviderClient.head({ dataSetId })`; `null`
+ * means "no hint, scan normally".
+ *
+ * `documentIdForDiagnostic` is optional — when supplied (e.g. by
+ * the reconciler) it appears on the `filecoin.hint.malformed`
+ * event so an operator can correlate the diagnostic with the
+ * specific row. The value itself NEVER appears in the event.
+ */
+export declare function readFilecoinDataSetIdHint(hints: RawContentHints | undefined, documentIdForDiagnostic?: string): string | null;
+/**
+ * Returns `{ dataSetId, pieceId }` from the sidecar — the bundle
+ * `FilecoinRawContentStore.delete` consumes. `pieceId` is picked
+ * from `filecoin.copies[]`:
+ *
+ *   1. Top-level `data_set_id` is validated first (positive
+ *      decimal bigint or `null`).
+ *   2. Each copy is read; only copies whose `data_set_id` is a
+ *      valid positive decimal bigint AND whose `piece_id` is a
+ *      valid positive decimal bigint are eligible.
+ *   3. If the top-level `data_set_id` resolved (non-null), we
+ *      prefer the first eligible copy whose `data_set_id`
+ *      matches it. Otherwise the first eligible copy wins.
+ *
+ * Returns `{ dataSetId, pieceId }` where each field is the
+ * validated string or `null`. Never throws. Malformed entries
+ * emit one `filecoin.hint.malformed` diagnostic per offending
+ * field (per copy) so the rejection is visible without leaking
+ * the rejected value.
+ */
+export declare function readFilecoinDeleteHints(hints: RawContentHints | undefined, documentIdForDiagnostic?: string): FilecoinDeleteHints;

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

@@ -0,0 +1,123 @@
+/**
+ * @file Strict readers for the `filecoin.*` hints adapters MAY
+ * consult to short-circuit lookups (`head`) and bypass the SDK's
+ * CID→active-piece resolution (`delete`).
+ *
+ * Source: `raw_storage_metadata.filecoin` sidecar that
+ * `FilecoinRawContentStore.put` wrote (`backend.ts`). The
+ * reconciler / cleanup loop read `raw_documents.raw_storage_metadata`
+ * straight out of the DB and pass it as the generic
+ * `RawContentHints` argument; this module is the only place that
+ * interprets it.
+ *
+ * Validation contract: every numeric id field MUST be a non-empty
+ * positive decimal `bigint` string (regex `^[1-9][0-9]*$`).
+ * Anything else — `0`, negative, hex/`0x...`, floats, scientific
+ * notation, surrounding whitespace, non-string types, missing
+ * keys, the `filecoin` sibling not being an object — is treated
+ * as **absent**. Malformed values NEVER throw; the helper returns
+ * `null` and emits a sanitized `filecoin.hint.malformed`
+ * diagnostic so an operator can see in observability that a hint
+ * was rejected without the malformed value itself crossing the
+ * boundary.
+ */
+import { emitFilecoinEvent } from '../../../services/filecoin-observability.js';
+const POSITIVE_DECIMAL_BIGINT = /^[1-9][0-9]*$/;
+/**
+ * Returns the validated `data_set_id` string, or `null` when the
+ * hint is missing or malformed. Callers pass the result straight
+ * through to `FilecoinProviderClient.head({ dataSetId })`; `null`
+ * means "no hint, scan normally".
+ *
+ * `documentIdForDiagnostic` is optional — when supplied (e.g. by
+ * the reconciler) it appears on the `filecoin.hint.malformed`
+ * event so an operator can correlate the diagnostic with the
+ * specific row. The value itself NEVER appears in the event.
+ */
+export function readFilecoinDataSetIdHint(hints, documentIdForDiagnostic) {
+    const sibling = readFilecoinSibling(hints);
+    if (sibling === null)
+        return null;
+    return readPositiveBigintString(sibling['data_set_id'], 'data_set_id', documentIdForDiagnostic);
+}
+/**
+ * Returns `{ dataSetId, pieceId }` from the sidecar — the bundle
+ * `FilecoinRawContentStore.delete` consumes. `pieceId` is picked
+ * from `filecoin.copies[]`:
+ *
+ *   1. Top-level `data_set_id` is validated first (positive
+ *      decimal bigint or `null`).
+ *   2. Each copy is read; only copies whose `data_set_id` is a
+ *      valid positive decimal bigint AND whose `piece_id` is a
+ *      valid positive decimal bigint are eligible.
+ *   3. If the top-level `data_set_id` resolved (non-null), we
+ *      prefer the first eligible copy whose `data_set_id`
+ *      matches it. Otherwise the first eligible copy wins.
+ *
+ * Returns `{ dataSetId, pieceId }` where each field is the
+ * validated string or `null`. Never throws. Malformed entries
+ * emit one `filecoin.hint.malformed` diagnostic per offending
+ * field (per copy) so the rejection is visible without leaking
+ * the rejected value.
+ */
+export function readFilecoinDeleteHints(hints, documentIdForDiagnostic) {
+    const sibling = readFilecoinSibling(hints);
+    if (sibling === null)
+        return { dataSetId: null, pieceId: null };
+    const dataSetId = readPositiveBigintString(sibling['data_set_id'], 'data_set_id', documentIdForDiagnostic);
+    const pieceId = pickPieceIdFromCopies(sibling['copies'], dataSetId, documentIdForDiagnostic);
+    return { dataSetId, pieceId };
+}
+function readFilecoinSibling(hints) {
+    if (!hints || typeof hints !== 'object')
+        return null;
+    const sibling = hints['filecoin'];
+    if (!sibling || typeof sibling !== 'object' || Array.isArray(sibling))
+        return null;
+    return sibling;
+}
+function readPositiveBigintString(raw, fieldName, documentIdForDiagnostic) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw !== 'string') {
+        emitMalformed(`${fieldName}_not_a_string`, documentIdForDiagnostic);
+        return null;
+    }
+    if (!POSITIVE_DECIMAL_BIGINT.test(raw)) {
+        emitMalformed(`${fieldName}_not_positive_decimal_bigint`, documentIdForDiagnostic);
+        return null;
+    }
+    return raw;
+}
+function pickPieceIdFromCopies(raw, preferredDataSetId, documentIdForDiagnostic) {
+    if (!Array.isArray(raw))
+        return null;
+    let fallback = null;
+    for (const entry of raw) {
+        const pair = readCopyPair(entry, documentIdForDiagnostic);
+        if (pair === null)
+            continue;
+        if (preferredDataSetId !== null && pair.dataSetId === preferredDataSetId)
+            return pair.pieceId;
+        if (fallback === null)
+            fallback = pair.pieceId;
+    }
+    return fallback;
+}
+function readCopyPair(entry, documentIdForDiagnostic) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry))
+        return null;
+    const copy = entry;
+    const dataSetId = readPositiveBigintString(copy['data_set_id'], 'data_set_id', documentIdForDiagnostic);
+    const pieceId = readPositiveBigintString(copy['piece_id'], 'piece_id', documentIdForDiagnostic);
+    if (dataSetId === null || pieceId === null)
+        return null;
+    return { dataSetId, pieceId };
+}
+function emitMalformed(errorCode, documentIdForDiagnostic) {
+    emitFilecoinEvent('filecoin.hint.malformed', {
+        provider: 'filecoin',
+        errorCode,
+        ...(documentIdForDiagnostic ? { documentId: documentIdForDiagnostic } : {}),
+    });
+}

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

@@ -0,0 +1,51 @@
+/**
+ * @file Filecoin storage provider — composition entry point.
+ *
+ * `createFilecoinStorageBackend(config)` is the single entry point
+ * that `src/storage/factory.ts` calls when
+ * `rawStorageProvider === 'filecoin'`. The provider REQUIRES a
+ * non-null parsed `FilecoinProviderConfig` — the null-config
+ * runtime path is not supported now that
+ * `head`/`get`/`delete` advertise real capabilities. The central
+ * `parseFilecoinProviderConfig` in `src/config.ts` already enforces
+ * "filecoin selected ⇒ full env block validated", so production
+ * never reaches this entry with a null config.
+ *
+ * The test client stays isolated in `./skeleton-client.ts` for
+ * tests that need a `FilecoinProviderClient`-shaped stub without standing up a real
+ * Synapse handle.
+ *
+ * Reverse import-boundary invariant (enforced by the
+ * `import-boundary.test.ts`): this module's only outward imports
+ * are sibling files inside `providers/filecoin/`, the adapter
+ * contract from `src/storage/raw-content-store.js`, and (inside
+ * `synapse-construction.ts`) the vendor packages
+ * `@filoz/synapse-sdk` + `viem`. No `RuntimeConfig`, no
+ * `process.env`, no route/db/service code.
+ */
+import type { FilecoinProviderConfig } from './config.js';
+import type { RawContentStore } from '../../raw-content-store.js';
+/**
+ * Build the Filecoin backend from a validated
+ * `FilecoinProviderConfig`. Throws `FilecoinProviderError` when
+ * the caller passes a non-config — the only path that can happen
+ * in production is a misconfiguration the central config
+ * validator should have caught, so the throw is a defense-in-
+ * depth signal rather than an expected branch.
+ *
+ * **Lazy-load contract.** Synchronous construction of the default
+ * `synapse` client is fine — its imports (`@filoz/synapse-sdk`,
+ * `viem`) are already in this module's static graph. The
+ * `filecoin_pin` client, however, pulls a much heavier graph
+ * (`filecoin-pin/core/upload`, `@helia/unixfs`, `@ipld/car`,
+ * `blockstore-core`), so we `await import` it ONLY inside the
+ * `filecoin_pin` branch. A deployment running the default
+ * `RAW_STORAGE_FILECOIN_DRIVER=synapse` never resolves the
+ * filecoin-pin module subtree at runtime, which keeps the
+ * `filecoin-pin` package's `optionalDependencies` status honest
+ * (a synapse-only deployment can be built without the package
+ * installed at all). The function returns `Promise<RawContentStore>`
+ * so the dynamic-import branch can await its loader.
+ */
+export declare function createFilecoinStorageBackend(config: FilecoinProviderConfig): Promise<RawContentStore>;
+export { FilecoinRawContentStore } from './backend.js';

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

@@ -0,0 +1,103 @@
+/**
+ * @file Filecoin storage provider — composition entry point.
+ *
+ * `createFilecoinStorageBackend(config)` is the single entry point
+ * that `src/storage/factory.ts` calls when
+ * `rawStorageProvider === 'filecoin'`. The provider REQUIRES a
+ * non-null parsed `FilecoinProviderConfig` — the null-config
+ * runtime path is not supported now that
+ * `head`/`get`/`delete` advertise real capabilities. The central
+ * `parseFilecoinProviderConfig` in `src/config.ts` already enforces
+ * "filecoin selected ⇒ full env block validated", so production
+ * never reaches this entry with a null config.
+ *
+ * The test client stays isolated in `./skeleton-client.ts` for
+ * tests that need a `FilecoinProviderClient`-shaped stub without standing up a real
+ * Synapse handle.
+ *
+ * Reverse import-boundary invariant (enforced by the
+ * `import-boundary.test.ts`): this module's only outward imports
+ * are sibling files inside `providers/filecoin/`, the adapter
+ * contract from `src/storage/raw-content-store.js`, and (inside
+ * `synapse-construction.ts`) the vendor packages
+ * `@filoz/synapse-sdk` + `viem`. No `RuntimeConfig`, no
+ * `process.env`, no route/db/service code.
+ */
+import { FilecoinRawContentStore } from './backend.js';
+import { SynapseFilecoinProviderClient } from './synapse-client.js';
+import { FilecoinProviderError } from './errors.js';
+import { buildSynapse } from './synapse-construction.js';
+/**
+ * Build the Filecoin backend from a validated
+ * `FilecoinProviderConfig`. Throws `FilecoinProviderError` when
+ * the caller passes a non-config — the only path that can happen
+ * in production is a misconfiguration the central config
+ * validator should have caught, so the throw is a defense-in-
+ * depth signal rather than an expected branch.
+ *
+ * **Lazy-load contract.** Synchronous construction of the default
+ * `synapse` client is fine — its imports (`@filoz/synapse-sdk`,
+ * `viem`) are already in this module's static graph. The
+ * `filecoin_pin` client, however, pulls a much heavier graph
+ * (`filecoin-pin/core/upload`, `@helia/unixfs`, `@ipld/car`,
+ * `blockstore-core`), so we `await import` it ONLY inside the
+ * `filecoin_pin` branch. A deployment running the default
+ * `RAW_STORAGE_FILECOIN_DRIVER=synapse` never resolves the
+ * filecoin-pin module subtree at runtime, which keeps the
+ * `filecoin-pin` package's `optionalDependencies` status honest
+ * (a synapse-only deployment can be built without the package
+ * installed at all). The function returns `Promise<RawContentStore>`
+ * so the dynamic-import branch can await its loader.
+ */
+export async function createFilecoinStorageBackend(config) {
+    if (config === null || config === undefined) {
+        throw new FilecoinProviderError('filecoin_provider_not_configured', 'createFilecoinStorageBackend was called without a FilecoinProviderConfig. ' +
+            'Set the RAW_STORAGE_FILECOIN_* env block before selecting filecoin.');
+    }
+    const synapse = buildSynapse(config);
+    const synapseClient = new SynapseFilecoinProviderClient(synapse, {
+        copies: config.copies,
+        providerIds: config.providerIds,
+        dataSetMetadata: filecoinDataSetMetadataToStrings(config.dataSetMetadata),
+        withCdn: config.withCdn,
+        uploadTimeoutMs: config.uploadTimeoutMs,
+        retrievalTimeoutMs: config.retrievalTimeoutMs,
+        minUploadBytes: config.minUploadBytes,
+        maxUploadBytes: config.maxUploadBytes,
+    });
+    let client = synapseClient;
+    if (config.driver === 'filecoin_pin') {
+        // Dynamic import keeps the filecoin-pin module subtree out
+        // of the synapse-only startup graph. The boundary test
+        // (`__tests__/lazy-loading-boundary.test.ts`) asserts this
+        // invariant statically by AST-scanning `index.ts`.
+        const { FilecoinPinFilecoinProviderClient } = await import('./filecoin-pin-client.js');
+        client = new FilecoinPinFilecoinProviderClient(synapse, synapseClient, {
+            ...(config.copies !== null ? { copies: config.copies } : {}),
+            providerIds: config.providerIds,
+            dataSetMetadata: filecoinDataSetMetadataToStrings(config.dataSetMetadata),
+            ...(config.uploadTimeoutMs !== null ? { uploadTimeoutMs: config.uploadTimeoutMs } : {}),
+            ...(config.retrievalTimeoutMs !== null ? { retrievalTimeoutMs: config.retrievalTimeoutMs } : {}),
+            minUploadBytes: config.minUploadBytes,
+            maxUploadBytes: config.maxUploadBytes,
+        });
+    }
+    return new FilecoinRawContentStore(client);
+}
+export { FilecoinRawContentStore } from './backend.js';
+// Public read-side projection lives in `src/storage/filecoin-public-metadata.ts`
+// so route + service consumers don't import providers/filecoin/* directly.
+// The provider directory keeps the internal upload allowlist only.
+/**
+ * Synapse `metadata` accepts `Record<string, string>` only. Convert
+ * any number/boolean values from the parsed `dataSetMetadata` to
+ * their canonical string form so the SDK boundary stays
+ * type-aligned with no silent truncation.
+ */
+function filecoinDataSetMetadataToStrings(metadata) {
+    const out = {};
+    for (const [k, v] of Object.entries(metadata)) {
+        out[k] = typeof v === 'string' ? v : String(v);
+    }
+    return out;
+}

package/dist/storage/providers/filecoin/ipfs-cid.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file IPFS / CAR-root CID parser for the provider boundary.
+ *
+ * Phase 4 introduces an optional `ipfs_cid` slot on the
+ * Filecoin sidecar: a future driver (filecoin-pin) will emit
+ * the IPFS / CAR-root identity alongside the canonical PieceCID
+ * so consumers that resolve content via IPFS gateways can do so
+ * without re-deriving the CID from bytes. Today the live Synapse
+ * driver leaves the slot undefined; this parser exists to gate
+ * the slot whenever a future driver populates it.
+ *
+ * The parser uses `multiformats/cid`, which is already inside
+ * the lazy provider-load graph (it's a transitive dependency of
+ * `@filoz/synapse-core/piece`). Importing it here therefore does
+ * NOT change the eager-import surface — non-Filecoin-provider
+ * startups still avoid the Filecoin SDK entirely.
+ *
+ * Codec policy: we accept any CIDv1 (`code` is any IPLD codec,
+ * `version === 1`). CIDv0 (`Qm…` base58btc) is rejected — the
+ * sidecar slot is a forward-looking field and we do not need to
+ * accept the legacy 1.0 shape. The canonical multibase form is
+ * `base32-lower` (`b…`); non-canonical encodings (e.g. base58btc
+ * `z…`) parse but are returned in their canonical form so the
+ * persisted sidecar value is deterministic regardless of how the
+ * driver originally serialized it.
+ *
+ * Sister module — `./piece-cid.ts` performs the same role for
+ * PieceCIDv2 via the Synapse SDK's `asPieceCID`. The two parsers
+ * are kept separate because the PieceCID parser ALSO enforces
+ * codec semantics (raw codec 0x55 + multihash 0x1011), which
+ * the IPFS CID slot intentionally does NOT — an IPFS CID may
+ * be dag-pb, raw, dag-cbor, etc.
+ */
+/**
+ * Returns the canonical CIDv1 string form of `value`, or throws
+ * `FilecoinProviderError('invalid_ipfs_cid', ...)` with a
+ * sanitized message when the value is not a string, is not a
+ * parsable CID, or is a CIDv0 (`Qm…`). Promoting a CIDv1 from a
+ * non-canonical multibase encoding to its canonical base32-lower
+ * `b…` form is done here so callers always get the deterministic
+ * persisted shape.
+ *
+ * `context` is a short noun-phrase that names the seam the
+ * caller is guarding (e.g. `"upload result ipfsCid"`). The
+ * rejected value itself is NEVER echoed into the error message —
+ * malformed CIDs may encode adversarial bytes worth keeping out
+ * of log streams. The closed-set `errorCode` is the diagnostic
+ * surface.
+ */
+export declare function requireIpfsCid(value: unknown, context: string): string;

package/dist/storage/providers/filecoin/ipfs-cid.js

@@ -0,0 +1,64 @@
+/**
+ * @file IPFS / CAR-root CID parser for the provider boundary.
+ *
+ * Phase 4 introduces an optional `ipfs_cid` slot on the
+ * Filecoin sidecar: a future driver (filecoin-pin) will emit
+ * the IPFS / CAR-root identity alongside the canonical PieceCID
+ * so consumers that resolve content via IPFS gateways can do so
+ * without re-deriving the CID from bytes. Today the live Synapse
+ * driver leaves the slot undefined; this parser exists to gate
+ * the slot whenever a future driver populates it.
+ *
+ * The parser uses `multiformats/cid`, which is already inside
+ * the lazy provider-load graph (it's a transitive dependency of
+ * `@filoz/synapse-core/piece`). Importing it here therefore does
+ * NOT change the eager-import surface — non-Filecoin-provider
+ * startups still avoid the Filecoin SDK entirely.
+ *
+ * Codec policy: we accept any CIDv1 (`code` is any IPLD codec,
+ * `version === 1`). CIDv0 (`Qm…` base58btc) is rejected — the
+ * sidecar slot is a forward-looking field and we do not need to
+ * accept the legacy 1.0 shape. The canonical multibase form is
+ * `base32-lower` (`b…`); non-canonical encodings (e.g. base58btc
+ * `z…`) parse but are returned in their canonical form so the
+ * persisted sidecar value is deterministic regardless of how the
+ * driver originally serialized it.
+ *
+ * Sister module — `./piece-cid.ts` performs the same role for
+ * PieceCIDv2 via the Synapse SDK's `asPieceCID`. The two parsers
+ * are kept separate because the PieceCID parser ALSO enforces
+ * codec semantics (raw codec 0x55 + multihash 0x1011), which
+ * the IPFS CID slot intentionally does NOT — an IPFS CID may
+ * be dag-pb, raw, dag-cbor, etc.
+ */
+import { CID } from 'multiformats/cid';
+import { FilecoinProviderError } from './errors.js';
+/**
+ * Returns the canonical CIDv1 string form of `value`, or throws
+ * `FilecoinProviderError('invalid_ipfs_cid', ...)` with a
+ * sanitized message when the value is not a string, is not a
+ * parsable CID, or is a CIDv0 (`Qm…`). Promoting a CIDv1 from a
+ * non-canonical multibase encoding to its canonical base32-lower
+ * `b…` form is done here so callers always get the deterministic
+ * persisted shape.
+ *
+ * `context` is a short noun-phrase that names the seam the
+ * caller is guarding (e.g. `"upload result ipfsCid"`). The
+ * rejected value itself is NEVER echoed into the error message —
+ * malformed CIDs may encode adversarial bytes worth keeping out
+ * of log streams. The closed-set `errorCode` is the diagnostic
+ * surface.
+ */
+export function requireIpfsCid(value, context) {
+    if (typeof value === 'string' && value.length > 0) {
+        try {
+            const parsed = CID.parse(value);
+            if (parsed.version === 1)
+                return parsed.toString();
+        }
+        catch {
+            // Fall through to the sanitized throw below.
+        }
+    }
+    throw new FilecoinProviderError('invalid_ipfs_cid', `Filecoin ${context} carries a value that is not a valid CIDv1.`);
+}

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

@@ -0,0 +1,72 @@
+/**
+ * @file Filecoin provider-internal metadata allowlist + denylist.
+ *
+ * The public projector lives in
+ * `src/storage/filecoin-public-metadata.ts` so routes / services
+ * don't have to import `providers/filecoin/*` directly. What
+ * remains here is provider-internal:
+ *
+ *   - `buildFilecoinMetadata(input)` produces the closed-shape
+ *     Synapse piece-metadata envelope upload calls may pass through.
+ *     Synapse's `METADATA_LIMITS.MAX_KEYS_PER_PIECE`
+ *     is 5 (per docs.filecoin.cloud/reference/filoz/synapse-core/
+ *     utils/variables/metadata_limits/); this builder enforces the
+ *     cap so an over-allowed envelope cannot reach Synapse and
+ *     fail mid-upload. Key length is also capped at the documented
+ *     32 chars and string values at 128 chars.
+ *   - The allowlist, denylist, and reserved-prefix constants the
+ *     upload + central config validators share (config.ts's
+ *     DATA_SET_METADATA validation reads from the same constants
+ *     and applies the dataset-side limits 10 / 32 / 128).
+ *
+ * Upload-side safety rule: this module NEVER lets private keys,
+ * wallet addresses, payment-rail state, signed requests, auth
+ * headers, UCAN proofs, raw Synapse responses, or any other key on
+ * the denylist reach the provider. Reserved prefixes
+ * (`atomicmemory.`, `synapse.`, `filecoin.`, `_`) are rejected as
+ * caller-supplied keys.
+ *
+ * Read-side projection — what survives onto the public wire when
+ * reading `raw_documents.raw_storage_metadata.filecoin` back — is
+ * the shared module's job (`projectFilecoinPublicMetadata`). The
+ * internal `copies: [{ provider_id, status }]` shape flattens to
+ * scalar `copy_count` / `provider_ids` / `copy_statuses` over
+ * there.
+ */
+export declare const ALLOWED_FILECOIN_METADATA_KEYS: readonly ["artifact_id", "storage_profile_id", "content_type", "stored_hash", "codec_name", "codec_version", "codec_key_id", "source_kind"];
+export type AllowedFilecoinMetadataKey = (typeof ALLOWED_FILECOIN_METADATA_KEYS)[number];
+/**
+ * Closed denylist — keys / shapes `buildFilecoinMetadata` MUST
+ * reject if a caller (or a stray test fixture) tries to push them
+ * onto a Filecoin upload. The list pins items that, if leaked
+ * through `provider_metadata` or `data_set_metadata`, would expose
+ * secrets or sensitive operational state.
+ */
+export declare const FILECOIN_METADATA_DENYLIST: readonly ["private_key", "wallet_address", "payment_rail", "rail_id", "signed_request", "authorization", "auth_header", "ucan_proof", "synapse_response", "raw_synapse_payload"];
+export declare const FILECOIN_METADATA_RESERVED_PREFIXES: readonly ["atomicmemory.", "synapse.", "filecoin.", "_"];
+/**
+ * Scalar leaf-type set accepted by `buildFilecoinMetadata`.
+ * Matches the existing `ArtifactMetadata` write-side contract
+ * (string | finite number | boolean).
+ */
+export type FilecoinMetadataLeaf = string | number | boolean;
+/**
+ * Input to `buildFilecoinMetadata`: any caller-supplied bag of
+ * metadata. Keys are normalized to the allowlist before any I/O;
+ * non-leaf values (arrays, objects, null, undefined) cause the
+ * call to throw so callers cannot quietly leak shape.
+ */
+export type FilecoinMetadataInput = Record<string, unknown>;
+/** Projected closed-shape envelope ready to ship to the provider. */
+export type FilecoinMetadataEnvelope = Readonly<Partial<Record<AllowedFilecoinMetadataKey, FilecoinMetadataLeaf>>>;
+/**
+ * Project caller-supplied metadata down to the allowlisted closed
+ * envelope, enforcing Synapse's per-piece limits (≤5 entries, ≤32
+ * char keys, ≤128 char string values). Throws on denylisted keys,
+ * reserved-prefix keys, non-scalar values, over-long strings, or
+ * an output that would exceed the 5-key cap. Unknown (non-
+ * allowlisted, non-denylisted) keys are silently dropped — fail-
+ * open on inputs we don't understand would surface secrets on a
+ * future contributor's keystroke.
+ */
+export declare function buildFilecoinMetadata(input: FilecoinMetadataInput): FilecoinMetadataEnvelope;