lightnode-sdk 0.4.4 → 0.4.6

package/dist/crypto.d.ts

@@ -9,12 +9,14 @@
  *   - AES-GCM ciphertext layout: nonce(12) || ciphertext || tag(16).
  *   - Encrypted session key layout: ephemeralPub(65) || nonce(12) || ciphertext || tag(16).
  *
- * Uses the Web Crypto API exposed via `globalThis.crypto.subtle`, available in
- * Node 18+ and all modern browsers. No Node-only dependencies; the SDK runs
- * unchanged in either environment.
+ * Uses the Web Crypto API. Tries `globalThis.crypto` first (real browsers +
+ * Node 19+ where it is global), then falls back to `node:crypto`'s
+ * `webcrypto` export (Node 18 and StackBlitz's WebContainer, which exposes
+ * the node: module but not the global). No hard dependency on Node, and no
+ * polyfill in the browser bundle.
  */
 /** A fresh 32-byte symmetric session key (random, never derived). */
-export declare function generateSessionKey(): Uint8Array;
+export declare function generateSessionKey(): Promise<Uint8Array>;
 /** Fresh ECDH P-256 keypair (extractable; we need to export the public key on the wire). */
 export declare function generateEcdhKeyPair(): Promise<CryptoKeyPair>;
 /** Export an ECDH public key to its raw uncompressed P-256 encoding (65 bytes). */

package/dist/crypto.js

@@ -9,23 +9,61 @@
  *   - AES-GCM ciphertext layout: nonce(12) || ciphertext || tag(16).
  *   - Encrypted session key layout: ephemeralPub(65) || nonce(12) || ciphertext || tag(16).
  *
- * Uses the Web Crypto API exposed via `globalThis.crypto.subtle`, available in
- * Node 18+ and all modern browsers. No Node-only dependencies; the SDK runs
- * unchanged in either environment.
+ * Uses the Web Crypto API. Tries `globalThis.crypto` first (real browsers +
+ * Node 19+ where it is global), then falls back to `node:crypto`'s
+ * `webcrypto` export (Node 18 and StackBlitz's WebContainer, which exposes
+ * the node: module but not the global). No hard dependency on Node, and no
+ * polyfill in the browser bundle.
  */
 const AES_KEY_BYTES = 32;
 const GCM_NONCE_BYTES = 12;
 const P256_UNCOMPRESSED_KEY_BYTES = 65;
 const SESSION_KEY_BYTES = 32;
-function subtle() {
-    const c = globalThis.crypto;
-    if (!c?.subtle)
-        throw new Error("Web Crypto unavailable - Node 18+ or a browser is required");
-    return c.subtle;
+let resolvedCrypto = null;
+let resolvingCrypto = null;
+async function getCrypto() {
+    if (resolvedCrypto)
+        return resolvedCrypto;
+    if (resolvingCrypto)
+        return resolvingCrypto;
+    resolvingCrypto = (async () => {
+        const g = globalThis.crypto;
+        if (g?.subtle && typeof g.getRandomValues === "function") {
+            const provider = { subtle: g.subtle, getRandomValues: g.getRandomValues.bind(g) };
+            resolvedCrypto = provider;
+            return provider;
+        }
+        // Node 18 + StackBlitz WebContainer: globalThis.crypto is missing, but
+        // `node:crypto` exposes the same Web Crypto API via `webcrypto`.
+        try {
+            const mod = (await import("node:crypto"));
+            const wc = mod.webcrypto;
+            if (wc?.subtle && typeof wc.getRandomValues === "function") {
+                const provider = { subtle: wc.subtle, getRandomValues: wc.getRandomValues.bind(wc) };
+                resolvedCrypto = provider;
+                return provider;
+            }
+        }
+        catch {
+            // node:crypto not importable - we're in a browser bundle without a
+            // global crypto. The fall-through error below explains the fix.
+        }
+        throw new Error("Web Crypto unavailable: globalThis.crypto is missing and node:crypto could not be loaded. " +
+            "The SDK requires Node 18+ or a modern browser.");
+    })();
+    try {
+        return await resolvingCrypto;
+    }
+    finally {
+        resolvingCrypto = null;
+    }
+}
+async function subtle() {
+    return (await getCrypto()).subtle;
 }
-function randomBytes(n) {
+async function randomBytes(n) {
     const buf = new Uint8Array(n);
-    globalThis.crypto.getRandomValues(buf);
+    (await getCrypto()).getRandomValues(buf);
     return buf;
 }
 /** A fresh 32-byte symmetric session key (random, never derived). */
@@ -33,16 +71,16 @@ export function generateSessionKey() {
     return randomBytes(SESSION_KEY_BYTES);
 }
 /** Fresh ECDH P-256 keypair (extractable; we need to export the public key on the wire). */
-export function generateEcdhKeyPair() {
-    return subtle().generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveBits"]);
+export async function generateEcdhKeyPair() {
+    return (await subtle()).generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveBits"]);
 }
 /** Export an ECDH public key to its raw uncompressed P-256 encoding (65 bytes). */
 export async function exportPublicKey(key) {
-    return new Uint8Array(await subtle().exportKey("raw", key));
+    return new Uint8Array(await (await subtle()).exportKey("raw", key));
 }
 /** Import a raw uncompressed P-256 public key (65 bytes) into a CryptoKey. */
-export function importPublicKey(raw) {
-    return subtle().importKey("raw", raw, { name: "ECDH", namedCurve: "P-256" }, true, []);
+export async function importPublicKey(raw) {
+    return (await subtle()).importKey("raw", raw, { name: "ECDH", namedCurve: "P-256" }, true, []);
 }
 /**
  * Derive a 32-byte shared secret from a local ECDH private key and a remote
@@ -50,15 +88,16 @@ export function importPublicKey(raw) {
  * protocol's `priv.ECDH(remotePub)` output exactly.
  */
 export async function deriveSharedSecret(privateKey, remotePublicKey) {
-    return new Uint8Array(await subtle().deriveBits({ name: "ECDH", public: remotePublicKey }, privateKey, 256));
+    return new Uint8Array(await (await subtle()).deriveBits({ name: "ECDH", public: remotePublicKey }, privateKey, 256));
 }
 /** Encrypt with AES-256-GCM. Output: nonce(12) || ciphertext || tag(16). */
 export async function encrypt(key, plaintext) {
     if (key.length !== AES_KEY_BYTES)
         throw new Error(`AES key must be ${AES_KEY_BYTES} bytes`);
-    const aesKey = await subtle().importKey("raw", key, "AES-GCM", false, ["encrypt"]);
-    const nonce = randomBytes(GCM_NONCE_BYTES);
-    const ctPlusTag = new Uint8Array(await subtle().encrypt({ name: "AES-GCM", iv: nonce }, aesKey, plaintext));
+    const s = await subtle();
+    const aesKey = await s.importKey("raw", key, "AES-GCM", false, ["encrypt"]);
+    const nonce = await randomBytes(GCM_NONCE_BYTES);
+    const ctPlusTag = new Uint8Array(await s.encrypt({ name: "AES-GCM", iv: nonce }, aesKey, plaintext));
     const out = new Uint8Array(GCM_NONCE_BYTES + ctPlusTag.byteLength);
     out.set(nonce, 0);
     out.set(ctPlusTag, GCM_NONCE_BYTES);
@@ -70,10 +109,11 @@ export async function decrypt(key, ciphertext) {
         throw new Error(`AES key must be ${AES_KEY_BYTES} bytes`);
     if (ciphertext.length < GCM_NONCE_BYTES + 16)
         throw new Error("ciphertext too short");
-    const aesKey = await subtle().importKey("raw", key, "AES-GCM", false, ["decrypt"]);
+    const s = await subtle();
+    const aesKey = await s.importKey("raw", key, "AES-GCM", false, ["decrypt"]);
     const nonce = ciphertext.slice(0, GCM_NONCE_BYTES);
     const body = ciphertext.slice(GCM_NONCE_BYTES);
-    return new Uint8Array(await subtle().decrypt({ name: "AES-GCM", iv: nonce }, aesKey, body));
+    return new Uint8Array(await s.decrypt({ name: "AES-GCM", iv: nonce }, aesKey, body));
 }
 /**
  * Wrap (encrypt) a 32-byte session key for delivery to a remote party (e.g. the

package/dist/gateway.d.ts

@@ -8,7 +8,14 @@
  * fresh-each-call thunk) by whatever means they prefer and hands it here.
  */
 import type { NetworkConfig } from "./types.js";
+/**
+ * Default gateway URL for a network. In Node, returns the gateway directly.
+ * In browser/WebContainer, returns the lightnode.app proxy (same upstream,
+ * but with permissive CORS so third-party origins work).
+ */
 export declare function consumerGatewayUrl(net: "mainnet" | "testnet"): string;
+/** Gateway host without any proxy fallback. For diagnostics / advanced callers. */
+export declare function consumerGatewayHost(net: "mainnet" | "testnet"): string;
 /** Either a fixed token, or a function that produces (or refreshes) one. */
 export type BearerSource = string | (() => string | Promise<string>);
 export declare class GatewayHttpError extends Error {

package/dist/gateway.js

@@ -11,7 +11,42 @@ const GATEWAY_HOSTS = {
     mainnet: "https://chat-api.mainnet.lightchain.ai",
     testnet: "https://chat-api.testnet.lightchain.ai",
 };
+// In browser-like contexts the gateway's CORS policy blocks third-party
+// origins, so the SDK routes through lightnode.app's public proxy instead.
+// The proxy is a thin pass-through (no state, no transformation), open to
+// any origin. In a real Node process this isn't needed - the gateway is
+// reached directly.
+const PROXY_HOSTS = {
+    mainnet: "https://lightnode.app/api/gw/mainnet",
+    testnet: "https://lightnode.app/api/gw/testnet",
+};
+/**
+ * True when the current runtime is a browser, or a Node-in-browser shim
+ * (StackBlitz WebContainer, Bolt, etc.) where `fetch` enforces browser-style
+ * CORS. Used to decide whether to call the gateway direct or via the proxy.
+ */
+function looksLikeBrowserFetch() {
+    if (typeof window !== "undefined" && typeof document !== "undefined")
+        return true;
+    // StackBlitz WebContainer exposes `process.versions.webcontainer`. Other
+    // Node-in-browser runtimes (Bolt, RunKit) may not, so we also check for
+    // the absence of a real Node TCP module via `process.versions.node` PLUS
+    // the presence of a global `WebSocket` (browser-only by spec).
+    const wc = globalThis.process?.versions?.webcontainer;
+    if (wc)
+        return true;
+    return false;
+}
+/**
+ * Default gateway URL for a network. In Node, returns the gateway directly.
+ * In browser/WebContainer, returns the lightnode.app proxy (same upstream,
+ * but with permissive CORS so third-party origins work).
+ */
 export function consumerGatewayUrl(net) {
+    return looksLikeBrowserFetch() ? PROXY_HOSTS[net] : GATEWAY_HOSTS[net];
+}
+/** Gateway host without any proxy fallback. For diagnostics / advanced callers. */
+export function consumerGatewayHost(net) {
     return GATEWAY_HOSTS[net];
 }
 async function resolveBearer(src) {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fromWei } from "./subgraph.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey } from "./inference.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -60,7 +60,7 @@ export declare class LightNode {
         baseUrl?: string;
     }): GatewayClient;
 }
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, runInference, runInferenceWithKey, StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, };
 export type { BearerSource, GatewayClientOptions, SelectSessionResult, PrepareSessionResult, UploadBlobResult, SessionTokenResult } from "./gateway.js";
 export type { SessionPreparation, RunInferenceArgs, RunInferenceResult, RunInferenceWithKeyArgs } from "./inference.js";
 export type { NetworkId, NetworkConfig, Worker, Job, ModelInfo, NetworkStats, ModelStat, WorkerStat, NetworkAnalytics };

package/dist/index.js

@@ -2,7 +2,7 @@ import { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS } from "./networks.js";
 import { fetchWorker, fetchWorkerJobs, fetchRecentJobs, fetchModels, fetchWorkers, summarize, fromWei, } from "./subgraph.js";
 import { isRegistered } from "./onchain.js";
 import { aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, } from "./analytics.js";
-import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, } from "./inference.js";
+import { modelId as computeModelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, runInference, runInferenceWithKey, } from "./inference.js";
 import { StalledWorkerError, OnChainRevertError, RelayTokenTimeoutError, GatewayAuthError, isStalledWorker, } from "./errors.js";
 import { GatewayClient, GatewayHttpError } from "./gateway.js";
 import * as crypto from "./crypto.js";
@@ -90,7 +90,7 @@ export class LightNode {
         return new GatewayClient({ network: this.network, ...opts });
     }
 }
-export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, 
+export { NETWORKS, WORKER_REGISTRY, REGISTRY_TOPICS, aggregateModelStats, aggregateWorkerStats, networkAnalytics, modelStatsCsv, workerStatsCsv, workerJobsCsv, fromWei, computeModelId as modelId, estimateJobFee, JOB_REGISTRY_CONSUMER_ABI, consumerGatewayUrl, consumerGatewayHost, 
 // v0.3 inference-submit surface (BETA - see README "Submitting inference").
 GatewayClient, GatewayHttpError, prepareSession, submitPrompt, decryptResponse, generateEcdhKeyPair, crypto, 
 // v0.4 high-level orchestrator: one call, full flow.

package/dist/inference.d.ts

@@ -91,7 +91,7 @@ export declare function submitPrompt(gateway: GatewayClient, sessionKey: Uint8Ar
 /** Decrypt a worker response (raw bytes or base64 from the relay) with the session key. */
 export declare function decryptResponse(sessionKey: Uint8Array, ciphertext: Uint8Array | string): Promise<string>;
 /** Re-export so callers don't have to import from a second module just for the URL helper. */
-export { consumerGatewayUrl, GatewayClient } from "./gateway.js";
+export { consumerGatewayUrl, consumerGatewayHost, GatewayClient } from "./gateway.js";
 /** Optional helper: generate the caller's own ECDH keypair if they want one (e.g. acting as the disputer). */
 export { generateEcdhKeyPair };
 interface MinimalWalletClient {

package/dist/inference.js

@@ -76,7 +76,7 @@ export const JOB_REGISTRY_CONSUMER_ABI = [
 export async function prepareSession(gateway, modelTag) {
     const id = modelId(modelTag);
     const selected = await gateway.selectSession(id);
-    const sessionKey = generateSessionKey();
+    const sessionKey = await generateSessionKey();
     // Workers' pubkeys arrive as base64; disputer's as hex - decodePublicKey
     // accepts either.
     const workerPub = await importPublicKey(decodePublicKey(selected.workerEncryptionKey));
@@ -123,7 +123,7 @@ export async function decryptResponse(sessionKey, ciphertext) {
     return bytesToUtf8(await decrypt(sessionKey, bytes));
 }
 /** Re-export so callers don't have to import from a second module just for the URL helper. */
-export { consumerGatewayUrl, GatewayClient } from "./gateway.js";
+export { consumerGatewayUrl, consumerGatewayHost, GatewayClient } from "./gateway.js";
 /** Optional helper: generate the caller's own ECDH keypair if they want one (e.g. acting as the disputer). */
 export { generateEcdhKeyPair };
 // ----------------------------------------------------------------------------
@@ -497,26 +497,44 @@ export async function runInferenceWithKey(args) {
     // the caller doesn't need a second import; in browsers + Node it works the
     // same against the consumer-api gateway.
     const gwBase = args.gatewayUrl ?? consumerGatewayUrlFn(networkId);
-    const chRes = await fetch(`${gwBase}/api/auth/challenge?address=${account.address}`, {
-        headers: { Accept: "application/json" },
-    });
+    // `fetch failed` with no cause is the worst possible error for a builder
+    // running this for the first time - they need to know which host failed and
+    // what the underlying cause was. Wrap both SIWE calls so the error names a
+    // host (so a network/DNS/CORS problem is obvious) and a hint when the cause
+    // looks like a CORS or undici-level reachability error.
+    const fetchOrFail = async (url, init, label) => {
+        try {
+            return await fetch(url, init);
+        }
+        catch (err) {
+            const cause = err.cause;
+            const code = cause?.code ?? "";
+            const msg = err.message ?? "fetch failed";
+            const detail = cause?.message ? ` (${cause.message})` : "";
+            const hint = /ENOTFOUND|EAI_AGAIN|ECONNREFUSED|UND_ERR_CONNECT|CERT_/.test(code) || msg.includes("CORS")
+                ? ` Tip: this host may be unreachable from this runtime (CORS, DNS, or TLS). Pass gatewayUrl: 'https://lightnode.app/api/gw/${networkId}' to route through the public proxy.`
+                : "";
+            throw new Error(`SIWE ${label ?? "request"} to ${url} failed: ${msg}${detail}${hint}`);
+        }
+    };
+    const chRes = await fetchOrFail(`${gwBase}/api/auth/challenge?address=${account.address}`, { headers: { Accept: "application/json" } }, "challenge");
     if (!chRes.ok)
         throw new GatewayAuthError(chRes.status, await chRes.text());
     const ch = (await chRes.json());
     if (!ch.message)
         throw new GatewayAuthError(chRes.status, "auth challenge returned no message");
     const signature = await wallet.signMessage({ account, message: ch.message });
-    const verifyRes = await fetch(`${gwBase}/api/auth/verify`, {
+    const verifyRes = await fetchOrFail(`${gwBase}/api/auth/verify`, {
         method: "POST",
         headers: { "Content-Type": "application/json", Accept: "application/json" },
         body: JSON.stringify({ message: ch.message, signature }),
-    });
+    }, "verify");
     if (!verifyRes.ok)
         throw new GatewayAuthError(verifyRes.status, await verifyRes.text());
     const verify = (await verifyRes.json());
     if (!verify.token)
         throw new GatewayAuthError(verifyRes.status, "auth verify returned no token");
-    const gateway = new GatewayClientCtor({ network: networkId, bearer: verify.token, baseUrl: args.gatewayUrl });
+    const gateway = new GatewayClientCtor({ network: networkId, bearer: verify.token, baseUrl: args.gatewayUrl ?? gwBase });
     // Pick a WebSocket: the browser global if present, otherwise the caller-
     // supplied ctor. We deliberately do NOT try to dynamic-import "ws" - it
     // isn't a hard dep, and a bundler trying to resolve it would fail noisily.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lightnode-sdk",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "Read-only TypeScript client for LightChain AI: workers, jobs, models, on-chain registration, and per-model network analytics. Independent, community-built (not an official LightChain package).",
   "type": "module",
   "main": "./dist/index.js",