@inversealtruism/cairn-sdk 0.4.0 → 0.4.2

package/dist/board.cjs

@@ -27,7 +27,7 @@ var import_csd_codec = require("@inversealtruism/csd-codec");
 var import_csd_codec2 = require("@inversealtruism/csd-codec");
 
 // src/errors.ts
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.4.2";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/board.js

@@ -1,7 +1,7 @@
 import {
   BoardClient
-} from "./chunk-2ZML7IKV.js";
-import "./chunk-MREZG2HN.js";
+} from "./chunk-XPTP5W75.js";
+import "./chunk-REHDMKBF.js";
 export {
   BoardClient
 };

package/dist/{chunk-GTTLMWGY.js → chunk-FS2BQWA5.js}

@@ -1,12 +1,15 @@
 import {
   getWallet
-} from "./chunk-RKR3JMIA.js";
+} from "./chunk-VGKXFRHY.js";
 
 // src/controller.ts
 var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error: null });
 var CairnController = class {
   state = DISCONNECTED;
   conn = null;
+  // MF-15: connect/disconnect generation token. disconnect() bumps it; a connect() whose await straddled
+  // the bump must never commit "connected" over the torn-down session (a zombie null-connection session).
+  epoch = 0;
   listeners = /* @__PURE__ */ new Set();
   getWalletFn;
   detectOpts;
@@ -59,34 +62,43 @@ var CairnController = class {
   }
   /** Detect + connect (prompts the user the first time per origin). Resolves the connected address. */
   connect = async () => {
+    const epoch = this.epoch;
     this.setState({ status: "connecting", error: null });
     try {
-      if (!this.conn) {
-        this.conn = await this.getWalletFn(this.detectOpts);
-        this.conn.on("accountsChanged", this.onAccounts);
-        this.conn.on("disconnect", this.onDisconnect);
+      let conn = this.conn;
+      if (!conn) {
+        conn = await this.getWalletFn(this.detectOpts);
+        if (epoch !== this.epoch) throw new Error("connection was torn down while connecting - call connect() again");
+        conn.on("accountsChanged", this.onAccounts);
+        conn.on("disconnect", this.onDisconnect);
+        this.conn = conn;
       }
-      const addr = await this.conn.connect();
+      const addr = await conn.connect();
+      if (epoch !== this.epoch) throw new Error("connection was torn down while awaiting approval - call connect() again");
       this.setState({ status: "connected", account: addr, error: null });
       return addr;
     } catch (e) {
-      this.setState({ status: "disconnected", account: null, error: e?.message ?? String(e) });
+      if (epoch === this.epoch) this.setState({ status: "disconnected", account: null, error: e?.message ?? String(e) });
       throw e;
     }
   };
-  /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort). */
+  /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort).
+   *  Local teardown is IMMEDIATE and unconditional; the wallet-side revoke happens after, so a hung
+   *  provider can never hold a torn-down session in "connected". */
   disconnect = async () => {
-    try {
-      await this.conn?.revokePermissions();
-    } catch {
-    }
+    this.epoch++;
+    const conn = this.conn;
     this.detach();
     this.conn = null;
     this.setState({ status: "disconnected", account: null, error: null });
+    try {
+      await conn?.revokePermissions();
+    } catch {
+    }
   };
   /** Audience-bound sign-in (must connect() first). Returns the signed artifact to verify server-side. */
   signInWithCsd = (params) => {
-    if (!this.conn) return Promise.reject(new Error("call connect() before signInWithCsd()"));
+    if (!this.conn || this.state.status !== "connected") return Promise.reject(new Error("call connect() before signInWithCsd()"));
     return this.conn.signInWithCsd(params);
   };
 };

package/dist/{chunk-2L5QNDAE.js → chunk-PZEQ4YHR.js}

@@ -1,6 +1,6 @@
 import {
   ContentVerificationError
-} from "./chunk-MREZG2HN.js";
+} from "./chunk-REHDMKBF.js";
 
 // src/content.ts
 import { payloadHash, canonicalJson, verifyContentBytes } from "@inversealtruism/csd-codec";

package/dist/{chunk-MREZG2HN.js → chunk-REHDMKBF.js}

@@ -1,5 +1,5 @@
 // src/errors.ts
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.4.2";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/{chunk-RKR3JMIA.js → chunk-VGKXFRHY.js}

@@ -4,7 +4,7 @@ import {
   UnsupportedMethodError,
   mapProviderError,
   mapSubmitResultError
-} from "./chunk-MREZG2HN.js";
+} from "./chunk-REHDMKBF.js";
 
 // src/connect.ts
 var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;
@@ -99,12 +99,15 @@ var WalletConnection = class {
   // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
   call(op, label) {
     const ms = this._timeoutMs;
-    if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve(op());
+    const invoke = () => new Promise((resolve) => {
+      resolve(op());
+    });
+    if (!Number.isFinite(ms) || ms <= 0) return invoke();
     let timer;
     const timeout = new Promise((_, reject) => {
       timer = setTimeout(() => reject(new CairnError(`the wallet did not respond to ${label} within ${ms}ms`, { retryable: false })), ms);
     });
-    return Promise.race([Promise.resolve(op()), timeout]).finally(() => clearTimeout(timer));
+    return Promise.race([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
   /** The wallet's version string (e.g. "0.2.x"). */
   get version() {
@@ -177,8 +180,24 @@ var WalletConnection = class {
     if (typeof this.provider.fillOffer !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
     }
+    this.adviseFillSpvCapability();
     return this.call(() => this.provider.fillOffer(params), "fillOffer").then(unwrapWrite);
   }
+  // P75-5 MF-10: ONE capability advisory per connection. The wallet's on-device fill-SPV (0.2.60+) is the
+  // payment-grade fill boundary; when the provider SELF-REPORTS an older version, warn the integrator once
+  // and STILL RELAY. WARN, NEVER BLOCK: a hard version gate would decline honest fills (version strings are
+  // spoofable and unparseable forks exist), and the wallet itself is the enforcement point. Reads only the
+  // sync `provider.version`; never an awaited getCapabilities() round-trip on the fill hot path. An
+  // unparseable version never warns (no false alarms).
+  _fillSpvAdvised = false;
+  adviseFillSpvCapability() {
+    if (this._fillSpvAdvised) return;
+    this._fillSpvAdvised = true;
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(this.provider?.version ?? ""));
+    if (!m) return;
+    const below = Number(m[1]) === 0 && (Number(m[2]) < 2 || Number(m[2]) === 2 && Number(m[3]) < 60);
+    if (below) console.warn(`[cairn-sdk] this Cairn Wallet (v${m[0]}) predates the on-device fill-SPV boundary (cairn-wallet 0.2.60+). The fill proceeds; suggest a wallet update for payment-grade offer verification.`);
+  }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
   async getPermissions() {
     if (typeof this.provider.getPermissions !== "function") return [];

package/dist/chunk-WBU7KDI3.js

@@ -0,0 +1,224 @@
+import {
+  HttpError
+} from "./chunk-REHDMKBF.js";
+
+// src/registry.ts
+import { fromRecords } from "@inversealtruism/csd-registry";
+
+// 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;
+  retries;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    const f = opts.fetch ?? globalThis.fetch;
+    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 ?? {};
+    this.retries = Math.min(10, Math.max(0, Math.floor(opts.retries ?? 0)));
+  }
+  /** 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));
+      }
+    }
+    return u.toString();
+  }
+  async raw(method, path, opts) {
+    const url = this.url(path, opts?.query);
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+    try {
+      const res = await this._fetch(url, {
+        method,
+        signal: ctrl.signal,
+        headers: {
+          ...opts?.body !== void 0 ? { "content-type": "application/json" } : {},
+          ...this.headers,
+          ...opts?.headers ?? {}
+        },
+        body: opts?.body !== void 0 ? JSON.stringify(opts.body) : void 0
+      });
+      return res;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // A malformed 2xx body must surface as a TYPED HttpError, not a leaked SyntaxError (B10: dApp
+  // code branches on `instanceof CairnError`; a raw parse error escaped that contract).
+  parseJson(res, text, url) {
+    try {
+      return JSON.parse(text);
+    } catch (e) {
+      throw new HttpError(res.status, url, `invalid JSON body: ${text.slice(0, 120)}`);
+    }
+  }
+  async getJson(path, query) {
+    const url = this.url(path, query);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const res = await this.raw("GET", path, { query });
+        if (!res.ok) {
+          if (!(res.status >= 500 && attempt < this.retries)) throw new HttpError(res.status, url, await safeText(res));
+          res.body?.cancel().catch(() => {
+          });
+        } else {
+          return this.parseJson(res, new TextDecoder().decode(await readCapped(res, this.maxBytes)), url);
+        }
+      } catch (e) {
+        if (e instanceof HttpError && e.status < 500) throw e;
+        if (attempt >= this.retries) throw e;
+      }
+      await new Promise((r) => setTimeout(r, Math.floor(Math.random() * Math.min(4e3, 250 * 2 ** attempt))));
+    }
+  }
+  async postJson(path, body, headers) {
+    const url = this.url(path);
+    const res = await this.raw("POST", path, { body, headers });
+    if (!res.ok) throw new HttpError(res.status, url, await safeText(res));
+    return this.parseJson(res, new TextDecoder().decode(await readCapped(res, this.maxBytes)), url);
+  }
+  /** 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));
+    return { bytes: await readCapped(res, this.maxBytes), headers: res.headers };
+  }
+};
+async function safeText(res) {
+  try {
+    return new TextDecoder().decode(await readCapped(res, ERR_TEXT_CAP));
+  } catch {
+    return "";
+  }
+}
+
+// src/registry.ts
+import {
+  fromRecords as fromRecords2,
+  verifyPeer,
+  verifyGateway,
+  verifyIdentitySig,
+  DOMAINS,
+  buildPeerRecord,
+  buildGatewayRecord,
+  buildIdentityCommit,
+  buildIdentityReveal,
+  epochOf
+} from "@inversealtruism/csd-registry";
+var RegistryClient = class {
+  http;
+  /** Accepts the SDK's hardened Http directly (the Cairn facade path) or the legacy
+   *  { baseUrl, fetch } options (kept for direct constructors; they now get the same
+   *  hardened transport, built internally). */
+  constructor(src) {
+    this.http = src instanceof Http ? src : new Http({ baseUrl: src.baseUrl, fetch: src.fetch });
+  }
+  /** Discover ranked content/pin gateways (GET /registry/gateways). */
+  gateways() {
+    return this.http.getJson("/registry/gateways");
+  }
+  /** Discover ranked libp2p peers (GET /registry/peers). */
+  peers() {
+    return this.http.getJson("/registry/peers");
+  }
+  /**
+   * Resolve a handle → identity (GET /identity/:handle). Returns null if unresolved.
+   *
+   * ⚠ TRUST (CAIRN-SDK-RESOLVE-VERIFIED-FOOTGUN): the returned `verified` flag is the INDEXER's assertion,
+   * NOT a client-side proof. A hostile/compromised indexer (or a MITM of the read proxy) can return
+   * `verified:true` for a wrong address. Do NOT use this directly as a payee/login target without either (a)
+   * recomputing from raw records via `fromRecords.name(...)`, or (b) cross-checking a second independent
+   * source (the wallet's namespv union cure). Treat `verified` here as a hint, not a guarantee.
+   */
+  resolveName(handle) {
+    return this.getOr404Null(`/identity/${encodeURIComponent(handle)}`);
+  }
+  /** Reverse-resolve an address → identity (GET /address/:addr/identity).
+   *  ⚠ Same indexer-trust caveat as resolveName — `verified` is the indexer's claim, not a client proof. */
+  reverseName(address) {
+    return this.getOr404Null(`/address/${encodeURIComponent(address)}/identity`);
+  }
+  // MF-12: 404 → null (the preserved csd-registry contract for both name resolvers); every other
+  // failure rethrows the typed HttpError/CairnError the hardened Http raises.
+  async getOr404Null(path) {
+    try {
+      return await this.http.getJson(path);
+    } catch (e) {
+      if (e instanceof HttpError && e.status === 404) return null;
+      return Promise.reject(e);
+    }
+  }
+  /** The deterministic, client-side resolvers (recompute from raw ChainRecord[]). */
+  get fromRecords() {
+    return fromRecords;
+  }
+};
+
+export {
+  readCapped,
+  Http,
+  RegistryClient,
+  fromRecords2 as fromRecords,
+  verifyPeer,
+  verifyGateway,
+  verifyIdentitySig,
+  DOMAINS,
+  buildPeerRecord,
+  buildGatewayRecord,
+  buildIdentityCommit,
+  buildIdentityReveal,
+  epochOf
+};

package/dist/{chunk-2ZML7IKV.js → chunk-XPTP5W75.js}

@@ -1,6 +1,6 @@
 import {
   CairnError
-} from "./chunk-MREZG2HN.js";
+} from "./chunk-REHDMKBF.js";
 
 // src/board.ts
 import { payloadHash } from "@inversealtruism/csd-codec";

package/dist/connect.cjs

@@ -30,7 +30,7 @@ __export(connect_exports, {
 module.exports = __toCommonJS(connect_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.4.2";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -240,12 +240,15 @@ var WalletConnection = class {
   // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
   call(op, label) {
     const ms = this._timeoutMs;
-    if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve(op());
+    const invoke = () => new Promise((resolve) => {
+      resolve(op());
+    });
+    if (!Number.isFinite(ms) || ms <= 0) return invoke();
     let timer;
     const timeout = new Promise((_, reject) => {
       timer = setTimeout(() => reject(new CairnError(`the wallet did not respond to ${label} within ${ms}ms`, { retryable: false })), ms);
     });
-    return Promise.race([Promise.resolve(op()), timeout]).finally(() => clearTimeout(timer));
+    return Promise.race([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
   /** The wallet's version string (e.g. "0.2.x"). */
   get version() {
@@ -318,8 +321,24 @@ var WalletConnection = class {
     if (typeof this.provider.fillOffer !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
     }
+    this.adviseFillSpvCapability();
     return this.call(() => this.provider.fillOffer(params), "fillOffer").then(unwrapWrite);
   }
+  // P75-5 MF-10: ONE capability advisory per connection. The wallet's on-device fill-SPV (0.2.60+) is the
+  // payment-grade fill boundary; when the provider SELF-REPORTS an older version, warn the integrator once
+  // and STILL RELAY. WARN, NEVER BLOCK: a hard version gate would decline honest fills (version strings are
+  // spoofable and unparseable forks exist), and the wallet itself is the enforcement point. Reads only the
+  // sync `provider.version`; never an awaited getCapabilities() round-trip on the fill hot path. An
+  // unparseable version never warns (no false alarms).
+  _fillSpvAdvised = false;
+  adviseFillSpvCapability() {
+    if (this._fillSpvAdvised) return;
+    this._fillSpvAdvised = true;
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(this.provider?.version ?? ""));
+    if (!m) return;
+    const below = Number(m[1]) === 0 && (Number(m[2]) < 2 || Number(m[2]) === 2 && Number(m[3]) < 60);
+    if (below) console.warn(`[cairn-sdk] this Cairn Wallet (v${m[0]}) predates the on-device fill-SPV boundary (cairn-wallet 0.2.60+). The fill proceeds; suggest a wallet update for payment-grade offer verification.`);
+  }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
   async getPermissions() {
     if (typeof this.provider.getPermissions !== "function") return [];

package/dist/connect.d.cts

@@ -57,7 +57,8 @@ interface SealClaimParams {
  * so a dApp settling real value MUST merkle-prove the offer and derive the recipient from its on-chain author
  * before building `outputs`. Payment-grade offer verification is the wallet's on-device fill-SPV path (F13;
  * added in cairn-wallet 0.2.60, which binds the fill payment/rebate/fee legs to the merkle-proven offer; see
- * docs/SDK-GUIDE.md verifies-vs-trusts). An SPV pre-verify helper in this SDK is roadmapped.
+ * docs/SDK-GUIDE.md verifies-vs-trusts). The SDK's SPV pre-verify SHIPPED: call `preverifyOffer` or
+ * `cairn.verifyOfferForFill(offerId, servedOffer, { pay })` before building `outputs`.
  */
 interface FillParams {
     proposalId: string;
@@ -249,6 +250,8 @@ declare class WalletConnection {
      * 0.2.60+, which binds payment/rebate/fee to the merkle-proven offer) is the payment-grade check; see FillParams.
      */
     fillOffer(params: FillParams): Promise<TxResult>;
+    private _fillSpvAdvised;
+    private adviseFillSpvCapability;
     /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
     getPermissions(): Promise<WalletPermission[]>;
     /** Explicitly request permission to see the address (prompts, like connect). */

package/dist/connect.d.ts

@@ -57,7 +57,8 @@ interface SealClaimParams {
  * so a dApp settling real value MUST merkle-prove the offer and derive the recipient from its on-chain author
  * before building `outputs`. Payment-grade offer verification is the wallet's on-device fill-SPV path (F13;
  * added in cairn-wallet 0.2.60, which binds the fill payment/rebate/fee legs to the merkle-proven offer; see
- * docs/SDK-GUIDE.md verifies-vs-trusts). An SPV pre-verify helper in this SDK is roadmapped.
+ * docs/SDK-GUIDE.md verifies-vs-trusts). The SDK's SPV pre-verify SHIPPED: call `preverifyOffer` or
+ * `cairn.verifyOfferForFill(offerId, servedOffer, { pay })` before building `outputs`.
  */
 interface FillParams {
     proposalId: string;
@@ -249,6 +250,8 @@ declare class WalletConnection {
      * 0.2.60+, which binds payment/rebate/fee to the merkle-proven offer) is the payment-grade check; see FillParams.
      */
     fillOffer(params: FillParams): Promise<TxResult>;
+    private _fillSpvAdvised;
+    private adviseFillSpvCapability;
     /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
     getPermissions(): Promise<WalletPermission[]>;
     /** Explicitly request permission to see the address (prompts, like connect). */

package/dist/connect.js

@@ -5,8 +5,8 @@ import {
   discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-RKR3JMIA.js";
-import "./chunk-MREZG2HN.js";
+} from "./chunk-VGKXFRHY.js";
+import "./chunk-REHDMKBF.js";
 export {
   WalletConnection,
   connect,

package/dist/content.cjs

@@ -26,7 +26,7 @@ module.exports = __toCommonJS(content_exports);
 var import_csd_codec = require("@inversealtruism/csd-codec");
 
 // src/errors.ts
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.4.2";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */

package/dist/content.js

@@ -1,7 +1,7 @@
 import {
   ContentClient
-} from "./chunk-2L5QNDAE.js";
-import "./chunk-MREZG2HN.js";
+} from "./chunk-PZEQ4YHR.js";
+import "./chunk-REHDMKBF.js";
 export {
   ContentClient
 };

package/dist/controller.cjs

@@ -25,7 +25,7 @@ __export(controller_exports, {
 module.exports = __toCommonJS(controller_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.4.0";
+var SDK_VERSION = "0.4.2";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -212,12 +212,15 @@ var WalletConnection = class {
   // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
   call(op, label) {
     const ms = this._timeoutMs;
-    if (!Number.isFinite(ms) || ms <= 0) return Promise.resolve(op());
+    const invoke = () => new Promise((resolve) => {
+      resolve(op());
+    });
+    if (!Number.isFinite(ms) || ms <= 0) return invoke();
     let timer;
     const timeout = new Promise((_, reject) => {
       timer = setTimeout(() => reject(new CairnError(`the wallet did not respond to ${label} within ${ms}ms`, { retryable: false })), ms);
     });
-    return Promise.race([Promise.resolve(op()), timeout]).finally(() => clearTimeout(timer));
+    return Promise.race([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
   /** The wallet's version string (e.g. "0.2.x"). */
   get version() {
@@ -290,8 +293,24 @@ var WalletConnection = class {
     if (typeof this.provider.fillOffer !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet predates fillOffer() \u2014 ask the user to update the Cairn Wallet"));
     }
+    this.adviseFillSpvCapability();
     return this.call(() => this.provider.fillOffer(params), "fillOffer").then(unwrapWrite);
   }
+  // P75-5 MF-10: ONE capability advisory per connection. The wallet's on-device fill-SPV (0.2.60+) is the
+  // payment-grade fill boundary; when the provider SELF-REPORTS an older version, warn the integrator once
+  // and STILL RELAY. WARN, NEVER BLOCK: a hard version gate would decline honest fills (version strings are
+  // spoofable and unparseable forks exist), and the wallet itself is the enforcement point. Reads only the
+  // sync `provider.version`; never an awaited getCapabilities() round-trip on the fill hot path. An
+  // unparseable version never warns (no false alarms).
+  _fillSpvAdvised = false;
+  adviseFillSpvCapability() {
+    if (this._fillSpvAdvised) return;
+    this._fillSpvAdvised = true;
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(this.provider?.version ?? ""));
+    if (!m) return;
+    const below = Number(m[1]) === 0 && (Number(m[2]) < 2 || Number(m[2]) === 2 && Number(m[3]) < 60);
+    if (below) console.warn(`[cairn-sdk] this Cairn Wallet (v${m[0]}) predates the on-device fill-SPV boundary (cairn-wallet 0.2.60+). The fill proceeds; suggest a wallet update for payment-grade offer verification.`);
+  }
   /** This origin's current permission grant (EIP-2255-style). Silent; [] if none / unsupported. */
   async getPermissions() {
     if (typeof this.provider.getPermissions !== "function") return [];
@@ -354,6 +373,9 @@ var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error:
 var CairnController = class {
   state = DISCONNECTED;
   conn = null;
+  // MF-15: connect/disconnect generation token. disconnect() bumps it; a connect() whose await straddled
+  // the bump must never commit "connected" over the torn-down session (a zombie null-connection session).
+  epoch = 0;
   listeners = /* @__PURE__ */ new Set();
   getWalletFn;
   detectOpts;
@@ -406,34 +428,43 @@ var CairnController = class {
   }
   /** Detect + connect (prompts the user the first time per origin). Resolves the connected address. */
   connect = async () => {
+    const epoch = this.epoch;
     this.setState({ status: "connecting", error: null });
     try {
-      if (!this.conn) {
-        this.conn = await this.getWalletFn(this.detectOpts);
-        this.conn.on("accountsChanged", this.onAccounts);
-        this.conn.on("disconnect", this.onDisconnect);
+      let conn = this.conn;
+      if (!conn) {
+        conn = await this.getWalletFn(this.detectOpts);
+        if (epoch !== this.epoch) throw new Error("connection was torn down while connecting - call connect() again");
+        conn.on("accountsChanged", this.onAccounts);
+        conn.on("disconnect", this.onDisconnect);
+        this.conn = conn;
       }
-      const addr = await this.conn.connect();
+      const addr = await conn.connect();
+      if (epoch !== this.epoch) throw new Error("connection was torn down while awaiting approval - call connect() again");
       this.setState({ status: "connected", account: addr, error: null });
       return addr;
     } catch (e) {
-      this.setState({ status: "disconnected", account: null, error: e?.message ?? String(e) });
+      if (epoch === this.epoch) this.setState({ status: "disconnected", account: null, error: e?.message ?? String(e) });
       throw e;
     }
   };
-  /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort). */
+  /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort).
+   *  Local teardown is IMMEDIATE and unconditional; the wallet-side revoke happens after, so a hung
+   *  provider can never hold a torn-down session in "connected". */
   disconnect = async () => {
-    try {
-      await this.conn?.revokePermissions();
-    } catch {
-    }
+    this.epoch++;
+    const conn = this.conn;
     this.detach();
     this.conn = null;
     this.setState({ status: "disconnected", account: null, error: null });
+    try {
+      await conn?.revokePermissions();
+    } catch {
+    }
   };
   /** Audience-bound sign-in (must connect() first). Returns the signed artifact to verify server-side. */
   signInWithCsd = (params) => {
-    if (!this.conn) return Promise.reject(new Error("call connect() before signInWithCsd()"));
+    if (!this.conn || this.state.status !== "connected") return Promise.reject(new Error("call connect() before signInWithCsd()"));
     return this.conn.signInWithCsd(params);
   };
 };

package/dist/controller.d.cts

@@ -12,6 +12,7 @@ interface CairnControllerOptions extends DetectOptions {
 declare class CairnController {
     private state;
     private conn;
+    private epoch;
     private readonly listeners;
     private readonly getWalletFn;
     private readonly detectOpts;
@@ -28,7 +29,9 @@ declare class CairnController {
     private detach;
     /** Detect + connect (prompts the user the first time per origin). Resolves the connected address. */
     connect: () => Promise<string>;
-    /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort). */
+    /** Forget the connection locally AND revoke this origin's wallet-side permission (best-effort).
+     *  Local teardown is IMMEDIATE and unconditional; the wallet-side revoke happens after, so a hung
+     *  provider can never hold a torn-down session in "connected". */
     disconnect: () => Promise<void>;
     /** Audience-bound sign-in (must connect() first). Returns the signed artifact to verify server-side. */
     signInWithCsd: (params: SiwcParams) => Promise<SiwcResult>;