@inversealtruism/cairn-sdk 0.1.2 → 0.1.4

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,12 +160,40 @@ 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;
 /**
  * High-level, typed wallet handle. Construct via `connect()` or `new WalletConnection(provider)`.
  * Methods throw `UserRejectedError` / `WalletLockedError` / `UnsupportedMethodError` on failure.
+ *
+ * Note (typed-error contract): the genuine Cairn Wallet always RESOLVES a `{ok,result|error}` reply, so a
+ * failure is mapped to a typed `CairnError` via `unwrap`. A non-conformant or SPOOFED provider that instead
+ * REJECTS its promise will surface that raw rejection un-mapped (it bypasses `unwrap`), so a dApp's
+ * `catch (e) { errorCode(e) }` may see `UNKNOWN` from such a provider. The real auth boundary is server-side
+ * SIWC verification, never a client-side error code.
  */
 declare class WalletConnection {
     readonly provider: CairnProvider;
@@ -103,8 +207,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 +262,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,12 +160,40 @@ 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;
 /**
  * High-level, typed wallet handle. Construct via `connect()` or `new WalletConnection(provider)`.
  * Methods throw `UserRejectedError` / `WalletLockedError` / `UnsupportedMethodError` on failure.
+ *
+ * Note (typed-error contract): the genuine Cairn Wallet always RESOLVES a `{ok,result|error}` reply, so a
+ * failure is mapped to a typed `CairnError` via `unwrap`. A non-conformant or SPOOFED provider that instead
+ * REJECTS its promise will surface that raw rejection un-mapped (it bypasses `unwrap`), so a dApp's
+ * `catch (e) { errorCode(e) }` may see `UNKNOWN` from such a provider. The real auth boundary is server-side
+ * SIWC verification, never a client-side error code.
  */
 declare class WalletConnection {
     readonly provider: CairnProvider;
@@ -103,8 +207,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 +262,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.js

@@ -2,14 +2,16 @@ import {
   WalletConnection,
   connect,
   detectProvider,
+  discoverProviders,
   getWallet,
   isInstalled
-} from "./chunk-SMAPCKVG.js";
-import "./chunk-PHMU3CG5.js";
+} from "./chunk-K7SJOW3O.js";
+import "./chunk-RELP23CH.js";
 export {
   WalletConnection,
   connect,
   detectProvider,
+  discoverProviders,
   getWallet,
   isInstalled
 };

package/dist/content.cjs

@@ -26,16 +26,47 @@ module.exports = __toCommonJS(content_exports);
 var import_csd_codec = require("@inversealtruism/csd-codec");
 
 // 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 ContentVerificationError = class extends CairnError {
   expected;
   constructor(expected) {
-    super(`Content does not match its payload hash ${expected} \u2014 bytes were tampered with in transit.`);
+    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;
   }
 };
@@ -104,8 +135,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;
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/content.d.cts

@@ -1,4 +1,4 @@
-import { H as Http } from './http-D2CzfOsm.cjs';
+import { H as Http } from './http-CQsNL8w9.cjs';
 
 interface ContentClientOptions {
     /** Swarm gateway HTTP client (e.g. https://cairn-substrate.com/swarm). */

package/dist/content.d.ts

@@ -1,4 +1,4 @@
-import { H as Http } from './http-D2CzfOsm.js';
+import { H as Http } from './http-CQsNL8w9.js';
 
 interface ContentClientOptions {
     /** Swarm gateway HTTP client (e.g. https://cairn-substrate.com/swarm). */

package/dist/content.js

@@ -1,7 +1,7 @@
 import {
   ContentClient
-} from "./chunk-BZVJVL4Q.js";
-import "./chunk-PHMU3CG5.js";
+} from "./chunk-MVX7VQT4.js";
+import "./chunk-RELP23CH.js";
 export {
   ContentClient
 };