@matanetwork/sovereign-id 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,251 @@
+# @matanetwork/sovereign-id
+
+Page-side SDK for **MATA Sovereign ID** (mID) — the permissionless
+self-issued identity protocol.
+
+Drop one button into your sign-in page. Users authenticate with their
+own wallet (browser extension or native app). You get back a signed
+JWT carrying a stable DID + the claims they consented to disclose.
+No `client_id`, no portal account, no MAU pricing, no MATA HTTP
+traffic at runtime.
+
+## Install
+
+```bash
+npm install @matanetwork/sovereign-id
+```
+
+Pair with the backend verifier (separate package, same protocol):
+
+```bash
+npm install @matanetwork/sovereign-id-verify
+```
+
+## Quick start
+
+```javascript
+import { signIn, resumePendingSignIn, SignInError } from '@matanetwork/sovereign-id';
+
+// 1. On boot — resume an interrupted sign-in if one was stashed.
+//    Returns null when there's nothing pending; the normal page renders.
+resumePendingSignIn().then(handleResult);
+
+// 2. On sign-in button click — start a fresh request.
+document.getElementById('signin').addEventListener('click', async () => {
+  try {
+    const nonce = await fetch('/api/auth/nonce').then(r => r.text());
+    const result = await signIn({
+      rpOrigin: 'https://acme.com',
+      nonce,
+      claims: {
+        required: ['did'],
+        optional: ['email', 'name'],
+      },
+    });
+    handleResult(result);
+  } catch (err) {
+    if (err instanceof SignInError) handleSignInError(err);
+    else throw err;
+  }
+});
+
+async function handleResult(result) {
+  if (!result) return;  // resumePendingSignIn returned null — nothing to do.
+
+  // Hand the JWT to your backend for verification.
+  const resp = await fetch('/api/auth/mid', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ jwt: result.jwt }),
+  });
+  if (resp.ok) window.location.href = '/dashboard';
+}
+
+function handleSignInError(err) {
+  switch (err.code) {
+    case 'user_denied':       /* user clicked Deny on the consent screen */ break;
+    case 'upsell_canceled':   /* user dismissed the install upsell */ break;
+    case 'timeout':           /* user left the consent screen open too long */ break;
+    case 'origin_mismatch':   /* page lied about its origin (rare) */ break;
+    default: console.error(err.code, err.message);
+  }
+}
+```
+
+That's it. No back-channel `/token` exchange. No JWKS to refresh. The
+JWT is self-anchored — your backend verifies it entirely against
+cryptographic material embedded in the token.
+
+## API reference
+
+### `signIn(request, options?)`
+
+Probes for the MATA browser extension first; falls back to the
+`mata-mid://` native-app deep link. If neither responds, an install
+upsell modal opens (links to the Chrome Web Store, polls for the
+extension, auto-resumes once installed).
+
+#### `request` — required
+
+| Field | Type | Notes |
+|---|---|---|
+| `rpOrigin` | `string` | Your bare origin, e.g. `"https://acme.com"`. Becomes the JWT's `aud` claim. |
+| `nonce` | `string` | Single-use random string from your backend. Echoed in the JWT for replay defense. |
+| `claims.required` | `string[]` | Claim keys the user MUST approve. Almost always `["did"]`. Denial blocks sign-in. |
+| `claims.optional` | `string[]` | Claim keys the user can include or skip. |
+| `claims.custom` | `Record<string, {optional: true, description?: string}>` | Arbitrary keys from the user's `profile_kv` (v0: ignored by the wallet). |
+
+**Standard claim catalog (v1):** `did`, `email`, `name`, `created_at`,
+`paired_devices_count`, `level_rating.trust`, `level_rating.security`,
+`level_rating.incentive`.
+
+#### `options` — optional
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `timeoutMs` | `number` | `120000` | Hard request timeout. |
+| `nativeAppCallback` | `string` | `window.location.href` | URL the native app's callback redirects to. |
+| `installUpsell` | `boolean` | `true` | When `false`, `ERR_NO_WALLET_INSTALLED` is thrown raw instead of showing the modal. |
+| `ref` | `string \| null` | hostname of `rpOrigin` | Referral code stamped onto the upsell's outbound links. Default delivers attribution back to your domain. Pass `null` to opt out. |
+
+#### Returns
+
+`Promise<{ jwt: string, surface: 'extension' | 'native_app' }>`.
+
+#### Throws
+
+`SignInError` with `.code` one of:
+
+| Code | When |
+|---|---|
+| `user_denied` | User clicked Deny on the consent screen. |
+| `upsell_canceled` | User dismissed the install upsell ("Cancel" or Escape). |
+| `no_wallet_installed` | Only when `installUpsell: false`. Neither extension nor native app responded. |
+| `invalid_request` | Your code passed a malformed request (caught on the page). |
+| `origin_mismatch` | Page-claimed origin didn't match the actual tab origin. Possible page bug or attack. |
+| `wallet_unavailable` | Vault locked, wallet not bootstrapped, or no matching credential. |
+| `required_claim_unavailable` | User signed up without an email but you required it. |
+| `timeout` | User didn't decide within `timeoutMs`. |
+| `internal_error` | Anything else. |
+
+### `resumePendingSignIn()`
+
+Call once at app boot. Resumes a sign-in that was interrupted by a
+page reload during the install upsell.
+
+| Returns | When |
+|---|---|
+| `{ jwt, surface }` | A pending request was stashed, the extension is now installed, and the resumed sign-in completed. |
+| `null` | No pending request, or the stash is stale, or the extension is still missing. |
+| `throws SignInError` | A pending request exists and the extension is present, but the resumed sign-in itself failed. |
+
+The stash lives in `sessionStorage` (per-tab, cleared on tab close).
+TTL = the original request's `timeoutMs`. Stale entries are silently
+dropped on read.
+
+### `hasExtension()`
+
+Returns `true` when `window.__mata_mid__` (set by the extension's
+content script) is present. Useful for conditionally rendering the
+sign-in button vs. an install prompt before the user has clicked.
+
+> **Race-condition note.** The content script runs at `document_idle`.
+> RPs calling `signIn()` synchronously from `<head>` may probe before
+> the script is injected. Call after `DOMContentLoaded` (or after a
+> user gesture) to avoid the false negative.
+
+### `showInstallUpsell(options)`
+
+Exposed for RPs who set `installUpsell: false` and want to render the
+upsell on their own conditions (e.g. after their own UI flow). Same
+modal `signIn()` uses internally; same `'installed' | 'canceled'`
+result shape.
+
+### `pickInstallCta()` / `defaultRefFromOrigin(origin)`
+
+Helpers for RPs building their own install upsell UI:
+
+- `pickInstallCta()` returns the right `{label, url, hint}` for the
+  current browser/OS.
+- `defaultRefFromOrigin('https://acme.com')` returns `'acme.com'` — the
+  referral code the SDK would stamp by default.
+
+### `clearPendingSignIn()`
+
+Imperatively drops the resume stash. Use when you've navigated to a
+different sign-in flow that supersedes the pending mID request.
+
+### `SignInError`
+
+```typescript
+class SignInError extends Error {
+  readonly code: ErrorCode;
+}
+```
+
+## Referral attribution
+
+Both outbound links in the install upsell modal carry `?ref=<code>` by
+default — your domain becomes the attribution code without any extra
+wiring. The signup flow at my.mata.network reads `?ref=` and forwards
+it through to your downstream analytics as `referral_code`.
+
+Customize:
+
+```javascript
+signIn(request, { ref: 'acme-launch-2026' });  // custom code
+signIn(request, { ref: null });                // opt out
+```
+
+## What you don't have to think about
+
+- **No `client_id`, `client_secret`, redirect URI allowlist.** There's no registration step.
+- **No `/token` back-channel exchange.** The JWT comes back from `signIn()` directly.
+- **No JWKS endpoint refresh.** The JWT bundles its own resolution data.
+- **No DID-resolver HTTP calls.** The DID is its own public key.
+- **No MAU pricing.** No metering of any kind.
+
+## Verification on the backend
+
+Use [@matanetwork/sovereign-id-verify](https://npmjs.com/package/@matanetwork/sovereign-id-verify):
+
+```javascript
+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),
+});
+
+// verified.did            — stable user identifier
+// verified.claims         — disclosed values
+// verified.currentVersion — head roster version; cache for rollback detection
+```
+
+## Browser support
+
+| Browser | Sign-in path |
+|---|---|
+| Chrome / Edge / Brave / Arc / Opera | Extension or native-app deep link |
+| Safari | Native-app deep link (extension coming) |
+| Firefox | Native-app deep link (extension coming) |
+| Mobile Chrome / Safari | Native-app deep link (apps coming) |
+
+When no compatible surface is available, the install upsell modal
+surfaces the right CTA per browser/OS automatically.
+
+## Accessibility
+
+The install upsell modal:
+
+- Renders in a closed Shadow DOM (RP CSS can't break or skin it).
+- Traps Tab / Shift+Tab focus inside the modal.
+- Restores focus to the element that was focused before opening.
+- Closes on Escape and on backdrop click.
+- Shows `:focus-visible` outlines for keyboard users.
+- Uses `role="dialog"` + `aria-modal="true"` + `aria-labelledby`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@matanetwork/sovereign-id",
+  "version": "0.1.0",
+  "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",
+  "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",
+    "sovereign-id",
+    "mid",
+    "sso",
+    "identity",
+    "did",
+    "self-sovereign",
+    "passwordless",
+    "did-mata",
+    "permissionless-auth"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://github.com/mata-network/mata/tree/main/packages/mata-sovereign-id-sdk#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-sdk"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,216 @@
+/**
+ * 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;