@otskit/client 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -29,7 +29,7 @@ __export(index_exports, {
   DEFAULT_CALENDARS: () => DEFAULT_CALENDARS,
   DEFAULT_CALENDAR_WHITELIST: () => DEFAULT_CALENDAR_WHITELIST,
   DEFAULT_RESILIENCE: () => DEFAULT_RESILIENCE,
-  DetachedTimestampFile: () => import_core5.DetachedTimestampFile,
+  DetachedTimestampFile: () => import_core7.DetachedTimestampFile,
   EsploraClient: () => EsploraClient,
   EsploraResponseError: () => EsploraResponseError,
   MAX_CALENDAR_RESPONSE_SIZE: () => MAX_CALENDAR_RESPONSE_SIZE,
@@ -41,7 +41,7 @@ __export(index_exports, {
   ResilientNetworkLayer: () => ResilientNetworkLayer,
   SizeLimitExceededError: () => SizeLimitExceededError,
   StampError: () => StampError,
-  Timestamp: () => import_core5.Timestamp,
+  Timestamp: () => import_core7.Timestamp,
   UpgradeError: () => UpgradeError,
   UrlWhitelist: () => UrlWhitelist,
   ValidationError: () => ValidationError,
@@ -49,7 +49,7 @@ __export(index_exports, {
   hashBuffer: () => hashBuffer,
   hashFile: () => hashFile,
   isVerified: () => isVerified,
-  verifyAgainstBlockheader: () => import_core6.verifyAgainstBlockheader,
+  verifyAgainstBlockheader: () => import_core8.verifyAgainstBlockheader,
   verifyTimestampAttestation: () => verifyTimestampAttestation
 });
 module.exports = __toCommonJS(index_exports);
@@ -85,7 +85,8 @@ var OpenTimestampsClientError = class extends Error {
   constructor(message, options) {
     super(message);
     this.name = this.constructor.name;
-    this.cause = options?.cause;
+    if (options?.cause !== void 0)
+      this.cause = options.cause;
     Error.captureStackTrace?.(this, this.constructor);
   }
 };
@@ -103,11 +104,11 @@ var StampError = class extends OpenTimestampsClientError {
 var UpgradeError = class extends OpenTimestampsClientError {
 };
 var NetworkError = class extends OpenTimestampsClientError {
-  /** HTTP status code, cuando el fallo viene de una respuesta HTTP. */
+  /** HTTP status code when the failure originates from an HTTP response. */
   status;
   constructor(message, options) {
     super(message, options);
-    this.status = options?.status;
+    if (options?.status !== void 0) this.status = options.status;
   }
 };
 var CircuitBreakerError = class extends NetworkError {
@@ -130,7 +131,7 @@ var SizeLimitExceededError = class extends NetworkError {
       options
     );
     this.maxBytes = maxBytes;
-    this.actualBytes = actualBytes;
+    if (actualBytes !== void 0) this.actualBytes = actualBytes;
   }
 };
 
@@ -182,7 +183,10 @@ var CircuitBreaker = class {
       this.onSuccess(key, circuit);
       return result;
     } catch (error) {
-      this.onFailure(key, circuit);
+      const is4xx = error instanceof Error && error.retryable === false;
+      if (!is4xx) {
+        this.onFailure(key, circuit);
+      }
       throw error;
     }
   }
@@ -279,11 +283,15 @@ function sleep(ms, signal) {
       reject(new Error("Aborted"));
       return;
     }
-    const timeout = setTimeout(resolve, ms);
-    signal?.addEventListener("abort", () => {
+    const onAbort = () => {
       clearTimeout(timeout);
       reject(new Error("Aborted"));
-    });
+    };
+    const timeout = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
   });
 }
 async function withRetry(fn, options, logger, signal) {
@@ -366,8 +374,9 @@ async function executeRequest(request, maxBytes) {
     const response = await globalThis.fetch(request.url, {
       method: request.method,
       headers: { "Content-Type": "application/octet-stream", ...request.headers },
-      body: request.body,
-      signal: request.signal
+      ...request.body !== void 0 ? { body: request.body } : {},
+      ...request.signal !== void 0 ? { signal: request.signal } : {},
+      redirect: "error"
     });
     const data = await readResponseBody(response, maxBytes);
     return { ok: response.ok, status: response.status, statusText: response.statusText, data };
@@ -376,7 +385,8 @@ async function executeRequest(request, maxBytes) {
     if (error instanceof NetworkError) throw error;
     if (error instanceof Error) {
       if (error.name === "AbortError") throw new NetworkError("Request aborted", { cause: error });
-      if (error.message.includes("timeout")) throw new NetworkError("Request timeout", { cause: error });
+      if (error.message.includes("timeout"))
+        throw new NetworkError("Request timeout", { cause: error });
       throw new NetworkError(`Network request failed: ${error.message}`, { cause: error });
     }
     throw new NetworkError("Unknown network error");
@@ -390,10 +400,14 @@ function createTimeoutController(timeoutMs, parentSignal) {
     parentSignal?.removeEventListener("abort", onParentAbort);
     controller.abort(parentSignal?.reason);
   };
-  controller.signal.addEventListener("abort", () => {
-    clearTimeout(timeout);
-    parentSignal?.removeEventListener("abort", onParentAbort);
-  }, { once: true });
+  controller.signal.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(timeout);
+      parentSignal?.removeEventListener("abort", onParentAbort);
+    },
+    { once: true }
+  );
   if (parentSignal) {
     if (parentSignal.aborted) {
       clearTimeout(timeout);
@@ -485,8 +499,8 @@ var ResilientNetworkLayer = class {
   }
 };
 
-// src/core/orchestration.ts
-var import_core4 = require("@otskit/core");
+// src/core/stamp.ts
+var import_core3 = require("@otskit/core");
 
 // src/network/calendar.ts
 var import_core2 = require("@otskit/core");
@@ -515,7 +529,7 @@ var CalendarClient = class {
   url;
   networkLayer;
   logger;
-  /** Envia un digest al calendario y devuelve el Timestamp que lo commit-ea. */
+  /** Submits a digest to the calendar and returns the Timestamp that commits to it. */
   async submit(digest, signal) {
     assertCommitment(digest);
     this.logger?.debug(`Submitting digest to ${this.url}/digest`);
@@ -526,7 +540,7 @@ var CalendarClient = class {
     );
     return this.#parseTimestamp(response.data, digest);
   }
-  /** Pregunta al calendario si tiene un Timestamp mas completo para `commitment` (upgrade). */
+  /** Asks the calendar for a more complete Timestamp for `commitment` (upgrade). */
   async getTimestamp(commitment, signal) {
     assertCommitment(commitment);
     const path = `/timestamp/${(0, import_core2.bytesToHex)(commitment)}`;
@@ -548,7 +562,7 @@ var CalendarClient = class {
     }
     return this.#parseTimestamp(response.data, commitment);
   }
-  /** Deserializa la respuesta del calendario como un Timestamp commit-eado a `commitment`. */
+  /** Deserializes the calendar response as a Timestamp committed to `commitment`. */
   #parseTimestamp(data, commitment) {
     if (data.length > MAX_CALENDAR_RESPONSE_SIZE) {
       throw new CalendarResponseTooLargeError(
@@ -578,7 +592,7 @@ function parseWhitelistPattern(raw) {
     hostname,
     port: parsed.port,
     pathname: parsed.pathname,
-    wildcardSuffix
+    ...wildcardSuffix !== void 0 ? { wildcardSuffix } : {}
   };
 }
 function hostnameMatchesPattern(hostname, pattern) {
@@ -594,20 +608,26 @@ var UrlWhitelist = class {
       for (const u of urls) this.add(u);
     }
   }
-  /** Anade un patron; si no trae esquema, se anaden las variantes http y https. */
+  /**
+   * Adds a pattern. If the URL has no scheme, both http:// and https:// variants are added.
+   * Throws TypeError if the pattern is not a valid string or is structurally invalid.
+   */
   add(url) {
     if (typeof url !== "string") {
       throw new TypeError("UrlWhitelist: URL must be a string");
     }
     if (url.startsWith("http://") || url.startsWith("https://")) {
       const pattern = parseWhitelistPattern(url);
-      if (pattern !== void 0) this.#patterns.set(url, pattern);
+      if (pattern === void 0) {
+        throw new TypeError(`UrlWhitelist: invalid or unsupported pattern: "${url}"`);
+      }
+      this.#patterns.set(url, pattern);
     } else {
       this.add("http://" + url);
       this.add("https://" + url);
     }
   }
-  /** Verdadero si `url` casa con algun patron de la whitelist. */
+  /** Returns true if `url` matches any pattern in the allowlist. */
   contains(url) {
     let parsed;
     try {
@@ -632,11 +652,158 @@ var UrlWhitelist = class {
 var DEFAULT_CALENDAR_WHITELIST = new UrlWhitelist([...import_core2.TRUSTED_CALENDAR_WHITELIST_PATTERNS]);
 var DEFAULT_AGGREGATORS = [...import_core2.DEFAULT_AGGREGATOR_URLS];
 
+// src/utils/hex.ts
+function hexToBytes(hex) {
+  const clean = hex.trim().toLowerCase();
+  if (clean.length % 2 !== 0 || !/^[0-9a-f]*$/.test(clean)) throw new Error("Invalid hex string");
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+function bytesToHex2(bytes) {
+  let s = "";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+
+// src/core/shared.ts
+function validateHash(hash) {
+  if (typeof hash === "string") {
+    const hex = hash.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(hex)) {
+      throw new ValidationError("Hash must be a 64-character hex string (SHA-256)");
+    }
+    return hexToBytes(hex);
+  }
+  if (hash.length !== 32) {
+    throw new ValidationError("Hash must be exactly 32 bytes (SHA-256)");
+  }
+  return Uint8Array.from(hash);
+}
+function secureNonce(n) {
+  const bytes = new Uint8Array(n);
+  if (!globalThis.crypto?.getRandomValues) {
+    throw new Error("secure RNG unavailable: globalThis.crypto.getRandomValues is required");
+  }
+  globalThis.crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+// src/core/stamp.ts
+async function orchestrateStamp(hash, calendars, networkLayer, validateCalendarUrl, logger, signal, minimumSuccessfulSubmissions = 2) {
+  if (calendars.length === 0) {
+    throw new ValidationError("at least one calendar is required to stamp");
+  }
+  if (!Number.isInteger(minimumSuccessfulSubmissions) || minimumSuccessfulSubmissions < 1) {
+    throw new ValidationError("minimumSuccessfulSubmissions must be an integer >= 1");
+  }
+  if (minimumSuccessfulSubmissions > calendars.length) {
+    throw new ValidationError(
+      `minimumSuccessfulSubmissions (${minimumSuccessfulSubmissions}) cannot exceed the number of calendars (${calendars.length})`
+    );
+  }
+  await Promise.all(calendars.map((url) => validateCalendarUrl(url)));
+  const digest = validateHash(hash);
+  logger?.info(`Starting stamp for ${bytesToHex2(digest)}`);
+  const detached = import_core3.DetachedTimestampFile.fromHash(new import_core3.OpSHA256(), digest);
+  const nonceAppended = detached.timestamp.add(new import_core3.OpAppend(secureNonce(16)));
+  const merkleRoot = nonceAppended.add(new import_core3.OpSHA256());
+  const merkleTip = (0, import_core3.makeMerkleTree)([merkleRoot]);
+  const results = await Promise.allSettled(
+    calendars.map(
+      (url) => new CalendarClient(url, networkLayer, logger).submit(merkleTip.getDigest(), signal)
+    )
+  );
+  const successful = [];
+  const failed = [];
+  results.forEach((r, i) => {
+    const calendar = calendars[i];
+    if (r.status === "fulfilled") {
+      merkleTip.merge(r.value);
+      successful.push({ calendar });
+      logger?.info(`Submitted to ${calendar}`);
+    } else {
+      const error = r.reason instanceof Error ? r.reason : new Error(String(r.reason));
+      failed.push({ calendar, error });
+      logger?.warn(`Failed to submit to ${calendar}: ${error.message}`);
+    }
+  });
+  if (successful.length < minimumSuccessfulSubmissions) {
+    throw new StampError(
+      `Insufficient successful submissions (${successful.length}/${minimumSuccessfulSubmissions} required)`,
+      successful,
+      failed
+    );
+  }
+  return detached.serializeToBytes();
+}
+
+// src/core/upgrade.ts
+var import_core4 = require("@otskit/core");
+var bytesEqFast = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)) === 0;
+async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, logger, signal) {
+  let detached;
+  try {
+    detached = import_core4.DetachedTimestampFile.deserialize(new Uint8Array(incompleteProof));
+  } catch (error) {
+    throw new ValidationError("Invalid .ots proof format", {
+      /* v8 ignore next */
+      ...error instanceof Error ? { cause: error } : {}
+    });
+  }
+  if (detached.timestamp.isTimestampComplete()) {
+    logger?.info("Proof already complete; nothing to upgrade");
+    return Buffer.from(incompleteProof);
+  }
+  const before = detached.serializeToBytes();
+  for (const subStamp of detached.timestamp.directlyVerified()) {
+    if (subStamp.isTimestampComplete()) continue;
+    for (const att of subStamp.attestations) {
+      if (att.kind !== "pending") continue;
+      if (!DEFAULT_CALENDAR_WHITELIST.contains(att.uri)) {
+        logger?.warn(`Ignoring attestation from non-whitelisted calendar ${att.uri}`);
+        continue;
+      }
+      try {
+        const upgraded = await new CalendarClient(att.uri, networkLayer, logger).getTimestamp(
+          subStamp.getDigest(),
+          signal
+        );
+        subStamp.merge(upgraded);
+      } catch (err) {
+        if (err instanceof CommitmentNotFoundError) {
+          logger?.debug(`Calendar ${att.uri} has not confirmed yet`);
+          continue;
+        }
+        logger?.warn(
+          `Failed to query ${att.uri}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  const after = detached.serializeToBytes();
+  if (bytesEqFast(before, after)) {
+    throw new UpgradeError("No calendar has confirmed the timestamp yet (Bitcoin not yet mined)");
+  }
+  return Buffer.from(after);
+}
+
+// src/core/verify.ts
+var import_core6 = require("@otskit/core");
+var import_node_crypto2 = require("crypto");
+
 // src/network/esplora.ts
-var import_core3 = require("@otskit/core");
+var import_node_crypto = require("crypto");
+var import_core5 = require("@otskit/core");
 var PUBLIC_ESPLORA_URL = "https://blockstream.info/api";
 var MAX_ESPLORA_RESPONSE_SIZE = 1e5;
+var RAW_HEADER_SIZE = 80;
 var HEX64_RE = /^[0-9a-f]{64}$/i;
+function sha256dDisplayHex(data) {
+  const first = (0, import_node_crypto.createHash)("sha256").update(data).digest();
+  const second = (0, import_node_crypto.createHash)("sha256").update(first).digest();
+  return Buffer.from(second).reverse().toString("hex");
+}
 var EsploraClient = class {
   #url;
   #networkLayer;
@@ -656,7 +823,7 @@ var EsploraClient = class {
     this.#url = raw.replace(/\/+$/, "");
     this.#logger = options.logger;
   }
-  /** Devuelve el hash (hex 64, minúsculas) del bloque a la altura dada. */
+  /** Returns the block hash (64-char hex, lowercase) at the given height. */
   async blockHash(height, signal) {
     if (!Number.isSafeInteger(height) || height < 0) {
       throw new ValidationError(`block height must be a non-negative safe integer; got ${height}`);
@@ -673,7 +840,7 @@ var EsploraClient = class {
     }
     return text.toLowerCase();
   }
-  /** Devuelve la cabecera del bloque (merkleroot + time) dado su hash. */
+  /** Returns the block header (merkle root + timestamp) for the given hash. */
   async block(hash, signal) {
     if (typeof hash !== "string" || !HEX64_RE.test(hash)) {
       throw new ValidationError("block hash must be a 64-char hex string");
@@ -691,7 +858,7 @@ var EsploraClient = class {
     } catch (err) {
       throw new EsploraResponseError("esplora returned a non-JSON block response", {
         /* v8 ignore next */
-        cause: err instanceof Error ? err : void 0
+        ...err instanceof Error ? { cause: err } : {}
       });
     }
     if (typeof body !== "object" || body === null) {
@@ -706,7 +873,36 @@ var EsploraClient = class {
     }
     return { merkleroot, time };
   }
-  /** Decodifica el cuerpo a texto aplicando el límite de tamaño (fail-closed). */
+  /**
+   * Fetches the raw 80-byte block header for `hash` and self-authenticates it:
+   * sha256d(rawHeader) reversed must equal `hash`. This removes trust in the explorer's
+   * JSON layer — the raw header is cryptographically bound to the block hash we requested.
+   */
+  async rawBlockHeader(hash, signal) {
+    if (typeof hash !== "string" || !HEX64_RE.test(hash)) {
+      throw new ValidationError("block hash must be a 64-char hex string");
+    }
+    this.#logger?.debug(`Esplora raw header ${hash}`);
+    const response = await this.#networkLayer.request(
+      this.#url,
+      { url: `${this.#url}/block/${hash}/header`, method: "GET", headers: { Accept: "application/octet-stream" } },
+      signal
+    );
+    const data = response.data;
+    if (data.length !== RAW_HEADER_SIZE) {
+      throw new EsploraResponseError(
+        `raw block header must be ${RAW_HEADER_SIZE} bytes; got ${data.length}`
+      );
+    }
+    const actualHash = sha256dDisplayHex(data);
+    if (actualHash !== hash.toLowerCase()) {
+      throw new EsploraResponseError(
+        `raw block header hash mismatch: expected ${hash.toLowerCase()}, got ${actualHash}`
+      );
+    }
+    return data;
+  }
+  /** Decodes the response body as text, enforcing the size limit (fail-closed). */
   #decode(data) {
     if (data.length > MAX_ESPLORA_RESPONSE_SIZE) {
       throw new EsploraResponseError(
@@ -717,22 +913,117 @@ var EsploraClient = class {
       return new TextDecoder("utf-8", { fatal: true }).decode(data);
     } catch (cause) {
       throw new EsploraResponseError("esplora response contains invalid UTF-8 bytes", {
-        cause: cause instanceof Error ? cause : void 0
+        ...cause instanceof Error ? { cause } : {}
       });
     }
   }
 };
 async function verifyTimestampAttestation(digest, attestation, explorer, signal) {
   if (attestation.kind !== "bitcoin" && attestation.kind !== "litecoin") {
-    throw new import_core3.VerificationError(`cannot verify a '${attestation.kind}' attestation against the chain`);
+    throw new import_core5.VerificationError(`cannot verify a '${attestation.kind}' attestation against the chain`);
   }
   const hash = await explorer.blockHash(attestation.height, signal);
-  const header = await explorer.block(hash, signal);
-  return (0, import_core3.verifyAgainstBlockheader)(digest, header);
+  const rawHeader = await explorer.rawBlockHeader(hash, signal);
+  return (0, import_core5.verifyAgainstRawHeader)(digest, rawHeader);
 }
 
-// src/core/orchestration.ts
-var import_node_crypto = require("crypto");
+// src/core/verify.ts
+var MAX_BITCOIN_ATTESTATIONS = 10;
+function timingSafeEq(a, b) {
+  if (a.length !== b.length) return false;
+  return (0, import_node_crypto2.timingSafeEqual)(a, b);
+}
+async function orchestrateVerify(proof, networkLayer, originalDataHash, logger, signal, esploraUrl) {
+  let detached;
+  try {
+    detached = import_core6.DetachedTimestampFile.deserialize(new Uint8Array(proof));
+  } catch (cause) {
+    throw new ValidationError("Invalid .ots proof format", {
+      ...cause instanceof Error ? { cause } : {}
+    });
+  }
+  if (detached.fileHashOp instanceof import_core6.OpSHA1 || detached.fileHashOp instanceof import_core6.OpRIPEMD160) {
+    return {
+      status: "invalid",
+      reason: `This proof uses ${detached.fileHashOp.tagName} (a weak hash algorithm). Re-stamp the original file with SHA-256 to get a verifiable proof.`
+    };
+  }
+  if (originalDataHash !== void 0) {
+    let expected;
+    try {
+      expected = validateHash(originalDataHash);
+    } catch (err) {
+      throw new ValidationError(err instanceof Error ? err.message : "Invalid hash format", {
+        ...err instanceof Error ? { cause: err } : {}
+      });
+    }
+    if (!timingSafeEq(expected, detached.fileDigest())) {
+      return {
+        status: "invalid",
+        reason: "File hash does not match proof \u2014 file may have been modified"
+      };
+    }
+  }
+  const allBitcoin = detached.timestamp.allAttestations().filter(({ attestation }) => attestation.kind === "bitcoin");
+  const seenHeights = /* @__PURE__ */ new Set();
+  const deduped = allBitcoin.filter(({ attestation }) => {
+    if (attestation.kind !== "bitcoin") return false;
+    if (seenHeights.has(attestation.height)) {
+      logger?.debug(`Skipping duplicate Bitcoin attestation at height ${attestation.height}`);
+      return false;
+    }
+    seenHeights.add(attestation.height);
+    return true;
+  });
+  const bitcoinAtts = deduped.slice(0, MAX_BITCOIN_ATTESTATIONS);
+  if (deduped.length > MAX_BITCOIN_ATTESTATIONS) {
+    logger?.warn(
+      `Proof has ${deduped.length} unique Bitcoin attestations; verifying only the first ${MAX_BITCOIN_ATTESTATIONS}`
+    );
+  }
+  if (bitcoinAtts.length === 0) {
+    const hasLitecoin = detached.timestamp.allAttestations().some(({ attestation }) => attestation.kind === "litecoin");
+    return {
+      status: "pending",
+      reason: hasLitecoin ? "Litecoin-only attestation is not supported by this client" : "No Bitcoin attestation found \u2014 timestamp not yet confirmed"
+    };
+  }
+  const explorer = new EsploraClient(networkLayer, {
+    ...esploraUrl !== void 0 ? { url: esploraUrl } : {},
+    ...logger !== void 0 ? { logger } : {}
+  });
+  let lastNetworkError;
+  let lastCryptoError;
+  for (const { msg, attestation } of bitcoinAtts) {
+    if (attestation.kind !== "bitcoin") continue;
+    try {
+      const blockTime = await verifyTimestampAttestation(
+        Uint8Array.from(msg).reverse(),
+        attestation,
+        explorer,
+        signal
+      );
+      logger?.info(`Verified against Bitcoin block ${attestation.height}`);
+      return { status: "verified", blockHeight: attestation.height, blockTime };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (err instanceof NetworkError || err instanceof EsploraResponseError) {
+        lastNetworkError = message;
+        logger?.warn(`Network error at block ${attestation.height}: ${message}`);
+      } else {
+        lastCryptoError = message;
+        logger?.warn(`Crypto verification failed at block ${attestation.height}: ${message}`);
+      }
+    }
+  }
+  if (lastCryptoError !== void 0) {
+    return { status: "invalid", reason: `Cryptographic verification failed: ${lastCryptoError}` };
+  }
+  return {
+    status: "network_error",
+    reason: `Could not reach Bitcoin blockchain: ${lastNetworkError ?? "unknown error"}`
+  };
+}
 
 // src/security/ssrf.ts
 var import_promises = require("dns/promises");
@@ -751,7 +1042,7 @@ var BLOCKED_CIDRS_V4 = [
 ];
 function ipv4ToUint32(ip) {
   const parts = ip.split(".");
-  return (parseInt(parts[0], 10) << 24 | parseInt(parts[1], 10) << 16 | parseInt(parts[2], 10) << 8 | parseInt(parts[3], 10)) >>> 0;
+  return (Number.parseInt(parts[0], 10) << 24 | Number.parseInt(parts[1], 10) << 16 | Number.parseInt(parts[2], 10) << 8 | Number.parseInt(parts[3], 10)) >>> 0;
 }
 function assertNotPrivateIPv4(ip, calendarUrl) {
   const n = ipv4ToUint32(ip);
@@ -830,206 +1121,6 @@ async function assertSafeCalendarUrl(url, options) {
   }
 }
 
-// src/core/orchestration.ts
-var MAX_BITCOIN_ATTESTATIONS = 10;
-function validateHash(hash) {
-  if (typeof hash === "string") {
-    const hex = hash.trim().toLowerCase();
-    if (!/^[0-9a-f]{64}$/.test(hex)) {
-      throw new ValidationError("Hash must be a 64-character hex string (SHA-256)");
-    }
-    return Uint8Array.from(Buffer.from(hex, "hex"));
-  }
-  if (hash.length !== 32) {
-    throw new ValidationError("Hash must be exactly 32 bytes (SHA-256)");
-  }
-  return Uint8Array.from(hash);
-}
-function secureNonce(n) {
-  const bytes = new Uint8Array(n);
-  if (!globalThis.crypto?.getRandomValues) {
-    throw new Error("secure RNG unavailable: globalThis.crypto.getRandomValues is required");
-  }
-  globalThis.crypto.getRandomValues(bytes);
-  return bytes;
-}
-function timingSafeEq(a, b) {
-  if (a.length !== b.length) return false;
-  return (0, import_node_crypto.timingSafeEqual)(a, b);
-}
-var bytesEqFast = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)) === 0;
-async function orchestrateStamp(hash, calendars, networkLayer, logger, signal, minimumSuccessfulSubmissions = 2, allowPrivateCalendars = false) {
-  if (calendars.length === 0) {
-    throw new ValidationError("at least one calendar is required to stamp");
-  }
-  if (!Number.isInteger(minimumSuccessfulSubmissions) || minimumSuccessfulSubmissions < 1) {
-    throw new ValidationError("minimumSuccessfulSubmissions must be an integer >= 1");
-  }
-  if (minimumSuccessfulSubmissions > calendars.length) {
-    throw new ValidationError(
-      `minimumSuccessfulSubmissions (${minimumSuccessfulSubmissions}) cannot exceed the number of calendars (${calendars.length})`
-    );
-  }
-  await Promise.all(
-    calendars.map((url) => assertSafeCalendarUrl(url, { allowPrivate: allowPrivateCalendars }))
-  );
-  const digest = validateHash(hash);
-  logger?.info(`Starting stamp for ${Buffer.from(digest).toString("hex")}`);
-  const detached = import_core4.DetachedTimestampFile.fromHash(new import_core4.OpSHA256(), digest);
-  const nonceAppended = detached.timestamp.add(new import_core4.OpAppend(secureNonce(16)));
-  const merkleRoot = nonceAppended.add(new import_core4.OpSHA256());
-  const merkleTip = (0, import_core4.makeMerkleTree)([merkleRoot]);
-  const results = await Promise.allSettled(
-    calendars.map((url) => new CalendarClient(url, networkLayer, logger).submit(merkleTip.getDigest(), signal))
-  );
-  const successful = [];
-  const failed = [];
-  results.forEach((r, i) => {
-    const calendar = calendars[i];
-    if (r.status === "fulfilled") {
-      merkleTip.merge(r.value);
-      successful.push({ calendar });
-      logger?.info(`Submitted to ${calendar}`);
-    } else {
-      const error = r.reason instanceof Error ? r.reason : new Error(String(r.reason));
-      failed.push({ calendar, error });
-      logger?.warn(`Failed to submit to ${calendar}: ${error.message}`);
-    }
-  });
-  if (successful.length < minimumSuccessfulSubmissions) {
-    throw new StampError(
-      `Insufficient successful submissions (${successful.length}/${minimumSuccessfulSubmissions} required)`,
-      successful,
-      failed
-    );
-  }
-  return Buffer.from(detached.serializeToBytes());
-}
-async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, logger, signal) {
-  let detached;
-  try {
-    detached = import_core4.DetachedTimestampFile.deserialize(new Uint8Array(incompleteProof));
-  } catch (error) {
-    throw new ValidationError("Invalid .ots proof format", {
-      /* v8 ignore next */
-      cause: error instanceof Error ? error : void 0
-    });
-  }
-  if (detached.timestamp.isTimestampComplete()) {
-    logger?.info("Proof already complete; nothing to upgrade");
-    return Buffer.from(incompleteProof);
-  }
-  const before = detached.serializeToBytes();
-  for (const subStamp of detached.timestamp.directlyVerified()) {
-    if (subStamp.isTimestampComplete()) continue;
-    for (const att of subStamp.attestations) {
-      if (att.kind !== "pending") continue;
-      if (!DEFAULT_CALENDAR_WHITELIST.contains(att.uri)) {
-        logger?.warn(`Ignoring attestation from non-whitelisted calendar ${att.uri}`);
-        continue;
-      }
-      try {
-        const upgraded = await new CalendarClient(att.uri, networkLayer, logger).getTimestamp(
-          subStamp.getDigest(),
-          signal
-        );
-        subStamp.merge(upgraded);
-      } catch (err) {
-        if (err instanceof CommitmentNotFoundError) {
-          logger?.debug(`Calendar ${att.uri} has not confirmed yet`);
-          continue;
-        }
-        logger?.warn(`Failed to query ${att.uri}: ${err instanceof Error ? err.message : String(err)}`);
-      }
-    }
-  }
-  const after = detached.serializeToBytes();
-  if (bytesEqFast(before, after)) {
-    throw new UpgradeError("No calendar has confirmed the timestamp yet (Bitcoin not yet mined)");
-  }
-  return Buffer.from(after);
-}
-async function orchestrateVerify(proof, networkLayer, originalDataHash, logger, signal) {
-  let detached;
-  try {
-    detached = import_core4.DetachedTimestampFile.deserialize(new Uint8Array(proof));
-  } catch (cause) {
-    throw new ValidationError("Invalid .ots proof format", {
-      cause: cause instanceof Error ? cause : void 0
-    });
-  }
-  if (originalDataHash !== void 0) {
-    let expected;
-    try {
-      expected = validateHash(originalDataHash);
-    } catch (err) {
-      throw new ValidationError(
-        err instanceof Error ? err.message : "Invalid hash format",
-        { cause: err instanceof Error ? err : void 0 }
-      );
-    }
-    if (!timingSafeEq(expected, detached.fileDigest())) {
-      return { status: "invalid", reason: "File hash does not match proof \u2014 file may have been modified" };
-    }
-  }
-  const allBitcoin = detached.timestamp.allAttestations().filter(({ attestation }) => attestation.kind === "bitcoin");
-  const seenHeights = /* @__PURE__ */ new Set();
-  const deduped = allBitcoin.filter(({ attestation }) => {
-    if (attestation.kind !== "bitcoin") return false;
-    if (seenHeights.has(attestation.height)) {
-      logger?.debug(`Skipping duplicate Bitcoin attestation at height ${attestation.height}`);
-      return false;
-    }
-    seenHeights.add(attestation.height);
-    return true;
-  });
-  const bitcoinAtts = deduped.slice(0, MAX_BITCOIN_ATTESTATIONS);
-  if (deduped.length > MAX_BITCOIN_ATTESTATIONS) {
-    logger?.warn(
-      `Proof has ${deduped.length} unique Bitcoin attestations; verifying only the first ${MAX_BITCOIN_ATTESTATIONS}`
-    );
-  }
-  if (bitcoinAtts.length === 0) {
-    const hasLitecoin = detached.timestamp.allAttestations().some(({ attestation }) => attestation.kind === "litecoin");
-    return {
-      status: "pending",
-      reason: hasLitecoin ? "Litecoin-only attestation is not supported by this client" : "No Bitcoin attestation found \u2014 timestamp not yet confirmed"
-    };
-  }
-  const explorer = new EsploraClient(networkLayer);
-  let lastNetworkError;
-  let lastCryptoError;
-  for (const { msg, attestation } of bitcoinAtts) {
-    if (attestation.kind !== "bitcoin") continue;
-    try {
-      const blockTime = await verifyTimestampAttestation(
-        Uint8Array.from(msg).reverse(),
-        attestation,
-        explorer,
-        signal
-      );
-      logger?.info(`Verified against Bitcoin block ${attestation.height}`);
-      return { status: "verified", blockHeight: attestation.height, blockTime };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (err instanceof NetworkError || err instanceof EsploraResponseError) {
-        lastNetworkError = message;
-        logger?.warn(`Network error at block ${attestation.height}: ${message}`);
-      } else {
-        lastCryptoError = message;
-        logger?.warn(`Crypto verification failed at block ${attestation.height}: ${message}`);
-      }
-    }
-  }
-  if (lastCryptoError !== void 0) {
-    return { status: "invalid", reason: `Cryptographic verification failed: ${lastCryptoError}` };
-  }
-  return {
-    status: "network_error",
-    reason: `Could not reach Bitcoin blockchain: ${lastNetworkError ?? "unknown error"}`
-  };
-}
-
 // src/client.ts
 var OpenTimestampsClient = class {
   calendars;
@@ -1038,20 +1129,32 @@ var OpenTimestampsClient = class {
   globalSignal;
   minimumSuccessfulSubmissions;
   allowPrivateCalendars;
+  esploraUrl;
   /**
    * Create a new OpenTimestamps client
-   * 
+   *
    * @param options Client configuration options
    */
   constructor(options = {}) {
+    this.logger = options.logger;
     if (!options.calendars || options.calendars.length === 0) {
       this.calendars = DEFAULT_CALENDARS;
       this.logger?.info("No calendars provided, using defaults");
     } else {
       this.calendars = options.calendars;
     }
-    this.minimumSuccessfulSubmissions = options.minimumSuccessfulSubmissions ?? 2;
+    const minSubs = options.minimumSuccessfulSubmissions ?? 2;
+    if (!Number.isInteger(minSubs) || minSubs < 1) {
+      throw new ValidationError("minimumSuccessfulSubmissions must be an integer >= 1");
+    }
+    if (minSubs > this.calendars.length) {
+      throw new ValidationError(
+        `minimumSuccessfulSubmissions (${minSubs}) cannot exceed the number of calendars (${this.calendars.length})`
+      );
+    }
+    this.minimumSuccessfulSubmissions = minSubs;
     this.allowPrivateCalendars = options.allowPrivateCalendars ?? false;
+    this.esploraUrl = options.esploraUrl;
     const resilienceConfig = {
       ...DEFAULT_RESILIENCE,
       ...options.resilience,
@@ -1068,23 +1171,22 @@ var OpenTimestampsClient = class {
         ...options.resilience?.circuitBreaker
       }
     };
-    this.logger = options.logger;
-    this.globalSignal = options.signal;
+    if (options.signal !== void 0) this.globalSignal = options.signal;
     const internalOptions = options;
     this.networkLayer = internalOptions._networkLayer ?? new ResilientNetworkLayer(resilienceConfig, this.logger);
     this.logger?.info(`OpenTimestamps client initialized with ${this.calendars.length} calendars`);
   }
   /**
    * Create a timestamp by submitting a hash to calendar servers
-   * 
+   *
    * @param hash SHA-256 hash of the data to timestamp (as Buffer or hex string)
    * @param options Operation-specific options
    * @returns Initial .ots proof with pending attestations
-   * 
+   *
    * @throws {ValidationError} If the hash is invalid
    * @throws {StampError} If submission fails to all calendars
    * @throws {NetworkError} If network errors occur
-   * 
+   *
    * @example
    * ```typescript
    * const hash = crypto.createHash('sha256').update('my data').digest()
@@ -1094,34 +1196,36 @@ var OpenTimestampsClient = class {
    */
   async stamp(hash, options) {
     const signal = options?.signal || this.globalSignal;
-    return orchestrateStamp(
+    const allowPrivate = this.allowPrivateCalendars;
+    const bytes = await orchestrateStamp(
       hash,
       this.calendars,
       this.networkLayer,
+      (url) => assertSafeCalendarUrl(url, { allowPrivate }),
       this.logger,
       signal,
-      this.minimumSuccessfulSubmissions,
-      this.allowPrivateCalendars
+      this.minimumSuccessfulSubmissions
     );
+    return Buffer.from(bytes);
   }
   /**
    * Upgrade an incomplete timestamp proof by querying calendars for Bitcoin confirmation
-   * 
+   *
    * @param incompleteProof The initial .ots proof returned by stamp()
    * @param options Operation-specific options
    * @returns Upgraded .ots proof with Bitcoin attestation (if available)
-   * 
+   *
    * @throws {ValidationError} If the proof format is invalid
    * @throws {UpgradeError} If no calendar has confirmed the timestamp yet
    * @throws {NetworkError} If network errors occur
-   * 
+   *
    * @example
    * ```typescript
    * // Proof already has pending attestations from stamp()
    * const upgradedProof = await client.upgrade(incompleteProof)
-   * 
+   *
    * // If upgrade throws UpgradeError, Bitcoin hasn't confirmed yet
-   * // Retry later (typically 10-60 minutes after stamp)
+   * // Retry later (typically ~60 minutes after stamp)
    * ```
    */
   async upgrade(incompleteProof, options) {
@@ -1136,15 +1240,15 @@ var OpenTimestampsClient = class {
   }
   /**
    * Verify a complete timestamp proof against the Bitcoin blockchain
-   * 
+   *
    * @param proof The complete .ots proof with Bitcoin attestation
    * @param originalDataHash Optional: the original data hash to verify against
    * @returns Verification result with block details
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.verify(completeProof, originalHash)
-   * 
+   *
    * if (result.valid) {
    *   console.log(`Timestamp confirmed in Bitcoin block ${result.blockHeight}`)
    *   console.log(`Block timestamp: ${new Date(result.timestamp! * 1000)}`)
@@ -1154,12 +1258,19 @@ var OpenTimestampsClient = class {
    * ```
    */
   async verify(proof, originalDataHash) {
-    return orchestrateVerify(proof, this.networkLayer, originalDataHash, this.logger, this.globalSignal);
+    return orchestrateVerify(
+      proof,
+      this.networkLayer,
+      originalDataHash,
+      this.logger,
+      this.globalSignal,
+      this.esploraUrl
+    );
   }
   /**
    * Get the current state of the circuit breaker for a calendar
    * Useful for monitoring and debugging
-   * 
+   *
    * @param calendarUrl The calendar URL to check
    * @returns Circuit state: 'CLOSED', 'OPEN', or 'HALF_OPEN' (undefined if not yet initialized)
    */
@@ -1169,7 +1280,7 @@ var OpenTimestampsClient = class {
   /**
    * Reset the circuit breaker for a specific calendar
    * Use this to manually recover a calendar that has been marked as failing
-   * 
+   *
    * @param calendarUrl The calendar URL to reset
    */
   resetCircuit(calendarUrl) {
@@ -1187,19 +1298,19 @@ var OpenTimestampsClient = class {
 };
 
 // src/index.ts
-var import_core5 = require("@otskit/core");
-var import_core6 = require("@otskit/core");
+var import_core7 = require("@otskit/core");
+var import_core8 = require("@otskit/core");
 
 // src/utils/hash.ts
-var import_crypto = require("crypto");
-var import_fs = require("fs");
+var import_node_crypto3 = require("crypto");
+var import_node_fs = require("fs");
 function hashBuffer(data) {
-  return (0, import_crypto.createHash)("sha256").update(data).digest();
+  return (0, import_node_crypto3.createHash)("sha256").update(data).digest();
 }
 function hashFile(path) {
   return new Promise((resolve, reject) => {
-    const hash = (0, import_crypto.createHash)("sha256");
-    (0, import_fs.createReadStream)(path).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve(hash.digest())).on("error", reject);
+    const hash = (0, import_node_crypto3.createHash)("sha256");
+    (0, import_node_fs.createReadStream)(path).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve(hash.digest())).on("error", reject);
   });
 }
 // Annotate the CommonJS export names for ESM import in node: