@inversealtruism/cairn-sdk 0.1.2 → 0.1.4

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { F as FetchLike } from './http-D2CzfOsm.cjs';
-export { H as Http, a as HttpOptions } from './http-D2CzfOsm.cjs';
+import { F as FetchLike } from './http-CQsNL8w9.cjs';
+export { H as Http, a as HttpOptions } from './http-CQsNL8w9.cjs';
 import { Chain } from './chain.cjs';
 import { BoardClient } from './board.cjs';
 export { BoardItemContent, BoardWindow, ProposeInput, ProposeResult, RankedItem, SupportInput } from './board.cjs';
@@ -9,7 +9,8 @@ import { ContentClient } from './content.cjs';
 export { ContentClientOptions, PreparedContent } from './content.cjs';
 import { RegistryClient } from './registry.cjs';
 import { WalletConnection, DetectOptions } from './connect.cjs';
-export { AttestParams, CairnProvider, ConnectResult, ProposeParams, SealClaimParams, SendParams, SignInResult, TxResult, connect, detectProvider, getWallet, isInstalled } from './connect.cjs';
+export { AttestParams, CairnProvider, ConnectResult, FillParams, ProposeParams, ProviderDetail, ProviderInfo, SealClaimParams, SendParams, SignInResult, SiwcParams, SiwcResult, TxResult, WalletCapabilities, WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled } from './connect.cjs';
+export { CairnController, CairnControllerOptions, CairnState } from './controller.cjs';
 import '@inversealtruism/csd-client';
 import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
@@ -17,8 +18,29 @@ import '@inversealtruism/csd-crypto';
 import '@inversealtruism/csd-light';
 import '@inversealtruism/csd-registry';
 
+/** Stable machine-readable error codes (branch on these, not the message text). */
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "UNKNOWN";
+declare const SDK_VERSION = "0.1.4";
+interface CairnErrorOptions {
+    code?: CairnErrorCode;
+    docsPath?: string;
+    cause?: unknown;
+}
 declare class CairnError extends Error {
-    constructor(message: string);
+    /** Stable machine code for programmatic branching. */
+    readonly code: CairnErrorCode;
+    /** The human message without the appended docs/version footer. */
+    readonly shortMessage: string;
+    /** Relative docs path (under the SDK docs base), if any. */
+    readonly docsPath?: string;
+    /** The cairn-sdk version that produced this error. */
+    readonly version = "0.1.4";
+    constructor(shortMessage: string, opts?: CairnErrorOptions);
+    /**
+     * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
+     * returns the DEEPEST cause (the root). Mirrors viem's `BaseError.walk()`.
+     */
+    walk(fn?: (err: unknown) => boolean): unknown;
 }
 /** The Cairn Wallet extension is not installed (no `window.cairn` appeared). */
 declare class NotInstalledError extends CairnError {
@@ -32,7 +54,7 @@ declare class UserRejectedError extends CairnError {
 declare class WalletLockedError extends CairnError {
     constructor(message?: string);
 }
-/** The method is not exposed to dApps by the wallet boundary. */
+/** The method is not exposed to dApps by the wallet boundary (or the wallet is too old for it). */
 declare class UnsupportedMethodError extends CairnError {
     constructor(message?: string);
 }
@@ -48,6 +70,13 @@ declare class ContentVerificationError extends CairnError {
     expected: string;
     constructor(expected: string);
 }
+/**
+ * Map a provider error string (from the wallet's `{ ok:false, error }`) onto a typed error. The
+ * wallet's strings are stable: "rejected by user", "wallet locked", "unsupported dApp method: …".
+ */
+declare function mapProviderError(error: string): CairnError;
+/** Convenience: the stable code of any error (or "UNKNOWN" for a non-CairnError). */
+declare function errorCode(err: unknown): CairnErrorCode;
 
 interface CairnBaseUrls {
     /** Cairn board server (board + /api/rpc proxy + /content origin). Default https://cairn-substrate.com */
@@ -93,6 +122,10 @@ interface CairnConfig {
         hash: string;
     };
 }
+declare const DEFAULT_SPV_CHECKPOINT: {
+    height: number;
+    hash: string;
+};
 declare class Cairn {
     readonly config: CairnConfig;
     readonly chain: Chain;
@@ -126,4 +159,4 @@ declare class Cairn {
     get connected(): boolean;
 }
 
-export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, Chain, ContentClient, ContentVerificationError, DetectOptions, FetchLike, HttpError, IndexerClient, NotInstalledError, RegistryClient, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError };
+export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, HttpError, IndexerClient, NotInstalledError, RegistryClient, SDK_VERSION, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FetchLike } from './http-D2CzfOsm.js';
-export { H as Http, a as HttpOptions } from './http-D2CzfOsm.js';
+import { F as FetchLike } from './http-CQsNL8w9.js';
+export { H as Http, a as HttpOptions } from './http-CQsNL8w9.js';
 import { Chain } from './chain.js';
 import { BoardClient } from './board.js';
 export { BoardItemContent, BoardWindow, ProposeInput, ProposeResult, RankedItem, SupportInput } from './board.js';
@@ -9,7 +9,8 @@ import { ContentClient } from './content.js';
 export { ContentClientOptions, PreparedContent } from './content.js';
 import { RegistryClient } from './registry.js';
 import { WalletConnection, DetectOptions } from './connect.js';
-export { AttestParams, CairnProvider, ConnectResult, ProposeParams, SealClaimParams, SendParams, SignInResult, TxResult, connect, detectProvider, getWallet, isInstalled } from './connect.js';
+export { AttestParams, CairnProvider, ConnectResult, FillParams, ProposeParams, ProviderDetail, ProviderInfo, SealClaimParams, SendParams, SignInResult, SiwcParams, SiwcResult, TxResult, WalletCapabilities, WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled } from './connect.js';
+export { CairnController, CairnControllerOptions, CairnState } from './controller.js';
 import '@inversealtruism/csd-client';
 import '@inversealtruism/csd-tx';
 import '@inversealtruism/csd-codec';
@@ -17,8 +18,29 @@ import '@inversealtruism/csd-crypto';
 import '@inversealtruism/csd-light';
 import '@inversealtruism/csd-registry';
 
+/** Stable machine-readable error codes (branch on these, not the message text). */
+type CairnErrorCode = "NOT_INSTALLED" | "USER_REJECTED" | "WALLET_LOCKED" | "UNSUPPORTED_METHOD" | "HTTP_ERROR" | "CONTENT_VERIFICATION" | "UNKNOWN";
+declare const SDK_VERSION = "0.1.4";
+interface CairnErrorOptions {
+    code?: CairnErrorCode;
+    docsPath?: string;
+    cause?: unknown;
+}
 declare class CairnError extends Error {
-    constructor(message: string);
+    /** Stable machine code for programmatic branching. */
+    readonly code: CairnErrorCode;
+    /** The human message without the appended docs/version footer. */
+    readonly shortMessage: string;
+    /** Relative docs path (under the SDK docs base), if any. */
+    readonly docsPath?: string;
+    /** The cairn-sdk version that produced this error. */
+    readonly version = "0.1.4";
+    constructor(shortMessage: string, opts?: CairnErrorOptions);
+    /**
+     * Walk the `cause` chain. With a predicate, returns the FIRST matching error (or null). Without one,
+     * returns the DEEPEST cause (the root). Mirrors viem's `BaseError.walk()`.
+     */
+    walk(fn?: (err: unknown) => boolean): unknown;
 }
 /** The Cairn Wallet extension is not installed (no `window.cairn` appeared). */
 declare class NotInstalledError extends CairnError {
@@ -32,7 +54,7 @@ declare class UserRejectedError extends CairnError {
 declare class WalletLockedError extends CairnError {
     constructor(message?: string);
 }
-/** The method is not exposed to dApps by the wallet boundary. */
+/** The method is not exposed to dApps by the wallet boundary (or the wallet is too old for it). */
 declare class UnsupportedMethodError extends CairnError {
     constructor(message?: string);
 }
@@ -48,6 +70,13 @@ declare class ContentVerificationError extends CairnError {
     expected: string;
     constructor(expected: string);
 }
+/**
+ * Map a provider error string (from the wallet's `{ ok:false, error }`) onto a typed error. The
+ * wallet's strings are stable: "rejected by user", "wallet locked", "unsupported dApp method: …".
+ */
+declare function mapProviderError(error: string): CairnError;
+/** Convenience: the stable code of any error (or "UNKNOWN" for a non-CairnError). */
+declare function errorCode(err: unknown): CairnErrorCode;
 
 interface CairnBaseUrls {
     /** Cairn board server (board + /api/rpc proxy + /content origin). Default https://cairn-substrate.com */
@@ -93,6 +122,10 @@ interface CairnConfig {
         hash: string;
     };
 }
+declare const DEFAULT_SPV_CHECKPOINT: {
+    height: number;
+    hash: string;
+};
 declare class Cairn {
     readonly config: CairnConfig;
     readonly chain: Chain;
@@ -126,4 +159,4 @@ declare class Cairn {
     get connected(): boolean;
 }
 
-export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, Chain, ContentClient, ContentVerificationError, DetectOptions, FetchLike, HttpError, IndexerClient, NotInstalledError, RegistryClient, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError };
+export { BoardClient, Cairn, type CairnBaseUrls, type CairnConfig, CairnError, type CairnErrorCode, type CairnErrorOptions, Chain, ContentClient, ContentVerificationError, DEFAULT_SPV_CHECKPOINT, DetectOptions, FetchLike, HttpError, IndexerClient, NotInstalledError, RegistryClient, SDK_VERSION, UnsupportedMethodError, UserRejectedError, WalletConnection, WalletLockedError, errorCode, mapProviderError };

package/dist/index.js

@@ -1,41 +1,86 @@
+import {
+  RegistryClient
+} from "./chunk-BGJZF7S2.js";
 import {
   BoardClient
-} from "./chunk-OGP2W7DL.js";
+} from "./chunk-FSQZVNEM.js";
 import {
   Chain,
   LightClient
-} from "./chunk-6VWLWF7R.js";
+} from "./chunk-C452UODV.js";
+import {
+  ContentClient
+} from "./chunk-MVX7VQT4.js";
+import {
+  IndexerClient
+} from "./chunk-OG4KA3LS.js";
+import {
+  CairnController
+} from "./chunk-MBSPHWZG.js";
 import {
   WalletConnection,
   connect,
   detectProvider,
+  discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-SMAPCKVG.js";
-import {
-  ContentClient
-} from "./chunk-BZVJVL4Q.js";
+} from "./chunk-K7SJOW3O.js";
 import {
   CairnError,
   ContentVerificationError,
   HttpError,
   NotInstalledError,
+  SDK_VERSION,
   UnsupportedMethodError,
   UserRejectedError,
-  WalletLockedError
-} from "./chunk-PHMU3CG5.js";
-import {
-  IndexerClient
-} from "./chunk-FNBE2FPE.js";
-import {
-  RegistryClient
-} from "./chunk-G7FABIF4.js";
+  WalletLockedError,
+  errorCode,
+  mapProviderError
+} from "./chunk-RELP23CH.js";
 
 // src/http.ts
+var DEFAULT_MAX_BYTES = 16 * 1024 * 1024;
+var ERR_TEXT_CAP = 8 * 1024;
+async function readCapped(res, maxBytes) {
+  const cl = Number(res.headers.get("content-length"));
+  if (Number.isFinite(cl) && cl > maxBytes) throw new HttpError(res.status, res.url, `response too large (content-length ${cl} > ${maxBytes})`);
+  const body = res.body;
+  if (!body || typeof body.getReader !== "function") {
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength > maxBytes) throw new HttpError(res.status, res.url, `response too large (${buf.byteLength} > ${maxBytes})`);
+    return buf;
+  }
+  const reader = body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      total += value.byteLength;
+      if (total > maxBytes) {
+        try {
+          await reader.cancel();
+        } catch {
+        }
+        throw new HttpError(res.status, res.url, `response exceeded ${maxBytes} bytes`);
+      }
+      chunks.push(value);
+    }
+  }
+  const out = new Uint8Array(total);
+  let off = 0;
+  for (const c of chunks) {
+    out.set(c, off);
+    off += c.byteLength;
+  }
+  return out;
+}
 var Http = class {
   baseUrl;
   _fetch;
   timeoutMs;
+  maxBytes;
   headers;
   constructor(opts) {
     this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
@@ -43,12 +88,17 @@ var Http = class {
     if (!f) throw new Error("No fetch available \u2014 pass `fetch` in the SDK options.");
     this._fetch = opts.fetch ? opts.fetch : f.bind(globalThis);
     this.timeoutMs = opts.timeoutMs ?? 15e3;
+    this.maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
     this.headers = opts.headers ?? {};
   }
   /** Build an absolute URL from a path + optional query params. */
   url(path, query) {
     const p = path.startsWith("/") ? path : `/${path}`;
     const u = new URL(this.baseUrl + p);
+    const basePath = new URL(this.baseUrl + "/").pathname;
+    if (basePath !== "/" && !(u.pathname + "/").startsWith(basePath)) {
+      throw new Error(`illegal path '${path}' \u2014 escapes base ${basePath}`);
+    }
     if (query) {
       for (const [k, v] of Object.entries(query)) {
         if (v !== void 0 && v !== null) u.searchParams.set(k, String(v));
@@ -79,25 +129,24 @@ var Http = class {
   async getJson(path, query) {
     const res = await this.raw("GET", path, { query });
     if (!res.ok) throw new HttpError(res.status, this.url(path, query), await safeText(res));
-    return await res.json();
+    return JSON.parse(new TextDecoder().decode(await readCapped(res, this.maxBytes)));
   }
   async postJson(path, body, headers) {
     const res = await this.raw("POST", path, { body, headers });
     if (!res.ok) throw new HttpError(res.status, this.url(path), await safeText(res));
-    return await res.json();
+    return JSON.parse(new TextDecoder().decode(await readCapped(res, this.maxBytes)));
   }
   /** GET raw bytes (for content retrieval). Returns null on 404. */
   async getBytes(path) {
     const res = await this.raw("GET", path);
     if (res.status === 404) return null;
     if (!res.ok) throw new HttpError(res.status, this.url(path), await safeText(res));
-    const buf = new Uint8Array(await res.arrayBuffer());
-    return { bytes: buf, headers: res.headers };
+    return { bytes: await readCapped(res, this.maxBytes), headers: res.headers };
   }
 };
 async function safeText(res) {
   try {
-    return await res.text();
+    return new TextDecoder().decode(await readCapped(res, ERR_TEXT_CAP));
   } catch {
     return "";
   }
@@ -186,21 +235,27 @@ var Cairn = class {
 export {
   BoardClient,
   Cairn,
+  CairnController,
   CairnError,
   Chain,
   ContentClient,
   ContentVerificationError,
+  DEFAULT_SPV_CHECKPOINT,
   Http,
   HttpError,
   IndexerClient,
   NotInstalledError,
   RegistryClient,
+  SDK_VERSION,
   UnsupportedMethodError,
   UserRejectedError,
   WalletConnection,
   WalletLockedError,
   connect,
   detectProvider,
+  discoverProviders,
+  errorCode,
   getWallet,
-  isInstalled
+  isInstalled,
+  mapProviderError
 };

package/dist/indexer.cjs

@@ -24,6 +24,13 @@ __export(indexer_exports, {
 });
 module.exports = __toCommonJS(indexer_exports);
 var import_csd_codec = require("@inversealtruism/csd-codec");
+var HEX64 = /^0x[0-9a-fA-F]{64}$/;
+var MAX_SSE_BUF = 1024 * 1024;
+function isValidMerkleProof(p) {
+  if (!p || typeof p !== "object") return false;
+  const m = p;
+  return Number.isInteger(m.block_height) && m.block_height >= 0 && Number.isInteger(m.pos) && m.pos >= 0 && typeof m.merkle_root === "string" && HEX64.test(m.merkle_root) && Array.isArray(m.merkle) && m.merkle.every((x) => typeof x === "string" && HEX64.test(x));
+}
 var IndexerClient = class {
   http;
   opts;
@@ -44,32 +51,35 @@ var IndexerClient = class {
   blockHashAtHeight(h) {
     return this.http.getJson(`/block-height/${h}`);
   }
+  // CAIRNSDK-CONTENT-HASH-PATH-1: encode every caller-supplied id segment. Raw interpolation let an id like
+  // `../../api/rpc/tip` walk `new URL` to a DIFFERENT same-origin endpoint whose body was then returned
+  // verbatim as the requested object (worse than the content case, which discards the walked-to response).
   block(hash) {
-    return this.http.getJson(`/block/${hash}`);
+    return this.http.getJson(`/block/${encodeURIComponent(hash)}`);
   }
   blockTxids(hash) {
-    return this.http.getJson(`/block/${hash}/txids`);
+    return this.http.getJson(`/block/${encodeURIComponent(hash)}/txids`);
   }
   tx(id) {
-    return this.http.getJson(`/tx/${id}`);
+    return this.http.getJson(`/tx/${encodeURIComponent(id)}`);
   }
   txStatus(id) {
-    return this.http.getJson(`/tx/${id}/status`);
+    return this.http.getJson(`/tx/${encodeURIComponent(id)}/status`);
   }
   txMerkleProof(id) {
-    return this.http.getJson(`/tx/${id}/merkle-proof`);
+    return this.http.getJson(`/tx/${encodeURIComponent(id)}/merkle-proof`);
   }
   address(a) {
-    return this.http.getJson(`/address/${a}`);
+    return this.http.getJson(`/address/${encodeURIComponent(a)}`);
   }
   addressTxs(a) {
-    return this.http.getJson(`/address/${a}/txs`);
+    return this.http.getJson(`/address/${encodeURIComponent(a)}/txs`);
   }
   addressUtxo(a) {
-    return this.http.getJson(`/address/${a}/utxo`);
+    return this.http.getJson(`/address/${encodeURIComponent(a)}/utxo`);
   }
   reputation(a) {
-    return this.http.getJson(`/address/${a}/reputation`);
+    return this.http.getJson(`/address/${encodeURIComponent(a)}/reputation`);
   }
   domains() {
     return this.http.getJson("/domains");
@@ -78,10 +88,10 @@ var IndexerClient = class {
     return this.http.getJson(`/domain/${encodeURIComponent(d)}/proposals`);
   }
   proposal(id) {
-    return this.http.getJson(`/proposal/${id}`);
+    return this.http.getJson(`/proposal/${encodeURIComponent(id)}`);
   }
   attestations(id) {
-    return this.http.getJson(`/proposal/${id}/attestations`);
+    return this.http.getJson(`/proposal/${encodeURIComponent(id)}/attestations`);
   }
   registryPeers() {
     return this.http.getJson("/registry/peers");
@@ -93,7 +103,7 @@ var IndexerClient = class {
     return this.http.getJson(`/identity/${encodeURIComponent(handle)}`);
   }
   reverseIdentity(addr) {
-    return this.http.getJson(`/address/${addr}/identity`);
+    return this.http.getJson(`/address/${encodeURIComponent(addr)}/identity`);
   }
   // ---- trust-minimized inclusion ----------------------------------------
   /**
@@ -102,9 +112,11 @@ var IndexerClient = class {
    * proof's root is cross-checked against the header merkle at that height →
    * trustLevel "verified-inclusion" (only as trustworthy as that header source —
    * see headerMerkleAt). Otherwise the proof is only internally consistent →
-   * "proof-consistent" (still useful, but the indexer is trusted). The Cairn
-   * facade wires headerMerkleAt ONLY when the node RPC is an independent origin
-   * from the indexer, so the default same-origin setup stays at "proof-consistent".
+   * "proof-consistent" (still useful, but the indexer is trusted). INDEXER-DOC-STALE-1: the Cairn facade now
+   * wires headerMerkleAt UNCONDITIONALLY via a PoW-verifying checkpoint light client (index.ts), so the
+   * default reaches "verified-inclusion" when the proof root matches the PoW-verified header — what makes a
+   * same-origin RPC safe is the forward PoW re-verification, not an origin gate (which no longer exists).
+   * Fails closed: a malformed proof or a chain-disagreement returns "not-found" (the latter with equivocation:true).
    */
   async verifyInclusion(txid) {
     let proof;
@@ -113,7 +125,15 @@ var IndexerClient = class {
     } catch {
       return { included: false, trustLevel: "not-found", reason: "no merkle proof (tx not indexed)" };
     }
-    const folds = (0, import_csd_codec.verifyMerkleProof)(txid, proof.pos, proof.merkle, proof.merkle_root);
+    if (!isValidMerkleProof(proof)) {
+      return { included: false, trustLevel: "not-found", reason: "malformed merkle proof" };
+    }
+    let folds = false;
+    try {
+      folds = (0, import_csd_codec.verifyMerkleProof)(txid, proof.pos, proof.merkle, proof.merkle_root);
+    } catch {
+      return { included: false, trustLevel: "not-found", blockHeight: proof.block_height, reason: "malformed merkle proof" };
+    }
     if (!folds) {
       return { included: false, trustLevel: "not-found", blockHeight: proof.block_height, reason: "merkle branch does not fold to the claimed root" };
     }
@@ -121,7 +141,7 @@ var IndexerClient = class {
       try {
         const onchain = await this.opts.headerMerkleAt(proof.block_height);
         if (norm(onchain) !== norm(proof.merkle_root)) {
-          return { included: false, trustLevel: "not-found", blockHeight: proof.block_height, reason: "proof root != on-chain header merkle (indexer disagrees with chain)" };
+          return { included: false, trustLevel: "not-found", equivocation: true, blockHeight: proof.block_height, reason: "proof root != on-chain header merkle (indexer disagrees with chain)" };
         }
         return { included: true, trustLevel: "verified-inclusion", blockHeight: proof.block_height, pos: proof.pos, merkleRoot: proof.merkle_root };
       } catch {
@@ -145,6 +165,11 @@ var IndexerClient = class {
   /**
    * Subscribe over WebSocket with selective tracking. Returns a handle with
    * `.close()`. `onEvent` receives every matching IndexEvent (incl. reorgs).
+   *
+   * WS-NORECONNECT-1: unlike the SSE feeds (streamAll/streamBlocks/streamDomain, which auto-reconnect with
+   * backoff), this WebSocket subscription does NOT auto-reconnect — it surfaces a terminal error via
+   * `onError` (when provided) and stops. A consumer tracking reorgs over WS MUST re-`subscribe()` on error
+   * to avoid a silently-stale view; for built-in reconnect prefer the SSE `stream*` methods.
    */
   subscribe(sub, onEvent, onError) {
     const WS = this.opts.WebSocketImpl ?? globalThis.WebSocket;
@@ -207,6 +232,13 @@ var IndexerClient = class {
               buf = buf.slice(idx + 2);
               dispatchFrame(frame, handlers);
             }
+            if (buf.length > MAX_SSE_BUF) {
+              try {
+                await reader.cancel();
+              } catch {
+              }
+              throw new Error(`SSE buffer exceeded ${MAX_SSE_BUF} bytes with no frame delimiter \u2014 aborting`);
+            }
           }
         } catch (err) {
           if (closed) return;

package/dist/indexer.d.cts

@@ -1,4 +1,4 @@
-import { H as Http, F as FetchLike } from './http-D2CzfOsm.cjs';
+import { H as Http, F as FetchLike } from './http-CQsNL8w9.cjs';
 
 interface MerkleProof {
     block_height: number;
@@ -14,6 +14,10 @@ interface InclusionResult {
     pos?: number;
     merkleRoot?: string;
     reason?: string;
+    /** CAIRN-SPV-3: set true when a folding proof's root conflicts with the PoW-verified on-chain header
+     *  merkle (active indexer↔chain equivocation/tamper) — distinct from an honest tx-absence. Consumers that
+     *  retry on `not-found` MUST check this and treat it as a detected attack, NOT a benign miss. */
+    equivocation?: boolean;
 }
 /** A live index event ({ kind: "block" | "proposal" | "attestation" | "reorg", ... }). */
 interface IndexEvent {
@@ -71,9 +75,11 @@ declare class IndexerClient {
      * proof's root is cross-checked against the header merkle at that height →
      * trustLevel "verified-inclusion" (only as trustworthy as that header source —
      * see headerMerkleAt). Otherwise the proof is only internally consistent →
-     * "proof-consistent" (still useful, but the indexer is trusted). The Cairn
-     * facade wires headerMerkleAt ONLY when the node RPC is an independent origin
-     * from the indexer, so the default same-origin setup stays at "proof-consistent".
+     * "proof-consistent" (still useful, but the indexer is trusted). INDEXER-DOC-STALE-1: the Cairn facade now
+     * wires headerMerkleAt UNCONDITIONALLY via a PoW-verifying checkpoint light client (index.ts), so the
+     * default reaches "verified-inclusion" when the proof root matches the PoW-verified header — what makes a
+     * same-origin RPC safe is the forward PoW re-verification, not an origin gate (which no longer exists).
+     * Fails closed: a malformed proof or a chain-disagreement returns "not-found" (the latter with equivocation:true).
      */
     verifyInclusion(txid: string): Promise<InclusionResult>;
     /** Stream all events (blocks, proposals, attestations, reorgs) via SSE. */
@@ -85,6 +91,11 @@ declare class IndexerClient {
     /**
      * Subscribe over WebSocket with selective tracking. Returns a handle with
      * `.close()`. `onEvent` receives every matching IndexEvent (incl. reorgs).
+     *
+     * WS-NORECONNECT-1: unlike the SSE feeds (streamAll/streamBlocks/streamDomain, which auto-reconnect with
+     * backoff), this WebSocket subscription does NOT auto-reconnect — it surfaces a terminal error via
+     * `onError` (when provided) and stops. A consumer tracking reorgs over WS MUST re-`subscribe()` on error
+     * to avoid a silently-stale view; for built-in reconnect prefer the SSE `stream*` methods.
      */
     subscribe(sub: {
         all?: boolean;

package/dist/indexer.d.ts

@@ -1,4 +1,4 @@
-import { H as Http, F as FetchLike } from './http-D2CzfOsm.js';
+import { H as Http, F as FetchLike } from './http-CQsNL8w9.js';
 
 interface MerkleProof {
     block_height: number;
@@ -14,6 +14,10 @@ interface InclusionResult {
     pos?: number;
     merkleRoot?: string;
     reason?: string;
+    /** CAIRN-SPV-3: set true when a folding proof's root conflicts with the PoW-verified on-chain header
+     *  merkle (active indexer↔chain equivocation/tamper) — distinct from an honest tx-absence. Consumers that
+     *  retry on `not-found` MUST check this and treat it as a detected attack, NOT a benign miss. */
+    equivocation?: boolean;
 }
 /** A live index event ({ kind: "block" | "proposal" | "attestation" | "reorg", ... }). */
 interface IndexEvent {
@@ -71,9 +75,11 @@ declare class IndexerClient {
      * proof's root is cross-checked against the header merkle at that height →
      * trustLevel "verified-inclusion" (only as trustworthy as that header source —
      * see headerMerkleAt). Otherwise the proof is only internally consistent →
-     * "proof-consistent" (still useful, but the indexer is trusted). The Cairn
-     * facade wires headerMerkleAt ONLY when the node RPC is an independent origin
-     * from the indexer, so the default same-origin setup stays at "proof-consistent".
+     * "proof-consistent" (still useful, but the indexer is trusted). INDEXER-DOC-STALE-1: the Cairn facade now
+     * wires headerMerkleAt UNCONDITIONALLY via a PoW-verifying checkpoint light client (index.ts), so the
+     * default reaches "verified-inclusion" when the proof root matches the PoW-verified header — what makes a
+     * same-origin RPC safe is the forward PoW re-verification, not an origin gate (which no longer exists).
+     * Fails closed: a malformed proof or a chain-disagreement returns "not-found" (the latter with equivocation:true).
      */
     verifyInclusion(txid: string): Promise<InclusionResult>;
     /** Stream all events (blocks, proposals, attestations, reorgs) via SSE. */
@@ -85,6 +91,11 @@ declare class IndexerClient {
     /**
      * Subscribe over WebSocket with selective tracking. Returns a handle with
      * `.close()`. `onEvent` receives every matching IndexEvent (incl. reorgs).
+     *
+     * WS-NORECONNECT-1: unlike the SSE feeds (streamAll/streamBlocks/streamDomain, which auto-reconnect with
+     * backoff), this WebSocket subscription does NOT auto-reconnect — it surfaces a terminal error via
+     * `onError` (when provided) and stops. A consumer tracking reorgs over WS MUST re-`subscribe()` on error
+     * to avoid a silently-stale view; for built-in reconnect prefer the SSE `stream*` methods.
      */
     subscribe(sub: {
         all?: boolean;

package/dist/indexer.js

@@ -1,6 +1,6 @@
 import {
   IndexerClient
-} from "./chunk-FNBE2FPE.js";
+} from "./chunk-OG4KA3LS.js";
 export {
   IndexerClient
 };