@matanetwork/sovereign-id 0.1.0 → 0.1.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 MATA Network
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 MATA Network
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matanetwork/sovereign-id",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Page-side SDK for MATA Sovereign ID — the permissionless self-issued identity protocol (mID). Probes for the MATA browser extension or native app, dispatches sign-in requests, and resolves with a signed JWT.",
   "type": "module",
   "main": "src/index.js",
@@ -37,13 +37,16 @@
   "engines": {
     "node": ">=18"
   },
-  "homepage": "https://github.com/mata-network/mata/tree/main/packages/mata-sovereign-id-sdk#readme",
+  "homepage": "https://github.com/Remade-With-Rust/sovereign-id/tree/main/packages/sovereign-id#readme",
   "bugs": {
-    "url": "https://github.com/mata-network/mata/issues"
+    "url": "https://github.com/Remade-With-Rust/sovereign-id/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mata-network/mata.git",
-    "directory": "packages/mata-sovereign-id-sdk"
+    "url": "git+https://github.com/Remade-With-Rust/sovereign-id.git",
+    "directory": "packages/sovereign-id"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }

package/src/index.d.ts

@@ -1,216 +1,229 @@
-/**
- * Type declarations for @matanetwork/sovereign-id.
- *
- * The runtime is pure JS (no TypeScript build step). This `.d.ts`
- * exists so consumers using TypeScript get full type-checking +
- * IDE intellisense.
- */
-
-// ─── Wire protocol constants ───────────────────────────────────────────────
-
-export const WINDOW_MID_GLOBAL: '__mata_mid__';
-export const MESSAGE_DISCRIMINATOR: '__mata_mid_v1';
-export const KIND_SIGN_IN_REQUEST: 'sign_in_request';
-export const KIND_SIGN_IN_RESPONSE: 'sign_in_response';
-export const URL_SCHEME: 'mata-mid';
-export const SCHEME_PATH_REQUEST: 'request';
-export const QUERY_PARAM_PAYLOAD: 'payload';
-export const FRAGMENT_KEY_RESPONSE: 'mid_response';
-export const PROTOCOL_VERSION: 1;
-
-// ─── Standard error codes ──────────────────────────────────────────────────
-
-export const ERR_USER_DENIED: 'user_denied';
-export const ERR_ORIGIN_MISMATCH: 'origin_mismatch';
-export const ERR_INVALID_REQUEST: 'invalid_request';
-export const ERR_WALLET_UNAVAILABLE: 'wallet_unavailable';
-export const ERR_REQUIRED_CLAIM_UNAVAILABLE: 'required_claim_unavailable';
-export const ERR_INTERNAL: 'internal_error';
-export const ERR_NO_WALLET_INSTALLED: 'no_wallet_installed';
-export const ERR_TIMEOUT: 'timeout';
-export const ERR_UPSELL_CANCELED: 'upsell_canceled';
-
-export type ErrorCode =
-  | typeof ERR_USER_DENIED
-  | typeof ERR_ORIGIN_MISMATCH
-  | typeof ERR_INVALID_REQUEST
-  | typeof ERR_WALLET_UNAVAILABLE
-  | typeof ERR_REQUIRED_CLAIM_UNAVAILABLE
-  | typeof ERR_INTERNAL
-  | typeof ERR_NO_WALLET_INSTALLED
-  | typeof ERR_TIMEOUT
-  | typeof ERR_UPSELL_CANCELED;
-
-// ─── Request / response types ──────────────────────────────────────────────
-
-export interface CustomClaim {
-  optional: true;
-  description?: string;
-}
-
-export interface SignInRequest {
-  /** The RP's bare origin, e.g. `"https://acme.com"`. */
-  rpOrigin: string;
-  /** RP-issued single-use nonce; appears in the JWT for replay defense. */
-  nonce: string;
-  /** Claim catalog the wallet should disclose. */
-  claims: {
-    /** Claims that MUST be approved; denial blocks sign-in. */
-    required: string[];
-    /** Claims the user can include or skip. */
-    optional?: string[];
-    /** Arbitrary custom keys from the user's profile_kv (v0: ignored). */
-    custom?: Record<string, CustomClaim>;
-  };
-}
-
-export interface SignInOptions {
-  /** Hard request timeout. Default: 120 seconds. */
-  timeoutMs?: number;
-  /**
-   * URL the native app's response will redirect to. Default:
-   * `window.location.href`. Only honored when the SDK falls through
-   * to the native-app deep link.
-   */
-  nativeAppCallback?: string;
-  /**
-   * Whether to show the install upsell modal when no wallet is
-   * detected on the user's device. Default: `true`. Set to `false`
-   * to get a raw `ERR_NO_WALLET_INSTALLED` rejection and handle
-   * the upsell UI yourself.
-   */
-  installUpsell?: boolean;
-  /**
-   * Referral code attributed to signups that flow through the install
-   * upsell. Default: the hostname extracted from `rpOrigin` (e.g.
-   * `"acme.com"`), so RPs get attribution by default without any
-   * extra wiring. Pass `null` to opt out of attribution entirely, or
-   * a custom string to override (e.g. a configured MATA referral
-   * code your team uses).
-   *
-   * Stamped onto the install CTA and the "create your account" link
-   * inside the upsell modal as `?ref=<code>`, following the existing
-   * MATA referral convention captured by my.mata.network's welcome
-   * view + signup form.
-   */
-  ref?: string | null;
-}
-
-/**
- * One of the CTAs the install upsell can present. Pick by browser/OS.
- * Exposed for RPs that want to render their own upsell UI from the
- * same recommendation engine.
- */
-export interface InstallCta {
-  /** Button text (e.g. `"Install MATA for Chrome"`). */
-  label: string;
-  /** Where the button navigates to. */
-  url: string;
-  /** Sub-text under the CTA (e.g. `"Opens the Chrome Web Store in a new tab"`). */
-  hint: string;
-}
-
-export interface InstallUpsellOptions {
-  /** Shown prominently as the requesting RP. */
-  rpOrigin: string;
-  /**
-   * Inversion-of-control hook so the SDK's `hasExtension()` is used
-   * in production and tests can stub it.
-   */
-  hasExtensionFn?: () => boolean;
-  /** Override the auto-picked CTA. */
-  cta?: InstallCta;
-  /** Default 1000 ms. */
-  pollIntervalMs?: number;
-  /**
-   * Referral code attributed to signups that flow through this
-   * upsell. Default: hostname of `rpOrigin`. Pass `null` to disable.
-   * See `SignInOptions.ref` for the full attribution model.
-   */
-  ref?: string | null;
-}
-
-export type InstallUpsellResult = 'installed' | 'canceled';
-
-export interface SignInSuccess {
-  /** JWS compact-form mID token. */
-  jwt: string;
-  /** Which surface produced the JWT. */
-  surface: 'extension' | 'native_app';
-}
-
-export class SignInError extends Error {
-  constructor(code: ErrorCode, message: string);
-  readonly code: ErrorCode;
-}
-
-// ─── Public functions ──────────────────────────────────────────────────────
-
-export function signIn(
-  request: SignInRequest,
-  options?: SignInOptions
-): Promise<SignInSuccess>;
-
-export function hasExtension(): boolean;
-
-/** Internal — exposed for SDK consumers that need to roll their own. */
-export function generateRequestId(): string;
-/** Internal — exposed for the verifier package + tests. */
-export function base64UrlEncode(str: string): string;
-/** Internal — exposed for the verifier package + tests. */
-export function base64UrlDecode(b64url: string): string;
-
-/**
- * Pick the right install CTA for the user's browser / OS. Auto-called
- * by `signIn()` when the upsell fires; exposed so RPs that opted out
- * of the inline modal can use the same recommendation engine in
- * their own UI.
- */
-export function pickInstallCta(): InstallCta;
-
-/**
- * Extract the default referral code from an RP origin — the bare
- * hostname (e.g. `"https://acme.com"` → `"acme.com"`). Exposed so
- * RPs can preview what attribution string they'd get without
- * actually triggering the upsell.
- *
- * Returns `null` for malformed origins.
- */
-export function defaultRefFromOrigin(rpOrigin: string): string | null;
-
-/**
- * Render the install upsell overlay and resolve when the user either
- * cancels or completes the install. Auto-called by `signIn()` on
- * `ERR_NO_WALLET_INSTALLED`; exposed for RPs who set
- * `installUpsell: false` and want to invoke it on their own
- * conditions.
- */
-export function showInstallUpsell(
-  options: InstallUpsellOptions
-): Promise<InstallUpsellResult>;
-
-/**
- * Resume a sign-in that was interrupted by a page reload during the
- * install upsell.
- *
- * Call once at app boot — ideally as early as possible — so a user
- * who installed MATA and reloaded sees their sign-in continue without
- * a visible flicker through the logged-out state.
- *
- * - Returns `{jwt, surface}` if a pending request was found, the
- *   extension is now installed, and the resumed sign-in completed.
- * - Returns `null` if no resume is pending, the stash is stale, or
- *   the extension is still missing (the user reloaded before
- *   actually installing).
- * - Rejects with `SignInError` when a pending request exists and the
- *   extension is present but the sign-in itself failed (`user_denied`,
- *   `timeout`, etc.). Same error shape as `signIn()`.
- */
-export function resumePendingSignIn(): Promise<SignInSuccess | null>;
-
-/**
- * Imperatively drop any pending resume entry. Useful when the RP
- * has navigated to a different sign-in flow that supersedes the
- * pending mID request.
- */
-export function clearPendingSignIn(): void;
+/**
+ * Type declarations for @matanetwork/sovereign-id.
+ *
+ * The runtime is pure JS (no TypeScript build step). This `.d.ts`
+ * exists so consumers using TypeScript get full type-checking +
+ * IDE intellisense.
+ */
+
+// ─── Wire protocol constants ───────────────────────────────────────────────
+
+export const WINDOW_MID_GLOBAL: '__mata_mid__';
+export const MESSAGE_DISCRIMINATOR: '__mata_mid_v1';
+export const KIND_SIGN_IN_REQUEST: 'sign_in_request';
+export const KIND_SIGN_IN_RESPONSE: 'sign_in_response';
+export const URL_SCHEME: 'mata-mid';
+export const SCHEME_PATH_REQUEST: 'request';
+export const QUERY_PARAM_PAYLOAD: 'payload';
+export const FRAGMENT_KEY_RESPONSE: 'mid_response';
+export const PROTOCOL_VERSION: 1;
+
+// ─── Standard error codes ──────────────────────────────────────────────────
+
+export const ERR_USER_DENIED: 'user_denied';
+export const ERR_ORIGIN_MISMATCH: 'origin_mismatch';
+export const ERR_INVALID_REQUEST: 'invalid_request';
+export const ERR_WALLET_UNAVAILABLE: 'wallet_unavailable';
+export const ERR_REQUIRED_CLAIM_UNAVAILABLE: 'required_claim_unavailable';
+export const ERR_INTERNAL: 'internal_error';
+export const ERR_NO_WALLET_INSTALLED: 'no_wallet_installed';
+export const ERR_TIMEOUT: 'timeout';
+export const ERR_UPSELL_CANCELED: 'upsell_canceled';
+
+export type ErrorCode =
+  | typeof ERR_USER_DENIED
+  | typeof ERR_ORIGIN_MISMATCH
+  | typeof ERR_INVALID_REQUEST
+  | typeof ERR_WALLET_UNAVAILABLE
+  | typeof ERR_REQUIRED_CLAIM_UNAVAILABLE
+  | typeof ERR_INTERNAL
+  | typeof ERR_NO_WALLET_INSTALLED
+  | typeof ERR_TIMEOUT
+  | typeof ERR_UPSELL_CANCELED;
+
+// ─── Request / response types ──────────────────────────────────────────────
+
+export interface CustomClaim {
+  optional: true;
+  description?: string;
+}
+
+export interface SignInRequest {
+  /** The RP's bare origin, e.g. `"https://acme.com"`. */
+  rpOrigin: string;
+  /** RP-issued single-use nonce; appears in the JWT for replay defense. */
+  nonce: string;
+  /** Claim catalog the wallet should disclose. */
+  claims: {
+    /** Claims that MUST be approved; denial blocks sign-in. */
+    required: string[];
+    /** Claims the user can include or skip. */
+    optional?: string[];
+    /** Arbitrary custom keys from the user's profile_kv (v0: ignored). */
+    custom?: Record<string, CustomClaim>;
+  };
+}
+
+export interface SignInOptions {
+  /** Hard request timeout. Default: 120 seconds. */
+  timeoutMs?: number;
+  /**
+   * URL the native app's response will redirect to. Default:
+   * `window.location.href`. Only honored when the SDK falls through
+   * to the native-app deep link. For a native host, set this to your
+   * app's own custom scheme (e.g. `"myapp://mid-callback"`) so the
+   * wallet's callback routes back to your app instead of a browser tab.
+   */
+  nativeAppCallback?: string;
+  /**
+   * Set `true` when this SDK runs inside a native webview
+   * (Dioxus/Tauri/wry/Electron) rather than a real browser tab. Skips
+   * the browser-only "no wallet installed" visibility heuristic — which
+   * would false-positive because a native webview never backgrounds when
+   * the OS opens the deep link — and relies on the hard `timeoutMs`
+   * instead. Pair with `nativeAppCallback` and have your host inject the
+   * returned `#mid_response=...` fragment back into the webview so the
+   * SDK's existing resume listener resolves the `signIn()` promise.
+   */
+  nativeHost?: boolean;
+  /**
+   * Whether to show the install upsell modal when no wallet is
+   * detected on the user's device. Default: `true`. Set to `false`
+   * to get a raw `ERR_NO_WALLET_INSTALLED` rejection and handle
+   * the upsell UI yourself.
+   */
+  installUpsell?: boolean;
+  /**
+   * Referral code attributed to signups that flow through the install
+   * upsell. Default: the hostname extracted from `rpOrigin` (e.g.
+   * `"acme.com"`), so RPs get attribution by default without any
+   * extra wiring. Pass `null` to opt out of attribution entirely, or
+   * a custom string to override (e.g. a configured MATA referral
+   * code your team uses).
+   *
+   * Stamped onto the install CTA and the "create your account" link
+   * inside the upsell modal as `?ref=<code>`, following the existing
+   * MATA referral convention captured by my.mata.network's welcome
+   * view + signup form.
+   */
+  ref?: string | null;
+}
+
+/**
+ * One of the CTAs the install upsell can present. Pick by browser/OS.
+ * Exposed for RPs that want to render their own upsell UI from the
+ * same recommendation engine.
+ */
+export interface InstallCta {
+  /** Button text (e.g. `"Install MATA for Chrome"`). */
+  label: string;
+  /** Where the button navigates to. */
+  url: string;
+  /** Sub-text under the CTA (e.g. `"Opens the Chrome Web Store in a new tab"`). */
+  hint: string;
+}
+
+export interface InstallUpsellOptions {
+  /** Shown prominently as the requesting RP. */
+  rpOrigin: string;
+  /**
+   * Inversion-of-control hook so the SDK's `hasExtension()` is used
+   * in production and tests can stub it.
+   */
+  hasExtensionFn?: () => boolean;
+  /** Override the auto-picked CTA. */
+  cta?: InstallCta;
+  /** Default 1000 ms. */
+  pollIntervalMs?: number;
+  /**
+   * Referral code attributed to signups that flow through this
+   * upsell. Default: hostname of `rpOrigin`. Pass `null` to disable.
+   * See `SignInOptions.ref` for the full attribution model.
+   */
+  ref?: string | null;
+}
+
+export type InstallUpsellResult = 'installed' | 'canceled';
+
+export interface SignInSuccess {
+  /** JWS compact-form mID token. */
+  jwt: string;
+  /** Which surface produced the JWT. */
+  surface: 'extension' | 'native_app';
+}
+
+export class SignInError extends Error {
+  constructor(code: ErrorCode, message: string);
+  readonly code: ErrorCode;
+}
+
+// ─── Public functions ──────────────────────────────────────────────────────
+
+export function signIn(
+  request: SignInRequest,
+  options?: SignInOptions
+): Promise<SignInSuccess>;
+
+export function hasExtension(): boolean;
+
+/** Internal — exposed for SDK consumers that need to roll their own. */
+export function generateRequestId(): string;
+/** Internal — exposed for the verifier package + tests. */
+export function base64UrlEncode(str: string): string;
+/** Internal — exposed for the verifier package + tests. */
+export function base64UrlDecode(b64url: string): string;
+
+/**
+ * Pick the right install CTA for the user's browser / OS. Auto-called
+ * by `signIn()` when the upsell fires; exposed so RPs that opted out
+ * of the inline modal can use the same recommendation engine in
+ * their own UI.
+ */
+export function pickInstallCta(): InstallCta;
+
+/**
+ * Extract the default referral code from an RP origin — the bare
+ * hostname (e.g. `"https://acme.com"` → `"acme.com"`). Exposed so
+ * RPs can preview what attribution string they'd get without
+ * actually triggering the upsell.
+ *
+ * Returns `null` for malformed origins.
+ */
+export function defaultRefFromOrigin(rpOrigin: string): string | null;
+
+/**
+ * Render the install upsell overlay and resolve when the user either
+ * cancels or completes the install. Auto-called by `signIn()` on
+ * `ERR_NO_WALLET_INSTALLED`; exposed for RPs who set
+ * `installUpsell: false` and want to invoke it on their own
+ * conditions.
+ */
+export function showInstallUpsell(
+  options: InstallUpsellOptions
+): Promise<InstallUpsellResult>;
+
+/**
+ * Resume a sign-in that was interrupted by a page reload during the
+ * install upsell.
+ *
+ * Call once at app boot — ideally as early as possible — so a user
+ * who installed MATA and reloaded sees their sign-in continue without
+ * a visible flicker through the logged-out state.
+ *
+ * - Returns `{jwt, surface}` if a pending request was found, the
+ *   extension is now installed, and the resumed sign-in completed.
+ * - Returns `null` if no resume is pending, the stash is stale, or
+ *   the extension is still missing (the user reloaded before
+ *   actually installing).
+ * - Rejects with `SignInError` when a pending request exists and the
+ *   extension is present but the sign-in itself failed (`user_denied`,
+ *   `timeout`, etc.). Same error shape as `signIn()`.
+ */
+export function resumePendingSignIn(): Promise<SignInSuccess | null>;
+
+/**
+ * Imperatively drop any pending resume entry. Useful when the RP
+ * has navigated to a different sign-in flow that supersedes the
+ * pending mID request.
+ */
+export function clearPendingSignIn(): void;

package/src/index.js

@@ -38,6 +38,12 @@ export const KIND_SIGN_IN_REQUEST = 'sign_in_request';
 /** The `kind` value on the sign-in response message. @internal */
 export const KIND_SIGN_IN_RESPONSE = 'sign_in_response';
 
+/** The `kind` value on the IAMHUMAN statement-sign request message. @internal */
+export const KIND_STATEMENT_SIGN_REQUEST = 'statement_sign_request';
+
+/** The `kind` value on the IAMHUMAN statement-sign response message. @internal */
+export const KIND_STATEMENT_SIGN_RESPONSE = 'statement_sign_response';
+
 /** The native app's URL scheme. @internal */
 export const URL_SCHEME = 'mata-mid';
 
@@ -122,7 +128,8 @@ const DEFAULT_TIMEOUT_MS = 120_000;
  * @param {Record<string, {optional: true, description?: string}>} [request.claims.custom] - custom claims
  * @param {object} [options]
  * @param {number} [options.timeoutMs] - request timeout (default: 2 min)
- * @param {string} [options.nativeAppCallback] - URL the native app opens to return (default: window.location.href)
+ * @param {string} [options.nativeAppCallback] - URL the native app opens to return (default: window.location.href). For a native host, set this to your app's own custom scheme (e.g. `"myapp://mid-callback"`) so the wallet's callback routes back to your app rather than a browser tab.
+ * @param {boolean} [options.nativeHost] - set `true` when this SDK runs inside a native webview (Dioxus/Tauri/wry/Electron) rather than a real browser tab. Skips the browser-only "no wallet" visibility heuristic (which would false-positive because a native webview never backgrounds) and relies on the hard `timeoutMs` instead. Pair with `nativeAppCallback` + your host injecting the `#mid_response` fragment back into the webview.
  * @param {boolean} [options.installUpsell] - whether to show the install upsell when no wallet is detected (default: true). Set to false to get the raw `ERR_NO_WALLET_INSTALLED` error and handle the upsell UI yourself.
  * @param {string | null} [options.ref] - referral code attributed to signups that flow through the install upsell. Defaults to the hostname extracted from `rpOrigin` (e.g., `"acme.com"`) so RPs get attribution by default. Pass `null` to opt out, or a custom string to override (e.g., a configured MATA referral code). Follows the existing `?ref=` convention captured by my.mata.network's signup flow.
  * @returns {Promise<{jwt: string, surface: "extension" | "native_app"}>}
@@ -397,6 +404,106 @@ function signInViaExtension(request, timeoutMs) {
   });
 }
 
+// ─── signStatement() — IAMHUMAN content signing (H0-broker) ─────────────────
+
+/**
+ * Ask the user's MATA wallet to sign content as their personal DID (an
+ * IAMHUMAN post/comment). The private key never leaves the wallet — it signs
+ * and returns a self-contained `mata-sign` token that the IAMHUMAN host
+ * accepts as-is. Parallel to `signIn()`, but produces a content signature.
+ *
+ * Extension surface only for now; native `mata-mid://statement` is a follow-up.
+ *
+ * @param {object} request
+ * @param {string} request.rpOrigin - the requesting site's bare origin
+ * @param {string} request.content - the exact content to sign
+ * @param {string} request.context - domain tag, e.g. "iamhuman"
+ * @param {string} [request.contentType] - media type (default "text/plain")
+ * @param {string | null} [request.nonce] - optional single-use nonce
+ * @param {object} [options]
+ * @param {number} [options.timeoutMs] - request timeout (default 2 min)
+ * @returns {Promise<{token: string, surface: "extension"}>}
+ * @throws {SignInError} with `.code` matching one of the `ERR_*` constants
+ */
+export async function signStatement(request, options = {}) {
+  if (
+    !request ||
+    typeof request.rpOrigin !== 'string' ||
+    typeof request.content !== 'string' ||
+    typeof request.context !== 'string'
+  ) {
+    throw new SignInError(
+      ERR_INVALID_REQUEST,
+      'signStatement requires { rpOrigin, content, context }',
+    );
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (hasExtension()) {
+    return await signStatementViaExtension(request, timeoutMs);
+  }
+  throw new SignInError(
+    ERR_NO_WALLET_INSTALLED,
+    'MATA extension not detected (native statement signing is a follow-up)',
+  );
+}
+
+/**
+ * Send the statement-sign request via the extension's `window.postMessage`
+ * bridge and await the wallet's response.
+ * @internal
+ */
+function signStatementViaExtension(request, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const requestId = generateRequestId();
+    let timeoutHandle = null;
+
+    const messageHandler = (event) => {
+      const data = event.data;
+      if (typeof data !== 'object' || data === null) return;
+      if (data[MESSAGE_DISCRIMINATOR] !== true) return;
+      if (data.kind !== KIND_STATEMENT_SIGN_RESPONSE) return;
+      if (data.request_id !== requestId) return;
+
+      window.removeEventListener('message', messageHandler);
+      if (timeoutHandle !== null) clearTimeout(timeoutHandle);
+
+      const result = data.result;
+      if (typeof result !== 'object' || result === null) {
+        reject(new SignInError(ERR_INTERNAL, 'malformed response from wallet'));
+        return;
+      }
+      if (result.outcome === 'ok') {
+        resolve({ token: result.token, surface: 'extension' });
+      } else if (result.outcome === 'denied') {
+        reject(new SignInError(ERR_USER_DENIED, 'user denied signing'));
+      } else if (result.outcome === 'error') {
+        reject(new SignInError(result.error_code ?? ERR_INTERNAL, result.message ?? ''));
+      } else {
+        reject(new SignInError(ERR_INTERNAL, `unknown outcome: ${result.outcome}`));
+      }
+    };
+
+    window.addEventListener('message', messageHandler);
+
+    const payload = {
+      [MESSAGE_DISCRIMINATOR]: true,
+      kind: KIND_STATEMENT_SIGN_REQUEST,
+      request_id: requestId,
+      rp_origin: request.rpOrigin,
+      context: request.context,
+      content: request.content,
+      content_type: request.contentType ?? 'text/plain',
+      nonce: request.nonce ?? null,
+    };
+    window.postMessage(payload, '*');
+
+    timeoutHandle = setTimeout(() => {
+      window.removeEventListener('message', messageHandler);
+      reject(new SignInError(ERR_TIMEOUT, `no response within ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+}
+
 // ─── Native app surface ────────────────────────────────────────────────────
 
 /**
@@ -477,19 +584,30 @@ function signInViaNativeApp(request, options, timeoutMs) {
     // app. If the page is still visible 1.5s after dispatching the
     // deep link AND no hash response has arrived, assume no app is
     // installed and reject with `no_wallet_installed`.
-    const NO_APP_DETECT_MS = 1500;
-    const noAppCheckHandle = setTimeout(() => {
-      if (document.visibilityState === 'visible') {
-        cleanup();
-        clearTimeout(noAppCheckHandle);
-        reject(
-          new SignInError(
-            ERR_NO_WALLET_INSTALLED,
-            'no MATA app responded to the deep link'
-          )
-        );
-      }
-    }, NO_APP_DETECT_MS);
+    //
+    // This heuristic is browser-only: it relies on the OS deep link
+    // backgrounding the tab. Inside a native host (a Dioxus/Tauri/wry/
+    // Electron webview that embeds this SDK), the page never loses
+    // visibility, so the check would false-positive on every call. Hosts
+    // that deliver the callback themselves — registering their own scheme
+    // and injecting the `#mid_response` fragment back into the webview —
+    // pass `options.nativeHost = true` to skip it and rely on the hard
+    // timeout instead.
+    let noAppCheckHandle = null;
+    if (!options.nativeHost) {
+      const NO_APP_DETECT_MS = 1500;
+      noAppCheckHandle = setTimeout(() => {
+        if (document.visibilityState === 'visible') {
+          cleanup();
+          reject(
+            new SignInError(
+              ERR_NO_WALLET_INSTALLED,
+              'no MATA app responded to the deep link'
+            )
+          );
+        }
+      }, NO_APP_DETECT_MS);
+    }
 
     // Hard timeout — user has the configured timeoutMs to complete.
     timeoutHandle = setTimeout(() => {