@otskit/client 0.1.3 → 0.3.0

package/dist/index.d.cts

@@ -39,6 +39,8 @@ interface ResilienceOptions {
     connectTimeoutMs: number;
     retries: RetryOptions;
     circuitBreaker: CircuitBreakerOptions;
+    /** Límite de bytes para el body de la respuesta. Default 100 KB. */
+    maxResponseBytes?: number;
 }
 /** Client configuration options */
 interface ClientOptions {
@@ -52,19 +54,51 @@ interface ClientOptions {
     signal?: AbortSignal;
     /** Minimum successful calendar submissions required (default: 2) */
     minimumSuccessfulSubmissions?: number;
+    /**
+     * Permite URLs de calendario que resuelven a IPs privadas/reservadas.
+     *
+     * **No activar en producción.** Útil para testing local o redes corporativas.
+     *
+     * Incluso con `false`, la protección es best-effort contra DNS rebinding (TOCTOU).
+     * Para alta seguridad, complementar con egress filtering a nivel de red.
+     *
+     * @default false
+     */
+    allowPrivateCalendars?: boolean;
 }
 /** Operation-specific options */
 interface OperationOptions {
     signal?: AbortSignal;
 }
-/** Verification result */
-interface VerificationResult {
-    valid: boolean;
-    blockHeight?: number;
-    blockHash?: string;
-    timestamp?: number;
-    error?: string;
+/** Verificación exitosa: prueba criptográficamente válida y confirmada en Bitcoin. */
+interface VerificationSuccess {
+    readonly status: 'verified';
+    readonly blockHeight: number;
+    readonly blockTime: number;
+    readonly blockHash?: string;
+}
+/** El timestamp es parseable pero aún no tiene confirmación Bitcoin. Estado normal. */
+interface VerificationPending {
+    readonly status: 'pending';
+    readonly reason: string;
 }
+/**
+ * La verificación criptográfica falló: el digest no coincide con el merkleroot.
+ * Indica posible manipulación del archivo o de la prueba.
+ */
+interface VerificationInvalid {
+    readonly status: 'invalid';
+    readonly reason: string;
+}
+/** Error de infraestructura: Esplora no disponible. El estado del timestamp es desconocido. */
+interface VerificationNetworkError {
+    readonly status: 'network_error';
+    readonly reason: string;
+}
+/** Resultado de verify(). Usar switch(result.status) para narrowing exhaustivo. */
+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 */
 declare const DEFAULT_CALENDARS: string[];
 /** Default resilience configuration */
@@ -104,6 +138,7 @@ declare class OpenTimestampsClient {
     private logger?;
     private globalSignal?;
     private minimumSuccessfulSubmissions;
+    private allowPrivateCalendars;
     /**
      * Create a new OpenTimestamps client
      *
@@ -250,6 +285,15 @@ declare class CalendarResponseTooLargeError extends NetworkError {
 /** Respuesta del explorador Esplora inválida: vacía, no-JSON, malformada o demasiado grande (defensa DoS). */
 declare class EsploraResponseError extends NetworkError {
 }
+/** La respuesta supera el límite de bytes permitido (defensa DoS). */
+declare class SizeLimitExceededError extends NetworkError {
+    readonly maxBytes: number;
+    readonly actualBytes?: number;
+    constructor(maxBytes: number, actualBytes?: number, options?: {
+        cause?: Error;
+        status?: number;
+    });
+}
 
 /**
  * Circuit Breaker implementation for protecting against cascading failures
@@ -262,8 +306,8 @@ declare enum CircuitState {
 }
 
 /**
- * Universal fetch adapter for multi-runtime compatibility
- * Works in Node.js 18+, browsers, and edge runtimes
+ * Universal fetch adapter para compatibilidad multi-runtime.
+ * Funciona en Node.js 18+, browsers y edge runtimes.
  */
 interface FetchRequest {
     url: string;
@@ -300,7 +344,7 @@ declare class ResilientNetworkLayer {
  * Cliente de un calendario remoto OpenTimestamps (protocolo OTS real).
  */
 
-/** Límite de tamaño de la respuesta de un calendario (defensa DoS). */
+/** Limite de tamano de la respuesta de un calendario (defensa DoS). */
 declare const MAX_CALENDAR_RESPONSE_SIZE = 10000;
 /** Interfaz con un servidor de calendario remoto. */
 declare class CalendarClient {
@@ -309,22 +353,22 @@ declare class CalendarClient {
     private readonly networkLayer;
     private readonly logger?;
     constructor(url: string, networkLayer: ResilientNetworkLayer, logger?: Logger | undefined);
-    /** 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. */
     submit(digest: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
-    /** 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). */
     getTimestamp(commitment: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
 }
 /** Lista blanca de URLs de calendario de confianza. */
 declare class UrlWhitelist {
     #private;
     constructor(urls?: readonly string[]);
-    /** 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: string): void;
-    /** Verdadero si `url` casa con algún patrón de la whitelist. */
+    /** Verdadero si `url` casa con algun patron de la whitelist. */
     contains(url: string): boolean;
     toString(): string;
 }
-/** Calendarios de confianza por defecto para verificación/upgrade. */
+/** Calendarios de confianza por defecto para verificacion/upgrade. */
 declare const DEFAULT_CALENDAR_WHITELIST: UrlWhitelist;
 /** Agregadores por defecto a los que enviar digests al sellar. */
 declare const DEFAULT_AGGREGATORS: readonly string[];
@@ -358,4 +402,28 @@ declare class EsploraClient {
  */
 declare function verifyTimestampAttestation(digest: Uint8Array, attestation: Attestation, explorer: EsploraClient, signal?: AbortSignal): Promise<number>;
 
-export { type BackoffStrategy, CalendarClient, CalendarResponseTooLargeError, CircuitBreakerError, type CircuitBreakerOptions, CircuitState, type ClientOptions, CommitmentNotFoundError, DEFAULT_AGGREGATORS, DEFAULT_CALENDARS, DEFAULT_CALENDAR_WHITELIST, DEFAULT_RESILIENCE, EsploraClient, type EsploraClientOptions, EsploraResponseError, type JitterType, type Logger, MAX_CALENDAR_RESPONSE_SIZE, MAX_ESPLORA_RESPONSE_SIZE, NetworkError, OpenTimestampsClient, OpenTimestampsClientError, type OperationOptions, PUBLIC_ESPLORA_URL, type ResilienceOptions, ResilientNetworkLayer, type RetryOptions, StampError, UpgradeError, UrlWhitelist, ValidationError, type VerificationResult, verifyTimestampAttestation };
+declare function hashBuffer(data: Buffer | Uint8Array): Buffer;
+declare function hashFile(path: string): Promise<Buffer>;
+
+/**
+ * SSRF protection para calendarios configurables por el usuario.
+ *
+ * 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.
+ */
+/**
+ * Valida que una URL de calendario es segura para hacer outbound HTTP.
+ * Bloquea IPs privadas/reservadas por defecto.
+ *
+ * @param allowPrivate Si true, omite la comprobación de rangos IP.
+ *   Útil para testing local o redes corporativas internas.
+ */
+declare function assertSafeCalendarUrl(url: string, options: {
+    allowPrivate: boolean;
+}): Promise<void>;
+
+export { type BackoffStrategy, CalendarClient, CalendarResponseTooLargeError, CircuitBreakerError, type CircuitBreakerOptions, CircuitState, type ClientOptions, CommitmentNotFoundError, DEFAULT_AGGREGATORS, DEFAULT_CALENDARS, DEFAULT_CALENDAR_WHITELIST, DEFAULT_RESILIENCE, EsploraClient, type EsploraClientOptions, EsploraResponseError, type JitterType, type Logger, MAX_CALENDAR_RESPONSE_SIZE, MAX_ESPLORA_RESPONSE_SIZE, NetworkError, OpenTimestampsClient, OpenTimestampsClientError, type OperationOptions, PUBLIC_ESPLORA_URL, type ResilienceOptions, ResilientNetworkLayer, type RetryOptions, SizeLimitExceededError, StampError, UpgradeError, UrlWhitelist, ValidationError, type VerificationInvalid, type VerificationNetworkError, type VerificationPending, type VerificationResult, type VerificationSuccess, assertSafeCalendarUrl, hashBuffer, hashFile, isVerified, verifyTimestampAttestation };

package/dist/index.d.ts

@@ -39,6 +39,8 @@ interface ResilienceOptions {
     connectTimeoutMs: number;
     retries: RetryOptions;
     circuitBreaker: CircuitBreakerOptions;
+    /** Límite de bytes para el body de la respuesta. Default 100 KB. */
+    maxResponseBytes?: number;
 }
 /** Client configuration options */
 interface ClientOptions {
@@ -52,19 +54,51 @@ interface ClientOptions {
     signal?: AbortSignal;
     /** Minimum successful calendar submissions required (default: 2) */
     minimumSuccessfulSubmissions?: number;
+    /**
+     * Permite URLs de calendario que resuelven a IPs privadas/reservadas.
+     *
+     * **No activar en producción.** Útil para testing local o redes corporativas.
+     *
+     * Incluso con `false`, la protección es best-effort contra DNS rebinding (TOCTOU).
+     * Para alta seguridad, complementar con egress filtering a nivel de red.
+     *
+     * @default false
+     */
+    allowPrivateCalendars?: boolean;
 }
 /** Operation-specific options */
 interface OperationOptions {
     signal?: AbortSignal;
 }
-/** Verification result */
-interface VerificationResult {
-    valid: boolean;
-    blockHeight?: number;
-    blockHash?: string;
-    timestamp?: number;
-    error?: string;
+/** Verificación exitosa: prueba criptográficamente válida y confirmada en Bitcoin. */
+interface VerificationSuccess {
+    readonly status: 'verified';
+    readonly blockHeight: number;
+    readonly blockTime: number;
+    readonly blockHash?: string;
+}
+/** El timestamp es parseable pero aún no tiene confirmación Bitcoin. Estado normal. */
+interface VerificationPending {
+    readonly status: 'pending';
+    readonly reason: string;
 }
+/**
+ * La verificación criptográfica falló: el digest no coincide con el merkleroot.
+ * Indica posible manipulación del archivo o de la prueba.
+ */
+interface VerificationInvalid {
+    readonly status: 'invalid';
+    readonly reason: string;
+}
+/** Error de infraestructura: Esplora no disponible. El estado del timestamp es desconocido. */
+interface VerificationNetworkError {
+    readonly status: 'network_error';
+    readonly reason: string;
+}
+/** Resultado de verify(). Usar switch(result.status) para narrowing exhaustivo. */
+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 */
 declare const DEFAULT_CALENDARS: string[];
 /** Default resilience configuration */
@@ -104,6 +138,7 @@ declare class OpenTimestampsClient {
     private logger?;
     private globalSignal?;
     private minimumSuccessfulSubmissions;
+    private allowPrivateCalendars;
     /**
      * Create a new OpenTimestamps client
      *
@@ -250,6 +285,15 @@ declare class CalendarResponseTooLargeError extends NetworkError {
 /** Respuesta del explorador Esplora inválida: vacía, no-JSON, malformada o demasiado grande (defensa DoS). */
 declare class EsploraResponseError extends NetworkError {
 }
+/** La respuesta supera el límite de bytes permitido (defensa DoS). */
+declare class SizeLimitExceededError extends NetworkError {
+    readonly maxBytes: number;
+    readonly actualBytes?: number;
+    constructor(maxBytes: number, actualBytes?: number, options?: {
+        cause?: Error;
+        status?: number;
+    });
+}
 
 /**
  * Circuit Breaker implementation for protecting against cascading failures
@@ -262,8 +306,8 @@ declare enum CircuitState {
 }
 
 /**
- * Universal fetch adapter for multi-runtime compatibility
- * Works in Node.js 18+, browsers, and edge runtimes
+ * Universal fetch adapter para compatibilidad multi-runtime.
+ * Funciona en Node.js 18+, browsers y edge runtimes.
  */
 interface FetchRequest {
     url: string;
@@ -300,7 +344,7 @@ declare class ResilientNetworkLayer {
  * Cliente de un calendario remoto OpenTimestamps (protocolo OTS real).
  */
 
-/** Límite de tamaño de la respuesta de un calendario (defensa DoS). */
+/** Limite de tamano de la respuesta de un calendario (defensa DoS). */
 declare const MAX_CALENDAR_RESPONSE_SIZE = 10000;
 /** Interfaz con un servidor de calendario remoto. */
 declare class CalendarClient {
@@ -309,22 +353,22 @@ declare class CalendarClient {
     private readonly networkLayer;
     private readonly logger?;
     constructor(url: string, networkLayer: ResilientNetworkLayer, logger?: Logger | undefined);
-    /** 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. */
     submit(digest: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
-    /** 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). */
     getTimestamp(commitment: Uint8Array, signal?: AbortSignal): Promise<Timestamp>;
 }
 /** Lista blanca de URLs de calendario de confianza. */
 declare class UrlWhitelist {
     #private;
     constructor(urls?: readonly string[]);
-    /** 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: string): void;
-    /** Verdadero si `url` casa con algún patrón de la whitelist. */
+    /** Verdadero si `url` casa con algun patron de la whitelist. */
     contains(url: string): boolean;
     toString(): string;
 }
-/** Calendarios de confianza por defecto para verificación/upgrade. */
+/** Calendarios de confianza por defecto para verificacion/upgrade. */
 declare const DEFAULT_CALENDAR_WHITELIST: UrlWhitelist;
 /** Agregadores por defecto a los que enviar digests al sellar. */
 declare const DEFAULT_AGGREGATORS: readonly string[];
@@ -358,4 +402,28 @@ declare class EsploraClient {
  */
 declare function verifyTimestampAttestation(digest: Uint8Array, attestation: Attestation, explorer: EsploraClient, signal?: AbortSignal): Promise<number>;
 
-export { type BackoffStrategy, CalendarClient, CalendarResponseTooLargeError, CircuitBreakerError, type CircuitBreakerOptions, CircuitState, type ClientOptions, CommitmentNotFoundError, DEFAULT_AGGREGATORS, DEFAULT_CALENDARS, DEFAULT_CALENDAR_WHITELIST, DEFAULT_RESILIENCE, EsploraClient, type EsploraClientOptions, EsploraResponseError, type JitterType, type Logger, MAX_CALENDAR_RESPONSE_SIZE, MAX_ESPLORA_RESPONSE_SIZE, NetworkError, OpenTimestampsClient, OpenTimestampsClientError, type OperationOptions, PUBLIC_ESPLORA_URL, type ResilienceOptions, ResilientNetworkLayer, type RetryOptions, StampError, UpgradeError, UrlWhitelist, ValidationError, type VerificationResult, verifyTimestampAttestation };
+declare function hashBuffer(data: Buffer | Uint8Array): Buffer;
+declare function hashFile(path: string): Promise<Buffer>;
+
+/**
+ * SSRF protection para calendarios configurables por el usuario.
+ *
+ * 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.
+ */
+/**
+ * Valida que una URL de calendario es segura para hacer outbound HTTP.
+ * Bloquea IPs privadas/reservadas por defecto.
+ *
+ * @param allowPrivate Si true, omite la comprobación de rangos IP.
+ *   Útil para testing local o redes corporativas internas.
+ */
+declare function assertSafeCalendarUrl(url: string, options: {
+    allowPrivate: boolean;
+}): Promise<void>;
+
+export { type BackoffStrategy, CalendarClient, CalendarResponseTooLargeError, CircuitBreakerError, type CircuitBreakerOptions, CircuitState, type ClientOptions, CommitmentNotFoundError, DEFAULT_AGGREGATORS, DEFAULT_CALENDARS, DEFAULT_CALENDAR_WHITELIST, DEFAULT_RESILIENCE, EsploraClient, type EsploraClientOptions, EsploraResponseError, type JitterType, type Logger, MAX_CALENDAR_RESPONSE_SIZE, MAX_ESPLORA_RESPONSE_SIZE, NetworkError, OpenTimestampsClient, OpenTimestampsClientError, type OperationOptions, PUBLIC_ESPLORA_URL, type ResilienceOptions, ResilientNetworkLayer, type RetryOptions, SizeLimitExceededError, StampError, UpgradeError, UrlWhitelist, ValidationError, type VerificationInvalid, type VerificationNetworkError, type VerificationPending, type VerificationResult, type VerificationSuccess, assertSafeCalendarUrl, hashBuffer, hashFile, isVerified, verifyTimestampAttestation };