@sparkvault/sdk 1.0.0

package/README.md

@@ -0,0 +1,720 @@
+# SparkVault JavaScript SDK
+
+A unified JavaScript SDK for SparkVault services: Identity verification, encrypted Sparks, secure Vaults, and cryptographic RNG.
+
+[![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)
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Architecture](#architecture)
+- [Modules](#modules)
+  - [Identity](#identity)
+  - [Sparks](#sparks)
+  - [Vaults](#vaults)
+  - [RNG](#rng)
+- [Configuration](#configuration)
+- [Error Handling](#error-handling)
+- [TypeScript](#typescript)
+- [Security](#security)
+- [Development](#development)
+- [License](#license)
+
+## Installation
+
+### CDN (Browser)
+
+Include the SDK directly in your HTML. This is the recommended approach for most web applications.
+
+#### Zero-Config Auto-Init (Recommended)
+
+The simplest way to add SparkVault authentication to your site:
+
+```html
+<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"
+></script>
+
+<button class="js-sparkvault-auth">Login with SparkVault</button>
+```
+
+That's it! The SDK automatically:
+- Initializes with your account ID
+- Attaches click handlers to matching elements
+- Opens the verification modal on click
+- POSTs the result to your success URL
+
+#### 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 |
+
+#### Success Handling
+
+When verification succeeds, the SDK can call a function and/or POST to a URL:
+
+```html
+<!-- Call a function -->
+<script>
+  function handleSparkVaultAuth(result) {
+    console.log('Verified:', result.identity);
+    console.log('Token:', result.token);
+    // Your logic here...
+  }
+</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>
+```
+
+When POSTing to `data-success-url`, the SDK sends:
+```json
+{
+  "token": "eyJ...",
+  "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
+```
+
+#### Manual Initialization
+
+For more control, initialize the SDK manually:
+
+```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>
+```
+
+#### Available CDN Files
+
+| File | Description |
+|------|-------------|
+| `sparkvault.js` | Minified UMD bundle (recommended) |
+| `sparkvault.esm.js` | ES module bundle |
+| `sparkvault.cjs.js` | CommonJS bundle |
+
+### npm
+
+```bash
+npm install @sparkvault/sdk
+```
+
+```javascript
+// ES Modules
+import { SparkVault } from '@sparkvault/sdk';
+
+// CommonJS
+const { SparkVault } = require('@sparkvault/sdk');
+```
+
+## Quick Start
+
+```javascript
+// Initialize the SDK
+const sv = SparkVault.init({
+  accountId: 'acc_your_account'
+});
+
+// Identity - Open verification popup
+const result = await sv.identity.pop({
+  email: 'user@example.com'
+});
+
+// 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
+```
+
+## 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                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Identity Popup Flow
+
+The Identity module uses a secure popup window for authentication:
+
+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
+
+```
+┌──────────────┐     ┌──────────────────┐     ┌──────────────┐
+│ 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
+
+Verify user identity through passkey, TOTP, magic link, or social authentication.
+
+The SDK provides two methods:
+- **`pop()`** — Opens a modal popup (most common)
+- **`render()`** — Embeds UI inline in your page
+
+```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'
+```
+
+#### Inline Rendering
+
+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
+});
+```
+
+| 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.).
+
+#### Supported Authentication Methods
+
+| 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 |
+
+#### Appearance Options
+
+The Identity popup supports theming and visual effects:
+
+```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'
+});
+
+// Disable backdrop blur (enabled by default)
+await sv.identity.pop({
+  backdropBlur: false
+});
+
+// Combine options
+await sv.identity.pop({
+  email: 'user@example.com',
+  theme: 'dark',
+  backdropBlur: true
+});
+```
+
+| 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. |
+
+#### Token Verification
+
+```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
+```
+
+### Sparks
+
+Create and read ephemeral encrypted secrets that burn on read.
+
+```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
+});
+
+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
+
+// Read a spark (burns it)
+const data = await sv.sparks.read(sparkId);
+// or
+const data = await sv.sparks.read(sparkId, 'password');
+
+console.log(data.payload);          // Decrypted payload
+console.log(data.burned);           // true if this was the last read
+```
+
+### Vaults
+
+Create and manage encrypted vaults with persistent storage for files (Ingots).
+
+```javascript
+// Create a vault
+const vault = await sv.vaults.create({
+  name: 'My Vault'
+});
+
+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
+
+// List vaults
+const vaults = await sv.vaults.list();
+
+// 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
+
+// Upload a file (ingot)
+const ingot = await sv.vaults.uploadIngot(unsealed, {
+  file: fileObject,                 // File or Blob
+  name: 'document.pdf'              // Display name
+});
+
+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
+
+// List ingots
+const ingots = await sv.vaults.listIngots(unsealed);
+
+// Download an ingot
+const blob = await sv.vaults.downloadIngot(unsealed, ingotId);
+
+// Delete an ingot
+await sv.vaults.deleteIngot(unsealed, ingotId);
+```
+
+### RNG
+
+Generate cryptographically secure random numbers using hybrid entropy (KMS + local).
+
+```javascript
+// Generate random bytes
+const result = await sv.rng.generate({
+  bytes: 32,                        // 1-1024 bytes
+  format: 'hex'                     // Output format
+});
+
+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
+```
+
+## Configuration
+
+```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)
+});
+```
+
+### 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
+
+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.
+
+```javascript
+// Default behavior (preloadConfig: true)
+// Config is fetched immediately when SDK initializes
+const sv = SparkVault.init({ accountId: 'acc_xxx' });
+
+// Later, when user clicks "Sign In"...
+await sv.identity.pop();  // Opens instantly - config already loaded!
+```
+
+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
+});
+
+// Config loads on-demand with a brief loading spinner
+await sv.identity.pop();
+```
+
+### Environments
+
+| Environment | API Base URL | Use Case |
+|-------------|--------------|----------|
+| `production` | `https://api.sparkvault.com` | Live applications |
+| `sandbox` | `https://sandbox.api.sparkvault.com` | Testing and development |
+
+## Error Handling
+
+The SDK provides typed errors for different failure scenarios:
+
+```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
+} from '@sparkvault/sdk';
+
+try {
+  await sv.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);
+  }
+}
+```
+
+### Error Properties
+
+All errors extend `SparkVaultError` and include:
+
+```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
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import {
+  SparkVault,
+  SparkVaultConfig,
+  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();
+```
+
+## Security
+
+### Token Security
+
+- 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
+
+### Session Management
+
+SparkVault Identity follows the same pattern as "Login with Google" and other major IdPs:
+
+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
+
+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.
+
+### Popup Security
+
+- Origin validation prevents cross-origin attacks
+- `postMessage` is used securely with origin checking
+- Popups are isolated from your main window context
+
+### API Security
+
+- All requests use HTTPS
+- The SDK only requires your account ID (no secrets in client-side code)
+
+### Best Practices
+
+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
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/Spark-Vault/sdk-js.git
+cd sdk-js
+npm install
+```
+
+### Scripts
+
+```bash
+npm run build        # Build all bundles
+npm run build:watch  # Build with watch mode
+npm run typecheck    # Run TypeScript type checking
+npm run lint         # Run ESLint
+npm run test         # Run tests
+npm run test:watch   # Run tests in watch mode
+```
+
+### Project Structure
+
+```
+sdk-js/
+├── src/
+│   ├── index.ts           # Main entry point
+│   ├── 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
+├── dist/                  # Built bundles
+├── tests/                 # Test files
+├── .github/workflows/     # CI/CD workflows
+├── rollup.config.js       # Rollup bundler config
+├── tsconfig.json          # TypeScript config
+└── 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.
+
+## Links
+
+- [SparkVault Documentation](https://sparkvault.com/api/docs)
+- [SDK API Reference](https://sparkvault.com/api/docs/sdk)
+- [GitHub Repository](https://github.com/Spark-Vault/sdk-js)
+- [npm Package](https://www.npmjs.com/package/@sparkvault/sdk)
+- [Report Issues](https://github.com/Spark-Vault/sdk-js/issues)