@coinbase/cdp-core 0.0.107 → 0.0.109

package/dist/web/index.web95.js

@@ -1,20 +1,45 @@
+import { getTransactionEncoder as m, getTransactionDecoder as u, address as p } from "@solana/kit";
+import { getCurrentUserSync as f } from "./index.web44.js";
 import "@coinbase/cdp-api-client";
+import "./index.web2.js";
+import "./index.web3.js";
+import "jose";
 import "viem";
-const u = async (c) => await c.isSignedIn();
-async function A(c, a, r) {
-  if (!await u(a))
-    throw new Error("User not signed in");
-  const t = a.getUser();
-  if ("evmAccount" in c && !(t.evmAccounts?.find((n) => n === c.evmAccount) || t.evmAccountObjects?.find((n) => n.address === c.evmAccount)))
-    throw new Error("EVM account not found");
-  if ("evmSmartAccount" in c && !(t.evmSmartAccounts?.find((n) => n === c.evmSmartAccount) || t.evmSmartAccountObjects?.find((n) => n.address === c.evmSmartAccount)))
-    throw new Error("EVM Smart Account not found");
-  if ("solanaAccount" in c && !(t.solanaAccounts?.find((n) => n === c.solanaAccount) || t.solanaAccountObjects?.find((n) => n.address === c.solanaAccount)))
-    throw new Error("Solana account not found");
-  const e = await a.getWalletSecretId();
-  return r({ ...c, user: t, walletSecretId: e });
+import "./index.web98.js";
+import "./index.web93.js";
+import { signSolanaTransaction as g } from "./index.web32.js";
+import "./index.web99.js";
+import "@solana/web3.js";
+import "bs58";
+import { encodeBase64 as l, decodeBase64 as T } from "./index.web96.js";
+function N(o) {
+  const t = f();
+  if (!t || !t.solanaAccountObjects?.length)
+    throw new Error(
+      "No accounts found. User must be authenticated and have at least one Solana account"
+    );
+  const e = m(), a = u();
+  return {
+    address: p(o),
+    signTransactions: async (c, h) => {
+      const n = [];
+      for (const i of c) {
+        const s = new Uint8Array(e.encode(i)), { signedTransaction: d } = await g({
+          solanaAccount: o,
+          transaction: l(s)
+        }), r = a.decode(T(d)).signatures[o];
+        if (!r)
+          throw new Error("Wallet did not return a signature for the selected account.");
+        n.push(
+          Object.freeze({
+            [o]: r
+          })
+        );
+      }
+      return n;
+    }
+  };
 }
 export {
-  u as isSignedIn,
-  A as withAuth
+  N as toTransactionSigner
 };

package/dist/web/index.web96.js

@@ -1,47 +1,34 @@
-import { SendEvmTransactionWithEndUserAccountBodyNetwork as i } from "@coinbase/cdp-api-client";
-const t = (e) => !e || typeof e != "object" ? e : Array.isArray(e) ? e.map(t) : Object.keys(e).sort().reduce(
-  (r, n) => (r[n] = t(e[n]), r),
-  {}
-), p = (e) => Object.values(i).includes(
-  e
-), a = {
-  "base-sepolia": 84532,
-  base: 8453,
-  ethereum: 1,
-  "ethereum-sepolia": 11155111,
-  avalanche: 43114,
-  polygon: 137,
-  optimism: 10,
-  arbitrum: 42161,
-  "arbitrum-sepolia": 421614,
-  world: 480,
-  "world-sepolia": 4801
-}, u = Object.fromEntries(
-  Object.entries(a).map(([e, r]) => [r, e])
-), c = (e) => Object.values(a).includes(
-  e
-), s = {
-  "base-sepolia": 84532,
-  base: 8453,
-  ethereum: 1,
-  "ethereum-sepolia": 11155111,
-  avalanche: 43114,
-  polygon: 137,
-  optimism: 10,
-  arbitrum: 42161,
-  zora: 7777777,
-  bnb: 56
-}, m = Object.fromEntries(
-  Object.entries(s).map(([e, r]) => [r, e])
-), d = (e) => Object.values(s).includes(
-  e
-);
+function a(e) {
+  if (typeof btoa < "u")
+    return btoa(
+      Array.from(e).map((t) => String.fromCharCode(t)).join("")
+    );
+  const c = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let r = "";
+  for (let t = 0; t < e.length; t += 3) {
+    const h = e[t], n = t + 1 < e.length ? e[t + 1] : 0, s = t + 2 < e.length ? e[t + 2] : 0, o = h << 16 | n << 8 | s;
+    r += c.charAt(o >> 18 & 63), r += c.charAt(o >> 12 & 63), r += t + 1 < e.length ? c.charAt(o >> 6 & 63) : "=", r += t + 2 < e.length ? c.charAt(o & 63) : "=";
+  }
+  return r;
+}
+function g(e) {
+  if (typeof atob < "u") {
+    const n = atob(e), s = new Uint8Array(n.length);
+    for (let o = 0; o < n.length; o++)
+      s[o] = n.charCodeAt(o);
+    return s;
+  }
+  const c = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/", r = {};
+  for (let n = 0; n < c.length; n++)
+    r[c[n]] = n;
+  const t = e.replace(/[^A-Za-z0-9+/]/g, ""), h = [];
+  for (let n = 0; n < t.length; n += 4) {
+    const s = r[t[n]] || 0, o = r[t[n + 1]] || 0, l = r[t[n + 2]] || 0, f = r[t[n + 3]] || 0, i = s << 18 | o << 12 | l << 6 | f;
+    h.push(i >> 16 & 255), n + 2 < t.length && h.push(i >> 8 & 255), n + 3 < t.length && h.push(i & 255);
+  }
+  return new Uint8Array(h);
+}
 export {
-  c as isChainIdSupportedForCDPSends,
-  d as isChainIdSupportedForCDPUserOps,
-  p as isChainSupportedForCDPSends,
-  u as sendTransactionChainIdToNameMapping,
-  t as sortKeys,
-  m as userOperationChainIdToNameMapping,
-  s as userOperationNameToChainIdMapping
+  g as decodeBase64,
+  a as encodeBase64
 };

package/dist/web/index.web97.js

@@ -1,5 +1,20 @@
-import { __require as r } from "./index.web133.js";
-var f = r();
+import "@coinbase/cdp-api-client";
+import "viem";
+const u = async (c) => await c.isSignedIn();
+async function A(c, a, r) {
+  if (!await u(a))
+    throw new Error("User not signed in");
+  const t = a.getUser();
+  if ("evmAccount" in c && !(t.evmAccounts?.find((n) => n === c.evmAccount) || t.evmAccountObjects?.find((n) => n.address === c.evmAccount)))
+    throw new Error("EVM account not found");
+  if ("evmSmartAccount" in c && !(t.evmSmartAccounts?.find((n) => n === c.evmSmartAccount) || t.evmSmartAccountObjects?.find((n) => n.address === c.evmSmartAccount)))
+    throw new Error("EVM Smart Account not found");
+  if ("solanaAccount" in c && !(t.solanaAccounts?.find((n) => n === c.solanaAccount) || t.solanaAccountObjects?.find((n) => n.address === c.solanaAccount)))
+    throw new Error("Solana account not found");
+  const e = await a.getWalletSecretId();
+  return r({ ...c, user: t, walletSecretId: e });
+}
 export {
-  f as b
+  u as isSignedIn,
+  A as withAuth
 };

package/dist/web/index.web98.js

@@ -1,46 +1,47 @@
-import { InputValidationError as a } from "./index.web86.js";
-import { getPlatformCrypto as l } from "./index.web4.js";
-function y(e, o) {
-  if (e.period !== void 0 && e.periodInDays !== void 0)
-    throw new a(
-      "Cannot specify both 'period' and 'periodInDays'. Please provide only one."
-    );
-  if (e.period === void 0 && e.periodInDays === void 0)
-    throw new a("Must specify either 'period' (in seconds) or 'periodInDays'.");
-  const t = e.period ?? e.periodInDays * 24 * 60 * 60, d = /* @__PURE__ */ new Date(), c = e.start ?? d, r = e.end, f = Math.floor(c.getTime() / 1e3), E = r ? Math.floor(r.getTime() / 1e3) : 281474976710655;
-  return {
-    account: e.account,
-    spender: e.spender,
-    allowance: e.allowance,
-    token: D(e.token, o),
-    period: t,
-    start: f,
-    end: E,
-    salt: e.salt ?? l().generateRandomSalt(),
-    extraData: e.extraData ?? "0x"
-  };
-}
-function D(e, o) {
-  if (e === "eth")
-    return "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
-  if (e === "usdc") {
-    const t = n[o]?.usdc;
-    if (!t)
-      throw new a(
-        `Automatic token address lookup for ${e} is not supported on ${o}. Please provide the token address manually.`
-      );
-    return t;
-  }
-  return e;
-}
-const n = {
-  base: {
-    usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"
-  },
-  "base-sepolia": {
-    usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
-  }
-};
+import { SendEvmTransactionWithEndUserAccountBodyNetwork as i } from "@coinbase/cdp-api-client";
+const t = (e) => !e || typeof e != "object" ? e : Array.isArray(e) ? e.map(t) : Object.keys(e).sort().reduce(
+  (r, n) => (r[n] = t(e[n]), r),
+  {}
+), p = (e) => Object.values(i).includes(
+  e
+), a = {
+  "base-sepolia": 84532,
+  base: 8453,
+  ethereum: 1,
+  "ethereum-sepolia": 11155111,
+  avalanche: 43114,
+  polygon: 137,
+  optimism: 10,
+  arbitrum: 42161,
+  "arbitrum-sepolia": 421614,
+  world: 480,
+  "world-sepolia": 4801
+}, u = Object.fromEntries(
+  Object.entries(a).map(([e, r]) => [r, e])
+), c = (e) => Object.values(a).includes(
+  e
+), s = {
+  "base-sepolia": 84532,
+  base: 8453,
+  ethereum: 1,
+  "ethereum-sepolia": 11155111,
+  avalanche: 43114,
+  polygon: 137,
+  optimism: 10,
+  arbitrum: 42161,
+  zora: 7777777,
+  bnb: 56
+}, m = Object.fromEntries(
+  Object.entries(s).map(([e, r]) => [r, e])
+), d = (e) => Object.values(s).includes(
+  e
+);
 export {
-  y as toSpendPermission
+  c as isChainIdSupportedForCDPSends,
+  d as isChainIdSupportedForCDPUserOps,
+  p as isChainSupportedForCDPSends,
+  u as sendTransactionChainIdToNameMapping,
+  t as sortKeys,
+  m as userOperationChainIdToNameMapping,
+  s as userOperationNameToChainIdMapping
 };

package/dist/web/index.web99.js

@@ -1,27 +1,5 @@
-import "@coinbase/cdp-api-client";
-const e = (t) => ({
-  userId: t.userId,
-  // Deprecated fields - keep for backward compatibility
-  evmAccounts: t.evmAccounts?.map((c) => c) ?? [],
-  evmSmartAccounts: t.evmSmartAccounts?.map((c) => c) ?? [],
-  solanaAccounts: t.solanaAccounts?.map((c) => c) ?? [],
-  // New account object fields
-  evmAccountObjects: t.evmAccountObjects,
-  evmSmartAccountObjects: t.evmSmartAccountObjects,
-  solanaAccountObjects: t.solanaAccountObjects,
-  btcAccountObjects: t.btcAccountObjects,
-  authenticationMethods: t.authenticationMethods.reduce((c, o) => (c[o.type] = o, c), {}),
-  mfaMethods: t.mfaMethods,
-  lastAuthenticatedAt: t.lastAuthenticatedAt
-}), s = (t, c, o) => {
-  const a = new Date(c).getTime();
-  return {
-    accessToken: t,
-    expiresAt: a,
-    user: e(o)
-  };
-};
+import { __require as r } from "./index.web135.js";
+var f = r();
 export {
-  s as toAuthState,
-  e as toAuthStateUser
+  f as b
 };

package/dist/web-types/actions/enableSpendPermissions.d.ts

@@ -0,0 +1,39 @@
+import { SpendPermissionNetwork as EnableSpendPermissionsNetwork } from '@coinbase/cdp-api-client';
+import { EvmAddress, Hex } from '../types.js';
+/**
+ * Options for enabling spend permissions on an existing EVM Smart Account.
+ */
+export type EnableSpendPermissionsOptions = {
+    /** - The EVM Smart Account to enable spend permissions for. */
+    evmSmartAccount: EvmAddress;
+    /** - The network where the owner change will be initially submitted. */
+    network: EnableSpendPermissionsNetwork;
+    /** - Optional idempotency key for safe retries. */
+    idempotencyKey?: string;
+};
+/**
+ * Result of enableSpendPermissions.
+ */
+export type EnableSpendPermissionsResult = {
+    /** - The user operation hash. Poll with `getUserOperation` until status is `complete`. */
+    userOperationHash: Hex;
+};
+/**
+ * Enables spend permissions on an existing EVM Smart Account by adding the
+ * SpendPermissionManager contract as an owner via a server-side signing flow.
+ *
+ * Returns a user operation hash that must be polled with `getUserOperation` until
+ * the status is `complete` before calling `createSpendPermission`.
+ *
+ * @param options - The options for enabling spend permissions.
+ * @example
+ * ```typescript lines
+ * const { userOperationHash } = await enableSpendPermissions({
+ *   evmSmartAccount: "0x1234...",
+ *   network: "base-sepolia",
+ * });
+ * ```
+ * @returns The user operation hash for polling on-chain confirmation.
+ */
+export declare const enableSpendPermissions: (options: EnableSpendPermissionsOptions) => Promise<EnableSpendPermissionsResult>;
+export type { EnableSpendPermissionsNetwork };

package/dist/web-types/errors.d.ts

@@ -61,7 +61,9 @@ export type MfaErrorCode =
 /** MFA verification was cancelled. */
  | "CANCELLED"
 /** No MFA listener is registered to handle verification. */
- | "LISTENER_REQUIRED";
+ | "LISTENER_REQUIRED"
+/** MFA listeners are registered but none matched the trigger value. */
+ | "NO_LISTENER_MATCHED";
 /**
  * Error thrown when an MFA operation fails.
  */

package/dist/web-types/index.d.ts

@@ -3,6 +3,7 @@ export { createSpendPermission, type CreateSpendPermissionOptions, type CreateSp
 export { listSpendPermissions, type ListSpendPermissionsOptions, type ListSpendPermissionsResult, } from './actions/listSpendPermissions.js';
 export { type SpendPermissionNetwork } from '@coinbase/cdp-api-client';
 export { revokeSpendPermission, type RevokeSpendPermissionOptions, type RevokeSpendPermissionResult, } from './actions/revokeSpendPermission.js';
+export { enableSpendPermissions, type EnableSpendPermissionsOptions, type EnableSpendPermissionsResult, type EnableSpendPermissionsNetwork, } from './actions/enableSpendPermissions.js';
 export { getCurrentUserSync } from './actions/getCurrentUserSync.js';
 export { fetchWithX402, type FetchWithX402Options, type FetchWithX402ReturnType, } from './actions/fetchWithX402.js';
 export { linkGoogle } from './actions/linkGoogle.js';
@@ -44,7 +45,8 @@ export { submitMfaEnrollment, type SubmitMfaEnrollmentOptions, type SubmitMfaEnr
 export { initiateMfaVerification, type InitiateMfaVerificationOptions, } from './actions/initiateMfaVerification.js';
 export { submitMfaVerification, type SubmitMfaVerificationOptions, } from './actions/submitMfaVerification.js';
 export { cancelMfaVerification } from './actions/cancelMfaVerification.js';
-export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, registerMfaListener, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaListenerOptions, type MfaVerificationContext, } from './mfa/index.js';
+export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaVerificationContext, } from './mfa/index.js';
+export { registerMfaListener, type MfaListenerOptions } from './mfa/state.web.js';
 export * from './auth/authManager.js';
 export * from './auth/types.js';
 export * from './shared/types.js';

package/dist/web-types/index.native.d.ts

@@ -8,6 +8,7 @@ export { createSpendPermission, type CreateSpendPermissionOptions, type CreateSp
 export { listSpendPermissions, type ListSpendPermissionsOptions, type ListSpendPermissionsResult, } from './actions/listSpendPermissions.js';
 export { type SpendPermissionNetwork } from '@coinbase/cdp-api-client';
 export { revokeSpendPermission, type RevokeSpendPermissionOptions, type RevokeSpendPermissionResult, } from './actions/revokeSpendPermission.js';
+export { enableSpendPermissions, type EnableSpendPermissionsOptions, type EnableSpendPermissionsResult, type EnableSpendPermissionsNetwork, } from './actions/enableSpendPermissions.js';
 export { getCurrentUserSync } from './actions/getCurrentUserSync.js';
 export { fetchWithX402, type FetchWithX402Options, type FetchWithX402ReturnType, } from './actions/fetchWithX402.js';
 export { linkGoogle } from './actions/linkGoogle.js';
@@ -48,7 +49,8 @@ export { submitMfaEnrollment, type SubmitMfaEnrollmentOptions, type SubmitMfaEnr
 export { initiateMfaVerification } from './actions/initiateMfaVerification.js';
 export { submitMfaVerification, type SubmitMfaVerificationOptions, } from './actions/submitMfaVerification.js';
 export { cancelMfaVerification } from './actions/cancelMfaVerification.js';
-export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, registerMfaListener, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaListenerOptions, type MfaVerificationContext, } from './mfa/index.js';
+export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaVerificationContext, } from './mfa/index.js';
+export { registerMfaListener, type MfaListenerOptions } from './mfa/state.js';
 export * from './auth/authManager.js';
 export * from './auth/types.js';
 export * from './types.js';

package/dist/web-types/index.web.d.ts

@@ -8,6 +8,7 @@ export { createSpendPermission, type CreateSpendPermissionOptions, type CreateSp
 export { listSpendPermissions, type ListSpendPermissionsOptions, type ListSpendPermissionsResult, } from './actions/listSpendPermissions.js';
 export { type SpendPermissionNetwork } from '@coinbase/cdp-api-client';
 export { revokeSpendPermission, type RevokeSpendPermissionOptions, type RevokeSpendPermissionResult, } from './actions/revokeSpendPermission.js';
+export { enableSpendPermissions, type EnableSpendPermissionsOptions, type EnableSpendPermissionsResult, type EnableSpendPermissionsNetwork, } from './actions/enableSpendPermissions.js';
 export { getCurrentUserSync } from './actions/getCurrentUserSync.js';
 export { fetchWithX402, type FetchWithX402Options, type FetchWithX402ReturnType, } from './actions/fetchWithX402.js';
 export { linkGoogle } from './actions/linkGoogle.js';
@@ -48,7 +49,8 @@ export { submitMfaEnrollment, type SubmitMfaEnrollmentOptions, type SubmitMfaEnr
 export { initiateMfaVerification } from './actions/initiateMfaVerification.js';
 export { submitMfaVerification, type SubmitMfaVerificationOptions, } from './actions/submitMfaVerification.js';
 export { cancelMfaVerification } from './actions/cancelMfaVerification.js';
-export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, registerMfaListener, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaListenerOptions, type MfaVerificationContext, } from './mfa/index.js';
+export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa, isMfaProtectedAction, isMfaRequired, MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, type MfaProtectedAction, type MfaListener, type MfaVerificationContext, } from './mfa/index.js';
+export { registerMfaListener, type MfaListenerOptions } from './mfa/state.web.js';
 export * from './auth/authManager.js';
 export * from './auth/types.js';
 export * from './shared/types.js';

package/dist/web-types/mfa/index.d.ts

@@ -1,4 +1,4 @@
-export { hasPendingMfaVerification, registerMfaListener, resolvePendingMfaVerification, rejectPendingMfaVerification, triggerMfaVerification, type MfaListener, type MfaVerificationContext, type MfaListenerOptions, } from './state.js';
+export { hasPendingMfaVerification, resolvePendingMfaVerification, rejectPendingMfaVerification, triggerMfaVerification, type MfaListener, type MfaVerificationContext, } from './state.js';
 export { getEnabledMfaMethods, getEnrolledMfaMethods, isEnrolledInMfa } from './utils.js';
 export { withMfa, ensureMfaVerified, isMfaRequired } from './withMfa.js';
 export { MFA_PROTECTED_ACTIONS, MFA_PROTECTED_FUNCTIONS, isMfaProtectedAction, type MfaProtectedAction, } from './protectedActions.js';

package/dist/web-types/mfa/state.d.ts

@@ -12,50 +12,66 @@ export type MfaVerificationContext = {
  */
 export type MfaListener = (context: MfaVerificationContext) => void;
 /**
- * Options for registering an MFA listener.
+ * Options for registering an MFA listener at the core layer.
+ *
+ * The core registry is platform-agnostic. The optional `matches` predicate
+ * lets a listener express "only fire when the trigger value satisfies this
+ * predicate." Platform adapters (e.g. the web adapter) layer their own
+ * scoping semantics on top of this opaque predicate.
  */
 export type MfaListenerOptions = {
     /**
-     * Optional DOM element that defines the scope for this handler.
-     * When provided, this handler will only respond to MFA triggers
-     * that originate from within this element (e.g., button clicks inside a container).
-     * Handlers without a scope act as global handlers.
+     * Optional predicate that gates this listener.
+     *
+     * When provided, the listener only fires when `triggerMfaVerification` is
+     * called with a `trigger` value (or a default trigger supplied by the
+     * platform) that satisfies the predicate. When omitted, the listener is
+     * a "global" listener that fires only when no predicate-based listener
+     * matched the trigger.
      */
-    scope?: HTMLElement;
+    matches?: (trigger: unknown) => boolean;
 };
 /**
- * Registers an MFA verification listener.
+ * Installs (or clears) the default trigger provider.
  *
- * Listeners can be global (no scope) or scoped to a specific DOM element.
- * The event bubbles up from the trigger element through the DOM:
- * - Scoped listeners listen on their container and catch events from within
- * - Global listeners listen on document and catch anything that bubbles up
+ * The web entry point uses this to expose `document.activeElement` as the
+ * default trigger so scoped listeners can match against it. Native entry
+ * points have no DOM and therefore install nothing.
  *
- * @param {MfaListener} listener - The listener function to call when MFA is required.
- * @param {MfaListenerOptions} [options] - Optional configuration including scope element.
- * @returns {() => void} A function to unregister the listener.
+ * @param provider - Function that returns the trigger value, or `null` to clear.
+ * @internal
+ */
+export declare const setDefaultTriggerProvider: (provider: (() => unknown) | null) => void;
+/**
+ * Registers an MFA verification listener.
+ *
+ * Listeners can be global (no `matches` predicate) or scoped via an opaque
+ * predicate. When `triggerMfaVerification` fires:
+ * - If any predicate-based listener matches the trigger, only those listeners
+ *   are invoked.
+ * - Otherwise, all global listeners are invoked.
  *
- * @example
- * ```typescript
- * // Global listener (responds to any MFA trigger not handled by a scoped listener)
- * const unregisterGlobal = registerMfaListener(({ methods }) => {
- *   openMfaModal(methods);
- * });
+ * Platform adapters wrap this function to provide their own scoping shape
+ * (e.g. a DOM `scope: HTMLElement` on web).
  *
- * // Scoped listener (only responds to triggers inside the container)
- * const container = document.getElementById('my-flow');
- * if (container) {
- *   const unregisterScoped = registerMfaListener(
- *     ({ methods }) => showInlineMfa(methods),
- *     { scope: container }
- *   );
- *   // Later, when done:
- *   unregisterScoped();
- * }
+ * Notes:
+ * - Matched suppresses globals. When any predicate-based listener matches,
+ *   all global (unscoped) listeners are skipped, including the app's own
+ *   default modal. This mirrors the previous DOM implementation's
+ *   stopPropagation semantics. Prefer narrow predicates; a permissive
+ *   `matches: () => true` silently suppresses every global listener.
+ * - Coordination, not authz. This registry is a UX coordination layer for
+ *   which listener shows the verification UI. The server still enforces MFA
+ *   via `mfa_required` regardless of which listener fires (or whether one
+ *   fires at all).
+ * - React Native: RN does not install a default trigger provider, so
+ *   `matches` is invoked with `undefined`. Predicates that don't accept
+ *   `undefined` will never match — most RN consumers should omit `matches`
+ *   entirely and register a global listener.
  *
- * // Clean up global listener when done:
- * unregisterGlobal();
- * ```
+ * @param {MfaListener} listener - The listener function to call when MFA is required.
+ * @param {MfaListenerOptions} [options] - Optional configuration with an opaque predicate.
+ * @returns {() => void} A function to unregister the listener.
  */
 export declare const registerMfaListener: (listener: MfaListener, options?: MfaListenerOptions) => (() => void);
 /**
@@ -68,18 +84,22 @@ export declare const hasRegisteredMfaListeners: () => boolean;
  * Triggers the MFA verification flow and returns a Promise that resolves
  * when MFA is successfully completed.
  *
- * Dispatches a custom DOM event from the trigger element that bubbles up.
- * Scoped handlers catch events from within their container.
- * Global handlers catch anything that bubbles to document.
+ * Selection rule:
+ * - All registered listeners with a `matches` predicate are evaluated against
+ *   the trigger (the explicit `trigger` argument, or the value returned by
+ *   the default trigger provider if one is installed).
+ * - If any predicate matches, only the matching listeners are invoked.
+ * - Otherwise, all listeners without a predicate (global listeners) are invoked.
  *
- * If no handlers are registered, this is a no-op and resolves immediately.
+ * If no listeners are registered, this is a no-op and resolves immediately.
  * Use `hasRegisteredMfaListeners()` to check before calling if needed.
  *
  * @param {MfaMethod[]} methods - The MFA methods available for verification.
+ * @param {unknown} [trigger] - Optional opaque trigger value used by listener predicates.
  * @returns {Promise<void>} A Promise that resolves when MFA is complete.
  * @internal
  */
-export declare const triggerMfaVerification: (methods: MfaMethod[]) => Promise<void>;
+export declare const triggerMfaVerification: (methods: MfaMethod[], trigger?: unknown) => Promise<void>;
 /**
  * Resolves the pending MFA verification Promise.
  * Called internally after successful MFA submission.

package/dist/web-types/mfa/state.web.d.ts

@@ -0,0 +1,62 @@
+import { MfaListener } from './state.js';
+/**
+ * Options for registering an MFA listener on web.
+ *
+ * Web-specific shape: when a `scope` element is provided, the listener only
+ * fires for MFA triggers that originate from inside that element (based on
+ * `document.activeElement` at trigger time, supplied by the web entry point's
+ * default trigger provider).
+ *
+ * Listeners without a scope act as global listeners.
+ */
+export type MfaListenerOptions = {
+    /**
+     * Optional DOM element that defines the scope for this handler.
+     * When provided, this handler only responds to MFA triggers that originate
+     * from within this element. Handlers without a scope act as global handlers.
+     */
+    scope?: HTMLElement;
+};
+/**
+ * Registers an MFA verification listener (web).
+ *
+ * The web adapter translates the DOM-shaped `scope` option into an opaque
+ * predicate against the trigger element supplied by the web entry point's
+ * default trigger provider (`document.activeElement` or `document.body`).
+ *
+ * Notes:
+ * - Matched suppresses globals. When any scoped listener's `scope` contains
+ *   the trigger, all global (unscoped) listeners are skipped, including the
+ *   app's own default modal. Mirrors the previous DOM implementation's
+ *   stopPropagation semantics.
+ * - Innermost wins. When multiple scoped listeners contain the trigger
+ *   (e.g. a page container scope and a nested per-flow scope), only the
+ *   deepest scope's listener fires. Mirrors DOM bubble order.
+ * - Shadow DOM. `Element.contains` does not cross shadow DOM boundaries.
+ *   A trigger inside an open shadow tree whose host is inside `scope` will
+ *   not match. Workaround: register a global listener.
+ * - Coordination, not authz. Same caveat as the core registry — the server
+ *   still enforces MFA via `mfa_required`.
+ *
+ * @param {MfaListener} listener - The listener function to call when MFA is required.
+ * @param {MfaListenerOptions} [options] - Optional configuration including a DOM scope element.
+ * @returns {() => void} A function to unregister the listener.
+ *
+ * @example
+ * ```typescript
+ * // Global listener (responds to any MFA trigger not handled by a scoped listener)
+ * const unregisterGlobal = registerMfaListener(({ methods }) => {
+ *   openMfaModal(methods);
+ * });
+ *
+ * // Scoped listener (only responds to triggers inside the container)
+ * const container = document.getElementById('my-flow');
+ * if (container) {
+ *   const unregisterScoped = registerMfaListener(
+ *     ({ methods }) => showInlineMfa(methods),
+ *     { scope: container }
+ *   );
+ * }
+ * ```
+ */
+export declare const registerMfaListener: (listener: MfaListener, options?: MfaListenerOptions) => (() => void);

package/dist/web-types/version.d.ts

@@ -2,4 +2,4 @@
  * Current version of @coinbase/cdp-core package.
  * This file is auto-generated by scripts/sync-versions.js
  */
-export declare const VERSION = "0.0.106";
+export declare const VERSION = "0.0.108";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cdp-core",
-  "version": "0.0.107",
+  "version": "0.0.109",
   "type": "module",
   "files": [
     "dist/**",
@@ -29,7 +29,7 @@
     "ox": "0.8.1",
     "viem": "^2.47.0",
     "zustand": "^5.0.6",
-    "@coinbase/cdp-api-client": "^0.0.107"
+    "@coinbase/cdp-api-client": "^0.0.109"
   },
   "peerDependencies": {
     "@react-native-async-storage/async-storage": "^2.0.0",