@inversealtruism/cairn-sdk 0.1.2 → 0.1.4

package/dist/{chunk-BZVJVL4Q.js → chunk-MVX7VQT4.js}

@@ -1,6 +1,6 @@
 import {
   ContentVerificationError
-} from "./chunk-PHMU3CG5.js";
+} from "./chunk-RELP23CH.js";
 
 // src/content.ts
 import { payloadHash, canonicalJson, verifyContentBytes } from "@inversealtruism/csd-codec";
@@ -67,8 +67,9 @@ var ContentClient = class {
   }
 };
 function normalizeHash(hash) {
-  const h = hash.startsWith("0x") || hash.startsWith("0X") ? hash : `0x${hash}`;
-  return h.toLowerCase();
+  const h = (hash.startsWith("0x") || hash.startsWith("0X") ? hash : `0x${hash}`).toLowerCase();
+  if (!/^0x[0-9a-f]{64}$/.test(h)) throw new Error(`invalid content hash: ${hash}`);
+  return h;
 }
 
 export {

package/dist/{chunk-FNBE2FPE.js → chunk-OG4KA3LS.js}

@@ -1,5 +1,12 @@
 // src/indexer.ts
 import { verifyMerkleProof } from "@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;
@@ -20,32 +27,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");
@@ -54,10 +64,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");
@@ -69,7 +79,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 ----------------------------------------
   /**
@@ -78,9 +88,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;
@@ -89,7 +101,15 @@ var IndexerClient = class {
     } catch {
       return { included: false, trustLevel: "not-found", reason: "no merkle proof (tx not indexed)" };
     }
-    const folds = 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 = 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" };
     }
@@ -97,7 +117,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 {
@@ -121,6 +141,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;
@@ -183,6 +208,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/chunk-RELP23CH.js

@@ -0,0 +1,99 @@
+// src/errors.ts
+var SDK_VERSION = "0.1.4";
+var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
+var CairnError = class extends Error {
+  /** Stable machine code for programmatic branching. */
+  code;
+  /** The human message without the appended docs/version footer. */
+  shortMessage;
+  /** Relative docs path (under the SDK docs base), if any. */
+  docsPath;
+  /** The cairn-sdk version that produced this error. */
+  version = SDK_VERSION;
+  constructor(shortMessage, opts = {}) {
+    const docs = opts.docsPath;
+    super(
+      [shortMessage, docs ? `Docs: ${DOCS_BASE}${docs}` : "", `Version: cairn-sdk@${SDK_VERSION}`].filter(Boolean).join("\n"),
+      { cause: opts.cause }
+    );
+    this.name = new.target.name;
+    this.code = opts.code ?? "UNKNOWN";
+    this.shortMessage = shortMessage;
+    this.docsPath = docs;
+  }
+  /**
+   * 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) {
+    let current = this;
+    let last = this;
+    while (current != null) {
+      if (fn && fn(current)) return current;
+      last = current;
+      current = current?.cause;
+    }
+    return fn ? null : last;
+  }
+};
+var NotInstalledError = class extends CairnError {
+  constructor(message = "Cairn Wallet not detected. Install it from cairn-substrate.com.") {
+    super(message, { code: "NOT_INSTALLED", docsPath: "/install" });
+  }
+};
+var UserRejectedError = class extends CairnError {
+  constructor(message = "Request rejected by user.") {
+    super(message, { code: "USER_REJECTED", docsPath: "/errors#user-rejected" });
+  }
+};
+var WalletLockedError = class extends CairnError {
+  constructor(message = "Wallet is locked.") {
+    super(message, { code: "WALLET_LOCKED", docsPath: "/errors#wallet-locked" });
+  }
+};
+var UnsupportedMethodError = class extends CairnError {
+  constructor(message = "Method not supported by the wallet.") {
+    super(message, { code: "UNSUPPORTED_METHOD", docsPath: "/errors#unsupported-method" });
+  }
+};
+var HttpError = class extends CairnError {
+  status;
+  url;
+  body;
+  constructor(status, url, body) {
+    super(`HTTP ${status} for ${url}${body ? `: ${String(body).slice(0, 200)}` : ""}`, { code: "HTTP_ERROR" });
+    this.status = status;
+    this.url = url;
+    this.body = body;
+  }
+};
+var ContentVerificationError = class extends CairnError {
+  expected;
+  constructor(expected) {
+    super(`Content does not match its payload hash ${expected} \u2014 bytes were tampered with in transit.`, { code: "CONTENT_VERIFICATION", docsPath: "/content#verification" });
+    this.expected = expected;
+  }
+};
+function mapProviderError(error) {
+  const e = String(error || "").toLowerCase();
+  if (e.includes("rejected by user")) return new UserRejectedError(error);
+  if (e.includes("wallet locked")) return new WalletLockedError(error);
+  if (e.includes("unsupported dapp method") || e.includes("predates") || e.includes("too old")) return new UnsupportedMethodError(error);
+  return new CairnError(error || "Unknown wallet error");
+}
+function errorCode(err) {
+  return err instanceof CairnError ? err.code : "UNKNOWN";
+}
+
+export {
+  SDK_VERSION,
+  CairnError,
+  NotInstalledError,
+  UserRejectedError,
+  WalletLockedError,
+  UnsupportedMethodError,
+  HttpError,
+  ContentVerificationError,
+  mapProviderError,
+  errorCode
+};

package/dist/connect.cjs

@@ -23,47 +23,99 @@ __export(connect_exports, {
   WalletConnection: () => WalletConnection,
   connect: () => connect,
   detectProvider: () => detectProvider,
+  discoverProviders: () => discoverProviders,
   getWallet: () => getWallet,
   isInstalled: () => isInstalled
 });
 module.exports = __toCommonJS(connect_exports);
 
 // src/errors.ts
+var SDK_VERSION = "0.1.4";
+var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
-  constructor(message) {
-    super(message);
+  /** Stable machine code for programmatic branching. */
+  code;
+  /** The human message without the appended docs/version footer. */
+  shortMessage;
+  /** Relative docs path (under the SDK docs base), if any. */
+  docsPath;
+  /** The cairn-sdk version that produced this error. */
+  version = SDK_VERSION;
+  constructor(shortMessage, opts = {}) {
+    const docs = opts.docsPath;
+    super(
+      [shortMessage, docs ? `Docs: ${DOCS_BASE}${docs}` : "", `Version: cairn-sdk@${SDK_VERSION}`].filter(Boolean).join("\n"),
+      { cause: opts.cause }
+    );
     this.name = new.target.name;
+    this.code = opts.code ?? "UNKNOWN";
+    this.shortMessage = shortMessage;
+    this.docsPath = docs;
+  }
+  /**
+   * 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) {
+    let current = this;
+    let last = this;
+    while (current != null) {
+      if (fn && fn(current)) return current;
+      last = current;
+      current = current?.cause;
+    }
+    return fn ? null : last;
   }
 };
 var NotInstalledError = class extends CairnError {
   constructor(message = "Cairn Wallet not detected. Install it from cairn-substrate.com.") {
-    super(message);
+    super(message, { code: "NOT_INSTALLED", docsPath: "/install" });
   }
 };
 var UserRejectedError = class extends CairnError {
   constructor(message = "Request rejected by user.") {
-    super(message);
+    super(message, { code: "USER_REJECTED", docsPath: "/errors#user-rejected" });
   }
 };
 var WalletLockedError = class extends CairnError {
   constructor(message = "Wallet is locked.") {
-    super(message);
+    super(message, { code: "WALLET_LOCKED", docsPath: "/errors#wallet-locked" });
   }
 };
 var UnsupportedMethodError = class extends CairnError {
   constructor(message = "Method not supported by the wallet.") {
-    super(message);
+    super(message, { code: "UNSUPPORTED_METHOD", docsPath: "/errors#unsupported-method" });
   }
 };
 function mapProviderError(error) {
   const e = String(error || "").toLowerCase();
   if (e.includes("rejected by user")) return new UserRejectedError(error);
   if (e.includes("wallet locked")) return new WalletLockedError(error);
-  if (e.includes("unsupported dapp method")) return new UnsupportedMethodError(error);
+  if (e.includes("unsupported dapp method") || e.includes("predates") || e.includes("too old")) return new UnsupportedMethodError(error);
   return new CairnError(error || "Unknown wallet error");
 }
 
 // src/connect.ts
+function discoverProviders(opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 1e3;
+  return new Promise((resolve) => {
+    if (typeof window === "undefined") {
+      resolve([]);
+      return;
+    }
+    const found = /* @__PURE__ */ new Map();
+    const onAnnounce = (ev) => {
+      const d = ev?.detail;
+      if (d?.info?.uuid && d?.provider?.isCairn) found.set(d.info.uuid, d);
+    };
+    window.addEventListener("csd:announceProvider", onAnnounce);
+    window.dispatchEvent(new CustomEvent("csd:requestProvider"));
+    setTimeout(() => {
+      window.removeEventListener("csd:announceProvider", onAnnounce);
+      resolve([...found.values()]);
+    }, timeoutMs);
+  });
+}
 function detectProvider(opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 3e3;
   return new Promise((resolve, reject) => {
@@ -71,18 +123,19 @@ function detectProvider(opts = {}) {
       reject(new NotInstalledError("Not running in a browser \u2014 `window.cairn` is unavailable."));
       return;
     }
-    if (window.cairn?.isCairn) {
-      resolve(window.cairn);
-      return;
-    }
     let done = false;
-    const onInit = () => {
+    const finish = (p) => {
       if (done) return;
-      if (window.cairn?.isCairn) {
-        done = true;
-        cleanup();
-        resolve(window.cairn);
-      }
+      done = true;
+      cleanup();
+      resolve(p);
+    };
+    const onInit = () => {
+      if (!done && window.cairn?.isCairn) finish(window.cairn);
+    };
+    const onAnnounce = (ev) => {
+      const p = ev?.detail?.provider;
+      if (p?.isCairn) finish(p);
     };
     const timer = setTimeout(() => {
       if (done) return;
@@ -93,8 +146,15 @@ function detectProvider(opts = {}) {
     const cleanup = () => {
       clearTimeout(timer);
       window.removeEventListener("cairn#initialized", onInit);
+      window.removeEventListener("csd:announceProvider", onAnnounce);
     };
     window.addEventListener("cairn#initialized", onInit);
+    window.addEventListener("csd:announceProvider", onAnnounce);
+    if (window.cairn?.isCairn) {
+      finish(window.cairn);
+      return;
+    }
+    window.dispatchEvent(new CustomEvent("csd:requestProvider"));
     onInit();
   });
 }
@@ -131,10 +191,76 @@ var WalletConnection = class {
     this._addr = addr;
     return addr;
   }
-  /** Passwordless sign-in: a signature over a login nonce (always prompts; structurally cannot sign a tx). */
+  /**
+   * @deprecated First-party-only legacy login (it authenticates against the wallet's own configured
+   * server and is rejected from third-party origins). Use {@link signInWithCsd} for any site.
+   * Passwordless sign-in: a signature over a login nonce (always prompts; structurally cannot sign a tx).
+   */
   signIn() {
     return Promise.resolve(this.provider.signIn()).then(unwrap);
   }
+  /**
+   * Audience-bound "Sign in with CSD" (SIWC) — the secure, replay-resistant third-party login.
+   * The wallet binds the REAL requesting origin + your single-use server `nonce` into the signed
+   * message and returns the artifact; it never mints a session. VERIFY the result SERVER-SIDE with
+   * `verifySiwc` from `@inversealtruism/csd-siwc` (domain/nonce/chain/time/signature/account), then
+   * issue your OWN session. The signature is proof-of-control, NOT a bearer token. Always prompts.
+   */
+  signInWithCsd(params) {
+    if (!params || typeof params.nonce !== "string" || !params.nonce) {
+      return Promise.reject(new UnsupportedMethodError("signInWithCsd requires a server-issued { nonce }"));
+    }
+    if (typeof this.provider.signInWithCsd !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet predates Sign-in-with-CSD \u2014 ask the user to update the Cairn Wallet"));
+    }
+    return Promise.resolve(this.provider.signInWithCsd(params)).then(unwrap);
+  }
+  /** True if this wallet supports audience-bound SIWC (safe to call `signInWithCsd`). */
+  get supportsSiwc() {
+    return typeof this.provider.signInWithCsd === "function";
+  }
+  /** Feature/capability detection. Returns null if the wallet predates `getCapabilities`. */
+  async getCapabilities() {
+    if (typeof this.provider.getCapabilities !== "function") return null;
+    try {
+      return await this.provider.getCapabilities();
+    } catch {
+      return null;
+    }
+  }
+  /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
+  fillOffer(params) {
+    return Promise.resolve(this.provider.fillOffer(params)).then(unwrap);
+  }
+  /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
+  async getPermissions() {
+    if (typeof this.provider.getPermissions !== "function") return [];
+    return unwrap(await this.provider.getPermissions());
+  }
+  /** Explicitly request permission to see the address (prompts, like connect). */
+  requestPermissions() {
+    if (typeof this.provider.requestPermissions !== "function") {
+      return Promise.reject(new UnsupportedMethodError("this wallet predates requestPermissions \u2014 use connect()"));
+    }
+    return Promise.resolve(this.provider.requestPermissions()).then(unwrap);
+  }
+  /** Revoke THIS origin's own access (silent). Returns { revoked }. Safe no-op on older wallets. */
+  async revokePermissions() {
+    if (typeof this.provider.revokePermissions !== "function") return { revoked: false };
+    return unwrap(await this.provider.revokePermissions());
+  }
+  /**
+   * Subscribe to provider events. `accountsChanged` fires with `[]` when this site loses access
+   * (wallet lock / account switch / revoke) — re-call connect() to (re)share; `disconnect` likewise.
+   * No-op if the wallet predates events. Use the SAME handler reference with off() to unsubscribe.
+   */
+  on(event, handler) {
+    this.provider.on?.(event, handler);
+  }
+  /** Remove a previously-added event handler (must be the same reference passed to on()). */
+  off(event, handler) {
+    this.provider.removeListener?.(event, handler);
+  }
   /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
   send(params) {
     return Promise.resolve(this.provider.send(params)).then(unwrap);
@@ -172,6 +298,7 @@ async function connect(opts = {}) {
   WalletConnection,
   connect,
   detectProvider,
+  discoverProviders,
   getWallet,
   isInstalled
 });