@lanonasis/oauth-client 1.0.2 → 1.2.0

package/README.md

@@ -1,12 +1,15 @@
 # @lanonasis/oauth-client
 
-Drop-in OAuth + MCP connectivity client for the Lanonasis ecosystem. Handles browser/desktop/terminal flows, token lifecycle, secure (hashed) API key storage, and MCP WebSocket/SSE connections so other projects can integrate without re-implementing auth.
+Drop-in OAuth + API Key authentication client for the Lanonasis ecosystem. Supports dual authentication modes: OAuth2 PKCE flow for pre-registered clients and direct API key authentication for dashboard users. Handles browser/desktop/terminal flows, token lifecycle, secure storage, and MCP WebSocket/SSE connections.
 
 ## Features
+- **Dual Authentication**: OAuth2 PKCE flow OR direct API key authentication
 - OAuth flows for terminal and desktop (Electron-friendly) environments
+- API key authentication for new users with dashboard-generated keys
 - Token storage with secure backends (Keytar, encrypted files, Electron secure store, mobile secure storage, WebCrypto in browsers)
 - API key storage that normalizes to SHA-256 digests before persisting
 - MCP client that connects over WebSocket (`/ws`) or SSE (`/sse`) with auto-refreshing tokens
+- Automatic auth mode detection based on configuration
 - ESM + CJS bundles with TypeScript types
 
 ## Installation
@@ -17,6 +20,24 @@ bun add @lanonasis/oauth-client
 ```
 
 ## Quick Start
+
+### Option 1: API Key Authentication (Recommended for New Users)
+```ts
+import { MCPClient } from '@lanonasis/oauth-client';
+
+// Simple API key mode - perfect for dashboard users
+const client = new MCPClient({
+  apiKey: 'lano_abc123xyz',  // Get from dashboard
+  mcpEndpoint: 'wss://mcp.lanonasis.com'
+});
+
+await client.connect();  // Automatically uses API key auth
+
+// Make requests
+const memories = await client.searchMemories('test query');
+```
+
+### Option 2: OAuth Authentication (For Pre-registered Clients)
 ```ts
 import { MCPClient } from '@lanonasis/oauth-client';
 
@@ -27,7 +48,7 @@ const client = new MCPClient({
   scope: 'mcp:read mcp:write api_keys:manage'
 });
 
-await client.connect(); // handles auth, refresh, and MCP connect
+await client.connect(); // Triggers OAuth flow, handles refresh
 ```
 
 ### Terminal OAuth flow
@@ -74,12 +95,20 @@ const hashed = await apiKeys.getApiKey(); // returns sha256 hex digest
 ```
 
 ## Configuration
+
+### API Key Mode
+- `apiKey` (required): Your dashboard-generated API key (starts with `lano_`).
+- `mcpEndpoint` (optional): defaults to `wss://mcp.lanonasis.com` and can also be `https://...` for SSE.
+
+### OAuth Mode
 - `clientId` (required): OAuth client id issued by Lanonasis Auth.
 - `authBaseUrl` (optional): defaults to `https://auth.lanonasis.com`.
 - `mcpEndpoint` (optional): defaults to `wss://mcp.lanonasis.com` and can also be `https://...` for SSE.
 - `scope` (optional): defaults to `mcp:read mcp:write api_keys:manage`.
 - `autoRefresh` (MCPClient): refresh tokens 5 minutes before expiry (default `true`).
 
+**Note**: Auth mode is automatically detected - if you provide `apiKey`, it uses API key authentication. If you provide `clientId`, it uses OAuth.
+
 ## Publishing (maintainers)
 1) Build artifacts: `npm install && npm run build`
 2) Verify contents: ensure `dist`, `README.md`, `LICENSE` are present.

package/dist/index.cjs

@@ -440,6 +440,9 @@ var TokenStorage = class {
     }
   }
   isTokenExpired(tokens) {
+    if (tokens.token_type === "api-key" || tokens.expires_in === 0) {
+      return false;
+    }
     if (!tokens.expires_in) return false;
     if (!tokens.issued_at) {
       console.warn("Token missing issued_at timestamp, treating as expired");
@@ -1071,9 +1074,66 @@ var ApiKeyStorage = class {
   }
 };
 
+// src/flows/apikey-flow.ts
+var APIKeyFlow = class extends BaseOAuthFlow {
+  constructor(apiKey, authBaseUrl = "https://mcp.lanonasis.com") {
+    super({
+      clientId: "api-key-client",
+      authBaseUrl
+    });
+    this.apiKey = apiKey;
+  }
+  /**
+   * "Authenticate" by returning the API key as a virtual token
+   * The API key will be used directly in request headers
+   */
+  async authenticate() {
+    if (!this.apiKey || !this.apiKey.startsWith("lano_") && !this.apiKey.startsWith("vx_")) {
+      throw new Error(
+        'Invalid API key format. Must start with "lano_" or "vx_". Please regenerate your API key from the dashboard.'
+      );
+    }
+    if (this.apiKey.startsWith("vx_")) {
+      console.warn(
+        '\u26A0\uFE0F  DEPRECATION WARNING: API keys with "vx_" prefix are deprecated and will stop working soon. Please regenerate your API key from the dashboard to get a "lano_" prefixed key. Support for "vx_" keys will be removed in a future version.'
+      );
+    }
+    return {
+      access_token: this.apiKey,
+      token_type: "api-key",
+      expires_in: 0,
+      // API keys don't expire
+      issued_at: Date.now()
+    };
+  }
+  /**
+   * API keys don't need refresh
+   */
+  async refreshToken(refreshToken) {
+    throw new Error("API keys do not support token refresh");
+  }
+  /**
+   * Optional: Validate API key by making a test request
+   */
+  async validateAPIKey() {
+    try {
+      const response = await fetch(`${this.config.authBaseUrl}/api/v1/health`, {
+        headers: {
+          "x-api-key": this.apiKey
+        }
+      });
+      return response.ok;
+    } catch (error) {
+      console.error("API key validation failed:", error);
+      return false;
+    }
+  }
+};
+
 // src/client/mcp-client.ts
 var MCPClient = class {
   constructor(config = {}) {
+    // ← NEW: Track auth mode
     this.ws = null;
     this.eventSource = null;
     this.accessToken = null;
@@ -1084,30 +1144,45 @@ var MCPClient = class {
       ...config
     };
     this.tokenStorage = new TokenStorage();
-    if (this.isTerminal()) {
-      this.authFlow = new TerminalOAuthFlow(config);
+    this.authMode = config.apiKey ? "apikey" : "oauth";
+    if (this.authMode === "apikey") {
+      this.authFlow = new APIKeyFlow(
+        config.apiKey,
+        config.authBaseUrl || "https://mcp.lanonasis.com"
+      );
     } else {
-      this.authFlow = new DesktopOAuthFlow(config);
+      if (this.isTerminal()) {
+        this.authFlow = new TerminalOAuthFlow(config);
+      } else {
+        this.authFlow = new DesktopOAuthFlow(config);
+      }
     }
   }
   async connect() {
     try {
       let tokens = await this.tokenStorage.retrieve();
-      if (!tokens || this.tokenStorage.isTokenExpired(tokens)) {
-        if (tokens?.refresh_token) {
-          try {
-            tokens = await this.authFlow.refreshToken(tokens.refresh_token);
-            await this.tokenStorage.store(tokens);
-          } catch (error) {
+      if (this.authMode === "apikey") {
+        if (!tokens) {
+          tokens = await this.authenticate();
+        }
+        this.accessToken = tokens.access_token;
+      } else {
+        if (!tokens || this.tokenStorage.isTokenExpired(tokens)) {
+          if (tokens?.refresh_token) {
+            try {
+              tokens = await this.authFlow.refreshToken(tokens.refresh_token);
+              await this.tokenStorage.store(tokens);
+            } catch (error) {
+              tokens = await this.authenticate();
+            }
+          } else {
             tokens = await this.authenticate();
           }
-        } else {
-          tokens = await this.authenticate();
         }
-      }
-      this.accessToken = tokens.access_token;
-      if (this.config.autoRefresh && tokens.expires_in) {
-        this.scheduleTokenRefresh(tokens);
+        this.accessToken = tokens.access_token;
+        if (this.config.autoRefresh && tokens.expires_in) {
+          this.scheduleTokenRefresh(tokens);
+        }
       }
       await this.establishConnection();
     } catch (error) {
@@ -1127,6 +1202,10 @@ var MCPClient = class {
     if (!tokens) {
       throw new Error("Not authenticated");
     }
+    if (this.authMode === "apikey") {
+      this.accessToken = tokens.access_token;
+      return;
+    }
     if (this.tokenStorage.isTokenExpired(tokens)) {
       if (tokens.refresh_token) {
         try {
@@ -1183,11 +1262,19 @@ var MCPClient = class {
       this.ws = new WebSocket(wsUrl.toString());
     } else {
       const { default: WS } = await import("ws");
-      this.ws = new WS(wsUrl.toString(), {
-        headers: {
-          "Authorization": `Bearer ${this.accessToken}`
-        }
-      });
+      if (this.authMode === "apikey") {
+        this.ws = new WS(wsUrl.toString(), {
+          headers: {
+            "x-api-key": this.accessToken
+          }
+        });
+      } else {
+        this.ws = new WS(wsUrl.toString(), {
+          headers: {
+            "Authorization": `Bearer ${this.accessToken}`
+          }
+        });
+      }
     }
     return new Promise((resolve, reject) => {
       if (!this.ws) {
@@ -1221,11 +1308,19 @@ var MCPClient = class {
     } else {
       const EventSourceModule = await import("eventsource");
       const ES = EventSourceModule.default || EventSourceModule;
-      this.eventSource = new ES(sseUrl.toString(), {
-        headers: {
-          "Authorization": `Bearer ${this.accessToken}`
-        }
-      });
+      if (this.authMode === "apikey") {
+        this.eventSource = new ES(sseUrl.toString(), {
+          headers: {
+            "x-api-key": this.accessToken
+          }
+        });
+      } else {
+        this.eventSource = new ES(sseUrl.toString(), {
+          headers: {
+            "Authorization": `Bearer ${this.accessToken}`
+          }
+        });
+      }
     }
     this.eventSource.onopen = () => {
       console.log("MCP SSE connected");
@@ -1255,12 +1350,17 @@ var MCPClient = class {
     if (!this.accessToken) {
       throw new Error("Not authenticated");
     }
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.authMode === "apikey") {
+      headers["x-api-key"] = this.accessToken;
+    } else {
+      headers["Authorization"] = `Bearer ${this.accessToken}`;
+    }
     const response = await fetch(`${this.config.mcpEndpoint}/api`, {
       method: "POST",
-      headers: {
-        "Authorization": `Bearer ${this.accessToken}`,
-        "Content-Type": "application/json"
-      },
+      headers,
       body: JSON.stringify({
         jsonrpc: "2.0",
         id: this.generateId(),
@@ -1269,6 +1369,9 @@ var MCPClient = class {
       })
     });
     if (response.status === 401) {
+      if (this.authMode === "apikey") {
+        throw new Error("Invalid API key - please check your credentials");
+      }
       const tokens = await this.tokenStorage.retrieve();
       if (tokens?.refresh_token) {
         const newTokens = await this.authFlow.refreshToken(tokens.refresh_token);

package/dist/index.d.cts

@@ -172,11 +172,13 @@ declare class ApiKeyStorage {
 interface MCPClientConfig extends Partial<OAuthConfig> {
     mcpEndpoint?: string;
     autoRefresh?: boolean;
+    apiKey?: string;
 }
 declare class MCPClient {
     private tokenStorage;
     private authFlow;
     private config;
+    private authMode;
     private ws;
     private eventSource;
     private accessToken;

package/dist/index.d.ts

@@ -172,11 +172,13 @@ declare class ApiKeyStorage {
 interface MCPClientConfig extends Partial<OAuthConfig> {
     mcpEndpoint?: string;
     autoRefresh?: boolean;
+    apiKey?: string;
 }
 declare class MCPClient {
     private tokenStorage;
     private authFlow;
     private config;
+    private authMode;
     private ws;
     private eventSource;
     private accessToken;

package/dist/index.js

@@ -406,6 +406,9 @@ var TokenStorage = class {
     }
   }
   isTokenExpired(tokens) {
+    if (tokens.token_type === "api-key" || tokens.expires_in === 0) {
+      return false;
+    }
     if (!tokens.expires_in) return false;
     if (!tokens.issued_at) {
       console.warn("Token missing issued_at timestamp, treating as expired");
@@ -1037,9 +1040,66 @@ var ApiKeyStorage = class {
   }
 };
 
+// src/flows/apikey-flow.ts
+var APIKeyFlow = class extends BaseOAuthFlow {
+  constructor(apiKey, authBaseUrl = "https://mcp.lanonasis.com") {
+    super({
+      clientId: "api-key-client",
+      authBaseUrl
+    });
+    this.apiKey = apiKey;
+  }
+  /**
+   * "Authenticate" by returning the API key as a virtual token
+   * The API key will be used directly in request headers
+   */
+  async authenticate() {
+    if (!this.apiKey || !this.apiKey.startsWith("lano_") && !this.apiKey.startsWith("vx_")) {
+      throw new Error(
+        'Invalid API key format. Must start with "lano_" or "vx_". Please regenerate your API key from the dashboard.'
+      );
+    }
+    if (this.apiKey.startsWith("vx_")) {
+      console.warn(
+        '\u26A0\uFE0F  DEPRECATION WARNING: API keys with "vx_" prefix are deprecated and will stop working soon. Please regenerate your API key from the dashboard to get a "lano_" prefixed key. Support for "vx_" keys will be removed in a future version.'
+      );
+    }
+    return {
+      access_token: this.apiKey,
+      token_type: "api-key",
+      expires_in: 0,
+      // API keys don't expire
+      issued_at: Date.now()
+    };
+  }
+  /**
+   * API keys don't need refresh
+   */
+  async refreshToken(refreshToken) {
+    throw new Error("API keys do not support token refresh");
+  }
+  /**
+   * Optional: Validate API key by making a test request
+   */
+  async validateAPIKey() {
+    try {
+      const response = await fetch(`${this.config.authBaseUrl}/api/v1/health`, {
+        headers: {
+          "x-api-key": this.apiKey
+        }
+      });
+      return response.ok;
+    } catch (error) {
+      console.error("API key validation failed:", error);
+      return false;
+    }
+  }
+};
+
 // src/client/mcp-client.ts
 var MCPClient = class {
   constructor(config = {}) {
+    // ← NEW: Track auth mode
     this.ws = null;
     this.eventSource = null;
     this.accessToken = null;
@@ -1050,30 +1110,45 @@ var MCPClient = class {
       ...config
     };
     this.tokenStorage = new TokenStorage();
-    if (this.isTerminal()) {
-      this.authFlow = new TerminalOAuthFlow(config);
+    this.authMode = config.apiKey ? "apikey" : "oauth";
+    if (this.authMode === "apikey") {
+      this.authFlow = new APIKeyFlow(
+        config.apiKey,
+        config.authBaseUrl || "https://mcp.lanonasis.com"
+      );
     } else {
-      this.authFlow = new DesktopOAuthFlow(config);
+      if (this.isTerminal()) {
+        this.authFlow = new TerminalOAuthFlow(config);
+      } else {
+        this.authFlow = new DesktopOAuthFlow(config);
+      }
     }
   }
   async connect() {
     try {
       let tokens = await this.tokenStorage.retrieve();
-      if (!tokens || this.tokenStorage.isTokenExpired(tokens)) {
-        if (tokens?.refresh_token) {
-          try {
-            tokens = await this.authFlow.refreshToken(tokens.refresh_token);
-            await this.tokenStorage.store(tokens);
-          } catch (error) {
+      if (this.authMode === "apikey") {
+        if (!tokens) {
+          tokens = await this.authenticate();
+        }
+        this.accessToken = tokens.access_token;
+      } else {
+        if (!tokens || this.tokenStorage.isTokenExpired(tokens)) {
+          if (tokens?.refresh_token) {
+            try {
+              tokens = await this.authFlow.refreshToken(tokens.refresh_token);
+              await this.tokenStorage.store(tokens);
+            } catch (error) {
+              tokens = await this.authenticate();
+            }
+          } else {
             tokens = await this.authenticate();
           }
-        } else {
-          tokens = await this.authenticate();
         }
-      }
-      this.accessToken = tokens.access_token;
-      if (this.config.autoRefresh && tokens.expires_in) {
-        this.scheduleTokenRefresh(tokens);
+        this.accessToken = tokens.access_token;
+        if (this.config.autoRefresh && tokens.expires_in) {
+          this.scheduleTokenRefresh(tokens);
+        }
       }
       await this.establishConnection();
     } catch (error) {
@@ -1093,6 +1168,10 @@ var MCPClient = class {
     if (!tokens) {
       throw new Error("Not authenticated");
     }
+    if (this.authMode === "apikey") {
+      this.accessToken = tokens.access_token;
+      return;
+    }
     if (this.tokenStorage.isTokenExpired(tokens)) {
       if (tokens.refresh_token) {
         try {
@@ -1149,11 +1228,19 @@ var MCPClient = class {
       this.ws = new WebSocket(wsUrl.toString());
     } else {
       const { default: WS } = await import("ws");
-      this.ws = new WS(wsUrl.toString(), {
-        headers: {
-          "Authorization": `Bearer ${this.accessToken}`
-        }
-      });
+      if (this.authMode === "apikey") {
+        this.ws = new WS(wsUrl.toString(), {
+          headers: {
+            "x-api-key": this.accessToken
+          }
+        });
+      } else {
+        this.ws = new WS(wsUrl.toString(), {
+          headers: {
+            "Authorization": `Bearer ${this.accessToken}`
+          }
+        });
+      }
     }
     return new Promise((resolve, reject) => {
       if (!this.ws) {
@@ -1187,11 +1274,19 @@ var MCPClient = class {
     } else {
       const EventSourceModule = await import("eventsource");
       const ES = EventSourceModule.default || EventSourceModule;
-      this.eventSource = new ES(sseUrl.toString(), {
-        headers: {
-          "Authorization": `Bearer ${this.accessToken}`
-        }
-      });
+      if (this.authMode === "apikey") {
+        this.eventSource = new ES(sseUrl.toString(), {
+          headers: {
+            "x-api-key": this.accessToken
+          }
+        });
+      } else {
+        this.eventSource = new ES(sseUrl.toString(), {
+          headers: {
+            "Authorization": `Bearer ${this.accessToken}`
+          }
+        });
+      }
     }
     this.eventSource.onopen = () => {
       console.log("MCP SSE connected");
@@ -1221,12 +1316,17 @@ var MCPClient = class {
     if (!this.accessToken) {
       throw new Error("Not authenticated");
     }
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    if (this.authMode === "apikey") {
+      headers["x-api-key"] = this.accessToken;
+    } else {
+      headers["Authorization"] = `Bearer ${this.accessToken}`;
+    }
     const response = await fetch(`${this.config.mcpEndpoint}/api`, {
       method: "POST",
-      headers: {
-        "Authorization": `Bearer ${this.accessToken}`,
-        "Content-Type": "application/json"
-      },
+      headers,
       body: JSON.stringify({
         jsonrpc: "2.0",
         id: this.generateId(),
@@ -1235,6 +1335,9 @@ var MCPClient = class {
       })
     });
     if (response.status === 401) {
+      if (this.authMode === "apikey") {
+        throw new Error("Invalid API key - please check your credentials");
+      }
       const tokens = await this.tokenStorage.retrieve();
       if (tokens?.refresh_token) {
         const newTokens = await this.authFlow.refreshToken(tokens.refresh_token);

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@lanonasis/oauth-client",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "type": "module",
-  "description": "OAuth client for Lan Onasis MCP integration",
+  "description": "OAuth and API Key authentication client for Lan Onasis MCP integration",
   "license": "MIT",
   "author": "Lan Onasis",
   "main": "./dist/index.js",