@otskit/client 0.1.3 → 0.3.0

package/dist/index.cjs

@@ -39,17 +39,23 @@ __export(index_exports, {
   OpenTimestampsClientError: () => OpenTimestampsClientError,
   PUBLIC_ESPLORA_URL: () => PUBLIC_ESPLORA_URL,
   ResilientNetworkLayer: () => ResilientNetworkLayer,
+  SizeLimitExceededError: () => SizeLimitExceededError,
   StampError: () => StampError,
   Timestamp: () => Timestamp,
   UpgradeError: () => UpgradeError,
   UrlWhitelist: () => UrlWhitelist,
   ValidationError: () => ValidationError,
+  assertSafeCalendarUrl: () => assertSafeCalendarUrl,
+  hashBuffer: () => hashBuffer,
+  hashFile: () => hashFile,
+  isVerified: () => isVerified,
   verifyAgainstBlockheader: () => verifyAgainstBlockheader,
   verifyTimestampAttestation: () => verifyTimestampAttestation
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/types.ts
+var isVerified = (r) => r.status === "verified";
 var DEFAULT_CALENDARS = [
   "https://alice.btc.calendar.opentimestamps.org",
   "https://bob.btc.calendar.opentimestamps.org",
@@ -119,6 +125,18 @@ var CalendarResponseTooLargeError = class extends NetworkError {
 };
 var EsploraResponseError = class extends NetworkError {
 };
+var SizeLimitExceededError = class extends NetworkError {
+  maxBytes;
+  actualBytes;
+  constructor(maxBytes, actualBytes, options) {
+    super(
+      actualBytes === void 0 ? `Response size exceeds limit of ${maxBytes} bytes` : `Response size ${actualBytes} bytes exceeds limit of ${maxBytes} bytes`,
+      options
+    );
+    this.maxBytes = maxBytes;
+    this.actualBytes = actualBytes;
+  }
+};
 
 // src/network/circuit-breaker.ts
 var CircuitState = /* @__PURE__ */ ((CircuitState2) => {
@@ -307,33 +325,62 @@ async function withRetry(fn, options, logger, signal) {
 }
 
 // src/adapters/fetch-adapter.ts
-async function executeRequest(request) {
+function getDeclaredContentLength(response) {
+  const value = response.headers.get("content-length");
+  if (value === null || !/^\d+$/.test(value)) return void 0;
+  const n = Number(value);
+  return Number.isSafeInteger(n) ? n : void 0;
+}
+async function readStreamLimited(body, maxBytes, status) {
+  const reader = body.getReader();
+  const buffer = new Uint8Array(maxBytes);
+  let received = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) return buffer.subarray(0, received);
+      const next = received + value.byteLength;
+      if (next > maxBytes) {
+        await reader.cancel();
+        throw new SizeLimitExceededError(maxBytes, next, { status });
+      }
+      buffer.set(value, received);
+      received = next;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function readResponseBody(response, maxBytes) {
+  const contentLength = getDeclaredContentLength(response);
+  if (contentLength !== void 0 && contentLength > maxBytes) {
+    throw new SizeLimitExceededError(maxBytes, contentLength, { status: response.status });
+  }
+  if (response.body === null) {
+    const ab = await response.arrayBuffer();
+    if (ab.byteLength > maxBytes) {
+      throw new SizeLimitExceededError(maxBytes, ab.byteLength, { status: response.status });
+    }
+    return new Uint8Array(ab);
+  }
+  return readStreamLimited(response.body, maxBytes, response.status);
+}
+async function executeRequest(request, maxBytes) {
   try {
     const response = await globalThis.fetch(request.url, {
       method: request.method,
-      headers: {
-        "Content-Type": "application/octet-stream",
-        ...request.headers
-      },
+      headers: { "Content-Type": "application/octet-stream", ...request.headers },
       body: request.body,
       signal: request.signal
     });
-    const arrayBuffer = await response.arrayBuffer();
-    const data = new Uint8Array(arrayBuffer);
-    return {
-      ok: response.ok,
-      status: response.status,
-      statusText: response.statusText,
-      data
-    };
+    const data = await readResponseBody(response, maxBytes);
+    return { ok: response.ok, status: response.status, statusText: response.statusText, data };
   } catch (error) {
+    if (error instanceof SizeLimitExceededError) throw error;
+    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.name === "AbortError") throw new NetworkError("Request aborted", { 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");
@@ -341,23 +388,24 @@ async function executeRequest(request) {
 }
 function createTimeoutController(timeoutMs, parentSignal) {
   const controller = new AbortController();
-  const timeout = setTimeout(() => {
-    controller.abort(new Error("Timeout"));
-  }, timeoutMs);
+  const timeout = setTimeout(() => controller.abort(new Error("Timeout")), timeoutMs);
+  const onParentAbort = () => {
+    clearTimeout(timeout);
+    parentSignal?.removeEventListener("abort", onParentAbort);
+    controller.abort(parentSignal?.reason);
+  };
+  controller.signal.addEventListener("abort", () => {
+    clearTimeout(timeout);
+    parentSignal?.removeEventListener("abort", onParentAbort);
+  }, { once: true });
   if (parentSignal) {
     if (parentSignal.aborted) {
       clearTimeout(timeout);
       controller.abort(parentSignal.reason);
     } else {
-      parentSignal.addEventListener("abort", () => {
-        clearTimeout(timeout);
-        controller.abort(parentSignal.reason);
-      });
+      parentSignal.addEventListener("abort", onParentAbort, { once: true });
     }
   }
-  controller.signal.addEventListener("abort", () => {
-    clearTimeout(timeout);
-  });
   return controller;
 }
 
@@ -389,10 +437,10 @@ var ResilientNetworkLayer = class {
               totalController.signal
             );
             try {
-              const response = await executeRequest({
-                ...request,
-                signal: attemptController.signal
-              });
+              const response = await executeRequest(
+                { ...request, signal: attemptController.signal },
+                this.options.maxResponseBytes ?? 1e5
+              );
               const elapsed = Date.now() - startTime;
               this.logger?.debug(`Request to ${calendarUrl} succeeded in ${elapsed}ms`);
               if (!response.ok) {
@@ -411,8 +459,7 @@ var ResilientNetworkLayer = class {
               }
               return response;
             } finally {
-              attemptController.signal.removeEventListener("abort", () => {
-              });
+              attemptController.abort(new Error("Attempt complete"));
             }
           },
           this.options.retries,
@@ -425,8 +472,7 @@ var ResilientNetworkLayer = class {
       this.logger?.error(`Request to ${calendarUrl} failed after ${elapsed}ms`, error);
       throw error;
     } finally {
-      totalController.signal.removeEventListener("abort", () => {
-      });
+      totalController.abort(new Error("Request complete"));
     }
   }
   /** Get circuit breaker state for a calendar */
@@ -1915,7 +1961,7 @@ var CalendarClient = class {
   url;
   networkLayer;
   logger;
-  /** Envía un digest al calendario y devuelve el Timestamp que lo commit-ea. */
+  /** Envia un digest al calendario y devuelve el Timestamp que lo commit-ea. */
   async submit(digest, signal) {
     assertCommitment(digest);
     this.logger?.debug(`Submitting digest to ${this.url}/digest`);
@@ -1926,7 +1972,7 @@ var CalendarClient = class {
     );
     return this.#parseTimestamp(response.data, digest);
   }
-  /** Pregunta al calendario si tiene un Timestamp más completo para `commitment` (upgrade). */
+  /** Pregunta al calendario si tiene un Timestamp mas completo para `commitment` (upgrade). */
   async getTimestamp(commitment, signal) {
     assertCommitment(commitment);
     const path = `/timestamp/${bytesToHex(commitment)}`;
@@ -1961,43 +2007,79 @@ var CalendarClient = class {
     return timestamp;
   }
 };
-function wildcardToRegExp(pattern) {
-  const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\\\*/g, "[^/]*");
-  return new RegExp(`^${escaped}$`, "i");
+function parseWhitelistPattern(raw) {
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return void 0;
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return void 0;
+  const hostname = parsed.hostname.toLowerCase();
+  const wildcardSuffix = hostname.startsWith("*.") ? hostname.slice(2) : void 0;
+  if (hostname.includes("*") && wildcardSuffix === void 0) return void 0;
+  if (wildcardSuffix !== void 0 && (wildcardSuffix.length === 0 || wildcardSuffix.includes("*"))) return void 0;
+  return {
+    protocol: parsed.protocol,
+    hostname,
+    port: parsed.port,
+    pathname: parsed.pathname,
+    wildcardSuffix
+  };
+}
+function hostnameMatchesPattern(hostname, pattern) {
+  if (pattern.wildcardSuffix === void 0) return hostname === pattern.hostname;
+  if (!hostname.endsWith("." + pattern.wildcardSuffix)) return false;
+  const label = hostname.slice(0, -pattern.wildcardSuffix.length - 1);
+  return label.length > 0 && !label.includes(".");
 }
 var UrlWhitelist = class {
-  #patterns = /* @__PURE__ */ new Set();
+  #patterns = /* @__PURE__ */ new Map();
   constructor(urls) {
     if (urls) {
       for (const u of urls) this.add(u);
     }
   }
-  /** Añade un patrón; si no trae esquema, se añaden las variantes http y https. */
+  /** Anade un patron; si no trae esquema, se anaden las variantes http y https. */
   add(url) {
     if (typeof url !== "string") {
       throw new TypeError("UrlWhitelist: URL must be a string");
     }
     if (url.startsWith("http://") || url.startsWith("https://")) {
-      this.#patterns.add(url);
+      const pattern = parseWhitelistPattern(url);
+      if (pattern !== void 0) this.#patterns.set(url, pattern);
     } else {
-      this.#patterns.add("http://" + url);
-      this.#patterns.add("https://" + url);
+      this.add("http://" + url);
+      this.add("https://" + url);
     }
   }
-  /** Verdadero si `url` casa con algún patrón de la whitelist. */
+  /** Verdadero si `url` casa con algun patron de la whitelist. */
   contains(url) {
-    for (const pattern of this.#patterns) {
-      if (wildcardToRegExp(pattern).test(url)) return true;
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch {
+      return false;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
+    if (parsed.search !== "" || parsed.hash !== "") return false;
+    const hostname = parsed.hostname.toLowerCase();
+    for (const pattern of this.#patterns.values()) {
+      if (parsed.protocol !== pattern.protocol || parsed.port !== pattern.port) continue;
+      if (parsed.pathname !== pattern.pathname) continue;
+      if (hostnameMatchesPattern(hostname, pattern)) return true;
     }
     return false;
   }
   toString() {
-    return `UrlWhitelist([${[...this.#patterns].join(", ")}])`;
+    return `UrlWhitelist([${[...this.#patterns.keys()].join(", ")}])`;
   }
 };
 var DEFAULT_CALENDAR_WHITELIST = new UrlWhitelist([
   "https://*.calendar.opentimestamps.org",
   // Peter Todd
+  "https://*.btc.calendar.opentimestamps.org",
+  // Peter Todd Bitcoin calendars
   "https://*.calendar.eternitywall.com",
   // Eternity Wall
   "https://*.calendar.catallaxy.com"
@@ -2090,7 +2172,13 @@ var EsploraClient = class {
         `esplora response of ${data.length} bytes exceeds limit ${MAX_ESPLORA_RESPONSE_SIZE}`
       );
     }
-    return new TextDecoder("utf-8", { fatal: false }).decode(data);
+    try {
+      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
+      });
+    }
   }
 };
 async function verifyTimestampAttestation(digest, attestation, explorer, signal) {
@@ -2103,6 +2191,106 @@ async function verifyTimestampAttestation(digest, attestation, explorer, signal)
 }
 
 // src/core/orchestration.ts
+var import_node_crypto = require("crypto");
+
+// src/security/ssrf.ts
+var import_promises = require("dns/promises");
+var import_node_net = require("net");
+var BLOCKED_CIDRS_V4 = [
+  { network: 0, mask: 4278190080, label: "0.0.0.0/8 (This Network)" },
+  { network: 167772160, mask: 4278190080, label: "10.0.0.0/8 (RFC 1918)" },
+  { network: 2130706432, mask: 4278190080, label: "127.0.0.0/8 (Loopback)" },
+  { network: 2851995648, mask: 4294901760, label: "169.254.0.0/16 (Link-local/IMDS)" },
+  { network: 2886729728, mask: 4293918720, label: "172.16.0.0/12 (RFC 1918)" },
+  { network: 3232235520, mask: 4294901760, label: "192.168.0.0/16 (RFC 1918)" },
+  { network: 3323068416, mask: 4294836224, label: "198.18.0.0/15 (Benchmarking)" },
+  { network: 3758096384, mask: 4026531840, label: "224.0.0.0/4 (Multicast)" },
+  { network: 4026531840, mask: 4026531840, label: "240.0.0.0/4 (Reserved)" },
+  { network: 4294967295, mask: 4294967295, label: "255.255.255.255 (Broadcast)" }
+];
+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;
+}
+function assertNotPrivateIPv4(ip, calendarUrl) {
+  const n = ipv4ToUint32(ip);
+  for (const cidr of BLOCKED_CIDRS_V4) {
+    if ((n & cidr.mask) >>> 0 === cidr.network) {
+      throw new ValidationError(
+        `Calendar URL "${calendarUrl}" resolves to a private/reserved IPv4 address (${ip} \u2014 ${cidr.label}). Set allowPrivateCalendars: true to override.`
+      );
+    }
+  }
+}
+var BLOCKED_IPV6_PREFIXES = [
+  { prefix: "::1", label: "Loopback" },
+  { prefix: "::", label: "Unspecified" },
+  { prefix: "fc", label: "fc00::/7 (Unique Local)" },
+  { prefix: "fd", label: "fd00::/8 (Unique Local)" },
+  { prefix: "fe8", label: "fe80::/10 (Link-local)" },
+  { prefix: "fe9", label: "fe80::/10 (Link-local)" },
+  { prefix: "fea", label: "fe80::/10 (Link-local)" },
+  { prefix: "feb", label: "fe80::/10 (Link-local)" },
+  { prefix: "ff", label: "ff00::/8 (Multicast)" },
+  { prefix: "::ffff:", label: "IPv4-mapped IPv6" },
+  { prefix: "64:ff9b:", label: "64:ff9b::/96 (NAT64)" },
+  { prefix: "2001:db8", label: "2001:db8::/32 (Documentation)" }
+];
+function assertNotPrivateIPv6(ip, calendarUrl) {
+  const lower = ip.toLowerCase();
+  for (const { prefix, label } of BLOCKED_IPV6_PREFIXES) {
+    if (lower === prefix || lower.startsWith(prefix)) {
+      throw new ValidationError(
+        `Calendar URL "${calendarUrl}" resolves to a private/reserved IPv6 address (${ip} \u2014 ${label}). Set allowPrivateCalendars: true to override.`
+      );
+    }
+  }
+}
+async function assertSafeCalendarUrl(url, options) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new ValidationError(`Calendar URL is not valid: "${url}"`);
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new ValidationError(`Calendar URL must use http or https: "${url}"`);
+  }
+  if (parsed.username || parsed.password) {
+    throw new ValidationError(`Calendar URL must not contain embedded credentials: "${url}"`);
+  }
+  if (options.allowPrivate) return;
+  const hostname = parsed.hostname;
+  const host = hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+  const ipVersion = (0, import_node_net.isIP)(host);
+  if (ipVersion === 4) {
+    assertNotPrivateIPv4(host, url);
+    return;
+  }
+  if (ipVersion === 6) {
+    assertNotPrivateIPv6(host, url);
+    return;
+  }
+  let addresses;
+  try {
+    addresses = await (0, import_promises.lookup)(hostname, { all: true });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ValidationError(
+      `Calendar URL hostname "${hostname}" could not be resolved: ${message}`
+    );
+  }
+  if (addresses.length === 0) {
+    throw new ValidationError(`Calendar URL hostname "${hostname}" resolved to no addresses`);
+  }
+  for (const { address, family } of addresses) {
+    if (family === 4) assertNotPrivateIPv4(address, url);
+    else if (family === 6) assertNotPrivateIPv6(address, url);
+  }
+}
+
+// src/core/orchestration.ts
+var MAX_BITCOIN_ATTESTATIONS = 10;
 function validateHash(hash) {
   if (typeof hash === "string") {
     const hex = hash.trim().toLowerCase();
@@ -2124,19 +2312,12 @@ function secureNonce(n) {
   globalThis.crypto.getRandomValues(bytes);
   return bytes;
 }
-var bytesEq = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)) === 0;
-function assertHttpUrl(url, label) {
-  let parsed;
-  try {
-    parsed = new URL(url);
-  } catch {
-    throw new ValidationError(`${label} is not a valid URL: ${url}`);
-  }
-  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-    throw new ValidationError(`${label} must use http(s): ${url}`);
-  }
+function timingSafeEq(a, b) {
+  if (a.length !== b.length) return false;
+  return (0, import_node_crypto.timingSafeEqual)(a, b);
 }
-async function orchestrateStamp(hash, calendars, networkLayer, logger, signal, minimumSuccessfulSubmissions = 2) {
+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");
   }
@@ -2148,7 +2329,9 @@ async function orchestrateStamp(hash, calendars, networkLayer, logger, signal, m
       `minimumSuccessfulSubmissions (${minimumSuccessfulSubmissions}) cannot exceed the number of calendars (${calendars.length})`
     );
   }
-  for (const url of calendars) assertHttpUrl(url, "calendar");
+  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 = DetachedTimestampFile.fromHash(new OpSHA256(), digest);
@@ -2220,7 +2403,7 @@ async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, log
     }
   }
   const after = detached.serializeToBytes();
-  if (bytesEq(before, after)) {
+  if (bytesEqFast(before, after)) {
     throw new UpgradeError("No calendar has confirmed the timestamp yet (Bitcoin not yet mined)");
   }
   return Buffer.from(after);
@@ -2229,42 +2412,81 @@ async function orchestrateVerify(proof, networkLayer, originalDataHash, logger,
   let detached;
   try {
     detached = DetachedTimestampFile.deserialize(new Uint8Array(proof));
-  } catch {
-    return { valid: false, error: "Invalid .ots proof format" };
+  } 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) {
-      return { valid: false, error: err instanceof Error ? err.message : "Invalid hash format" };
+      throw new ValidationError(
+        err instanceof Error ? err.message : "Invalid hash format",
+        { cause: err instanceof Error ? err : void 0 }
+      );
     }
-    if (!bytesEq(expected, detached.fileDigest())) {
-      return { valid: false, error: "File hash does not match proof" };
+    if (!timingSafeEq(expected, detached.fileDigest())) {
+      return { status: "invalid", reason: "File hash does not match proof \u2014 file may have been modified" };
     }
   }
-  const bitcoinAtts = detached.timestamp.allAttestations().filter(({ attestation }) => attestation.kind === "bitcoin");
+  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");
-    if (hasLitecoin) {
-      return { valid: false, error: "Litecoin verification is not supported by this client" };
-    }
-    return { valid: false, error: "No Bitcoin attestation found (timestamp not yet confirmed)" };
+    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 lastError = "";
+  let lastNetworkError;
+  let lastCryptoError;
   for (const { msg, attestation } of bitcoinAtts) {
     if (attestation.kind !== "bitcoin") continue;
     try {
-      const time = await verifyTimestampAttestation(Uint8Array.from(msg).reverse(), attestation, explorer, signal);
+      const blockTime = await verifyTimestampAttestation(
+        Uint8Array.from(msg).reverse(),
+        attestation,
+        explorer,
+        signal
+      );
       logger?.info(`Verified against Bitcoin block ${attestation.height}`);
-      return { valid: true, blockHeight: attestation.height, timestamp: time };
+      return { status: "verified", blockHeight: attestation.height, blockTime };
     } catch (err) {
-      lastError = err instanceof Error ? err.message : String(err);
-      logger?.warn(`Bitcoin attestation at height ${attestation.height} failed: ${lastError}`);
+      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}`);
+      }
     }
   }
-  return { valid: false, error: `Could not verify against the Bitcoin blockchain: ${lastError}` };
+  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
@@ -2274,6 +2496,7 @@ var OpenTimestampsClient = class {
   logger;
   globalSignal;
   minimumSuccessfulSubmissions;
+  allowPrivateCalendars;
   /**
    * Create a new OpenTimestamps client
    * 
@@ -2287,6 +2510,7 @@ var OpenTimestampsClient = class {
       this.calendars = options.calendars;
     }
     this.minimumSuccessfulSubmissions = options.minimumSuccessfulSubmissions ?? 2;
+    this.allowPrivateCalendars = options.allowPrivateCalendars ?? false;
     const resilienceConfig = {
       ...DEFAULT_RESILIENCE,
       ...options.resilience,
@@ -2305,7 +2529,8 @@ var OpenTimestampsClient = class {
     };
     this.logger = options.logger;
     this.globalSignal = options.signal;
-    this.networkLayer = options.networkLayer ?? new ResilientNetworkLayer(resilienceConfig, this.logger);
+    const internalOptions = options;
+    this.networkLayer = internalOptions._networkLayer ?? new ResilientNetworkLayer(resilienceConfig, this.logger);
     this.logger?.info(`OpenTimestamps client initialized with ${this.calendars.length} calendars`);
   }
   /**
@@ -2334,7 +2559,8 @@ var OpenTimestampsClient = class {
       this.networkLayer,
       this.logger,
       signal,
-      this.minimumSuccessfulSubmissions
+      this.minimumSuccessfulSubmissions,
+      this.allowPrivateCalendars
     );
   }
   /**
@@ -2418,6 +2644,19 @@ var OpenTimestampsClient = class {
     this.networkLayer.resetAllCircuits();
   }
 };
+
+// src/utils/hash.ts
+var import_crypto = require("crypto");
+var import_fs = require("fs");
+function hashBuffer(data) {
+  return (0, import_crypto.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);
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CalendarClient,
@@ -2439,11 +2678,16 @@ var OpenTimestampsClient = class {
   OpenTimestampsClientError,
   PUBLIC_ESPLORA_URL,
   ResilientNetworkLayer,
+  SizeLimitExceededError,
   StampError,
   Timestamp,
   UpgradeError,
   UrlWhitelist,
   ValidationError,
+  assertSafeCalendarUrl,
+  hashBuffer,
+  hashFile,
+  isVerified,
   verifyAgainstBlockheader,
   verifyTimestampAttestation
 });