salesflare-mcp-server 1.0.0

package/dist/auth/api-key-auth.d.ts

@@ -0,0 +1,75 @@
+/**
+ * API Key Authentication for Salesflare MCP Server
+ *
+ * Implements AuthProvider interface for API key authentication.
+ * Reads API key from SALESFLARE_API_KEY environment variable.
+ *
+ * Per D-06: Crashes on startup with clear error if SALESFLARE_API_KEY is missing.
+ * Per D-08: Uses SALESFLARE_API_KEY environment variable.
+ *
+ * @module auth/api-key-auth
+ */
+import { AuthProvider, AuthHeaders } from './token-manager.js';
+/**
+ * API Key authentication provider
+ *
+ * Implements the AuthProvider interface for API key authentication.
+ * Stores the API key in memory and provides it as a Bearer token
+ * in Authorization headers.
+ *
+ * @class
+ * @implements {AuthProvider}
+ */
+export declare class ApiKeyAuth implements AuthProvider {
+    /** The API key for authentication */
+    private apiKey;
+    /**
+     * Create a new ApiKeyAuth instance
+     *
+     * @param apiKey - The Salesflare API key
+     * @throws {SalesflareError} If apiKey is empty or not a string
+     */
+    constructor(apiKey: string);
+    /**
+     * Get authentication headers for API requests
+     *
+     * Returns the Authorization header with the API key as a Bearer token.
+     *
+     * @returns Promise resolving to auth headers with Bearer token
+     */
+    getAuthHeaders(): Promise<AuthHeaders>;
+    /**
+     * Check if currently authenticated
+     *
+     * Always returns true for API key auth since the key is validated
+     * at construction time.
+     *
+     * @returns Always true
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get the authentication type
+     *
+     * @returns 'api_key' to identify this as API key authentication
+     */
+    getAuthType(): 'api_key' | 'oauth';
+}
+/**
+ * Create an API key authentication provider from environment
+ *
+ * Reads SALESFLARE_API_KEY from process.env and creates an ApiKeyAuth instance.
+ * Per D-06: Throws a clear error if the environment variable is missing.
+ * Per D-08: Uses SALESFLARE_API_KEY environment variable name.
+ *
+ * @returns Configured ApiKeyAuth instance
+ * @throws {SalesflareError} If SALESFLARE_API_KEY environment variable is missing
+ *
+ * @example
+ * ```typescript
+ * const auth = createApiKeyAuth();
+ * const headers = await auth.getAuthHeaders();
+ * // headers = { Authorization: 'Bearer your-api-key' }
+ * ```
+ */
+export declare function createApiKeyAuth(): ApiKeyAuth;
+//# sourceMappingURL=api-key-auth.d.ts.map

package/dist/auth/api-key-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-key-auth.d.ts","sourceRoot":"","sources":["../../src/auth/api-key-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAG/D;;;;;;;;;GASG;AACH,qBAAa,UAAW,YAAW,YAAY;IAC7C,qCAAqC;IACrC,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBACS,MAAM,EAAE,MAAM;IAY1B;;;;;;OAMG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAM5C;;;;;;;OAOG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;OAIG;IACH,WAAW,IAAI,SAAS,GAAG,OAAO;CAGnC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,IAAI,UAAU,CAa7C"}

package/dist/auth/api-key-auth.js

@@ -0,0 +1,103 @@
+/**
+ * API Key Authentication for Salesflare MCP Server
+ *
+ * Implements AuthProvider interface for API key authentication.
+ * Reads API key from SALESFLARE_API_KEY environment variable.
+ *
+ * Per D-06: Crashes on startup with clear error if SALESFLARE_API_KEY is missing.
+ * Per D-08: Uses SALESFLARE_API_KEY environment variable.
+ *
+ * @module auth/api-key-auth
+ */
+import { SalesflareError, ErrorCode } from '../utils/errors.js';
+/**
+ * API Key authentication provider
+ *
+ * Implements the AuthProvider interface for API key authentication.
+ * Stores the API key in memory and provides it as a Bearer token
+ * in Authorization headers.
+ *
+ * @class
+ * @implements {AuthProvider}
+ */
+export class ApiKeyAuth {
+    /** The API key for authentication */
+    apiKey;
+    /**
+     * Create a new ApiKeyAuth instance
+     *
+     * @param apiKey - The Salesflare API key
+     * @throws {SalesflareError} If apiKey is empty or not a string
+     */
+    constructor(apiKey) {
+        if (!apiKey || typeof apiKey !== 'string') {
+            throw new SalesflareError({
+                code: ErrorCode.AUTH_INVALID,
+                message: 'API key must be a non-empty string',
+                fix: 'Provide a valid Salesflare API key',
+                retryable: false,
+            });
+        }
+        this.apiKey = apiKey;
+    }
+    /**
+     * Get authentication headers for API requests
+     *
+     * Returns the Authorization header with the API key as a Bearer token.
+     *
+     * @returns Promise resolving to auth headers with Bearer token
+     */
+    async getAuthHeaders() {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Check if currently authenticated
+     *
+     * Always returns true for API key auth since the key is validated
+     * at construction time.
+     *
+     * @returns Always true
+     */
+    isAuthenticated() {
+        return true;
+    }
+    /**
+     * Get the authentication type
+     *
+     * @returns 'api_key' to identify this as API key authentication
+     */
+    getAuthType() {
+        return 'api_key';
+    }
+}
+/**
+ * Create an API key authentication provider from environment
+ *
+ * Reads SALESFLARE_API_KEY from process.env and creates an ApiKeyAuth instance.
+ * Per D-06: Throws a clear error if the environment variable is missing.
+ * Per D-08: Uses SALESFLARE_API_KEY environment variable name.
+ *
+ * @returns Configured ApiKeyAuth instance
+ * @throws {SalesflareError} If SALESFLARE_API_KEY environment variable is missing
+ *
+ * @example
+ * ```typescript
+ * const auth = createApiKeyAuth();
+ * const headers = await auth.getAuthHeaders();
+ * // headers = { Authorization: 'Bearer your-api-key' }
+ * ```
+ */
+export function createApiKeyAuth() {
+    const apiKey = process.env.SALESFLARE_API_KEY;
+    if (!apiKey) {
+        throw new SalesflareError({
+            code: ErrorCode.AUTH_INVALID,
+            message: 'SALESFLARE_API_KEY environment variable is required',
+            fix: 'Set SALESFLARE_API_KEY to your Salesflare API key',
+            retryable: false,
+        });
+    }
+    return new ApiKeyAuth(apiKey);
+}

package/dist/auth/oauth-auth.d.ts

@@ -0,0 +1,81 @@
+/**
+ * OAuth Authentication placeholder for Salesflare MCP Server
+ *
+ * This is a placeholder implementation for OAuth 2.0 authentication.
+ * Per D-01, full OAuth implementation is deferred to Phase 2.
+ *
+ * The class implements AuthProvider interface but throws errors
+ * for any actual usage, directing users to use API key authentication instead.
+ *
+ * @module auth/oauth-auth
+ */
+import { AuthProvider, AuthHeaders } from './token-manager.js';
+/**
+ * OAuth authentication provider (Phase 2 placeholder)
+ *
+ * Implements the AuthProvider interface but is not fully functional.
+ * This is a placeholder that will be completed in Phase 2.
+ *
+ * Per D-01: OAuth deferred to Phase 2.
+ *
+ * @class
+ * @implements {AuthProvider}
+ */
+export declare class OAuthAuth implements AuthProvider {
+    /** OAuth client ID */
+    private clientId;
+    /** OAuth client secret */
+    private clientSecret;
+    /** OAuth redirect URI */
+    private redirectUri;
+    /** Token manager for OAuth tokens */
+    private tokenManager;
+    /**
+     * Create a new OAuthAuth instance
+     *
+     * @param clientId - OAuth client ID
+     * @param clientSecret - OAuth client secret
+     * @param redirectUri - OAuth redirect URI
+     */
+    constructor(clientId: string, clientSecret: string, redirectUri: string);
+    /**
+     * Get authentication headers for API requests
+     *
+     * Returns Authorization header with OAuth access token.
+     *
+     * TODO(Phase 2): Implement token refresh on AUTH_EXPIRED
+     *
+     * @returns Promise resolving to auth headers
+     * @throws {SalesflareError} If not authenticated or token expired
+     */
+    getAuthHeaders(): Promise<AuthHeaders>;
+    /**
+     * Check if currently authenticated
+     *
+     * Per Phase 1 placeholder: always returns false.
+     *
+     * TODO(Phase 2): Return tokenManager.hasValidToken()
+     *
+     * @returns Always false in Phase 1
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get the authentication type
+     *
+     * @returns 'oauth' to identify this as OAuth authentication
+     */
+    getAuthType(): 'api_key' | 'oauth';
+    /**
+     * Initiate OAuth authentication flow
+     *
+     * This is a placeholder for the full OAuth flow that will be
+     * implemented in Phase 2.
+     *
+     * TODO(Phase 2): Implement built-in local server for OAuth callback
+     * TODO(Phase 2): Implement salesflare_auth_initiate tool
+     *
+     * @throws {SalesflareError} Always throws as OAuth is not yet implemented
+     */
+    initiateAuth(): void;
+}
+//# sourceMappingURL=oauth-auth.d.ts.map

package/dist/auth/oauth-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-auth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAgB,MAAM,oBAAoB,CAAC;AAG7E;;;;;;;;;;GAUG;AACH,qBAAa,SAAU,YAAW,YAAY;IAC5C,sBAAsB;IACtB,OAAO,CAAC,QAAQ,CAAS;IAEzB,0BAA0B;IAC1B,OAAO,CAAC,YAAY,CAAS;IAE7B,yBAAyB;IACzB,OAAO,CAAC,WAAW,CAAS;IAE5B,qCAAqC;IACrC,OAAO,CAAC,YAAY,CAAe;IAEnC;;;;;;OAMG;gBACS,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;IAOvE;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IA2B5C;;;;;;;;OAQG;IACH,eAAe,IAAI,OAAO;IAM1B;;;;OAIG;IACH,WAAW,IAAI,SAAS,GAAG,OAAO;IAIlC;;;;;;;;;;OAUG;IACH,YAAY,IAAI,IAAI;CAUrB"}

package/dist/auth/oauth-auth.js

@@ -0,0 +1,123 @@
+/**
+ * OAuth Authentication placeholder for Salesflare MCP Server
+ *
+ * This is a placeholder implementation for OAuth 2.0 authentication.
+ * Per D-01, full OAuth implementation is deferred to Phase 2.
+ *
+ * The class implements AuthProvider interface but throws errors
+ * for any actual usage, directing users to use API key authentication instead.
+ *
+ * @module auth/oauth-auth
+ */
+import { TokenManager } from './token-manager.js';
+import { SalesflareError, ErrorCode } from '../utils/errors.js';
+/**
+ * OAuth authentication provider (Phase 2 placeholder)
+ *
+ * Implements the AuthProvider interface but is not fully functional.
+ * This is a placeholder that will be completed in Phase 2.
+ *
+ * Per D-01: OAuth deferred to Phase 2.
+ *
+ * @class
+ * @implements {AuthProvider}
+ */
+export class OAuthAuth {
+    /** OAuth client ID */
+    clientId;
+    /** OAuth client secret */
+    clientSecret;
+    /** OAuth redirect URI */
+    redirectUri;
+    /** Token manager for OAuth tokens */
+    tokenManager;
+    /**
+     * Create a new OAuthAuth instance
+     *
+     * @param clientId - OAuth client ID
+     * @param clientSecret - OAuth client secret
+     * @param redirectUri - OAuth redirect URI
+     */
+    constructor(clientId, clientSecret, redirectUri) {
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+        this.redirectUri = redirectUri;
+        this.tokenManager = new TokenManager();
+    }
+    /**
+     * Get authentication headers for API requests
+     *
+     * Returns Authorization header with OAuth access token.
+     *
+     * TODO(Phase 2): Implement token refresh on AUTH_EXPIRED
+     *
+     * @returns Promise resolving to auth headers
+     * @throws {SalesflareError} If not authenticated or token expired
+     */
+    async getAuthHeaders() {
+        const token = this.tokenManager.getAccessToken();
+        if (!token) {
+            throw new SalesflareError({
+                code: ErrorCode.AUTH_INVALID,
+                message: 'OAuth not authenticated. Call salesflare_auth_initiate first.',
+                fix: 'Use API key authentication instead, or wait for Phase 2 OAuth implementation',
+                retryable: false,
+            });
+        }
+        if (this.tokenManager.isTokenExpired()) {
+            // TODO(Phase 2): Implement token refresh on AUTH_EXPIRED
+            throw new SalesflareError({
+                code: ErrorCode.AUTH_EXPIRED,
+                message: 'OAuth token has expired',
+                fix: 'Use API key authentication instead, or wait for Phase 2 OAuth implementation with token refresh',
+                retryable: false,
+            });
+        }
+        return {
+            Authorization: `Bearer ${token}`,
+        };
+    }
+    /**
+     * Check if currently authenticated
+     *
+     * Per Phase 1 placeholder: always returns false.
+     *
+     * TODO(Phase 2): Return tokenManager.hasValidToken()
+     *
+     * @returns Always false in Phase 1
+     */
+    isAuthenticated() {
+        // Phase 1: Return false as placeholder
+        // TODO(Phase 2): Return this.tokenManager.hasValidToken()
+        return false;
+    }
+    /**
+     * Get the authentication type
+     *
+     * @returns 'oauth' to identify this as OAuth authentication
+     */
+    getAuthType() {
+        return 'oauth';
+    }
+    /**
+     * Initiate OAuth authentication flow
+     *
+     * This is a placeholder for the full OAuth flow that will be
+     * implemented in Phase 2.
+     *
+     * TODO(Phase 2): Implement built-in local server for OAuth callback
+     * TODO(Phase 2): Implement salesflare_auth_initiate tool
+     *
+     * @throws {SalesflareError} Always throws as OAuth is not yet implemented
+     */
+    initiateAuth() {
+        // TODO(Phase 2): Implement built-in local server for OAuth callback
+        // TODO(Phase 2): Implement salesflare_auth_initiate tool
+        throw new SalesflareError({
+            code: ErrorCode.AUTH_INVALID,
+            message: 'OAuth authentication not yet implemented. Use API key authentication instead.',
+            fix: 'Set SALESFLARE_API_KEY environment variable and use API key authentication for Phase 1',
+            retryable: false,
+        });
+    }
+}

package/dist/auth/token-manager.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Token manager and authentication provider interfaces
+ *
+ * Provides abstractions for different authentication methods (API key, OAuth)
+ * and token lifecycle management.
+ *
+ * @module auth/token-manager
+ */
+/**
+ * HTTP headers for authentication
+ *
+ * Used by API client to include Authorization header in requests.
+ */
+export interface AuthHeaders {
+    /** Authorization header with Bearer token */
+    Authorization: string;
+    /** Additional headers can be added */
+    [key: string]: string;
+}
+/**
+ * Authentication provider interface
+ *
+ * All authentication methods must implement this interface.
+ * Provides a common way to get auth headers and check auth status.
+ *
+ * @interface
+ */
+export interface AuthProvider {
+    /**
+     * Get authentication headers for API requests
+     *
+     * @returns Promise resolving to auth headers object
+     */
+    getAuthHeaders(): Promise<AuthHeaders>;
+    /**
+     * Check if currently authenticated
+     *
+     * @returns True if authenticated and ready for API calls
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get the authentication type
+     *
+     * @returns 'api_key' for API key auth, 'oauth' for OAuth
+     */
+    getAuthType(): 'api_key' | 'oauth';
+}
+/**
+ * Token manager for OAuth token storage
+ *
+ * Manages access and refresh tokens in memory only (per D-13, D-14).
+ * Tokens are lost on server restart.
+ *
+ * This is primarily used by OAuth authentication. API key authentication
+ * does not use this class.
+ *
+ * @class
+ */
+export declare class TokenManager {
+    /** Current access token */
+    private accessToken;
+    /** Current refresh token */
+    private refreshToken;
+    /** Token expiration timestamp */
+    private expiresAt;
+    /**
+     * Store new tokens
+     *
+     * @param access - The access token
+     * @param refresh - The refresh token
+     * @param expiresIn - Token lifetime in seconds
+     */
+    setTokens(access: string, refresh: string, expiresIn: number): void;
+    /**
+     * Get the current access token
+     *
+     * @returns The access token or null if not set
+     */
+    getAccessToken(): string | null;
+    /**
+     * Get the current refresh token
+     *
+     * @returns The refresh token or null if not set
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Check if the access token is expired
+     *
+     * @returns True if token is expired or not set
+     */
+    isTokenExpired(): boolean;
+    /**
+     * Check if a valid token exists
+     *
+     * @returns True if token exists and is not expired
+     */
+    hasValidToken(): boolean;
+    /**
+     * Clear all stored tokens
+     *
+     * Called on logout or when tokens become invalid.
+     */
+    clearTokens(): void;
+}
+//# sourceMappingURL=token-manager.d.ts.map

package/dist/auth/token-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.d.ts","sourceRoot":"","sources":["../../src/auth/token-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAEvC;;;;OAIG;IACH,eAAe,IAAI,OAAO,CAAC;IAE3B;;;;OAIG;IACH,WAAW,IAAI,SAAS,GAAG,OAAO,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,YAAY;IACvB,2BAA2B;IAC3B,OAAO,CAAC,WAAW,CAAuB;IAE1C,4BAA4B;IAC5B,OAAO,CAAC,YAAY,CAAuB;IAE3C,iCAAiC;IACjC,OAAO,CAAC,SAAS,CAAqB;IAEtC;;;;;;OAMG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAMnE;;;;OAIG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;;;OAIG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC;;;;OAIG;IACH,cAAc,IAAI,OAAO;IAUzB;;;;OAIG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;OAIG;IACH,WAAW,IAAI,IAAI;CAKpB"}

package/dist/auth/token-manager.js

@@ -0,0 +1,87 @@
+/**
+ * Token manager and authentication provider interfaces
+ *
+ * Provides abstractions for different authentication methods (API key, OAuth)
+ * and token lifecycle management.
+ *
+ * @module auth/token-manager
+ */
+/**
+ * Token manager for OAuth token storage
+ *
+ * Manages access and refresh tokens in memory only (per D-13, D-14).
+ * Tokens are lost on server restart.
+ *
+ * This is primarily used by OAuth authentication. API key authentication
+ * does not use this class.
+ *
+ * @class
+ */
+export class TokenManager {
+    /** Current access token */
+    accessToken = null;
+    /** Current refresh token */
+    refreshToken = null;
+    /** Token expiration timestamp */
+    expiresAt = null;
+    /**
+     * Store new tokens
+     *
+     * @param access - The access token
+     * @param refresh - The refresh token
+     * @param expiresIn - Token lifetime in seconds
+     */
+    setTokens(access, refresh, expiresIn) {
+        this.accessToken = access;
+        this.refreshToken = refresh;
+        this.expiresAt = new Date(Date.now() + expiresIn * 1000);
+    }
+    /**
+     * Get the current access token
+     *
+     * @returns The access token or null if not set
+     */
+    getAccessToken() {
+        return this.accessToken;
+    }
+    /**
+     * Get the current refresh token
+     *
+     * @returns The refresh token or null if not set
+     */
+    getRefreshToken() {
+        return this.refreshToken;
+    }
+    /**
+     * Check if the access token is expired
+     *
+     * @returns True if token is expired or not set
+     */
+    isTokenExpired() {
+        if (!this.expiresAt) {
+            return true;
+        }
+        // Consider token expired 60 seconds before actual expiration
+        // to account for clock skew and network latency
+        const bufferMs = 60 * 1000;
+        return Date.now() > this.expiresAt.getTime() - bufferMs;
+    }
+    /**
+     * Check if a valid token exists
+     *
+     * @returns True if token exists and is not expired
+     */
+    hasValidToken() {
+        return this.accessToken !== null && !this.isTokenExpired();
+    }
+    /**
+     * Clear all stored tokens
+     *
+     * Called on logout or when tokens become invalid.
+     */
+    clearTokens() {
+        this.accessToken = null;
+        this.refreshToken = null;
+        this.expiresAt = null;
+    }
+}