@atomicmemory/core 1.0.0

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

@@ -0,0 +1,343 @@
+/**
+ * @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 { createHash } from 'node:crypto';
+import { FilecoinProviderError } from './errors.js';
+import { wrapSynapseDeleteError, wrapSynapseDownloadError, wrapSynapseHeadError, wrapSynapseStorageInfoError, wrapSynapseUploadError, } from './synapse-error-mapping.js';
+import { synapseCheckReadiness } from './synapse-readiness.js';
+import { formatPieceUri, parsePieceUri } from './uri.js';
+export class SynapseFilecoinProviderClient {
+    synapse;
+    options;
+    provider = 'filecoin';
+    driver = 'synapse';
+    constructor(synapse, options = {}) {
+        this.synapse = synapse;
+        this.options = options;
+    }
+    async put(input) {
+        const effectiveTimeoutMs = input.timeoutMs ?? this.options.uploadTimeoutMs ?? null;
+        const controller = effectiveTimeoutMs ? new AbortController() : undefined;
+        const timer = controller && effectiveTimeoutMs
+            ? setTimeout(() => controller.abort(), effectiveTimeoutMs)
+            : undefined;
+        try {
+            const result = await this.callSynapseUpload(input, controller?.signal);
+            return mapUploadResult(result);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async callSynapseUpload(input, signal) {
+        const options = {
+            ...(this.options.copies !== null && this.options.copies !== undefined
+                ? { copies: this.options.copies }
+                : {}),
+            ...(this.options.providerIds && this.options.providerIds.length > 0
+                ? { providerIds: this.options.providerIds.map((id) => BigInt(id)) }
+                : {}),
+            ...(this.options.dataSetMetadata
+                ? { metadata: this.options.dataSetMetadata }
+                : {}),
+            ...(input.pieceMetadata ? { pieceMetadata: input.pieceMetadata } : {}),
+            ...(signal ? { signal } : {}),
+        };
+        try {
+            // `Buffer` IS a `Uint8Array` at runtime; cast for the SDK's
+            // narrower parameter type.
+            return await this.synapse.storage.upload(input.body, options);
+        }
+        catch (err) {
+            throw wrapSynapseUploadError(err, signal);
+        }
+    }
+    async get(input) {
+        const pieceCid = parsePieceUri(input.storageUri);
+        const effectiveTimeoutMs = input.timeoutMs ?? this.options.retrievalTimeoutMs ?? null;
+        const controller = effectiveTimeoutMs ? new AbortController() : undefined;
+        const timer = controller && effectiveTimeoutMs
+            ? setTimeout(() => controller.abort(), effectiveTimeoutMs)
+            : undefined;
+        try {
+            const bytes = await this.callSynapseDownload(pieceCid, controller?.signal);
+            return {
+                body: Buffer.from(bytes),
+                providerMetadata: { piece_cid: pieceCid },
+            };
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async callSynapseDownload(pieceCid, signal) {
+        const opts = {
+            pieceCid,
+            ...(this.options.withCdn !== undefined ? { withCDN: this.options.withCdn } : {}),
+            ...(signal ? { signal } : {}),
+        };
+        try {
+            return await this.synapse.storage.download(opts);
+        }
+        catch (err) {
+            throw wrapSynapseDownloadError(err, signal);
+        }
+    }
+    async head(input) {
+        const pieceCid = parsePieceUri(input.storageUri);
+        try {
+            const status = await this.locatePieceStatus(pieceCid, input.dataSetId);
+            if (status === null) {
+                return {
+                    exists: false,
+                    proven: false,
+                    providerMetadata: { piece_cid: pieceCid },
+                };
+            }
+            return {
+                exists: true,
+                proven: status.dataSetLastProven !== null,
+                providerMetadata: buildHeadMetadata(pieceCid, status),
+            };
+        }
+        catch (err) {
+            throw wrapSynapseHeadError(err);
+        }
+    }
+    async delete(input) {
+        const pieceCid = parsePieceUri(input.storageUri);
+        try {
+            const context = await this.locateContext(pieceCid, input.dataSetId);
+            if (context === null) {
+                // Piece not found in any data set the signer owns — treat
+                // as already-removed under tombstone semantics. The
+                // reconciler/cleanup path is idempotent on this.
+                return { deleted: false, semantics: 'tombstone' };
+            }
+            // Prefer the explicit per-copy `piece_id` from the upload
+            // sidecar when the caller supplied it. Synapse's
+            // `deletePiece({ piece: pieceCid })` resolves the piece via
+            // PDP active-piece lookup, which cannot complete for
+            // freshly-uploaded calibration pieces before proof lands.
+            // `BigInt(pieceId)` short-circuits the lookup and deletes
+            // by id directly. CID fallback stays for callers (and
+            // legacy rows) that don't carry the sidecar piece_id yet.
+            const pieceForDelete = input.pieceId !== undefined
+                ? toPieceIdBigIntOrThrow(input.pieceId)
+                : pieceCid;
+            const txHash = await context.deletePiece({ piece: pieceForDelete });
+            return { deleted: true, semantics: 'tombstone', txHash };
+        }
+        catch (err) {
+            throw wrapSynapseDeleteError(err);
+        }
+    }
+    async checkReadiness(network) {
+        return synapseCheckReadiness(this.synapse, this.readinessOptions(), network);
+    }
+    /**
+     * 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.
+     */
+    async getServiceMinUploadBytes() {
+        try {
+            const info = await this.synapse.storage.getStorageInfo();
+            return info.serviceParameters.minUploadSize;
+        }
+        catch (err) {
+            throw wrapSynapseStorageInfoError(err);
+        }
+    }
+    readinessOptions() {
+        return {
+            providerIds: this.options.providerIds ?? [],
+            minUploadBytes: this.options.minUploadBytes ?? null,
+            maxUploadBytes: this.options.maxUploadBytes ?? null,
+            ...(this.options.withCdn !== undefined ? { withCdn: this.options.withCdn } : {}),
+        };
+    }
+    async verify(input) {
+        let body;
+        try {
+            const got = await this.get({
+                storageUri: input.storageUri,
+                ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+            });
+            body = got.body;
+        }
+        catch (err) {
+            if (err instanceof FilecoinProviderError) {
+                return { verified: false, reason: err.errorCode };
+            }
+            return { verified: false, reason: 'filecoin_verify_failed' };
+        }
+        const actualHash = createHash('sha256').update(body).digest('hex');
+        if (actualHash === input.expectedContentHash) {
+            return { verified: true };
+        }
+        return { verified: false, reason: 'content_hash_mismatch' };
+    }
+    /**
+     * 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.
+     */
+    async locateContext(pieceCid, dataSetIdHint) {
+        if (dataSetIdHint !== undefined) {
+            const dataSetId = toBigIntOrThrow(dataSetIdHint, 'filecoin_invalid_data_set_id');
+            const context = await this.synapse.storage.createContext({ dataSetId });
+            const status = await context.pieceStatus({ pieceCid });
+            return status === null ? null : context;
+        }
+        const dataSets = await this.synapse.storage.findDataSets();
+        for (const info of dataSets) {
+            if (info.isLive === false)
+                continue;
+            const context = await this.synapse.storage.createContext({ dataSetId: info.dataSetId });
+            const status = await context.pieceStatus({ pieceCid });
+            if (status !== null)
+                return context;
+        }
+        return null;
+    }
+    /**
+     * 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.
+     */
+    async locatePieceStatus(pieceCid, dataSetIdHint) {
+        if (dataSetIdHint !== undefined) {
+            const dataSetId = toBigIntOrThrow(dataSetIdHint, 'filecoin_invalid_data_set_id');
+            const context = await this.synapse.storage.createContext({ dataSetId });
+            return context.pieceStatus({ pieceCid });
+        }
+        const dataSets = await this.synapse.storage.findDataSets();
+        for (const info of dataSets) {
+            if (info.isLive === false)
+                continue;
+            const context = await this.synapse.storage.createContext({ dataSetId: info.dataSetId });
+            const status = await context.pieceStatus({ pieceCid });
+            if (status !== null)
+                return status;
+        }
+        return null;
+    }
+}
+/**
+ * Project the Synapse `UploadResult` onto the AtomicMemory
+ * `FilecoinPutResult` boundary. The transformation is total —
+ * every input field maps to a documented output field; vendor
+ * types (`PieceCID`, `bigint`) are stringified at the boundary so
+ * the result is JSON-safe.
+ */
+function mapUploadResult(result) {
+    const pieceCid = stringifyPieceCid(result.pieceCid);
+    return {
+        pieceCid,
+        storageUri: formatPieceUri(pieceCid),
+        sizeBytes: result.size,
+        copies: result.copies.map(toCopySnapshot),
+        failedAttempts: result.failedAttempts.map(toFailedAttempt),
+        complete: result.complete,
+        requestedCopies: result.requestedCopies,
+    };
+}
+function stringifyPieceCid(pieceCid) {
+    // `PieceCID` is a `Link` from `multiformats`; its `.toString()`
+    // emits the canonical base32 representation. Defensive in case a
+    // future SDK release introduces a different runtime shape.
+    if (typeof pieceCid === 'string')
+        return pieceCid;
+    if (pieceCid && typeof pieceCid.toString === 'function') {
+        return pieceCid.toString();
+    }
+    throw new FilecoinProviderError('filecoin_invalid_piece_cid', 'Synapse upload returned an unserializable PieceCID.');
+}
+function toCopySnapshot(copy) {
+    return {
+        providerId: copy.providerId.toString(),
+        dataSetId: copy.dataSetId.toString(),
+        pieceId: copy.pieceId.toString(),
+        role: copy.role,
+    };
+}
+function toFailedAttempt(attempt) {
+    return {
+        providerId: attempt.providerId.toString(),
+        role: attempt.role,
+        errorCode: 'filecoin_copy_failed',
+        explicit: attempt.explicit,
+    };
+}
+/**
+ * Build the head-result metadata returned to the adapter. Synapse's
+ * `PieceStatus.retrievalUrl` is intentionally NOT included: it is
+ * an arbitrary provider URL whose public exposure / persistence
+ * would violate the plan's CDN/SSRF rule (no arbitrary provider
+ * URLs on public or persisted paths). The bounded fields below are
+ * all derived state (`piece_cid`, proof timestamps, challenge-
+ * window flags) that the reconciler can act on without ever
+ * needing the URL.
+ */
+function buildHeadMetadata(pieceCid, status) {
+    const meta = { piece_cid: pieceCid };
+    if (status.dataSetLastProven !== null && status.dataSetLastProven !== undefined) {
+        meta['data_set_last_proven_at'] = status.dataSetLastProven.toISOString();
+    }
+    if (status.inChallengeWindow !== undefined) {
+        meta['in_challenge_window'] = status.inChallengeWindow;
+    }
+    if (status.isProofOverdue !== undefined) {
+        meta['proof_overdue'] = status.isProofOverdue;
+    }
+    return meta;
+}
+function toBigIntOrThrow(value, errorCode) {
+    try {
+        return BigInt(value);
+    }
+    catch {
+        throw new FilecoinProviderError(errorCode, `Filecoin id '${value}' is not a valid bigint.`);
+    }
+}
+/**
+ * Strict positive-decimal-bigint parser for the `piece_id` field
+ * accepted by `delete`. The hint reader at the adapter layer
+ * already filters malformed values, but defense-in-depth: a
+ * caller passing the value directly (bypassing hints) still gets
+ * a sanitized rejection. The error message is fixed — the
+ * rejected value NEVER leaks across the boundary.
+ */
+function toPieceIdBigIntOrThrow(value) {
+    if (!/^[1-9][0-9]*$/.test(value)) {
+        throw new FilecoinProviderError('filecoin_invalid_piece_id', 'FilecoinDeleteInput.pieceId must be a positive decimal bigint string.');
+    }
+    return BigInt(value);
+}

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

@@ -0,0 +1,26 @@
+/**
+ * @file Construct a `Synapse` instance from a parsed
+ * `FilecoinProviderConfig`. Owns the viem-account + chain wiring
+ * so the rest of the provider module can stay vendor-agnostic.
+ *
+ * Boundary rule: this is the ONE place that imports
+ * `@filoz/synapse-sdk` / `@filoz/synapse-core/chains` / `viem`.
+ * Other provider files depend on the constructed `Synapse`
+ * instance via `synapse-client.ts`, not on these packages.
+ *
+ * Construction is synchronous — `Synapse.create` does not perform
+ * network I/O until the first `storage.upload` / `storage.download`
+ * / readiness call. Tests inject a fake `Synapse`-shaped object
+ * directly into `SynapseFilecoinProviderClient`; the production
+ * factory path runs through this module.
+ */
+import { Synapse } from '@filoz/synapse-sdk';
+import type { FilecoinProviderConfig } from './config.js';
+/**
+ * Build a `Synapse` instance from validated provider config.
+ * Wraps account / chain construction in `FilecoinProviderError`
+ * so the boundary stays clean even when viem rejects the key
+ * (which `parseFilecoinPrivateKey` already syntactically blocked,
+ * but defense-in-depth costs nothing).
+ */
+export declare function buildSynapse(config: FilecoinProviderConfig): Synapse;

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

@@ -0,0 +1,47 @@
+/**
+ * @file Construct a `Synapse` instance from a parsed
+ * `FilecoinProviderConfig`. Owns the viem-account + chain wiring
+ * so the rest of the provider module can stay vendor-agnostic.
+ *
+ * Boundary rule: this is the ONE place that imports
+ * `@filoz/synapse-sdk` / `@filoz/synapse-core/chains` / `viem`.
+ * Other provider files depend on the constructed `Synapse`
+ * instance via `synapse-client.ts`, not on these packages.
+ *
+ * Construction is synchronous — `Synapse.create` does not perform
+ * network I/O until the first `storage.upload` / `storage.download`
+ * / readiness call. Tests inject a fake `Synapse`-shaped object
+ * directly into `SynapseFilecoinProviderClient`; the production
+ * factory path runs through this module.
+ */
+import { Synapse, calibration, mainnet } from '@filoz/synapse-sdk';
+import { privateKeyToAccount } from 'viem/accounts';
+import { FilecoinProviderError } from './errors.js';
+/**
+ * Build a `Synapse` instance from validated provider config.
+ * Wraps account / chain construction in `FilecoinProviderError`
+ * so the boundary stays clean even when viem rejects the key
+ * (which `parseFilecoinPrivateKey` already syntactically blocked,
+ * but defense-in-depth costs nothing).
+ */
+export function buildSynapse(config) {
+    const account = toAccount(config.privateKey);
+    const chain = config.network === 'mainnet' ? mainnet : calibration;
+    return Synapse.create({
+        account,
+        chain,
+        source: config.source,
+        withCDN: config.withCdn,
+    });
+}
+function toAccount(privateKeyHex) {
+    try {
+        return privateKeyToAccount(privateKeyHex);
+    }
+    catch {
+        // `parseFilecoinPrivateKey` already enforces `^0x[a-fA-F0-9]{64}$`
+        // at config-load time. If viem still rejects, surface as a
+        // sanitized provider error — NEVER include the key value.
+        throw new FilecoinProviderError('filecoin_invalid_private_key', 'RAW_STORAGE_FILECOIN_PRIVATE_KEY failed account derivation.');
+    }
+}

package/dist/storage/providers/filecoin/synapse-error-mapping.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file Vendor → boundary error mapping for `SynapseFilecoinProviderClient`.
+ *
+ * Each helper replaces a raw `@filoz/synapse-sdk` error with a
+ * sanitized `FilecoinProviderError` carrying a closed-set
+ * `errorCode`. The vendor `message` string NEVER reaches the
+ * boundary — it could embed wallet addresses, balances, signed
+ * requests, RPC URLs, or other operator-internal data that the
+ * provider package promises not to leak. The replacement message
+ * is a fixed, hand-written sentence whose ONLY variability is the
+ * stable `errorCode`.
+ *
+ * Lives in its own module so `synapse-client.ts` stays under the
+ * workspace 400-LOC cap. The boundary surface here is consumed
+ * only by `synapse-client.ts`; nothing else in the provider
+ * package depends on these helpers.
+ */
+import { FilecoinProviderError } from './errors.js';
+export declare function wrapSynapseUploadError(err: unknown, signal: AbortSignal | undefined): FilecoinProviderError;
+export declare function wrapSynapseDownloadError(err: unknown, signal: AbortSignal | undefined): FilecoinProviderError;
+export declare function wrapSynapseHeadError(err: unknown): FilecoinProviderError;
+export declare function wrapSynapseDeleteError(err: unknown): FilecoinProviderError;
+export declare function wrapSynapseStorageInfoError(err: unknown): FilecoinProviderError;

package/dist/storage/providers/filecoin/synapse-error-mapping.js

@@ -0,0 +1,49 @@
+/**
+ * @file Vendor → boundary error mapping for `SynapseFilecoinProviderClient`.
+ *
+ * Each helper replaces a raw `@filoz/synapse-sdk` error with a
+ * sanitized `FilecoinProviderError` carrying a closed-set
+ * `errorCode`. The vendor `message` string NEVER reaches the
+ * boundary — it could embed wallet addresses, balances, signed
+ * requests, RPC URLs, or other operator-internal data that the
+ * provider package promises not to leak. The replacement message
+ * is a fixed, hand-written sentence whose ONLY variability is the
+ * stable `errorCode`.
+ *
+ * Lives in its own module so `synapse-client.ts` stays under the
+ * workspace 400-LOC cap. The boundary surface here is consumed
+ * only by `synapse-client.ts`; nothing else in the provider
+ * package depends on these helpers.
+ */
+import { FilecoinProviderError } from './errors.js';
+export function wrapSynapseUploadError(err, signal) {
+    if (signal?.aborted) {
+        return new FilecoinProviderError('filecoin_upload_timeout', 'Synapse upload aborted by RAW_STORAGE_FILECOIN_UPLOAD_TIMEOUT_MS.');
+    }
+    if (err instanceof FilecoinProviderError)
+        return err;
+    return new FilecoinProviderError('filecoin_upload_failed', 'Synapse upload failed; vendor error suppressed at the provider boundary.');
+}
+export function wrapSynapseDownloadError(err, signal) {
+    if (signal?.aborted) {
+        return new FilecoinProviderError('filecoin_download_timeout', 'Synapse download aborted by RAW_STORAGE_FILECOIN_RETRIEVAL_TIMEOUT_MS.');
+    }
+    if (err instanceof FilecoinProviderError)
+        return err;
+    return new FilecoinProviderError('filecoin_download_failed', 'Synapse download failed; vendor error suppressed at the provider boundary.');
+}
+export function wrapSynapseHeadError(err) {
+    if (err instanceof FilecoinProviderError)
+        return err;
+    return new FilecoinProviderError('filecoin_head_failed', 'Synapse pieceStatus failed; vendor error suppressed at the provider boundary.');
+}
+export function wrapSynapseDeleteError(err) {
+    if (err instanceof FilecoinProviderError)
+        return err;
+    return new FilecoinProviderError('filecoin_delete_failed', 'Synapse deletePiece failed; vendor error suppressed at the provider boundary.');
+}
+export function wrapSynapseStorageInfoError(err) {
+    if (err instanceof FilecoinProviderError)
+        return err;
+    return new FilecoinProviderError('filecoin_storage_info_failed', 'Synapse getStorageInfo failed; vendor error suppressed at the provider boundary.');
+}

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

@@ -0,0 +1,37 @@
+/**
+ * @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 type { FilecoinReadinessCheck, FilecoinReadinessNetwork } from './provider-client.js';
+import type { SynapseLike } from './synapse-client.js';
+export interface ReadinessProbeOptions {
+    readonly providerIds: ReadonlyArray<string>;
+    readonly minUploadBytes: number | null;
+    readonly maxUploadBytes: number | null;
+    readonly withCdn?: boolean;
+}
+/**
+ * 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 declare function synapseCheckReadiness(synapse: SynapseLike, options: ReadinessProbeOptions, network: FilecoinReadinessNetwork): Promise<ReadonlyArray<FilecoinReadinessCheck>>;