sqlew 3.6.10 → 3.7.0

package/dist/adapters/auth/direct-auth-provider.d.ts

@@ -0,0 +1,356 @@
+/**
+ * @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, type ConnectionParams } 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 declare 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(): string;
+    /**
+     * 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(): void;
+    /**
+     * 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');
+     *   }
+     * }
+     */
+    authenticate(): Promise<ConnectionParams>;
+    /**
+     * 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
+     */
+    cleanup(): Promise<void>;
+}
+//# sourceMappingURL=direct-auth-provider.d.ts.map

package/dist/adapters/auth/direct-auth-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct-auth-provider.d.ts","sourceRoot":"","sources":["../../../src/adapters/auth/direct-auth-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGlF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkHG;AACH,qBAAa,kBAAmB,SAAQ,gBAAgB;IACtD;;;;;;;;OAQG;IACH,aAAa,IAAI,MAAM;IAIvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkEG;IACH,QAAQ,IAAI,IAAI;IAyBhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsFG;IACG,YAAY,IAAI,OAAO,CAAC,gBAAgB,CAAC;IA2B/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAQ/B"}