@parity/product-sdk-cloud-storage 0.5.0

package/src/cid.ts

@@ -0,0 +1,214 @@
+/**
+ * CID helpers for converting between on-chain hex hashes and CIDs.
+ *
+ * Upstream `@parity/bulletin-sdk` exposes `calculateCid` (data → CID),
+ * `parseCid` (string → CID), `cidFromBytes` (full-encoded → CID), and
+ * `cidToBytes` (CID → full-encoded). The helpers here add a thin layer
+ * for the `0x`-prefixed hex shape that on-chain `TransactionInfo` uses,
+ * so callers don't need to do the digest plumbing themselves.
+ *
+ * Both helpers default to the chain default (blake2b-256, raw codec).
+ * Pass `HashAlgorithm` and `CidCodec` for other configurations
+ * (sha2-256, dag-pb, etc.).
+ */
+import { CID } from "multiformats/cid";
+import * as Digest from "multiformats/hashes/digest";
+
+import { CloudStorageCidError } from "./errors.js";
+
+/**
+ * Hash algorithms supported by Cloud Storage.
+ *
+ * Values are multihash codes from the multicodec table.
+ */
+export const HashAlgorithm = {
+    /** BLAKE2b-256 — chain default. */
+    Blake2b256: 0xb220,
+    /** SHA2-256. */
+    Sha2_256: 0x12,
+    /** Keccak-256 — Ethereum compatibility. */
+    Keccak256: 0x1b,
+} as const;
+export type HashAlgorithm = (typeof HashAlgorithm)[keyof typeof HashAlgorithm];
+
+/**
+ * CID codecs supported by Cloud Storage.
+ */
+export const CidCodec = {
+    /** Raw binary — default for single-chunk data. */
+    Raw: 0x55,
+    /** DAG-PB — used for multi-chunk manifests / IPFS UnixFS. */
+    DagPb: 0x70,
+    /** DAG-CBOR — alternative DAG encoding. */
+    DagCbor: 0x71,
+} as const;
+export type CidCodec = (typeof CidCodec)[keyof typeof CidCodec];
+
+const SUPPORTED_HASH_CODES = new Set<number>(Object.values(HashAlgorithm));
+const SUPPORTED_CODEC_CODES = new Set<number>(Object.values(CidCodec));
+const EXPECTED_HEX_LENGTH = 66; // "0x" + 64 hex chars (32-byte digest)
+
+/**
+ * Reconstruct a CIDv1 from a `0x`-prefixed 32-byte hex hash.
+ *
+ * Useful when reading on-chain `TransactionInfo.content_hash` and you need
+ * the CID to look up content via an IPFS gateway.
+ *
+ * @param hexHash  - 66-char `0x`-prefixed hex of a 32-byte digest.
+ * @param hashCode - Multihash code (default: blake2b-256).
+ * @param codec    - Multicodec code (default: raw).
+ */
+export function hashToCid(
+    hexHash: `0x${string}`,
+    hashCode: HashAlgorithm = HashAlgorithm.Blake2b256,
+    codec: CidCodec = CidCodec.Raw,
+): string {
+    if (hexHash.length !== EXPECTED_HEX_LENGTH) {
+        throw new CloudStorageCidError(
+            `Expected a 0x-prefixed 32-byte hex hash (${EXPECTED_HEX_LENGTH} chars), ` +
+                `got ${hexHash.length} chars`,
+        );
+    }
+    if (!/^0x[0-9a-fA-F]{64}$/.test(hexHash)) {
+        throw new CloudStorageCidError(
+            `Invalid hash format: expected 0x-prefixed 32-byte hex string, got: ${hexHash}`,
+        );
+    }
+    if (!SUPPORTED_HASH_CODES.has(hashCode)) {
+        throw new CloudStorageCidError(
+            `Unsupported hash algorithm 0x${hashCode.toString(16)}; ` +
+                `expected one of: ${[...SUPPORTED_HASH_CODES].map((c) => `0x${c.toString(16)}`).join(", ")}`,
+        );
+    }
+    if (!SUPPORTED_CODEC_CODES.has(codec)) {
+        throw new CloudStorageCidError(
+            `Unsupported CID codec 0x${codec.toString(16)}; ` +
+                `expected one of: ${[...SUPPORTED_CODEC_CODES].map((c) => `0x${c.toString(16)}`).join(", ")}`,
+        );
+    }
+    const digest = hexToBytes(hexHash);
+    return CID.createV1(codec, Digest.create(hashCode, digest)).toString();
+}
+
+/**
+ * Extract the 32-byte content hash digest from a CIDv1 and return it as a
+ * `0x`-prefixed hex string.
+ *
+ * Useful for matching a CID against on-chain `TransactionInfo.content_hash`.
+ */
+export function cidToPreimageKey(cid: string): `0x${string}` {
+    let parsed;
+    try {
+        parsed = CID.parse(cid);
+    } catch {
+        throw new CloudStorageCidError(`Invalid CID: ${cid}`, cid);
+    }
+    if (parsed.version !== 1) {
+        throw new CloudStorageCidError(`Expected CIDv1, got CIDv${parsed.version}`, cid);
+    }
+    if (!SUPPORTED_HASH_CODES.has(parsed.multihash.code)) {
+        throw new CloudStorageCidError(
+            `Unsupported hash algorithm 0x${parsed.multihash.code.toString(16)}; ` +
+                `expected one of: ${[...SUPPORTED_HASH_CODES].map((c) => `0x${c.toString(16)}`).join(", ")}`,
+            cid,
+        );
+    }
+    return `0x${bytesToHex(parsed.multihash.digest)}` as `0x${string}`;
+}
+
+function hexToBytes(hex: `0x${string}`): Uint8Array {
+    const out = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        out[i] = Number.parseInt(hex.slice(2 + i * 2, 4 + i * 2), 16);
+    }
+    return out;
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+    let s = "";
+    for (let i = 0; i < bytes.length; i++) {
+        s += bytes[i]!.toString(16).padStart(2, "0");
+    }
+    return s;
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+
+    describe("hashToCid", () => {
+        const sampleHex = `0x${"ab".repeat(32)}` as `0x${string}`;
+
+        test("produces valid base32-lower CIDv1 (default: blake2b-256, raw)", () => {
+            const cid = hashToCid(sampleHex);
+            expect(cid).toMatch(/^b[a-z2-7]+$/);
+            const parsed = CID.parse(cid);
+            expect(parsed.version).toBe(1);
+            expect(parsed.code).toBe(CidCodec.Raw);
+            expect(parsed.multihash.code).toBe(HashAlgorithm.Blake2b256);
+        });
+
+        test("supports sha2-256", () => {
+            const cid = hashToCid(sampleHex, HashAlgorithm.Sha2_256);
+            expect(CID.parse(cid).multihash.code).toBe(HashAlgorithm.Sha2_256);
+        });
+
+        test("supports dag-pb codec", () => {
+            const cid = hashToCid(sampleHex, HashAlgorithm.Blake2b256, CidCodec.DagPb);
+            expect(CID.parse(cid).code).toBe(CidCodec.DagPb);
+        });
+
+        test("throws on short hex", () => {
+            expect(() => hashToCid("0xabcd" as `0x${string}`)).toThrow(CloudStorageCidError);
+        });
+
+        test("throws on long hex", () => {
+            const tooLong = `0x${"aa".repeat(33)}` as `0x${string}`;
+            expect(() => hashToCid(tooLong)).toThrow(CloudStorageCidError);
+        });
+
+        test("throws on non-hex characters", () => {
+            const bad = `0x${"zz".repeat(32)}` as `0x${string}`;
+            expect(() => hashToCid(bad)).toThrow(CloudStorageCidError);
+        });
+
+        test("throws on unsupported hash algorithm", () => {
+            expect(() => hashToCid(sampleHex, 0x99 as HashAlgorithm)).toThrow(CloudStorageCidError);
+        });
+
+        test("throws on unsupported codec", () => {
+            expect(() => hashToCid(sampleHex, HashAlgorithm.Blake2b256, 0x99 as CidCodec)).toThrow(
+                CloudStorageCidError,
+            );
+        });
+    });
+
+    describe("cidToPreimageKey", () => {
+        test("round-trip with hashToCid", () => {
+            const hex = `0x${"cd".repeat(32)}` as `0x${string}`;
+            const cid = hashToCid(hex);
+            expect(cidToPreimageKey(cid)).toBe(hex);
+        });
+
+        test("round-trip with sha2-256", () => {
+            const hex = `0x${"ef".repeat(32)}` as `0x${string}`;
+            const cid = hashToCid(hex, HashAlgorithm.Sha2_256);
+            expect(cidToPreimageKey(cid)).toBe(hex);
+        });
+
+        test("throws on invalid CID string", () => {
+            expect(() => cidToPreimageKey("not-a-cid")).toThrow(CloudStorageCidError);
+        });
+
+        test("throws on CIDv0 input", () => {
+            const hash = new Uint8Array(32).fill(0xab);
+            const cidV0 = CID.create(0, 0x70, Digest.create(HashAlgorithm.Sha2_256, hash));
+            expect(() => cidToPreimageKey(cidV0.toString())).toThrow(CloudStorageCidError);
+        });
+
+        test("throws on unsupported hash algorithm", () => {
+            const hash = new Uint8Array(32).fill(0xab);
+            const cidV1 = CID.createV1(CidCodec.Raw, Digest.create(0x99, hash));
+            expect(() => cidToPreimageKey(cidV1.toString())).toThrow(CloudStorageCidError);
+        });
+    });
+}

package/src/client.ts

@@ -0,0 +1,316 @@
+import {
+    AsyncBulletinClient,
+    type AuthCallBuilder,
+    type BulletinTypedApi,
+    type CallBuilder,
+    type ClientConfig,
+    type StoreBuilder,
+    type SubmitFn,
+} from "@parity/bulletin-sdk";
+import { createChainClient, getChainAPI } from "@parity/product-sdk-chain-client";
+import { createLogger } from "@parity/product-sdk-logger";
+import type { PolkadotSigner } from "polkadot-api";
+
+import { checkAuthorization } from "./authorization.js";
+import type { CloudStorageNetworks, CloudStorageEnvironment } from "./networks.js";
+import { executeQuery } from "./query.js";
+import { resolveQueryStrategy, type QueryStrategy } from "./resolve-query.js";
+import type { AuthorizationStatus, CloudStorageApi, QueryOptions } from "./types.js";
+import { verifyStored, type ChainStoredEntry, type VerifyStoredOptions } from "./verify.js";
+
+const log = createLogger("bulletin");
+
+/**
+ * Options for {@link CloudStorageClient.create}.
+ *
+ * One of two construction shapes is supported:
+ *
+ * - **Environment shorthand** — pass an `environment` string keyed by
+ *   {@link CloudStorageNetworks}. Wires up the chain-client automatically.
+ * - **Explicit network** — pass `genesisHash` and `descriptor` directly
+ *   (e.g., spread from a {@link CloudStorageNetworks} entry, or supply custom
+ *   values for a private chain).
+ */
+export type CreateCloudStorageClientOptions =
+    | (CreateCloudStorageClientCommon & { environment: CloudStorageEnvironment })
+    | (CreateCloudStorageClientCommon & {
+          genesisHash: `0x${string}`;
+          descriptor: (typeof CloudStorageNetworks)[CloudStorageEnvironment]["descriptor"];
+      });
+
+interface CreateCloudStorageClientCommon {
+    /** Signer for transaction submission. Required — every store needs a signer. */
+    signer: PolkadotSigner;
+    /** Optional config forwarded to the upstream client. */
+    config?: Partial<ClientConfig>;
+}
+
+/**
+ * Ergonomic entry point for Cloud Storage operations.
+ *
+ * Wraps the upstream `@parity/bulletin-sdk` client (which handles
+ * chunking, DAG-PB manifests, CID calculation, and progress events) and adds:
+ *
+ * - **Network presets** via {@link CloudStorageClient.create} and {@link CloudStorageNetworks}.
+ * - **Read helpers** ({@link fetchBytes}, {@link fetchJson}) routed through
+ *   the host's preimage subscription — upstream is upload-only and the SDK
+ *   is container-only by design (no public-gateway fetches).
+ * - **Pre-flight authorization check** ({@link checkAuthorization}) for
+ *   friendlier UX before submitting a store.
+ *
+ * For uploads, mirror upstream's fluent builders:
+ *
+ * ```ts
+ * const client = await CloudStorageClient.create({ environment: "paseo", signer });
+ * const result = await client.store(data).send();
+ * ```
+ *
+ * For chunked uploads with progress:
+ *
+ * ```ts
+ * const result = await client
+ *   .store(largeFile)
+ *   .withChunkSize(1 << 20)
+ *   .withCallback((evt) => console.log(evt))
+ *   .send();
+ * ```
+ */
+export class CloudStorageClient {
+    /** Underlying upstream client — exposed for power users. */
+    readonly inner: AsyncBulletinClient;
+    /** Typed CloudStorage API. */
+    readonly api: CloudStorageApi;
+
+    /** Lazy-resolved host-preimage query strategy, cached for the client lifetime. */
+    private queryStrategyPromise: Promise<QueryStrategy> | null = null;
+
+    /** Constructed via {@link create} or {@link from}. */
+    private constructor(inner: AsyncBulletinClient, api: CloudStorageApi) {
+        this.inner = inner;
+        this.api = api;
+    }
+
+    /** Resolve and cache the host query strategy on first use. */
+    private resolveQuery(): Promise<QueryStrategy> {
+        if (!this.queryStrategyPromise) {
+            this.queryStrategyPromise = resolveQueryStrategy();
+        }
+        return this.queryStrategyPromise;
+    }
+
+    /**
+     * Create a client from an environment shorthand or an explicit network.
+     *
+     * Environment form uses our `getChainAPI(env)` to resolve the typed API.
+     * Explicit form skips the environment lookup and lets you pass any
+     * genesis/descriptor combo.
+     *
+     * @example
+     * ```ts
+     * // Shorthand
+     * const client = await CloudStorageClient.create({ environment: "paseo", signer });
+     *
+     * // Explicit (custom network)
+     * const client = await CloudStorageClient.create({
+     *   ...CloudStorageNetworks.paseo,
+     *   signer,
+     *   config: { defaultChunkSize: 1 << 20 },
+     * });
+     * ```
+     */
+    static async create(options: CreateCloudStorageClientOptions): Promise<CloudStorageClient> {
+        if ("environment" in options) {
+            const chain = await getChainAPI(options.environment);
+            const inner = new AsyncBulletinClient(
+                chain.bulletin as BulletinTypedApi,
+                options.signer,
+                chain.raw.bulletin.submit as SubmitFn,
+                options.config,
+                () => chain.destroy(),
+            );
+            log.info("CloudStorageClient created (environment shorthand)", {
+                environment: options.environment,
+            });
+            return new CloudStorageClient(inner, chain.bulletin);
+        }
+
+        // Explicit form — caller owns the descriptor choice. We still need a
+        // PolkadotClient to feed AsyncBulletinClient. Going through
+        // chain-client keeps connection management consistent across the SDK.
+        const { genesisHash, descriptor, signer, config } = options;
+        // Catch the obvious foot-gun where caller mixes a genesis from one
+        // network with a descriptor from another — the connection would
+        // succeed but typed calls would silently target the wrong chain.
+        // The descriptor's own `.genesis` field is the on-chain truth; the
+        // user-supplied `genesisHash` is informational today (createChainClient
+        // doesn't use it because host routes connections) but kept on the
+        // option shape for future RPC-direct paths.
+        if (descriptor.genesis && genesisHash.toLowerCase() !== descriptor.genesis.toLowerCase()) {
+            throw new Error(
+                `CloudStorageClient.create: genesisHash (${genesisHash}) does not match descriptor.genesis (${descriptor.genesis}). These must refer to the same network — check that you're pairing the right descriptor with the right genesis hash.`,
+            );
+        }
+        const chain = await createChainClient({
+            chains: { bulletin: descriptor },
+            rpcs: { bulletin: [] },
+        });
+        const inner = new AsyncBulletinClient(
+            chain.bulletin as BulletinTypedApi,
+            signer,
+            chain.raw.bulletin.submit as SubmitFn,
+            config,
+            () => chain.destroy(),
+        );
+        log.info("CloudStorageClient created (explicit network)");
+        return new CloudStorageClient(inner, chain.bulletin);
+    }
+
+    /**
+     * Construct from a pre-built `AsyncBulletinClient` and PAPI typed API.
+     *
+     * Use this when you already own the connection lifecycle (BYOD setups,
+     * tests). The caller is responsible for calling `papiClient.destroy()`
+     * — this client's {@link destroy} only tears down the upstream's
+     * `onDestroy` hook.
+     */
+    static from(inner: AsyncBulletinClient, api: CloudStorageApi): CloudStorageClient {
+        return new CloudStorageClient(inner, api);
+    }
+
+    // ─── Upload + authorization (forwarded to upstream) ────────────────
+
+    /** Build a store transaction. See upstream `StoreBuilder` for chained options. */
+    store(data: Uint8Array): StoreBuilder {
+        return this.inner.store(data);
+    }
+
+    /** Authorize an account to store data on the chain (sudo required on most networks). */
+    authorizeAccount(who: string, transactions: number, bytes: bigint): AuthCallBuilder {
+        return this.inner.authorizeAccount(who, transactions, bytes);
+    }
+
+    /** Authorize content storage by hash (anyone can store; no fees). */
+    authorizePreimage(contentHash: Uint8Array, maxSize: bigint): AuthCallBuilder {
+        return this.inner.authorizePreimage(contentHash, maxSize);
+    }
+
+    /** Renew a stored transaction by block + index. */
+    renew(block: number, index: number): CallBuilder {
+        return this.inner.renew(block, index);
+    }
+
+    /** Estimate the authorization (transactions + bytes) needed for `dataSize`. */
+    estimateAuthorization(dataSize: number): { transactions: number; bytes: number } {
+        return this.inner.estimateAuthorization(dataSize);
+    }
+
+    // ─── Read side (our own helpers) ───────────────────────────────────
+
+    /**
+     * Fetch raw bytes for a CID via the host's preimage lookup.
+     *
+     * Container-only — outside a Polkadot Browser / Desktop host this
+     * throws {@link CloudStorageHostUnavailableError}. The chain stores
+     * content metadata (`content_hash`, size, codec) but the bytes
+     * themselves are surfaced through the host's preimage subscription.
+     *
+     * Use {@link verifyStored} if you only need to confirm a CID was
+     * recorded on-chain (no byte fetch).
+     */
+    async fetchBytes(cid: string, options?: QueryOptions): Promise<Uint8Array> {
+        const strategy = await this.resolveQuery();
+        return executeQuery(strategy, cid, options);
+    }
+
+    /** Fetch and parse JSON for a CID. */
+    async fetchJson<T>(cid: string, options?: QueryOptions): Promise<T> {
+        const bytes = await this.fetchBytes(cid, options);
+        return JSON.parse(new TextDecoder().decode(bytes)) as T;
+    }
+
+    /** Pre-flight: check whether `address` can store via Cloud Storage. */
+    async checkAuthorization(address: string): Promise<AuthorizationStatus> {
+        return checkAuthorization(this.api, address);
+    }
+
+    /**
+     * Verify that a CID was recorded on-chain at the given block.
+     *
+     * Common pattern: pass `blockNumber` (and optionally `extrinsicIndex`)
+     * from a `store(...).send()` receipt to confirm the upload landed.
+     * See {@link verifyStored} for details.
+     */
+    async verifyStored(
+        cid: string,
+        options: VerifyStoredOptions,
+    ): Promise<ChainStoredEntry | null> {
+        return verifyStored(this.api, cid, options);
+    }
+
+    /** Tear down the underlying connection. */
+    async destroy(): Promise<void> {
+        await this.inner.destroy();
+    }
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect, vi } = import.meta.vitest;
+
+    describe("CloudStorageClient.from", () => {
+        test("constructs with given inner and api", () => {
+            const inner = {
+                destroy: vi.fn().mockResolvedValue(undefined),
+            } as unknown as AsyncBulletinClient;
+            const api = {} as CloudStorageApi;
+            const client = CloudStorageClient.from(inner, api);
+            expect(client.inner).toBe(inner);
+            expect(client.api).toBe(api);
+        });
+
+        test("destroy delegates to upstream", async () => {
+            const destroy = vi.fn().mockResolvedValue(undefined);
+            const inner = { destroy } as unknown as AsyncBulletinClient;
+            const client = CloudStorageClient.from(inner, {} as CloudStorageApi);
+            await client.destroy();
+            expect(destroy).toHaveBeenCalledOnce();
+        });
+
+        test("store delegates to inner", () => {
+            const builder = {} as StoreBuilder;
+            const inner = {
+                store: vi.fn().mockReturnValue(builder),
+            } as unknown as AsyncBulletinClient;
+            const client = CloudStorageClient.from(inner, {} as CloudStorageApi);
+            const data = new Uint8Array([1, 2, 3]);
+            expect(client.store(data)).toBe(builder);
+            expect(inner.store).toHaveBeenCalledWith(data);
+        });
+    });
+
+    describe("CloudStorageClient.create (BYOD genesis assertion)", () => {
+        // Stand-in descriptor with a known genesis. The full PAPI descriptor
+        // type is a `ChainDefinition` with a deep type-level shape; the cast
+        // below is fine for the assertion test because we never actually
+        // reach createChainClient.
+        const stubDescriptor = (
+            genesis: `0x${string}`,
+        ): (typeof CloudStorageNetworks)[CloudStorageEnvironment]["descriptor"] =>
+            ({
+                genesis,
+            }) as unknown as (typeof CloudStorageNetworks)[CloudStorageEnvironment]["descriptor"];
+
+        const realPaseo =
+            "0x744960c32e3a3df5440e1ecd4d34096f1ce2230d7016a5ada8a765d5a622b4ea" as `0x${string}`;
+
+        test("throws when genesisHash and descriptor.genesis disagree", async () => {
+            await expect(
+                CloudStorageClient.create({
+                    genesisHash:
+                        "0x0000000000000000000000000000000000000000000000000000000000000001",
+                    descriptor: stubDescriptor(realPaseo),
+                    signer: {} as PolkadotSigner,
+                }),
+            ).rejects.toThrow(/does not match descriptor\.genesis/i);
+        });
+    });
+}

package/src/errors.ts

@@ -0,0 +1,162 @@
+/**
+ * Cloud Storage error types.
+ *
+ * Two error families coexist:
+ *
+ * 1. **Upstream SDK errors** — `BulletinError` and `ErrorCode` from
+ *    `@parity/bulletin-sdk` cover upload/store/authorization failures
+ *    surfaced by `AsyncBulletinClient`. Each carries `code`, `retryable`,
+ *    and `recoveryHint`.
+ * 2. **Read-side errors** declared here — host preimage availability /
+ *    lookup timeouts / interrupts, plus CID format problems, surfaced by
+ *    our retrieval helpers (`fetchBytes`, `fetchJson`, `verifyStored`).
+ *
+ * Catch upstream errors with `instanceof BulletinError`. Catch our read-side
+ * errors with `instanceof ProductCloudStorageError` (or the specific subclass).
+ */
+export { BulletinError, ErrorCode } from "@parity/bulletin-sdk";
+
+/**
+ * Base class for read-side errors raised by `@parity/product-sdk-cloud-storage`.
+ *
+ * Distinct from upstream `BulletinError` which covers upload/store failures.
+ */
+export class ProductCloudStorageError extends Error {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = "ProductCloudStorageError";
+    }
+}
+
+/**
+ * The host preimage API is unavailable.
+ *
+ * Thrown when cloud storage operations require the host container but it's not
+ * available. This typically means the SDK is running outside Polkadot
+ * Browser / Desktop. The Cloud Storage SDK is container-only by design — see
+ * the README for the rationale.
+ */
+export class CloudStorageHostUnavailableError extends ProductCloudStorageError {
+    constructor(operation: "upload" | "query") {
+        super(
+            `Host preimage API unavailable for ${operation}. Ensure you are running inside a host container (Polkadot Browser / Desktop).`,
+        );
+        this.name = "CloudStorageHostUnavailableError";
+    }
+}
+
+/**
+ * The host preimage lookup timed out.
+ *
+ * The host was unable to retrieve the requested content within the timeout
+ * period. The content may still become available later.
+ */
+export class CloudStorageLookupTimeoutError extends ProductCloudStorageError {
+    /** The CID that was being looked up. */
+    readonly cid: string;
+    /** The timeout duration in milliseconds. */
+    readonly timeoutMs: number;
+
+    constructor(cid: string, timeoutMs: number) {
+        super(`Host preimage lookup timed out after ${timeoutMs}ms for CID: ${cid}`);
+        this.name = "CloudStorageLookupTimeoutError";
+        this.cid = cid;
+        this.timeoutMs = timeoutMs;
+    }
+}
+
+/**
+ * The host interrupted the preimage lookup.
+ *
+ * The host terminated the lookup subscription, typically after repeated
+ * failures or when the host determines the content is unavailable.
+ */
+export class CloudStorageLookupInterruptedError extends ProductCloudStorageError {
+    /** The CID that was being looked up. */
+    readonly cid: string;
+
+    constructor(cid: string) {
+        super(`Host preimage lookup was interrupted for CID: ${cid}`);
+        this.name = "CloudStorageLookupInterruptedError";
+        this.cid = cid;
+    }
+}
+
+/**
+ * Invalid CID format or version.
+ */
+export class CloudStorageCidError extends ProductCloudStorageError {
+    /** The invalid CID string, if available. */
+    readonly cid?: string;
+
+    constructor(message: string, cid?: string) {
+        super(message);
+        this.name = "CloudStorageCidError";
+        this.cid = cid;
+    }
+}
+
+/**
+ * Failed to check authorization status for an account.
+ *
+ * Wraps RPC or query errors that occur when checking if an account
+ * is authorized to store data in Cloud Storage.
+ */
+export class CloudStorageAuthorizationError extends ProductCloudStorageError {
+    /** The address that was being checked. */
+    readonly address: string;
+
+    constructor(address: string, cause?: unknown) {
+        super(`Failed to check authorization for ${address}`, { cause });
+        this.name = "CloudStorageAuthorizationError";
+        this.address = address;
+    }
+}
+
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+
+    describe("ProductCloudStorageError hierarchy", () => {
+        test("ProductCloudStorageError extends Error", () => {
+            const err = new ProductCloudStorageError("test");
+            expect(err).toBeInstanceOf(Error);
+            expect(err.name).toBe("ProductCloudStorageError");
+        });
+
+        test("CloudStorageCidError", () => {
+            const err = new CloudStorageCidError("bad", "Qmabc");
+            expect(err).toBeInstanceOf(ProductCloudStorageError);
+            expect(err.cid).toBe("Qmabc");
+        });
+
+        test("CloudStorageinHostUnavailableError", () => {
+            const err = new CloudStorageHostUnavailableError("query");
+            expect(err).toBeInstanceOf(ProductCloudStorageError);
+            expect(err.message).toContain("query");
+            expect(err.message).toContain("Host preimage API unavailable");
+        });
+
+        test("CloudStorageLookupTimeoutError", () => {
+            const err = new CloudStorageLookupTimeoutError("bafyabc123", 30000);
+            expect(err).toBeInstanceOf(ProductCloudStorageError);
+            expect(err.cid).toBe("bafyabc123");
+            expect(err.timeoutMs).toBe(30000);
+            expect(err.message).toContain("30000ms");
+        });
+
+        test("CloudStorageLookupInterruptedError", () => {
+            const err = new CloudStorageLookupInterruptedError("bafyabc123");
+            expect(err).toBeInstanceOf(ProductCloudStorageError);
+            expect(err.cid).toBe("bafyabc123");
+            expect(err.message).toContain("interrupted");
+        });
+
+        test("CloudStorageAuthorizationError carries cause", () => {
+            const cause = new Error("RPC down");
+            const err = new CloudStorageAuthorizationError("5GrwvaEF...", cause);
+            expect(err).toBeInstanceOf(ProductCloudStorageError);
+            expect(err.address).toBe("5GrwvaEF...");
+            expect(err.cause).toBe(cause);
+        });
+    });
+}