@friggframework/core 2.0.0-next.111 → 2.0.0-next.113

package/database/encryption/README.md

@@ -680,7 +680,11 @@ The encryption system uses **fail-fast error handling**:
 
 ### Logging Configuration
 
-Configure log verbosity with `FRIGG_LOG_LEVEL`:
+`FRIGG_LOG_LEVEL` is the one Frigg log level. The level rules, the record
+fields and the redaction rules are in the
+[Logging guide](../../../../docs/guides/LOGGING.md). The encryption logger
+still writes text lines through `console` with the same level names until it
+moves to the structured logger (ADR-048, incremental adoption).
 
 ```bash
 # Production (minimal logging)
@@ -814,6 +818,26 @@ export AES_KEY=$(openssl rand -hex 16)  # Generate 32-char key
 ❌ Query on encrypted fields (not supported)
 ❌ Manually decrypt data (use extension)
 
+The integration mapping repositories' `queryMappings()` (PostgreSQL, MongoDB
+and DocumentDB) filters and sorts inside the `mapping` JSON, so it refuses to
+run while field-level encryption still encrypts `IntegrationMapping.mapping` on
+write. Opt the field out in the app definition, together with any nested
+`mapping.*` path that `encryption.schema` encrypts; the Prisma extension and
+`DocumentDBEncryptionService` both honor the opt-out:
+
+```javascript
+encryption: {
+    disable: { IntegrationMapping: ['mapping'] },
+}
+```
+
+The opt-out applies to writes only. Rows written encrypted before it stay
+readable, but `queryMappings()` does not match them until they are written
+again. It returns the rows it matches decrypted, like
+`findMappingsByIntegration()`: a nested `mapping.*` path written encrypted
+before its opt-out reads plain, though conditions and ordering on that path
+still see the ciphertext until the row is written again.
+
 ## Future Enhancements
 
 ### Planned

package/database/encryption/encryption-schema-registry.js

@@ -9,6 +9,7 @@
  */
 
 const { logger } = require('./logger');
+const { registerDeniedKeys } = require('../../logs/denied-keys');
 
 /**
  * Core encryption schema (immutable - cannot be overridden by custom schemas)
@@ -120,6 +121,7 @@ function registerCustomSchema(schema) {
     }
 
     customSchema = { ...schema };
+    registerDeniedKeys(Object.values(schema).flatMap((config) => config.fields));
     logger.info(
         `Registered custom encryption schema for models: ${Object.keys(customSchema).join(', ')}`
     );
@@ -149,6 +151,7 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
         }
     }
 
+    registerDeniedKeys(fields);
     return [...new Set(fields)];
 }
 

package/database/encryption/integration-mapping-encryption.js

@@ -0,0 +1,97 @@
+const { getEncryptionConfig } = require('../prisma');
+const { Cryptor } = require('../../encrypt/Cryptor');
+const {
+    getFieldsToDecryptOnRead,
+    getFieldsToEncryptOnWrite,
+    loadCustomEncryptionSchema,
+} = require('./encryption-schema-registry');
+const {
+    createFieldEncryptionService,
+} = require('./prisma-encryption-extension');
+
+let plainMappingEncryption = null;
+
+/**
+ * The `IntegrationMapping` fields, `mapping` itself or a nested `mapping.*`
+ * path, that field-level encryption encrypts on write. An empty result is
+ * kept for the life of the process.
+ *
+ * @returns {string[]} Empty when every mapping path is written as plain JSON
+ */
+function getMappingFieldsEncryptedOnWrite() {
+    return mappingEncryption().encryptedOnWrite;
+}
+
+/**
+ * @throws {Error} When field-level encryption still encrypts `mapping`, or a
+ *   nested `mapping.*` path, on write, naming the opt-out that lifts it
+ */
+function assertMappingWrittenUnencrypted() {
+    const fields = getMappingFieldsEncryptedOnWrite();
+    if (fields.length === 0) return;
+
+    const encrypted = fields
+        .map((field) => `IntegrationMapping.${field}`)
+        .join(', ');
+    const optOut = fields.map((field) => `'${field}'`).join(', ');
+    throw new Error(
+        `queryMappings: field-level encryption still encrypts ${encrypted} on write, so it cannot be queried. Opt out by adding ${optOut} to appDefinition.encryption.disable.IntegrationMapping.`
+    );
+}
+
+/**
+ * Decrypts rows that `queryMappings` read around the Prisma encryption
+ * extension, the way reads through the extension do: every
+ * `IntegrationMapping` field the schema lists, opted-out paths included, so a
+ * path written encrypted before its opt-out comes back plain.
+ *
+ * @param {Object[]} rows - Rows whose `mapping` is a JSON object
+ * @returns {Promise<Object[]>} `rows` itself when encryption is off or the
+ *   schema lists no field besides `mapping`
+ */
+async function decryptQueriedMappings(rows) {
+    const { decryptor } = mappingEncryption();
+    if (!decryptor) return rows;
+    return decryptor.decryptFieldsInBulk('IntegrationMapping', rows);
+}
+
+function mappingEncryption() {
+    if (plainMappingEncryption) return plainMappingEncryption;
+
+    const encryption = currentMappingEncryption();
+    if (encryption.encryptedOnWrite.length === 0) {
+        plainMappingEncryption = encryption;
+    }
+    return encryption;
+}
+
+function currentMappingEncryption() {
+    const config = getEncryptionConfig();
+    if (!config.enabled) return { encryptedOnWrite: [], decryptor: null };
+
+    loadCustomEncryptionSchema();
+    const encryptedOnWrite = getFieldsToEncryptOnWrite(
+        'IntegrationMapping'
+    ).filter((field) => field === 'mapping' || field.startsWith('mapping.'));
+    const decryptsBesidesMapping = getFieldsToDecryptOnRead(
+        'IntegrationMapping'
+    ).some((field) => field !== 'mapping');
+    const decryptor = decryptsBesidesMapping
+        ? createFieldEncryptionService(
+              new Cryptor({ shouldUseAws: config.method === 'kms' })
+          )
+        : null;
+    return { encryptedOnWrite, decryptor };
+}
+
+/** Test helper: forget a kept result. */
+function resetMappingEncryptionCheck() {
+    plainMappingEncryption = null;
+}
+
+module.exports = {
+    assertMappingWrittenUnencrypted,
+    decryptQueriedMappings,
+    getMappingFieldsEncryptedOnWrite,
+    resetMappingEncryptionCheck,
+};

package/database/encryption/logger.js

@@ -17,9 +17,12 @@ class EncryptionLogger {
         this.minLevel = this._getMinLevel();
     }
 
+    // FRIGG_LOG_LEVEL also takes TRACE and FATAL (ADR-048); this logger has
+    // no such levels, so they map to its nearest ones.
     _getMinLevel() {
-        const level = process.env.FRIGG_LOG_LEVEL || 'INFO';
-        return LOG_LEVELS[level.toUpperCase()] ?? LOG_LEVELS.INFO;
+        const level = (process.env.FRIGG_LOG_LEVEL || 'INFO').trim().toUpperCase();
+        const mapped = { TRACE: 'DEBUG', FATAL: 'ERROR' }[level] ?? level;
+        return LOG_LEVELS[mapped] ?? LOG_LEVELS.INFO;
     }
 
     _shouldLog(level) {

package/database/encryption/prisma-encryption-extension.js

@@ -10,6 +10,24 @@ const {
 } = require('./encryption-schema-registry');
 const { FieldEncryptionService } = require('./field-encryption-service');
 
+/**
+ * The FieldEncryptionService the extension runs, with field paths from the
+ * encryption schema registry.
+ *
+ * @param {import('../../encrypt/Cryptor').Cryptor} cryptor
+ * @returns {FieldEncryptionService}
+ */
+function createFieldEncryptionService(cryptor) {
+    return new FieldEncryptionService({
+        cryptor,
+        schema: {
+            getEncryptedFields,
+            getFieldsToEncryptOnWrite,
+            getFieldsToDecryptOnRead,
+        },
+    });
+}
+
 function createEncryptionExtension({ cryptor, enabled = true }) {
     if (!enabled) {
         return (client) => client;
@@ -21,14 +39,7 @@ function createEncryptionExtension({ cryptor, enabled = true }) {
         );
     }
 
-    const encryptionService = new FieldEncryptionService({
-        cryptor,
-        schema: {
-            getEncryptedFields,
-            getFieldsToEncryptOnWrite,
-            getFieldsToDecryptOnRead,
-        },
-    });
+    const encryptionService = createFieldEncryptionService(cryptor);
 
     return {
         name: 'frigg-field-encryption',
@@ -227,4 +238,4 @@ function createEncryptionExtension({ cryptor, enabled = true }) {
     };
 }
 
-module.exports = { createEncryptionExtension };
+module.exports = { createEncryptionExtension, createFieldEncryptionService };

package/errors/fetch-error.js

@@ -1,82 +1,65 @@
 const { BaseError } = require('./base-error');
-const { stripIndent } = require('common-tags');
-
-// TODO hide header values
+const { redactUrl, scrubString } = require('../logs/redact');
 
 // Parameters names here are based on fetch.  See:
 // https://developer.mozilla.org/en-US/docs/Web/API/fetch
 
-class FetchError extends BaseError {
-    response = null;
-
-    constructor(options = {}) {
-        const { resource, init, response, responseBody } = options;
-        const method = init?.method ?? 'GET';
-        let initText = init
-            ? init.body instanceof URLSearchParams
-                ? (() => {
-                    init.body = init.body.toString();
-                    return JSON.stringify({ init }, null, 2);
-                })()
-                : JSON.stringify({ init }, null, 2)
-            : '';
-
-        let responseBodyText = '<response body is unavailable>';
-        if (typeof responseBody === 'string') {
-            responseBodyText = responseBody;
-        } else if (responseBody) {
-            responseBodyText = JSON.stringify(responseBody, null, 2);
-        }
-
-        const responseHeaders = {};
-        if (response?.headers) {
-            for (const [key, value] of response.headers) {
-                responseHeaders[key] = value;
-            }
-        }
-
-        let responseHeaderText = response
-            ? JSON.stringify({ headers: responseHeaders }, null, 2)
-            : '';
+function resourceUrl(resource) {
+    if (resource === undefined || resource === null) return '';
+    if (typeof resource === 'object' && typeof resource.url === 'string') {
+        return redactUrl(resource.url);
+    }
+    return redactUrl(resource);
+}
 
-        // sanitize error reporting
-        if (process.env.STAGE !== 'dev') {
-            initText = false;
-            responseHeaderText = false;
-            responseBodyText = false;
-        }
+function causeLabel(cause) {
+    if (!cause || typeof cause !== 'object') return '';
+    const label = cause.code ?? cause.name;
+    return label === undefined || label === null ? '' : scrubString(String(label));
+}
 
-        const messageParts = [
-            stripIndent`
-                -----------------------------------------------------
-                An error ocurred while fetching an external resource.
-                -----------------------------------------------------
-                >>> Request Details >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-                ${method} ${resource}
-            `,
-            initText,
-            stripIndent`
-                <<< Response Details <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
-                ${response?.status} ${response?.statusText}
-            `,
-            responseHeaderText,
-            responseBodyText,
-            stripIndent`
-                -----------------------------------------------------
-                Stack Trace:
-            `,
-        ];
+function buildMessage({ method, url, response, cause }) {
+    const outcome = response
+        ? response.status === undefined || response.status === null
+            ? ''
+            : String(response.status)
+        : causeLabel(cause);
+    return [method, url, outcome].filter(Boolean).join(' ');
+}
 
-        super(messageParts.filter(Boolean).join('\n'));
+class FetchError extends BaseError {
+    constructor({ resource, init, response, cause, responseBody, body } = {}) {
+        const method = String(init?.method ?? 'GET').toUpperCase();
+        const url = resourceUrl(resource);
+        super(
+            buildMessage({ method, url, response, cause }),
+            cause ? { cause } : undefined
+        );
 
-        this.response = response;
         this.statusCode = response?.status;
+        this.method = method;
+        this.url = url;
+        Object.defineProperty(this, 'response', {
+            value: response ?? null,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+        Object.defineProperty(this, 'body', {
+            value: responseBody ?? body,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
     }
 
     static async create(options = {}) {
         const { response } = options;
-        let responseBody = response?.bodyUsed ? null : await response?.text();
-        if (!responseBody && options.body) responseBody = options.body;
+        let responseBody =
+            response && !response.bodyUsed && typeof response.text === 'function'
+                ? await response.text()
+                : null;
+        if (!responseBody) responseBody = options.responseBody ?? options.body;
         return new FetchError({ ...options, responseBody });
     }
 }

package/handlers/app-definition-loader.js

@@ -2,13 +2,38 @@ const { findNearestBackendPackageJson } = require('@friggframework/core/utils');
 const path = require('node:path');
 const fs = require('fs-extra');
 const { resolveTelemetryConfig } = require('../telemetry/telemetry-config');
+const { registerDeniedKeys } = require('../logs/denied-keys');
+const {
+    extractCredentialFieldsFromModules,
+} = require('../database/encryption/encryption-schema-registry');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('../integrations/utils/map-integration-dto');
+
+// Handlers without a database never load the encryption registry, so the
+// credential leaf keys are registered for redaction here too.
+function registerCredentialLogKeys(appDefinition, integrations) {
+    try {
+        extractCredentialFieldsFromModules(
+            getModulesDefinitionFromIntegrationClasses(integrations)
+        );
+    } catch {
+        // An odd integration shape must not stop the app from loading.
+    }
+    const schema = appDefinition.encryption?.schema;
+    if (schema && typeof schema === 'object') {
+        for (const config of Object.values(schema)) {
+            registerDeniedKeys(config?.fields);
+        }
+    }
+}
 
 /**
  * Loads the App definition from the nearest backend package
  * @function loadAppDefinition
  * @description Searches for the nearest backend package.json, loads the corresponding index.js file,
  * and extracts the application definition containing integrations and user configuration.
- * @returns {{integrations: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object}} An object containing the application definition.
+ * @returns {{integrations: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null}} An object containing the application definition.
  * @throws {Error} Throws error if backend package.json cannot be found.
  * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
  * @example
@@ -36,8 +61,11 @@ function loadAppDefinition() {
         adminScripts = [],
         reports = [],
         admin = {},
+        logging = null,
     } = appDefinition;
 
+    registerCredentialLogKeys(appDefinition, integrations);
+
     // Degrade consistently: an invalid telemetry block must never take down a
     // router bundle that loads the app definition at module scope (telemetry is
     // never allowed to break a handler). The singletons apply the same
@@ -59,7 +87,15 @@ function loadAppDefinition() {
         };
     }
 
-    return { integrations, userConfig, adminScripts, reports, admin, telemetry };
+    return {
+        integrations,
+        userConfig,
+        adminScripts,
+        reports,
+        admin,
+        telemetry,
+        logging,
+    };
 }
 
 module.exports = {

package/handlers/app-handler-helpers.js

@@ -1,10 +1,14 @@
-const { createHandler, flushDebugLog } = require('@friggframework/core');
+const { createHandler } = require('@friggframework/core');
+const { getLogger } = require('../logs');
+const { summarizeExpressRequest } = require('../logs/summarize-event');
 const express = require('express');
 const bodyParser = require('body-parser');
 const cors = require('cors');
 const Boom = require('@hapi/boom');
 const serverlessHttp = require('serverless-http');
 
+const log = getLogger('frigg.http');
+
 const createApp = (applyMiddleware) => {
     const app = express();
 
@@ -21,7 +25,7 @@ const createApp = (applyMiddleware) => {
 
     if (applyMiddleware) applyMiddleware(app);
 
-    // Handle sending error response and logging server errors to console
+    // The express boundary: send the error response and log it one time.
     app.use((err, req, res, next) => {
         const boomError = err.isBoom ? err : Boom.boomify(err);
         const {
@@ -29,10 +33,20 @@ const createApp = (applyMiddleware) => {
         } = boomError;
 
         if (statusCode >= 500) {
-            flushDebugLog(boomError);
+            log.error('Request failed', {
+                eventName: 'frigg.http.request_failed',
+                statusCode,
+                invocation: summarizeExpressRequest(req),
+                error: boomError,
+            });
             res.status(statusCode).json({ error: 'Internal Server Error' });
         } else {
-            console.warn(`[Frigg] ${req.method} ${req.path} -> ${statusCode}: ${err.message}`);
+            // A client error needs no stack; the logger scrubs the reason.
+            log.warn('Request rejected', {
+                eventName: 'frigg.http.request_rejected',
+                statusCode,
+                reason: boomError.message,
+            });
             res.status(statusCode).json({ error: err.message });
         }
     });

package/handlers/backend-utils.js

@@ -1,4 +1,5 @@
 const { Router } = require('express');
+const { runInContext, LOGGER_SCOPE_KEY } = require('../logs/context');
 const { Worker } = require('@friggframework/core');
 const {
     IntegrationEventDispatcher,
@@ -19,6 +20,7 @@ const {
 const {
     getModulesDefinitionFromIntegrationClasses,
 } = require('../integrations/utils/map-integration-dto');
+const { processNotFound } = require('../integrations/use-cases/process-errors');
 
 const loadRouterFromObject = (IntegrationClass, routerObject) => {
     const router = Router();
@@ -37,12 +39,11 @@ const loadRouterFromObject = (IntegrationClass, routerObject) => {
             const dispatcher = new IntegrationEventDispatcher(
                 integrationInstance
             );
-            const result = await dispatcher.dispatchHttp({
-                event,
-                req,
-                res,
-                next,
-            });
+            // Logs only: a route :integrationId is unauthenticated input.
+            const result = await runInContext(
+                { [LOGGER_SCOPE_KEY]: { integrationId: req.params?.integrationId } },
+                () => dispatcher.dispatchHttp({ event, req, res, next })
+            );
             res.json(result);
         } catch (error) {
             next(error);
@@ -149,7 +150,7 @@ const loadIntegrationForProcess = async (processId, integrationClass) => {
     const process = await processRepository.findById(processId);
 
     if (!process) {
-        throw new Error(`Process not found: ${processId}`);
+        throw processNotFound(`Process not found: ${processId}`);
     }
 
     const instance = await getIntegrationInstance.execute(
@@ -164,7 +165,7 @@ const createQueueWorker = (integrationClass) => {
     const integrationName = integrationClass.Definition.name;
 
     class QueueWorker extends Worker {
-        async _run(params, context) {
+        async _run(params, context, delivery) {
             const logCtx = {
                 integration: integrationName,
                 event: params.event,
@@ -254,6 +255,7 @@ const createQueueWorker = (integrationClass) => {
                     event: params.event,
                     data: params.data,
                     context: context,
+                    delivery,
                 });
                 console.log(
                     `[QueueWorker] ${params.event} dispatched ok`,
@@ -273,11 +275,6 @@ const createQueueWorker = (integrationClass) => {
                     return;
                 }
 
-                console.error(
-                    `Error in ${params.event} for ${integrationName}:`,
-                    error
-                );
-
                 // 4xx HTTP errors are permanent — the requester already
                 // attempted token refresh (401) and backoff (429/5xx).
                 // By the time a 4xx reaches here, retrying won't help.

package/handlers/database-migration-handler.js

@@ -24,6 +24,9 @@
 
 const { execFile } = require('child_process');
 const path = require('path');
+const { getLogger } = require('../logs');
+
+const log = getLogger('frigg.database.migration');
 
 /**
  * Execute Prisma migration command
@@ -153,7 +156,13 @@ exports.handler = async (event, context) => {
     console.log('='.repeat(60));
     console.log('Database Migration Handler');
     console.log('='.repeat(60));
-    console.log('Event:', JSON.stringify(event, null, 2));
+    log.info('Database migration invoked', {
+        eventName: 'frigg.database.migration.invoked',
+        migrationId: event.migrationId,
+        dbType: process.env.DB_TYPE,
+        targetStage: process.env.STAGE,
+        action: event.command || 'deploy',
+    });
     console.log('Context:', JSON.stringify({
         functionName: context.functionName,
         functionVersion: context.functionVersion,

package/handlers/integration-event-dispatcher.js

@@ -18,9 +18,9 @@ class IntegrationEventDispatcher {
         );
     }
 
-    async dispatchJob({ event, data, context }) {
+    async dispatchJob({ event, data, context, delivery }) {
         return this._dispatch(event, (instance, handler) =>
-            handler.call(instance, { data, context })
+            handler.call(instance, { data, context, delivery })
         );
     }
 

package/handlers/routers/integration-webhook-routers.js

@@ -1,6 +1,7 @@
 const { createAppHandler } = require('./../app-handler-helpers');
 const { loadAppDefinition } = require('../app-definition-loader');
 const { Router } = require('express');
+const { runInContext, LOGGER_SCOPE_KEY } = require('../../logs/context');
 const {
     IntegrationEventDispatcher,
 } = require('../integration-event-dispatcher');
@@ -55,12 +56,18 @@ for (const IntegrationClass of integrationClasses) {
             const dispatcher = new IntegrationEventDispatcher(
                 integrationInstance
             );
-            await dispatcher.dispatchHttp({
-                event: 'WEBHOOK_RECEIVED',
-                req,
-                res,
-                next,
-            });
+            // Logs only: the id comes from an unauthenticated URL, so it must
+            // not reach the telemetry context that drives usage attribution.
+            await runInContext(
+                { [LOGGER_SCOPE_KEY]: { integrationId: req.params.integrationId } },
+                () =>
+                    dispatcher.dispatchHttp({
+                        event: 'WEBHOOK_RECEIVED',
+                        req,
+                        res,
+                        next,
+                    })
+            );
         } catch (error) {
             next(error);
         }