@qwickapps/server 1.5.2 → 1.6.1

package/dist/plugins/api-keys/stores/postgres-store.js

@@ -0,0 +1,360 @@
+/**
+ * PostgreSQL API Keys Store
+ *
+ * API key storage implementation using PostgreSQL with Row-Level Security (RLS).
+ * Uses SHA-256 for token hashing (high-entropy keys don't need bcrypt's slowness).
+ *
+ * RLS Context Pattern:
+ * Each operation uses an explicit transaction and sets `app.current_user_id`
+ * as a transaction-local configuration variable. The RLS policy checks this
+ * variable to enforce that users can only access their own API keys.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import crypto from 'crypto';
+import { getLogger } from '@qwickapps/logging';
+// ============================================================================
+// Logging
+// ============================================================================
+const logger = getLogger('api-keys');
+// ============================================================================
+// Token Generation and Hashing
+// ============================================================================
+/**
+ * Generate a cryptographically secure API key
+ *
+ * Token format: `qk_<env>_<32 bytes base64url>`
+ * - qk = QwickApps
+ * - env = live or test
+ * - 32 random bytes = high entropy secret
+ *
+ * @param isTest Whether this is a test key (default: false)
+ * @returns Object with plaintext key, hash, and prefix
+ */
+function generateApiKey(isTest = false) {
+    const env = isTest ? 'test' : 'live';
+    const randomBytes = crypto.randomBytes(32);
+    const secret = randomBytes.toString('base64url');
+    const key = `qk_${env}_${secret}`;
+    // Hash the key for storage (SHA-256 is appropriate for high-entropy tokens)
+    const hash = crypto.createHash('sha256').update(key).digest('hex');
+    // Prefix for identification (first 12 characters)
+    const prefix = key.substring(0, 12);
+    return { key, hash, prefix };
+}
+/**
+ * Hash an API key using SHA-256
+ *
+ * We use SHA-256 instead of bcrypt because:
+ * 1. API keys are high-entropy (32 random bytes)
+ * 2. No need for slow hashing (not user passwords)
+ * 3. Faster verification for high-throughput API calls
+ *
+ * @param key Plaintext API key
+ * @returns Hex-encoded SHA-256 hash
+ */
+function hashApiKey(key) {
+    return crypto.createHash('sha256').update(key).digest('hex');
+}
+/**
+ * Verify an API key against its stored hash
+ *
+ * Uses constant-time comparison to prevent timing attacks.
+ *
+ * @param key Plaintext API key
+ * @param storedHash Hash from database
+ * @returns True if key matches hash
+ */
+function verifyApiKey(key, storedHash) {
+    const keyHash = hashApiKey(key);
+    // Constant-time comparison
+    return crypto.timingSafeEqual(Buffer.from(keyHash, 'hex'), Buffer.from(storedHash, 'hex'));
+}
+/**
+ * Extract prefix from API key
+ *
+ * @param key Plaintext API key
+ * @returns Key prefix (first 12 characters)
+ */
+function getKeyPrefix(key) {
+    return key.substring(0, 12);
+}
+/**
+ * Validate API key format
+ *
+ * @param key Key to validate
+ * @returns True if format is valid
+ */
+function isValidKeyFormat(key) {
+    // Must start with qk_live_ or qk_test_
+    if (!key.startsWith('qk_live_') && !key.startsWith('qk_test_')) {
+        return false;
+    }
+    // Extract secret part
+    const parts = key.split('_');
+    if (parts.length !== 3) {
+        return false;
+    }
+    const secret = parts[2];
+    // Validate length (32 bytes base64url = 43 characters)
+    if (secret.length !== 43) {
+        return false;
+    }
+    // Validate characters (base64url: A-Za-z0-9_-)
+    const base64urlPattern = /^[A-Za-z0-9_-]+$/;
+    return base64urlPattern.test(secret);
+}
+// ============================================================================
+// RLS Helper
+// ============================================================================
+/**
+ * Execute a function within an RLS-protected transaction
+ *
+ * This helper ensures that:
+ * 1. All queries run within the same transaction
+ * 2. The RLS context is set before any data access
+ * 3. The transaction is properly committed or rolled back
+ *
+ * @param pool PostgreSQL pool
+ * @param userId User ID to set as the RLS context
+ * @param callback Function to execute within the transaction
+ */
+async function withRLSContext(pool, userId, callback) {
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        // Set transaction-local user context for RLS
+        await client.query("SELECT set_config('app.current_user_id', $1, true)", [userId]);
+        const result = await callback(client);
+        await client.query('COMMIT');
+        return result;
+    }
+    catch (error) {
+        await client.query('ROLLBACK');
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+// ============================================================================
+// PostgreSQL Store Implementation
+// ============================================================================
+/**
+ * Create a PostgreSQL API keys store with RLS
+ *
+ * @param config Configuration including a pg Pool instance
+ * @returns ApiKeyStore implementation
+ *
+ * @example
+ * ```ts
+ * import { Pool } from 'pg';
+ * import { postgresApiKeyStore } from '@qwickapps/server';
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const store = postgresApiKeyStore({ pool });
+ *
+ * // Or with lazy initialization:
+ * const store = postgresApiKeyStore({ pool: () => getPostgres().getPool() });
+ * ```
+ */
+export function postgresApiKeyStore(config) {
+    const { pool: poolOrFn, tableName = 'api_keys', schema = 'public', autoCreateTables = true, enableRLS = true, defaultExpirationDays = 90, environment = process.env.NODE_ENV === 'production' ? 'live' : 'test', } = config;
+    // Validate environment configuration
+    if (environment !== 'test' && environment !== 'live') {
+        throw new Error(`Invalid environment: "${environment}". Must be "test" or "live". ` +
+            `Check your PostgresApiKeyStoreConfig.environment setting.`);
+    }
+    // Helper to get pool (supports lazy initialization via function)
+    const getPool = () => {
+        const pool = typeof poolOrFn === 'function' ? poolOrFn() : poolOrFn;
+        if (!pool || typeof pool.query !== 'function') {
+            throw new Error('Invalid pool: must have query method');
+        }
+        return pool;
+    };
+    const tableFullName = `"${schema}"."${tableName}"`;
+    return {
+        name: 'postgres',
+        async initialize() {
+            if (!autoCreateTables)
+                return;
+            const pool = getPool();
+            // Create table with foreign key to users
+            await pool.query(`
+        CREATE TABLE IF NOT EXISTS ${tableFullName} (
+          id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+          user_id UUID NOT NULL REFERENCES "public"."users"(id) ON DELETE CASCADE,
+          name VARCHAR(255) NOT NULL,
+          key_hash VARCHAR(64) NOT NULL,
+          key_prefix VARCHAR(12) NOT NULL,
+          key_type VARCHAR(10) NOT NULL CHECK (key_type IN ('m2m', 'pat')),
+          scopes TEXT[] NOT NULL DEFAULT '{}',
+          last_used_at TIMESTAMPTZ,
+          expires_at TIMESTAMPTZ,
+          is_active BOOLEAN NOT NULL DEFAULT true,
+          created_at TIMESTAMPTZ DEFAULT NOW(),
+          updated_at TIMESTAMPTZ DEFAULT NOW()
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_user_id ON ${tableFullName}(user_id);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_key_prefix ON ${tableFullName}(key_prefix);
+        CREATE INDEX IF NOT EXISTS idx_${tableName}_key_hash ON ${tableFullName}(key_hash);
+      `);
+            // Enable RLS if configured
+            if (enableRLS) {
+                await pool.query(`
+          ALTER TABLE ${tableFullName} ENABLE ROW LEVEL SECURITY;
+          ALTER TABLE ${tableFullName} FORCE ROW LEVEL SECURITY;
+        `);
+                // Create or replace the RLS policy
+                await pool.query(`
+          DROP POLICY IF EXISTS "${tableName}_owner" ON ${tableFullName};
+        `);
+                // RLS policy: users can only access their own keys
+                await pool.query(`
+          CREATE POLICY "${tableName}_owner" ON ${tableFullName}
+            FOR ALL
+            USING (user_id::text = current_setting('app.current_user_id', true))
+            WITH CHECK (user_id::text = current_setting('app.current_user_id', true));
+        `);
+            }
+        },
+        async create(params) {
+            const { user_id, name, key_type, scopes, expires_at } = params;
+            // Generate API key based on configured environment
+            const isTest = environment === 'test';
+            const { key: plaintextKey, hash, prefix } = generateApiKey(isTest);
+            // Calculate expiration if not provided
+            const expiration = expires_at || (defaultExpirationDays !== null
+                ? new Date(Date.now() + defaultExpirationDays * 24 * 60 * 60 * 1000)
+                : null);
+            return withRLSContext(getPool(), user_id, async (client) => {
+                const result = await client.query(`INSERT INTO ${tableFullName}
+           (user_id, name, key_hash, key_prefix, key_type, scopes, expires_at)
+           VALUES ($1, $2, $3, $4, $5, $6, $7)
+           RETURNING *`, [user_id, name, hash, prefix, key_type, scopes, expiration]);
+                const row = result.rows[0];
+                logger.info('API key created', {
+                    action: 'api_key.created',
+                    user_id,
+                    key_id: row.id,
+                    key_prefix: row.key_prefix,
+                    key_type: row.key_type,
+                    scopes: row.scopes,
+                    timestamp: new Date().toISOString(),
+                });
+                return {
+                    ...row,
+                    plaintext_key: plaintextKey,
+                };
+            });
+        },
+        async list(userId) {
+            return withRLSContext(getPool(), userId, async (client) => {
+                const result = await client.query(`SELECT * FROM ${tableFullName} WHERE user_id = $1 ORDER BY created_at DESC`, [userId]);
+                return result.rows;
+            });
+        },
+        async get(userId, keyId) {
+            return withRLSContext(getPool(), userId, async (client) => {
+                const result = await client.query(`SELECT * FROM ${tableFullName} WHERE user_id = $1 AND id = $2`, [userId, keyId]);
+                if (result.rows.length === 0) {
+                    return null;
+                }
+                return result.rows[0];
+            });
+        },
+        async verify(plaintextKey) {
+            // Validate format first
+            if (!isValidKeyFormat(plaintextKey)) {
+                return null;
+            }
+            const pool = getPool();
+            const prefix = getKeyPrefix(plaintextKey);
+            // Find key by prefix (no RLS needed for verification)
+            const result = await pool.query(`SELECT * FROM ${tableFullName}
+         WHERE key_prefix = $1 AND is_active = true`, [prefix]);
+            if (result.rows.length === 0) {
+                return null;
+            }
+            const key = result.rows[0];
+            // Verify hash
+            if (!verifyApiKey(plaintextKey, key.key_hash)) {
+                return null;
+            }
+            // Check expiration
+            if (key.expires_at && new Date() > new Date(key.expires_at)) {
+                return null;
+            }
+            return key;
+        },
+        async update(userId, keyId, params) {
+            const updates = [];
+            const values = [userId, keyId];
+            let paramIndex = 3;
+            if (params.name !== undefined) {
+                updates.push(`name = $${paramIndex++}`);
+                values.push(params.name);
+            }
+            if (params.scopes !== undefined) {
+                updates.push(`scopes = $${paramIndex++}`);
+                values.push(params.scopes);
+            }
+            if (params.expires_at !== undefined) {
+                updates.push(`expires_at = $${paramIndex++}`);
+                values.push(params.expires_at);
+            }
+            if (params.is_active !== undefined) {
+                updates.push(`is_active = $${paramIndex++}`);
+                values.push(params.is_active);
+            }
+            if (updates.length === 0) {
+                // No updates, just return current key
+                return this.get(userId, keyId);
+            }
+            updates.push(`updated_at = NOW()`);
+            return withRLSContext(getPool(), userId, async (client) => {
+                const result = await client.query(`UPDATE ${tableFullName}
+           SET ${updates.join(', ')}
+           WHERE user_id = $1 AND id = $2
+           RETURNING *`, values);
+                if (result.rows.length === 0) {
+                    return null;
+                }
+                const updatedKey = result.rows[0];
+                logger.info('API key updated', {
+                    action: 'api_key.updated',
+                    user_id: userId,
+                    key_id: keyId,
+                    changes: Object.keys(params),
+                    timestamp: new Date().toISOString(),
+                });
+                return updatedKey;
+            });
+        },
+        async delete(userId, keyId) {
+            return withRLSContext(getPool(), userId, async (client) => {
+                const result = await client.query(`DELETE FROM ${tableFullName} WHERE user_id = $1 AND id = $2`, [userId, keyId]);
+                const deleted = (result.rowCount ?? 0) > 0;
+                if (deleted) {
+                    logger.info('API key deleted', {
+                        action: 'api_key.deleted',
+                        user_id: userId,
+                        key_id: keyId,
+                        timestamp: new Date().toISOString(),
+                    });
+                }
+                return deleted;
+            });
+        },
+        async recordUsage(keyId) {
+            const pool = getPool();
+            await pool.query(`UPDATE ${tableFullName} SET last_used_at = NOW() WHERE id = $1`, [keyId]);
+        },
+        async shutdown() {
+            // Pool is managed externally, nothing to do here
+        },
+    };
+}
+//# sourceMappingURL=postgres-store.js.map

package/dist/plugins/api-keys/stores/postgres-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres-store.js","sourceRoot":"","sources":["../../../../src/plugins/api-keys/stores/postgres-store.ts"],"names":[],"mappings":"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"}

package/dist/plugins/api-keys/stores/usage-log-store.d.ts

@@ -0,0 +1,119 @@
+/**
+ * API Key Usage Log Store - PostgreSQL Implementation
+ *
+ * Tracks all API calls made with API keys for audit trails and usage analytics.
+ * Uses table partitioning for efficient storage and querying of large log volumes.
+ *
+ * Copyright (c) 2025 QwickApps.com. All rights reserved.
+ */
+import type { Pool } from 'pg';
+/**
+ * API key usage log entry
+ */
+export interface UsageLogEntry {
+    /** Log entry ID */
+    id?: string;
+    /** API key ID that made the request */
+    key_id: string;
+    /** Endpoint path (e.g., '/cpanel/api/qwickbrain/tools') */
+    endpoint: string;
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+    /** HTTP response status code */
+    status_code?: number;
+    /** Client IP address */
+    ip_address?: string;
+    /** User agent string */
+    user_agent?: string;
+    /** Request timestamp */
+    timestamp?: Date;
+}
+/**
+ * Usage log query options
+ */
+export interface UsageLogQueryOptions {
+    /** Limit number of results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Filter by start date */
+    since?: Date;
+    /** Filter by end date */
+    until?: Date;
+    /** Filter by endpoint pattern */
+    endpoint?: string;
+    /** Filter by HTTP method */
+    method?: string;
+    /** Filter by status code */
+    statusCode?: number;
+}
+/**
+ * Usage log statistics
+ */
+export interface UsageLogStats {
+    /** Total number of calls */
+    totalCalls: number;
+    /** Last call timestamp */
+    lastUsed?: Date;
+    /** Calls by status code */
+    callsByStatus: Record<number, number>;
+    /** Calls by endpoint */
+    callsByEndpoint: Record<string, number>;
+}
+/**
+ * Usage log store interface
+ */
+export interface UsageLogStore {
+    /** Store name */
+    name: string;
+    /**
+     * Initialize the store (create tables, partitions, indexes, etc.)
+     */
+    initialize(): Promise<void>;
+    /**
+     * Log an API key usage
+     */
+    log(entry: UsageLogEntry): Promise<void>;
+    /**
+     * Batch log multiple entries (more efficient)
+     */
+    logBatch(entries: UsageLogEntry[]): Promise<void>;
+    /**
+     * Get usage logs for a specific API key
+     */
+    getKeyUsage(keyId: string, options?: UsageLogQueryOptions): Promise<UsageLogEntry[]>;
+    /**
+     * Get usage statistics for a specific API key
+     */
+    getKeyStats(keyId: string, options?: Pick<UsageLogQueryOptions, 'since' | 'until'>): Promise<UsageLogStats>;
+    /**
+     * Delete old logs (for retention policy)
+     */
+    deleteOlderThan(date: Date): Promise<number>;
+    /**
+     * Shutdown the store
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * PostgreSQL usage log store configuration
+ */
+export interface PostgresUsageLogStoreConfig {
+    /** PostgreSQL pool instance or a function that returns one (for lazy initialization) */
+    pool: Pool | (() => Pool);
+    /** Table name (default: 'api_key_usage_logs') */
+    tableName?: string;
+    /** Schema name (default: 'public') */
+    schema?: string;
+    /** Auto-create tables on init (default: true) */
+    autoCreateTables?: boolean;
+    /** Enable table partitioning (default: true) */
+    enablePartitioning?: boolean;
+    /** Partition interval in days (default: 30) */
+    partitionIntervalDays?: number;
+}
+/**
+ * PostgreSQL implementation of UsageLogStore
+ */
+export declare function createPostgresUsageLogStore(config: PostgresUsageLogStoreConfig): UsageLogStore;
+//# sourceMappingURL=usage-log-store.d.ts.map

package/dist/plugins/api-keys/stores/usage-log-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-log-store.d.ts","sourceRoot":"","sources":["../../../../src/plugins/api-keys/stores/usage-log-store.ts"],"names":[],"mappings":"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"}