@parity/product-sdk-cloud-storage 0.5.0

package/dist/index.js

@@ -0,0 +1,534 @@
+import { parseCid, CidCodec as CidCodec$1, UnixFsDagBuilder, AsyncBulletinClient } from '@parity/bulletin-sdk';
+export { AsyncBulletinClient, AuthCallBuilder, AuthorizationScope, BulletinError, BulletinPreparer, CID, CallBuilder, ChunkStatus, DEFAULT_CHUNKER_CONFIG, DEFAULT_CLIENT_CONFIG, DEFAULT_STORE_OPTIONS, ErrorCode, MAX_CHUNK_SIZE, MAX_FILE_SIZE, MockBulletinClient, StoreBuilder, TxStatus, WaitFor, calculateCid, cidFromBytes, cidToBytes, convertCid, estimateAuthorization, getContentHash, parseCid, reassembleChunks, resolveClientConfig, validateChunkSize } from '@parity/bulletin-sdk';
+import { getChainAPI, createChainClient } from '@parity/product-sdk-chain-client';
+import { createLogger } from '@parity/product-sdk-logger';
+import { submitAndWatch } from '@parity/product-sdk-tx';
+import { Enum } from 'polkadot-api';
+import { getPreimageManager } from '@parity/product-sdk-host';
+import { CID } from 'multiformats/cid';
+import * as Digest from 'multiformats/hashes/digest';
+import { paseo_bulletin } from '@parity/product-sdk-descriptors/paseo-bulletin';
+
+// src/client.ts
+var ProductCloudStorageError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ProductCloudStorageError";
+  }
+};
+var CloudStorageHostUnavailableError = class extends ProductCloudStorageError {
+  constructor(operation) {
+    super(
+      `Host preimage API unavailable for ${operation}. Ensure you are running inside a host container (Polkadot Browser / Desktop).`
+    );
+    this.name = "CloudStorageHostUnavailableError";
+  }
+};
+var CloudStorageLookupTimeoutError = class extends ProductCloudStorageError {
+  /** The CID that was being looked up. */
+  cid;
+  /** The timeout duration in milliseconds. */
+  timeoutMs;
+  constructor(cid, timeoutMs) {
+    super(`Host preimage lookup timed out after ${timeoutMs}ms for CID: ${cid}`);
+    this.name = "CloudStorageLookupTimeoutError";
+    this.cid = cid;
+    this.timeoutMs = timeoutMs;
+  }
+};
+var CloudStorageLookupInterruptedError = class extends ProductCloudStorageError {
+  /** The CID that was being looked up. */
+  cid;
+  constructor(cid) {
+    super(`Host preimage lookup was interrupted for CID: ${cid}`);
+    this.name = "CloudStorageLookupInterruptedError";
+    this.cid = cid;
+  }
+};
+var CloudStorageCidError = class extends ProductCloudStorageError {
+  /** The invalid CID string, if available. */
+  cid;
+  constructor(message, cid) {
+    super(message);
+    this.name = "CloudStorageCidError";
+    this.cid = cid;
+  }
+};
+var CloudStorageAuthorizationError = class extends ProductCloudStorageError {
+  /** The address that was being checked. */
+  address;
+  constructor(address, cause) {
+    super(`Failed to check authorization for ${address}`, { cause });
+    this.name = "CloudStorageAuthorizationError";
+    this.address = address;
+  }
+};
+
+// src/authorization.ts
+var log = createLogger("cloudStorage");
+var NOT_AUTHORIZED = Object.freeze({
+  authorized: false,
+  remainingTransactions: 0,
+  remainingBytes: 0n,
+  expiration: 0
+});
+async function checkAuthorization(api, address) {
+  let auth;
+  try {
+    auth = await api.query.TransactionStorage.Authorizations.getValue(
+      Enum("Account", address)
+    );
+  } catch (error) {
+    log.error("checkAuthorization: query failed", { address, error });
+    throw new CloudStorageAuthorizationError(address, error);
+  }
+  if (!auth) {
+    log.debug("checkAuthorization: no authorization found", { address });
+    return NOT_AUTHORIZED;
+  }
+  const status = {
+    authorized: true,
+    remainingTransactions: auth.extent.transactions_allowance - auth.extent.transactions,
+    // `auth` is `any` (TypedApi<any> upstream — see line 53). TS narrows
+    // `any - any` to `number`, so cast each u64 operand to bigint to keep
+    // the subtraction in bigint space. Runtime values are bigints from PAPI.
+    remainingBytes: auth.extent.bytes_allowance - auth.extent.bytes,
+    expiration: auth.expiration
+  };
+  log.debug("checkAuthorization", {
+    address,
+    remainingTransactions: status.remainingTransactions,
+    remainingBytes: status.remainingBytes.toString(),
+    expiration: status.expiration
+  });
+  return status;
+}
+async function authorizeAccount(api, who, transactions, bytes, signer, options = {}) {
+  const { viaSudo = false, waitFor, timeoutMs, onStatus } = options;
+  const apiTx = api.tx;
+  log.info("authorizeAccount: building extrinsic", {
+    who,
+    transactions,
+    bytes: bytes.toString(),
+    viaSudo
+  });
+  if (viaSudo && !apiTx.Sudo?.sudo) {
+    throw new ProductCloudStorageError(
+      "viaSudo: true requires the Sudo pallet, which is not available on this network. On production networks (Polkadot, Kusama), authorize_account requires governance or a different mechanism."
+    );
+  }
+  const authorizeTx = apiTx.TransactionStorage.authorize_account({
+    who,
+    transactions,
+    bytes
+  });
+  const txToSubmit = viaSudo ? apiTx.Sudo.sudo({ call: authorizeTx.decodedCall }) : authorizeTx;
+  const result = await submitAndWatch(txToSubmit, signer, {
+    waitFor,
+    timeoutMs,
+    onStatus
+  });
+  log.info("authorizeAccount: included in block", {
+    who,
+    blockHash: result.block.hash
+  });
+  return { blockHash: result.block.hash };
+}
+var HashAlgorithm = {
+  /** BLAKE2b-256 — chain default. */
+  Blake2b256: 45600,
+  /** SHA2-256. */
+  Sha2_256: 18,
+  /** Keccak-256 — Ethereum compatibility. */
+  Keccak256: 27
+};
+var CidCodec = {
+  /** Raw binary — default for single-chunk data. */
+  Raw: 85,
+  /** DAG-PB — used for multi-chunk manifests / IPFS UnixFS. */
+  DagPb: 112,
+  /** DAG-CBOR — alternative DAG encoding. */
+  DagCbor: 113
+};
+var SUPPORTED_HASH_CODES = new Set(Object.values(HashAlgorithm));
+var SUPPORTED_CODEC_CODES = new Set(Object.values(CidCodec));
+var EXPECTED_HEX_LENGTH = 66;
+function hashToCid(hexHash, hashCode = HashAlgorithm.Blake2b256, codec = CidCodec.Raw) {
+  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();
+}
+function cidToPreimageKey(cid) {
+  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)}`;
+}
+function hexToBytes(hex) {
+  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) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) {
+    s += bytes[i].toString(16).padStart(2, "0");
+  }
+  return s;
+}
+
+// src/resolve-query.ts
+var log2 = createLogger("bulletin");
+var DEFAULT_LOOKUP_TIMEOUT_MS = 3e4;
+async function resolveQueryStrategy() {
+  const preimageManager = await getPreimageManager();
+  if (preimageManager) {
+    log2.info("using host preimage lookup for Cloud Storage queries");
+    return {
+      kind: "host-lookup",
+      lookup: (cid, timeoutMs) => lookupViaHost(preimageManager, cid, timeoutMs)
+    };
+  }
+  throw new CloudStorageHostUnavailableError("query");
+}
+function lookupViaHost(manager, cid, timeoutMs = DEFAULT_LOOKUP_TIMEOUT_MS) {
+  const key = cidToPreimageKey(cid);
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      cancelInterrupt();
+      sub.unsubscribe();
+    };
+    const settle = (fn) => {
+      if (timer === null) return;
+      clearTimeout(timer);
+      timer = null;
+      cleanup();
+      fn();
+    };
+    let timer = setTimeout(() => {
+      settle(() => {
+        reject(new CloudStorageLookupTimeoutError(cid, timeoutMs));
+      });
+    }, timeoutMs);
+    const sub = manager.lookup(key, (preimage) => {
+      if (preimage !== null) {
+        settle(() => resolve(preimage));
+      }
+    });
+    const cancelInterrupt = sub.onInterrupt(() => {
+      settle(() => {
+        reject(new CloudStorageLookupInterruptedError(cid));
+      });
+    });
+  });
+}
+
+// src/query.ts
+var log3 = createLogger("bulletin");
+async function queryBytes(cid, options) {
+  const strategy = await resolveQueryStrategy();
+  return executeQuery(strategy, cid, options);
+}
+async function queryJson(cid, options) {
+  const bytes = await queryBytes(cid, options);
+  return JSON.parse(new TextDecoder().decode(bytes));
+}
+async function executeQuery(strategy, cid, options) {
+  log3.info("query: host preimage lookup", { cid });
+  const bytes = await strategy.lookup(cid, options?.lookupTimeoutMs);
+  if (options?.noReassemble) return bytes;
+  const parsed = parseCid(cid);
+  if (parsed.code !== CidCodec$1.DagPb) return bytes;
+  log3.info("query: reassembling DAG-PB manifest", { cid });
+  const builder = new UnixFsDagBuilder();
+  const { chunkCids } = await builder.parse(bytes);
+  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;
+}
+var HASH_CODE_TO_ENUM_TYPE = {
+  [HashAlgorithm.Blake2b256]: "Blake2b256",
+  [HashAlgorithm.Sha2_256]: "Sha2_256",
+  [HashAlgorithm.Keccak256]: "Keccak256"
+};
+async function verifyStored(api, cid, options) {
+  const parsed = parseCidForVerify(cid);
+  const queryFn = api.query?.TransactionStorage?.Transactions?.getValue;
+  if (!queryFn) {
+    throw new Error(
+      "CloudStorage API does not expose query.TransactionStorage.Transactions \u2014 the typed API may be incomplete or the runtime version doesn't match the descriptor."
+    );
+  }
+  const entries = await queryFn(options.block);
+  if (!entries || entries.length === 0) return null;
+  if (options.index !== void 0) {
+    const entry = entries[options.index];
+    if (entry && matchesEntry(entry, parsed)) {
+      return {
+        block: options.block,
+        index: options.index,
+        size: entry.size,
+        blockChunks: entry.block_chunks
+      };
+    }
+    return null;
+  }
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    if (matchesEntry(entry, parsed)) {
+      return {
+        block: options.block,
+        index: i,
+        size: entry.size,
+        blockChunks: entry.block_chunks
+      };
+    }
+  }
+  return null;
+}
+function parseCidForVerify(cid) {
+  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);
+  }
+  const hashType = HASH_CODE_TO_ENUM_TYPE[parsed.multihash.code];
+  if (!hashType) {
+    throw new CloudStorageCidError(
+      `Unsupported hash algorithm 0x${parsed.multihash.code.toString(16)}`,
+      cid
+    );
+  }
+  return { digest: parsed.multihash.digest, hashType };
+}
+function matchesEntry(entry, target) {
+  if (entry.hashing.type !== target.hashType) return false;
+  const onChainBytes = entry.content_hash instanceof Uint8Array ? entry.content_hash : entry.content_hash.asBytes();
+  if (onChainBytes.length !== target.digest.length) return false;
+  for (let i = 0; i < onChainBytes.length; i++) {
+    if (onChainBytes[i] !== target.digest[i]) return false;
+  }
+  return true;
+}
+
+// src/client.ts
+var log4 = createLogger("bulletin");
+var CloudStorageClient = class _CloudStorageClient {
+  /** Underlying upstream client — exposed for power users. */
+  inner;
+  /** Typed CloudStorage API. */
+  api;
+  /** Lazy-resolved host-preimage query strategy, cached for the client lifetime. */
+  queryStrategyPromise = null;
+  /** Constructed via {@link create} or {@link from}. */
+  constructor(inner, api) {
+    this.inner = inner;
+    this.api = api;
+  }
+  /** Resolve and cache the host query strategy on first use. */
+  resolveQuery() {
+    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) {
+    if ("environment" in options) {
+      const chain2 = await getChainAPI(options.environment);
+      const inner2 = new AsyncBulletinClient(
+        chain2.bulletin,
+        options.signer,
+        chain2.raw.bulletin.submit,
+        options.config,
+        () => chain2.destroy()
+      );
+      log4.info("CloudStorageClient created (environment shorthand)", {
+        environment: options.environment
+      });
+      return new _CloudStorageClient(inner2, chain2.bulletin);
+    }
+    const { genesisHash, descriptor, signer, config } = options;
+    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 \u2014 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,
+      signer,
+      chain.raw.bulletin.submit,
+      config,
+      () => chain.destroy()
+    );
+    log4.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, api) {
+    return new _CloudStorageClient(inner, api);
+  }
+  // ─── Upload + authorization (forwarded to upstream) ────────────────
+  /** Build a store transaction. See upstream `StoreBuilder` for chained options. */
+  store(data) {
+    return this.inner.store(data);
+  }
+  /** Authorize an account to store data on the chain (sudo required on most networks). */
+  authorizeAccount(who, transactions, bytes) {
+    return this.inner.authorizeAccount(who, transactions, bytes);
+  }
+  /** Authorize content storage by hash (anyone can store; no fees). */
+  authorizePreimage(contentHash, maxSize) {
+    return this.inner.authorizePreimage(contentHash, maxSize);
+  }
+  /** Renew a stored transaction by block + index. */
+  renew(block, index) {
+    return this.inner.renew(block, index);
+  }
+  /** Estimate the authorization (transactions + bytes) needed for `dataSize`. */
+  estimateAuthorization(dataSize) {
+    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, options) {
+    const strategy = await this.resolveQuery();
+    return executeQuery(strategy, cid, options);
+  }
+  /** Fetch and parse JSON for a CID. */
+  async fetchJson(cid, options) {
+    const bytes = await this.fetchBytes(cid, options);
+    return JSON.parse(new TextDecoder().decode(bytes));
+  }
+  /** Pre-flight: check whether `address` can store via Cloud Storage. */
+  async checkAuthorization(address) {
+    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, options) {
+    return verifyStored(this.api, cid, options);
+  }
+  /** Tear down the underlying connection. */
+  async destroy() {
+    await this.inner.destroy();
+  }
+};
+var CloudStorageNetworks = {
+  paseo: {
+    genesisHash: "0x8cfe6717dc4becfda2e13c488a1e2061ff2dfee96e7d031157f72d36716c0a22",
+    descriptor: paseo_bulletin
+  }
+};
+
+// src/lazy-signer.ts
+function createLazySigner(getSigner, onMissing = "No signer available \u2014 connect a wallet and select an account first.") {
+  const resolve = () => {
+    const inner = getSigner();
+    if (!inner) throw new Error(onMissing);
+    return inner;
+  };
+  const lazy = {
+    get publicKey() {
+      return resolve().publicKey;
+    },
+    signTx: async (...args) => resolve().signTx(...args),
+    signBytes: async (...args) => resolve().signBytes(...args)
+  };
+  return lazy;
+}
+
+export { CidCodec, CloudStorageAuthorizationError, CloudStorageCidError, CloudStorageClient, CloudStorageHostUnavailableError, CloudStorageLookupInterruptedError, CloudStorageLookupTimeoutError, CloudStorageNetworks, HashAlgorithm, ProductCloudStorageError, authorizeAccount, checkAuthorization, cidToPreimageKey, createLazySigner, executeQuery, hashToCid, queryBytes, queryJson, resolveQueryStrategy, verifyStored };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map