@otskit/client 0.5.0 → 0.6.1

package/dist/index.js

@@ -29,7 +29,8 @@ var OpenTimestampsClientError = class extends Error {
   constructor(message, options) {
     super(message);
     this.name = this.constructor.name;
-    if (options?.cause !== void 0) this.cause = options.cause;
+    if (options?.cause !== void 0)
+      this.cause = options.cause;
     Error.captureStackTrace?.(this, this.constructor);
   }
 };
@@ -328,7 +329,8 @@ async function executeRequest(request, maxBytes) {
     if (error instanceof NetworkError) throw error;
     if (error instanceof Error) {
       if (error.name === "AbortError") throw new NetworkError("Request aborted", { cause: error });
-      if (error.message.includes("timeout")) throw new NetworkError("Request timeout", { cause: error });
+      if (error.message.includes("timeout"))
+        throw new NetworkError("Request timeout", { cause: error });
       throw new NetworkError(`Network request failed: ${error.message}`, { cause: error });
     }
     throw new NetworkError("Unknown network error");
@@ -342,10 +344,14 @@ function createTimeoutController(timeoutMs, parentSignal) {
     parentSignal?.removeEventListener("abort", onParentAbort);
     controller.abort(parentSignal?.reason);
   };
-  controller.signal.addEventListener("abort", () => {
-    clearTimeout(timeout);
-    parentSignal?.removeEventListener("abort", onParentAbort);
-  }, { once: true });
+  controller.signal.addEventListener(
+    "abort",
+    () => {
+      clearTimeout(timeout);
+      parentSignal?.removeEventListener("abort", onParentAbort);
+    },
+    { once: true }
+  );
   if (parentSignal) {
     if (parentSignal.aborted) {
       clearTimeout(timeout);
@@ -437,15 +443,8 @@ var ResilientNetworkLayer = class {
   }
 };
 
-// src/core/orchestration.ts
-import {
-  DetachedTimestampFile,
-  OpSHA256,
-  OpAppend,
-  OpSHA1,
-  OpRIPEMD160,
-  makeMerkleTree
-} from "@otskit/core";
+// src/core/stamp.ts
+import { DetachedTimestampFile, OpSHA256, OpAppend, makeMerkleTree } from "@otskit/core";
 
 // src/network/calendar.ts
 import {
@@ -603,6 +602,146 @@ var UrlWhitelist = class {
 var DEFAULT_CALENDAR_WHITELIST = new UrlWhitelist([...TRUSTED_CALENDAR_WHITELIST_PATTERNS]);
 var DEFAULT_AGGREGATORS = [...DEFAULT_AGGREGATOR_URLS];
 
+// src/utils/hex.ts
+function hexToBytes(hex) {
+  const clean = hex.trim().toLowerCase();
+  if (clean.length % 2 !== 0 || !/^[0-9a-f]*$/.test(clean)) throw new Error("Invalid hex string");
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+function bytesToHex2(bytes) {
+  let s = "";
+  for (const b of bytes) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+
+// src/core/shared.ts
+function validateHash(hash) {
+  if (typeof hash === "string") {
+    const hex = hash.trim().toLowerCase();
+    if (!/^[0-9a-f]{64}$/.test(hex)) {
+      throw new ValidationError("Hash must be a 64-character hex string (SHA-256)");
+    }
+    return hexToBytes(hex);
+  }
+  if (hash.length !== 32) {
+    throw new ValidationError("Hash must be exactly 32 bytes (SHA-256)");
+  }
+  return Uint8Array.from(hash);
+}
+function secureNonce(n) {
+  const bytes = new Uint8Array(n);
+  if (!globalThis.crypto?.getRandomValues) {
+    throw new Error("secure RNG unavailable: globalThis.crypto.getRandomValues is required");
+  }
+  globalThis.crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+// src/core/stamp.ts
+async function orchestrateStamp(hash, calendars, networkLayer, validateCalendarUrl, logger, signal, minimumSuccessfulSubmissions = 2) {
+  if (calendars.length === 0) {
+    throw new ValidationError("at least one calendar is required to stamp");
+  }
+  if (!Number.isInteger(minimumSuccessfulSubmissions) || minimumSuccessfulSubmissions < 1) {
+    throw new ValidationError("minimumSuccessfulSubmissions must be an integer >= 1");
+  }
+  if (minimumSuccessfulSubmissions > calendars.length) {
+    throw new ValidationError(
+      `minimumSuccessfulSubmissions (${minimumSuccessfulSubmissions}) cannot exceed the number of calendars (${calendars.length})`
+    );
+  }
+  await Promise.all(calendars.map((url) => validateCalendarUrl(url)));
+  const digest = validateHash(hash);
+  logger?.info(`Starting stamp for ${bytesToHex2(digest)}`);
+  const detached = DetachedTimestampFile.fromHash(new OpSHA256(), digest);
+  const nonceAppended = detached.timestamp.add(new OpAppend(secureNonce(16)));
+  const merkleRoot = nonceAppended.add(new OpSHA256());
+  const merkleTip = makeMerkleTree([merkleRoot]);
+  const results = await Promise.allSettled(
+    calendars.map(
+      (url) => new CalendarClient(url, networkLayer, logger).submit(merkleTip.getDigest(), signal)
+    )
+  );
+  const successful = [];
+  const failed = [];
+  results.forEach((r, i) => {
+    const calendar = calendars[i];
+    if (r.status === "fulfilled") {
+      merkleTip.merge(r.value);
+      successful.push({ calendar });
+      logger?.info(`Submitted to ${calendar}`);
+    } else {
+      const error = r.reason instanceof Error ? r.reason : new Error(String(r.reason));
+      failed.push({ calendar, error });
+      logger?.warn(`Failed to submit to ${calendar}: ${error.message}`);
+    }
+  });
+  if (successful.length < minimumSuccessfulSubmissions) {
+    throw new StampError(
+      `Insufficient successful submissions (${successful.length}/${minimumSuccessfulSubmissions} required)`,
+      successful,
+      failed
+    );
+  }
+  return detached.serializeToBytes();
+}
+
+// src/core/upgrade.ts
+import { DetachedTimestampFile as DetachedTimestampFile2 } from "@otskit/core";
+var bytesEqFast = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)) === 0;
+async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, logger, signal) {
+  let detached;
+  try {
+    detached = DetachedTimestampFile2.deserialize(new Uint8Array(incompleteProof));
+  } catch (error) {
+    throw new ValidationError("Invalid .ots proof format", {
+      /* v8 ignore next */
+      ...error instanceof Error ? { cause: error } : {}
+    });
+  }
+  if (detached.timestamp.isTimestampComplete()) {
+    logger?.info("Proof already complete; nothing to upgrade");
+    return Buffer.from(incompleteProof);
+  }
+  const before = detached.serializeToBytes();
+  for (const subStamp of detached.timestamp.directlyVerified()) {
+    if (subStamp.isTimestampComplete()) continue;
+    for (const att of subStamp.attestations) {
+      if (att.kind !== "pending") continue;
+      if (!DEFAULT_CALENDAR_WHITELIST.contains(att.uri)) {
+        logger?.warn(`Ignoring attestation from non-whitelisted calendar ${att.uri}`);
+        continue;
+      }
+      try {
+        const upgraded = await new CalendarClient(att.uri, networkLayer, logger).getTimestamp(
+          subStamp.getDigest(),
+          signal
+        );
+        subStamp.merge(upgraded);
+      } catch (err) {
+        if (err instanceof CommitmentNotFoundError) {
+          logger?.debug(`Calendar ${att.uri} has not confirmed yet`);
+          continue;
+        }
+        logger?.warn(
+          `Failed to query ${att.uri}: ${err instanceof Error ? err.message : String(err)}`
+        );
+      }
+    }
+  }
+  const after = detached.serializeToBytes();
+  if (bytesEqFast(before, after)) {
+    throw new UpgradeError("No calendar has confirmed the timestamp yet (Bitcoin not yet mined)");
+  }
+  return Buffer.from(after);
+}
+
+// src/core/verify.ts
+import { DetachedTimestampFile as DetachedTimestampFile3, OpSHA1, OpRIPEMD160 } from "@otskit/core";
+import { timingSafeEqual } from "crypto";
+
 // src/network/esplora.ts
 import { createHash } from "crypto";
 import { verifyAgainstRawHeader, VerificationError } from "@otskit/core";
@@ -696,10 +835,18 @@ var EsploraClient = class {
     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" } },
+      { url: `${this.#url}/block/${hash}/header`, method: "GET", headers: { Accept: "text/plain" } },
       signal
     );
-    const data = response.data;
+    const hex = this.#decode(response.data).trim();
+    let data;
+    try {
+      data = hexToBytes(hex);
+    } catch (cause) {
+      throw new EsploraResponseError("esplora returned a non-hex raw block header", {
+        ...cause instanceof Error ? { cause } : {}
+      });
+    }
     if (data.length !== RAW_HEADER_SIZE) {
       throw new EsploraResponseError(
         `raw block header must be ${RAW_HEADER_SIZE} bytes; got ${data.length}`
@@ -738,8 +885,98 @@ async function verifyTimestampAttestation(digest, attestation, explorer, signal)
   return verifyAgainstRawHeader(digest, rawHeader);
 }
 
-// src/core/orchestration.ts
-import { timingSafeEqual } from "crypto";
+// src/core/verify.ts
+var MAX_BITCOIN_ATTESTATIONS = 10;
+function timingSafeEq(a, b) {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}
+async function orchestrateVerify(proof, networkLayer, originalDataHash, logger, signal, esploraUrl) {
+  let detached;
+  try {
+    detached = DetachedTimestampFile3.deserialize(new Uint8Array(proof));
+  } catch (cause) {
+    throw new ValidationError("Invalid .ots proof format", {
+      ...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 {
+      expected = validateHash(originalDataHash);
+    } catch (err) {
+      throw new ValidationError(err instanceof Error ? err.message : "Invalid hash format", {
+        ...err instanceof Error ? { cause: err } : {}
+      });
+    }
+    if (!timingSafeEq(expected, detached.fileDigest())) {
+      return {
+        status: "invalid",
+        reason: "File hash does not match proof \u2014 file may have been modified"
+      };
+    }
+  }
+  const allBitcoin = detached.timestamp.allAttestations().filter(({ attestation }) => attestation.kind === "bitcoin");
+  const seenHeights = /* @__PURE__ */ new Set();
+  const deduped = allBitcoin.filter(({ attestation }) => {
+    if (attestation.kind !== "bitcoin") return false;
+    if (seenHeights.has(attestation.height)) {
+      logger?.debug(`Skipping duplicate Bitcoin attestation at height ${attestation.height}`);
+      return false;
+    }
+    seenHeights.add(attestation.height);
+    return true;
+  });
+  const bitcoinAtts = deduped.slice(0, MAX_BITCOIN_ATTESTATIONS);
+  if (deduped.length > MAX_BITCOIN_ATTESTATIONS) {
+    logger?.warn(
+      `Proof has ${deduped.length} unique Bitcoin attestations; verifying only the first ${MAX_BITCOIN_ATTESTATIONS}`
+    );
+  }
+  if (bitcoinAtts.length === 0) {
+    const hasLitecoin = detached.timestamp.allAttestations().some(({ attestation }) => attestation.kind === "litecoin");
+    return {
+      status: "pending",
+      reason: hasLitecoin ? "Litecoin-only attestation is not supported by this client" : "No Bitcoin attestation found \u2014 timestamp not yet confirmed"
+    };
+  }
+  const explorer = new EsploraClient(networkLayer, {
+    ...esploraUrl !== void 0 ? { url: esploraUrl } : {},
+    ...logger !== void 0 ? { logger } : {}
+  });
+  let lastNetworkError;
+  let lastCryptoError;
+  for (const { msg, attestation } of bitcoinAtts) {
+    if (attestation.kind !== "bitcoin") continue;
+    try {
+      const blockTime = await verifyTimestampAttestation(msg, attestation, explorer, signal);
+      logger?.info(`Verified against Bitcoin block ${attestation.height}`);
+      return { status: "verified", blockHeight: attestation.height, blockTime };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (err instanceof NetworkError || err instanceof EsploraResponseError) {
+        lastNetworkError = message;
+        logger?.warn(`Network error at block ${attestation.height}: ${message}`);
+      } else {
+        lastCryptoError = message;
+        logger?.warn(`Crypto verification failed at block ${attestation.height}: ${message}`);
+      }
+    }
+  }
+  if (lastCryptoError !== void 0) {
+    return { status: "invalid", reason: `Cryptographic verification failed: ${lastCryptoError}` };
+  }
+  return {
+    status: "network_error",
+    reason: `Could not reach Bitcoin blockchain: ${lastNetworkError ?? "unknown error"}`
+  };
+}
 
 // src/security/ssrf.ts
 import { lookup } from "dns/promises";
@@ -758,7 +995,7 @@ var BLOCKED_CIDRS_V4 = [
 ];
 function ipv4ToUint32(ip) {
   const parts = ip.split(".");
-  return (parseInt(parts[0], 10) << 24 | parseInt(parts[1], 10) << 16 | parseInt(parts[2], 10) << 8 | parseInt(parts[3], 10)) >>> 0;
+  return (Number.parseInt(parts[0], 10) << 24 | Number.parseInt(parts[1], 10) << 16 | Number.parseInt(parts[2], 10) << 8 | Number.parseInt(parts[3], 10)) >>> 0;
 }
 function assertNotPrivateIPv4(ip, calendarUrl) {
   const n = ipv4ToUint32(ip);
@@ -837,215 +1074,6 @@ async function assertSafeCalendarUrl(url, options) {
   }
 }
 
-// src/core/orchestration.ts
-var MAX_BITCOIN_ATTESTATIONS = 10;
-function validateHash(hash) {
-  if (typeof hash === "string") {
-    const hex = hash.trim().toLowerCase();
-    if (!/^[0-9a-f]{64}$/.test(hex)) {
-      throw new ValidationError("Hash must be a 64-character hex string (SHA-256)");
-    }
-    return Uint8Array.from(Buffer.from(hex, "hex"));
-  }
-  if (hash.length !== 32) {
-    throw new ValidationError("Hash must be exactly 32 bytes (SHA-256)");
-  }
-  return Uint8Array.from(hash);
-}
-function secureNonce(n) {
-  const bytes = new Uint8Array(n);
-  if (!globalThis.crypto?.getRandomValues) {
-    throw new Error("secure RNG unavailable: globalThis.crypto.getRandomValues is required");
-  }
-  globalThis.crypto.getRandomValues(bytes);
-  return bytes;
-}
-function timingSafeEq(a, b) {
-  if (a.length !== b.length) return false;
-  return timingSafeEqual(a, b);
-}
-var bytesEqFast = (a, b) => Buffer.compare(Buffer.from(a), Buffer.from(b)) === 0;
-async function orchestrateStamp(hash, calendars, networkLayer, logger, signal, minimumSuccessfulSubmissions = 2, allowPrivateCalendars = false) {
-  if (calendars.length === 0) {
-    throw new ValidationError("at least one calendar is required to stamp");
-  }
-  if (!Number.isInteger(minimumSuccessfulSubmissions) || minimumSuccessfulSubmissions < 1) {
-    throw new ValidationError("minimumSuccessfulSubmissions must be an integer >= 1");
-  }
-  if (minimumSuccessfulSubmissions > calendars.length) {
-    throw new ValidationError(
-      `minimumSuccessfulSubmissions (${minimumSuccessfulSubmissions}) cannot exceed the number of calendars (${calendars.length})`
-    );
-  }
-  await Promise.all(
-    calendars.map((url) => assertSafeCalendarUrl(url, { allowPrivate: allowPrivateCalendars }))
-  );
-  const digest = validateHash(hash);
-  logger?.info(`Starting stamp for ${Buffer.from(digest).toString("hex")}`);
-  const detached = DetachedTimestampFile.fromHash(new OpSHA256(), digest);
-  const nonceAppended = detached.timestamp.add(new OpAppend(secureNonce(16)));
-  const merkleRoot = nonceAppended.add(new OpSHA256());
-  const merkleTip = makeMerkleTree([merkleRoot]);
-  const results = await Promise.allSettled(
-    calendars.map((url) => new CalendarClient(url, networkLayer, logger).submit(merkleTip.getDigest(), signal))
-  );
-  const successful = [];
-  const failed = [];
-  results.forEach((r, i) => {
-    const calendar = calendars[i];
-    if (r.status === "fulfilled") {
-      merkleTip.merge(r.value);
-      successful.push({ calendar });
-      logger?.info(`Submitted to ${calendar}`);
-    } else {
-      const error = r.reason instanceof Error ? r.reason : new Error(String(r.reason));
-      failed.push({ calendar, error });
-      logger?.warn(`Failed to submit to ${calendar}: ${error.message}`);
-    }
-  });
-  if (successful.length < minimumSuccessfulSubmissions) {
-    throw new StampError(
-      `Insufficient successful submissions (${successful.length}/${minimumSuccessfulSubmissions} required)`,
-      successful,
-      failed
-    );
-  }
-  return Buffer.from(detached.serializeToBytes());
-}
-async function orchestrateUpgrade(incompleteProof, _calendars, networkLayer, logger, signal) {
-  let detached;
-  try {
-    detached = DetachedTimestampFile.deserialize(new Uint8Array(incompleteProof));
-  } catch (error) {
-    throw new ValidationError("Invalid .ots proof format", {
-      /* v8 ignore next */
-      ...error instanceof Error ? { cause: error } : {}
-    });
-  }
-  if (detached.timestamp.isTimestampComplete()) {
-    logger?.info("Proof already complete; nothing to upgrade");
-    return Buffer.from(incompleteProof);
-  }
-  const before = detached.serializeToBytes();
-  for (const subStamp of detached.timestamp.directlyVerified()) {
-    if (subStamp.isTimestampComplete()) continue;
-    for (const att of subStamp.attestations) {
-      if (att.kind !== "pending") continue;
-      if (!DEFAULT_CALENDAR_WHITELIST.contains(att.uri)) {
-        logger?.warn(`Ignoring attestation from non-whitelisted calendar ${att.uri}`);
-        continue;
-      }
-      try {
-        const upgraded = await new CalendarClient(att.uri, networkLayer, logger).getTimestamp(
-          subStamp.getDigest(),
-          signal
-        );
-        subStamp.merge(upgraded);
-      } catch (err) {
-        if (err instanceof CommitmentNotFoundError) {
-          logger?.debug(`Calendar ${att.uri} has not confirmed yet`);
-          continue;
-        }
-        logger?.warn(`Failed to query ${att.uri}: ${err instanceof Error ? err.message : String(err)}`);
-      }
-    }
-  }
-  const after = detached.serializeToBytes();
-  if (bytesEqFast(before, after)) {
-    throw new UpgradeError("No calendar has confirmed the timestamp yet (Bitcoin not yet mined)");
-  }
-  return Buffer.from(after);
-}
-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 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 {
-      expected = validateHash(originalDataHash);
-    } catch (err) {
-      throw new ValidationError(
-        err instanceof Error ? err.message : "Invalid hash format",
-        { ...err instanceof Error ? { cause: err } : {} }
-      );
-    }
-    if (!timingSafeEq(expected, detached.fileDigest())) {
-      return { status: "invalid", reason: "File hash does not match proof \u2014 file may have been modified" };
-    }
-  }
-  const allBitcoin = detached.timestamp.allAttestations().filter(({ attestation }) => attestation.kind === "bitcoin");
-  const seenHeights = /* @__PURE__ */ new Set();
-  const deduped = allBitcoin.filter(({ attestation }) => {
-    if (attestation.kind !== "bitcoin") return false;
-    if (seenHeights.has(attestation.height)) {
-      logger?.debug(`Skipping duplicate Bitcoin attestation at height ${attestation.height}`);
-      return false;
-    }
-    seenHeights.add(attestation.height);
-    return true;
-  });
-  const bitcoinAtts = deduped.slice(0, MAX_BITCOIN_ATTESTATIONS);
-  if (deduped.length > MAX_BITCOIN_ATTESTATIONS) {
-    logger?.warn(
-      `Proof has ${deduped.length} unique Bitcoin attestations; verifying only the first ${MAX_BITCOIN_ATTESTATIONS}`
-    );
-  }
-  if (bitcoinAtts.length === 0) {
-    const hasLitecoin = detached.timestamp.allAttestations().some(({ attestation }) => attestation.kind === "litecoin");
-    return {
-      status: "pending",
-      reason: hasLitecoin ? "Litecoin-only attestation is not supported by this client" : "No Bitcoin attestation found \u2014 timestamp not yet confirmed"
-    };
-  }
-  const explorer = new EsploraClient(networkLayer, {
-    ...esploraUrl !== void 0 ? { url: esploraUrl } : {},
-    ...logger !== void 0 ? { logger } : {}
-  });
-  let lastNetworkError;
-  let lastCryptoError;
-  for (const { msg, attestation } of bitcoinAtts) {
-    if (attestation.kind !== "bitcoin") continue;
-    try {
-      const blockTime = await verifyTimestampAttestation(
-        Uint8Array.from(msg).reverse(),
-        attestation,
-        explorer,
-        signal
-      );
-      logger?.info(`Verified against Bitcoin block ${attestation.height}`);
-      return { status: "verified", blockHeight: attestation.height, blockTime };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      if (err instanceof NetworkError || err instanceof EsploraResponseError) {
-        lastNetworkError = message;
-        logger?.warn(`Network error at block ${attestation.height}: ${message}`);
-      } else {
-        lastCryptoError = message;
-        logger?.warn(`Crypto verification failed at block ${attestation.height}: ${message}`);
-      }
-    }
-  }
-  if (lastCryptoError !== void 0) {
-    return { status: "invalid", reason: `Cryptographic verification failed: ${lastCryptoError}` };
-  }
-  return {
-    status: "network_error",
-    reason: `Could not reach Bitcoin blockchain: ${lastNetworkError ?? "unknown error"}`
-  };
-}
-
 // src/client.ts
 var OpenTimestampsClient = class {
   calendars;
@@ -1057,7 +1085,7 @@ var OpenTimestampsClient = class {
   esploraUrl;
   /**
    * Create a new OpenTimestamps client
-   * 
+   *
    * @param options Client configuration options
    */
   constructor(options = {}) {
@@ -1103,15 +1131,15 @@ var OpenTimestampsClient = class {
   }
   /**
    * Create a timestamp by submitting a hash to calendar servers
-   * 
+   *
    * @param hash SHA-256 hash of the data to timestamp (as Buffer or hex string)
    * @param options Operation-specific options
    * @returns Initial .ots proof with pending attestations
-   * 
+   *
    * @throws {ValidationError} If the hash is invalid
    * @throws {StampError} If submission fails to all calendars
    * @throws {NetworkError} If network errors occur
-   * 
+   *
    * @example
    * ```typescript
    * const hash = crypto.createHash('sha256').update('my data').digest()
@@ -1121,34 +1149,36 @@ var OpenTimestampsClient = class {
    */
   async stamp(hash, options) {
     const signal = options?.signal || this.globalSignal;
-    return orchestrateStamp(
+    const allowPrivate = this.allowPrivateCalendars;
+    const bytes = await orchestrateStamp(
       hash,
       this.calendars,
       this.networkLayer,
+      (url) => assertSafeCalendarUrl(url, { allowPrivate }),
       this.logger,
       signal,
-      this.minimumSuccessfulSubmissions,
-      this.allowPrivateCalendars
+      this.minimumSuccessfulSubmissions
     );
+    return Buffer.from(bytes);
   }
   /**
    * Upgrade an incomplete timestamp proof by querying calendars for Bitcoin confirmation
-   * 
+   *
    * @param incompleteProof The initial .ots proof returned by stamp()
    * @param options Operation-specific options
    * @returns Upgraded .ots proof with Bitcoin attestation (if available)
-   * 
+   *
    * @throws {ValidationError} If the proof format is invalid
    * @throws {UpgradeError} If no calendar has confirmed the timestamp yet
    * @throws {NetworkError} If network errors occur
-   * 
+   *
    * @example
    * ```typescript
    * // Proof already has pending attestations from stamp()
    * const upgradedProof = await client.upgrade(incompleteProof)
-   * 
+   *
    * // If upgrade throws UpgradeError, Bitcoin hasn't confirmed yet
-   * // Retry later (typically 10-60 minutes after stamp)
+   * // Retry later (typically ~60 minutes after stamp)
    * ```
    */
   async upgrade(incompleteProof, options) {
@@ -1163,15 +1193,15 @@ var OpenTimestampsClient = class {
   }
   /**
    * Verify a complete timestamp proof against the Bitcoin blockchain
-   * 
+   *
    * @param proof The complete .ots proof with Bitcoin attestation
    * @param originalDataHash Optional: the original data hash to verify against
    * @returns Verification result with block details
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.verify(completeProof, originalHash)
-   * 
+   *
    * if (result.valid) {
    *   console.log(`Timestamp confirmed in Bitcoin block ${result.blockHeight}`)
    *   console.log(`Block timestamp: ${new Date(result.timestamp! * 1000)}`)
@@ -1181,12 +1211,19 @@ var OpenTimestampsClient = class {
    * ```
    */
   async verify(proof, originalDataHash) {
-    return orchestrateVerify(proof, this.networkLayer, originalDataHash, this.logger, this.globalSignal, this.esploraUrl);
+    return orchestrateVerify(
+      proof,
+      this.networkLayer,
+      originalDataHash,
+      this.logger,
+      this.globalSignal,
+      this.esploraUrl
+    );
   }
   /**
    * Get the current state of the circuit breaker for a calendar
    * Useful for monitoring and debugging
-   * 
+   *
    * @param calendarUrl The calendar URL to check
    * @returns Circuit state: 'CLOSED', 'OPEN', or 'HALF_OPEN' (undefined if not yet initialized)
    */
@@ -1196,7 +1233,7 @@ var OpenTimestampsClient = class {
   /**
    * Reset the circuit breaker for a specific calendar
    * Use this to manually recover a calendar that has been marked as failing
-   * 
+   *
    * @param calendarUrl The calendar URL to reset
    */
   resetCircuit(calendarUrl) {
@@ -1214,7 +1251,7 @@ var OpenTimestampsClient = class {
 };
 
 // src/index.ts
-import { DetachedTimestampFile as DetachedTimestampFile2, Timestamp as Timestamp2 } from "@otskit/core";
+import { DetachedTimestampFile as DetachedTimestampFile4, Timestamp as Timestamp2 } from "@otskit/core";
 import { verifyAgainstBlockheader } from "@otskit/core";
 
 // src/utils/hash.ts
@@ -1239,7 +1276,7 @@ export {
   DEFAULT_CALENDARS,
   DEFAULT_CALENDAR_WHITELIST,
   DEFAULT_RESILIENCE,
-  DetachedTimestampFile2 as DetachedTimestampFile,
+  DetachedTimestampFile4 as DetachedTimestampFile,
   EsploraClient,
   EsploraResponseError,
   MAX_CALENDAR_RESPONSE_SIZE,