@friggframework/core 2.0.0--canary.548.c8ae0ca.0 → 2.0.0--canary.545.c40eca4.0

package/admin-scripts/index.js

@@ -0,0 +1,52 @@
+/**
+ * Admin Scripts Module
+ *
+ * Exports repository interfaces and factories for admin script management.
+ * Concrete implementations support MongoDB, PostgreSQL, and DocumentDB.
+ *
+ * Repository interfaces follow the Port pattern in Hexagonal Architecture:
+ * - Define contracts for data access
+ * - Enable dependency injection
+ * - Allow testing with mocks
+ * - Support multiple database implementations
+ *
+ * Authentication:
+ * - Uses ENV-based ADMIN_API_KEY (see handlers/middleware/admin-auth.js)
+ * - No database-backed API keys (simplified from original design)
+ */
+
+// Repository Interfaces
+const { AdminProcessRepositoryInterface } = require('./repositories/admin-process-repository-interface');
+const { ScriptScheduleRepositoryInterface } = require('./repositories/script-schedule-repository-interface');
+
+// Repository Factories
+const {
+    createAdminProcessRepository,
+    AdminProcessRepositoryMongo,
+    AdminProcessRepositoryPostgres,
+    AdminProcessRepositoryDocumentDB,
+} = require('./repositories/admin-process-repository-factory');
+const {
+    createScriptScheduleRepository,
+    ScriptScheduleRepositoryMongo,
+    ScriptScheduleRepositoryPostgres,
+    ScriptScheduleRepositoryDocumentDB,
+} = require('./repositories/script-schedule-repository-factory');
+
+module.exports = {
+    // Repository Interfaces
+    AdminProcessRepositoryInterface,
+    ScriptScheduleRepositoryInterface,
+
+    // Repository Factories (primary exports for use cases)
+    createAdminProcessRepository,
+    createScriptScheduleRepository,
+
+    // Concrete Implementations (for testing)
+    AdminProcessRepositoryMongo,
+    AdminProcessRepositoryPostgres,
+    AdminProcessRepositoryDocumentDB,
+    ScriptScheduleRepositoryMongo,
+    ScriptScheduleRepositoryPostgres,
+    ScriptScheduleRepositoryDocumentDB,
+};

package/admin-scripts/repositories/admin-api-key-repository-documentdb.js

@@ -0,0 +1,21 @@
+const {
+    AdminApiKeyRepositoryMongo,
+} = require('./admin-api-key-repository-mongo');
+
+/**
+ * DocumentDB Admin API Key Repository Adapter
+ * Extends MongoDB implementation since DocumentDB uses the same Prisma client
+ *
+ * DocumentDB-specific characteristics:
+ * - Uses MongoDB-compatible API
+ * - Prisma client handles the connection
+ * - IDs are strings with ObjectId format
+ * - All operations identical to MongoDB implementation
+ */
+class AdminApiKeyRepositoryDocumentDB extends AdminApiKeyRepositoryMongo {
+    constructor() {
+        super();
+    }
+}
+
+module.exports = { AdminApiKeyRepositoryDocumentDB };

package/admin-scripts/repositories/admin-api-key-repository-factory.js

@@ -0,0 +1,51 @@
+const {
+    AdminApiKeyRepositoryPostgres,
+} = require('./admin-api-key-repository-postgres');
+const config = require('../../database/config');
+
+/**
+ * Admin API Key Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * This implements the Factory pattern for Hexagonal Architecture:
+ * - Reads database type from app definition (backend/index.js)
+ * - Returns correct adapter (MongoDB, DocumentDB, or PostgreSQL)
+ * - Provides clear error for unsupported databases
+ *
+ * Usage:
+ * ```javascript
+ * const repository = createAdminApiKeyRepository();
+ * ```
+ *
+ * @returns {AdminApiKeyRepositoryInterface} Configured repository adapter
+ * @throws {Error} If database type is not supported
+ */
+function createAdminApiKeyRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            const { AdminApiKeyRepositoryMongo } = require('./admin-api-key-repository-mongo');
+            return new AdminApiKeyRepositoryMongo();
+
+        case 'postgresql':
+            return new AdminApiKeyRepositoryPostgres();
+
+        case 'documentdb':
+            const { AdminApiKeyRepositoryDocumentDB } = require('./admin-api-key-repository-documentdb');
+            return new AdminApiKeyRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createAdminApiKeyRepository,
+    // Export adapters for direct testing
+    get AdminApiKeyRepositoryMongo() { return require('./admin-api-key-repository-mongo').AdminApiKeyRepositoryMongo; },
+    AdminApiKeyRepositoryPostgres,
+    get AdminApiKeyRepositoryDocumentDB() { return require('./admin-api-key-repository-documentdb').AdminApiKeyRepositoryDocumentDB; },
+};

package/admin-scripts/repositories/admin-api-key-repository-interface.js

@@ -0,0 +1,121 @@
+/**
+ * Admin API Key Repository Interface
+ * Abstract base class defining the contract for admin API key persistence adapters
+ *
+ * This follows the Port in Hexagonal Architecture:
+ * - Domain layer depends on this abstraction
+ * - Concrete adapters implement this interface
+ * - Use cases receive repositories via dependency injection
+ *
+ * Admin API keys provide authentication for script execution and management endpoints.
+ * Keys are bcrypt-hashed for security and support scoping and expiration.
+ *
+ * @abstract
+ */
+class AdminApiKeyRepositoryInterface {
+    /**
+     * Create a new admin API key
+     *
+     * @param {Object} params - API key creation parameters
+     * @param {string} params.name - Human-readable name for the key
+     * @param {string} params.keyHash - bcrypt hash of the raw key
+     * @param {string} params.keyLast4 - Last 4 characters of key (for display)
+     * @param {string[]} params.scopes - Array of permission scopes (e.g., ['scripts:execute', 'scripts:read'])
+     * @param {Date} [params.expiresAt] - Optional expiration date
+     * @param {string} [params.createdBy] - Optional identifier of creator (user/admin)
+     * @returns {Promise<Object>} The created API key record
+     * @abstract
+     */
+    async createApiKey({
+        name,
+        keyHash,
+        keyLast4,
+        scopes,
+        expiresAt,
+        createdBy,
+    }) {
+        throw new Error('Method createApiKey must be implemented by subclass');
+    }
+
+    /**
+     * Find an API key by its bcrypt hash
+     * Used during authentication to validate incoming keys
+     *
+     * @param {string} keyHash - The bcrypt hash to search for
+     * @returns {Promise<Object|null>} The API key record or null if not found
+     * @abstract
+     */
+    async findApiKeyByHash(keyHash) {
+        throw new Error(
+            'Method findApiKeyByHash must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Find an API key by its ID
+     *
+     * @param {string|number} id - The API key ID
+     * @returns {Promise<Object|null>} The API key record or null if not found
+     * @abstract
+     */
+    async findApiKeyById(id) {
+        throw new Error(
+            'Method findApiKeyById must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Find all active (non-expired, non-deactivated) API keys
+     * Used during authentication to check all valid keys
+     *
+     * @returns {Promise<Array>} Array of active API key records
+     * @abstract
+     */
+    async findActiveApiKeys() {
+        throw new Error(
+            'Method findActiveApiKeys must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Update the lastUsedAt timestamp for an API key
+     * Called after successful authentication
+     *
+     * @param {string|number} id - The API key ID
+     * @returns {Promise<Object>} Updated API key record
+     * @abstract
+     */
+    async updateApiKeyLastUsed(id) {
+        throw new Error(
+            'Method updateApiKeyLastUsed must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Deactivate an API key (soft delete)
+     * Sets isActive to false, preventing further use
+     *
+     * @param {string|number} id - The API key ID
+     * @returns {Promise<Object>} Updated API key record
+     * @abstract
+     */
+    async deactivateApiKey(id) {
+        throw new Error(
+            'Method deactivateApiKey must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Delete an API key (hard delete)
+     * Permanently removes the key from the database
+     *
+     * @param {string|number} id - The API key ID
+     * @returns {Promise<Object>} Deletion result
+     * @abstract
+     */
+    async deleteApiKey(id) {
+        throw new Error('Method deleteApiKey must be implemented by subclass');
+    }
+}
+
+module.exports = { AdminApiKeyRepositoryInterface };

package/admin-scripts/repositories/admin-api-key-repository-mongo.js

@@ -0,0 +1,155 @@
+const { prisma } = require('../../database/prisma');
+const {
+    AdminApiKeyRepositoryInterface,
+} = require('./admin-api-key-repository-interface');
+
+/**
+ * MongoDB Admin API Key Repository Adapter
+ * Handles admin API key persistence using Prisma with MongoDB
+ *
+ * MongoDB-specific characteristics:
+ * - IDs are strings with @db.ObjectId
+ * - Supports bcrypt hashed keys
+ * - Scopes stored as String[] array
+ */
+class AdminApiKeyRepositoryMongo extends AdminApiKeyRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Create a new admin API key
+     *
+     * @param {Object} params - API key creation parameters
+     * @param {string} params.name - Human-readable name for the key
+     * @param {string} params.keyHash - bcrypt hash of the raw key
+     * @param {string} params.keyLast4 - Last 4 characters of key (for display)
+     * @param {string[]} params.scopes - Array of permission scopes
+     * @param {Date} [params.expiresAt] - Optional expiration date
+     * @param {string} [params.createdBy] - Optional identifier of creator
+     * @returns {Promise<Object>} The created API key record
+     */
+    async createApiKey({
+        name,
+        keyHash,
+        keyLast4,
+        scopes,
+        expiresAt,
+        createdBy,
+    }) {
+        const apiKey = await this.prisma.adminApiKey.create({
+            data: {
+                name,
+                keyHash,
+                keyLast4,
+                scopes,
+                expiresAt,
+                createdBy,
+            },
+        });
+
+        return apiKey;
+    }
+
+    /**
+     * Find an API key by its bcrypt hash
+     * Used during authentication to validate incoming keys
+     *
+     * @param {string} keyHash - The bcrypt hash to search for
+     * @returns {Promise<Object|null>} The API key record or null if not found
+     */
+    async findApiKeyByHash(keyHash) {
+        const apiKey = await this.prisma.adminApiKey.findUnique({
+            where: { keyHash },
+        });
+
+        return apiKey;
+    }
+
+    /**
+     * Find an API key by its ID
+     *
+     * @param {string} id - The API key ID (MongoDB ObjectId as string)
+     * @returns {Promise<Object|null>} The API key record or null if not found
+     */
+    async findApiKeyById(id) {
+        const apiKey = await this.prisma.adminApiKey.findUnique({
+            where: { id },
+        });
+
+        return apiKey;
+    }
+
+    /**
+     * Find all active (non-expired, non-deactivated) API keys
+     * Used during authentication to check all valid keys
+     *
+     * @returns {Promise<Array>} Array of active API key records
+     */
+    async findActiveApiKeys() {
+        const now = new Date();
+        const apiKeys = await this.prisma.adminApiKey.findMany({
+            where: {
+                isActive: true,
+                OR: [{ expiresAt: null }, { expiresAt: { gt: now } }],
+            },
+        });
+
+        return apiKeys;
+    }
+
+    /**
+     * Update the lastUsedAt timestamp for an API key
+     * Called after successful authentication
+     *
+     * @param {string} id - The API key ID
+     * @returns {Promise<Object>} Updated API key record
+     */
+    async updateApiKeyLastUsed(id) {
+        const apiKey = await this.prisma.adminApiKey.update({
+            where: { id },
+            data: {
+                lastUsedAt: new Date(),
+            },
+        });
+
+        return apiKey;
+    }
+
+    /**
+     * Deactivate an API key (soft delete)
+     * Sets isActive to false, preventing further use
+     *
+     * @param {string} id - The API key ID
+     * @returns {Promise<Object>} Updated API key record
+     */
+    async deactivateApiKey(id) {
+        const apiKey = await this.prisma.adminApiKey.update({
+            where: { id },
+            data: {
+                isActive: false,
+            },
+        });
+
+        return apiKey;
+    }
+
+    /**
+     * Delete an API key (hard delete)
+     * Permanently removes the key from the database
+     *
+     * @param {string} id - The API key ID
+     * @returns {Promise<Object>} Deletion result
+     */
+    async deleteApiKey(id) {
+        await this.prisma.adminApiKey.delete({
+            where: { id },
+        });
+
+        // Return Mongoose-compatible result
+        return { acknowledged: true, deletedCount: 1 };
+    }
+}
+
+module.exports = { AdminApiKeyRepositoryMongo };

package/admin-scripts/repositories/admin-api-key-repository-postgres.js

@@ -0,0 +1,189 @@
+const { prisma } = require('../../database/prisma');
+const {
+    AdminApiKeyRepositoryInterface,
+} = require('./admin-api-key-repository-interface');
+
+/**
+ * PostgreSQL Admin API Key Repository Adapter
+ * Handles admin API key persistence using Prisma with PostgreSQL
+ *
+ * PostgreSQL-specific characteristics:
+ * - Uses Int IDs with autoincrement
+ * - Requires ID conversion: String (app layer) ↔ Int (database)
+ * - All returned IDs are converted to strings for application layer consistency
+ */
+class AdminApiKeyRepositoryPostgres extends AdminApiKeyRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    /**
+     * Convert string ID to integer for PostgreSQL queries
+     * @private
+     * @param {string|number|null|undefined} id - ID to convert
+     * @returns {number|null|undefined} Integer ID or null/undefined
+     * @throws {Error} If ID cannot be converted to integer
+     */
+    _convertId(id) {
+        if (id === null || id === undefined) return id;
+        const parsed = Number.parseInt(id, 10);
+        if (Number.isNaN(parsed)) {
+            throw new Error(`Invalid ID: ${id} cannot be converted to integer`);
+        }
+        return parsed;
+    }
+
+    /**
+     * Convert API key object IDs to strings
+     * @private
+     * @param {Object|null} apiKey - API key object from database
+     * @returns {Object|null} API key with string IDs
+     */
+    _convertApiKeyIds(apiKey) {
+        if (!apiKey) return apiKey;
+        return {
+            ...apiKey,
+            id: apiKey.id?.toString(),
+        };
+    }
+
+    /**
+     * Create a new admin API key
+     *
+     * @param {Object} params - API key creation parameters
+     * @param {string} params.name - Human-readable name for the key
+     * @param {string} params.keyHash - bcrypt hash of the raw key
+     * @param {string} params.keyLast4 - Last 4 characters of key (for display)
+     * @param {string[]} params.scopes - Array of permission scopes
+     * @param {Date} [params.expiresAt] - Optional expiration date
+     * @param {string} [params.createdBy] - Optional identifier of creator
+     * @returns {Promise<Object>} The created API key record with string ID
+     */
+    async createApiKey({
+        name,
+        keyHash,
+        keyLast4,
+        scopes,
+        expiresAt,
+        createdBy,
+    }) {
+        const apiKey = await this.prisma.adminApiKey.create({
+            data: {
+                name,
+                keyHash,
+                keyLast4,
+                scopes,
+                expiresAt,
+                createdBy,
+            },
+        });
+
+        return this._convertApiKeyIds(apiKey);
+    }
+
+    /**
+     * Find an API key by its bcrypt hash
+     * Used during authentication to validate incoming keys
+     *
+     * @param {string} keyHash - The bcrypt hash to search for
+     * @returns {Promise<Object|null>} The API key record with string ID or null if not found
+     */
+    async findApiKeyByHash(keyHash) {
+        const apiKey = await this.prisma.adminApiKey.findUnique({
+            where: { keyHash },
+        });
+
+        return this._convertApiKeyIds(apiKey);
+    }
+
+    /**
+     * Find an API key by its ID
+     *
+     * @param {string|number} id - The API key ID
+     * @returns {Promise<Object|null>} The API key record with string ID or null if not found
+     */
+    async findApiKeyById(id) {
+        const intId = this._convertId(id);
+        const apiKey = await this.prisma.adminApiKey.findUnique({
+            where: { id: intId },
+        });
+
+        return this._convertApiKeyIds(apiKey);
+    }
+
+    /**
+     * Find all active (non-expired, non-deactivated) API keys
+     * Used during authentication to check all valid keys
+     *
+     * @returns {Promise<Array>} Array of active API key records with string IDs
+     */
+    async findActiveApiKeys() {
+        const now = new Date();
+        const apiKeys = await this.prisma.adminApiKey.findMany({
+            where: {
+                isActive: true,
+                OR: [{ expiresAt: null }, { expiresAt: { gt: now } }],
+            },
+        });
+
+        return apiKeys.map((apiKey) => this._convertApiKeyIds(apiKey));
+    }
+
+    /**
+     * Update the lastUsedAt timestamp for an API key
+     * Called after successful authentication
+     *
+     * @param {string|number} id - The API key ID
+     * @returns {Promise<Object>} Updated API key record with string ID
+     */
+    async updateApiKeyLastUsed(id) {
+        const intId = this._convertId(id);
+        const apiKey = await this.prisma.adminApiKey.update({
+            where: { id: intId },
+            data: {
+                lastUsedAt: new Date(),
+            },
+        });
+
+        return this._convertApiKeyIds(apiKey);
+    }
+
+    /**
+     * Deactivate an API key (soft delete)
+     * Sets isActive to false, preventing further use
+     *
+     * @param {string|number} id - The API key ID
+     * @returns {Promise<Object>} Updated API key record with string ID
+     */
+    async deactivateApiKey(id) {
+        const intId = this._convertId(id);
+        const apiKey = await this.prisma.adminApiKey.update({
+            where: { id: intId },
+            data: {
+                isActive: false,
+            },
+        });
+
+        return this._convertApiKeyIds(apiKey);
+    }
+
+    /**
+     * Delete an API key (hard delete)
+     * Permanently removes the key from the database
+     *
+     * @param {string|number} id - The API key ID
+     * @returns {Promise<Object>} Deletion result
+     */
+    async deleteApiKey(id) {
+        const intId = this._convertId(id);
+        await this.prisma.adminApiKey.delete({
+            where: { id: intId },
+        });
+
+        // Return Mongoose-compatible result
+        return { acknowledged: true, deletedCount: 1 };
+    }
+}
+
+module.exports = { AdminApiKeyRepositoryPostgres };

package/admin-scripts/repositories/admin-process-repository-documentdb.js

@@ -0,0 +1,21 @@
+const {
+    AdminProcessRepositoryMongo,
+} = require('./admin-process-repository-mongo');
+
+/**
+ * DocumentDB Admin Process Repository Adapter
+ * Extends MongoDB implementation since DocumentDB uses the same Prisma client
+ *
+ * DocumentDB-specific characteristics:
+ * - Uses MongoDB-compatible API
+ * - Prisma client handles the connection
+ * - IDs are strings with ObjectId format
+ * - All operations identical to MongoDB implementation
+ */
+class AdminProcessRepositoryDocumentDB extends AdminProcessRepositoryMongo {
+    constructor() {
+        super();
+    }
+}
+
+module.exports = { AdminProcessRepositoryDocumentDB };

package/admin-scripts/repositories/admin-process-repository-factory.js

@@ -0,0 +1,49 @@
+const { AdminProcessRepositoryPostgres } = require('./admin-process-repository-postgres');
+const config = require('../../database/config');
+
+/**
+ * Admin Process Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * This implements the Factory pattern for Hexagonal Architecture:
+ * - Reads database type from app definition (backend/index.js)
+ * - Returns correct adapter (MongoDB, DocumentDB, or PostgreSQL)
+ * - Provides clear error for unsupported databases
+ *
+ * Usage:
+ * ```javascript
+ * const repository = createAdminProcessRepository();
+ * ```
+ *
+ * @returns {AdminProcessRepositoryInterface} Configured repository adapter
+ * @throws {Error} If database type is not supported
+ */
+function createAdminProcessRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            const { AdminProcessRepositoryMongo } = require('./admin-process-repository-mongo');
+            return new AdminProcessRepositoryMongo();
+
+        case 'postgresql':
+            return new AdminProcessRepositoryPostgres();
+
+        case 'documentdb':
+            const { AdminProcessRepositoryDocumentDB } = require('./admin-process-repository-documentdb');
+            return new AdminProcessRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createAdminProcessRepository,
+    // Export adapters for direct testing
+    get AdminProcessRepositoryMongo() { return require('./admin-process-repository-mongo').AdminProcessRepositoryMongo; },
+    AdminProcessRepositoryPostgres,
+    get AdminProcessRepositoryDocumentDB() { return require('./admin-process-repository-documentdb').AdminProcessRepositoryDocumentDB; },
+};