@atomicmemory/core 1.0.0

package/dist/storage/providers/filecoin/verified-fetch-retriever.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @file Verified-fetch retriever — Phase 6 experimental
+ * `FilecoinRetriever` implementation backed by
+ * `@helia/verified-fetch`.
+ *
+ * The retriever takes a parsed `CID` (never a URL) and
+ * constructs the canonical `ipfs://<cid>` form internally before
+ * handing it to verified-fetch. This is the only path through
+ * which an `ipfs://` URL is ever assembled inside core; the
+ * type system + the `requireParsedCid` guard (which re-parses
+ * via `CID.parse`) reject any other input shape. The full
+ * security contract is in `retriever.ts`'s file header.
+ *
+ * File split (lifecycle helpers + vendor seam are siblings):
+ *
+ *   - `verified-fetch-vendor.ts` — vendor minimal types +
+ *     `loadAndCreateVerifiedFetch` (sanitised import + create
+ *     boundary, maps `ERR_MODULE_NOT_FOUND` →
+ *     `verified_fetch_unsupported`, vendor throws →
+ *     `verified_fetch_failed`).
+ *   - `verified-fetch-lifecycle.ts` — `startLifecycle`,
+ *     `runBoundedRetrieval`, body-reading helpers,
+ *     `requireParsedCid`, `mapVerifiedFetchFailure`.
+ *   - This file — the `FilecoinRetriever`-implementing class.
+ *
+ * Source-build invariant. The production build path
+ * (`tsc -p tsconfig.build.json` / `npm run build`) compiles
+ * WITHOUT the `optionalDependencies` graph present. The
+ * vendor module is reached only via a runtime
+ * `await import(VENDOR_VERIFIED_FETCH)` inside
+ * `verified-fetch-vendor.ts`; no production source statically
+ * imports `@helia/verified-fetch`.
+ *
+ * Lifecycle. Every `get` call creates a fresh fetch handle,
+ * awaits the response inside one `Promise.race` against the
+ * timeout sentinel, and tears the handle down in `finally`.
+ * The implementation never reuses a handle across calls.
+ */
+import type { CID } from 'multiformats/cid';
+import type { FilecoinRetriever, RetrieverGetOptions, RetrieverGetResult } from './retriever.js';
+export interface VerifiedFetchRetrieverOptions {
+    /**
+     * Bytes ceiling for a single retrieval. Defaults to 100 MiB —
+     * roughly the largest object AtomicMemory has reason to fetch
+     * from IPFS today. Set lower in tests or in operator
+     * deployments with stricter memory budgets.
+     */
+    readonly maxBodyBytes?: number;
+}
+export declare class VerifiedFetchRetriever implements FilecoinRetriever {
+    private readonly maxBodyBytes;
+    constructor(options?: VerifiedFetchRetrieverOptions);
+    get(ipfsCid: CID, options?: RetrieverGetOptions): Promise<RetrieverGetResult>;
+}

package/dist/storage/providers/filecoin/verified-fetch-retriever.js

@@ -0,0 +1,81 @@
+/**
+ * @file Verified-fetch retriever — Phase 6 experimental
+ * `FilecoinRetriever` implementation backed by
+ * `@helia/verified-fetch`.
+ *
+ * The retriever takes a parsed `CID` (never a URL) and
+ * constructs the canonical `ipfs://<cid>` form internally before
+ * handing it to verified-fetch. This is the only path through
+ * which an `ipfs://` URL is ever assembled inside core; the
+ * type system + the `requireParsedCid` guard (which re-parses
+ * via `CID.parse`) reject any other input shape. The full
+ * security contract is in `retriever.ts`'s file header.
+ *
+ * File split (lifecycle helpers + vendor seam are siblings):
+ *
+ *   - `verified-fetch-vendor.ts` — vendor minimal types +
+ *     `loadAndCreateVerifiedFetch` (sanitised import + create
+ *     boundary, maps `ERR_MODULE_NOT_FOUND` →
+ *     `verified_fetch_unsupported`, vendor throws →
+ *     `verified_fetch_failed`).
+ *   - `verified-fetch-lifecycle.ts` — `startLifecycle`,
+ *     `runBoundedRetrieval`, body-reading helpers,
+ *     `requireParsedCid`, `mapVerifiedFetchFailure`.
+ *   - This file — the `FilecoinRetriever`-implementing class.
+ *
+ * Source-build invariant. The production build path
+ * (`tsc -p tsconfig.build.json` / `npm run build`) compiles
+ * WITHOUT the `optionalDependencies` graph present. The
+ * vendor module is reached only via a runtime
+ * `await import(VENDOR_VERIFIED_FETCH)` inside
+ * `verified-fetch-vendor.ts`; no production source statically
+ * imports `@helia/verified-fetch`.
+ *
+ * Lifecycle. Every `get` call creates a fresh fetch handle,
+ * awaits the response inside one `Promise.race` against the
+ * timeout sentinel, and tears the handle down in `finally`.
+ * The implementation never reuses a handle across calls.
+ */
+import { loadAndCreateVerifiedFetch, } from './verified-fetch-vendor.js';
+import { mapVerifiedFetchFailure, requireParsedCid, runBoundedRetrieval, startLifecycle, } from './verified-fetch-lifecycle.js';
+/** Upper bound on what we'll consume from a single retrieval response. */
+const DEFAULT_MAX_BODY_BYTES = 100 * 1024 * 1024;
+export class VerifiedFetchRetriever {
+    maxBodyBytes;
+    constructor(options = {}) {
+        this.maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+    }
+    async get(ipfsCid, options = {}) {
+        const canonical = requireParsedCid(ipfsCid);
+        const url = `ipfs://${canonical}`;
+        const lifecycle = startLifecycle(options.timeoutMs);
+        let fetch = null;
+        try {
+            fetch = await loadAndCreateVerifiedFetch();
+            const bytes = await runBoundedRetrieval({
+                fetch, url, maxBytes: this.maxBodyBytes,
+                signal: lifecycle.aborter?.signal,
+                timeoutRejection: lifecycle.timeoutRejection,
+            });
+            return { body: bytes, ipfsCid: canonical };
+        }
+        catch (err) {
+            throw mapVerifiedFetchFailure(err, lifecycle.aborter, options.timeoutMs);
+        }
+        finally {
+            lifecycle.cancel();
+            // Tear the verified-fetch handle down on every path. Swallow
+            // any cleanup error so the original failure (if any) is
+            // what surfaces to the caller.
+            if (fetch !== null) {
+                try {
+                    await fetch.stop();
+                }
+                catch {
+                    // intentionally suppressed — cleanup must not mask the
+                    // primary error.
+                }
+            }
+        }
+    }
+}

package/dist/storage/providers/filecoin/verified-fetch-vendor.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file Vendor-boundary helpers for the verified-fetch retriever.
+ *
+ * Owns the surface that crosses from our code into
+ * `@helia/verified-fetch`. The split exists so
+ * `verified-fetch-retriever.ts` stays focused on the
+ * `FilecoinRetriever` implementation while this file owns the
+ * closed minimal type aliases that mirror the bits of the vendor
+ * shape we consume, plus the sanitized load + create helpers.
+ *
+ * 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 `@helia/verified-fetch`. Every shape we consume is
+ *      defined locally so `tsc` never has to resolve the vendor
+ *      type declarations.
+ *
+ *   2. **Non-literal dynamic-import specifier.** The
+ *      `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`) compiles
+ *      cleanly even though the optional module is absent.
+ *
+ * `loadAndCreateVerifiedFetch` is the single sanitisation seam
+ * for both the import failure and the construct failure — see
+ * `retriever.ts`'s file-header error-code table for the closed
+ * mapping.
+ */
+/**
+ * Local minimal mirror of the `@helia/verified-fetch` callable
+ * surface. The runtime instance is richer; we narrow to the
+ * closed set our code actually consumes.
+ */
+export interface MinimalVerifiedFetch {
+    (resource: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    stop(): Promise<void>;
+}
+export interface MinimalCreateVerifiedFetch {
+    (init?: {
+        allowLocal?: boolean;
+        allowInsecure?: boolean;
+    }): Promise<MinimalVerifiedFetch>;
+}
+/**
+ * Load the vendor module AND construct a fetch handle, mapping
+ * every failure mode to a sanitized closed `errorCode`:
+ *
+ *   - Missing optional package (`ERR_MODULE_NOT_FOUND`) →
+ *     `verified_fetch_unsupported`. This is the expected failure
+ *     on a synapse-only install
+ *     (`npm ci --legacy-peer-deps --omit=optional`); operators
+ *     surface it through the closed code rather than seeing a
+ *     raw `Cannot find module '@helia/verified-fetch'` Node
+ *     error.
+ *   - Any other load failure → `verified_fetch_failed`.
+ *   - Vendor `createVerifiedFetch({...})` throw →
+ *     `verified_fetch_failed`. Raw vendor messages do NOT cross
+ *     the boundary.
+ *
+ * Pinned: `allowLocal: false`, `allowInsecure: false`. Vendor
+ * defaults today, but pinning prevents a future vendor flip
+ * from silently letting us connect to loopback / HTTP gateways.
+ */
+export declare function loadAndCreateVerifiedFetch(): Promise<MinimalVerifiedFetch>;

package/dist/storage/providers/filecoin/verified-fetch-vendor.js

@@ -0,0 +1,94 @@
+/**
+ * @file Vendor-boundary helpers for the verified-fetch retriever.
+ *
+ * Owns the surface that crosses from our code into
+ * `@helia/verified-fetch`. The split exists so
+ * `verified-fetch-retriever.ts` stays focused on the
+ * `FilecoinRetriever` implementation while this file owns the
+ * closed minimal type aliases that mirror the bits of the vendor
+ * shape we consume, plus the sanitized load + create helpers.
+ *
+ * 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 `@helia/verified-fetch`. Every shape we consume is
+ *      defined locally so `tsc` never has to resolve the vendor
+ *      type declarations.
+ *
+ *   2. **Non-literal dynamic-import specifier.** The
+ *      `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`) compiles
+ *      cleanly even though the optional module is absent.
+ *
+ * `loadAndCreateVerifiedFetch` is the single sanitisation seam
+ * for both the import failure and the construct failure — see
+ * `retriever.ts`'s file-header error-code table for the closed
+ * mapping.
+ */
+import { FilecoinProviderError } from './errors.js';
+// Specifier stored as a `const` so `tsc` does not statically
+// resolve the optional module — same pattern as the Phase 5
+// `filecoin-pin-vendor.ts` loaders.
+const VENDOR_VERIFIED_FETCH = '@helia/verified-fetch';
+async function loadCreateVerifiedFetch() {
+    const mod = (await import(VENDOR_VERIFIED_FETCH));
+    return mod.createVerifiedFetch;
+}
+/**
+ * Load the vendor module AND construct a fetch handle, mapping
+ * every failure mode to a sanitized closed `errorCode`:
+ *
+ *   - Missing optional package (`ERR_MODULE_NOT_FOUND`) →
+ *     `verified_fetch_unsupported`. This is the expected failure
+ *     on a synapse-only install
+ *     (`npm ci --legacy-peer-deps --omit=optional`); operators
+ *     surface it through the closed code rather than seeing a
+ *     raw `Cannot find module '@helia/verified-fetch'` Node
+ *     error.
+ *   - Any other load failure → `verified_fetch_failed`.
+ *   - Vendor `createVerifiedFetch({...})` throw →
+ *     `verified_fetch_failed`. Raw vendor messages do NOT cross
+ *     the boundary.
+ *
+ * Pinned: `allowLocal: false`, `allowInsecure: false`. Vendor
+ * defaults today, but pinning prevents a future vendor flip
+ * from silently letting us connect to loopback / HTTP gateways.
+ */
+export async function loadAndCreateVerifiedFetch() {
+    let create;
+    try {
+        create = await loadCreateVerifiedFetch();
+    }
+    catch (err) {
+        if (isModuleNotFound(err)) {
+            throw new FilecoinProviderError('verified_fetch_unsupported', 'verified-fetch retriever is unavailable: the @helia/verified-fetch optional package is not installed.');
+        }
+        throw new FilecoinProviderError('verified_fetch_failed', 'verified-fetch retriever failed to load.');
+    }
+    try {
+        return await create({ allowLocal: false, allowInsecure: false });
+    }
+    catch (err) {
+        // Treat `ERR_MODULE_NOT_FOUND` from the construction path
+        // the same as from the import itself — both signal a missing
+        // (transitive) optional dependency, which is the
+        // `verified_fetch_unsupported` outcome operators care about.
+        // Any other vendor throw is the generic `verified_fetch_failed`.
+        if (isModuleNotFound(err)) {
+            throw new FilecoinProviderError('verified_fetch_unsupported', 'verified-fetch retriever is unavailable: a required optional dependency is not installed.');
+        }
+        throw new FilecoinProviderError('verified_fetch_failed', 'verified-fetch retriever failed to initialize.');
+    }
+}
+function isModuleNotFound(err) {
+    if (err === null || typeof err !== 'object')
+        return false;
+    const code = err.code;
+    return code === 'ERR_MODULE_NOT_FOUND' || code === 'MODULE_NOT_FOUND';
+}

package/dist/storage/raw-content-codec.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Content-codec layer that sits between the upload service and the
+ * raw-content adapter (`RawContentStore`). A codec transforms the bytes
+ * the caller asked us to store into the bytes the adapter actually
+ * writes (`encode`), and is the inverse on read (`decode`).
+ *
+ * The motivating use case is Filecoin / IPFS, where the URI is
+ * content-addressed: any third party who guesses or learns the CID can
+ * pull the bytes from a public gateway. Plaintext storage there leaks
+ * user data; encrypting at this layer means the CID commits to
+ * ciphertext, while AtomicMemory still hashes the user's plaintext for
+ * its own `raw_documents.content_hash` invariants.
+ *
+ * The codec also serves immediate providers (`local_fs`, `s3`) when an
+ * operator wants encryption at rest above what the provider already
+ * offers. The interface is unchanged — only the metadata sidecar (`name`,
+ * `key_id`, `nonce`, `tag` for AES-GCM) tells the read path how to
+ * reverse the transform.
+ *
+ * Keyring model: encode picks the operator-selected ACTIVE key; decode
+ * reads `key_id` from the metadata and finds THAT key in the configured
+ * ring. Operators rotate by adding a new key + flipping the active id —
+ * old rows keep decoding via their stored `key_id`. Missing keys fail
+ * loud (never silently fall back).
+ */
+/** Codec name carried in `raw_storage_metadata.codec.name`. */
+export type RawContentCodecName = 'none' | 'aes_gcm';
+/** Public, allowlisted codec metadata projected to the wire. */
+export interface PublicRawContentCodecMetadata {
+    name: RawContentCodecName;
+    version: number;
+}
+/**
+ * Internal codec metadata persisted on `raw_storage_metadata.codec`. The
+ * AES-GCM codec also writes `key_id`, `nonce`, `tag`, and optionally
+ * `encoded_content_hash` + `encoded_size_bytes` (rev-2 §5 — ops
+ * diagnostics). `formatPublicMetadata` strips everything except the
+ * `name` + `version` fields when emitting to the wire.
+ */
+export interface InternalRawContentCodecMetadata extends PublicRawContentCodecMetadata {
+    key_id?: string;
+    nonce?: string;
+    tag?: string;
+    encoded_content_hash?: string;
+    encoded_size_bytes?: number;
+}
+export interface RawContentCodecEncodeInput {
+    /** Plaintext bytes the caller asked us to store. */
+    body: Buffer;
+}
+export interface RawContentCodecEncodeResult {
+    /** Bytes the adapter actually writes (ciphertext for `aes_gcm`). */
+    body: Buffer;
+    /** Internal sidecar; the upload service merges this under `raw_storage_metadata.codec`. */
+    metadata: InternalRawContentCodecMetadata;
+}
+export interface RawContentCodecDecodeInput {
+    /** Bytes the adapter returned (ciphertext for `aes_gcm`). */
+    body: Buffer;
+    /** Sidecar read from `raw_storage_metadata.codec`. */
+    metadata: InternalRawContentCodecMetadata;
+}
+export interface RawContentCodecDecodeResult {
+    /** Plaintext bytes the original caller asked us to store. */
+    body: Buffer;
+}
+/**
+ * Codec interface. Implementations are stateless and must not mutate
+ * the input buffer.
+ */
+export interface RawContentCodec {
+    readonly name: RawContentCodecName;
+    encode(input: RawContentCodecEncodeInput): Promise<RawContentCodecEncodeResult>;
+    decode(input: RawContentCodecDecodeInput): Promise<RawContentCodecDecodeResult>;
+}
+/** Thrown for any codec-layer failure (bad input, tamper, key missing). */
+export declare class RawContentCodecError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when `decode` reads a `key_id` that is not present in the
+ * configured keyring. Loud-fail per the no-fallback policy — operators
+ * must restore the key (or accept that the row's bytes are
+ * unrecoverable) rather than the codec silently skipping.
+ */
+export declare class RawContentCodecKeyNotFoundError extends RawContentCodecError {
+    readonly keyId: string;
+    constructor(keyId: string);
+}

package/dist/storage/raw-content-codec.js

@@ -0,0 +1,47 @@
+/**
+ * Content-codec layer that sits between the upload service and the
+ * raw-content adapter (`RawContentStore`). A codec transforms the bytes
+ * the caller asked us to store into the bytes the adapter actually
+ * writes (`encode`), and is the inverse on read (`decode`).
+ *
+ * The motivating use case is Filecoin / IPFS, where the URI is
+ * content-addressed: any third party who guesses or learns the CID can
+ * pull the bytes from a public gateway. Plaintext storage there leaks
+ * user data; encrypting at this layer means the CID commits to
+ * ciphertext, while AtomicMemory still hashes the user's plaintext for
+ * its own `raw_documents.content_hash` invariants.
+ *
+ * The codec also serves immediate providers (`local_fs`, `s3`) when an
+ * operator wants encryption at rest above what the provider already
+ * offers. The interface is unchanged — only the metadata sidecar (`name`,
+ * `key_id`, `nonce`, `tag` for AES-GCM) tells the read path how to
+ * reverse the transform.
+ *
+ * Keyring model: encode picks the operator-selected ACTIVE key; decode
+ * reads `key_id` from the metadata and finds THAT key in the configured
+ * ring. Operators rotate by adding a new key + flipping the active id —
+ * old rows keep decoding via their stored `key_id`. Missing keys fail
+ * loud (never silently fall back).
+ */
+/** Thrown for any codec-layer failure (bad input, tamper, key missing). */
+export class RawContentCodecError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RawContentCodecError';
+    }
+}
+/**
+ * Thrown when `decode` reads a `key_id` that is not present in the
+ * configured keyring. Loud-fail per the no-fallback policy — operators
+ * must restore the key (or accept that the row's bytes are
+ * unrecoverable) rather than the codec silently skipping.
+ */
+export class RawContentCodecKeyNotFoundError extends RawContentCodecError {
+    keyId;
+    constructor(keyId) {
+        super(`Codec key '${keyId}' is not configured in RAW_CONTENT_CODEC_KEYS. ` +
+            'The decode cannot proceed; restore the key or treat the row as unrecoverable.');
+        this.name = 'RawContentCodecKeyNotFoundError';
+        this.keyId = keyId;
+    }
+}

package/dist/storage/raw-content-store-backend-adapter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @file Adapter exposing an existing `RawContentStore` as a `StorageBackend`.
+ *
+ * Step 5 of the storage-sibling plan — adapter, not rewrite. The
+ * existing `local_fs`, `s3`, and (excluded-from-direct-uploads)
+ * `filecoin` adapters keep their `RawContentStore` shape; this
+ * adapter narrows their surface to the smaller `StorageBackend`
+ * contract the storage service depends on.
+ *
+ * Hash semantics for v1 direct API:
+ *   * `local_fs` / `s3` write identity-codec bytes — `plaintextHash`
+ *     equals `storedHash` and equals the adapter's returned
+ *     `contentHash` (SHA-256 of the bytes the adapter persisted).
+ *   * `filecoin` direct managed upload is 501 in v1 and never
+ *     reaches this adapter, so we do NOT need to model ciphertext
+ *     hash divergence here.
+ */
+import type { RawContentStore } from './raw-content-store.js';
+import type { DeleteBackendResult, GetBackendResult, HeadBackendResult, PutBackendInput, PutBackendResult, StorageBackend } from './storage-backend.js';
+export declare class RawContentStoreBackendAdapter implements StorageBackend {
+    readonly provider: string;
+    private readonly store;
+    constructor(store: RawContentStore);
+    put(input: PutBackendInput): Promise<PutBackendResult>;
+    get(uri: string): Promise<GetBackendResult>;
+    head(uri: string): Promise<HeadBackendResult>;
+    delete(uri: string): Promise<DeleteBackendResult>;
+}

package/dist/storage/raw-content-store-backend-adapter.js

@@ -0,0 +1,67 @@
+/**
+ * @file Adapter exposing an existing `RawContentStore` as a `StorageBackend`.
+ *
+ * Step 5 of the storage-sibling plan — adapter, not rewrite. The
+ * existing `local_fs`, `s3`, and (excluded-from-direct-uploads)
+ * `filecoin` adapters keep their `RawContentStore` shape; this
+ * adapter narrows their surface to the smaller `StorageBackend`
+ * contract the storage service depends on.
+ *
+ * Hash semantics for v1 direct API:
+ *   * `local_fs` / `s3` write identity-codec bytes — `plaintextHash`
+ *     equals `storedHash` and equals the adapter's returned
+ *     `contentHash` (SHA-256 of the bytes the adapter persisted).
+ *   * `filecoin` direct managed upload is 501 in v1 and never
+ *     reaches this adapter, so we do NOT need to model ciphertext
+ *     hash divergence here.
+ */
+export class RawContentStoreBackendAdapter {
+    provider;
+    store;
+    constructor(store) {
+        this.store = store;
+        this.provider = store.provider;
+    }
+    async put(input) {
+        const stored = await this.store.put({
+            key: input.key,
+            body: input.body,
+            contentType: input.contentType,
+        });
+        return {
+            uri: stored.storageUri,
+            sizeBytes: stored.sizeBytes,
+            // v1 direct API runs identity codec only (Filecoin is 501);
+            // the adapter's returned `contentHash` is the SHA-256 of the
+            // exact bytes the caller passed.
+            plaintextHash: stored.contentHash,
+            storedHash: stored.contentHash,
+            providerMetadata: stored.providerMetadata,
+        };
+    }
+    async get(uri) {
+        const result = await this.store.get(uri);
+        return {
+            body: result.body,
+            contentType: result.metadata.contentType,
+            sizeBytes: result.metadata.contentLength,
+        };
+    }
+    async head(uri) {
+        const result = await this.store.head(uri);
+        return {
+            exists: result.exists,
+            sizeBytes: extractContentLength(result.metadata),
+            contentType: result.metadata?.contentType ?? null,
+        };
+    }
+    async delete(uri) {
+        const result = await this.store.delete(uri);
+        return { deleted: result.deleted, semantics: result.semantics };
+    }
+}
+function extractContentLength(metadata) {
+    if (metadata === null)
+        return null;
+    return metadata.contentLength;
+}