@atomicmemory/core 1.0.0

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

@@ -0,0 +1,82 @@
+/**
+ * @file Provider-local retriever interface — the seam between
+ * the Filecoin provider client and an alternative retrieval
+ * backend (e.g. `@helia/verified-fetch`).
+ *
+ * Phase 6 of the harvest plan adds verified-fetch as an
+ * experimental retriever, sitting BEHIND the Filecoin provider
+ * boundary rather than the generic storage interface. Doing so
+ * lets us evaluate retrieval semantics without exposing a
+ * Filecoin-specific public API or letting `provider_details`
+ * JSONB drive arbitrary URL fetches.
+ *
+ * Security contract — every implementer MUST uphold:
+ *
+ *   1. **CID, not URL.** `get`'s input is a parsed `CID`
+ *      (`multiformats/cid`), never a string URL. The
+ *      implementation constructs the canonical
+ *      `ipfs://<canonicalCidString>` form internally. Callers
+ *      cannot pass an arbitrary URL — the type system rejects
+ *      it.
+ *
+ *   2. **CID source provenance.** The `CID` argument MUST come
+ *      from one of: the upload pipeline's just-computed root,
+ *      a validated provider-client result, or a value that has
+ *      already been validated via the SDK parser. Values read
+ *      directly from `raw_storage_metadata` / `provider_details`
+ *      JSONB are NEVER acceptable input — the parse-and-validate
+ *      step must happen at the provider boundary first.
+ *
+ *   3. **Bounded lifecycle.** The retrieval respects
+ *      `options.timeoutMs` via an `AbortSignal`. The
+ *      implementation MUST clean up the underlying fetch handle
+ *      (`stop()` / similar) on every code path — success,
+ *      timeout, error — and MUST NOT leak network/event-loop
+ *      resources.
+ *
+ *   4. **Sanitized errors.** Failures throw
+ *      `FilecoinProviderError` with a closed `errorCode` literal.
+ *      Raw vendor messages, stack traces, gateway URLs, peer
+ *      IDs, multiaddrs, and IP addresses NEVER cross the
+ *      boundary — only the documented stable codes:
+ *        - `verified_fetch_failed` — generic vendor / retrieval
+ *          failure (status ≥ 400 except 404; vendor throw).
+ *        - `verified_fetch_timeout` — bounded lifecycle fired
+ *          before completion.
+ *        - `verified_fetch_not_found` — content not located on
+ *          the IPFS network (HTTP 404).
+ *        - `verified_fetch_unsupported` — the optional vendor
+ *          package (or a transitive dep) is not installed; the
+ *          retriever is unavailable in this build.
+ *        - `verified_fetch_invalid_cid` — the supplied argument
+ *          did not parse as a CID via `CID.parse`. Surfaced when
+ *          a caller bypasses the TS signature.
+ *        - `verified_fetch_body_too_large` — response body
+ *          exceeded the configured `maxBodyBytes` ceiling.
+ *
+ *   5. **No credentials / private-IP exposure.** No private keys,
+ *      wallet addresses, payment-rail details, or
+ *      local/loopback addresses leak. The implementation MUST
+ *      disable any vendor option that would connect over
+ *      private/loopback networks by default.
+ */
+import type { CID } from 'multiformats/cid';
+export interface RetrieverGetOptions {
+    /** Per-call timeout in ms; the retriever wires this to an `AbortSignal`. */
+    readonly timeoutMs?: number;
+}
+export interface RetrieverGetResult {
+    /** Plaintext bytes addressed by the supplied CID. */
+    readonly body: Buffer;
+    /** Canonical multibase string form of the retrieved CID. */
+    readonly ipfsCid: string;
+}
+export interface FilecoinRetriever {
+    /**
+     * Retrieve the bytes addressed by `ipfsCid`. The CID MUST
+     * come from a validated provider-client result or the
+     * same-upload computed root — see the file header's security
+     * contract.
+     */
+    get(ipfsCid: CID, options?: RetrieverGetOptions): Promise<RetrieverGetResult>;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * @file Provider-local retriever interface — the seam between
+ * the Filecoin provider client and an alternative retrieval
+ * backend (e.g. `@helia/verified-fetch`).
+ *
+ * Phase 6 of the harvest plan adds verified-fetch as an
+ * experimental retriever, sitting BEHIND the Filecoin provider
+ * boundary rather than the generic storage interface. Doing so
+ * lets us evaluate retrieval semantics without exposing a
+ * Filecoin-specific public API or letting `provider_details`
+ * JSONB drive arbitrary URL fetches.
+ *
+ * Security contract — every implementer MUST uphold:
+ *
+ *   1. **CID, not URL.** `get`'s input is a parsed `CID`
+ *      (`multiformats/cid`), never a string URL. The
+ *      implementation constructs the canonical
+ *      `ipfs://<canonicalCidString>` form internally. Callers
+ *      cannot pass an arbitrary URL — the type system rejects
+ *      it.
+ *
+ *   2. **CID source provenance.** The `CID` argument MUST come
+ *      from one of: the upload pipeline's just-computed root,
+ *      a validated provider-client result, or a value that has
+ *      already been validated via the SDK parser. Values read
+ *      directly from `raw_storage_metadata` / `provider_details`
+ *      JSONB are NEVER acceptable input — the parse-and-validate
+ *      step must happen at the provider boundary first.
+ *
+ *   3. **Bounded lifecycle.** The retrieval respects
+ *      `options.timeoutMs` via an `AbortSignal`. The
+ *      implementation MUST clean up the underlying fetch handle
+ *      (`stop()` / similar) on every code path — success,
+ *      timeout, error — and MUST NOT leak network/event-loop
+ *      resources.
+ *
+ *   4. **Sanitized errors.** Failures throw
+ *      `FilecoinProviderError` with a closed `errorCode` literal.
+ *      Raw vendor messages, stack traces, gateway URLs, peer
+ *      IDs, multiaddrs, and IP addresses NEVER cross the
+ *      boundary — only the documented stable codes:
+ *        - `verified_fetch_failed` — generic vendor / retrieval
+ *          failure (status ≥ 400 except 404; vendor throw).
+ *        - `verified_fetch_timeout` — bounded lifecycle fired
+ *          before completion.
+ *        - `verified_fetch_not_found` — content not located on
+ *          the IPFS network (HTTP 404).
+ *        - `verified_fetch_unsupported` — the optional vendor
+ *          package (or a transitive dep) is not installed; the
+ *          retriever is unavailable in this build.
+ *        - `verified_fetch_invalid_cid` — the supplied argument
+ *          did not parse as a CID via `CID.parse`. Surfaced when
+ *          a caller bypasses the TS signature.
+ *        - `verified_fetch_body_too_large` — response body
+ *          exceeded the configured `maxBodyBytes` ceiling.
+ *
+ *   5. **No credentials / private-IP exposure.** No private keys,
+ *      wallet addresses, payment-rail details, or
+ *      local/loopback addresses leak. The implementation MUST
+ *      disable any vendor option that would connect over
+ *      private/loopback networks by default.
+ */
+export {};

package/dist/storage/providers/filecoin/skeleton-client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @file Test-only `FilecoinProviderClient` whose every
+ * operation throws `FilecoinNotImplementedError` and whose
+ * `checkReadiness` reports every required check as
+ * `'unknown' / 'not_implemented'`.
+ *
+ * Used by tests that need to construct a `FilecoinRawContentStore`
+ * without standing up a real Synapse instance. The test
+ * "bare selection" runtime path (`createFilecoinStorageBackend(null)`)
+ * has been removed — `src/storage/factory.ts` now throws when
+ * `rawStorageProvider='filecoin'` and `filecoinProvider` is null,
+ * so this class never reaches the production composition root.
+ *
+ * The real Synapse-backed implementation lives in
+ * `synapse-client.ts` and is constructed via
+ * `synapse-construction.ts` from a parsed `FilecoinProviderConfig`.
+ */
+import type { FilecoinDeleteInput, FilecoinDeleteResult, FilecoinGetInput, FilecoinGetResult, FilecoinHeadInput, FilecoinHeadResult, FilecoinProviderClient, FilecoinPutInput, FilecoinPutResult, FilecoinReadinessCheck, FilecoinReadinessNetwork, FilecoinVerifyInput, FilecoinVerifyResult } from './provider-client.js';
+export declare class SkeletonFilecoinProviderClient implements FilecoinProviderClient {
+    readonly provider: "filecoin";
+    readonly driver: "synapse";
+    put(_input: FilecoinPutInput): Promise<FilecoinPutResult>;
+    get(_input: FilecoinGetInput): Promise<FilecoinGetResult>;
+    head(_input: FilecoinHeadInput): Promise<FilecoinHeadResult>;
+    delete(_input: FilecoinDeleteInput): Promise<FilecoinDeleteResult>;
+    verify(_input: FilecoinVerifyInput): Promise<FilecoinVerifyResult>;
+    /**
+     * The test client reports every documented required check as
+     * `'unknown' / 'not_implemented'`. The aggregate
+     * (`aggregateFilecoinReadiness`) collapses this to
+     * `ready: false`, which is exactly the contract for a
+     * non-Synapse-backed deployment.
+     */
+    checkReadiness(_network: FilecoinReadinessNetwork): Promise<ReadonlyArray<FilecoinReadinessCheck>>;
+    getServiceMinUploadBytes(): Promise<number>;
+}

package/dist/storage/providers/filecoin/skeleton-client.js

@@ -0,0 +1,55 @@
+/**
+ * @file Test-only `FilecoinProviderClient` whose every
+ * operation throws `FilecoinNotImplementedError` and whose
+ * `checkReadiness` reports every required check as
+ * `'unknown' / 'not_implemented'`.
+ *
+ * Used by tests that need to construct a `FilecoinRawContentStore`
+ * without standing up a real Synapse instance. The test
+ * "bare selection" runtime path (`createFilecoinStorageBackend(null)`)
+ * has been removed — `src/storage/factory.ts` now throws when
+ * `rawStorageProvider='filecoin'` and `filecoinProvider` is null,
+ * so this class never reaches the production composition root.
+ *
+ * The real Synapse-backed implementation lives in
+ * `synapse-client.ts` and is constructed via
+ * `synapse-construction.ts` from a parsed `FilecoinProviderConfig`.
+ */
+import { FilecoinNotImplementedError } from './errors.js';
+import { FILECOIN_READINESS_REQUIRED_CHECKS } from './readiness.js';
+export class SkeletonFilecoinProviderClient {
+    provider = 'filecoin';
+    driver = 'synapse';
+    async put(_input) {
+        throw new FilecoinNotImplementedError('put');
+    }
+    async get(_input) {
+        throw new FilecoinNotImplementedError('get');
+    }
+    async head(_input) {
+        throw new FilecoinNotImplementedError('head');
+    }
+    async delete(_input) {
+        throw new FilecoinNotImplementedError('delete');
+    }
+    async verify(_input) {
+        throw new FilecoinNotImplementedError('verify');
+    }
+    /**
+     * The test client reports every documented required check as
+     * `'unknown' / 'not_implemented'`. The aggregate
+     * (`aggregateFilecoinReadiness`) collapses this to
+     * `ready: false`, which is exactly the contract for a
+     * non-Synapse-backed deployment.
+     */
+    async checkReadiness(_network) {
+        return FILECOIN_READINESS_REQUIRED_CHECKS.map((name) => ({
+            name,
+            status: 'unknown',
+            errorCode: 'not_implemented',
+        }));
+    }
+    async getServiceMinUploadBytes() {
+        throw new FilecoinNotImplementedError('getServiceMinUploadBytes');
+    }
+}

package/dist/storage/providers/filecoin/synapse-client.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @file Synapse-driver implementation of `FilecoinProviderClient`.
+ *
+ * Wraps a constructed `Synapse` instance and translates the
+ * AtomicMemory-shaped boundary onto the SDK surface:
+ *
+ *   - `put`    → `synapse.storage.upload`
+ *   - `get`    → `synapse.storage.download`
+ *   - `head`   → `findDataSets` + `createContext` + `pieceStatus`
+ *   - `delete` → `findDataSets` + `createContext` + `deletePiece`
+ *   - `verify` → `get` + plaintext SHA-256 comparison
+ *
+ * Vendor types (`UploadResult`, `PieceCID`, `Hash`, ...) stay inside
+ * this file; the boundary surface (`FilecoinPutResult`, etc.) is
+ * the only shape that escapes the provider package.
+ *
+ * Sanitization: every Synapse error caught here is replaced with
+ * `FilecoinProviderError` + a stable `errorCode`. Raw vendor
+ * messages, wallet addresses, payment-rail state, and signed
+ * requests do not survive the boundary.
+ */
+import type { PieceCID, PieceStatus, UploadResult } from '@filoz/synapse-sdk';
+import type { FilecoinDeleteInput, FilecoinDeleteResult, FilecoinGetInput, FilecoinGetResult, FilecoinHeadInput, FilecoinHeadResult, FilecoinProviderClient, FilecoinPutInput, FilecoinPutResult, FilecoinReadinessCheck, FilecoinReadinessNetwork, FilecoinVerifyInput, FilecoinVerifyResult } from './provider-client.js';
+/**
+ * Narrow subset of `Synapse` that `SynapseFilecoinProviderClient`
+ * actually depends on. Structural — production code passes the
+ * real `Synapse` instance; tests pass a hand-rolled fake exposing
+ * only the methods exercised.
+ */
+export interface SynapseLike {
+    readonly storage: SynapseStorageLike;
+    readonly chain: SynapseChainLike;
+    readonly client: SynapseClientLike;
+}
+export interface SynapseChainLike {
+    readonly id: number | bigint;
+}
+export interface SynapseClientLike {
+    getChainId(): Promise<number | bigint>;
+}
+export interface SynapseStorageLike {
+    upload(data: Uint8Array, options?: SynapseUploadOptionsLike): Promise<UploadResult>;
+    download(options: SynapseDownloadOptionsLike): Promise<Uint8Array>;
+    findDataSets(options?: {
+        readonly address?: `0x${string}`;
+    }): Promise<ReadonlyArray<SynapseDataSetInfoLike>>;
+    createContext(options?: SynapseCreateContextOptionsLike): Promise<SynapseContextLike>;
+    getStorageInfo(): Promise<SynapseStorageInfoLike>;
+    getUploadCosts(options: {
+        readonly dataSize: bigint;
+        readonly withCDN?: boolean;
+    }): Promise<{
+        readonly ready: boolean;
+    }>;
+}
+export interface SynapseStorageInfoLike {
+    readonly providers: ReadonlyArray<SynapseProviderInfoLike>;
+    readonly serviceParameters: {
+        readonly minUploadSize: number;
+        readonly maxUploadSize: number;
+    };
+    readonly allowances: {
+        readonly isApproved: boolean;
+        readonly rateAllowance: bigint;
+        readonly rateUsed: bigint;
+        readonly lockupAllowance: bigint;
+        readonly lockupUsed: bigint;
+    } | null;
+}
+export interface SynapseProviderInfoLike {
+    readonly id: bigint;
+}
+export interface SynapseUploadOptionsLike {
+    readonly copies?: number;
+    readonly providerIds?: ReadonlyArray<bigint>;
+    readonly metadata?: Readonly<Record<string, string>>;
+    readonly pieceMetadata?: Readonly<Record<string, string>>;
+    readonly signal?: AbortSignal;
+}
+export interface SynapseDownloadOptionsLike {
+    readonly pieceCid: string | PieceCID;
+    readonly withCDN?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface SynapseCreateContextOptionsLike {
+    readonly dataSetId?: bigint;
+    readonly providerId?: bigint;
+}
+export interface SynapseDataSetInfoLike {
+    readonly dataSetId: bigint;
+    readonly providerId: bigint;
+    readonly isLive?: boolean;
+}
+export interface SynapseContextLike {
+    readonly dataSetId: bigint | undefined;
+    pieceStatus(options: {
+        readonly pieceCid: string | PieceCID;
+    }): Promise<PieceStatus | null>;
+    deletePiece(options: {
+        readonly piece: string | PieceCID | bigint;
+    }): Promise<`0x${string}`>;
+}
+/**
+ * Per-instance options the production factory threads in from the
+ * parsed `FilecoinProviderConfig`. The Synapse SDK takes
+ * provider/copy/metadata hints PER UPLOAD CALL, so we hold them on
+ * the client and merge with per-input overrides in `put`. The
+ * timeout fields are operator-configured defaults wired from
+ * `RAW_STORAGE_FILECOIN_UPLOAD_TIMEOUT_MS` and
+ * `RAW_STORAGE_FILECOIN_RETRIEVAL_TIMEOUT_MS`; per-call
+ * `input.timeoutMs` overrides them when supplied.
+ */
+export interface SynapseProviderClientOptions {
+    readonly copies?: number | null;
+    readonly providerIds?: ReadonlyArray<string>;
+    readonly dataSetMetadata?: Readonly<Record<string, string>>;
+    readonly withCdn?: boolean;
+    readonly uploadTimeoutMs?: number | null;
+    readonly retrievalTimeoutMs?: number | null;
+    /**
+     * Configured min/max upload size thresholds from
+     * `RAW_STORAGE_FILECOIN_MIN_UPLOAD_BYTES` /
+     * `RAW_STORAGE_FILECOIN_MAX_UPLOAD_BYTES`. Used only by
+     * `checkReadiness` (`upload_size_bounds_compatible`) —
+     * may extend this to also gate `put` at the adapter level.
+     */
+    readonly minUploadBytes?: number | null;
+    readonly maxUploadBytes?: number | null;
+}
+export declare class SynapseFilecoinProviderClient implements FilecoinProviderClient {
+    private readonly synapse;
+    private readonly options;
+    readonly provider: "filecoin";
+    readonly driver: "synapse";
+    constructor(synapse: SynapseLike, options?: SynapseProviderClientOptions);
+    put(input: FilecoinPutInput): Promise<FilecoinPutResult>;
+    private callSynapseUpload;
+    get(input: FilecoinGetInput): Promise<FilecoinGetResult>;
+    private callSynapseDownload;
+    head(input: FilecoinHeadInput): Promise<FilecoinHeadResult>;
+    delete(input: FilecoinDeleteInput): Promise<FilecoinDeleteResult>;
+    checkReadiness(network: FilecoinReadinessNetwork): Promise<ReadonlyArray<FilecoinReadinessCheck>>;
+    /**
+     * Non-mutating SDK read of the service-advertised minimum
+     * upload size in bytes. Exposed for preflight/sizing callers
+     * (e.g. the live calibration smoke test) that need to size
+     * payloads against the provider's real contract rather than a
+     * baked-in constant. Errors map onto
+     * `filecoin_storage_info_failed`; vendor strings stay inside.
+     */
+    getServiceMinUploadBytes(): Promise<number>;
+    private readinessOptions;
+    verify(input: FilecoinVerifyInput): Promise<FilecoinVerifyResult>;
+    /**
+     * Resolve the StorageContext that holds `pieceCid`. When the
+     * caller supplied `dataSetIdHint`, build a context for that
+     * specific data set; otherwise iterate the signer's data sets via
+     * `findDataSets` and probe each with `pieceStatus`. Returns the
+     * first context whose `pieceStatus` is non-null.
+     */
+    private locateContext;
+    /**
+     * Variant of `locateContext` that returns the `PieceStatus`
+     * directly. Used by `head` so the caller doesn't have to issue a
+     * second `pieceStatus` call to read the status it already
+     * located.
+     */
+    private locatePieceStatus;
+}