sqlew 3.6.9 → 3.7.0

package/dist/adapters/auth/direct-auth-provider.js

@@ -0,0 +1,406 @@
+/**
+ * @fileoverview Direct authentication provider for sqlew's multi-RDBMS system.
+ *
+ * This module implements direct database connections without intermediate tunneling
+ * or proxy mechanisms. It provides the simplest authentication method, suitable for:
+ * - Local database instances
+ * - Docker containers on the same network
+ * - On-premise servers with direct network access
+ * - Cloud databases with public endpoints
+ *
+ * **Use Cases:**
+ * - Development environments with local PostgreSQL/MySQL instances
+ * - Docker Compose services with service-to-service connections
+ * - On-premise data centers with internal network access
+ * - Cloud RDS/Cloud SQL instances with allowlisted IP addresses
+ *
+ * **Security Considerations:**
+ * - Supports SSL/TLS encryption for secure connections
+ * - Password is optional to support future IAM authentication
+ * - No intermediate resources to manage (unlike SSH tunnels)
+ * - Direct exposure to database port (ensure proper firewall rules)
+ *
+ * @module adapters/auth/direct-auth-provider
+ * @since v3.7.0
+ */
+import { BaseAuthProvider } from './base-auth-provider.js';
+/**
+ * Direct database authentication provider.
+ *
+ * Provides straightforward database connections without tunneling, proxy servers,
+ * or token generation. The provider validates configuration and returns connection
+ * parameters directly from the config object.
+ *
+ * **Authentication Flow:**
+ * 1. `validate()` - Verify required configuration fields (host, port, database, user)
+ * 2. `authenticate()` - Return connection parameters directly (no external calls)
+ * 3. Database connection uses provided credentials
+ * 4. `cleanup()` - No-op (no resources to release)
+ *
+ * **Configuration Requirements:**
+ * - Database host address
+ * - Database port number
+ * - Database name
+ * - Database username
+ * - Database password (optional for future IAM support)
+ * - Optional SSL configuration for encrypted connections
+ *
+ * @class DirectAuthProvider
+ * @extends {BaseAuthProvider}
+ *
+ * @example
+ * // Local PostgreSQL connection
+ * const config: DatabaseConfig = {
+ *   type: 'postgres',
+ *   connection: {
+ *     host: 'localhost',
+ *     port: 5432,
+ *     database: 'dev_db'
+ *   },
+ *   auth: {
+ *     type: 'direct',
+ *     user: 'postgres',
+ *     password: 'postgres'
+ *   }
+ * };
+ *
+ * const provider = new DirectAuthProvider(config);
+ * provider.validate();
+ * const connParams = await provider.authenticate();
+ * // connParams.host = 'localhost'
+ * // connParams.port = 5432
+ *
+ * @example
+ * // Docker MySQL connection with SSL
+ * const config: DatabaseConfig = {
+ *   type: 'mysql',
+ *   connection: {
+ *     host: 'mysql-container',
+ *     port: 3306,
+ *     database: 'app_db'
+ *   },
+ *   auth: {
+ *     type: 'direct',
+ *     user: 'root',
+ *     password: 'root_password',
+ *     ssl: {
+ *       ca: '/path/to/ca.pem',
+ *       rejectUnauthorized: true
+ *     }
+ *   }
+ * };
+ *
+ * @example
+ * // Cloud RDS connection with SSL (production)
+ * const config: DatabaseConfig = {
+ *   type: 'postgres',
+ *   connection: {
+ *     host: 'mydb.abc123.us-east-1.rds.amazonaws.com',
+ *     port: 5432,
+ *     database: 'production'
+ *   },
+ *   auth: {
+ *     type: 'direct',
+ *     user: 'admin',
+ *     password: 'secure_password_123',
+ *     ssl: {
+ *       ca: '/etc/ssl/rds-ca-bundle.pem',
+ *       rejectUnauthorized: true
+ *     }
+ *   }
+ * };
+ *
+ * @example
+ * // Complete usage with cleanup (cleanup is no-op for direct connections)
+ * const provider = new DirectAuthProvider(config);
+ * try {
+ *   provider.validate();
+ *   const params = await provider.authenticate();
+ *   const db = await createDatabaseConnection(params);
+ *   await db.query('SELECT 1');
+ *   await db.close();
+ * } finally {
+ *   await provider.cleanup(); // No-op, but good practice
+ * }
+ *
+ * @example
+ * // Future IAM authentication (password optional)
+ * const config: DatabaseConfig = {
+ *   type: 'postgres',
+ *   connection: {
+ *     host: 'mydb.region.rds.amazonaws.com',
+ *     port: 5432,
+ *     database: 'production'
+ *   },
+ *   auth: {
+ *     type: 'direct',
+ *     user: 'iam_user'
+ *     // password will be generated by IAM provider
+ *   }
+ * };
+ */
+export class DirectAuthProvider extends BaseAuthProvider {
+    /**
+     * Returns the authentication method name for logging and diagnostics.
+     *
+     * @returns {string} 'Direct Connection'
+     *
+     * @example
+     * const provider = new DirectAuthProvider(config);
+     * console.log(provider.getAuthMethod()); // 'Direct Connection'
+     */
+    getAuthMethod() {
+        return 'Direct Connection';
+    }
+    /**
+     * Validates direct connection configuration before authentication.
+     *
+     * **Validation Checks:**
+     * - Connection config object exists
+     * - Database host is specified
+     * - Database port is specified
+     * - Database name is specified
+     * - Database user is specified
+     * - Password is optional (for future IAM authentication support)
+     *
+     * This method should be called immediately after provider instantiation
+     * to fail fast on configuration errors before attempting database connections.
+     *
+     * @throws {Error} 'Connection configuration is required for DirectAuthProvider'
+     * @throws {Error} 'Database host, port, and database name are required'
+     * @throws {Error} 'Database user is required for direct authentication'
+     *
+     * @example
+     * const provider = new DirectAuthProvider(config);
+     * try {
+     *   provider.validate();
+     *   // Configuration is valid, proceed with authentication
+     * } catch (error) {
+     *   console.error('Invalid configuration:', error.message);
+     *   // Fix configuration before retrying
+     * }
+     *
+     * @example
+     * // Missing connection config
+     * const invalidConfig = { type: 'postgres', auth: { type: 'direct' } };
+     * const provider = new DirectAuthProvider(invalidConfig);
+     * provider.validate(); // Throws: 'Connection configuration is required for DirectAuthProvider'
+     *
+     * @example
+     * // Missing database user
+     * const config = {
+     *   connection: {
+     *     host: 'localhost',
+     *     port: 5432,
+     *     database: 'mydb'
+     *   },
+     *   auth: {
+     *     type: 'direct'
+     *     // Missing user field
+     *   }
+     * };
+     * const provider = new DirectAuthProvider(config);
+     * provider.validate(); // Throws: 'Database user is required for direct authentication'
+     *
+     * @example
+     * // Valid config (password optional)
+     * const config = {
+     *   connection: {
+     *     host: 'localhost',
+     *     port: 5432,
+     *     database: 'mydb'
+     *   },
+     *   auth: {
+     *     type: 'direct',
+     *     user: 'postgres'
+     *     // password is optional (for future IAM support)
+     *   }
+     * };
+     * const provider = new DirectAuthProvider(config);
+     * provider.validate(); // Success - password is optional
+     */
+    validate() {
+        // Check connection config exists
+        if (!this.config.connection) {
+            throw new Error('Connection configuration is required for DirectAuthProvider');
+        }
+        const conn = this.config.connection;
+        // Check required connection parameters
+        if (!conn.host || !conn.port || !conn.database) {
+            throw new Error('Database host, port, and database name are required');
+        }
+        // Check authentication config exists
+        if (!this.config.auth) {
+            throw new Error('Authentication configuration is required for DirectAuthProvider');
+        }
+        // Check required auth parameters
+        // Note: password is optional to support future IAM authentication
+        if (!this.config.auth.user) {
+            throw new Error('Database user is required for direct authentication');
+        }
+    }
+    /**
+     * Authenticates and returns connection parameters for direct database connection.
+     *
+     * This method:
+     * 1. Validates configuration (defensive check)
+     * 2. Extracts connection and authentication parameters
+     * 3. Constructs ConnectionParams object
+     * 4. Returns parameters immediately (no async operations)
+     *
+     * **Connection Parameters:**
+     * - `host`: Database host address from config
+     * - `port`: Database port number from config
+     * - `database`: Database name from config
+     * - `user`: Database username from config
+     * - `password`: Database password from config (optional)
+     * - `ssl`: SSL configuration from config (optional)
+     *
+     * **Important Notes:**
+     * - No external resources are created (unlike SSH tunnels)
+     * - Returns synchronously despite Promise signature (for consistency with base class)
+     * - Password is optional to support future IAM authentication methods
+     * - SSL configuration is passed through unchanged for database client to handle
+     *
+     * @returns {Promise<ConnectionParams>} Connection parameters for database client
+     *
+     * @throws {Error} If configuration is invalid (call `validate()` first)
+     *
+     * @example
+     * // Basic authentication flow
+     * const provider = new DirectAuthProvider(config);
+     * provider.validate();
+     * const params = await provider.authenticate();
+     * console.log(params);
+     * // {
+     * //   host: 'localhost',
+     * //   port: 5432,
+     * //   database: 'dev_db',
+     * //   user: 'postgres',
+     * //   password: 'postgres'
+     * // }
+     *
+     * @example
+     * // With SSL configuration preserved
+     * const config = {
+     *   connection: { host: 'db.example.com', port: 5432, database: 'app' },
+     *   auth: {
+     *     type: 'direct',
+     *     user: 'admin',
+     *     password: 'secret',
+     *     ssl: {
+     *       ca: '/path/to/ca.pem',
+     *       rejectUnauthorized: true
+     *     }
+     *   }
+     * };
+     * const provider = new DirectAuthProvider(config);
+     * const params = await provider.authenticate();
+     * // SSL config passed through to database client
+     * // params.ssl.ca = '/path/to/ca.pem'
+     *
+     * @example
+     * // Without password (future IAM authentication)
+     * const config = {
+     *   connection: { host: 'db.example.com', port: 5432, database: 'app' },
+     *   auth: {
+     *     type: 'direct',
+     *     user: 'iam_user'
+     *     // password will be generated by IAM provider
+     *   }
+     * };
+     * const provider = new DirectAuthProvider(config);
+     * const params = await provider.authenticate();
+     * // params.password will be undefined
+     *
+     * @example
+     * // Error handling (validation errors)
+     * const provider = new DirectAuthProvider(invalidConfig);
+     * try {
+     *   const params = await provider.authenticate();
+     * } catch (error) {
+     *   if (error.message.includes('host')) {
+     *     console.error('Missing database host');
+     *   } else if (error.message.includes('user')) {
+     *     console.error('Missing database user');
+     *   }
+     * }
+     */
+    async authenticate() {
+        // Validate before proceeding (defensive check)
+        this.validate();
+        // Build connection parameters directly from config
+        // Non-null assertions safe after validate()
+        const params = {
+            host: this.config.connection.host,
+            port: this.config.connection.port,
+            database: this.config.connection.database,
+            user: this.config.auth.user,
+            password: this.config.auth.password,
+        };
+        // Preserve SSL configuration if present
+        if (this.config.auth.ssl) {
+            params.ssl = {
+                ca: this.config.auth.ssl.ca,
+                cert: this.config.auth.ssl.cert,
+                key: this.config.auth.ssl.key,
+                rejectUnauthorized: this.config.auth.ssl.rejectUnauthorized,
+            };
+        }
+        return params;
+    }
+    /**
+     * Cleanup method for direct connections (no-op).
+     *
+     * Since direct connections do not create any intermediate resources
+     * (no SSH tunnels, proxy servers, or temporary tokens), this method
+     * has nothing to clean up. It is implemented as a no-op for consistency
+     * with the BaseAuthProvider interface.
+     *
+     * **Cleanup Behavior:**
+     * - No-op (does nothing)
+     * - Idempotent (safe to call multiple times)
+     * - Returns immediately
+     * - Never throws errors
+     *
+     * This method exists to maintain API consistency with other auth providers
+     * that DO require cleanup (e.g., SSHAuthProvider closes tunnels).
+     *
+     * @returns {Promise<void>}
+     *
+     * @example
+     * // Basic cleanup (no-op)
+     * const provider = new DirectAuthProvider(config);
+     * const params = await provider.authenticate();
+     * // ... use database connection ...
+     * await provider.cleanup(); // Does nothing, but good practice
+     *
+     * @example
+     * // Cleanup in finally block (recommended pattern)
+     * const provider = new DirectAuthProvider(config);
+     * try {
+     *   const params = await provider.authenticate();
+     *   const db = await connect(params);
+     *   await db.query('SELECT 1');
+     * } finally {
+     *   // Always cleanup, even though it's a no-op for direct connections
+     *   // This ensures consistency when switching between auth providers
+     *   await provider.cleanup();
+     * }
+     *
+     * @example
+     * // Multiple cleanup calls (idempotent, no-op)
+     * await provider.cleanup(); // No-op
+     * await provider.cleanup(); // Still no-op
+     * await provider.cleanup(); // Always no-op
+     */
+    async cleanup() {
+        // No-op: direct connections have no resources to clean up
+        // Unlike SSH tunnels, there are no:
+        // - Active SSH connections to close
+        // - Local ports to release
+        // - Temporary tokens to invalidate
+        // - Proxy servers to terminate
+    }
+}
+//# sourceMappingURL=direct-auth-provider.js.map

package/dist/adapters/auth/direct-auth-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-auth-provider.js","sourceRoot":"","sources":["../../../src/adapters/auth/direct-auth-provider.ts"],"names":[],"mappings":"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"}