@sparkvault/sdk 1.0.0 → 1.1.5

package/README.md

@@ -1,6 +1,6 @@
 # SparkVault JavaScript SDK
 
-A unified JavaScript SDK for SparkVault services: Identity verification, encrypted Sparks, secure Vaults, and cryptographic RNG.
+The official SparkVault JavaScript SDK for browser applications. Add passwordless authentication to your app in minutes with zero-config integration or full programmatic control.
 
 [![npm version](https://img.shields.io/npm/v/@sparkvault/sdk.svg)](https://www.npmjs.com/package/@sparkvault/sdk)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -8,627 +8,699 @@ A unified JavaScript SDK for SparkVault services: Identity verification, encrypt
 ## Table of Contents
 
 - [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Architecture](#architecture)
-- [Modules](#modules)
-  - [Identity](#identity)
-  - [Sparks](#sparks)
-  - [Vaults](#vaults)
-  - [RNG](#rng)
-- [Configuration](#configuration)
+- [Zero-Config Integration](#zero-config-integration)
+- [Manual Initialization](#manual-initialization)
+- [Identity Verification](#identity-verification)
+- [Backend Token Verification](#backend-token-verification)
+- [React Integration](#react-integration)
 - [Error Handling](#error-handling)
-- [TypeScript](#typescript)
-- [Security](#security)
+- [TypeScript Support](#typescript-support)
+- [Browser Support](#browser-support)
 - [Development](#development)
 - [License](#license)
 
 ## Installation
 
-### CDN (Browser)
+### CDN (Recommended)
 
-Include the SDK directly in your HTML. This is the recommended approach for most web applications.
+```html
+<script src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"></script>
+```
 
-#### Zero-Config Auto-Init (Recommended)
+### npm / yarn
 
-The simplest way to add SparkVault authentication to your site:
+```bash
+npm install @sparkvault/sdk
+# or
+yarn add @sparkvault/sdk
+```
+
+**Bundle Formats:**
+- `sparkvault.js` — UMD bundle for browsers (recommended)
+- `sparkvault.esm.js` — ES modules for modern bundlers
+- `sparkvault.cjs.js` — CommonJS for Node.js
+
+## Zero-Config Integration
+
+Add SparkVault authentication to your site with a single script tag — no JavaScript required!
 
 ```html
+<!-- Add this single script tag -->
 <script
   async
   src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
-  data-account-id="acc_your_account"
-  data-attach-selector=".js-sparkvault-auth"
-  data-success-url="https://example.com/auth/verify-token"
-  data-debug="true"
+  data-account-id="acc_YOUR_ACCOUNT_ID"
+  data-attach-selector=".login-btn"
+  data-success-url="/auth/verify-token"
 ></script>
 
-<button class="js-sparkvault-auth">Login with SparkVault</button>
+<!-- Any element matching the selector becomes a login button -->
+<button class="login-btn">Sign In</button>
+<a href="#" class="login-btn">Create Account</a>
 ```
 
 That's it! The SDK automatically:
 - Initializes with your account ID
-- Attaches click handlers to matching elements
-- Opens the verification modal on click
+- Attaches click handlers to all matching elements
+- Opens the verification modal when clicked
 - POSTs the result to your success URL
+- Watches for dynamically added elements (MutationObserver)
 
-#### Auto-Init Data Attributes
-
-| Attribute | Description |
-|-----------|-------------|
-| `data-account-id` | Your SparkVault account ID (required for auto-init) |
-| `data-attach-selector` | CSS selector for elements to attach click handlers |
-| `data-success-url` | URL to POST `{ token, identity, identityType }` on success |
-| `data-success-function` | Global function name to call on success (e.g., `"handleAuth"` or `"MyApp.auth.onSuccess"`) |
-| `data-error-url` | URL to redirect to on error (appends `?error=message`) |
-| `data-error-function` | Global function name to call on error |
-| `data-debug` | Set to `"true"` for verbose console logging |
+### Data Attributes
 
-#### Success Handling
+| Attribute | Required | Description |
+|-----------|----------|-------------|
+| `data-account-id` | Yes | Your SparkVault account ID (required for auto-init) |
+| `data-attach-selector` | No | CSS selector for elements to attach click handlers |
+| `data-success-url` | No | URL to POST `{ token, identity, identityType }` on success |
+| `data-success-function` | No | Global function name to call on success (e.g., `"MyApp.auth.onSuccess"`) |
+| `data-error-url` | No | URL to redirect on error (appends `?error=message`) |
+| `data-error-function` | No | Global function name to call on error |
+| `data-preload-config` | No | Set to `"false"` to defer config loading. Default: true |
+| `data-timeout` | No | Request timeout in milliseconds. Default: 30000 |
+| `data-debug` | No | Set to `"true"` for verbose console logging |
 
-When verification succeeds, the SDK can call a function and/or POST to a URL:
+### Complete Example
 
 ```html
-<!-- Call a function -->
+<script
+  async
+  src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
+  data-account-id="acc_YOUR_ACCOUNT_ID"
+  data-attach-selector=".js-sparkvault-auth"
+  data-success-url="https://example.com/auth/verify-token"
+  data-success-function="onSparkVaultSuccess"
+  data-error-function="onSparkVaultError"
+  data-debug="true"
+></script>
+
 <script>
-  function handleSparkVaultAuth(result) {
+  // Optional: Define callback functions
+  function onSparkVaultSuccess(result) {
     console.log('Verified:', result.identity);
     console.log('Token:', result.token);
-    // Your logic here...
+    // The SDK will also POST to data-success-url
+  }
+
+  function onSparkVaultError(error) {
+    console.error('Error:', error.message);
+    alert('Authentication failed. Please try again.');
   }
 </script>
-<script
-  src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
-  data-account-id="acc_your_account"
-  data-attach-selector=".login-btn"
-  data-success-function="handleSparkVaultAuth"
-></script>
 
-<!-- POST to your backend -->
-<script
-  src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
-  data-account-id="acc_your_account"
-  data-attach-selector=".login-btn"
-  data-success-url="/auth/verify-sparkvault-token"
-></script>
+<!-- Multiple elements can use the same selector -->
+<button class="js-sparkvault-auth">Sign In</button>
+<a href="#" class="js-sparkvault-auth">Login with SparkVault</a>
 ```
 
-When POSTing to `data-success-url`, the SDK sends:
+### Success URL Response
+
+When you specify `data-success-url`, the SDK POSTs the verification result:
+
 ```json
 {
-  "token": "eyJ...",
+  "token": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9...",
   "identity": "user@example.com",
   "identityType": "email"
 }
 ```
 
-Your backend can respond with:
-```json
-{ "redirectUrl": "/dashboard" }  // SDK redirects to this URL
-{ "reload": true }               // SDK reloads the page
-```
+Your backend can respond with redirect instructions:
 
-#### Manual Initialization
+```javascript
+// Option 1: Redirect to a URL
+{ "redirectUrl": "/dashboard" }
+// or
+{ "redirect_url": "/dashboard" }
 
-For more control, initialize the SDK manually:
+// Option 2: Reload the current page
+{ "reload": true }
 
-```html
-<script src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"></script>
-<script>
-  const sv = SparkVault.init({
-    accountId: 'acc_your_account'
-  });
-
-  // Trigger verification popup manually
-  document.getElementById('login-btn').addEventListener('click', async () => {
-    const result = await sv.identity.pop();
-    // Handle result...
-  });
-</script>
+// Option 3: Return data (no automatic action)
+{ "success": true, "user": { "id": 123, "email": "user@example.com" } }
 ```
 
-#### Available CDN Files
+### Manual Trigger from JavaScript
 
-| File | Description |
-|------|-------------|
-| `sparkvault.js` | Minified UMD bundle (recommended) |
-| `sparkvault.esm.js` | ES module bundle |
-| `sparkvault.cjs.js` | CommonJS bundle |
+You can also trigger authentication programmatically using the `SparkVault` global:
 
-### npm
+```javascript
+// Trigger authentication from anywhere in your code
+SparkVault.identity.pop();
 
-```bash
-npm install @sparkvault/sdk
+// This uses your configured success/error handlers
 ```
 
-```javascript
-// ES Modules
-import { SparkVault } from '@sparkvault/sdk';
-
-// CommonJS
-const { SparkVault } = require('@sparkvault/sdk');
+```html
+<button onclick="SparkVault.identity.pop()">
+  Sign In with SparkVault
+</button>
 ```
 
-## Quick Start
+## Manual Initialization
+
+For full control over the SDK, initialize it manually in JavaScript:
 
 ```javascript
-// Initialize the SDK
-const sv = SparkVault.init({
-  accountId: 'acc_your_account'
-});
+import SparkVault from '@sparkvault/sdk';
 
-// Identity - Open verification popup
-const result = await sv.identity.pop({
-  email: 'user@example.com'
+const sparkvault = SparkVault.init({
+  accountId: 'acc_YOUR_ACCOUNT_ID'  // Required
 });
 
-// The token is a single-use verification proof - send it to YOUR backend
-await fetch('/api/auth/login', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ token: result.token })
-});
-// Your backend verifies the token, then creates YOUR session
+// The SDK is now ready to use
+const result = await sparkvault.identity.pop();
 ```
 
-## Architecture
-
-The SparkVault SDK follows a Stripe.js-like architecture:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                     Your Application                         │
-├─────────────────────────────────────────────────────────────┤
-│                    SparkVault SDK                            │
-│  ┌─────────────┬─────────────┬─────────────┬─────────────┐  │
-│  │  Identity   │   Sparks    │   Vaults    │     RNG     │  │
-│  │   Module    │   Module    │   Module    │   Module    │  │
-│  └─────────────┴─────────────┴─────────────┴─────────────┘  │
-│                          │                                   │
-│                    HTTP Client                               │
-├─────────────────────────────────────────────────────────────┤
-│                 api.sparkvault.com                           │
-└─────────────────────────────────────────────────────────────┘
-```
+### Configuration Options
 
-### Identity Popup Flow
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `accountId` | `string` | **required** | Your SparkVault account ID (starts with `acc_`) |
+| `timeout` | `number` | `30000` | HTTP request timeout in milliseconds |
+| `preloadConfig` | `boolean` | `true` | Preload Identity config for instant modal |
 
-The Identity module uses a secure popup window for authentication:
+### CDN Usage
 
-1. **SDK opens popup** → `api.sparkvault.com/apps/identity/{account_id}/embed`
-2. **User authenticates** → Passkey, TOTP, Magic Link, or Social OAuth
-3. **Popup posts result** → `postMessage` with signed JWT token
-4. **SDK validates origin** → Ensures message is from SparkVault
-5. **Promise resolves** → Returns verified user info and token
+```html
+<script src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"></script>
+<script>
+  const sparkvault = SparkVault.init({
+    accountId: 'acc_YOUR_ACCOUNT_ID'
+  });
 
+  document.getElementById('login-btn').addEventListener('click', async () => {
+    const result = await sparkvault.identity.pop();
+    console.log('Verified:', result.identity);
+  });
+</script>
 ```
-┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
-│ Your App     │     │   SDK Popup      │     │  SparkVault  │
-│              │     │                  │     │   Identity   │
-├──────────────┤     ├──────────────────┤     ├──────────────┤
-│ sv.identity  │────>│ Opens popup      │     │              │
-│ .pop()       │     │ window           │────>│ /embed page  │
-│              │     │                  │     │              │
-│              │     │ User selects     │     │ Auth methods │
-│              │     │ auth method      │<────│ displayed    │
-│              │     │                  │     │              │
-│              │     │ User completes   │────>│ Verify       │
-│              │     │ authentication   │     │ credentials  │
-│              │     │                  │     │              │
-│ Promise      │<────│ postMessage      │<────│ Sign JWT     │
-│ resolves     │     │ with token       │     │ token        │
-└──────────────┘     └──────────────────┘     └──────────────┘
-```
-
-## Modules
 
-### Identity
+## Identity Verification
 
-Verify user identity through passkey, TOTP, magic link, or social authentication.
+The Identity module provides passwordless authentication through a beautiful, customizable modal. Users can verify via passkeys, email codes, SMS codes, magic links, or social providers.
 
-The SDK provides two methods:
-- **`pop()`** — Opens a modal popup (most common)
-- **`render()`** — Embeds UI inline in your page
+### Basic Usage
 
 ```javascript
-// Open popup modal
-const result = await sv.identity.pop();
-
-// With options
-const result = await sv.identity.pop({
-  email: 'user@example.com',        // Pre-fill email
-  methods: ['passkey', 'totp_email', 'magic_link'],  // Filter methods
-  theme: 'dark',                    // 'light', 'dark', or 'auto' (system preference)
-  backdropBlur: true,               // Enable backdrop blur effect (default: true)
-  locale: 'en',                     // UI language
-  onSuccess: (result) => {},        // Success callback
-  onCancel: () => {},               // User cancelled
-  onError: (error) => {}            // Error callback
-});
-
-// Result structure
-console.log(result.token);          // Signed JWT
-console.log(result.identity);       // Verified identity (email or phone)
-console.log(result.identityType);   // 'email' or 'phone'
-```
+// Open the verification modal
+const result = await sparkvault.identity.pop();
 
-#### Inline Rendering
+// User verified!
+console.log(result.identity);      // "user@example.com" or "+14155551234"
+console.log(result.identityType);  // "email" or "phone"
+console.log(result.token);         // Signed JWT token
 
-For cases where you want to embed the authentication UI directly in your page instead of a popup modal, use `render()`:
-
-```javascript
-// Render inline in a container element
-const result = await sv.identity.render({
-  target: document.getElementById('auth-container'),
-  email: 'user@example.com'
-});
-
-// Embed in your own dialog without SparkVault header/footer
-const result = await sv.identity.render({
-  target: dialogContentElement,
-  showHeader: false,
-  showFooter: false
-});
-
-// Minimal - just the auth flow, no chrome
-const result = await sv.identity.render({
-  target: myElement,
-  showHeader: false,
-  showCloseButton: false,
-  showFooter: false
+// Send the token to your backend for verification
+await fetch('/api/auth/login', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ token: result.token })
 });
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `target` | `HTMLElement` | **required** | Element to render the auth UI into |
-| `showHeader` | `boolean` | `true` | Show header with branding |
-| `showCloseButton` | `boolean` | `true` | Show close button in header |
-| `showFooter` | `boolean` | `true` | Show "Secured by SparkVault" footer |
-
-All other options from `pop()` are also supported (`email`, `phone`, `onSuccess`, etc.).
+### pop() Options
 
-#### Supported Authentication Methods
+| Option | Type | Description |
+|--------|------|-------------|
+| `email` | `string` | Pre-fill email address (mutually exclusive with phone) |
+| `phone` | `string` | Pre-fill phone in E.164 format, e.g. `"+14155551234"` |
+| `backdropBlur` | `boolean` | Override backdrop blur setting from app config |
+| `onCancel` | `function` | Callback when user closes modal without verifying |
+| `onSuccess` | `function` | Callback on success (before promise resolves) |
+| `onError` | `function` | Callback on error (before promise rejects) |
 
-| Method | Description |
-|--------|-------------|
-| `passkey` | WebAuthn/FIDO2 passkey authentication |
-| `totp_email` | Time-based OTP sent via email |
-| `totp_sms` | Time-based OTP sent via SMS |
-| `magic_link` | One-click email verification link |
-| `google` | Google OAuth |
-| `apple` | Apple Sign In |
-| `microsoft` | Microsoft OAuth |
-| `github` | GitHub OAuth |
+### pop() Result
 
-#### Appearance Options
+| Field | Type | Description |
+|-------|------|-------------|
+| `token` | `string` | Signed JWT token (Ed25519). Verify this on your backend. |
+| `identity` | `string` | The verified email address or phone number |
+| `identityType` | `"email" \| "phone"` | Type of identity that was verified |
 
-The Identity popup supports theming and visual effects:
+### Example with Options
 
 ```javascript
-// Dark mode
-await sv.identity.pop({
-  theme: 'dark'
-});
-
-// Light mode
-await sv.identity.pop({
-  theme: 'light'
-});
-
-// Auto (follows system preference)
-await sv.identity.pop({
-  theme: 'auto'
-});
+try {
+  const result = await sparkvault.identity.pop({
+    // Pre-fill the email field
+    email: 'user@example.com',
+
+    // Handle cancellation
+    onCancel: () => {
+      console.log('User cancelled');
+    }
+  });
 
-// Disable backdrop blur (enabled by default)
-await sv.identity.pop({
-  backdropBlur: false
-});
+  // Success! Send token to your backend
+  await loginWithToken(result.token);
 
-// Combine options
-await sv.identity.pop({
-  email: 'user@example.com',
-  theme: 'dark',
-  backdropBlur: true
-});
+} catch (error) {
+  if (error.code === 'user_cancelled') {
+    // User closed the modal
+  } else {
+    // Handle other errors
+    console.error('Verification failed:', error.message);
+  }
+}
 ```
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `theme` | `'light' \| 'dark' \| 'auto'` | Tenant default | UI color theme. `'auto'` follows system preference. |
-| `backdropBlur` | `boolean` | `true` | Apply blur effect to the page behind the popup. |
+### Authentication Methods
 
-#### Token Verification
+Authentication methods are configured in your Identity App settings. The SDK automatically shows only the methods you have enabled.
 
-```javascript
-// Verify a token (validates expiration and issuer)
-const claims = await sv.identity.verifyToken(token);
-console.log(claims.identity);        // Verified email or phone
-console.log(claims.identity_type);   // 'email' or 'phone'
-console.log(claims.method);          // Auth method used
-console.log(claims.verified_at);     // Verification timestamp
-console.log(claims.exp);             // Expiration timestamp
-```
+| Method | Description | Identity Type |
+|--------|-------------|---------------|
+| `passkey` | WebAuthn/FIDO2 biometric or security key | Email |
+| `totp_email` | 6-digit code sent via email | Email |
+| `totp_sms` | 6-digit code sent via SMS | Phone |
+| `totp_voice` | 6-digit code sent via voice call | Phone |
+| `magic_link` / `sparklink` | One-click magic link via email | Email |
+| `google` | Sign in with Google | Email |
+| `apple` | Sign in with Apple | Email |
+| `microsoft` | Sign in with Microsoft | Email |
+| `github` | Sign in with GitHub | Email |
+| `facebook` | Sign in with Facebook | Email |
+| `linkedin` | Sign in with LinkedIn | Email |
+
+## Backend Token Verification
 
-### Sparks
+> **Security Critical:** Always verify tokens on your backend. Never trust the frontend result alone. Tokens are signed with Ed25519 — use the JWKS endpoint to verify the signature.
 
-Create and read ephemeral encrypted secrets that burn on read.
+### Node.js
 
 ```javascript
-// Create a spark
-const spark = await sv.sparks.create({
-  payload: 'secret data',           // String or binary data
-  ttl: 3600,                        // Time-to-live in seconds (default: 3600)
-  maxReads: 1,                      // Max reads before burn (default: 1)
-  password: 'optional-password'     // Optional password protection
-});
+import * as jose from 'jose';
 
-console.log(spark.id);              // Spark ID
-console.log(spark.url);             // Direct shareable URL
-console.log(spark.expiresAt);       // Expiration timestamp
-console.log(spark.maxReads);        // Remaining reads
+const ACCOUNT_ID = 'acc_YOUR_ACCOUNT_ID';
+const IDENTITY_URL = 'https://api.sparkvault.com/v1/apps/identity';
 
-// Read a spark (burns it)
-const data = await sv.sparks.read(sparkId);
-// or
-const data = await sv.sparks.read(sparkId, 'password');
+app.post('/api/auth/login', async (req, res) => {
+  const { token } = req.body;
 
-console.log(data.payload);          // Decrypted payload
-console.log(data.burned);           // true if this was the last read
-```
+  try {
+    // Fetch public keys and verify signature
+    const jwksUrl = `${IDENTITY_URL}/${ACCOUNT_ID}/.well-known/jwks.json`;
+    const JWKS = jose.createRemoteJWKSet(new URL(jwksUrl));
 
-### Vaults
+    const { payload } = await jose.jwtVerify(token, JWKS, {
+      issuer: `${IDENTITY_URL}/${ACCOUNT_ID}`,
+      audience: ACCOUNT_ID
+    });
 
-Create and manage encrypted vaults with persistent storage for files (Ingots).
+    // Token is valid! Create user session
+    const user = await findOrCreateUser(payload.identity, payload.identity_type);
+    req.session.userId = user.id;
 
-```javascript
-// Create a vault
-const vault = await sv.vaults.create({
-  name: 'My Vault'
+    res.json({ success: true, user });
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid token' });
+  }
 });
+```
 
-console.log(vault.id);              // Vault ID
-console.log(vault.name);            // Vault name
-console.log(vault.vmk);             // Vault Master Key (24 chars) - SAVE THIS!
-console.log(vault.createdAt);       // Creation timestamp
+### Python
 
-// List vaults
-const vaults = await sv.vaults.list();
+```python
+import jwt
+from jwt import PyJWKClient
 
-// Unseal a vault (required before accessing ingots)
-const unsealed = await sv.vaults.unseal(vaultId, vmk);
-console.log(unsealed.vatToken);     // Vault Access Token
-console.log(unsealed.expiresAt);    // Token expiration
+ACCOUNT_ID = 'acc_YOUR_ACCOUNT_ID'
+IDENTITY_URL = 'https://api.sparkvault.com/v1/apps/identity'
 
-// Upload a file (ingot)
-const ingot = await sv.vaults.uploadIngot(unsealed, {
-  file: fileObject,                 // File or Blob
-  name: 'document.pdf'              // Display name
-});
+def verify_identity_token(token: str):
+    """Verify a SparkVault Identity token and return the claims."""
+    jwks_url = f"{IDENTITY_URL}/{ACCOUNT_ID}/.well-known/jwks.json"
+    jwks_client = PyJWKClient(jwks_url)
 
-console.log(ingot.id);              // Ingot ID
-console.log(ingot.name);            // File name
-console.log(ingot.size);            // File size in bytes
-console.log(ingot.mimeType);        // MIME type
+    # Get the signing key
+    signing_key = jwks_client.get_signing_key_from_jwt(token)
 
-// List ingots
-const ingots = await sv.vaults.listIngots(unsealed);
+    # Verify and decode
+    claims = jwt.decode(
+        token,
+        signing_key.key,
+        algorithms=["EdDSA"],
+        issuer=f"{IDENTITY_URL}/{ACCOUNT_ID}",
+        audience=ACCOUNT_ID
+    )
 
-// Download an ingot
-const blob = await sv.vaults.downloadIngot(unsealed, ingotId);
-
-// Delete an ingot
-await sv.vaults.deleteIngot(unsealed, ingotId);
-```
+    return claims
 
-### RNG
+# Usage in Flask
+@app.route('/api/auth/login', methods=['POST'])
+def login():
+    token = request.json.get('token')
 
-Generate cryptographically secure random numbers using hybrid entropy (KMS + local).
+    try:
+        claims = verify_identity_token(token)
 
-```javascript
-// Generate random bytes
-const result = await sv.rng.generate({
-  bytes: 32,                        // 1-1024 bytes
-  format: 'hex'                     // Output format
-});
+        # Create session
+        user = find_or_create_user(claims['identity'], claims['identity_type'])
+        session['user_id'] = user.id
 
-console.log(result.value);          // Random value in requested format
-console.log(result.bytes);          // Number of bytes generated
-console.log(result.format);         // Format used
-
-// Available formats
-// 'hex'          - Hexadecimal string
-// 'base64'       - Base64 encoded
-// 'base64url'    - URL-safe Base64
-// 'bytes'        - Raw Uint8Array
-// 'alphanumeric' - Alphanumeric string
-// 'numeric'      - Numeric string
-// 'uuid'         - UUID v4 format
-// 'password'     - Password-safe characters
-
-// Convenience methods
-const uuid = await sv.rng.uuid();           // UUID v4
-const password = await sv.rng.password(16); // 16-char password
+        return jsonify({'success': True, 'user': user.to_dict()})
+    except jwt.InvalidTokenError as e:
+        return jsonify({'error': 'Invalid token'}), 401
 ```
 
-## Configuration
+### Go
+
+```go
+package main
+
+import (
+    "github.com/lestrrat-go/jwx/v2/jwk"
+    "github.com/lestrrat-go/jwx/v2/jwt"
+)
+
+const (
+    AccountID   = "acc_YOUR_ACCOUNT_ID"
+    IdentityURL = "https://api.sparkvault.com/v1/apps/identity"
+)
+
+func verifyToken(tokenString string) (jwt.Token, error) {
+    jwksURL := fmt.Sprintf("%s/%s/.well-known/jwks.json", IdentityURL, AccountID)
+
+    // Fetch JWKS
+    keySet, err := jwk.Fetch(context.Background(), jwksURL)
+    if err != nil {
+        return nil, err
+    }
+
+    // Parse and verify token
+    token, err := jwt.Parse(
+        []byte(tokenString),
+        jwt.WithKeySet(keySet),
+        jwt.WithIssuer(fmt.Sprintf("%s/%s", IdentityURL, AccountID)),
+        jwt.WithAudience(AccountID),
+    )
+    if err != nil {
+        return nil, err
+    }
+
+    return token, nil
+}
 
-```javascript
-const sv = SparkVault.init({
-  // Required
-  accountId: 'acc_your_account',    // Your SparkVault account ID
-
-  // Optional
-  locale: 'en',                      // Default UI locale
-  timeout: 30000,                    // Request timeout in ms (default: 30000)
-  preloadConfig: true                // Preload Identity config on init (default: true)
-});
+// Usage in HTTP handler
+func loginHandler(w http.ResponseWriter, r *http.Request) {
+    var body struct {
+        Token string `json:"token"`
+    }
+    json.NewDecoder(r.Body).Decode(&body)
+
+    token, err := verifyToken(body.Token)
+    if err != nil {
+        http.Error(w, "Invalid token", http.StatusUnauthorized)
+        return
+    }
+
+    identity, _ := token.Get("identity")
+    // Create session with identity...
+}
 ```
 
-### Configuration Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `accountId` | `string` | **required** | Your SparkVault account ID (starts with `acc_`) |
-| `locale` | `string` | `'en'` | Default UI locale for the Identity modal |
-| `timeout` | `number` | `30000` | Request timeout in milliseconds |
-| `preloadConfig` | `boolean` | `true` | Preload Identity configuration on SDK init |
-
-### Config Preloading
+### Ruby
+
+```ruby
+require 'jwt'
+require 'net/http'
+require 'json'
+
+ACCOUNT_ID = 'acc_YOUR_ACCOUNT_ID'
+IDENTITY_URL = 'https://api.sparkvault.com/v1/apps/identity'
+
+def verify_identity_token(token)
+  jwks_url = "#{IDENTITY_URL}/#{ACCOUNT_ID}/.well-known/jwks.json"
+
+  # Fetch JWKS
+  uri = URI(jwks_url)
+  response = Net::HTTP.get(uri)
+  jwks = JSON.parse(response)
+
+  # Decode and verify
+  JWT.decode(
+    token,
+    nil,
+    true,
+    {
+      algorithms: ['EdDSA'],
+      iss: "#{IDENTITY_URL}/#{ACCOUNT_ID}",
+      aud: ACCOUNT_ID,
+      verify_iss: true,
+      verify_aud: true,
+      jwks: jwks
+    }
+  ).first
+end
+
+# Usage in Rails controller
+class AuthController < ApplicationController
+  def login
+    claims = verify_identity_token(params[:token])
+
+    user = User.find_or_create_by(email: claims['identity'])
+    session[:user_id] = user.id
+
+    render json: { success: true, user: user }
+  rescue JWT::DecodeError => e
+    render json: { error: 'Invalid token' }, status: :unauthorized
+  end
+end
+```
 
-By default, the SDK preloads your Identity configuration in the background when `SparkVault.init()` is called. This means when the user clicks your "Sign In" button and you call `pop()`, the modal opens **instantly** without a loading spinner.
+### Token Claims
 
-```javascript
-// Default behavior (preloadConfig: true)
-// Config is fetched immediately when SDK initializes
-const sv = SparkVault.init({ accountId: 'acc_xxx' });
+When decoded, the JWT token contains these claims:
 
-// Later, when user clicks "Sign In"...
-await sv.identity.pop();  // Opens instantly - config already loaded!
+```json
+{
+  "iss": "https://api.sparkvault.com/v1/apps/identity/acc_xxx",
+  "sub": "identity:a1b2c3d4e5f67890",
+  "aud": "acc_xxx",
+  "identity": "user@example.com",
+  "identity_type": "email",
+  "method": "totp_email",
+  "verified_at": 1703977195,
+  "iat": 1703977200,
+  "exp": 1703980800,
+  "jti": "tok_unique_id"
+}
 ```
 
-If you want to defer config loading until `pop()` is called (the legacy behavior), disable preloading:
-
-```javascript
-// Disable preloading - config loads when pop() is called
-const sv = SparkVault.init({
-  accountId: 'acc_xxx',
-  preloadConfig: false
+| Claim | Type | Description |
+|-------|------|-------------|
+| `iss` | `string` | Issuer URL — always verify this matches expected value |
+| `sub` | `string` | Subject — hashed identity for consistent user identification |
+| `aud` | `string` | Audience — your account ID |
+| `identity` | `string` | The verified email address or phone number |
+| `identity_type` | `string` | `"email"` or `"phone"` |
+| `method` | `string` | Authentication method used (e.g., `"totp_email"`, `"passkey"`) |
+| `verified_at` | `number` | Unix timestamp when identity was verified |
+| `iat` | `number` | Issued at timestamp |
+| `exp` | `number` | Expiration timestamp |
+| `jti` | `string` | Unique token ID for replay protection |
+
+## React Integration
+
+```jsx
+import { useState, useCallback } from 'react';
+import SparkVault from '@sparkvault/sdk';
+
+// Initialize once, outside component
+const sparkvault = SparkVault.init({
+  accountId: 'acc_YOUR_ACCOUNT_ID'
 });
 
-// Config loads on-demand with a brief loading spinner
-await sv.identity.pop();
-```
+function useSparkVaultAuth() {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+
+  const login = useCallback(async (options = {}) => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      // Open verification modal
+      const result = await sparkvault.identity.pop(options);
+
+      // Send token to backend
+      const response = await fetch('/api/auth/login', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ token: result.token })
+      });
+
+      if (!response.ok) throw new Error('Login failed');
+
+      const data = await response.json();
+      setUser(data.user);
+      return data.user;
+
+    } catch (err) {
+      if (err.code !== 'user_cancelled') {
+        setError(err.message);
+      }
+      throw err;
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  const logout = useCallback(async () => {
+    await fetch('/api/auth/logout', { method: 'POST' });
+    setUser(null);
+  }, []);
+
+  return { user, loading, error, login, logout };
+}
 
-### Environments
+// Usage in component
+function LoginPage() {
+  const { user, loading, error, login, logout } = useSparkVaultAuth();
+
+  if (user) {
+    return (
+      <div>
+        <p>Welcome, {user.email}!</p>
+        <button onClick={logout}>Sign out</button>
+      </div>
+    );
+  }
 
-| Environment | API Base URL | Use Case |
-|-------------|--------------|----------|
-| `production` | `https://api.sparkvault.com` | Live applications |
-| `sandbox` | `https://sandbox.api.sparkvault.com` | Testing and development |
+  return (
+    <div>
+      <button onClick={() => login()} disabled={loading}>
+        {loading ? 'Verifying...' : 'Sign in'}
+      </button>
+      {error && <p className="error">{error}</p>}
+    </div>
+  );
+}
+```
 
 ## Error Handling
 
-The SDK provides typed errors for different failure scenarios:
+The SDK throws typed errors that you can catch and handle appropriately.
 
 ```javascript
-import {
-  SparkVaultError,      // Base error class
-  ValidationError,       // Invalid input (400)
-  AuthenticationError,   // Not authenticated (401)
-  AuthorizationError,    // Not authorized (403)
-  NetworkError,          // Network failure
-  TimeoutError,          // Request timeout
-  PopupBlockedError,     // Popup was blocked
-  UserCancelledError     // User closed popup
+import SparkVault, {
+  UserCancelledError,
+  ValidationError,
+  NetworkError,
+  TimeoutError
 } from '@sparkvault/sdk';
 
 try {
-  await sv.identity.pop();
+  const result = await sparkvault.identity.pop();
 } catch (error) {
-  if (error instanceof PopupBlockedError) {
-    alert('Please allow popups for this site');
-  } else if (error instanceof UserCancelledError) {
-    console.log('User cancelled verification');
-  } else if (error instanceof ValidationError) {
-    console.error('Validation failed:', error.message);
-    console.error('Details:', error.details);
-  } else if (error instanceof AuthenticationError) {
-    console.error('Authentication failed:', error.message);
-  } else if (error instanceof NetworkError) {
-    console.error('Network error:', error.message);
-  } else if (error instanceof TimeoutError) {
-    console.error('Request timed out');
-  } else {
-    console.error('Unknown error:', error);
+  switch (error.code) {
+    case 'user_cancelled':
+      // User closed the modal — not necessarily an error
+      console.log('User cancelled verification');
+      break;
+
+    case 'validation_error':
+      // Invalid input (e.g., malformed email)
+      console.error('Validation error:', error.message);
+      break;
+
+    case 'network_error':
+      // Network connectivity issue
+      console.error('Network error — please check your connection');
+      break;
+
+    case 'timeout_error':
+      // Request timed out
+      console.error('Request timed out — please try again');
+      break;
+
+    case 'popup_blocked':
+      // Browser blocked the popup
+      console.error('Please allow popups for this site');
+      break;
+
+    default:
+      console.error('Unexpected error:', error.message);
   }
 }
 ```
 
-### Error Properties
+### Error Types
 
-All errors extend `SparkVaultError` and include:
+| Error Class | Code | Description |
+|-------------|------|-------------|
+| `UserCancelledError` | `user_cancelled` | User closed the modal without completing verification |
+| `ValidationError` | `validation_error` | Invalid input or configuration |
+| `NetworkError` | `network_error` | Network connectivity failure |
+| `TimeoutError` | `timeout_error` | Request exceeded timeout limit |
+| `PopupBlockedError` | `popup_blocked` | Browser blocked the popup window |
+| `AuthenticationError` | `authentication_error` | Authentication failed (e.g., expired token) |
 
-```typescript
-interface SparkVaultError extends Error {
-  message: string;              // Human-readable message
-  code: string;                 // Error code (e.g., 'validation_error')
-  statusCode?: number;          // HTTP status code if applicable
-  details?: Record<string, any>; // Additional error details
-}
-```
-
-## TypeScript
+## TypeScript Support
 
-The SDK is written in TypeScript and includes full type definitions:
+The SDK is written in TypeScript and includes full type definitions.
 
 ```typescript
-import {
-  SparkVault,
+import SparkVault, {
+  // Configuration
   SparkVaultConfig,
+
+  // Identity types
   VerifyOptions,
-  RenderOptions,
   VerifyResult,
   TokenClaims,
-  AuthMethod,
-  CreateSparkOptions,
-  Spark,
-  SparkPayload,
-  CreateVaultOptions,
-  Vault,
-  UnsealedVault,
-  Ingot,
-  UploadIngotOptions,
-  GenerateOptions,
-  RandomResult,
-  RNGFormat
-} from '@sparkvault/sdk';
-
-// All methods are fully typed
-const sv = SparkVault.init({
-  accountId: 'acc_test'
-});
 
-// TypeScript knows the return types
-const result: VerifyResult = await sv.identity.pop();
-```
+  // Error types
+  SparkVaultError,
+  UserCancelledError,
+  ValidationError,
+  NetworkError,
+  TimeoutError,
+  PopupBlockedError,
+} from '@sparkvault/sdk';
 
-## Security
+// Fully typed configuration
+const config: SparkVaultConfig = {
+  accountId: 'acc_YOUR_ACCOUNT_ID',
+  timeout: 30000,
+};
 
-### Token Security
+const sparkvault = SparkVault.init(config);
 
-- All tokens are Ed25519-signed JWTs
-- Tokens are validated for expiration and issuer
-- Tokens are short-lived (1 hour default) and scoped to your account
-- **Tokens are single-use verification proofs** — not session tokens
+// Fully typed options and result
+const options: VerifyOptions = {
+  email: 'user@example.com',
+  onCancel: () => console.log('Cancelled'),
+};
 
-### Session Management
+const result: VerifyResult = await sparkvault.identity.pop(options);
+// result.token: string
+// result.identity: string
+// result.identityType: 'email' | 'phone'
+```
 
-SparkVault Identity follows the same pattern as "Login with Google" and other major IdPs:
+## Best Practices
 
-1. **SparkVault verifies identity** → Returns signed ID token
-2. **Your backend validates the token** → Checks signature via JWKS
-3. **Your backend creates YOUR session** → Cookie, JWT, database session
-4. **Token is discarded** → Your session takes over
+1. **Initialize Once** — Create the SparkVault instance once when your app loads, not on every login attempt. The SDK preloads configuration for instant modal opening.
 
-There are no refresh tokens by design. Your application owns the user relationship and decides session lifetime, storage, and re-verification policy. This is the industry standard approach used by Google, Okta, Auth0, and all major identity providers.
+2. **Always Verify Server-Side** — Never trust client-side token validation in production. Always verify the JWT signature on your backend using the JWKS endpoint before creating a session.
 
-### Popup Security
+3. **Handle Cancellation Gracefully** — Users may close the modal without completing verification. This throws a `UserCancelledError` — handle it gracefully rather than showing an error message.
 
-- Origin validation prevents cross-origin attacks
-- `postMessage` is used securely with origin checking
-- Popups are isolated from your main window context
+4. **Cache JWKS Keys** — The JWKS endpoint returns public keys with caching headers. Use a library like `jose` that handles caching automatically, or cache keys for 5-10 minutes.
 
-### API Security
+## Browser Support
 
-- All requests use HTTPS
-- The SDK only requires your account ID (no secrets in client-side code)
+The SDK supports all modern browsers:
 
-### Best Practices
+- Chrome 80+
+- Firefox 75+
+- Safari 13.1+
+- Edge 80+
 
-1. **Validate tokens server-side** - Don't trust client-side token validation alone
-2. **Use HTTPS** - Always serve your application over HTTPS
-3. **Keep VMKs secure** - Vault Master Keys should be stored securely by users
+**Note:** Passkey authentication requires WebAuthn support. On unsupported browsers, passkey will not appear as an option — other methods will still work.
 
 ## Development
 
@@ -660,19 +732,7 @@ sdk-js/
 │   ├── config.ts          # Configuration management
 │   ├── http.ts            # HTTP client
 │   ├── errors.ts          # Error types
-│   ├── identity/          # Identity module
-│   │   ├── index.ts
-│   │   ├── modal.ts       # Popup manager
-│   │   └── types.ts
-│   ├── sparks/            # Sparks module
-│   │   ├── index.ts
-│   │   └── types.ts
-│   ├── vaults/            # Vaults module
-│   │   ├── index.ts
-│   │   └── types.ts
-│   └── rng/               # RNG module
-│       ├── index.ts
-│       └── types.ts
+│   └── identity/          # Identity module
 ├── dist/                  # Built bundles
 ├── tests/                 # Test files
 ├── .github/workflows/     # CI/CD workflows
@@ -681,32 +741,6 @@ sdk-js/
 └── package.json
 ```
 
-### CI/CD
-
-The SDK uses GitHub Actions for automated testing and deployment:
-
-- **On PR**: Runs build, lint, typecheck, and tests
-- **On push to main**: Deploys to CDN (`cdn.sparkvault.com`)
-- **On release commit**: Publishes to npm
-
-Required secrets for deployment:
-- `CLOUDFLARE_API_TOKEN` - Cloudflare API token with R2 access
-- `CLOUDFLARE_ACCOUNT_ID` - Cloudflare account ID
-- `NPM_TOKEN` - npm publish token (for releases)
-
-## Browser Support
-
-- Chrome 80+
-- Firefox 75+
-- Safari 13.1+
-- Edge 80+
-
-The SDK requires:
-- `fetch` API
-- `Promise`
-- `window.open` (for Identity popup)
-- `postMessage` (for popup communication)
-
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.