@liveauth-labs/sdk 0.1.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LiveAuth
+
+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

@@ -1,48 +1,42 @@
-# LiveAuth – Developer Portal Documentation
+# LiveAuth JS SDK
 
-## Getting Started
+> Human verification through economics, not heuristics.
 
-LiveAuth verifies humans economically instead of heuristically.
+[![npm version](https://img.shields.io/npm/v/@liveauth-labs/sdk.svg)](https://www.npmjs.com/package/@liveauth-labs/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## What is LiveAuth?
 
-Instead of CAPTCHAs or tracking, LiveAuth asks the browser to perform a short
-cryptographic proof. If that fails or is skipped, it falls back to a small
-Bitcoin Lightning payment.
+LiveAuth verifies humans economically instead of heuristically.
 
-No cookies.  
-No fingerprinting.  
-No behavioral profiling.
+Instead of CAPTCHAs or tracking, LiveAuth asks the browser to perform a short cryptographic proof. If that fails or is skipped, it falls back to a small Bitcoin Lightning payment.
 
----
+- No cookies
+- No fingerprinting  
+- No behavioral profiling
 
-## What LiveAuth Does
+## How It Works
 
-When a user clicks “Verify”:
+When a user triggers verification:
 
 1. **Browser attempts Proof-of-Work (PoW)**  
-   – Takes ~200–800ms for a real device  
-   – Bots pay CPU / battery cost
+   Takes ~200–800ms for a real device. Bots pay CPU/battery cost.
 
 2. **If PoW fails → Lightning fallback**  
-   – Small payment (e.g. 21 sats)  
-   – Real economic cost to bots
+   Small payment (e.g. 21 sats). Real economic cost to bots.
 
 3. **LiveAuth returns a short-lived JWT**  
-   – Verifiable on your backend  
-   – No user identity required
+   Verifiable on your backend. No user identity required.
 
 Most humans never see the Lightning step.
 
----
-
-## Installation (JavaScript)
+## Installation
 
 ```bash
 npm install @liveauth-labs/sdk
 ```
 
----
-
-## Basic Usage
+## Quick Start
 
 ```ts
 import { LiveAuth } from '@liveauth-labs/sdk';
@@ -52,52 +46,187 @@ const liveauth = new LiveAuth({
 });
 
 const result = await liveauth.verify();
+
+if (result.method === 'pow') {
+  // PoW succeeded - send token to your backend
+  console.log('Verified via PoW:', result.token);
+} else {
+  // Lightning fallback - show invoice to user
+  console.log('Pay invoice:', result.lightning.invoice);
+  
+  // Poll for payment confirmation
+  const token = await liveauth.pollLightning(result.lightning.sessionId);
+  console.log('Verified via Lightning:', token);
+}
 ```
 
----
+## API Reference
+
+### `new LiveAuth(config)`
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `publicKey` | `string` | ✓ | Your LiveAuth public key |
+| `baseUrl` | `string` | | API base URL (default: `https://api.liveauth.app`) |
+
+### `verify(options?)`
+
+Attempts verification, starting with PoW and falling back to Lightning if needed.
 
-## Example Result
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `forceLightning` | `boolean` | `false` | Skip PoW, go straight to Lightning |
+| `onProgress` | `function` | | Callback: `(hashesPerSec, iterations) => void` |
+| `powTimeoutMs` | `number` | `30000` | Max time for PoW before fallback |
+| `maxPowIterations` | `number` | `50000000` | Max iterations before fallback |
+
+**Returns:** `Promise<LiveAuthResult>`
 
 ```ts
+// PoW success
 {
-  token: "eyJhbGciOi...",
-  method: "pow",
+  method: 'pow',
+  token: 'eyJhbGciOi...',
   solveMs: 412,
   difficultyBits: 18
 }
+
+// Lightning fallback
+{
+  method: 'lightning',
+  lightning: {
+    sessionId: 'sess_xxx',
+    invoice: 'lnbc...',
+    amountSats: 21,
+    expiresAtUnix: 1234567890,
+    mode: 'LIVE'
+  },
+  diagnostics: {
+    reason: 'pow_unsupported'
+  }
+}
 ```
 
----
+### `pollLightning(sessionId, options?)`
 
-## Verifying on Your Backend
+Polls for Lightning payment confirmation.
 
-Send the JWT to your backend and verify it using your LiveAuth secret key.
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `timeoutMs` | `number` | `300000` | Max wait time (5 min) |
+| `intervalMs` | `number` | `2000` | Poll interval |
+| `signal` | `AbortSignal` | | Cancellation signal |
 
-The token includes:
+**Returns:** `Promise<string>` - The verification token
 
-- projectId
-- projectPublicKey
-- authType (pow or lightning)
-- short expiration (default: 10 minutes)
+## Error Handling
 
----
+```ts
+import { 
+  LiveAuth,
+  LiveAuthTimeoutError,
+  LiveAuthCancelledError,
+  LiveAuthNetworkError,
+  LiveAuthPowTimeoutError
+} from '@liveauth-labs/sdk';
+
+try {
+  const result = await liveauth.verify();
+} catch (err) {
+  if (err instanceof LiveAuthNetworkError) {
+    console.error('Network issue:', err.message);
+  } else if (err instanceof LiveAuthPowTimeoutError) {
+    console.error('PoW took too long');
+  }
+}
+```
 
-## Why LiveAuth
+## Progress Feedback
 
-| CAPTCHA | LiveAuth |
-|-------|----------|
-| Tracks behavior | No tracking |
-| ML heuristics | Cryptography |
-| CAPTCHA farms | Real economic cost |
-| Bad UX | Invisible to humans |
+Show users what's happening during PoW:
+
+```ts
+const result = await liveauth.verify({
+  onProgress: (hashesPerSec, iterations) => {
+    console.log(`${(iterations / 1000).toFixed(0)}k hashes @ ${hashesPerSec}/sec`);
+  }
+});
+```
 
----
+## Backend Verification
+
+Send the JWT to your backend and verify it using your LiveAuth secret key.
+
+### Example (Node.js)
+
+```ts
+import jwt from 'jsonwebtoken';
+
+app.post('/api/verify-liveauth', (req, res) => {
+  const { token } = req.body;
+  
+  try {
+    // Verify JWT signature with your LiveAuth secret key
+    const decoded = jwt.verify(token, process.env.LIVEAUTH_SECRET_KEY);
+    
+    // Check expiration (JWT library handles this, but you can also check manually)
+    if (decoded.exp && decoded.exp < Date.now() / 1000) {
+      return res.status(401).json({ error: 'Token expired' });
+    }
+    
+    // Extract claims
+    const { projectId, projectPublicKey, authType, sub } = decoded;
+    
+    // Verify it matches your project
+    if (projectPublicKey !== process.env.LIVEAUTH_PUBLIC_KEY) {
+      return res.status(401).json({ error: 'Invalid project' });
+    }
+    
+    // Success - user is verified
+    res.json({ 
+      verified: true, 
+      authType, // 'pow' or 'lightning'
+      userId: sub 
+    });
+    
+  } catch (err) {
+    res.status(401).json({ error: 'Invalid token' });
+  }
+});
+```
+
+### Token Claims
+
+The JWT contains:
+- `sub` - Unique user identifier (format: `pow:{projectId}:{challengeHex}` or `lightning:{invoiceId}`)
+- `projectId` - Your project's UUID
+- `projectPublicKey` - Your public API key
+- `authType` - Verification method: `pow` or `lightning`
+- `exp` - Expiration timestamp (default: 10 minutes from issuance)
+- `iat` - Issued at timestamp
+
+**Security Notes:**
+- Always verify the JWT signature using your secret key
+- Check the `projectPublicKey` claim matches your expected key
+- Respect the `exp` (expiration) claim
+- The `sub` claim is ephemeral - don't use it as a permanent user ID unless you're tracking sessions
 
 ## Debug Mode
 
 Add `?liveauth_debug=1` to your URL to see:
+- Verification method used
+- PoW difficulty and solve time
+- Lightning fallback triggers
+
+## Why LiveAuth?
+
+| Traditional CAPTCHA | LiveAuth |
+|--------------------|----------|
+| Tracks behavior | No tracking |
+| ML heuristics | Cryptography |
+| CAPTCHA farms | Real economic cost |
+| Bad UX | Invisible to most humans |
+
+## License
 
-- Verification method
-- PoW difficulty
-- Solve time
-- Lightning fallback (demo mode)
+MIT

package/dist/index.cjs

@@ -20,26 +20,51 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
-  LiveAuth: () => LiveAuth
+  LiveAuth: () => LiveAuth,
+  LiveAuthCancelledError: () => LiveAuthCancelledError,
+  LiveAuthNetworkError: () => LiveAuthNetworkError,
+  LiveAuthPowTimeoutError: () => LiveAuthPowTimeoutError,
+  LiveAuthPowUnsupportedError: () => LiveAuthPowUnsupportedError,
+  LiveAuthTimeoutError: () => LiveAuthTimeoutError
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/errors.ts
 var LiveAuthTimeoutError = class extends Error {
-  constructor(message = "Lightning verification timed out") {
+  constructor(message = "LiveAuth verification timed out") {
     super(message);
     this.name = "LiveAuthTimeoutError";
   }
 };
 var LiveAuthCancelledError = class extends Error {
-  constructor(message = "Lightning verification cancelled") {
+  constructor(message = "LiveAuth verification cancelled") {
     super(message);
     this.name = "LiveAuthCancelledError";
   }
 };
+var LiveAuthNetworkError = class extends Error {
+  constructor(message = "LiveAuth network request failed", cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "LiveAuthNetworkError";
+  }
+};
+var LiveAuthPowUnsupportedError = class extends Error {
+  constructor(message = "Proof-of-Work is not supported in this environment") {
+    super(message);
+    this.name = "LiveAuthPowUnsupportedError";
+  }
+};
+var LiveAuthPowTimeoutError = class extends Error {
+  constructor(message = "Proof-of-Work timed out") {
+    super(message);
+    this.name = "LiveAuthPowTimeoutError";
+  }
+};
 
 // src/index.ts
 var import_meta = {};
+var SDK_VERSION = "0.2.0";
 var LiveAuth = class {
   constructor(config) {
     this.config = config;
@@ -49,85 +74,149 @@ var LiveAuth = class {
     this.baseUrl = config.baseUrl ?? "https://api.liveauth.app";
     this.headers = {
       "Content-Type": "application/json",
-      "X-LW-Public": config.publicKey
+      "X-LW-Public": config.publicKey,
+      "X-LW-SDK-Version": SDK_VERSION
     };
   }
   /* ======================================================
    * PUBLIC ENTRYPOINT
    * ====================================================== */
-  async verify() {
-    const startedAt = performance.now();
-    const challenge = await this.getPowChallenge();
-    const solution = await this.solvePow(challenge);
-    const verifyRes = await this.verifyPow({
-      challengeHex: challenge.challengeHex,
-      nonce: solution.nonce,
-      hashHex: solution.hashHex,
-      expiresAtUnix: challenge.expiresAtUnix,
-      sig: challenge.sig
-    });
-    if (verifyRes.verified && verifyRes.token) {
+  async verify(options = {}) {
+    const {
+      forceLightning = false,
+      onProgress,
+      powTimeoutMs = 3e4,
+      maxPowIterations = 5e7
+    } = options;
+    if (forceLightning) {
+      const lightning = await this.startLightning();
       return {
-        method: "pow",
-        token: verifyRes.token,
-        solveMs: Math.round(performance.now() - startedAt),
-        difficultyBits: challenge.difficultyBits
+        method: "lightning",
+        lightning,
+        diagnostics: { reason: "forced_lightning" }
       };
     }
-    if (verifyRes.fallback === "lightning") {
+    if (!this.canUsePow()) {
       const lightning = await this.startLightning();
       return {
         method: "lightning",
-        lightning
+        lightning,
+        diagnostics: { reason: "pow_unsupported" }
       };
     }
-    throw new Error("LiveAuth: verification failed");
+    const startedAt = performance.now();
+    try {
+      const challenge = await this.getPowChallenge();
+      const solution = await this.solvePow(challenge, {
+        onProgress,
+        timeoutMs: powTimeoutMs,
+        maxIterations: maxPowIterations
+      });
+      const verifyRes = await this.verifyPow({
+        challengeHex: challenge.challengeHex,
+        nonce: solution.nonce,
+        hashHex: solution.hashHex,
+        expiresAtUnix: challenge.expiresAtUnix,
+        difficultyBits: challenge.difficultyBits,
+        sig: challenge.sig
+      });
+      if (verifyRes.verified && verifyRes.token) {
+        return {
+          method: "pow",
+          token: verifyRes.token,
+          solveMs: Math.round(performance.now() - startedAt),
+          difficultyBits: challenge.difficultyBits
+        };
+      }
+      if (verifyRes.fallback === "lightning") {
+        const lightning = await this.startLightning();
+        return {
+          method: "lightning",
+          lightning,
+          diagnostics: { reason: "pow_server_fallback" }
+        };
+      }
+      throw new Error("LiveAuth: verification failed");
+    } catch (err) {
+      if (err instanceof LiveAuthPowTimeoutError || err instanceof LiveAuthPowUnsupportedError) {
+        const lightning = await this.startLightning();
+        return {
+          method: "lightning",
+          lightning,
+          diagnostics: {
+            reason: "pow_failed",
+            detail: err.message
+          }
+        };
+      }
+      throw err;
+    }
   }
   /* ======================================================
    * POW FLOW
    * ====================================================== */
   async getPowChallenge() {
-    const res = await fetch(`${this.baseUrl}/api/public/pow/challenge`, {
+    const res = await this.fetchWithRetry(`${this.baseUrl}/api/public/pow/challenge`, {
       headers: this.headers
     });
-    if (!res.ok) throw new Error("PoW challenge failed");
+    if (!res.ok) throw new LiveAuthNetworkError("PoW challenge failed");
     return res.json();
   }
   async verifyPow(req) {
-    const res = await fetch(`${this.baseUrl}/api/public/pow/verify`, {
+    const res = await this.fetchWithRetry(`${this.baseUrl}/api/public/pow/verify`, {
       method: "POST",
       headers: this.headers,
       body: JSON.stringify(req)
     });
-    if (!res.ok) throw new Error("PoW verify failed");
+    if (!res.ok) throw new LiveAuthNetworkError("PoW verify failed");
     return res.json();
   }
   /* ======================================================
    * POW SOLVER (WORKER)
    * ====================================================== */
-  solvePow(challenge) {
+  solvePow(challenge, options = {}) {
+    const { onProgress, timeoutMs = 3e4, maxIterations = 5e7 } = options;
     if (!this.canUsePow()) {
-      return Promise.reject(
-        new Error("LiveAuth: PoW not supported in this environment")
-      );
+      return Promise.reject(new LiveAuthPowUnsupportedError());
     }
     return new Promise((resolve, reject) => {
       const worker = new Worker(
         new URL("./pow.worker.js", import_meta.url),
         { type: "module" }
       );
-      worker.onmessage = (e) => {
+      const timeoutId = setTimeout(() => {
         worker.terminate();
-        resolve(e.data);
+        reject(new LiveAuthPowTimeoutError(`PoW timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      worker.onmessage = (e) => {
+        const data = e.data;
+        if (data.type === "progress") {
+          onProgress?.(data.hashesPerSec ?? 0, data.iterations ?? 0);
+          return;
+        }
+        if (data.type === "timeout") {
+          clearTimeout(timeoutId);
+          worker.terminate();
+          reject(new LiveAuthPowTimeoutError(`PoW hit max iterations (${maxIterations})`));
+          return;
+        }
+        if (data.type === "solution" && data.nonce !== void 0 && data.hashHex) {
+          clearTimeout(timeoutId);
+          worker.terminate();
+          resolve({ nonce: data.nonce, hashHex: data.hashHex });
+          return;
+        }
       };
       worker.onerror = (e) => {
+        clearTimeout(timeoutId);
         worker.terminate();
-        reject(e);
+        reject(new LiveAuthPowUnsupportedError(`Worker error: ${e.message}`));
       };
       worker.postMessage({
         projectPublicKey: challenge.projectPublicKey,
         challengeHex: challenge.challengeHex,
-        targetHex: challenge.targetHex
+        targetHex: challenge.targetHex,
+        maxIterations
       });
     });
   }
@@ -135,26 +224,16 @@ var LiveAuth = class {
    * LIGHTNING FALLBACK
    * ====================================================== */
   async startLightning() {
-    const res = await fetch(`${this.baseUrl}/api/public/auth/start`, {
+    const res = await this.fetchWithRetry(`${this.baseUrl}/api/public/auth/start`, {
       method: "POST",
       headers: this.headers,
       body: JSON.stringify({ userHint: "browser" })
     });
     if (!res.ok) {
-      throw new Error("Lightning auth start failed");
+      throw new LiveAuthNetworkError("Lightning auth start failed");
     }
     return res.json();
   }
-  canUsePow() {
-    try {
-      if (typeof window === "undefined") return false;
-      if (typeof Worker === "undefined") return false;
-      if (typeof URL === "undefined") return false;
-      return true;
-    } catch {
-      return false;
-    }
-  }
   async pollLightning(sessionId, options) {
     const timeoutMs = options?.timeoutMs ?? 5 * 6e4;
     const intervalMs = options?.intervalMs ?? 2e3;
@@ -187,7 +266,7 @@ var LiveAuth = class {
           }
         );
         if (!res.ok) {
-          throw new Error("Lightning confirm failed");
+          throw new LiveAuthNetworkError("Lightning confirm failed");
         }
         const json = await res.json();
         if (json.verified && json.token) {
@@ -199,10 +278,47 @@ var LiveAuth = class {
       clearTimeout(timeoutId);
     }
   }
+  /* ======================================================
+   * UTILITIES
+   * ====================================================== */
+  canUsePow() {
+    try {
+      if (typeof window === "undefined") return false;
+      if (typeof Worker === "undefined") return false;
+      if (typeof URL === "undefined") return false;
+      if (typeof crypto === "undefined" || !crypto.subtle) return false;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async fetchWithRetry(url, init, retries = 2, backoffMs = 500) {
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        const res = await fetch(url, init);
+        return res;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        if (attempt < retries) {
+          await sleep(backoffMs * Math.pow(2, attempt));
+        }
+      }
+    }
+    throw new LiveAuthNetworkError(
+      `Request failed after ${retries + 1} attempts`,
+      lastError
+    );
+  }
 };
 var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  LiveAuth
+  LiveAuth,
+  LiveAuthCancelledError,
+  LiveAuthNetworkError,
+  LiveAuthPowTimeoutError,
+  LiveAuthPowUnsupportedError,
+  LiveAuthTimeoutError
 });
 //# sourceMappingURL=index.cjs.map