@spec2tools/core 0.1.0 → 0.1.1

package/dist/auth-manager.d.ts

@@ -1,32 +1,35 @@
 import { AuthConfig } from './types.js';
 export declare class AuthManager {
-    private authConfig;
+    private globalAuthConfig;
     private accessToken?;
     private refreshToken?;
     private clientId?;
     private clientSecret?;
     private codeVerifier?;
-    constructor(authConfig: AuthConfig);
+    constructor(globalAuthConfig: AuthConfig);
     /**
      * Check if authentication is required
      */
-    requiresAuth(): boolean;
+    requiresAuth(authConfig?: AuthConfig): boolean;
     /**
      * Get the current access token
      */
     getAccessToken(): string | undefined;
     /**
      * Get authorization headers for requests
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    getAuthHeaders(): Record<string, string>;
+    getAuthHeaders(authConfig?: AuthConfig): Record<string, string>;
     /**
      * Get query parameters for API key auth
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    getAuthQueryParams(): Record<string, string>;
+    getAuthQueryParams(authConfig?: AuthConfig): Record<string, string>;
     /**
      * Perform authentication based on config type
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    authenticate(): Promise<void>;
+    authenticate(authConfig?: AuthConfig): Promise<void>;
     /**
      * Prompt user for API key
      */
@@ -35,6 +38,10 @@ export declare class AuthManager {
      * Prompt user for bearer token
      */
     private promptForBearerToken;
+    /**
+     * Prompt user for basic auth credentials
+     */
+    private promptForBasicAuth;
     /**
      * Perform OAuth2 authorization code flow
      */

package/dist/auth-manager.js

@@ -7,20 +7,21 @@ import * as readline from 'readline';
 const CALLBACK_PORT = 54321;
 const CALLBACK_PATH = '/callback';
 export class AuthManager {
-    authConfig;
+    globalAuthConfig;
     accessToken;
     refreshToken;
     clientId;
     clientSecret;
     codeVerifier;
-    constructor(authConfig) {
-        this.authConfig = authConfig;
+    constructor(globalAuthConfig) {
+        this.globalAuthConfig = globalAuthConfig;
     }
     /**
      * Check if authentication is required
      */
-    requiresAuth() {
-        return this.authConfig.type !== 'none';
+    requiresAuth(authConfig) {
+        const config = authConfig ?? this.globalAuthConfig;
+        return config.type !== 'none';
     }
     /**
      * Get the current access token
@@ -30,18 +31,22 @@ export class AuthManager {
     }
     /**
      * Get authorization headers for requests
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    getAuthHeaders() {
+    getAuthHeaders(authConfig) {
         if (!this.accessToken) {
             return {};
         }
-        switch (this.authConfig.type) {
+        const config = authConfig ?? this.globalAuthConfig;
+        switch (config.type) {
             case 'oauth2':
             case 'bearer':
                 return { Authorization: `Bearer ${this.accessToken}` };
+            case 'basic':
+                return { Authorization: `Basic ${this.accessToken}` };
             case 'apiKey':
-                if (this.authConfig.apiKeyIn === 'header' && this.authConfig.apiKeyHeader) {
-                    return { [this.authConfig.apiKeyHeader]: this.accessToken };
+                if (config.apiKeyIn === 'header' && config.apiKeyHeader) {
+                    return { [config.apiKeyHeader]: this.accessToken };
                 }
                 return {};
             default:
@@ -50,30 +55,37 @@ export class AuthManager {
     }
     /**
      * Get query parameters for API key auth
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    getAuthQueryParams() {
-        if (this.authConfig.type === 'apiKey' &&
-            this.authConfig.apiKeyIn === 'query' &&
-            this.authConfig.apiKeyHeader &&
+    getAuthQueryParams(authConfig) {
+        const config = authConfig ?? this.globalAuthConfig;
+        if (config.type === 'apiKey' &&
+            config.apiKeyIn === 'query' &&
+            config.apiKeyHeader &&
             this.accessToken) {
-            return { [this.authConfig.apiKeyHeader]: this.accessToken };
+            return { [config.apiKeyHeader]: this.accessToken };
         }
         return {};
     }
     /**
      * Perform authentication based on config type
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    async authenticate() {
-        switch (this.authConfig.type) {
+    async authenticate(authConfig) {
+        const config = authConfig ?? this.globalAuthConfig;
+        switch (config.type) {
             case 'oauth2':
-                await this.performOAuth2Flow();
+                await this.performOAuth2Flow(config);
                 break;
             case 'apiKey':
-                await this.promptForApiKey();
+                await this.promptForApiKey(config);
                 break;
             case 'bearer':
                 await this.promptForBearerToken();
                 break;
+            case 'basic':
+                await this.promptForBasicAuth();
+                break;
             case 'none':
                 // No authentication needed
                 break;
@@ -82,12 +94,12 @@ export class AuthManager {
     /**
      * Prompt user for API key
      */
-    async promptForApiKey() {
+    async promptForApiKey(config) {
         const rl = readline.createInterface({
             input: process.stdin,
             output: process.stdout,
         });
-        const headerName = this.authConfig.apiKeyHeader || 'API-Key';
+        const headerName = config.apiKeyHeader || 'API-Key';
         this.accessToken = await new Promise((resolve) => {
             rl.question(`Enter your API key (${headerName}): `, (answer) => {
                 rl.close();
@@ -116,26 +128,50 @@ export class AuthManager {
             throw new AuthenticationError('Bearer token is required');
         }
     }
+    /**
+     * Prompt user for basic auth credentials
+     */
+    async promptForBasicAuth() {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const question = (prompt) => {
+            return new Promise((resolve) => {
+                rl.question(prompt, (answer) => {
+                    resolve(answer.trim());
+                });
+            });
+        };
+        const username = await question('Enter username: ');
+        const password = await question('Enter password: ');
+        rl.close();
+        if (!username || !password) {
+            throw new AuthenticationError('Username and password are required for Basic auth');
+        }
+        // Base64 encode the credentials
+        this.accessToken = Buffer.from(`${username}:${password}`).toString('base64');
+    }
     /**
      * Perform OAuth2 authorization code flow
      */
-    async performOAuth2Flow() {
-        if (!this.authConfig.authorizationUrl || !this.authConfig.tokenUrl) {
+    async performOAuth2Flow(config) {
+        if (!config.authorizationUrl || !config.tokenUrl) {
             throw new AuthenticationError('OAuth2 requires authorizationUrl and tokenUrl');
         }
         // Register client dynamically
-        await this.registerClient();
+        await this.registerClient(config);
         // Start local callback server
-        const authCode = await this.startCallbackServerAndAuthorize();
+        const authCode = await this.startCallbackServerAndAuthorize(config);
         // Exchange code for token
-        await this.exchangeCodeForToken(authCode);
+        await this.exchangeCodeForToken(authCode, config);
     }
     /**
      * Register OAuth2 client dynamically
      */
-    async registerClient() {
+    async registerClient(config) {
         // Derive registration URL from token URL (replace /token with /register)
-        const registrationUrl = this.authConfig.tokenUrl.replace(/\/token$/, '/register');
+        const registrationUrl = config.tokenUrl.replace(/\/token$/, '/register');
         const redirectUri = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
         console.log('Registering OAuth2 client...');
         const response = await fetch(registrationUrl, {
@@ -162,7 +198,7 @@ export class AuthManager {
     /**
      * Start local callback server and initiate authorization
      */
-    async startCallbackServerAndAuthorize() {
+    async startCallbackServerAndAuthorize(config) {
         return new Promise((resolve, reject) => {
             const app = express();
             let server;
@@ -211,7 +247,7 @@ export class AuthManager {
             server = createServer(app);
             server.listen(CALLBACK_PORT, '127.0.0.1', () => {
                 const redirectUri = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
-                const authUrl = this.buildAuthorizationUrl(redirectUri);
+                const authUrl = this.buildAuthorizationUrl(redirectUri, config);
                 console.log('\nAuthentication required. Opening browser...');
                 console.log(`If browser doesn't open, visit: ${authUrl}\n`);
                 open(authUrl).catch(() => {
@@ -249,8 +285,8 @@ export class AuthManager {
     /**
      * Build the OAuth2 authorization URL
      */
-    buildAuthorizationUrl(redirectUri) {
-        const url = new URL(this.authConfig.authorizationUrl);
+    buildAuthorizationUrl(redirectUri, config) {
+        const url = new URL(config.authorizationUrl);
         // Generate PKCE
         const pkce = this.generatePKCE();
         this.codeVerifier = pkce.verifier;
@@ -259,8 +295,8 @@ export class AuthManager {
         url.searchParams.set('redirect_uri', redirectUri);
         url.searchParams.set('code_challenge', pkce.challenge);
         url.searchParams.set('code_challenge_method', 'S256');
-        if (this.authConfig.scopes && this.authConfig.scopes.length > 0) {
-            url.searchParams.set('scope', this.authConfig.scopes.join(' '));
+        if (config.scopes && config.scopes.length > 0) {
+            url.searchParams.set('scope', config.scopes.join(' '));
         }
         // Generate state for CSRF protection
         const state = crypto.randomBytes(16).toString('base64url');
@@ -270,7 +306,7 @@ export class AuthManager {
     /**
      * Exchange authorization code for access token
      */
-    async exchangeCodeForToken(code) {
+    async exchangeCodeForToken(code, config) {
         const redirectUri = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
         const params = new URLSearchParams({
             grant_type: 'authorization_code',
@@ -283,7 +319,7 @@ export class AuthManager {
         if (this.clientSecret) {
             params.set('client_secret', this.clientSecret);
         }
-        const response = await fetch(this.authConfig.tokenUrl, {
+        const response = await fetch(config.tokenUrl, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/x-www-form-urlencoded',

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { UnsupportedSchemaError, AuthenticationError, ToolExecutionError, SpecLoadError, } from './errors.js';
 export type { HttpMethod, Tool, AuthType, AuthConfig, Session, OpenAPISpec, PathItem, Operation, Parameter, RequestBody, MediaType, Response, SchemaObject, SecurityScheme, } from './types.js';
-export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
+export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, extractOperationAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
 export { AuthManager } from './auth-manager.js';
 export { createExecutableTools, executeToolByName } from './tool-executor.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,7 +1,7 @@
 // Error classes
 export { UnsupportedSchemaError, AuthenticationError, ToolExecutionError, SpecLoadError, } from './errors.js';
 // OpenAPI Parser
-export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
+export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, extractOperationAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
 // Auth Manager
 export { AuthManager } from './auth-manager.js';
 // Tool Executor

package/dist/openapi-parser.d.ts

@@ -1,4 +1,4 @@
-import { OpenAPISpec, Tool, AuthConfig } from './types.js';
+import { OpenAPISpec, Operation, Tool, AuthConfig } from './types.js';
 /**
  * Fetch and parse an OpenAPI specification from URL or file path
  */
@@ -11,6 +11,11 @@ export declare function extractBaseUrl(spec: OpenAPISpec): string;
  * Extract authentication configuration from security schemes
  */
 export declare function extractAuthConfig(spec: OpenAPISpec): AuthConfig;
+/**
+ * Extract authentication configuration for a specific operation
+ * Uses operation-level security if defined, otherwise falls back to global security
+ */
+export declare function extractOperationAuthConfig(spec: OpenAPISpec, operation: Operation): AuthConfig;
 /**
  * Parse all operations from the OpenAPI spec and generate tool definitions
  */

package/dist/openapi-parser.js

@@ -47,13 +47,33 @@ export function extractBaseUrl(spec) {
  * Extract authentication configuration from security schemes
  */
 export function extractAuthConfig(spec) {
-    const securitySchemes = spec.components?.securitySchemes;
-    const globalSecurity = spec.security;
-    if (!securitySchemes || !globalSecurity || globalSecurity.length === 0) {
+    return extractAuthConfigFromSecurity(spec.security, spec.components?.securitySchemes);
+}
+/**
+ * Extract authentication configuration for a specific operation
+ * Uses operation-level security if defined, otherwise falls back to global security
+ */
+export function extractOperationAuthConfig(spec, operation) {
+    // If operation has its own security field, use it (even if empty array = no auth)
+    if (operation.security !== undefined) {
+        return extractAuthConfigFromSecurity(operation.security, spec.components?.securitySchemes);
+    }
+    // Fall back to global security
+    return extractAuthConfig(spec);
+}
+/**
+ * Extract auth config from a security requirement array
+ */
+function extractAuthConfigFromSecurity(security, securitySchemes) {
+    // Empty security array means explicitly no auth required
+    if (security !== undefined && security.length === 0) {
+        return { type: 'none' };
+    }
+    if (!securitySchemes || !security || security.length === 0) {
         return { type: 'none' };
     }
     // Get the first security requirement
-    const securityReq = globalSecurity[0];
+    const securityReq = security[0];
     const schemeName = Object.keys(securityReq)[0];
     const scheme = securitySchemes[schemeName];
     if (!scheme) {
@@ -84,6 +104,9 @@ function parseSecurityScheme(scheme, scopes) {
     if (scheme.type === 'http' && scheme.scheme === 'bearer') {
         return { type: 'bearer' };
     }
+    if (scheme.type === 'http' && scheme.scheme === 'basic') {
+        return { type: 'basic' };
+    }
     return { type: 'none' };
 }
 /**
@@ -273,12 +296,15 @@ export function parseOperations(spec) {
             const bodyShape = buildRequestBodySchema(operation, operationId);
             const combinedShape = { ...parameterShape, ...bodyShape };
             const parameters = z.object(combinedShape);
+            // Extract operation-specific auth config
+            const authConfig = extractOperationAuthConfig(spec, operation);
             tools.push({
                 name: operationId,
                 description: operation.summary || operation.description || `${method} ${path}`,
                 parameters,
                 httpMethod: method,
                 path,
+                authConfig,
             });
         }
     }

package/dist/tool-executor.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Tool, HttpMethod } from './types.js';
+import { Tool, HttpMethod, AuthConfig } from './types.js';
 import { AuthManager } from './auth-manager.js';
 interface ToolDefinition {
     name: string;
@@ -7,6 +7,7 @@ interface ToolDefinition {
     parameters: z.ZodObject<z.ZodRawShape>;
     httpMethod: HttpMethod;
     path: string;
+    authConfig?: AuthConfig;
 }
 /**
  * Create executable tools from tool definitions

package/dist/tool-executor.js

@@ -28,15 +28,20 @@ function createExecutor(tool, baseUrl, authManager) {
                     urlObj.searchParams.set(key, String(value));
                 }
             }
+            // Check if this tool requires auth (respects operation-level security)
+            // Tool-level authConfig overrides the global authConfig
+            const toolRequiresAuth = authManager.requiresAuth(tool.authConfig);
             // Add auth query params if needed
-            const authQueryParams = authManager.getAuthQueryParams();
-            for (const [key, value] of Object.entries(authQueryParams)) {
-                urlObj.searchParams.set(key, value);
+            if (toolRequiresAuth) {
+                const authQueryParams = authManager.getAuthQueryParams(tool.authConfig);
+                for (const [key, value] of Object.entries(authQueryParams)) {
+                    urlObj.searchParams.set(key, value);
+                }
             }
             url = urlObj.toString();
             // Build request options
             const headers = {
-                ...authManager.getAuthHeaders(),
+                ...(toolRequiresAuth ? authManager.getAuthHeaders(tool.authConfig) : {}),
             };
             const fetchOptions = {
                 method: tool.httpMethod,
@@ -62,7 +67,29 @@ function createExecutor(tool, baseUrl, authManager) {
                 responseData = await response.text();
             }
             if (!response.ok) {
-                throw new Error(`HTTP ${response.status}: ${JSON.stringify(responseData)}`);
+                // Build detailed error message
+                const errorDetails = [
+                    `HTTP ${response.status} ${response.statusText}`,
+                    `URL: ${tool.httpMethod} ${url}`,
+                    `Response: ${typeof responseData === 'string' ? responseData : JSON.stringify(responseData, null, 2)}`
+                ];
+                // Add helpful context for common errors
+                if (response.status === 401) {
+                    errorDetails.push('Authentication failed. Check your API key/token.');
+                }
+                else if (response.status === 403) {
+                    errorDetails.push('Access forbidden. Verify your permissions.');
+                }
+                else if (response.status === 404) {
+                    errorDetails.push('Resource not found.');
+                }
+                else if (response.status === 429) {
+                    errorDetails.push('Rate limit exceeded. Try again later.');
+                }
+                else if (response.status >= 500) {
+                    errorDetails.push('Server error. The API service may be experiencing issues.');
+                }
+                throw new Error(errorDetails.join('\n'));
             }
             return responseData;
         }

package/dist/types.d.ts

@@ -7,8 +7,9 @@ export interface Tool {
     execute: (params: unknown) => Promise<unknown>;
     httpMethod: HttpMethod;
     path: string;
+    authConfig?: AuthConfig;
 }
-export type AuthType = 'oauth2' | 'apiKey' | 'bearer' | 'none';
+export type AuthType = 'oauth2' | 'apiKey' | 'bearer' | 'basic' | 'none';
 export interface AuthConfig {
     type: AuthType;
     authorizationUrl?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec2tools/core",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Core utilities for OpenAPI parsing and authentication",
   "type": "module",
   "main": "dist/index.js",