@coinbase/cdp-core 0.0.107 → 0.0.108

package/dist/native/index.native7.js

@@ -1,10 +1,10 @@
 import * as u from "expo-web-browser";
 import { WebBrowserResultType as o } from "expo-web-browser";
 import { getAppleAuthProvider as l } from "./index.native95.js";
-import { getCoreOAuthManager as s, getConfig as p } from "./index.native75.js";
+import { getCoreOAuthManager as s, getConfig as h } from "./index.native75.js";
 const d = {
   getRedirectUrl: () => {
-    const e = p().nativeOAuthCallback;
+    const e = h().nativeOAuthCallback;
     if (!e)
       throw new Error("nativeOAuthCallback must be configured in order to use native OAuth");
     return e;
@@ -54,13 +54,13 @@ const d = {
   openTelegramOAuthPopup: async () => {
     throw new Error("Telegram OAuth is not currently supported in React Native environments.");
   },
-  signInWithAppleNative: async () => {
-    const e = l();
-    if (!e)
-      throw new Error(
-        "Apple Sign In provider not registered. Import '@coinbase/cdp-react-native' in your app's entry point to enable native Apple Sign In."
-      );
-    return e();
+  /**
+   * Returns the registered Apple auth provider, or undefined to fall back to the webview flow.
+   *
+   * @returns The registered Apple auth provider, or undefined if none is registered.
+   */
+  get signInWithAppleNative() {
+    return l() ?? void 0;
   }
 };
 export {

package/dist/native/index.native82.js

@@ -1,50 +1,65 @@
 import "@coinbase/cdp-api-client";
-import { MfaError as p } from "./index.native89.js";
-const c = "cdp-web-mfa-required", v = () => {
-  let t, r;
-  return { promise: new Promise((o, s) => {
-    t = o, r = s;
-  }), resolve: t, reject: r };
-}, i = /* @__PURE__ */ new Set();
-let e = null;
-const M = (t, r) => {
-  const n = r?.scope, o = n ?? document, s = (l) => {
-    const f = l, { methods: m } = f.detail;
-    n && l.stopPropagation();
-    try {
-      t({ methods: m });
-    } catch (u) {
-      console.error("MFA listener threw an error:", u);
-    }
-  };
-  o.addEventListener(c, s);
-  const a = () => {
-    o.removeEventListener(c, s);
-  }, d = { listener: t, scope: n, cleanup: a };
-  return i.add(d), () => {
-    a(), i.delete(d);
+import { MfaError as d } from "./index.native89.js";
+const g = () => {
+  let t, s;
+  return { promise: new Promise((o, n) => {
+    t = o, s = n;
+  }), resolve: t, reject: s };
+}, c = /* @__PURE__ */ new Set();
+let e = null, u = null;
+const p = (t, s) => {
+  const r = { listener: t, matches: s?.matches };
+  return c.add(r), () => {
+    c.delete(r);
   };
-}, b = () => i.size > 0, w = (t) => {
-  if (i.size === 0)
+}, M = () => c.size > 0, v = (t, s) => {
+  if (c.size === 0)
     return Promise.resolve();
   e && (e.reject(
-    new p("SUPERSEDED", "MFA verification superseded by a newer request")
-  ), e = null), e = v();
-  const r = document.activeElement, n = r && r !== document.body ? r : document.body, o = new CustomEvent(c, {
-    bubbles: !0,
-    // Allow event to bubble up through DOM
-    detail: { methods: t }
-  });
-  return n.dispatchEvent(o), e.promise;
-}, P = () => {
+    new d("SUPERSEDED", "MFA verification superseded by a newer request")
+  ), e = null);
+  const r = g();
+  e = r;
+  let o;
+  try {
+    o = s !== void 0 ? s : u?.();
+  } catch (i) {
+    console.error("MFA default trigger provider threw an error:", i), o = void 0;
+  }
+  const n = [], l = [];
+  for (const i of c)
+    if (i.matches)
+      try {
+        i.matches(o) && n.push(i);
+      } catch (a) {
+        console.error("MFA listener predicate threw an error:", a);
+      }
+    else
+      l.push(i);
+  const f = n.length > 0 ? n : l;
+  if (f.length === 0)
+    return r.reject(
+      new d(
+        "NO_LISTENER_MATCHED",
+        "MFA verification was triggered but no registered listener matched. Ensure a global MFA listener is registered, or that a scoped listener's predicate matches the trigger."
+      )
+    ), e === r && (e = null), r.promise;
+  for (const i of f)
+    try {
+      i.listener({ methods: t });
+    } catch (a) {
+      console.error("MFA listener threw an error:", a);
+    }
+  return r.promise;
+}, w = () => {
   e && (e.resolve(), e = null);
-}, L = (t) => {
+}, E = (t) => {
   e && (e.reject(t), e = null);
 };
 export {
-  b as hasRegisteredMfaListeners,
-  M as registerMfaListener,
-  L as rejectPendingMfaVerification,
-  P as resolvePendingMfaVerification,
-  w as triggerMfaVerification
+  M as hasRegisteredMfaListeners,
+  p as registerMfaListener,
+  E as rejectPendingMfaVerification,
+  w as resolvePendingMfaVerification,
+  v as triggerMfaVerification
 };

package/dist/native-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/native-types/index.d.ts

@@ -44,7 +44,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/native-types/index.native.d.ts

@@ -48,7 +48,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/native-types/index.web.d.ts

@@ -48,7 +48,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/native-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/native-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/native-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/native-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/dist/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/types/index.d.ts

@@ -44,7 +44,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/types/index.native.d.ts

@@ -48,7 +48,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/types/index.web.d.ts

@@ -48,7 +48,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/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/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.