@otskit/client 0.4.0 → 0.5.0

package/README.md

@@ -32,7 +32,7 @@
 
 ### Developer Experience
 - **TypeScript-first** — Strict types throughout; full IntelliSense for every option and error
-- **Multi-runtime** — Node.js 18+, browsers, and edge runtimes (uses the standard `fetch` API)
+- **Node.js 20+** — Requires Node.js; uses native `crypto`, `dns`, and `net` APIs not available in browsers or edge runtimes
 - **Tree-shakeable** — Dual ESM/CJS build, zero runtime dependencies
 - **`AbortController` support** — Cancel any in-flight operation at any level
 - **Observable** — Drop-in `Logger` interface compatible with `console`, `pino`, `winston`, etc.

package/dist/index.cjs

@@ -85,7 +85,7 @@ 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 +103,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 +130,7 @@ var SizeLimitExceededError = class extends NetworkError {
       options
     );
     this.maxBytes = maxBytes;
-    this.actualBytes = actualBytes;
+    if (actualBytes !== void 0) this.actualBytes = actualBytes;
   }
 };
 
@@ -182,7 +182,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 +282,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 +373,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 };
@@ -515,7 +523,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 +534,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 +556,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 +586,7 @@ function parseWhitelistPattern(raw) {
     hostname,
     port: parsed.port,
     pathname: parsed.pathname,
-    wildcardSuffix
+    ...wildcardSuffix !== void 0 ? { wildcardSuffix } : {}
   };
 }
 function hostnameMatchesPattern(hostname, pattern) {
@@ -594,20 +602,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 {
@@ -633,10 +647,17 @@ var DEFAULT_CALENDAR_WHITELIST = new UrlWhitelist([...import_core2.TRUSTED_CALEN
 var DEFAULT_AGGREGATORS = [...import_core2.DEFAULT_AGGREGATOR_URLS];
 
 // src/network/esplora.ts
+var import_node_crypto = require("crypto");
 var import_core3 = 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 +677,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 +694,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 +712,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 +727,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,7 +767,7 @@ 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 } : {}
       });
     }
   }
@@ -727,12 +777,12 @@ async function verifyTimestampAttestation(digest, attestation, explorer, signal)
     throw new import_core3.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_core3.verifyAgainstRawHeader)(digest, rawHeader);
 }
 
 // src/core/orchestration.ts
-var import_node_crypto = require("crypto");
+var import_node_crypto2 = require("crypto");
 
 // src/security/ssrf.ts
 var import_promises = require("dns/promises");
@@ -855,7 +905,7 @@ function secureNonce(n) {
 }
 function timingSafeEq(a, b) {
   if (a.length !== b.length) return false;
-  return (0, import_node_crypto.timingSafeEqual)(a, b);
+  return (0, import_node_crypto2.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) {
@@ -912,7 +962,7 @@ async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, log
   } catch (error) {
     throw new ValidationError("Invalid .ots proof format", {
       /* v8 ignore next */
-      cause: error instanceof Error ? error : void 0
+      ...error instanceof Error ? { cause: error } : {}
     });
   }
   if (detached.timestamp.isTimestampComplete()) {
@@ -949,15 +999,21 @@ async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, log
   }
   return Buffer.from(after);
 }
-async function orchestrateVerify(proof, networkLayer, originalDataHash, logger, signal) {
+async function orchestrateVerify(proof, networkLayer, originalDataHash, logger, signal, esploraUrl) {
   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
+      ...cause instanceof Error ? { cause } : {}
     });
   }
+  if (detached.fileHashOp instanceof import_core4.OpSHA1 || detached.fileHashOp instanceof import_core4.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 {
@@ -965,7 +1021,7 @@ async function orchestrateVerify(proof, networkLayer, originalDataHash, logger,
     } catch (err) {
       throw new ValidationError(
         err instanceof Error ? err.message : "Invalid hash format",
-        { cause: err instanceof Error ? err : void 0 }
+        { ...err instanceof Error ? { cause: err } : {} }
       );
     }
     if (!timingSafeEq(expected, detached.fileDigest())) {
@@ -996,7 +1052,10 @@ async function orchestrateVerify(proof, networkLayer, originalDataHash, logger,
       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);
+  const explorer = new EsploraClient(networkLayer, {
+    ...esploraUrl !== void 0 ? { url: esploraUrl } : {},
+    ...logger !== void 0 ? { logger } : {}
+  });
   let lastNetworkError;
   let lastCryptoError;
   for (const { msg, attestation } of bitcoinAtts) {
@@ -1038,20 +1097,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,8 +1139,7 @@ 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`);
@@ -1154,7 +1224,7 @@ 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

package/dist/index.d.cts

@@ -4,7 +4,7 @@ export { Attestation, BitcoinAttestation, DetachedTimestampFile, PendingAttestat
 /**
  * Type definitions for the OpenTimestamps Client SDK
  */
-/** Logger interface for observability */
+/** Logger interface for observability. */
 interface Logger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
@@ -39,7 +39,7 @@ interface ResilienceOptions {
     connectTimeoutMs: number;
     retries: RetryOptions;
     circuitBreaker: CircuitBreakerOptions;
-    /** Límite de bytes para el body de la respuesta. Default 100 KB. */
+    /** Maximum bytes allowed in the response body. Defaults to 100 KB. */
     maxResponseBytes?: number;
 }
 /** Client configuration options */
@@ -55,12 +55,18 @@ interface ClientOptions {
     /** Minimum successful calendar submissions required (default: 2) */
     minimumSuccessfulSubmissions?: number;
     /**
-     * Permite URLs de calendario que resuelven a IPs privadas/reservadas.
+     * Base URL for the Esplora block explorer used by verify().
+     * Defaults to Blockstream (https://blockstream.info/api).
+     * Override to use a self-hosted or alternative explorer.
+     */
+    esploraUrl?: string;
+    /**
+     * Allows calendar URLs that resolve to private/reserved IPs.
      *
-     * **No activar en producción.** Útil para testing local o redes corporativas.
+     * **Do not enable in production.** Useful for local testing or corporate networks.
      *
-     * Incluso con `false`, la protección es best-effort contra DNS rebinding (TOCTOU).
-     * Para alta seguridad, complementar con egress filtering a nivel de red.
+     * Even when `false`, protection is best-effort against DNS rebinding (TOCTOU).
+     * For high-security environments, complement with network-level egress filtering.
      *
      * @default false
      */
@@ -139,6 +145,7 @@ declare class OpenTimestampsClient {
     private globalSignal?;
     private minimumSuccessfulSubmissions;
     private allowPrivateCalendars;
+    private esploraUrl;
     /**
      * Create a new OpenTimestamps client
      *
@@ -265,7 +272,7 @@ declare class UpgradeError extends OpenTimestampsClientError {
 }
 /** Network-related error (timeout, all retries failed, etc.) */
 declare class NetworkError extends OpenTimestampsClientError {
-    /** HTTP status code, cuando el fallo viene de una respuesta HTTP. */
+    /** HTTP status code when the failure originates from an HTTP response. */
     readonly status?: number;
     constructor(message: string, options?: {
         cause?: Error;
@@ -276,16 +283,16 @@ declare class NetworkError extends OpenTimestampsClientError {
 declare class CircuitBreakerError extends NetworkError {
     constructor(calendar: string);
 }
-/** El calendario no conoce (todavía) el commitment consultado (HTTP 404). */
+/** The calendar does not yet know the queried commitment (HTTP 404). */
 declare class CommitmentNotFoundError extends NetworkError {
 }
-/** La respuesta del calendario supera el límite de tamaño permitido (defensa DoS). */
+/** The calendar response exceeds the allowed size limit (DoS defense). */
 declare class CalendarResponseTooLargeError extends NetworkError {
 }
-/** Respuesta del explorador Esplora inválida: vacía, no-JSON, malformada o demasiado grande (defensa DoS). */
+/** Invalid Esplora response: empty, non-JSON, malformed, or too large (DoS defense). */
 declare class EsploraResponseError extends NetworkError {
 }
-/** La respuesta supera el límite de bytes permitido (defensa DoS). */
+/** Response exceeds the allowed byte limit (DoS defense). */
 declare class SizeLimitExceededError extends NetworkError {
     readonly maxBytes: number;
     readonly actualBytes?: number;
@@ -306,8 +313,7 @@ declare enum CircuitState {
 }
 
 /**
- * Universal fetch adapter para compatibilidad multi-runtime.
- * Funciona en Node.js 18+, browsers y edge runtimes.
+ * Fetch adapter for Node.js 20+.
  */
 interface FetchRequest {
     url: string;
@@ -341,30 +347,33 @@ declare class ResilientNetworkLayer {
 }
 
 /**
- * Cliente de un calendario remoto OpenTimestamps (protocolo OTS real).
+ * Remote OpenTimestamps calendar client (real OTS protocol).
  */
 
-/** Limite de tamano de la respuesta de un calendario (defensa DoS). */
+/** Maximum response size from a calendar server (DoS defense). */
 declare const MAX_CALENDAR_RESPONSE_SIZE = 10000;
-/** Interfaz con un servidor de calendario remoto. */
+/** Interface to a remote calendar server. */
 declare class CalendarClient {
     #private;
     private readonly url;
     private readonly networkLayer;
     private readonly logger?;
     constructor(url: string, networkLayer: ResilientNetworkLayer, logger?: Logger | undefined);
-    /** 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. */
     submit(digest: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
-    /** Pregunta al calendario si tiene un Timestamp mas completo para `commitment` (upgrade). */
+    /** Asks the calendar for a more complete Timestamp for `commitment` (upgrade). */
     getTimestamp(commitment: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
 }
-/** Lista blanca de URLs de calendario de confianza. */
+/** Allowlist of trusted calendar URLs. */
 declare class UrlWhitelist {
     #private;
     constructor(urls?: readonly string[]);
-    /** 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: string): void;
-    /** Verdadero si `url` casa con algun patron de la whitelist. */
+    /** Returns true if `url` matches any pattern in the allowlist. */
     contains(url: string): boolean;
     toString(): string;
 }
@@ -379,32 +388,38 @@ declare const DEFAULT_CALENDAR_WHITELIST: UrlWhitelist;
  */
 declare const DEFAULT_AGGREGATORS: readonly string[];
 
-/** Explorador Esplora público por defecto (Bitcoin mainnet). */
+/** Default public Esplora explorer (Bitcoin mainnet). */
 declare const PUBLIC_ESPLORA_URL = "https://blockstream.info/api";
-/** Límite de tamaño de una respuesta de Esplora (defensa DoS). Una cabecera JSON ronda los cientos de bytes. */
+/** Maximum size of an Esplora response (DoS defense). A JSON block header is a few hundred bytes. */
 declare const MAX_ESPLORA_RESPONSE_SIZE = 100000;
 interface EsploraClientOptions {
-    /** URL base del explorador (por defecto Blockstream). Útil para apuntar a un Esplora de Litecoin. */
+    /** Base URL of the explorer (defaults to Blockstream). Useful for pointing to a Litecoin Esplora. */
     url?: string;
     logger?: Logger;
 }
-/** Cliente de un explorador Esplora remoto. */
+/** Client for a remote Esplora explorer. */
 declare class EsploraClient {
     #private;
     constructor(networkLayer: ResilientNetworkLayer, options?: EsploraClientOptions);
-    /** 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. */
     blockHash(height: number, signal?: AbortSignal): Promise<string>;
-    /** Devuelve la cabecera del bloque (merkleroot + time) dado su hash. */
+    /** Returns the block header (merkle root + timestamp) for the given hash. */
     block(hash: string, signal?: AbortSignal): Promise<BlockHeader>;
+    /**
+     * 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.
+     */
+    rawBlockHeader(hash: string, signal?: AbortSignal): Promise<Uint8Array>;
 }
 /**
- * Verifica una atestación Bitcoin/Litecoin contra la cabecera del bloque correspondiente.
+ * Verifies a Bitcoin/Litecoin attestation against the corresponding block header.
  *
- * `digest` es el commitment final del árbol del timestamp en el punto de la atestación
- * (32 bytes, debe ser el merkleroot del bloque). `explorer` debe apuntar a la cadena de la
- * atestación (Blockstream para Bitcoin; un Esplora de Litecoin para Litecoin). Devuelve el
- * tiempo del bloque (epoch s) en éxito; lanza `VerificationError` si no coincide o si la
- * atestación no es verificable en cadena (`pending`/`unknown`). Fail-closed.
+ * `digest` is the final tree commitment at the attestation point (32 bytes, must equal the
+ * block's merkle root). `explorer` must point to the correct chain (Blockstream for Bitcoin;
+ * a Litecoin Esplora for Litecoin). Returns the block time (epoch seconds) on success;
+ * throws `VerificationError` if the digest does not match or the attestation is not
+ * on-chain verifiable (`pending`/`unknown`). Fail-closed.
  */
 declare function verifyTimestampAttestation(digest: Uint8Array, attestation: Attestation, explorer: EsploraClient, signal?: AbortSignal): Promise<number>;
 
@@ -412,21 +427,21 @@ declare function hashBuffer(data: Buffer | Uint8Array): Buffer;
 declare function hashFile(path: string): Promise<Buffer>;
 
 /**
- * SSRF protection para calendarios configurables por el usuario.
+ * SSRF protection for user-configurable calendar URLs.
  *
- * LIMITACIONES (documentadas intencionalmente):
- * - TOCTOU/DNS rebinding: la validación DNS ocurre ANTES de la conexión.
- *   Un servidor con TTL=0 puede cambiar la IP entre la validación y el fetch.
- *   Mitigación real requiere egress filtering a nivel de red.
- * - IPv4-mapped IPv6 (::ffff:x.x.x.x): se bloquea el prefijo ::ffff:
- *   pero la validación del componente IPv4 depende del formato que devuelva Node.js.
+ * KNOWN LIMITATIONS (documented intentionally):
+ * - TOCTOU / DNS rebinding: DNS validation happens BEFORE the connection.
+ *   A server with TTL=0 can change its IP between validation and the actual fetch.
+ *   Real mitigation requires network-level egress filtering.
+ * - IPv4-mapped IPv6 (::ffff:x.x.x.x): the ::ffff: prefix is blocked but the
+ *   IPv4 component validation depends on the format Node.js returns.
  */
 /**
- * Valida que una URL de calendario es segura para hacer outbound HTTP.
- * Bloquea IPs privadas/reservadas por defecto.
+ * Validates that a calendar URL is safe for outbound HTTP requests.
+ * Blocks private/reserved IPs by default.
  *
- * @param allowPrivate Si true, omite la comprobación de rangos IP.
- *   Útil para testing local o redes corporativas internas.
+ * @param allowPrivate When true, skips the IP range check.
+ *   Useful for local testing or internal corporate networks.
  */
 declare function assertSafeCalendarUrl(url: string, options: {
     allowPrivate: boolean;

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { Attestation, BitcoinAttestation, DetachedTimestampFile, PendingAttestat
 /**
  * Type definitions for the OpenTimestamps Client SDK
  */
-/** Logger interface for observability */
+/** Logger interface for observability. */
 interface Logger {
     debug(message: string, ...args: unknown[]): void;
     info(message: string, ...args: unknown[]): void;
@@ -39,7 +39,7 @@ interface ResilienceOptions {
     connectTimeoutMs: number;
     retries: RetryOptions;
     circuitBreaker: CircuitBreakerOptions;
-    /** Límite de bytes para el body de la respuesta. Default 100 KB. */
+    /** Maximum bytes allowed in the response body. Defaults to 100 KB. */
     maxResponseBytes?: number;
 }
 /** Client configuration options */
@@ -55,12 +55,18 @@ interface ClientOptions {
     /** Minimum successful calendar submissions required (default: 2) */
     minimumSuccessfulSubmissions?: number;
     /**
-     * Permite URLs de calendario que resuelven a IPs privadas/reservadas.
+     * Base URL for the Esplora block explorer used by verify().
+     * Defaults to Blockstream (https://blockstream.info/api).
+     * Override to use a self-hosted or alternative explorer.
+     */
+    esploraUrl?: string;
+    /**
+     * Allows calendar URLs that resolve to private/reserved IPs.
      *
-     * **No activar en producción.** Útil para testing local o redes corporativas.
+     * **Do not enable in production.** Useful for local testing or corporate networks.
      *
-     * Incluso con `false`, la protección es best-effort contra DNS rebinding (TOCTOU).
-     * Para alta seguridad, complementar con egress filtering a nivel de red.
+     * Even when `false`, protection is best-effort against DNS rebinding (TOCTOU).
+     * For high-security environments, complement with network-level egress filtering.
      *
      * @default false
      */
@@ -139,6 +145,7 @@ declare class OpenTimestampsClient {
     private globalSignal?;
     private minimumSuccessfulSubmissions;
     private allowPrivateCalendars;
+    private esploraUrl;
     /**
      * Create a new OpenTimestamps client
      *
@@ -265,7 +272,7 @@ declare class UpgradeError extends OpenTimestampsClientError {
 }
 /** Network-related error (timeout, all retries failed, etc.) */
 declare class NetworkError extends OpenTimestampsClientError {
-    /** HTTP status code, cuando el fallo viene de una respuesta HTTP. */
+    /** HTTP status code when the failure originates from an HTTP response. */
     readonly status?: number;
     constructor(message: string, options?: {
         cause?: Error;
@@ -276,16 +283,16 @@ declare class NetworkError extends OpenTimestampsClientError {
 declare class CircuitBreakerError extends NetworkError {
     constructor(calendar: string);
 }
-/** El calendario no conoce (todavía) el commitment consultado (HTTP 404). */
+/** The calendar does not yet know the queried commitment (HTTP 404). */
 declare class CommitmentNotFoundError extends NetworkError {
 }
-/** La respuesta del calendario supera el límite de tamaño permitido (defensa DoS). */
+/** The calendar response exceeds the allowed size limit (DoS defense). */
 declare class CalendarResponseTooLargeError extends NetworkError {
 }
-/** Respuesta del explorador Esplora inválida: vacía, no-JSON, malformada o demasiado grande (defensa DoS). */
+/** Invalid Esplora response: empty, non-JSON, malformed, or too large (DoS defense). */
 declare class EsploraResponseError extends NetworkError {
 }
-/** La respuesta supera el límite de bytes permitido (defensa DoS). */
+/** Response exceeds the allowed byte limit (DoS defense). */
 declare class SizeLimitExceededError extends NetworkError {
     readonly maxBytes: number;
     readonly actualBytes?: number;
@@ -306,8 +313,7 @@ declare enum CircuitState {
 }
 
 /**
- * Universal fetch adapter para compatibilidad multi-runtime.
- * Funciona en Node.js 18+, browsers y edge runtimes.
+ * Fetch adapter for Node.js 20+.
  */
 interface FetchRequest {
     url: string;
@@ -341,30 +347,33 @@ declare class ResilientNetworkLayer {
 }
 
 /**
- * Cliente de un calendario remoto OpenTimestamps (protocolo OTS real).
+ * Remote OpenTimestamps calendar client (real OTS protocol).
  */
 
-/** Limite de tamano de la respuesta de un calendario (defensa DoS). */
+/** Maximum response size from a calendar server (DoS defense). */
 declare const MAX_CALENDAR_RESPONSE_SIZE = 10000;
-/** Interfaz con un servidor de calendario remoto. */
+/** Interface to a remote calendar server. */
 declare class CalendarClient {
     #private;
     private readonly url;
     private readonly networkLayer;
     private readonly logger?;
     constructor(url: string, networkLayer: ResilientNetworkLayer, logger?: Logger | undefined);
-    /** 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. */
     submit(digest: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
-    /** Pregunta al calendario si tiene un Timestamp mas completo para `commitment` (upgrade). */
+    /** Asks the calendar for a more complete Timestamp for `commitment` (upgrade). */
     getTimestamp(commitment: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
 }
-/** Lista blanca de URLs de calendario de confianza. */
+/** Allowlist of trusted calendar URLs. */
 declare class UrlWhitelist {
     #private;
     constructor(urls?: readonly string[]);
-    /** 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: string): void;
-    /** Verdadero si `url` casa con algun patron de la whitelist. */
+    /** Returns true if `url` matches any pattern in the allowlist. */
     contains(url: string): boolean;
     toString(): string;
 }
@@ -379,32 +388,38 @@ declare const DEFAULT_CALENDAR_WHITELIST: UrlWhitelist;
  */
 declare const DEFAULT_AGGREGATORS: readonly string[];
 
-/** Explorador Esplora público por defecto (Bitcoin mainnet). */
+/** Default public Esplora explorer (Bitcoin mainnet). */
 declare const PUBLIC_ESPLORA_URL = "https://blockstream.info/api";
-/** Límite de tamaño de una respuesta de Esplora (defensa DoS). Una cabecera JSON ronda los cientos de bytes. */
+/** Maximum size of an Esplora response (DoS defense). A JSON block header is a few hundred bytes. */
 declare const MAX_ESPLORA_RESPONSE_SIZE = 100000;
 interface EsploraClientOptions {
-    /** URL base del explorador (por defecto Blockstream). Útil para apuntar a un Esplora de Litecoin. */
+    /** Base URL of the explorer (defaults to Blockstream). Useful for pointing to a Litecoin Esplora. */
     url?: string;
     logger?: Logger;
 }
-/** Cliente de un explorador Esplora remoto. */
+/** Client for a remote Esplora explorer. */
 declare class EsploraClient {
     #private;
     constructor(networkLayer: ResilientNetworkLayer, options?: EsploraClientOptions);
-    /** 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. */
     blockHash(height: number, signal?: AbortSignal): Promise<string>;
-    /** Devuelve la cabecera del bloque (merkleroot + time) dado su hash. */
+    /** Returns the block header (merkle root + timestamp) for the given hash. */
     block(hash: string, signal?: AbortSignal): Promise<BlockHeader>;
+    /**
+     * 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.
+     */
+    rawBlockHeader(hash: string, signal?: AbortSignal): Promise<Uint8Array>;
 }
 /**
- * Verifica una atestación Bitcoin/Litecoin contra la cabecera del bloque correspondiente.
+ * Verifies a Bitcoin/Litecoin attestation against the corresponding block header.
  *
- * `digest` es el commitment final del árbol del timestamp en el punto de la atestación
- * (32 bytes, debe ser el merkleroot del bloque). `explorer` debe apuntar a la cadena de la
- * atestación (Blockstream para Bitcoin; un Esplora de Litecoin para Litecoin). Devuelve el
- * tiempo del bloque (epoch s) en éxito; lanza `VerificationError` si no coincide o si la
- * atestación no es verificable en cadena (`pending`/`unknown`). Fail-closed.
+ * `digest` is the final tree commitment at the attestation point (32 bytes, must equal the
+ * block's merkle root). `explorer` must point to the correct chain (Blockstream for Bitcoin;
+ * a Litecoin Esplora for Litecoin). Returns the block time (epoch seconds) on success;
+ * throws `VerificationError` if the digest does not match or the attestation is not
+ * on-chain verifiable (`pending`/`unknown`). Fail-closed.
  */
 declare function verifyTimestampAttestation(digest: Uint8Array, attestation: Attestation, explorer: EsploraClient, signal?: AbortSignal): Promise<number>;
 
@@ -412,21 +427,21 @@ declare function hashBuffer(data: Buffer | Uint8Array): Buffer;
 declare function hashFile(path: string): Promise<Buffer>;
 
 /**
- * SSRF protection para calendarios configurables por el usuario.
+ * SSRF protection for user-configurable calendar URLs.
  *
- * LIMITACIONES (documentadas intencionalmente):
- * - TOCTOU/DNS rebinding: la validación DNS ocurre ANTES de la conexión.
- *   Un servidor con TTL=0 puede cambiar la IP entre la validación y el fetch.
- *   Mitigación real requiere egress filtering a nivel de red.
- * - IPv4-mapped IPv6 (::ffff:x.x.x.x): se bloquea el prefijo ::ffff:
- *   pero la validación del componente IPv4 depende del formato que devuelva Node.js.
+ * KNOWN LIMITATIONS (documented intentionally):
+ * - TOCTOU / DNS rebinding: DNS validation happens BEFORE the connection.
+ *   A server with TTL=0 can change its IP between validation and the actual fetch.
+ *   Real mitigation requires network-level egress filtering.
+ * - IPv4-mapped IPv6 (::ffff:x.x.x.x): the ::ffff: prefix is blocked but the
+ *   IPv4 component validation depends on the format Node.js returns.
  */
 /**
- * Valida que una URL de calendario es segura para hacer outbound HTTP.
- * Bloquea IPs privadas/reservadas por defecto.
+ * Validates that a calendar URL is safe for outbound HTTP requests.
+ * Blocks private/reserved IPs by default.
  *
- * @param allowPrivate Si true, omite la comprobación de rangos IP.
- *   Útil para testing local o redes corporativas internas.
+ * @param allowPrivate When true, skips the IP range check.
+ *   Useful for local testing or internal corporate networks.
  */
 declare function assertSafeCalendarUrl(url: string, options: {
     allowPrivate: boolean;

package/dist/index.js

@@ -29,7 +29,7 @@ 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);
   }
 };
@@ -47,11 +47,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 {
@@ -74,7 +74,7 @@ var SizeLimitExceededError = class extends NetworkError {
       options
     );
     this.maxBytes = maxBytes;
-    this.actualBytes = actualBytes;
+    if (actualBytes !== void 0) this.actualBytes = actualBytes;
   }
 };
 
@@ -126,7 +126,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;
     }
   }
@@ -223,11 +226,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) {
@@ -310,8 +317,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 };
@@ -434,6 +442,8 @@ import {
   DetachedTimestampFile,
   OpSHA256,
   OpAppend,
+  OpSHA1,
+  OpRIPEMD160,
   makeMerkleTree
 } from "@otskit/core";
 
@@ -470,7 +480,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`);
@@ -481,7 +491,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/${bytesToHex(commitment)}`;
@@ -503,7 +513,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(
@@ -533,7 +543,7 @@ function parseWhitelistPattern(raw) {
     hostname,
     port: parsed.port,
     pathname: parsed.pathname,
-    wildcardSuffix
+    ...wildcardSuffix !== void 0 ? { wildcardSuffix } : {}
   };
 }
 function hostnameMatchesPattern(hostname, pattern) {
@@ -549,20 +559,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 {
@@ -588,10 +604,17 @@ var DEFAULT_CALENDAR_WHITELIST = new UrlWhitelist([...TRUSTED_CALENDAR_WHITELIST
 var DEFAULT_AGGREGATORS = [...DEFAULT_AGGREGATOR_URLS];
 
 // src/network/esplora.ts
-import { verifyAgainstBlockheader, VerificationError } from "@otskit/core";
+import { createHash } from "crypto";
+import { verifyAgainstRawHeader, VerificationError } from "@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 = createHash("sha256").update(data).digest();
+  const second = createHash("sha256").update(first).digest();
+  return Buffer.from(second).reverse().toString("hex");
+}
 var EsploraClient = class {
   #url;
   #networkLayer;
@@ -611,7 +634,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}`);
@@ -628,7 +651,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");
@@ -646,7 +669,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) {
@@ -661,7 +684,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(
@@ -672,7 +724,7 @@ 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 } : {}
       });
     }
   }
@@ -682,8 +734,8 @@ async function verifyTimestampAttestation(digest, attestation, explorer, signal)
     throw new 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 verifyAgainstBlockheader(digest, header);
+  const rawHeader = await explorer.rawBlockHeader(hash, signal);
+  return verifyAgainstRawHeader(digest, rawHeader);
 }
 
 // src/core/orchestration.ts
@@ -867,7 +919,7 @@ async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, log
   } catch (error) {
     throw new ValidationError("Invalid .ots proof format", {
       /* v8 ignore next */
-      cause: error instanceof Error ? error : void 0
+      ...error instanceof Error ? { cause: error } : {}
     });
   }
   if (detached.timestamp.isTimestampComplete()) {
@@ -904,15 +956,21 @@ async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, log
   }
   return Buffer.from(after);
 }
-async function orchestrateVerify(proof, networkLayer, originalDataHash, logger, signal) {
+async function orchestrateVerify(proof, networkLayer, originalDataHash, logger, signal, esploraUrl) {
   let detached;
   try {
     detached = DetachedTimestampFile.deserialize(new Uint8Array(proof));
   } catch (cause) {
     throw new ValidationError("Invalid .ots proof format", {
-      cause: cause instanceof Error ? cause : void 0
+      ...cause instanceof Error ? { cause } : {}
     });
   }
+  if (detached.fileHashOp instanceof OpSHA1 || detached.fileHashOp instanceof 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 {
@@ -920,7 +978,7 @@ async function orchestrateVerify(proof, networkLayer, originalDataHash, logger,
     } catch (err) {
       throw new ValidationError(
         err instanceof Error ? err.message : "Invalid hash format",
-        { cause: err instanceof Error ? err : void 0 }
+        { ...err instanceof Error ? { cause: err } : {} }
       );
     }
     if (!timingSafeEq(expected, detached.fileDigest())) {
@@ -951,7 +1009,10 @@ async function orchestrateVerify(proof, networkLayer, originalDataHash, logger,
       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);
+  const explorer = new EsploraClient(networkLayer, {
+    ...esploraUrl !== void 0 ? { url: esploraUrl } : {},
+    ...logger !== void 0 ? { logger } : {}
+  });
   let lastNetworkError;
   let lastCryptoError;
   for (const { msg, attestation } of bitcoinAtts) {
@@ -993,20 +1054,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,
@@ -1023,8 +1096,7 @@ 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`);
@@ -1109,7 +1181,7 @@ 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
@@ -1143,17 +1215,17 @@ var OpenTimestampsClient = class {
 
 // src/index.ts
 import { DetachedTimestampFile as DetachedTimestampFile2, Timestamp as Timestamp2 } from "@otskit/core";
-import { verifyAgainstBlockheader as verifyAgainstBlockheader2 } from "@otskit/core";
+import { verifyAgainstBlockheader } from "@otskit/core";
 
 // src/utils/hash.ts
-import { createHash } from "crypto";
+import { createHash as createHash2 } from "crypto";
 import { createReadStream } from "fs";
 function hashBuffer(data) {
-  return createHash("sha256").update(data).digest();
+  return createHash2("sha256").update(data).digest();
 }
 function hashFile(path) {
   return new Promise((resolve, reject) => {
-    const hash = createHash("sha256");
+    const hash = createHash2("sha256");
     createReadStream(path).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve(hash.digest())).on("error", reject);
   });
 }
@@ -1187,6 +1259,6 @@ export {
   hashBuffer,
   hashFile,
   isVerified,
-  verifyAgainstBlockheader2 as verifyAgainstBlockheader,
+  verifyAgainstBlockheader,
   verifyTimestampAttestation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@otskit/client",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Official client SDK for OpenTimestamps calendars with resilience patterns",
   "author": "alexalves87",
   "license": "MIT",
@@ -24,12 +24,13 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
     "test": "vitest run",
+    "coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "eslint .",
     "format": "prettier --write \"src/**/*.ts\"",
@@ -71,7 +72,7 @@
     "prettier": "^3.3.3",
     "semantic-release": "^25.0.3",
     "tsup": "^8.3.5",
-    "typescript": "^5.6.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.8"
   }
 }