@atomicmemory/core 1.0.0

package/dist/storage/cleanup.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Managed-blob cleanup helper (raw-content + per-row provider dispatch).
+ *
+ * Every code path that soft- or hard-deletes a `raw_documents` row
+ * backed by `storage_mode='managed_blob'` runs the collected
+ * `(storage_provider, storage_uri)` tuples through this helper *after*
+ * the DB transaction commits.
+ *
+ * per-row provider dispatch changes: cleanup dispatches per `blob.storageProvider` via
+ * a `RawContentStoreRegistry`, not via a single active store. A row
+ * created when the deployment was on `local_fs` and still pending
+ * cleanup after the deployment switched to `filecoin` is handled by
+ * the registered legacy adapter (`RAW_STORAGE_LEGACY_PROVIDERS`).
+ * Providers that aren't registered surface as failures with an
+ * explicit error message — never silent no-ops.
+ *
+ * Result shape: `successes` carries one entry per non-failure outcome
+ * (including `deleted: false` already-missing) so callers can write the
+ * correct terminal marker (`blob_deleted` vs `blob_tombstoned`) based
+ * on the adapter's `semantics` field. The legacy `deleted` /
+ * `alreadyMissing` counters are kept for backwards-compatible metrics.
+ *
+ * Failure model: per-blob delete is attempted independently. The
+ * adapter's `delete()` already treats "missing" as a NON-ERROR
+ * outcome with `deleted: false`. Adapter errors (network, auth,
+ * permission, missing provider) are NEVER swallowed — they're
+ * collected on `failures` and the caller MUST surface a 500 to the
+ * client (see `ManagedBlobCleanupError`). No degraded mode.
+ *
+ * Hint plumbing: `ManagedBlobRef.rawStorageMetadata` carries the
+ * row's `raw_documents.raw_storage_metadata` JSONB so the cleanup
+ * loop can hand it to `RawContentStore.delete(uri, hints)` as an
+ * opaque `RawContentHints` object. The Filecoin adapter narrows
+ * this to `filecoin.data_set_id` + `filecoin.copies[].piece_id`
+ * and issues a hinted `deletePiece({ piece: BigInt(pieceId) })`
+ * against the resolved context — which bypasses the SDK's
+ * CID→active-piece lookup and lets a freshly-uploaded piece
+ * (still pre-PDP-proof) be deleted directly. Non-Filecoin
+ * adapters (local_fs, s3) ignore the `hints` argument.
+ */
+import type { RawContentDeleteResult } from './raw-content-store.js';
+import type { RawContentStoreRegistry } from './store-registry.js';
+export interface ManagedBlobRef {
+    /** Source-row id — required so the cleanup loop can sync the
+     * paired `storage_artifacts` row by id (URIs are not globally
+     * unique across documents). */
+    rawDocumentId: string;
+    storageProvider: string;
+    storageUri: string;
+    /** `raw_documents.raw_storage_metadata` JSONB (defaulted to `{}`
+     * by the repository mapper for legacy rows). Threaded through
+     * to `RawContentStore.delete` as opaque `RawContentHints` —
+     * each adapter narrows its own provider sibling. Required:
+     * production repository rows always populate it (the
+     * `toManagedBlobRef` mapper coerces missing/non-object JSONB
+     * to `{}`), and direct test callers pass `{}` explicitly. */
+    rawStorageMetadata: Record<string, unknown>;
+}
+/**
+ * Result entries DO NOT extend `ManagedBlobRef`. `rawStorageMetadata`
+ * is INPUT-ONLY hint material (Filecoin sidecar fields like
+ * `data_set_id` / `copies[].piece_id`) and must never appear on
+ * a result record or in `ManagedBlobCleanupError.result` — those
+ * surface to route handlers / 500 envelopes / observability and
+ * the hint sidecar isn't on the public allowlist. The cleanup
+ * loop hands the metadata to `RawContentStore.delete` and then
+ * drops it before constructing the entry below.
+ */
+export interface ManagedBlobCleanupSuccess {
+    rawDocumentId: string;
+    storageProvider: string;
+    storageUri: string;
+    /** True when the adapter actively removed bytes; false for already-missing. */
+    deleted: boolean;
+    /** What the adapter's delete did — drives terminal marker selection. */
+    semantics: RawContentDeleteResult['semantics'];
+}
+export interface ManagedBlobFailure {
+    rawDocumentId: string;
+    storageProvider: string;
+    storageUri: string;
+    message: string;
+}
+export interface ManagedBlobCleanupResult {
+    attempted: number;
+    /** Count metric — number of `successes` with `deleted=true`. */
+    deleted: number;
+    /** Count metric — number of `successes` with `deleted=false`. */
+    alreadyMissing: number;
+    /** One entry per non-failure outcome; iteration drives marker writes. */
+    successes: ManagedBlobCleanupSuccess[];
+    failures: ManagedBlobFailure[];
+}
+export declare function cleanupManagedBlobs(registry: RawContentStoreRegistry, blobs: ManagedBlobRef[]): Promise<ManagedBlobCleanupResult>;
+/**
+ * Thrown by callers when one or more blob deletes raised. Wraps the
+ * cleanup result so the route layer can surface a 500 with the failed
+ * URIs instead of silently corrupting the cleanup contract.
+ */
+export declare class ManagedBlobCleanupError extends Error {
+    readonly result: ManagedBlobCleanupResult;
+    constructor(result: ManagedBlobCleanupResult);
+}

package/dist/storage/cleanup.js

@@ -0,0 +1,138 @@
+/**
+ * Managed-blob cleanup helper (raw-content + per-row provider dispatch).
+ *
+ * Every code path that soft- or hard-deletes a `raw_documents` row
+ * backed by `storage_mode='managed_blob'` runs the collected
+ * `(storage_provider, storage_uri)` tuples through this helper *after*
+ * the DB transaction commits.
+ *
+ * per-row provider dispatch changes: cleanup dispatches per `blob.storageProvider` via
+ * a `RawContentStoreRegistry`, not via a single active store. A row
+ * created when the deployment was on `local_fs` and still pending
+ * cleanup after the deployment switched to `filecoin` is handled by
+ * the registered legacy adapter (`RAW_STORAGE_LEGACY_PROVIDERS`).
+ * Providers that aren't registered surface as failures with an
+ * explicit error message — never silent no-ops.
+ *
+ * Result shape: `successes` carries one entry per non-failure outcome
+ * (including `deleted: false` already-missing) so callers can write the
+ * correct terminal marker (`blob_deleted` vs `blob_tombstoned`) based
+ * on the adapter's `semantics` field. The legacy `deleted` /
+ * `alreadyMissing` counters are kept for backwards-compatible metrics.
+ *
+ * Failure model: per-blob delete is attempted independently. The
+ * adapter's `delete()` already treats "missing" as a NON-ERROR
+ * outcome with `deleted: false`. Adapter errors (network, auth,
+ * permission, missing provider) are NEVER swallowed — they're
+ * collected on `failures` and the caller MUST surface a 500 to the
+ * client (see `ManagedBlobCleanupError`). No degraded mode.
+ *
+ * Hint plumbing: `ManagedBlobRef.rawStorageMetadata` carries the
+ * row's `raw_documents.raw_storage_metadata` JSONB so the cleanup
+ * loop can hand it to `RawContentStore.delete(uri, hints)` as an
+ * opaque `RawContentHints` object. The Filecoin adapter narrows
+ * this to `filecoin.data_set_id` + `filecoin.copies[].piece_id`
+ * and issues a hinted `deletePiece({ piece: BigInt(pieceId) })`
+ * against the resolved context — which bypasses the SDK's
+ * CID→active-piece lookup and lets a freshly-uploaded piece
+ * (still pre-PDP-proof) be deleted directly. Non-Filecoin
+ * adapters (local_fs, s3) ignore the `hints` argument.
+ */
+import { emitFilecoinEvent } from '../services/filecoin-observability.js';
+export async function cleanupManagedBlobs(registry, blobs) {
+    const result = {
+        attempted: blobs.length,
+        deleted: 0,
+        alreadyMissing: 0,
+        successes: [],
+        failures: [],
+    };
+    for (const blob of blobs) {
+        await processOneBlob(registry, blob, result);
+    }
+    return result;
+}
+/**
+ * Process a single blob through the registry-resolved adapter
+ * and append the outcome to `result`. Split out so the outer
+ * loop stays under the workspace complexity caps after the
+ * Phase 7 observability emit was added.
+ *
+ * Closed-key discipline: we NEVER spread `...blob` into a
+ * result entry — that would carry `rawStorageMetadata` (the
+ * Filecoin sidecar with `piece_id` / `data_set_id` / planted
+ * secrets) into the success/failure output, the
+ * `ManagedBlobCleanupError.result` payload, and downstream
+ * observability. Each entry is built from the three public
+ * fields (`rawDocumentId`, `storageProvider`, `storageUri`)
+ * plus the adapter's own scalars (`deleted`, `semantics`,
+ * `message`). The `RawContentDeleteResult.txHash` field, when
+ * present, is routed ONLY to the internal observability event
+ * — never to the success entry. Pinned by
+ * `cleanup-leak-invariants.test.ts`.
+ */
+async function processOneBlob(registry, blob, result) {
+    const publicRef = {
+        rawDocumentId: blob.rawDocumentId,
+        storageProvider: blob.storageProvider,
+        storageUri: blob.storageUri,
+    };
+    const store = registry.get(blob.storageProvider);
+    if (!store) {
+        result.failures.push({
+            ...publicRef,
+            message: `managed_blob cleanup requested for provider '${blob.storageProvider}' but no ` +
+                'adapter is registered. Set RAW_STORAGE_LEGACY_PROVIDERS to include this provider, ' +
+                'or migrate the row before retiring its adapter.',
+        });
+        return;
+    }
+    try {
+        const r = await store.delete(blob.storageUri, blob.rawStorageMetadata);
+        if (r.deleted)
+            result.deleted++;
+        else
+            result.alreadyMissing++;
+        emitDeleteTxHashIfAny(blob.storageProvider, r);
+        result.successes.push({ ...publicRef, deleted: r.deleted, semantics: r.semantics });
+    }
+    catch (err) {
+        result.failures.push({
+            ...publicRef,
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+/**
+ * Phase 7 billing/cost-impact metadata. If the Filecoin adapter
+ * returned an on-chain `txHash` (the Synapse SDK's `deletePiece`
+ * scheduled-removal tx), emit it on the internal
+ * `filecoin.delete.tombstoned` observability event for
+ * operator-side cost auditing. The hash NEVER reaches the
+ * cleanup-result DTO — it travels only on the closed
+ * `FilecoinEventPayload.deleteTxHash` channel.
+ */
+function emitDeleteTxHashIfAny(storageProvider, r) {
+    if (r.txHash === undefined || storageProvider !== 'filecoin')
+        return;
+    emitFilecoinEvent('filecoin.delete.tombstoned', {
+        provider: storageProvider,
+        deleteTxHash: r.txHash,
+        statusAfter: r.semantics === 'deleted' ? 'blob_deleted' : 'blob_tombstoned',
+    });
+}
+/**
+ * Thrown by callers when one or more blob deletes raised. Wraps the
+ * cleanup result so the route layer can surface a 500 with the failed
+ * URIs instead of silently corrupting the cleanup contract.
+ */
+export class ManagedBlobCleanupError extends Error {
+    result;
+    constructor(result) {
+        const first = result.failures[0];
+        super(`managed_blob cleanup failed: ${result.failures.length} of ${result.attempted} ` +
+            `(first: ${first?.storageUri ?? '<unknown>'}: ${first?.message ?? '<no message>'})`);
+        this.result = result;
+        this.name = 'ManagedBlobCleanupError';
+    }
+}

package/dist/storage/codec-factory.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Construct the `RawContentCodec` instance the upload service wraps
+ * around `RawContentStore.put()` / `get()` (Phase 5 wiring).
+ *
+ * The factory is composition-root code: validates the configured
+ * codec/keyring is consistent (config validation already enforced this
+ * at startup; this is defense-in-depth) and returns the codec
+ * implementation. Returns the noop codec for `RAW_CONTENT_CODEC='none'`
+ * — bytes pass through unchanged but a `{ name: 'none', version: 1 }`
+ * sidecar still lands in `raw_storage_metadata.codec` so the read
+ * path branches deterministically.
+ */
+import type { RuntimeConfig } from '../config.js';
+import type { RawContentCodec } from './raw-content-codec.js';
+type CodecConfig = Pick<RuntimeConfig, 'rawContentCodec' | 'rawContentCodecKeys' | 'rawContentCodecActiveKeyId'>;
+export declare function buildRawContentCodec(cfg: CodecConfig): RawContentCodec;
+export {};

package/dist/storage/codec-factory.js

@@ -0,0 +1,33 @@
+/**
+ * Construct the `RawContentCodec` instance the upload service wraps
+ * around `RawContentStore.put()` / `get()` (Phase 5 wiring).
+ *
+ * The factory is composition-root code: validates the configured
+ * codec/keyring is consistent (config validation already enforced this
+ * at startup; this is defense-in-depth) and returns the codec
+ * implementation. Returns the noop codec for `RAW_CONTENT_CODEC='none'`
+ * — bytes pass through unchanged but a `{ name: 'none', version: 1 }`
+ * sidecar still lands in `raw_storage_metadata.codec` so the read
+ * path branches deterministically.
+ */
+import { NoopRawContentCodec } from './codecs/noop-codec.js';
+import { AesGcmRawContentCodec } from './codecs/aes-gcm-codec.js';
+export function buildRawContentCodec(cfg) {
+    if (cfg.rawContentCodec === 'none') {
+        return new NoopRawContentCodec();
+    }
+    if (!cfg.rawContentCodecActiveKeyId) {
+        throw new Error("buildRawContentCodec: RAW_CONTENT_CODEC='aes_gcm' requires RAW_CONTENT_CODEC_ACTIVE_KEY_ID.");
+    }
+    const keys = Array.from(cfg.rawContentCodecKeys.entries()).map(([keyId, key]) => ({
+        keyId,
+        key,
+    }));
+    if (keys.length === 0) {
+        throw new Error("buildRawContentCodec: RAW_CONTENT_CODEC='aes_gcm' requires a non-empty RAW_CONTENT_CODEC_KEYS ring.");
+    }
+    return new AesGcmRawContentCodec({
+        keys,
+        activeKeyId: cfg.rawContentCodecActiveKeyId,
+    });
+}

package/dist/storage/codecs/aes-gcm-codec.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AES-256-GCM content codec backed by a keyring. `encode` picks the
+ * caller-provided ACTIVE key and writes `{ name, version, key_id,
+ * nonce, tag, encoded_content_hash, encoded_size_bytes }` into the
+ * sidecar metadata. `decode` reads `key_id` from the metadata, looks up
+ * THAT key in the ring, and runs `createDecipheriv` — wrong key, wrong
+ * nonce, or tampered ciphertext all surface as
+ * `RawContentCodecError` via the GCM auth tag.
+ *
+ * Keys are 32 bytes (AES-256). Nonces are 12 random bytes per encode
+ * (the GCM IV — must be unique per (key, message) pair). Tags are 16
+ * bytes (the default GCM auth tag size).
+ *
+ * Encoding stores diagnostic context (`encoded_content_hash`,
+ * `encoded_size_bytes`) under the codec sidecar — these never reach
+ * the wire (rev-6 §6 redaction allowlist), they exist so ops can
+ * correlate the bytes the adapter saw with the row's plaintext
+ * `content_hash`.
+ */
+import type { RawContentCodec, RawContentCodecDecodeInput, RawContentCodecDecodeResult, RawContentCodecEncodeInput, RawContentCodecEncodeResult } from '../raw-content-codec.js';
+/**
+ * Keyring entry: parsed 32-byte key paired with its operator-assigned
+ * id. The id is what ends up in `raw_storage_metadata.codec.key_id`
+ * so future decodes can find the right key even after rotation.
+ */
+export interface AesGcmKeyringEntry {
+    keyId: string;
+    key: Buffer;
+}
+/** Operator-provided keyring config consumed by the codec constructor. */
+export interface AesGcmKeyringConfig {
+    /** Every key the codec can decode with. MUST contain `activeKeyId`. */
+    keys: ReadonlyArray<AesGcmKeyringEntry>;
+    /** Which key id to use for new `encode` calls. */
+    activeKeyId: string;
+}
+export declare class AesGcmRawContentCodec implements RawContentCodec {
+    readonly name: "aes_gcm";
+    private readonly ring;
+    private readonly activeKeyId;
+    constructor(config: AesGcmKeyringConfig);
+    encode(input: RawContentCodecEncodeInput): Promise<RawContentCodecEncodeResult>;
+    decode(input: RawContentCodecDecodeInput): Promise<RawContentCodecDecodeResult>;
+}

package/dist/storage/codecs/aes-gcm-codec.js

@@ -0,0 +1,108 @@
+/**
+ * AES-256-GCM content codec backed by a keyring. `encode` picks the
+ * caller-provided ACTIVE key and writes `{ name, version, key_id,
+ * nonce, tag, encoded_content_hash, encoded_size_bytes }` into the
+ * sidecar metadata. `decode` reads `key_id` from the metadata, looks up
+ * THAT key in the ring, and runs `createDecipheriv` — wrong key, wrong
+ * nonce, or tampered ciphertext all surface as
+ * `RawContentCodecError` via the GCM auth tag.
+ *
+ * Keys are 32 bytes (AES-256). Nonces are 12 random bytes per encode
+ * (the GCM IV — must be unique per (key, message) pair). Tags are 16
+ * bytes (the default GCM auth tag size).
+ *
+ * Encoding stores diagnostic context (`encoded_content_hash`,
+ * `encoded_size_bytes`) under the codec sidecar — these never reach
+ * the wire (rev-6 §6 redaction allowlist), they exist so ops can
+ * correlate the bytes the adapter saw with the row's plaintext
+ * `content_hash`.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import { RawContentCodecError, RawContentCodecKeyNotFoundError, } from '../raw-content-codec.js';
+const AES_GCM_CODEC_VERSION = 1;
+const AES_GCM_KEY_BYTES = 32;
+const AES_GCM_NONCE_BYTES = 12;
+const AES_GCM_TAG_BYTES = 16;
+function assertKeyBytes(keyId, key) {
+    if (key.length !== AES_GCM_KEY_BYTES) {
+        throw new RawContentCodecError(`AES-256-GCM key '${keyId}' must be exactly ${AES_GCM_KEY_BYTES} bytes (got ${key.length}).`);
+    }
+}
+export class AesGcmRawContentCodec {
+    name = 'aes_gcm';
+    ring;
+    activeKeyId;
+    constructor(config) {
+        if (config.keys.length === 0) {
+            throw new RawContentCodecError('AES-GCM codec requires at least one key in the ring.');
+        }
+        this.ring = new Map();
+        for (const entry of config.keys) {
+            assertKeyBytes(entry.keyId, entry.key);
+            if (this.ring.has(entry.keyId)) {
+                throw new RawContentCodecError(`Duplicate keyId '${entry.keyId}' in keyring.`);
+            }
+            this.ring.set(entry.keyId, entry.key);
+        }
+        if (!this.ring.has(config.activeKeyId)) {
+            throw new RawContentCodecError(`Active key id '${config.activeKeyId}' is not present in the keyring.`);
+        }
+        this.activeKeyId = config.activeKeyId;
+    }
+    async encode(input) {
+        const key = this.ring.get(this.activeKeyId);
+        if (!key) {
+            throw new RawContentCodecKeyNotFoundError(this.activeKeyId);
+        }
+        const nonce = randomBytes(AES_GCM_NONCE_BYTES);
+        const cipher = createCipheriv('aes-256-gcm', key, nonce);
+        const ciphertext = Buffer.concat([cipher.update(input.body), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        const encodedHash = createHash('sha256').update(ciphertext).digest('hex');
+        const metadata = {
+            name: 'aes_gcm',
+            version: AES_GCM_CODEC_VERSION,
+            key_id: this.activeKeyId,
+            nonce: nonce.toString('base64url'),
+            tag: tag.toString('base64url'),
+            encoded_content_hash: encodedHash,
+            encoded_size_bytes: ciphertext.length,
+        };
+        return { body: ciphertext, metadata };
+    }
+    async decode(input) {
+        const { metadata } = input;
+        if (metadata.name !== 'aes_gcm') {
+            throw new RawContentCodecError(`AES-GCM codec cannot decode metadata.name='${metadata.name}'.`);
+        }
+        if (!metadata.key_id) {
+            throw new RawContentCodecError('AES-GCM codec metadata is missing key_id.');
+        }
+        const key = this.ring.get(metadata.key_id);
+        if (!key) {
+            throw new RawContentCodecKeyNotFoundError(metadata.key_id);
+        }
+        const nonce = decodeBase64Url(metadata.nonce, 'nonce', AES_GCM_NONCE_BYTES);
+        const tag = decodeBase64Url(metadata.tag, 'tag', AES_GCM_TAG_BYTES);
+        const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+        decipher.setAuthTag(tag);
+        try {
+            const plaintext = Buffer.concat([decipher.update(input.body), decipher.final()]);
+            return { body: plaintext };
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new RawContentCodecError(`AES-GCM decode failed (auth tag mismatch or tamper): ${reason}`);
+        }
+    }
+}
+function decodeBase64Url(value, field, expectedBytes) {
+    if (!value) {
+        throw new RawContentCodecError(`AES-GCM codec metadata is missing '${field}'.`);
+    }
+    const buf = Buffer.from(value, 'base64url');
+    if (buf.length !== expectedBytes) {
+        throw new RawContentCodecError(`AES-GCM codec metadata '${field}' has ${buf.length} bytes; expected ${expectedBytes}.`);
+    }
+    return buf;
+}

package/dist/storage/codecs/noop-codec.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pass-through codec: bytes go in and bytes come out unchanged. Used
+ * when `RAW_CONTENT_CODEC=none` — the immediate-provider default for
+ * `local_fs` / `s3` deployments where operator-level encryption isn't
+ * needed (or is handled below the application layer by the provider).
+ *
+ * Round-trips a `name + version` sidecar so the read path can branch on
+ * `metadata.codec.name === 'none'` deterministically rather than
+ * inferring "no codec" from a missing key.
+ */
+import type { RawContentCodec, RawContentCodecDecodeInput, RawContentCodecDecodeResult, RawContentCodecEncodeInput, RawContentCodecEncodeResult } from '../raw-content-codec.js';
+export declare class NoopRawContentCodec implements RawContentCodec {
+    readonly name: "none";
+    encode(input: RawContentCodecEncodeInput): Promise<RawContentCodecEncodeResult>;
+    decode(input: RawContentCodecDecodeInput): Promise<RawContentCodecDecodeResult>;
+}

package/dist/storage/codecs/noop-codec.js

@@ -0,0 +1,23 @@
+/**
+ * Pass-through codec: bytes go in and bytes come out unchanged. Used
+ * when `RAW_CONTENT_CODEC=none` — the immediate-provider default for
+ * `local_fs` / `s3` deployments where operator-level encryption isn't
+ * needed (or is handled below the application layer by the provider).
+ *
+ * Round-trips a `name + version` sidecar so the read path can branch on
+ * `metadata.codec.name === 'none'` deterministically rather than
+ * inferring "no codec" from a missing key.
+ */
+const NOOP_CODEC_VERSION = 1;
+export class NoopRawContentCodec {
+    name = 'none';
+    async encode(input) {
+        return {
+            body: input.body,
+            metadata: { name: 'none', version: NOOP_CODEC_VERSION },
+        };
+    }
+    async decode(input) {
+        return { body: input.body };
+    }
+}

package/dist/storage/factory.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Builds the `RawContentStore` instance backing
+ * `rawStorageMode='managed_blob'`.
+ *
+ * The actual cross-field validation happens at config-load time in
+ * `src/config.ts` (`validateRawStorageConfig`). This factory trusts
+ * the validated config: when `rawStorageMode='managed_blob'` arrives,
+ * the provider-specific fields are already non-null. When mode is
+ * `pointer_only`, the factory returns `null` and document upload routes
+ * report 503 to clients that try to upload anyway — see the route
+ * layer for the user-facing error envelope.
+ */
+import type { RuntimeConfig } from '../config.js';
+import type { RawContentStore } from './raw-content-store.js';
+type RawStorageConfig = Pick<RuntimeConfig, 'rawStorageMode' | 'rawStorageProvider' | 'rawStorageLocalFsRoot' | 'rawStorageS3Bucket' | 'rawStorageS3Region' | 'rawStorageS3Endpoint' | 'rawStorageS3AccessKeyId' | 'rawStorageS3SecretAccessKey' | 'rawStorageDeploymentEnv' | 'rawStorageLegacyProviders' | 'filecoinProvider'>;
+/**
+ * Returns `null` when raw bytes are not stored by core (pointer-only
+ * default). Returns a configured adapter when
+ * `rawStorageMode='managed_blob'`.
+ *
+ * Async because some providers (e.g. the Synapse-backed Filecoin
+ * client) may need async composition at startup. The current
+ * `createFilecoinStorageBackend` is synchronous internally; the
+ * async return type preserves the boundary for future
+ * providers that need awaitable construction (handshake,
+ * credential exchange, etc.) without forcing a signature change.
+ */
+export declare function buildRawContentStore(cfg: RawStorageConfig): Promise<RawContentStore | null>;
+/**
+ * Build read-only adapters for any legacy providers configured via
+ * `RAW_STORAGE_LEGACY_PROVIDERS`. Composition-root code registers
+ * these in the `RawContentStoreRegistry` alongside the active store
+ * so cleanup dispatches historical rows to the right adapter (Phase
+ * 4a §6 — `local-fs://...` rows on a Filecoin-active deployment
+ * still need a registered `local_fs` adapter to run their DELETE).
+ *
+ * `validateRawStorageConfig` already enforced that every named legacy
+ * provider has its full env block; this function trusts that
+ * validation and re-runs the per-provider builder. Returns an empty
+ * array when the operator hasn't configured any legacy providers —
+ * the common single-provider deployment.
+ */
+export declare function buildLegacyStores(cfg: RawStorageConfig): ReadonlyArray<RawContentStore>;
+export {};

package/dist/storage/factory.js

@@ -0,0 +1,99 @@
+/**
+ * Builds the `RawContentStore` instance backing
+ * `rawStorageMode='managed_blob'`.
+ *
+ * The actual cross-field validation happens at config-load time in
+ * `src/config.ts` (`validateRawStorageConfig`). This factory trusts
+ * the validated config: when `rawStorageMode='managed_blob'` arrives,
+ * the provider-specific fields are already non-null. When mode is
+ * `pointer_only`, the factory returns `null` and document upload routes
+ * report 503 to clients that try to upload anyway — see the route
+ * layer for the user-facing error envelope.
+ */
+import { LocalFsRawContentStore } from './local-fs-store.js';
+import { S3RawContentStore } from './s3-store.js';
+/**
+ * Returns `null` when raw bytes are not stored by core (pointer-only
+ * default). Returns a configured adapter when
+ * `rawStorageMode='managed_blob'`.
+ *
+ * Async because some providers (e.g. the Synapse-backed Filecoin
+ * client) may need async composition at startup. The current
+ * `createFilecoinStorageBackend` is synchronous internally; the
+ * async return type preserves the boundary for future
+ * providers that need awaitable construction (handshake,
+ * credential exchange, etc.) without forcing a signature change.
+ */
+export async function buildRawContentStore(cfg) {
+    if (cfg.rawStorageMode !== 'managed_blob')
+        return null;
+    if (cfg.rawStorageProvider === 'local_fs')
+        return buildLocalFs(cfg);
+    if (cfg.rawStorageProvider === 's3')
+        return buildS3(cfg);
+    if (cfg.rawStorageProvider === 'filecoin') {
+        if (cfg.filecoinProvider === null) {
+            // Defense-in-depth: `parseFilecoinProviderConfig` in
+            // `src/config.ts` already enforces "filecoin selected ⇒ full
+            // RAW_STORAGE_FILECOIN_* env block", so this branch is
+            // unreachable in production. Throw rather than silently
+            // construct a half-wired backend that advertises supportsHead
+            // / supportsGet but cannot actually perform either.
+            throw new Error("buildRawContentStore: rawStorageProvider='filecoin' but filecoinProvider config is null. " +
+                'Set the full RAW_STORAGE_FILECOIN_* env block.');
+        }
+        // Lazy: heavy Filecoin packages (`@filoz/synapse-sdk`, `viem`)
+        // resolve ONLY here, never on non-Filecoin startup. The defense-
+        // in-depth `cfg.filecoinProvider === null` throw above runs
+        // BEFORE the import, so a misconfigured deployment fails fast
+        // without pulling the vendor SDK either.
+        const { createFilecoinStorageBackend } = await import('./providers/filecoin/index.js');
+        return createFilecoinStorageBackend(cfg.filecoinProvider);
+    }
+    // Defense-in-depth: config validation should already have caught this.
+    throw new Error(`buildRawContentStore: rawStorageMode='managed_blob' but provider is missing/unknown ` +
+        `(got '${cfg.rawStorageProvider}'). Fix RAW_STORAGE_PROVIDER and restart.`);
+}
+function buildLocalFs(cfg) {
+    if (!cfg.rawStorageLocalFsRoot) {
+        throw new Error("buildRawContentStore(local_fs): RAW_STORAGE_LOCAL_FS_ROOT is required.");
+    }
+    return new LocalFsRawContentStore({ root: cfg.rawStorageLocalFsRoot });
+}
+function buildS3(cfg) {
+    if (!cfg.rawStorageS3Bucket || !cfg.rawStorageS3Region
+        || !cfg.rawStorageS3AccessKeyId || !cfg.rawStorageS3SecretAccessKey) {
+        throw new Error("buildRawContentStore(s3): bucket/region/access-key-id/secret-access-key are all required.");
+    }
+    return new S3RawContentStore({
+        bucket: cfg.rawStorageS3Bucket,
+        region: cfg.rawStorageS3Region,
+        endpoint: cfg.rawStorageS3Endpoint ?? undefined,
+        accessKeyId: cfg.rawStorageS3AccessKeyId,
+        secretAccessKey: cfg.rawStorageS3SecretAccessKey,
+    });
+}
+/**
+ * Build read-only adapters for any legacy providers configured via
+ * `RAW_STORAGE_LEGACY_PROVIDERS`. Composition-root code registers
+ * these in the `RawContentStoreRegistry` alongside the active store
+ * so cleanup dispatches historical rows to the right adapter (Phase
+ * 4a §6 — `local-fs://...` rows on a Filecoin-active deployment
+ * still need a registered `local_fs` adapter to run their DELETE).
+ *
+ * `validateRawStorageConfig` already enforced that every named legacy
+ * provider has its full env block; this function trusts that
+ * validation and re-runs the per-provider builder. Returns an empty
+ * array when the operator hasn't configured any legacy providers —
+ * the common single-provider deployment.
+ */
+export function buildLegacyStores(cfg) {
+    return cfg.rawStorageLegacyProviders.map((provider) => {
+        if (provider === 'local_fs')
+            return buildLocalFs(cfg);
+        if (provider === 's3')
+            return buildS3(cfg);
+        // Defense-in-depth: validation already rejects 'filecoin' here.
+        throw new Error(`buildLegacyStores: provider '${provider}' is not registerable as legacy.`);
+    });
+}