@matanetwork/sovereign-id-react 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,242 @@
+# @matanetwork/sovereign-id-react
+
+React adapter for [`@matanetwork/sovereign-id`](https://www.npmjs.com/package/@matanetwork/sovereign-id).
+Drop in a `<SignInButton/>`, get a signed JWT carrying a verified
+DID + the user's consented claims.
+
+Lowers your integration from ~20 LOC + manual state plumbing to one
+component or one hook.
+
+## Install
+
+```bash
+npm install @matanetwork/sovereign-id-react @matanetwork/sovereign-id react
+```
+
+`react` is a peer dependency — works with React 17, 18, and 19.
+
+For the backend verifier, also install [`@matanetwork/sovereign-id-verify`](https://www.npmjs.com/package/@matanetwork/sovereign-id-verify).
+
+## Quick start — drop-in button
+
+```jsx
+import { SignInButton } from '@matanetwork/sovereign-id-react';
+
+function LoginPage() {
+  return (
+    <SignInButton
+      getNonce={() => fetch('/api/auth/nonce').then((r) => r.text())}
+      claims={{ required: ['did'], optional: ['email', 'name'] }}
+      onSuccess={({ jwt }) =>
+        fetch('/api/auth/mid', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ jwt }),
+        }).then(() => (window.location.href = '/dashboard'))
+      }
+      onCancel={(code) => console.log('user cancelled:', code)}
+      onError={(err) => console.error(err.code, err.message)}
+    />
+  );
+}
+```
+
+That's it. The button:
+
+- Fetches a nonce from your backend
+- Probes for the MATA extension → falls back to the native-app deep
+  link → falls back to the install upsell modal
+- Resolves the user's consent decision
+- Hands you `{ jwt, surface }` on success
+
+## Hook — custom button styling
+
+When you want full control over the rendered button:
+
+```jsx
+import { useSignIn } from '@matanetwork/sovereign-id-react';
+
+function LoginPage() {
+  const { signIn, isLoading, error } = useSignIn({
+    rpOrigin: 'https://acme.com',
+    getNonce: () => fetch('/api/auth/nonce').then((r) => r.text()),
+    defaultClaims: { required: ['did'], optional: ['email'] },
+  });
+
+  return (
+    <>
+      <button
+        onClick={async () => {
+          try {
+            const { jwt } = await signIn();
+            await fetch('/api/auth/mid', {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ jwt }),
+            });
+            window.location.href = '/dashboard';
+          } catch {
+            /* useSignIn already mirrors the error into `error` */
+          }
+        }}
+        disabled={isLoading}
+        className="my-styled-button"
+      >
+        {isLoading ? 'Signing in…' : 'Sign in with MATA'}
+      </button>
+      {error && <p role="alert">{error.message}</p>}
+    </>
+  );
+}
+```
+
+`useSignIn` returns `{ signIn, reset, status, isLoading, result, error }`.
+Status is `'idle' | 'pending' | 'success' | 'error'`.
+
+## Resume after page reload
+
+The install upsell flow stashes a pending sign-in in `sessionStorage`
+so it survives a reload (common when Chrome prompts the user to
+reload after extension install). Wire the resume at the root of your
+app:
+
+```jsx
+import { useResumePendingSignIn } from '@matanetwork/sovereign-id-react';
+
+function App() {
+  useResumePendingSignIn({
+    onSuccess: ({ jwt }) => {
+      fetch('/api/auth/mid', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ jwt }),
+      }).then(() => (window.location.href = '/dashboard'));
+    },
+  });
+
+  return <Routes>{/* ... */}</Routes>;
+}
+```
+
+The hook fires once on mount, looks for a stashed pending sign-in,
+and invokes `onSuccess` if one resumes. If you want to delay
+rendering your logged-out UI until the resume check completes (avoids
+a flicker), watch the `noResume` flag:
+
+```jsx
+const { noResume, status } = useResumePendingSignIn({ onSuccess });
+if (status === 'pending') return <Spinner />;
+// noResume === true once we've confirmed nothing was pending
+```
+
+## API
+
+### `<SignInButton/>`
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `getNonce` | `() => Promise<string>` | yes | Async fn returning a fresh single-use nonce. |
+| `claims` | `{ required, optional?, custom? }` | yes | Standard SDK claim shape. |
+| `onSuccess` | `(result) => void` | yes | Called with `{ jwt, surface }`. |
+| `onCancel` | `(code) => void` | no | Called on `user_denied` or `upsell_canceled`. |
+| `onError` | `(err: SignInError) => void` | no | Called on any other failure path. |
+| `rpOrigin` | `string` | no | Default: `window.location.origin`. |
+| `installUpsell` | `boolean` | no | Default: SDK default (`true`). |
+| `ref` | `string \| null` | no | Referral code. Default: hostname of `rpOrigin`. |
+| `timeoutMs` | `number` | no | Default: 120000. |
+| `nativeAppCallback` | `string` | no | Default: `window.location.href`. |
+| `children` | `ReactNode` | no | Button label. Default: `"Sign in with Sovereign ID"`. |
+| `className` | `string` | no | When set, default inline styles are NOT applied. |
+| `style` | `CSSProperties` | no | Merged with default inline styles when `className` is unset. |
+| `disabled` | `boolean` | no | OR'd with the internal in-flight disabled state. |
+| `buttonProps` | `object` | no | Spread onto the `<button>` (aria-*, data-*, etc.). |
+
+### `useSignIn(options?)`
+
+| Option | Type | Notes |
+|---|---|---|
+| `rpOrigin` | `string` | Default: `window.location.origin`. |
+| `getNonce` | `() => Promise<string>` | Required unless you pass `nonce` to every `signIn()` call directly. |
+| `defaultClaims` | `claims` | Default `claims` payload. |
+| `installUpsell`, `ref`, `timeoutMs`, `nativeAppCallback` | — | Forwarded to the SDK. |
+
+Returns:
+
+```ts
+{
+  signIn(overrides?): Promise<{ jwt, surface } | null>;
+  reset(): void;
+  status: 'idle' | 'pending' | 'success' | 'error';
+  isLoading: boolean;
+  result: { jwt, surface } | null;
+  error: SignInError | null;
+}
+```
+
+The hook protects against stale calls — if you click sign-in twice
+in a row, only the most recent call's result commits to state.
+
+### `useResumePendingSignIn(options?)`
+
+| Option | Type | Notes |
+|---|---|---|
+| `onSuccess` | `(result) => void` | Called when a resume completes with a JWT. |
+| `onError` | `(err) => void` | Called when a resume threw. |
+| `onNothingPending` | `() => void` | Called when there's nothing to resume — most boots. |
+
+Returns:
+
+```ts
+{
+  status: 'idle' | 'pending' | 'success' | 'error';
+  result: { jwt, surface } | null;
+  error: SignInError | null;
+  noResume: boolean;
+}
+```
+
+### Re-exports from the core SDK
+
+For convenience, this package re-exports everything from
+`@matanetwork/sovereign-id` so you only need one import line:
+
+```js
+import {
+  SignInError,
+  ERR_USER_DENIED,
+  ERR_UPSELL_CANCELED,
+  hasExtension,
+  defaultRefFromOrigin,
+  // ...
+} from '@matanetwork/sovereign-id-react';
+```
+
+## Backend
+
+Same as the core SDK — use [`@matanetwork/sovereign-id-verify`](https://www.npmjs.com/package/@matanetwork/sovereign-id-verify):
+
+```js
+import { verifyResponse } from '@matanetwork/sovereign-id-verify';
+
+const verified = await verifyResponse(req.body.jwt, {
+  expectedAudience: 'https://acme.com',
+  expectedNonce: sessionNonce,
+  nowUnixSecs: Math.floor(Date.now() / 1000),
+});
+```
+
+See the
+[main docs](https://github.com/mata-network/mata/tree/main/docs/sovereign-id)
+for the integration guide, error-handling matrix, and protocol spec.
+
+## What you don't have to think about
+
+- Wallet detection (extension vs. native app vs. install upsell)
+- Resume after page reload
+- Referral attribution (your domain rides along to `my.mata.network/signup` by default)
+- Stale-call state collisions
+- React 18 strict-mode double-mount during boot resume
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@matanetwork/sovereign-id-react",
+  "version": "0.1.0",
+  "description": "React adapter for @matanetwork/sovereign-id — drop-in <SignInButton/>, useSignIn() hook, useResumePendingSignIn() boot helper. Lowers Sovereign ID RP integration from ~20 LOC to one import.",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "test": "node --test tests/index.test.js",
+    "prepublishOnly": "node --test tests/index.test.js"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mata",
+    "matanetwork",
+    "sovereign-id",
+    "mid",
+    "react",
+    "react-hook",
+    "sso",
+    "identity",
+    "did",
+    "did-mata",
+    "permissionless-auth",
+    "self-sovereign"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://github.com/mata-network/mata/tree/main/packages/mata-sovereign-id-react#readme",
+  "bugs": {
+    "url": "https://github.com/mata-network/mata/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mata-network/mata.git",
+    "directory": "packages/mata-sovereign-id-react"
+  },
+  "peerDependencies": {
+    "@matanetwork/sovereign-id": "^0.1.0",
+    "react": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": false
+    },
+    "@matanetwork/sovereign-id": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@matanetwork/sovereign-id": "^0.1.0",
+    "react": "^18.3.1"
+  }
+}

package/src/SignInButton.js

@@ -0,0 +1,169 @@
+/**
+ * `<SignInButton/>` — drop-in React button that runs the full
+ * Sovereign ID sign-in flow on click.
+ *
+ * RPs that just want a working button drop this in and pass an
+ * `onSuccess` callback that hands the JWT to their backend. Custom
+ * styling via `className` / `style` / `children`. RPs that need more
+ * control over the click handler should use `useSignIn()` directly.
+ *
+ * ## Rendering note (no JSX)
+ *
+ * Authored with `React.createElement` so this package can ship as
+ * pure ESM with no build step. Bundlers (Vite / Webpack / esbuild)
+ * still tree-shake, type-check, etc. — they just don't have to
+ * transpile JSX. Keeps the package single-file-readable and zero-
+ * configure.
+ *
+ * ## What clicking does
+ *
+ * 1. Sets internal `loading` state.
+ * 2. Resolves the nonce via `getNonce` (required prop).
+ * 3. Calls the SDK's `signIn({ rpOrigin, nonce, claims })`.
+ * 4. On success, calls `onSuccess({ jwt, surface })`.
+ * 5. On `user_denied` / `upsell_canceled`, calls `onCancel(code)`.
+ * 6. On any other failure, calls `onError(err)`.
+ * 7. Resets loading state and re-enables the button.
+ *
+ * The button is `disabled` for the duration of step 1-6 so duplicate
+ * clicks are no-ops.
+ */
+
+import { createElement } from 'react';
+import { SignInError } from '@matanetwork/sovereign-id';
+import { useSignIn } from './useSignIn.js';
+
+const DEFAULT_LABEL = 'Sign in with Sovereign ID';
+
+const DEFAULT_BUTTON_STYLE = {
+  // Match the popup CSS palette so the button feels at-home next to
+  // the consent screen that opens after the click.
+  background: '#4b2ad5',
+  color: '#fff',
+  border: 'none',
+  borderRadius: '8px',
+  padding: '10px 18px',
+  font: 'inherit',
+  fontSize: '14px',
+  fontWeight: 600,
+  cursor: 'pointer',
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: '8px',
+  lineHeight: 1.3,
+  transition: 'background 0.12s ease',
+};
+
+const DEFAULT_BUTTON_STYLE_DISABLED = {
+  ...DEFAULT_BUTTON_STYLE,
+  opacity: 0.6,
+  cursor: 'not-allowed',
+};
+
+/**
+ * @param {object} props
+ * @param {string} [props.rpOrigin] - Defaults to `window.location.origin`.
+ * @param {() => Promise<string>} props.getNonce - Async fn returning a
+ *     fresh single-use nonce from your backend. Required.
+ * @param {object} props.claims - Claim catalog. `{ required: [...],
+ *     optional?: [...], custom?: {...} }`. Required.
+ * @param {(result: {jwt: string, surface: 'extension' | 'native_app'}) => void} props.onSuccess
+ *     Called with the resulting JWT.
+ * @param {(code: 'user_denied' | 'upsell_canceled') => void} [props.onCancel]
+ *     Called when the user explicitly chose not to sign in.
+ * @param {(err: SignInError) => void} [props.onError]
+ *     Called for any other failure path (timeout, wallet_unavailable,
+ *     etc.). If omitted, errors are silently swallowed — RPs should
+ *     usually pass at least a logger here.
+ * @param {boolean} [props.installUpsell] - SDK option pass-through.
+ * @param {string | null} [props.ref] - SDK referral code; defaults
+ *     to the hostname of `rpOrigin`.
+ * @param {number} [props.timeoutMs] - SDK option pass-through.
+ * @param {string} [props.nativeAppCallback] - SDK option pass-through.
+ * @param {React.ReactNode} [props.children] - Button label. Defaults
+ *     to `"Sign in with Sovereign ID"`.
+ * @param {string} [props.className] - When set, the default styles
+ *     are NOT applied (assume the RP has full control via CSS).
+ * @param {React.CSSProperties} [props.style] - Merged with the
+ *     default inline styles when `className` is not provided.
+ * @param {boolean} [props.disabled] - Explicitly disable the button.
+ *     The button is also disabled internally while a sign-in is in
+ *     flight; this prop is OR'd with that.
+ * @param {object} [props.buttonProps] - Spread onto the underlying
+ *     `<button>` for things like `aria-*`, `data-*`, etc.
+ */
+export function SignInButton(props) {
+  const {
+    rpOrigin,
+    getNonce,
+    claims,
+    onSuccess,
+    onCancel,
+    onError,
+    installUpsell,
+    ref,
+    timeoutMs,
+    nativeAppCallback,
+    children,
+    className,
+    style,
+    disabled = false,
+    buttonProps = {},
+  } = props;
+
+  const { signIn, isLoading } = useSignIn({
+    rpOrigin,
+    getNonce,
+    defaultClaims: claims,
+    installUpsell,
+    ref,
+    timeoutMs,
+    nativeAppCallback,
+  });
+
+  const isDisabled = disabled || isLoading;
+
+  const handleClick = async () => {
+    if (isDisabled) return;
+    try {
+      const result = await signIn();
+      if (result && typeof onSuccess === 'function') {
+        onSuccess(result);
+      }
+    } catch (err) {
+      if (err instanceof SignInError) {
+        if (
+          (err.code === 'user_denied' || err.code === 'upsell_canceled') &&
+          typeof onCancel === 'function'
+        ) {
+          onCancel(err.code);
+          return;
+        }
+      }
+      if (typeof onError === 'function') {
+        onError(err);
+      }
+    }
+  };
+
+  // When `className` is provided, defer fully to caller CSS — don't
+  // apply the default inline styles at all. When not, ship a sensible
+  // styled button and let `style` override fields one at a time.
+  const resolvedStyle = className
+    ? style
+    : { ...(isDisabled ? DEFAULT_BUTTON_STYLE_DISABLED : DEFAULT_BUTTON_STYLE), ...style };
+
+  return createElement(
+    'button',
+    {
+      type: 'button',
+      onClick: handleClick,
+      disabled: isDisabled,
+      'aria-busy': isLoading || undefined,
+      className,
+      style: resolvedStyle,
+      ...buttonProps,
+    },
+    children ?? DEFAULT_LABEL
+  );
+}

package/src/index.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Type declarations for @matanetwork/sovereign-id-react.
+ *
+ * Mirrors the JS runtime exactly. The runtime is pure JS (no build
+ * step); this `.d.ts` exists so consumers using TypeScript get full
+ * type-checking + IDE intellisense.
+ */
+
+import type { CSSProperties, ReactNode, ButtonHTMLAttributes } from 'react';
+import type {
+  SignInError,
+  SignInRequest,
+  SignInSuccess,
+  ErrorCode,
+} from '@matanetwork/sovereign-id';
+
+// ─── Hook: useSignIn ───────────────────────────────────────────────────────
+
+export interface UseSignInOptions {
+  /**
+   * Default `rpOrigin` used by `signIn()`. If omitted, falls back to
+   * `window.location.origin`. RPs running SSR should set this
+   * explicitly.
+   */
+  rpOrigin?: string;
+
+  /**
+   * Async function that returns a fresh single-use nonce. Called
+   * once per `signIn()` invocation; the resolved string is passed
+   * through to the SDK. If omitted, `signIn()` must be called with
+   * a `nonce` override directly.
+   */
+  getNonce?: () => Promise<string>;
+
+  /**
+   * Default `claims` payload, merged with the per-call override.
+   * Almost always `{ required: ['did'], optional: [...] }`.
+   */
+  defaultClaims?: SignInRequest['claims'];
+
+  /**
+   * Forwarded to the SDK. When `false`, throws
+   * `ERR_NO_WALLET_INSTALLED` raw instead of showing the install
+   * upsell. Default: SDK default (`true`).
+   */
+  installUpsell?: boolean;
+
+  /**
+   * Forwarded to the SDK. Referral code attributed to signups that
+   * flow through the install upsell. Defaults to the hostname of
+   * `rpOrigin`. Pass `null` to opt out.
+   */
+  ref?: string | null;
+
+  /** Forwarded to the SDK. */
+  timeoutMs?: number;
+
+  /** Forwarded to the SDK. */
+  nativeAppCallback?: string;
+}
+
+export type SignInStatus = 'idle' | 'pending' | 'success' | 'error';
+
+export interface SignInOverrides {
+  rpOrigin?: string;
+  nonce?: string;
+  claims?: SignInRequest['claims'];
+  installUpsell?: boolean;
+  ref?: string | null;
+  timeoutMs?: number;
+  nativeAppCallback?: string;
+}
+
+export interface UseSignInReturn {
+  /**
+   * Fires a sign-in. Merges `overrides` over the hook-level
+   * options. Resolves to the result on success, `null` if the call
+   * was superseded by a newer signIn, or rejects with `SignInError`
+   * on failure.
+   */
+  signIn(overrides?: SignInOverrides): Promise<SignInSuccess | null>;
+  /** Drops result/error and returns to idle. */
+  reset(): void;
+  status: SignInStatus;
+  /** True iff `status === 'pending'`. */
+  isLoading: boolean;
+  result: SignInSuccess | null;
+  error: SignInError | null;
+}
+
+export function useSignIn(options?: UseSignInOptions): UseSignInReturn;
+
+// ─── Hook: useResumePendingSignIn ──────────────────────────────────────────
+
+export interface UseResumeOptions {
+  /**
+   * Called when a pending sign-in resumes and completes. RPs hand
+   * the JWT to their backend here.
+   */
+  onSuccess?: (result: SignInSuccess) => void;
+  /**
+   * Called when a pending sign-in was found but its resume threw.
+   * `err.code` is the same set the regular signIn() throws.
+   */
+  onError?: (err: SignInError) => void;
+  /**
+   * Called when there's no pending resume — most boots. Lets RPs
+   * record analytics on "did we hit the resume path on this boot"
+   * without watching the `noResume` flag.
+   */
+  onNothingPending?: () => void;
+}
+
+export interface UseResumeReturn {
+  status: SignInStatus;
+  result: SignInSuccess | null;
+  error: SignInError | null;
+  /**
+   * `true` once we've finished checking and confirmed no pending
+   * sign-in was waiting. Useful for RPs that want to delay
+   * rendering their logged-out UI until the resume check is done.
+   */
+  noResume: boolean;
+}
+
+export function useResumePendingSignIn(options?: UseResumeOptions): UseResumeReturn;
+
+// ─── Component: SignInButton ───────────────────────────────────────────────
+
+export interface SignInButtonProps {
+  /** Defaults to `window.location.origin`. */
+  rpOrigin?: string;
+  /** Async fn returning a fresh single-use nonce from your backend. */
+  getNonce: () => Promise<string>;
+  /** Claim catalog. `{ required: [...], optional?: [...] }`. */
+  claims: SignInRequest['claims'];
+  /** Called with the resulting JWT. */
+  onSuccess: (result: SignInSuccess) => void;
+  /**
+   * Called when the user explicitly chose not to sign in
+   * (`user_denied` from the consent screen, `upsell_canceled` from
+   * the install upsell modal).
+   */
+  onCancel?: (code: 'user_denied' | 'upsell_canceled') => void;
+  /**
+   * Called for any other failure path (timeout, wallet_unavailable,
+   * etc.). If omitted, errors are silently swallowed — RPs should
+   * usually pass at least a logger here.
+   */
+  onError?: (err: SignInError) => void;
+  /** SDK option pass-through. */
+  installUpsell?: boolean;
+  /** SDK referral code; defaults to the hostname of `rpOrigin`. */
+  ref?: string | null;
+  /** SDK option pass-through. */
+  timeoutMs?: number;
+  /** SDK option pass-through. */
+  nativeAppCallback?: string;
+  /** Button label. Defaults to `"Sign in with Sovereign ID"`. */
+  children?: ReactNode;
+  /**
+   * When set, the default inline styles are NOT applied; the RP has
+   * full control via CSS.
+   */
+  className?: string;
+  /**
+   * Merged with the default inline styles when `className` is not
+   * provided.
+   */
+  style?: CSSProperties;
+  /**
+   * Explicitly disable the button. The button is also disabled
+   * internally while a sign-in is in flight.
+   */
+  disabled?: boolean;
+  /** Spread onto the underlying `<button>`. */
+  buttonProps?: Omit<
+    ButtonHTMLAttributes<HTMLButtonElement>,
+    'onClick' | 'disabled' | 'type' | 'style' | 'className' | 'children'
+  >;
+}
+
+export function SignInButton(props: SignInButtonProps): JSX.Element;
+
+// ─── Re-exports from @matanetwork/sovereign-id ────────────────────────────
+
+export {
+  SignInError,
+  hasExtension,
+  showInstallUpsell,
+  pickInstallCta,
+  defaultRefFromOrigin,
+  clearPendingSignIn,
+  resumePendingSignIn,
+  signIn,
+  PROTOCOL_VERSION,
+  WINDOW_MID_GLOBAL,
+  MESSAGE_DISCRIMINATOR,
+  KIND_SIGN_IN_REQUEST,
+  KIND_SIGN_IN_RESPONSE,
+  URL_SCHEME,
+  SCHEME_PATH_REQUEST,
+  QUERY_PARAM_PAYLOAD,
+  FRAGMENT_KEY_RESPONSE,
+  ERR_USER_DENIED,
+  ERR_ORIGIN_MISMATCH,
+  ERR_INVALID_REQUEST,
+  ERR_WALLET_UNAVAILABLE,
+  ERR_REQUIRED_CLAIM_UNAVAILABLE,
+  ERR_INTERNAL,
+  ERR_NO_WALLET_INSTALLED,
+  ERR_TIMEOUT,
+  ERR_UPSELL_CANCELED,
+} from '@matanetwork/sovereign-id';
+
+export type {
+  SignInRequest,
+  SignInSuccess,
+  ErrorCode,
+  CustomClaim,
+  InstallCta,
+  InstallUpsellOptions,
+  InstallUpsellResult,
+  SignInOptions,
+} from '@matanetwork/sovereign-id';

package/src/index.js

@@ -0,0 +1,56 @@
+/**
+ * @matanetwork/sovereign-id-react — React adapter for the
+ * `@matanetwork/sovereign-id` SDK.
+ *
+ * Three entry points:
+ *
+ *  - [`<SignInButton/>`](./SignInButton.js) — drop-in styled button.
+ *    Three required props: `getNonce`, `claims`, `onSuccess`.
+ *
+ *  - [`useSignIn`](./useSignIn.js) — hook for RPs that want their
+ *    own button. Returns `{ signIn, status, isLoading, result, error,
+ *    reset }`.
+ *
+ *  - [`useResumePendingSignIn`](./useResumePendingSignIn.js) — boot-
+ *    time hook. Call once at the root of your app to handle the
+ *    resume-after-reload path that the install upsell sets up.
+ *
+ * Everything else (`SignInError`, error codes, `defaultRefFromOrigin`,
+ * etc.) is re-exported from `@matanetwork/sovereign-id` so RPs only
+ * need one import line.
+ */
+
+export { SignInButton } from './SignInButton.js';
+export { useSignIn } from './useSignIn.js';
+export { useResumePendingSignIn } from './useResumePendingSignIn.js';
+
+// Re-export the core SDK surface so RPs don't have to install both
+// packages just to type their callbacks against `SignInError`.
+export {
+  SignInError,
+  hasExtension,
+  showInstallUpsell,
+  pickInstallCta,
+  defaultRefFromOrigin,
+  clearPendingSignIn,
+  resumePendingSignIn,
+  signIn,
+  PROTOCOL_VERSION,
+  WINDOW_MID_GLOBAL,
+  MESSAGE_DISCRIMINATOR,
+  KIND_SIGN_IN_REQUEST,
+  KIND_SIGN_IN_RESPONSE,
+  URL_SCHEME,
+  SCHEME_PATH_REQUEST,
+  QUERY_PARAM_PAYLOAD,
+  FRAGMENT_KEY_RESPONSE,
+  ERR_USER_DENIED,
+  ERR_ORIGIN_MISMATCH,
+  ERR_INVALID_REQUEST,
+  ERR_WALLET_UNAVAILABLE,
+  ERR_REQUIRED_CLAIM_UNAVAILABLE,
+  ERR_INTERNAL,
+  ERR_NO_WALLET_INSTALLED,
+  ERR_TIMEOUT,
+  ERR_UPSELL_CANCELED,
+} from '@matanetwork/sovereign-id';

package/src/useResumePendingSignIn.js

@@ -0,0 +1,148 @@
+/**
+ * `useResumePendingSignIn` — React hook around
+ * `resumePendingSignIn()`.
+ *
+ * Call once at the root of your app. The hook fires
+ * `resumePendingSignIn()` on first mount, manages the resolution
+ * state, and invokes `onSuccess` / `onError` (if provided) when the
+ * resume completes.
+ *
+ * ## What it solves
+ *
+ * The install-upsell flow stashes a pending sign-in in
+ * `sessionStorage` so it survives a page reload (common when Chrome
+ * prompts the user to reload after extension install). On the next
+ * boot, the SDK's `resumePendingSignIn()` picks the flow back up. RPs
+ * that want this resume path need to call it explicitly — this hook
+ * makes that "drop it in App.jsx and forget" simple.
+ *
+ * ## Idempotent at boot
+ *
+ * Internally guards with a ref so React 18's strict-mode
+ * double-invoke doesn't fire two parallel resume calls. Whichever
+ * one wins commits; the other's result is dropped.
+ *
+ * ## Status reporting
+ *
+ * Exposes the same `status` shape as `useSignIn` so RPs that mount
+ * loading UI can share the rendering branch:
+ *
+ *   - `idle` — hook hasn't started checking yet (one paint at most).
+ *   - `pending` — `resumePendingSignIn()` is in flight.
+ *   - `success` — a resume returned a JWT. Result is in `.result`.
+ *   - `error` — a resume found a pending request and the SDK threw
+ *     while completing it. Error is in `.error`.
+ *   - `idle` (with `noResume: true`) — explicitly: no pending
+ *     resume was found.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+import {
+  resumePendingSignIn as sdkResume,
+  SignInError,
+} from '@matanetwork/sovereign-id';
+
+/**
+ * @typedef {object} UseResumeOptions
+ * @property {(result: {jwt: string, surface: 'extension' | 'native_app'}) => void} [onSuccess]
+ *     Called when a pending sign-in resumes and completes. RPs hand
+ *     the JWT to their backend here.
+ * @property {(err: SignInError) => void} [onError]
+ *     Called when a pending sign-in was found but its resume threw.
+ *     `err.code` is the same set the regular signIn() throws.
+ * @property {() => void} [onNothingPending]
+ *     Called when there's no pending resume — most boots. Lets RPs
+ *     telemetry "did we hit the resume path on this boot" without
+ *     watching the `noResume` flag.
+ */
+
+/**
+ * @typedef {object} UseResumeReturn
+ * @property {'idle' | 'pending' | 'success' | 'error'} status
+ * @property {{jwt: string, surface: 'extension' | 'native_app'} | null} result
+ * @property {SignInError | null} error
+ * @property {boolean} noResume
+ *     `true` once we've finished checking and confirmed no pending
+ *     sign-in was waiting. Useful for RPs that want to delay
+ *     rendering their logged-out UI until the resume check is done
+ *     (avoids a flicker through the logged-out state when the
+ *     resume succeeds).
+ */
+
+/**
+ * @param {UseResumeOptions} [options]
+ * @returns {UseResumeReturn}
+ */
+export function useResumePendingSignIn(options = {}) {
+  const [state, setState] = useState({
+    status: 'idle',
+    result: null,
+    error: null,
+    noResume: false,
+  });
+
+  // Guard against React 18 strict-mode double-mount. The first mount
+  // fires the resume; the dev-mode second mount is a no-op.
+  const hasStartedRef = useRef(false);
+
+  // Keep callbacks in a ref so the boot effect doesn't need to
+  // re-fire when the parent re-renders with new inline callbacks.
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+
+  useEffect(() => {
+    if (hasStartedRef.current) return;
+    hasStartedRef.current = true;
+
+    let cancelled = false;
+    setState((s) => ({ ...s, status: 'pending' }));
+
+    (async () => {
+      try {
+        const result = await sdkResume();
+        if (cancelled) return;
+        if (result) {
+          setState({
+            status: 'success',
+            result,
+            error: null,
+            noResume: false,
+          });
+          optionsRef.current.onSuccess?.(result);
+        } else {
+          setState({
+            status: 'idle',
+            result: null,
+            error: null,
+            noResume: true,
+          });
+          optionsRef.current.onNothingPending?.();
+        }
+      } catch (e) {
+        if (cancelled) return;
+        const err =
+          e instanceof SignInError
+            ? e
+            : new SignInError(
+                'internal_error',
+                `useResumePendingSignIn: unexpected error: ${e?.message ?? e}`
+              );
+        setState({
+          status: 'error',
+          result: null,
+          error: err,
+          noResume: false,
+        });
+        optionsRef.current.onError?.(err);
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  return state;
+}

package/src/useSignIn.js

@@ -0,0 +1,222 @@
+/**
+ * `useSignIn` — React hook around `@matanetwork/sovereign-id`'s `signIn`.
+ *
+ * Manages the full state machine of a sign-in attempt: idle → pending
+ * → (success | error). Exposes `signIn(extraRequest)` for the click
+ * handler, `reset()` for a clean retry, and the current status fields
+ * for rendering.
+ *
+ * Use this when you want full control over the button / link that
+ * triggers sign-in. If you just want a drop-in button, use
+ * `<SignInButton/>` from the same package.
+ *
+ * ## State machine
+ *
+ *   idle ──signIn()──▶ pending ──┬──▶ success  (result populated)
+ *                                └──▶ error    (error populated)
+ *
+ * Any of those terminal states can transition back to `idle` via
+ * `reset()` or to `pending` again via a fresh `signIn()` call.
+ *
+ * ## Why a hook (not a one-shot helper)
+ *
+ * Sign-in is async, the UI needs to reflect three distinct phases
+ * (idle / pending / done), and the result drives downstream effects
+ * (call `/api/auth/mid`, set session, navigate). A hook is the
+ * idiomatic React shape for "stateful async operation."
+ *
+ * ## Stale-call protection
+ *
+ * If a component re-renders mid-flight or the user clicks the button
+ * twice in a row, only the **most recent** signIn() call resolves into
+ * state. Earlier calls' results are dropped (their promises still
+ * resolve, but their setStates are gated by a request-id check). This
+ * prevents a slow first call from clobbering a fast second call's
+ * result — common bug class for naive async hooks.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { signIn as sdkSignIn, SignInError } from '@matanetwork/sovereign-id';
+
+/**
+ * @typedef {object} UseSignInOptions
+ * @property {string} [rpOrigin] - Default `rpOrigin` used by `signIn()`.
+ *     If omitted, falls back to `window.location.origin`. RPs running
+ *     SSR should set this explicitly.
+ * @property {() => Promise<string>} [getNonce] - Async function that
+ *     returns a fresh single-use nonce. Called once per `signIn()`
+ *     invocation; the resolved string is passed through to the SDK.
+ *     If omitted, `signIn()` must be called with a `nonce` directly.
+ * @property {object} [defaultClaims] - Default `claims` payload, merged
+ *     with the per-call override.
+ * @property {boolean} [installUpsell] - Forwarded to the SDK.
+ * @property {string | null} [ref] - Forwarded to the SDK. See the
+ *     `defaultRefFromOrigin` docs for the auto-derive behavior.
+ * @property {number} [timeoutMs] - Forwarded to the SDK.
+ * @property {string} [nativeAppCallback] - Forwarded to the SDK.
+ */
+
+/**
+ * @typedef {object} UseSignInState
+ * @property {'idle' | 'pending' | 'success' | 'error'} status
+ * @property {boolean} isLoading - True iff `status === 'pending'`.
+ * @property {{jwt: string, surface: 'extension' | 'native_app'} | null} result
+ * @property {SignInError | null} error
+ */
+
+/**
+ * @typedef {object} UseSignInReturn
+ * @property {(overrides?: object) => Promise<{jwt: string, surface: 'extension' | 'native_app'} | null>} signIn
+ *     Fires a sign-in. Merges `overrides` over the hook-level options;
+ *     `overrides.nonce` overrides `getNonce()`. Resolves to the result
+ *     on success, `null` if the call was superseded by a newer signIn,
+ *     or rejects with `SignInError` on failure.
+ * @property {() => void} reset - Drops result/error and returns to idle.
+ * @property {'idle' | 'pending' | 'success' | 'error'} status
+ * @property {boolean} isLoading
+ * @property {{jwt: string, surface: 'extension' | 'native_app'} | null} result
+ * @property {SignInError | null} error
+ */
+
+/**
+ * @param {UseSignInOptions} [options]
+ * @returns {UseSignInReturn}
+ */
+export function useSignIn(options = {}) {
+  const [state, setState] = useState({
+    status: 'idle',
+    result: null,
+    error: null,
+  });
+
+  // Stale-call protection: every signIn() bumps this counter; the
+  // resulting promise only commits its outcome to state if it matches
+  // the latest counter value at resolve time. Stops a slow first call
+  // from overwriting a fast second call.
+  const currentRequestIdRef = useRef(0);
+
+  // Mount-tracking so we don't `setState` after unmount (React 18
+  // tolerates it, but it still logs a warning). The ref is set by the
+  // cleanup function returned from useEffect.
+  const isMountedRef = useRef(true);
+  useEffect(
+    () => () => {
+      isMountedRef.current = false;
+    },
+    []
+  );
+
+  // Refs over options so the `signIn` callback doesn't have to be
+  // recreated every render when the caller passes inline objects.
+  // Stable reference → safe to use as a dep in the caller's own
+  // useEffect/useMemo.
+  const optionsRef = useRef(options);
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+
+  const signIn = useCallback(async (overrides = {}) => {
+    const myRequestId = ++currentRequestIdRef.current;
+    setState({ status: 'pending', result: null, error: null });
+
+    const opts = optionsRef.current;
+
+    // Resolve nonce: caller override > hook-level getNonce().
+    let nonce = overrides.nonce;
+    if (typeof nonce !== 'string' || nonce.length === 0) {
+      if (typeof opts.getNonce !== 'function') {
+        const err = new SignInError(
+          'invalid_request',
+          'useSignIn: no nonce provided and no `getNonce` configured.'
+        );
+        // Commit only if still latest.
+        if (
+          currentRequestIdRef.current === myRequestId &&
+          isMountedRef.current
+        ) {
+          setState({ status: 'error', result: null, error: err });
+        }
+        throw err;
+      }
+      try {
+        nonce = await opts.getNonce();
+      } catch (e) {
+        const err =
+          e instanceof SignInError
+            ? e
+            : new SignInError(
+                'invalid_request',
+                `useSignIn: getNonce() threw: ${e?.message ?? e}`
+              );
+        if (
+          currentRequestIdRef.current === myRequestId &&
+          isMountedRef.current
+        ) {
+          setState({ status: 'error', result: null, error: err });
+        }
+        throw err;
+      }
+    }
+
+    // Resolve rpOrigin.
+    const rpOrigin =
+      overrides.rpOrigin ??
+      opts.rpOrigin ??
+      (typeof window !== 'undefined' ? window.location.origin : undefined);
+
+    // Resolve claims. Caller-level overrides win field-by-field.
+    const claims = overrides.claims ??
+      opts.defaultClaims ?? { required: ['did'] };
+
+    const request = { rpOrigin, nonce, claims };
+
+    const sdkOpts = {
+      installUpsell:
+        overrides.installUpsell ?? opts.installUpsell ?? undefined,
+      ref: overrides.ref ?? opts.ref,
+      timeoutMs: overrides.timeoutMs ?? opts.timeoutMs ?? undefined,
+      nativeAppCallback:
+        overrides.nativeAppCallback ?? opts.nativeAppCallback ?? undefined,
+    };
+
+    try {
+      const result = await sdkSignIn(request, sdkOpts);
+      if (
+        currentRequestIdRef.current === myRequestId &&
+        isMountedRef.current
+      ) {
+        setState({ status: 'success', result, error: null });
+      }
+      return result;
+    } catch (e) {
+      const err =
+        e instanceof SignInError
+          ? e
+          : new SignInError(
+              'internal_error',
+              `useSignIn: unexpected error: ${e?.message ?? e}`
+            );
+      if (
+        currentRequestIdRef.current === myRequestId &&
+        isMountedRef.current
+      ) {
+        setState({ status: 'error', result: null, error: err });
+      }
+      throw err;
+    }
+  }, []);
+
+  const reset = useCallback(() => {
+    currentRequestIdRef.current++;
+    setState({ status: 'idle', result: null, error: null });
+  }, []);
+
+  return {
+    signIn,
+    reset,
+    status: state.status,
+    isLoading: state.status === 'pending',
+    result: state.result,
+    error: state.error,
+  };
+}