@parity/product-sdk-cloud-storage 0.5.0

package/src/index.ts

@@ -0,0 +1,107 @@
+/**
+ * @parity/product-sdk-cloud-storage — Upload and retrieve content from the cloud
+ * (currently through the Polkadot Bulletin Chain).
+ *
+ * Wraps `@parity/bulletin-sdk` (chunking, DAG-PB manifests, CID calculation,
+ * progress events) and adds:
+ *
+ * - **Network presets** via {@link CloudStorageNetworks}
+ * - **Read helpers** ({@link CloudStorageClient.fetchBytes} /
+ *   {@link CloudStorageClient.fetchJson})
+ * - **Authorization pre-flight** via {@link checkAuthorization}
+ *
+ * @packageDocumentation
+ */
+
+export { CloudStorageClient } from "./client.js";
+export type { CreateCloudStorageClientOptions } from "./client.js";
+export { CloudStorageNetworks } from "./networks.js";
+export type { CloudStorageEnvironment, CloudStorageNetwork } from "./networks.js";
+export { authorizeAccount, checkAuthorization } from "./authorization.js";
+export type { AuthorizeAccountOptions } from "./authorization.js";
+export { createLazySigner } from "./lazy-signer.js";
+export { executeQuery, queryBytes, queryJson } from "./query.js";
+export { resolveQueryStrategy } from "./resolve-query.js";
+export type { QueryStrategy } from "./resolve-query.js";
+export { verifyStored } from "./verify.js";
+export type { ChainStoredEntry, VerifyStoredOptions } from "./verify.js";
+export {
+    cidToPreimageKey,
+    hashToCid,
+    HashAlgorithm,
+    CidCodec,
+} from "./cid.js";
+
+// Errors — abstracted CloudStorage* family plus the upstream `BulletinError` /
+// `ErrorCode` re-exports for callers that need to catch upstream failures
+// specifically.
+export {
+    BulletinError,
+    ErrorCode,
+    ProductCloudStorageError,
+    CloudStorageAuthorizationError,
+    CloudStorageCidError,
+    CloudStorageHostUnavailableError,
+    CloudStorageLookupInterruptedError,
+    CloudStorageLookupTimeoutError,
+} from "./errors.js";
+
+// Types
+export type {
+    AuthorizationStatus,
+    CloudStorageApi,
+    Environment,
+    QueryOptions,
+} from "./types.js";
+
+// Re-exports from upstream `@parity/bulletin-sdk` — surfaced for power users
+// + so consumers don't need a separate `@parity/bulletin-sdk` import.
+export {
+    AsyncBulletinClient,
+    BulletinPreparer,
+    AuthCallBuilder,
+    CallBuilder,
+    StoreBuilder,
+    MockBulletinClient,
+    AuthorizationScope,
+    ChunkStatus,
+    TxStatus,
+    WaitFor,
+    MAX_CHUNK_SIZE,
+    MAX_FILE_SIZE,
+    DEFAULT_CHUNKER_CONFIG,
+    DEFAULT_CLIENT_CONFIG,
+    DEFAULT_STORE_OPTIONS,
+    calculateCid,
+    cidFromBytes,
+    cidToBytes,
+    convertCid,
+    estimateAuthorization,
+    getContentHash,
+    parseCid,
+    reassembleChunks,
+    resolveClientConfig,
+    validateChunkSize,
+    CID,
+} from "@parity/bulletin-sdk";
+
+export type {
+    BulletinClientInterface,
+    BulletinTypedApi,
+    Chunk,
+    ChunkDetails,
+    ChunkProgressEvent,
+    ChunkedStoreResult,
+    ChunkerConfig,
+    ClientConfig,
+    DagManifest,
+    MockClientConfig,
+    MockOperation,
+    ProgressCallback,
+    ProgressEvent,
+    StoreOptions,
+    StoreResult,
+    SubmitFn,
+    TransactionReceipt,
+    TransactionStatusEvent,
+} from "@parity/bulletin-sdk";

package/src/lazy-signer.ts

@@ -0,0 +1,113 @@
+import type { PolkadotSigner } from "polkadot-api";
+
+/**
+ * Build a `PolkadotSigner` whose underlying signer is resolved on every call.
+ *
+ * `AsyncBulletinClient` takes a fixed `PolkadotSigner` at construction, but
+ * apps often build the Cloud Storage client before any account is selected. This
+ * wrapper defers signer resolution: each call to `signTx` / `signBytes`
+ * invokes `getSigner()` and forwards to the result. If the getter returns
+ * `null`, calls throw with a clear message.
+ *
+ * The `publicKey` field is *also* resolved lazily — accessing it before a
+ * signer is available throws. This means callers that read `publicKey`
+ * eagerly will fail fast with the same error rather than seeing a stale
+ * key from a previously-selected account.
+ *
+ * Account changes between calls are picked up automatically: each sign
+ * resolves the current signer.
+ */
+export function createLazySigner(
+    getSigner: () => PolkadotSigner | null,
+    onMissing = "No signer available — connect a wallet and select an account first.",
+): PolkadotSigner {
+    const resolve = (): PolkadotSigner => {
+        const inner = getSigner();
+        if (!inner) throw new Error(onMissing);
+        return inner;
+    };
+
+    // `async` on the methods is deliberate: it converts a "no signer" throw
+    // from `resolve()` into a rejected Promise. PolkadotSigner.signTx /
+    // signBytes are typed as returning Promises, and consumers expect a
+    // rejection rather than a synchronous escape on the failure path.
+    const lazy: PolkadotSigner = {
+        get publicKey() {
+            return resolve().publicKey;
+        },
+        signTx: async (...args: Parameters<PolkadotSigner["signTx"]>) => resolve().signTx(...args),
+        signBytes: async (...args: Parameters<PolkadotSigner["signBytes"]>) =>
+            resolve().signBytes(...args),
+    };
+    return lazy;
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect, vi } = import.meta.vitest;
+
+    function makeMockSigner(label: string): PolkadotSigner {
+        return {
+            publicKey: new TextEncoder().encode(label),
+            signTx: vi.fn().mockResolvedValue(new Uint8Array([1])),
+            signBytes: vi.fn().mockResolvedValue(new Uint8Array([2])),
+        };
+    }
+
+    describe("createLazySigner", () => {
+        test("publicKey throws when getter returns null", () => {
+            const lazy = createLazySigner(() => null);
+            expect(() => lazy.publicKey).toThrow("No signer available");
+        });
+
+        test("publicKey resolves through getter when signer is available", () => {
+            const inner = makeMockSigner("alice");
+            const lazy = createLazySigner(() => inner);
+            expect(lazy.publicKey).toBe(inner.publicKey);
+        });
+
+        test("signTx throws when getter returns null", async () => {
+            const lazy = createLazySigner(() => null);
+            await expect(lazy.signTx(new Uint8Array(), {}, new Uint8Array(), 0)).rejects.toThrow(
+                "No signer available",
+            );
+        });
+
+        test("signTx forwards to current signer", async () => {
+            const inner = makeMockSigner("alice");
+            const lazy = createLazySigner(() => inner);
+            const callData = new Uint8Array([0xaa, 0xbb]);
+            const signedExtensions = {};
+            const metadata = new Uint8Array([0xcc]);
+            const atBlock = 42;
+            const result = await lazy.signTx(callData, signedExtensions, metadata, atBlock);
+            expect(inner.signTx).toHaveBeenCalledWith(
+                callData,
+                signedExtensions,
+                metadata,
+                atBlock,
+            );
+            expect(result).toEqual(new Uint8Array([1]));
+        });
+
+        test("signBytes forwards to current signer", async () => {
+            const inner = makeMockSigner("bob");
+            const lazy = createLazySigner(() => inner);
+            const result = await lazy.signBytes(new Uint8Array([9]));
+            expect(inner.signBytes).toHaveBeenCalledWith(new Uint8Array([9]));
+            expect(result).toEqual(new Uint8Array([2]));
+        });
+
+        test("picks up account changes between calls", () => {
+            let active: PolkadotSigner | null = makeMockSigner("first");
+            const lazy = createLazySigner(() => active);
+            expect(lazy.publicKey).toEqual(new TextEncoder().encode("first"));
+            active = makeMockSigner("second");
+            expect(lazy.publicKey).toEqual(new TextEncoder().encode("second"));
+        });
+
+        test("custom error message", () => {
+            const lazy = createLazySigner(() => null, "select an account first");
+            expect(() => lazy.publicKey).toThrow("select an account first");
+        });
+    });
+}

package/src/networks.ts

@@ -0,0 +1,47 @@
+/**
+ * Known Cloud Storage networks.
+ *
+ * Each environment pairs its genesis hash with a per-environment PAPI descriptor.
+ */
+import { paseo_bulletin as paseoBulletinDescriptor } from "@parity/product-sdk-descriptors/paseo-bulletin";
+
+export interface CloudStorageNetwork {
+    /** Genesis hash of the underlying chain on this environment. */
+    genesisHash: `0x${string}`;
+    /** PAPI descriptor for typed API access. */
+    descriptor: typeof paseoBulletinDescriptor;
+}
+
+/**
+ * Cloud Storage network presets.
+ *
+ * Use these with {@link CloudStorageClient.create} when you want to be explicit
+ * about the network rather than passing an environment string. Reads go
+ * through the host's preimage subscription (container-only); no gateway
+ * URL is configured per network.
+ */
+export const CloudStorageNetworks = {
+    paseo: {
+        genesisHash: "0x8cfe6717dc4becfda2e13c488a1e2061ff2dfee96e7d031157f72d36716c0a22",
+        descriptor: paseoBulletinDescriptor,
+    },
+} as const satisfies Record<string, CloudStorageNetwork>;
+
+/** Network keys with built-in presets in {@link CloudStorageNetworks}. */
+export type CloudStorageEnvironment = keyof typeof CloudStorageNetworks;
+
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+
+    describe("CloudStorageNetworks", () => {
+        test("paseo has a valid genesis hash", () => {
+            expect(CloudStorageNetworks.paseo.genesisHash).toMatch(/^0x[a-f0-9]{64}$/);
+        });
+
+        test("paseo descriptor has matching genesis", () => {
+            expect(CloudStorageNetworks.paseo.descriptor.genesis).toBe(
+                CloudStorageNetworks.paseo.genesisHash,
+            );
+        });
+    });
+}

package/src/query.ts

@@ -0,0 +1,216 @@
+import { CidCodec, parseCid, UnixFsDagBuilder } from "@parity/bulletin-sdk";
+import { createLogger } from "@parity/product-sdk-logger";
+
+import type { QueryStrategy } from "./resolve-query.js";
+import { resolveQueryStrategy } from "./resolve-query.js";
+import type { QueryOptions } from "./types.js";
+
+const log = createLogger("bulletin");
+
+/**
+ * Fetch raw bytes for a CID via the host's preimage lookup.
+ *
+ * Container-only by design: the Cloud Storage SDK does not retrieve content
+ * through public IPFS gateways. Inside a Polkadot Browser / Desktop
+ * container, the host's `preimageManager` provides a cached, polling-
+ * managed lookup that returns bytes when the underlying IPFS network
+ * makes them available. Outside a container, this throws
+ * {@link CloudStorageHostUnavailableError}.
+ *
+ * The underlying chain stores transaction *metadata* on-chain
+ * (`chunk_root`, `content_hash`, `size`, `cid_codec`, `hashing`) — the
+ * content bytes themselves live in IPFS and are surfaced through the
+ * host's preimage subscription, never via direct gateway fetch.
+ *
+ * To prove that a CID was stored on-chain (without fetching the bytes),
+ * use `verifyStored` from `verify.ts`.
+ *
+ * @param cid     - CIDv1 string to fetch.
+ * @param options - Query options (`lookupTimeoutMs` for host).
+ * @throws {CloudStorageHostUnavailableError} If running outside a container.
+ */
+export async function queryBytes(cid: string, options?: QueryOptions): Promise<Uint8Array> {
+    const strategy = await resolveQueryStrategy();
+    return executeQuery(strategy, cid, options);
+}
+
+/**
+ * Fetch and parse JSON for a CID via the host's preimage lookup.
+ *
+ * Convenience wrapper over {@link queryBytes}.
+ */
+export async function queryJson<T>(cid: string, options?: QueryOptions): Promise<T> {
+    const bytes = await queryBytes(cid, options);
+    return JSON.parse(new TextDecoder().decode(bytes)) as T;
+}
+
+/**
+ * Execute a query using a pre-resolved strategy.
+ *
+ * Exposed so `CloudStorageClient` can resolve the strategy once at
+ * construction time and reuse it across calls without re-detecting
+ * the host environment on every fetch.
+ *
+ * **Reassembly is automatic.** If `cid` carries the DAG-PB codec
+ * (`0x70`) — meaning the upload was chunked and a UnixFS manifest was
+ * created — this function recursively fetches each chunk via `strategy
+ * .lookup` and returns the concatenated bytes. Pass `noReassemble: true`
+ * to get the raw manifest bytes instead.
+ *
+ * For raw-codec CIDs (`0x55`, single-chunk content), the bytes returned
+ * by the host are returned directly — no parsing overhead.
+ */
+export async function executeQuery(
+    strategy: QueryStrategy,
+    cid: string,
+    options?: QueryOptions,
+): Promise<Uint8Array> {
+    log.info("query: host preimage lookup", { cid });
+    const bytes = await strategy.lookup(cid, options?.lookupTimeoutMs);
+
+    // Skip reassembly when the caller explicitly asks for raw bytes, or
+    // when the CID's codec says this is a single-block payload (raw,
+    // 0x55) — most uploads land here, so the parseCid + Promise.all
+    // overhead is worth gating on codec rather than always paying it.
+    if (options?.noReassemble) return bytes;
+    const parsed = parseCid(cid);
+    if (parsed.code !== CidCodec.DagPb) return bytes;
+
+    log.info("query: reassembling DAG-PB manifest", { cid });
+    const builder = new UnixFsDagBuilder();
+    const { chunkCids } = await builder.parse(bytes);
+
+    // Fetch chunks in parallel — the host's preimageManager caches and
+    // dedupes lookups, and order is preserved by Promise.all's input
+    // ordering, which matches the DAG-PB Links order from parse().
+    const chunks = await Promise.all(
+        chunkCids.map((c) => strategy.lookup(c.toString(), options?.lookupTimeoutMs)),
+    );
+
+    let total = 0;
+    for (const chunk of chunks) total += chunk.length;
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+
+if (import.meta.vitest) {
+    const { beforeAll, describe, test, expect, vi } = import.meta.vitest;
+    const { calculateCid } = await import("@parity/bulletin-sdk");
+
+    describe("executeQuery", () => {
+        const testData = new Uint8Array([1, 2, 3]);
+
+        test("delegates to the strategy's lookup function", async () => {
+            const lookup = vi.fn().mockResolvedValue(testData);
+            const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+            // Use a real raw-codec CID so the codec check passes through
+            // without triggering reassembly.
+            const rawCid = (await calculateCid(testData)).toString();
+            const result = await executeQuery(strategy, rawCid);
+            expect(result).toBe(testData);
+            expect(lookup).toHaveBeenCalledWith(rawCid, undefined);
+        });
+
+        test("forwards lookupTimeoutMs to the strategy", async () => {
+            const lookup = vi.fn().mockResolvedValue(testData);
+            const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+            const rawCid = (await calculateCid(testData)).toString();
+            await executeQuery(strategy, rawCid, { lookupTimeoutMs: 5000 });
+            expect(lookup).toHaveBeenCalledWith(rawCid, 5000);
+        });
+
+        test("returns raw bytes directly for raw-codec CIDs (no reassembly)", async () => {
+            const lookup = vi.fn().mockResolvedValue(testData);
+            const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+            const rawCid = (await calculateCid(testData)).toString();
+            const result = await executeQuery(strategy, rawCid);
+            expect(result).toBe(testData);
+            // Single lookup, no recursion.
+            expect(lookup).toHaveBeenCalledTimes(1);
+        });
+
+        test("noReassemble: true short-circuits even for DAG-PB CIDs", async () => {
+            // Manufacture a DAG-PB CID; we don't need the bytes to actually
+            // be a valid manifest because we're skipping the parse step.
+            const fakeManifestBytes = new Uint8Array([10, 20, 30]);
+            const dagPbCid = (await calculateCid(fakeManifestBytes, /* dag-pb */ 0x70)).toString();
+            const lookup = vi.fn().mockResolvedValue(fakeManifestBytes);
+            const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+            const result = await executeQuery(strategy, dagPbCid, { noReassemble: true });
+            expect(result).toBe(fakeManifestBytes);
+            expect(lookup).toHaveBeenCalledTimes(1);
+        });
+
+        describe("DAG-PB reassembly", () => {
+            // Build a real manifest: two raw chunks, dag-pb root.
+            const chunkA = new Uint8Array([0xaa, 0xaa, 0xaa]);
+            const chunkB = new Uint8Array([0xbb, 0xbb]);
+            let chunkACid: string;
+            let chunkBCid: string;
+            let manifestBytes: Uint8Array;
+            let manifestCid: string;
+
+            beforeAll(async () => {
+                const { UnixFsDagBuilder: Builder } = await import("@parity/bulletin-sdk");
+                chunkACid = (await calculateCid(chunkA)).toString();
+                chunkBCid = (await calculateCid(chunkB)).toString();
+                const cidA = await calculateCid(chunkA);
+                const cidB = await calculateCid(chunkB);
+                const manifest = await new Builder().build([
+                    { data: chunkA, cid: cidA, index: 0, totalChunks: 2 },
+                    { data: chunkB, cid: cidB, index: 1, totalChunks: 2 },
+                ]);
+                manifestBytes = manifest.dagBytes;
+                manifestCid = manifest.rootCid.toString();
+            });
+
+            test("recursively fetches chunks and concatenates", async () => {
+                const lookup = vi.fn(async (cid: string) => {
+                    if (cid === manifestCid) return manifestBytes;
+                    if (cid === chunkACid) return chunkA;
+                    if (cid === chunkBCid) return chunkB;
+                    throw new Error(`unexpected lookup: ${cid}`);
+                });
+                const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+                const result = await executeQuery(strategy, manifestCid);
+                expect(result).toEqual(new Uint8Array([0xaa, 0xaa, 0xaa, 0xbb, 0xbb]));
+                // 1 manifest + 2 chunks = 3 lookups.
+                expect(lookup).toHaveBeenCalledTimes(3);
+            });
+
+            test("forwards lookupTimeoutMs to every chunk lookup", async () => {
+                const lookup = vi.fn(async (cid: string, _timeoutMs?: number) => {
+                    if (cid === manifestCid) return manifestBytes;
+                    if (cid === chunkACid) return chunkA;
+                    if (cid === chunkBCid) return chunkB;
+                    throw new Error("boom");
+                });
+                const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+                await executeQuery(strategy, manifestCid, { lookupTimeoutMs: 7777 });
+                for (const call of lookup.mock.calls) {
+                    expect(call[1]).toBe(7777);
+                }
+            });
+
+            test("preserves chunk order from the manifest", async () => {
+                const lookup = vi.fn(async (cid: string) => {
+                    if (cid === manifestCid) return manifestBytes;
+                    if (cid === chunkACid) return chunkA;
+                    if (cid === chunkBCid) return chunkB;
+                    throw new Error("boom");
+                });
+                const strategy: QueryStrategy = { kind: "host-lookup", lookup };
+                const result = await executeQuery(strategy, manifestCid);
+                // Order matters: chunkA bytes must come before chunkB bytes
+                // even though both are fetched in parallel.
+                expect(Array.from(result.slice(0, 3))).toEqual([0xaa, 0xaa, 0xaa]);
+                expect(Array.from(result.slice(3))).toEqual([0xbb, 0xbb]);
+            });
+        });
+    });
+}

package/src/resolve-query.ts

@@ -0,0 +1,198 @@
+import { calculateCid } from "@parity/bulletin-sdk";
+import { getPreimageManager, type PreimageManager } from "@parity/product-sdk-host";
+import { createLogger } from "@parity/product-sdk-logger";
+
+import { cidToPreimageKey } from "./cid.js";
+import {
+    CloudStorageHostUnavailableError,
+    CloudStorageLookupInterruptedError,
+    CloudStorageLookupTimeoutError,
+} from "./errors.js";
+
+const log = createLogger("bulletin");
+
+const DEFAULT_LOOKUP_TIMEOUT_MS = 30_000;
+
+/**
+ * Query strategy for Cloud Storage retrieval.
+ *
+ * The host manages the lookup via its preimage subscription API,
+ * which includes local caching and managed IPFS polling.
+ */
+export interface QueryStrategy {
+    kind: "host-lookup";
+    lookup: (cid: string, timeoutMs?: number) => Promise<Uint8Array>;
+}
+
+/**
+ * Determine the query strategy for Cloud Storage retrieval.
+ *
+ * Uses the host preimage lookup API which caches results and manages
+ * IPFS polling automatically.
+ *
+ * @returns The resolved query strategy.
+ * @throws {CloudStorageHostUnavailableError} If the host preimage manager is unavailable.
+ */
+export async function resolveQueryStrategy(): Promise<QueryStrategy> {
+    const preimageManager = await getPreimageManager();
+    if (preimageManager) {
+        log.info("using host preimage lookup for Cloud Storage queries");
+        return {
+            kind: "host-lookup",
+            lookup: (cid, timeoutMs) => lookupViaHost(preimageManager, cid, timeoutMs),
+        };
+    }
+
+    throw new CloudStorageHostUnavailableError("query");
+}
+
+/**
+ * Wrap `preimageManager.lookup` (subscription-based) into a one-shot Promise.
+ *
+ * Converts the CID to a hex preimage key, subscribes, and resolves on the
+ * first non-null callback. Rejects on timeout or if the host interrupts the
+ * subscription (e.g. after repeated failures). Always unsubscribes on settlement.
+ *
+ * @param manager   - The product-sdk preimage manager.
+ * @param cid       - CIDv1 string to look up.
+ * @param timeoutMs - Maximum wait time. Default: 30_000ms.
+ * @returns The raw bytes of the preimage.
+ */
+export function lookupViaHost(
+    manager: PreimageManager,
+    cid: string,
+    timeoutMs: number = DEFAULT_LOOKUP_TIMEOUT_MS,
+): Promise<Uint8Array> {
+    const key = cidToPreimageKey(cid);
+
+    return new Promise<Uint8Array>((resolve, reject) => {
+        const cleanup = () => {
+            cancelInterrupt();
+            sub.unsubscribe();
+        };
+
+        const settle = (fn: () => void) => {
+            if (timer === null) return;
+            clearTimeout(timer);
+            timer = null;
+            cleanup();
+            fn();
+        };
+
+        let timer: ReturnType<typeof setTimeout> | null = setTimeout(() => {
+            settle(() => {
+                reject(new CloudStorageLookupTimeoutError(cid, timeoutMs));
+            });
+        }, timeoutMs);
+
+        const sub = manager.lookup(key, (preimage) => {
+            if (preimage !== null) {
+                settle(() => resolve(preimage));
+            }
+            // null means "not found yet" — host will keep polling
+        });
+
+        const cancelInterrupt = sub.onInterrupt(() => {
+            settle(() => {
+                reject(new CloudStorageLookupInterruptedError(cid));
+            });
+        });
+    });
+}
+
+if (import.meta.vitest) {
+    const { beforeAll, describe, test, expect, vi } = import.meta.vitest;
+
+    // Note: resolveQueryStrategy tests require e2e testing as they
+    // depend on the host container environment.
+
+    describe("lookupViaHost", () => {
+        function createMockManager(
+            behavior: "resolve" | "null-then-resolve" | "hang" | "interrupt",
+        ) {
+            const unsubscribe = vi.fn();
+            const cancelInterrupt = vi.fn();
+            let interruptCb: VoidFunction | undefined;
+
+            const lookup = vi.fn((_key: string, callback: (p: Uint8Array | null) => void) => {
+                const data = new Uint8Array([10, 20, 30]);
+                queueMicrotask(() => {
+                    if (behavior === "resolve") {
+                        callback(data);
+                    } else if (behavior === "null-then-resolve") {
+                        callback(null);
+                        queueMicrotask(() => callback(data));
+                    } else if (behavior === "interrupt") {
+                        interruptCb?.();
+                    }
+                    // "hang" does nothing
+                });
+                return {
+                    unsubscribe,
+                    onInterrupt: (cb: VoidFunction) => {
+                        interruptCb = cb;
+                        return cancelInterrupt;
+                    },
+                };
+            });
+
+            return { lookup, unsubscribe, cancelInterrupt, submit: vi.fn() };
+        }
+
+        // calculateCid is async (Web Crypto), so populate lazily.
+        let testCid: string;
+        beforeAll(async () => {
+            const cid = await calculateCid(new TextEncoder().encode("test"));
+            testCid = cid.toString();
+        });
+
+        test("resolves on first non-null callback", async () => {
+            const manager = createMockManager("resolve");
+            const result = await lookupViaHost(manager, testCid);
+            expect(result).toEqual(new Uint8Array([10, 20, 30]));
+        });
+
+        test("ignores null callbacks and resolves on subsequent data", async () => {
+            const manager = createMockManager("null-then-resolve");
+            const result = await lookupViaHost(manager, testCid);
+            expect(result).toEqual(new Uint8Array([10, 20, 30]));
+        });
+
+        test("rejects with CloudStorageLookupTimeoutError on timeout", async () => {
+            const { CloudStorageLookupTimeoutError } = await import("./errors.js");
+            const manager = createMockManager("hang");
+            const err = await lookupViaHost(manager, testCid, 50).catch((e) => e);
+            expect(err).toBeInstanceOf(CloudStorageLookupTimeoutError);
+            expect(err.cid).toBe(testCid);
+            expect(err.timeoutMs).toBe(50);
+        });
+
+        test("rejects with CloudStorageLookupInterruptedError on interrupt", async () => {
+            const { CloudStorageLookupInterruptedError } = await import("./errors.js");
+            const manager = createMockManager("interrupt");
+            const err = await lookupViaHost(manager, testCid).catch((e) => e);
+            expect(err).toBeInstanceOf(CloudStorageLookupInterruptedError);
+            expect(err.cid).toBe(testCid);
+        });
+
+        test("calls unsubscribe and cancelInterrupt on resolution", async () => {
+            const manager = createMockManager("resolve");
+            await lookupViaHost(manager, testCid);
+            expect(manager.unsubscribe).toHaveBeenCalledOnce();
+            expect(manager.cancelInterrupt).toHaveBeenCalledOnce();
+        });
+
+        test("calls unsubscribe on interrupt", async () => {
+            const manager = createMockManager("interrupt");
+            await lookupViaHost(manager, testCid).catch(() => {});
+            expect(manager.unsubscribe).toHaveBeenCalledOnce();
+        });
+
+        test("passes correct hex key to manager", async () => {
+            const expectedKey = cidToPreimageKey(testCid);
+            const manager = createMockManager("resolve");
+            await lookupViaHost(manager, testCid);
+            expect(manager.lookup).toHaveBeenCalledWith(expectedKey, expect.any(Function));
+        });
+    });
+}