@inversealtruism/cairn-sdk 0.3.2 → 0.4.1

package/dist/connect.cjs

@@ -30,7 +30,7 @@ __export(connect_exports, {
 module.exports = __toCommonJS(connect_exports);
 
 // src/errors.ts
-var SDK_VERSION = "0.3.2";
+var SDK_VERSION = "0.4.1";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -104,7 +104,7 @@ var SubmitInFlightError = class extends CairnError {
     this.txid = txid;
   }
 };
-var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+var NATIVE_CODES = /* @__PURE__ */ new Set(["FIRST_PARTY_ONLY", "RATE_LIMITED", "FORBIDDEN", "INTERNAL"]);
 var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN"]);
 var NESTED_TERMINAL = /* @__PURE__ */ new Set([
   "FILL_UNSAFE",
@@ -148,6 +148,7 @@ function mapSubmitResultError(result) {
 }
 
 // src/connect.ts
+var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;
 function discoverProviders(opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 1e3;
   return new Promise((resolve) => {
@@ -227,8 +228,27 @@ function unwrapWrite(reply) {
 var WalletConnection = class {
   provider;
   _addr = null;
-  constructor(provider) {
+  /** B7c: per-call provider timeout (ms). GENEROUS by default so it never rejects an in-flight human
+   *  approval; 0 disables it. Every provider call (writes especially) races against it. */
+  _timeoutMs;
+  constructor(provider, opts = {}) {
     this.provider = provider;
+    this._timeoutMs = opts.timeoutMs ?? DEFAULT_PROVIDER_TIMEOUT_MS;
+  }
+  // B7c: race a provider call against the per-call timeout. On timeout, throw a fail-closed CairnError
+  // (retryable:false: a write may already have reached the wallet, so never invite a blind auto-retry). The
+  // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
+  call(op, label) {
+    const ms = this._timeoutMs;
+    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([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
   /** The wallet's version string (e.g. "0.2.x"). */
   get version() {
@@ -240,13 +260,13 @@ var WalletConnection = class {
   }
   /** Request connection. First time per origin prompts the user; afterwards may be silent. */
   async connect() {
-    const { addr } = unwrap(await this.provider.connect());
+    const { addr } = unwrap(await this.call(() => this.provider.connect(), "connect"));
     this._addr = addr;
     return addr;
   }
   /** Get the connected address (does not force a new connection prompt if already consented). */
   async getAddress() {
-    const { addr } = unwrap(await this.provider.getAddress());
+    const { addr } = unwrap(await this.call(() => this.provider.getAddress(), "getAddress"));
     this._addr = addr;
     return addr;
   }
@@ -259,7 +279,7 @@ var WalletConnection = class {
     if (typeof this.provider.signIn !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet does not expose signIn()"));
     }
-    return Promise.resolve(this.provider.signIn()).then(unwrap);
+    return this.call(() => this.provider.signIn(), "signIn").then(unwrap);
   }
   /**
    * Audience-bound "Sign in with CSD" (SIWC) — the secure, replay-resistant third-party login.
@@ -275,7 +295,7 @@ var WalletConnection = class {
     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);
+    return this.call(() => this.provider.signInWithCsd(params), "signInWithCsd").then(unwrap);
   }
   /** True if this wallet supports audience-bound SIWC (safe to call `signInWithCsd`). */
   get supportsSiwc() {
@@ -285,7 +305,7 @@ var WalletConnection = class {
   async getCapabilities() {
     if (typeof this.provider.getCapabilities !== "function") return null;
     try {
-      return await this.provider.getCapabilities();
+      return await this.call(() => this.provider.getCapabilities(), "getCapabilities");
     } catch {
       return null;
     }
@@ -301,24 +321,40 @@ 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"));
     }
-    return Promise.resolve(this.provider.fillOffer(params)).then(unwrapWrite);
+    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 [];
-    return unwrap(await this.provider.getPermissions());
+    return unwrap(await this.call(() => this.provider.getPermissions(), "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);
+    return this.call(() => this.provider.requestPermissions(), "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());
+    return unwrap(await this.call(() => this.provider.revokePermissions(), "revokePermissions"));
   }
   /**
    * Subscribe to provider events. `accountsChanged` fires with `[]` when this site loses access
@@ -334,26 +370,26 @@ var WalletConnection = class {
   }
   /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
   send(params) {
-    return Promise.resolve(this.provider.send(params)).then(unwrapWrite);
+    return this.call(() => this.provider.send(params), "send").then(unwrapWrite);
   }
   /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
   propose(params) {
-    return Promise.resolve(this.provider.propose(params)).then(unwrapWrite);
+    return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
   }
   /** Attest/support a proposal (always prompts). */
   attest(params) {
-    return Promise.resolve(this.provider.attest(params)).then(unwrapWrite);
+    return this.call(() => this.provider.attest(params), "attest").then(unwrapWrite);
   }
   /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
   sealClaim(params) {
-    return Promise.resolve(this.provider.sealClaim(params)).then(unwrapWrite);
+    return this.call(() => this.provider.sealClaim(params), "sealClaim").then(unwrapWrite);
   }
   /** Reveal a previously sealed claim by its sealing txid (always prompts). */
   revealClaim(txid) {
     if (typeof txid !== "string" || !txid) {
       return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
     }
-    return Promise.resolve(this.provider.revealClaim(txid)).then(unwrapWrite);
+    return this.call(() => this.provider.revealClaim(txid), "revealClaim").then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {

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;
@@ -208,7 +209,13 @@ declare function isInstalled(): boolean;
 declare class WalletConnection {
     readonly provider: CairnProvider;
     private _addr;
-    constructor(provider: CairnProvider);
+    /** B7c: per-call provider timeout (ms). GENEROUS by default so it never rejects an in-flight human
+     *  approval; 0 disables it. Every provider call (writes especially) races against it. */
+    private readonly _timeoutMs;
+    constructor(provider: CairnProvider, opts?: {
+        timeoutMs?: number;
+    });
+    private call;
     /** The wallet's version string (e.g. "0.2.x"). */
     get version(): string;
     /** The connected address, if `connect()`/`getAddress()` has resolved. */
@@ -243,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;
@@ -208,7 +209,13 @@ declare function isInstalled(): boolean;
 declare class WalletConnection {
     readonly provider: CairnProvider;
     private _addr;
-    constructor(provider: CairnProvider);
+    /** B7c: per-call provider timeout (ms). GENEROUS by default so it never rejects an in-flight human
+     *  approval; 0 disables it. Every provider call (writes especially) races against it. */
+    private readonly _timeoutMs;
+    constructor(provider: CairnProvider, opts?: {
+        timeoutMs?: number;
+    });
+    private call;
     /** The wallet's version string (e.g. "0.2.x"). */
     get version(): string;
     /** The connected address, if `connect()`/`getAddress()` has resolved. */
@@ -243,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-BN3PFJDY.js";
-import "./chunk-FMXNJQWL.js";
+} from "./chunk-PIPN6FSA.js";
+import "./chunk-ERBT4DFD.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.3.2";
+var SDK_VERSION = "0.4.1";
 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-JKC5K253.js";
-import "./chunk-FMXNJQWL.js";
+} from "./chunk-OCEHXK6A.js";
+import "./chunk-ERBT4DFD.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.3.2";
+var SDK_VERSION = "0.4.1";
 var DOCS_BASE = "https://cairn-substrate.com/docs/sdk";
 var CairnError = class extends Error {
   /** Stable machine code for programmatic branching. */
@@ -99,7 +99,7 @@ var SubmitInFlightError = class extends CairnError {
     this.txid = txid;
   }
 };
-var NATIVE_CODES = /* @__PURE__ */ new Set(["ACCOUNT_CHANGED", "FIRST_PARTY_ONLY", "RATE_LIMITED", "APPROVAL_CLOSED", "FORBIDDEN", "INTERNAL"]);
+var NATIVE_CODES = /* @__PURE__ */ new Set(["FIRST_PARTY_ONLY", "RATE_LIMITED", "FORBIDDEN", "INTERNAL"]);
 var NESTED_TRANSIENT = /* @__PURE__ */ new Set(["VERIFY_UNAVAILABLE", "OFFER_UNKNOWN"]);
 var NESTED_TERMINAL = /* @__PURE__ */ new Set([
   "FILL_UNSAFE",
@@ -143,6 +143,7 @@ function mapSubmitResultError(result) {
 }
 
 // src/connect.ts
+var DEFAULT_PROVIDER_TIMEOUT_MS = 10 * 6e4;
 function detectProvider(opts = {}) {
   const timeoutMs = opts.timeoutMs ?? 3e3;
   return new Promise((resolve, reject) => {
@@ -199,8 +200,27 @@ function unwrapWrite(reply) {
 var WalletConnection = class {
   provider;
   _addr = null;
-  constructor(provider) {
+  /** B7c: per-call provider timeout (ms). GENEROUS by default so it never rejects an in-flight human
+   *  approval; 0 disables it. Every provider call (writes especially) races against it. */
+  _timeoutMs;
+  constructor(provider, opts = {}) {
     this.provider = provider;
+    this._timeoutMs = opts.timeoutMs ?? DEFAULT_PROVIDER_TIMEOUT_MS;
+  }
+  // B7c: race a provider call against the per-call timeout. On timeout, throw a fail-closed CairnError
+  // (retryable:false: a write may already have reached the wallet, so never invite a blind auto-retry). The
+  // genuine wallet resolves quickly once the user acts; this only fires on a truly hung/absent response.
+  call(op, label) {
+    const ms = this._timeoutMs;
+    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([invoke(), timeout]).finally(() => clearTimeout(timer));
   }
   /** The wallet's version string (e.g. "0.2.x"). */
   get version() {
@@ -212,13 +232,13 @@ var WalletConnection = class {
   }
   /** Request connection. First time per origin prompts the user; afterwards may be silent. */
   async connect() {
-    const { addr } = unwrap(await this.provider.connect());
+    const { addr } = unwrap(await this.call(() => this.provider.connect(), "connect"));
     this._addr = addr;
     return addr;
   }
   /** Get the connected address (does not force a new connection prompt if already consented). */
   async getAddress() {
-    const { addr } = unwrap(await this.provider.getAddress());
+    const { addr } = unwrap(await this.call(() => this.provider.getAddress(), "getAddress"));
     this._addr = addr;
     return addr;
   }
@@ -231,7 +251,7 @@ var WalletConnection = class {
     if (typeof this.provider.signIn !== "function") {
       return Promise.reject(new UnsupportedMethodError("this wallet does not expose signIn()"));
     }
-    return Promise.resolve(this.provider.signIn()).then(unwrap);
+    return this.call(() => this.provider.signIn(), "signIn").then(unwrap);
   }
   /**
    * Audience-bound "Sign in with CSD" (SIWC) — the secure, replay-resistant third-party login.
@@ -247,7 +267,7 @@ var WalletConnection = class {
     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);
+    return this.call(() => this.provider.signInWithCsd(params), "signInWithCsd").then(unwrap);
   }
   /** True if this wallet supports audience-bound SIWC (safe to call `signInWithCsd`). */
   get supportsSiwc() {
@@ -257,7 +277,7 @@ var WalletConnection = class {
   async getCapabilities() {
     if (typeof this.provider.getCapabilities !== "function") return null;
     try {
-      return await this.provider.getCapabilities();
+      return await this.call(() => this.provider.getCapabilities(), "getCapabilities");
     } catch {
       return null;
     }
@@ -273,24 +293,40 @@ 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"));
     }
-    return Promise.resolve(this.provider.fillOffer(params)).then(unwrapWrite);
+    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 [];
-    return unwrap(await this.provider.getPermissions());
+    return unwrap(await this.call(() => this.provider.getPermissions(), "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);
+    return this.call(() => this.provider.requestPermissions(), "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());
+    return unwrap(await this.call(() => this.provider.revokePermissions(), "revokePermissions"));
   }
   /**
    * Subscribe to provider events. `accountsChanged` fires with `[]` when this site loses access
@@ -306,26 +342,26 @@ var WalletConnection = class {
   }
   /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
   send(params) {
-    return Promise.resolve(this.provider.send(params)).then(unwrapWrite);
+    return this.call(() => this.provider.send(params), "send").then(unwrapWrite);
   }
   /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
   propose(params) {
-    return Promise.resolve(this.provider.propose(params)).then(unwrapWrite);
+    return this.call(() => this.provider.propose(params), "propose").then(unwrapWrite);
   }
   /** Attest/support a proposal (always prompts). */
   attest(params) {
-    return Promise.resolve(this.provider.attest(params)).then(unwrapWrite);
+    return this.call(() => this.provider.attest(params), "attest").then(unwrapWrite);
   }
   /** Seal a commit-reveal claim (always prompts; salt stays inside the wallet). */
   sealClaim(params) {
-    return Promise.resolve(this.provider.sealClaim(params)).then(unwrapWrite);
+    return this.call(() => this.provider.sealClaim(params), "sealClaim").then(unwrapWrite);
   }
   /** Reveal a previously sealed claim by its sealing txid (always prompts). */
   revealClaim(txid) {
     if (typeof txid !== "string" || !txid) {
       return Promise.reject(new UnsupportedMethodError("revealClaim requires the sealing txid"));
     }
-    return Promise.resolve(this.provider.revealClaim(txid)).then(unwrapWrite);
+    return this.call(() => this.provider.revealClaim(txid), "revealClaim").then(unwrapWrite);
   }
 };
 async function getWallet(opts = {}) {
@@ -337,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;
@@ -389,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>;

package/dist/controller.d.ts

@@ -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>;

package/dist/controller.js

@@ -1,8 +1,8 @@
 import {
   CairnController
-} from "./chunk-AGU6K5EZ.js";
-import "./chunk-BN3PFJDY.js";
-import "./chunk-FMXNJQWL.js";
+} from "./chunk-QATE6AIP.js";
+import "./chunk-PIPN6FSA.js";
+import "./chunk-ERBT4DFD.js";
 export {
   CairnController
 };