@lanonasis/oauth-client 1.2.1 → 1.2.3

package/README.md

@@ -1,13 +1,16 @@
 # @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
-- Token storage with secure backends (Keytar, encrypted files, Electron secure store, mobile secure storage, WebCrypto in browsers)
+- 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); browser builds auto-use web storage
 - 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
-- ESM + CJS bundles with TypeScript types
+- Automatic auth mode detection based on configuration
+- ESM + CJS bundles with a dedicated browser export to avoid Node-only deps
 
 ## Installation
 ```bash
@@ -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'; // or '@lanonasis/oauth-client/browser' in web-only bundles
+
+// 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';
 
@@ -24,10 +45,10 @@ const client = new MCPClient({
   clientId: 'your_oauth_client_id',
   authBaseUrl: 'https://auth.lanonasis.com',
   mcpEndpoint: 'wss://mcp.lanonasis.com',
-  scope: 'mcp:read mcp:write api_keys:manage'
+  scope: 'memories:read memories:write memories:delete profile' // default if omitted
 });
 
-await client.connect(); // handles auth, refresh, and MCP connect
+await client.connect(); // Triggers OAuth flow, handles refresh
 ```
 
 ### Terminal OAuth flow
@@ -74,12 +95,26 @@ 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.
+- `tokenStorage` (optional): provide a custom storage adapter; defaults to secure Node storage in Node/Electron and WebCrypto+localStorage in browsers.
+
+### 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`.
+- `scope` (optional): defaults to `memories:read memories:write memories:delete profile`.
 - `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.
+
+## Browser builds
+- The package ships a browser entry at `@lanonasis/oauth-client/browser`; modern bundlers will also pick it via the `browser` export.
+- Browser bundles avoid Node-only deps (`keytar`, `open`, `fs`, `os`, etc.) and use Web Crypto + `localStorage` for token/API key persistence.
+- The terminal/device code flow remains Node-only; in browser previews use API key or desktop flow.
+
 ## Publishing (maintainers)
 1) Build artifacts: `npm install && npm run build`
 2) Verify contents: ensure `dist`, `README.md`, `LICENSE` are present.

package/dist/api-key-storage-web-DannE11B.d.cts

@@ -0,0 +1,208 @@
+interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+    token_type: string;
+    scope?: string;
+    issued_at?: number;
+}
+interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+interface OAuthConfig {
+    clientId: string;
+    authBaseUrl?: string;
+    redirectUri?: string;
+    scope?: string;
+}
+interface AuthError {
+    error: string;
+    error_description?: string;
+}
+type GrantType = 'authorization_code' | 'urn:ietf:params:oauth:grant-type:device_code' | 'refresh_token';
+interface PKCEChallenge {
+    codeVerifier: string;
+    codeChallenge: string;
+}
+
+declare abstract class BaseOAuthFlow {
+    protected readonly clientId: string;
+    protected readonly authBaseUrl: string;
+    protected readonly scope: string;
+    constructor(config: OAuthConfig);
+    abstract authenticate(): Promise<TokenResponse>;
+    protected makeTokenRequest(body: Record<string, string>): Promise<TokenResponse>;
+    protected generateState(): string;
+    protected base64URLEncode(buffer: ArrayBuffer | Uint8Array): string;
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    revokeToken(token: string, tokenType?: 'access_token' | 'refresh_token'): Promise<void>;
+}
+
+declare class DesktopOAuthFlow extends BaseOAuthFlow {
+    private readonly redirectUri;
+    private authWindow;
+    constructor(config: OAuthConfig);
+    authenticate(): Promise<TokenResponse>;
+    private generatePKCEChallenge;
+    private generateCodeVerifier;
+    private generateCodeChallenge;
+    private buildAuthorizationUrl;
+    private openAuthWindow;
+    private openBrowserWindow;
+    private openElectronWindow;
+    private exchangeCodeForToken;
+}
+
+interface TokenStorageAdapter {
+    store(tokens: TokenResponse): Promise<void>;
+    retrieve(): Promise<TokenResponse | null>;
+    clear(): Promise<void>;
+    isTokenExpired(tokens: TokenResponse & {
+        issued_at?: number;
+    }): boolean;
+}
+declare class TokenStorage implements TokenStorageAdapter {
+    private readonly storageKey;
+    private readonly webEncryptionKeyStorage;
+    private keytar;
+    constructor();
+    store(tokens: TokenResponse): Promise<void>;
+    retrieve(): Promise<TokenResponse | null>;
+    clear(): Promise<void>;
+    isTokenExpired(tokens: TokenResponse & {
+        issued_at?: number;
+    }): boolean;
+    private storeToFile;
+    private retrieveFromFile;
+    private deleteFile;
+    private getFileEncryptionKey;
+    private encrypt;
+    private decrypt;
+    private isNode;
+    private isElectron;
+    private isMobile;
+    private base64Encode;
+    private base64Decode;
+    private getWebEncryptionKey;
+}
+
+/**
+ * Browser-only token storage that avoids Node/Electron dependencies.
+ * Tokens are encrypted with Web Crypto and stored in localStorage.
+ */
+declare class TokenStorageWeb implements TokenStorageAdapter {
+    private readonly storageKey;
+    private readonly webEncryptionKeyStorage;
+    store(tokens: TokenResponse): Promise<void>;
+    retrieve(): Promise<TokenResponse | null>;
+    clear(): Promise<void>;
+    isTokenExpired(tokens: TokenResponse & {
+        issued_at?: number;
+    }): boolean;
+    private encrypt;
+    private decrypt;
+    private getWebEncryptionKey;
+    private base64Encode;
+    private base64Decode;
+}
+
+/**
+ * API Key Storage Service
+ * Secure multi-platform API key storage with encryption
+ * Supports Node.js, Electron, Web, and Mobile environments
+ */
+interface ApiKeyData {
+    apiKey: string;
+    organizationId?: string;
+    userId?: string;
+    environment?: 'development' | 'staging' | 'production';
+    createdAt?: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class ApiKeyStorage {
+    private readonly storageKey;
+    private readonly legacyConfigKey;
+    private readonly webEncryptionKeyStorage;
+    private keytar;
+    private migrationCompleted;
+    constructor();
+    /**
+     * Initialize and migrate from legacy storage if needed
+     */
+    initialize(): Promise<void>;
+    /**
+     * Store API key securely
+     */
+    store(data: ApiKeyData): Promise<void>;
+    /**
+     * Retrieve API key from secure storage
+     */
+    retrieve(): Promise<ApiKeyData | null>;
+    /**
+     * Get just the API key string (convenience method)
+     */
+    getApiKey(): Promise<string | null>;
+    /**
+     * Check if API key exists
+     */
+    hasApiKey(): Promise<boolean>;
+    /**
+     * Clear API key from storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Check if API key is expired
+     */
+    isExpired(data: ApiKeyData): boolean;
+    /**
+     * Update API key metadata without changing the key itself
+     */
+    updateMetadata(metadata: Record<string, unknown>): Promise<void>;
+    /**
+     * Migrate from legacy configuration storage
+     */
+    private migrateFromLegacyIfNeeded;
+    private storeToFile;
+    private retrieveFromFile;
+    private deleteFile;
+    private retrieveLegacyFromFile;
+    private deleteLegacyFile;
+    private getFileEncryptionKey;
+    private encrypt;
+    private decrypt;
+    private getWebEncryptionKey;
+    private isNode;
+    private isElectron;
+    private isMobile;
+    private base64Encode;
+    private base64Decode;
+    /**
+     * Normalize API keys to a SHA-256 hex digest.
+     * Accepts pre-hashed input and lowercases it to prevent double hashing.
+     */
+    private normalizeApiKey;
+}
+
+/**
+ * Browser-only API key storage using Web Crypto + localStorage.
+ */
+declare class ApiKeyStorageWeb {
+    private readonly storageKey;
+    private readonly webEncryptionKeyStorage;
+    store(data: ApiKeyData): Promise<void>;
+    retrieve(): Promise<ApiKeyData | null>;
+    clear(): Promise<void>;
+    private encrypt;
+    private decrypt;
+    private getWebEncryptionKey;
+    private base64Encode;
+    private base64Decode;
+}
+
+export { ApiKeyStorageWeb as A, BaseOAuthFlow as B, DesktopOAuthFlow as D, type GrantType as G, type OAuthConfig as O, type PKCEChallenge as P, type TokenStorageAdapter as T, TokenStorageWeb as a, type TokenResponse as b, type DeviceCodeResponse as c, type AuthError as d, TokenStorage as e, type ApiKeyData as f, ApiKeyStorage as g };

package/dist/api-key-storage-web-DannE11B.d.ts

@@ -0,0 +1,208 @@
+interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in: number;
+    token_type: string;
+    scope?: string;
+    issued_at?: number;
+}
+interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+interface OAuthConfig {
+    clientId: string;
+    authBaseUrl?: string;
+    redirectUri?: string;
+    scope?: string;
+}
+interface AuthError {
+    error: string;
+    error_description?: string;
+}
+type GrantType = 'authorization_code' | 'urn:ietf:params:oauth:grant-type:device_code' | 'refresh_token';
+interface PKCEChallenge {
+    codeVerifier: string;
+    codeChallenge: string;
+}
+
+declare abstract class BaseOAuthFlow {
+    protected readonly clientId: string;
+    protected readonly authBaseUrl: string;
+    protected readonly scope: string;
+    constructor(config: OAuthConfig);
+    abstract authenticate(): Promise<TokenResponse>;
+    protected makeTokenRequest(body: Record<string, string>): Promise<TokenResponse>;
+    protected generateState(): string;
+    protected base64URLEncode(buffer: ArrayBuffer | Uint8Array): string;
+    refreshToken(refreshToken: string): Promise<TokenResponse>;
+    revokeToken(token: string, tokenType?: 'access_token' | 'refresh_token'): Promise<void>;
+}
+
+declare class DesktopOAuthFlow extends BaseOAuthFlow {
+    private readonly redirectUri;
+    private authWindow;
+    constructor(config: OAuthConfig);
+    authenticate(): Promise<TokenResponse>;
+    private generatePKCEChallenge;
+    private generateCodeVerifier;
+    private generateCodeChallenge;
+    private buildAuthorizationUrl;
+    private openAuthWindow;
+    private openBrowserWindow;
+    private openElectronWindow;
+    private exchangeCodeForToken;
+}
+
+interface TokenStorageAdapter {
+    store(tokens: TokenResponse): Promise<void>;
+    retrieve(): Promise<TokenResponse | null>;
+    clear(): Promise<void>;
+    isTokenExpired(tokens: TokenResponse & {
+        issued_at?: number;
+    }): boolean;
+}
+declare class TokenStorage implements TokenStorageAdapter {
+    private readonly storageKey;
+    private readonly webEncryptionKeyStorage;
+    private keytar;
+    constructor();
+    store(tokens: TokenResponse): Promise<void>;
+    retrieve(): Promise<TokenResponse | null>;
+    clear(): Promise<void>;
+    isTokenExpired(tokens: TokenResponse & {
+        issued_at?: number;
+    }): boolean;
+    private storeToFile;
+    private retrieveFromFile;
+    private deleteFile;
+    private getFileEncryptionKey;
+    private encrypt;
+    private decrypt;
+    private isNode;
+    private isElectron;
+    private isMobile;
+    private base64Encode;
+    private base64Decode;
+    private getWebEncryptionKey;
+}
+
+/**
+ * Browser-only token storage that avoids Node/Electron dependencies.
+ * Tokens are encrypted with Web Crypto and stored in localStorage.
+ */
+declare class TokenStorageWeb implements TokenStorageAdapter {
+    private readonly storageKey;
+    private readonly webEncryptionKeyStorage;
+    store(tokens: TokenResponse): Promise<void>;
+    retrieve(): Promise<TokenResponse | null>;
+    clear(): Promise<void>;
+    isTokenExpired(tokens: TokenResponse & {
+        issued_at?: number;
+    }): boolean;
+    private encrypt;
+    private decrypt;
+    private getWebEncryptionKey;
+    private base64Encode;
+    private base64Decode;
+}
+
+/**
+ * API Key Storage Service
+ * Secure multi-platform API key storage with encryption
+ * Supports Node.js, Electron, Web, and Mobile environments
+ */
+interface ApiKeyData {
+    apiKey: string;
+    organizationId?: string;
+    userId?: string;
+    environment?: 'development' | 'staging' | 'production';
+    createdAt?: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}
+declare class ApiKeyStorage {
+    private readonly storageKey;
+    private readonly legacyConfigKey;
+    private readonly webEncryptionKeyStorage;
+    private keytar;
+    private migrationCompleted;
+    constructor();
+    /**
+     * Initialize and migrate from legacy storage if needed
+     */
+    initialize(): Promise<void>;
+    /**
+     * Store API key securely
+     */
+    store(data: ApiKeyData): Promise<void>;
+    /**
+     * Retrieve API key from secure storage
+     */
+    retrieve(): Promise<ApiKeyData | null>;
+    /**
+     * Get just the API key string (convenience method)
+     */
+    getApiKey(): Promise<string | null>;
+    /**
+     * Check if API key exists
+     */
+    hasApiKey(): Promise<boolean>;
+    /**
+     * Clear API key from storage
+     */
+    clear(): Promise<void>;
+    /**
+     * Check if API key is expired
+     */
+    isExpired(data: ApiKeyData): boolean;
+    /**
+     * Update API key metadata without changing the key itself
+     */
+    updateMetadata(metadata: Record<string, unknown>): Promise<void>;
+    /**
+     * Migrate from legacy configuration storage
+     */
+    private migrateFromLegacyIfNeeded;
+    private storeToFile;
+    private retrieveFromFile;
+    private deleteFile;
+    private retrieveLegacyFromFile;
+    private deleteLegacyFile;
+    private getFileEncryptionKey;
+    private encrypt;
+    private decrypt;
+    private getWebEncryptionKey;
+    private isNode;
+    private isElectron;
+    private isMobile;
+    private base64Encode;
+    private base64Decode;
+    /**
+     * Normalize API keys to a SHA-256 hex digest.
+     * Accepts pre-hashed input and lowercases it to prevent double hashing.
+     */
+    private normalizeApiKey;
+}
+
+/**
+ * Browser-only API key storage using Web Crypto + localStorage.
+ */
+declare class ApiKeyStorageWeb {
+    private readonly storageKey;
+    private readonly webEncryptionKeyStorage;
+    store(data: ApiKeyData): Promise<void>;
+    retrieve(): Promise<ApiKeyData | null>;
+    clear(): Promise<void>;
+    private encrypt;
+    private decrypt;
+    private getWebEncryptionKey;
+    private base64Encode;
+    private base64Decode;
+}
+
+export { ApiKeyStorageWeb as A, BaseOAuthFlow as B, DesktopOAuthFlow as D, type GrantType as G, type OAuthConfig as O, type PKCEChallenge as P, type TokenStorageAdapter as T, TokenStorageWeb as a, type TokenResponse as b, type DeviceCodeResponse as c, type AuthError as d, TokenStorage as e, type ApiKeyData as f, ApiKeyStorage as g };