@otskit/client 0.3.0 → 0.5.0

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
      */
@@ -99,7 +105,7 @@ interface VerificationNetworkError {
 type VerificationResult = VerificationSuccess | VerificationPending | VerificationInvalid | VerificationNetworkError;
 /** Type guard — verdadero si la verificación fue exitosa. */
 declare const isVerified: (r: VerificationResult) => r is VerificationSuccess;
-/** Default calendar servers */
+/** Default calendar servers. Sourced from @otskit/core (single source of truth). */
 declare const DEFAULT_CALENDARS: string[];
 /** Default resilience configuration */
 declare const DEFAULT_RESILIENCE: ResilienceOptions;
@@ -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,64 +347,79 @@ 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;
 }
-/** Calendarios de confianza por defecto para verificacion/upgrade. */
+/**
+ * Default trusted calendars for verification/upgrade.
+ * Patterns sourced from @otskit/core (single source of truth).
+ */
 declare const DEFAULT_CALENDAR_WHITELIST: UrlWhitelist;
-/** Agregadores por defecto a los que enviar digests al sellar. */
+/**
+ * Default aggregators to submit digests to when stamping.
+ * Sourced from @otskit/core (single source of truth).
+ */
 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>;
 
@@ -406,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
      */
@@ -99,7 +105,7 @@ interface VerificationNetworkError {
 type VerificationResult = VerificationSuccess | VerificationPending | VerificationInvalid | VerificationNetworkError;
 /** Type guard — verdadero si la verificación fue exitosa. */
 declare const isVerified: (r: VerificationResult) => r is VerificationSuccess;
-/** Default calendar servers */
+/** Default calendar servers. Sourced from @otskit/core (single source of truth). */
 declare const DEFAULT_CALENDARS: string[];
 /** Default resilience configuration */
 declare const DEFAULT_RESILIENCE: ResilienceOptions;
@@ -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,64 +347,79 @@ 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;
 }
-/** Calendarios de confianza por defecto para verificacion/upgrade. */
+/**
+ * Default trusted calendars for verification/upgrade.
+ * Patterns sourced from @otskit/core (single source of truth).
+ */
 declare const DEFAULT_CALENDAR_WHITELIST: UrlWhitelist;
-/** Agregadores por defecto a los que enviar digests al sellar. */
+/**
+ * Default aggregators to submit digests to when stamping.
+ * Sourced from @otskit/core (single source of truth).
+ */
 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>;
 
@@ -406,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;