@inversealtruism/cairn-sdk 0.1.2 → 0.1.3

package/dist/chunk-ZAE2BIH5.js

@@ -0,0 +1,78 @@
+import {
+  getWallet
+} from "./chunk-G4OZKZSJ.js";
+
+// src/controller.ts
+var DISCONNECTED = Object.freeze({ status: "disconnected", account: null, error: null });
+var CairnController = class {
+  state = DISCONNECTED;
+  conn = null;
+  listeners = /* @__PURE__ */ new Set();
+  getWalletFn;
+  detectOpts;
+  constructor(opts = {}) {
+    const { getWallet: gw, ...detect } = opts;
+    this.getWalletFn = gw ?? getWallet;
+    this.detectOpts = detect;
+  }
+  /** useSyncExternalStore-compatible. Returns an unsubscribe fn. */
+  subscribe = (cb) => {
+    this.listeners.add(cb);
+    return () => {
+      this.listeners.delete(cb);
+    };
+  };
+  /** useSyncExternalStore-compatible snapshot — stable reference until the state actually changes. */
+  getSnapshot = () => this.state;
+  /** The underlying WalletConnection (for advanced use: send/propose/permissions/…). Null until connect(). */
+  get connection() {
+    return this.conn;
+  }
+  setState(patch) {
+    const next = { ...this.state, ...patch };
+    if (next.status === this.state.status && next.account === this.state.account && next.error === this.state.error) return;
+    this.state = Object.freeze(next);
+    for (const l of [...this.listeners]) l();
+  }
+  onAccounts = (accounts) => {
+    if (!Array.isArray(accounts) || accounts.length === 0) this.setState({ status: "disconnected", account: null });
+    else this.setState({ status: "connected", account: String(accounts[0]), error: null });
+  };
+  onDisconnect = () => {
+    this.setState({ status: "disconnected", account: null });
+  };
+  /** Detect + connect (prompts the user the first time per origin). Resolves the connected address. */
+  connect = async () => {
+    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);
+      }
+      const addr = await this.conn.connect();
+      this.setState({ status: "connected", account: addr, error: null });
+      return addr;
+    } catch (e) {
+      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). */
+  disconnect = async () => {
+    try {
+      await this.conn?.revokePermissions();
+    } catch {
+    }
+    this.setState({ status: "disconnected", account: null, error: null });
+  };
+  /** 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()"));
+    return this.conn.signInWithCsd(params);
+  };
+};
+
+export {
+  CairnController
+};

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.2";
+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
 });

package/dist/connect.d.cts

@@ -49,18 +49,94 @@ interface SealClaimParams {
     claim: string;
     fee?: number;
 }
+/** Atomic fill (CairnX delivery-vs-payment): an Attest + payment outputs in ONE tx. */
+interface FillParams {
+    proposalId: string;
+    outputs: {
+        to: string;
+        value: number;
+    }[];
+    score?: number;
+    confidence?: number;
+    fee?: number;
+}
+/**
+ * Audience-bound "Sign in with CSD" (SIWC) params — the secure third-party login. The wallet binds
+ * the REAL requesting origin as the message `domain` (from the unforgeable sender.origin, NEVER this
+ * field) plus your server `nonce`, chain id, and a validity window, and returns only the signed
+ * artifact. The relying party MUST verify it server-side (see below).
+ */
+interface SiwcParams {
+    /** Server-issued, single-use, >=8 alphanumeric (use `generateNonce()` from @inversealtruism/csd-siwc). */
+    nonce: string;
+    /** Optional one-line human statement shown in the wallet (no newline). */
+    statement?: string;
+    /** Subject URI; defaults to the origin root. If given, MUST be on the requesting site. */
+    uri?: string;
+    /** Validity window in seconds (wallet clamps 60..3600, default 600). */
+    expirationSecs?: number;
+    notBeforeSecs?: number;
+    requestId?: string;
+    resources?: string[];
+    /** Optional cross-check only — if set it MUST equal the requesting origin's host, else refused. */
+    domain?: string;
+}
+/**
+ * SIWC result — the signed artifact. VERIFY SERVER-SIDE with `verifySiwc` from
+ * `@inversealtruism/csd-siwc` (check domain==your-origin, nonce==your-issued-single-use-nonce,
+ * chainId, time window, signature, hash160(pub33)==account), THEN issue your OWN session. The
+ * signature is proof-of-control, NEVER a bearer token.
+ */
+interface SiwcResult {
+    account: string;
+    pub33: string;
+    sig64: string;
+    /** The exact canonical SIWC message that was signed (verify the signature over this). */
+    message: string;
+    /** CAIP-2 chain id the sign-in is bound to. */
+    chainId: string;
+}
+/** Wallet feature/capability descriptor (feature-detection; older wallets may not expose it). */
+interface WalletCapabilities {
+    version: string;
+    /** SIWC byte-contract version, e.g. "1", when audience-bound sign-in is supported. */
+    siwc?: string;
+    methods?: string[];
+    [k: string]: unknown;
+}
+/** An EIP-2255-style per-origin permission grant. */
+interface WalletPermission {
+    invoker: string;
+    accounts: string[];
+    grantedAt: number;
+}
 /** The raw provider object the extension injects at `window.cairn`. */
 interface CairnProvider {
     isCairn: true;
     version: string;
     connect(): Promise<ProviderReply<ConnectResult>>;
     getAddress(): Promise<ProviderReply<ConnectResult>>;
+    /** @deprecated First-party-only legacy login. Third parties MUST use `signInWithCsd`. */
     signIn(): Promise<ProviderReply<SignInResult>>;
+    /** Audience-bound "Sign in with CSD" — the secure third-party login. */
+    signInWithCsd(p: SiwcParams): Promise<ProviderReply<SiwcResult>>;
     propose(p: ProposeParams): Promise<ProviderReply<TxResult>>;
     attest(p: AttestParams): Promise<ProviderReply<TxResult>>;
     send(p: SendParams): Promise<ProviderReply<TxResult>>;
+    fillOffer(p: FillParams): Promise<ProviderReply<TxResult>>;
     sealClaim(p: SealClaimParams): Promise<ProviderReply<TxResult>>;
     revealClaim(txid: string): Promise<ProviderReply<TxResult>>;
+    /** Feature/capability detection (optional; absent on older wallets). */
+    getCapabilities?(): Promise<WalletCapabilities>;
+    /** EIP-2255-style per-origin permissions (optional; absent on older wallets). */
+    getPermissions?(): Promise<ProviderReply<WalletPermission[]>>;
+    requestPermissions?(): Promise<ProviderReply<WalletPermission[]>>;
+    revokePermissions?(): Promise<ProviderReply<{
+        revoked: boolean;
+    }>>;
+    /** Event subscription (accountsChanged / disconnect) (optional; absent on older wallets). */
+    on?(event: string, handler: (data: unknown) => void): void;
+    removeListener?(event: string, handler: (data: unknown) => void): void;
 }
 /** Every provider call resolves to this discriminated reply (never rejects). */
 type ProviderReply<T> = {
@@ -84,6 +160,28 @@ interface DetectOptions {
  * content script hasn't injected yet. Throws `NotInstalledError` on timeout or
  * outside a browser.
  */
+/** EIP-6963-style announced wallet info (Cairn's own `csd:` discovery namespace). */
+interface ProviderInfo {
+    uuid: string;
+    name: string;
+    icon: string;
+    rdns: string;
+}
+/** A discovered provider + its display info. */
+interface ProviderDetail {
+    info: ProviderInfo;
+    provider: CairnProvider;
+}
+/**
+ * Enumerate all wallets that announce via the `csd:` discovery handshake (EIP-6963 analog) — for a
+ * multi-wallet picker. Resolves with everything announced within `timeoutMs` (default 1000ms).
+ */
+declare function discoverProviders(opts?: DetectOptions): Promise<ProviderDetail[]>;
+/**
+ * Resolve `window.cairn`, via three paths that race: an immediate global, the legacy
+ * `cairn#initialized` event, or the `csd:announceProvider` discovery handshake (we dispatch
+ * `csd:requestProvider`). Throws `NotInstalledError` on timeout or outside a browser.
+ */
 declare function detectProvider(opts?: DetectOptions): Promise<CairnProvider>;
 /** True if the Cairn Wallet is already present (no waiting). */
 declare function isInstalled(): boolean;
@@ -103,8 +201,42 @@ declare class WalletConnection {
     connect(): Promise<string>;
     /** Get the connected address (does not force a new connection prompt if already consented). */
     getAddress(): Promise<string>;
-    /** 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(): Promise<SignInResult>;
+    /**
+     * 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: SiwcParams): Promise<SiwcResult>;
+    /** True if this wallet supports audience-bound SIWC (safe to call `signInWithCsd`). */
+    get supportsSiwc(): boolean;
+    /** Feature/capability detection. Returns null if the wallet predates `getCapabilities`. */
+    getCapabilities(): Promise<WalletCapabilities | null>;
+    /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
+    fillOffer(params: FillParams): Promise<TxResult>;
+    /** 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). */
+    requestPermissions(): Promise<WalletPermission[]>;
+    /** Revoke THIS origin's own access (silent). Returns { revoked }. Safe no-op on older wallets. */
+    revokePermissions(): Promise<{
+        revoked: boolean;
+    }>;
+    /**
+     * 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: "accountsChanged" | "disconnect" | (string & {}), handler: (data: any) => void): void;
+    /** Remove a previously-added event handler (must be the same reference passed to on()). */
+    off(event: string, handler: (data: any) => void): void;
     /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
     send(params: SendParams): Promise<TxResult>;
     /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
@@ -124,4 +256,4 @@ declare function connect(opts?: DetectOptions): Promise<{
     address: string;
 }>;
 
-export { type AttestParams, type CairnProvider, type ConnectResult, type DetectOptions, type ProposeParams, type ProviderReply, type SealClaimParams, type SendParams, type SignInResult, type TxResult, WalletConnection, connect, detectProvider, getWallet, isInstalled };
+export { type AttestParams, type CairnProvider, type ConnectResult, type DetectOptions, type FillParams, type ProposeParams, type ProviderDetail, type ProviderInfo, type ProviderReply, type SealClaimParams, type SendParams, type SignInResult, type SiwcParams, type SiwcResult, type TxResult, type WalletCapabilities, WalletConnection, type WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled };

package/dist/connect.d.ts

@@ -49,18 +49,94 @@ interface SealClaimParams {
     claim: string;
     fee?: number;
 }
+/** Atomic fill (CairnX delivery-vs-payment): an Attest + payment outputs in ONE tx. */
+interface FillParams {
+    proposalId: string;
+    outputs: {
+        to: string;
+        value: number;
+    }[];
+    score?: number;
+    confidence?: number;
+    fee?: number;
+}
+/**
+ * Audience-bound "Sign in with CSD" (SIWC) params — the secure third-party login. The wallet binds
+ * the REAL requesting origin as the message `domain` (from the unforgeable sender.origin, NEVER this
+ * field) plus your server `nonce`, chain id, and a validity window, and returns only the signed
+ * artifact. The relying party MUST verify it server-side (see below).
+ */
+interface SiwcParams {
+    /** Server-issued, single-use, >=8 alphanumeric (use `generateNonce()` from @inversealtruism/csd-siwc). */
+    nonce: string;
+    /** Optional one-line human statement shown in the wallet (no newline). */
+    statement?: string;
+    /** Subject URI; defaults to the origin root. If given, MUST be on the requesting site. */
+    uri?: string;
+    /** Validity window in seconds (wallet clamps 60..3600, default 600). */
+    expirationSecs?: number;
+    notBeforeSecs?: number;
+    requestId?: string;
+    resources?: string[];
+    /** Optional cross-check only — if set it MUST equal the requesting origin's host, else refused. */
+    domain?: string;
+}
+/**
+ * SIWC result — the signed artifact. VERIFY SERVER-SIDE with `verifySiwc` from
+ * `@inversealtruism/csd-siwc` (check domain==your-origin, nonce==your-issued-single-use-nonce,
+ * chainId, time window, signature, hash160(pub33)==account), THEN issue your OWN session. The
+ * signature is proof-of-control, NEVER a bearer token.
+ */
+interface SiwcResult {
+    account: string;
+    pub33: string;
+    sig64: string;
+    /** The exact canonical SIWC message that was signed (verify the signature over this). */
+    message: string;
+    /** CAIP-2 chain id the sign-in is bound to. */
+    chainId: string;
+}
+/** Wallet feature/capability descriptor (feature-detection; older wallets may not expose it). */
+interface WalletCapabilities {
+    version: string;
+    /** SIWC byte-contract version, e.g. "1", when audience-bound sign-in is supported. */
+    siwc?: string;
+    methods?: string[];
+    [k: string]: unknown;
+}
+/** An EIP-2255-style per-origin permission grant. */
+interface WalletPermission {
+    invoker: string;
+    accounts: string[];
+    grantedAt: number;
+}
 /** The raw provider object the extension injects at `window.cairn`. */
 interface CairnProvider {
     isCairn: true;
     version: string;
     connect(): Promise<ProviderReply<ConnectResult>>;
     getAddress(): Promise<ProviderReply<ConnectResult>>;
+    /** @deprecated First-party-only legacy login. Third parties MUST use `signInWithCsd`. */
     signIn(): Promise<ProviderReply<SignInResult>>;
+    /** Audience-bound "Sign in with CSD" — the secure third-party login. */
+    signInWithCsd(p: SiwcParams): Promise<ProviderReply<SiwcResult>>;
     propose(p: ProposeParams): Promise<ProviderReply<TxResult>>;
     attest(p: AttestParams): Promise<ProviderReply<TxResult>>;
     send(p: SendParams): Promise<ProviderReply<TxResult>>;
+    fillOffer(p: FillParams): Promise<ProviderReply<TxResult>>;
     sealClaim(p: SealClaimParams): Promise<ProviderReply<TxResult>>;
     revealClaim(txid: string): Promise<ProviderReply<TxResult>>;
+    /** Feature/capability detection (optional; absent on older wallets). */
+    getCapabilities?(): Promise<WalletCapabilities>;
+    /** EIP-2255-style per-origin permissions (optional; absent on older wallets). */
+    getPermissions?(): Promise<ProviderReply<WalletPermission[]>>;
+    requestPermissions?(): Promise<ProviderReply<WalletPermission[]>>;
+    revokePermissions?(): Promise<ProviderReply<{
+        revoked: boolean;
+    }>>;
+    /** Event subscription (accountsChanged / disconnect) (optional; absent on older wallets). */
+    on?(event: string, handler: (data: unknown) => void): void;
+    removeListener?(event: string, handler: (data: unknown) => void): void;
 }
 /** Every provider call resolves to this discriminated reply (never rejects). */
 type ProviderReply<T> = {
@@ -84,6 +160,28 @@ interface DetectOptions {
  * content script hasn't injected yet. Throws `NotInstalledError` on timeout or
  * outside a browser.
  */
+/** EIP-6963-style announced wallet info (Cairn's own `csd:` discovery namespace). */
+interface ProviderInfo {
+    uuid: string;
+    name: string;
+    icon: string;
+    rdns: string;
+}
+/** A discovered provider + its display info. */
+interface ProviderDetail {
+    info: ProviderInfo;
+    provider: CairnProvider;
+}
+/**
+ * Enumerate all wallets that announce via the `csd:` discovery handshake (EIP-6963 analog) — for a
+ * multi-wallet picker. Resolves with everything announced within `timeoutMs` (default 1000ms).
+ */
+declare function discoverProviders(opts?: DetectOptions): Promise<ProviderDetail[]>;
+/**
+ * Resolve `window.cairn`, via three paths that race: an immediate global, the legacy
+ * `cairn#initialized` event, or the `csd:announceProvider` discovery handshake (we dispatch
+ * `csd:requestProvider`). Throws `NotInstalledError` on timeout or outside a browser.
+ */
 declare function detectProvider(opts?: DetectOptions): Promise<CairnProvider>;
 /** True if the Cairn Wallet is already present (no waiting). */
 declare function isInstalled(): boolean;
@@ -103,8 +201,42 @@ declare class WalletConnection {
     connect(): Promise<string>;
     /** Get the connected address (does not force a new connection prompt if already consented). */
     getAddress(): Promise<string>;
-    /** 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(): Promise<SignInResult>;
+    /**
+     * 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: SiwcParams): Promise<SiwcResult>;
+    /** True if this wallet supports audience-bound SIWC (safe to call `signInWithCsd`). */
+    get supportsSiwc(): boolean;
+    /** Feature/capability detection. Returns null if the wallet predates `getCapabilities`. */
+    getCapabilities(): Promise<WalletCapabilities | null>;
+    /** Atomic fill (CairnX DvP): pay + attest in ONE tx. Always prompts with clear-signing. */
+    fillOffer(params: FillParams): Promise<TxResult>;
+    /** 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). */
+    requestPermissions(): Promise<WalletPermission[]>;
+    /** Revoke THIS origin's own access (silent). Returns { revoked }. Safe no-op on older wallets. */
+    revokePermissions(): Promise<{
+        revoked: boolean;
+    }>;
+    /**
+     * 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: "accountsChanged" | "disconnect" | (string & {}), handler: (data: any) => void): void;
+    /** Remove a previously-added event handler (must be the same reference passed to on()). */
+    off(event: string, handler: (data: any) => void): void;
     /** Send CSD (always prompts with clear-signing; wallet picks inputs + returns change to itself). */
     send(params: SendParams): Promise<TxResult>;
     /** Low-level Propose (always prompts). Prefer `cairn.board.propose()` which computes the hash/uri/expiry. */
@@ -124,4 +256,4 @@ declare function connect(opts?: DetectOptions): Promise<{
     address: string;
 }>;
 
-export { type AttestParams, type CairnProvider, type ConnectResult, type DetectOptions, type ProposeParams, type ProviderReply, type SealClaimParams, type SendParams, type SignInResult, type TxResult, WalletConnection, connect, detectProvider, getWallet, isInstalled };
+export { type AttestParams, type CairnProvider, type ConnectResult, type DetectOptions, type FillParams, type ProposeParams, type ProviderDetail, type ProviderInfo, type ProviderReply, type SealClaimParams, type SendParams, type SignInResult, type SiwcParams, type SiwcResult, type TxResult, type WalletCapabilities, WalletConnection, type WalletPermission, connect, detectProvider, discoverProviders, getWallet, isInstalled };