@friggframework/core 2.0.0-next.112 → 2.0.0-next.114

package/logs/__fixtures__/vectors.js

@@ -0,0 +1,329 @@
+// ADR-048 §14 redaction vectors. Each vector is one log call that carries
+// secrets; the suite asserts that no 8-char window of them reaches a record.
+const { SECRETS: S, fakeToken } = require('./secrets');
+const { httpApiV2Event, restV1Event, sqsEvent } = require('./events');
+const { summarizeLambdaEvent } = require('../summarize-event');
+
+const secretUrl = `https://api.example.com/v1/items?api_key=${S.apiKeyQuery}`;
+const SIGNATURE_VALUE = fakeToken('signatureValue', 27);
+
+// Built by concatenation so push protection does not match the prefixes.
+const TOKEN_TAIL = fakeToken('prefixTail', 25);
+const PREFIXED_TOKENS = [
+    'sk_' + 'live_' + TOKEN_TAIL,
+    'whsec' + '_' + TOKEN_TAIL,
+    'xox' + 'b-' + TOKEN_TAIL,
+    'gh' + 'p_' + TOKEN_TAIL,
+    'AK' + 'IA' + 'ZQPR3FIXTAIL8HN2',
+];
+
+function errorWithMessage(message, name = 'Error') {
+    const error = new Error(message);
+    error.name = name;
+    return error;
+}
+
+function nodeFetchError() {
+    const { FetchError } = require('node-fetch');
+    return new FetchError(
+        `request to ${secretUrl} failed, reason: connect ECONNREFUSED Authorization: Bearer ${S.bearer}`,
+        'system',
+        { code: 'ECONNREFUSED' }
+    );
+}
+
+function causeChain() {
+    const deepest = errorWithMessage(`token refresh failed: refresh_token=${S.refreshToken}`);
+    const third = new Error('third', { cause: deepest });
+    const second = new Error('second', { cause: third });
+    return new Error('top', { cause: second });
+}
+
+function cyclicObject() {
+    const node = { name: 'node', access_token: S.accessToken };
+    node.self = node;
+    node.list = [node, { password: S.password }];
+    return node;
+}
+
+function aggregateError() {
+    return new AggregateError(
+        [
+            errorWithMessage(`GET ${secretUrl} 401`),
+            errorWithMessage(`Authorization: Basic ${Buffer.from(`u:${S.password}`).toString('base64')}`),
+        ],
+        'batch failed'
+    );
+}
+
+function prismaValidationError() {
+    const error = errorWithMessage(
+        [
+            'Invalid `prisma.credential.create()` invocation:',
+            '',
+            `{ data: { access_token: "${S.accessToken}", refresh_token: "${S.refreshToken}" } }`,
+            '',
+            'Argument `userId` is missing.',
+        ].join('\n'),
+        'PrismaClientValidationError'
+    );
+    error.clientVersion = '6.19.3';
+    return error;
+}
+
+function vectors() {
+    return [
+        {
+            name: 'HTTP API v2 event through summarizeLambdaEvent',
+            level: 'info',
+            fields: () => ({ invocation: summarizeLambdaEvent(httpApiV2Event()) }),
+            secrets: [S.friggApiKey, S.cookie, S.oauthCode, S.bearer, S.apiKeyQuery, S.codeVerifier, S.clientSecret],
+            expectSanitized: (record) => {
+                expect(record.invocation.headerNames).toEqual(
+                    expect.arrayContaining(['x-frigg-api-key', 'cookie', 'authorization'])
+                );
+                expect(record.invocation.queryKeys).toEqual(expect.arrayContaining(['code', 'api_key']));
+            },
+        },
+        {
+            name: 'HTTP API v2 event as a raw field',
+            level: 'debug',
+            fields: () => ({ event: httpApiV2Event() }),
+            secrets: [S.friggApiKey, S.cookie, S.oauthCode, S.bearer, S.apiKeyQuery, S.codeVerifier, S.clientSecret],
+            expectSanitized: (record) => {
+                expect(record.event.headers).toEqual(
+                    expect.arrayContaining(['x-frigg-api-key', 'cookie'])
+                );
+            },
+        },
+        {
+            name: 'REST v1 event as a raw field',
+            level: 'debug',
+            fields: () => ({ event: restV1Event() }),
+            secrets: [S.friggApiKey, S.cookie, S.password, S.accessToken, S.refreshToken],
+            expectSanitized: (record) => {
+                expect(record.event.httpMethod).toBe('POST');
+            },
+        },
+        {
+            name: 'SQS event as a raw field',
+            level: 'debug',
+            fields: () => ({ event: sqsEvent() }),
+            secrets: [S.accessToken, S.clientSecret, S.bearer],
+            expectSanitized: (record) => {
+                expect(record.event.Records[0].messageId).toBe('msg-1');
+            },
+        },
+        {
+            name: 'node-fetch FetchError',
+            level: 'error',
+            fields: () => ({ error: nodeFetchError() }),
+            secrets: [S.apiKeyQuery, S.bearer],
+            expectSanitized: (record) => {
+                expect(record.error.message).toContain('api_key=REDACTED');
+            },
+        },
+        {
+            name: 'Error as the message',
+            level: 'error',
+            message: () => errorWithMessage(`GET ${secretUrl} Authorization: Bearer ${S.bearer}`),
+            secrets: [S.apiKeyQuery, S.bearer],
+            expectSanitized: (record) => {
+                expect(record.message).toContain('api_key=REDACTED');
+            },
+        },
+        {
+            name: 'cause chain with a secret at depth 3',
+            level: 'error',
+            fields: () => ({ error: causeChain() }),
+            secrets: [S.refreshToken],
+            expectSanitized: (record) => {
+                expect(record.error.cause.cause.message).toBe('third');
+            },
+        },
+        {
+            name: 'cyclic object',
+            level: 'warn',
+            fields: () => ({ node: cyclicObject() }),
+            secrets: [S.accessToken, S.password],
+            expectSanitized: (record) => {
+                expect(JSON.stringify(record)).toContain('[Circular]');
+            },
+        },
+        {
+            name: 'AggregateError',
+            level: 'error',
+            fields: () => ({ error: aggregateError() }),
+            secrets: [S.apiKeyQuery, S.password],
+            expectSanitized: (record) => {
+                expect(record.error.type).toBe('AggregateError');
+            },
+        },
+        {
+            name: 'Prisma validation error',
+            level: 'error',
+            fields: () => ({ error: prismaValidationError() }),
+            secrets: [S.accessToken, S.refreshToken],
+            expectSanitized: (record) => {
+                expect(record.error.message).toContain('Argument `userId` is missing.');
+            },
+        },
+        {
+            name: 'connection strings',
+            level: 'warn',
+            message: () =>
+                `connect failed postgresql://frigg:${S.dbPassword}@db.internal:5432/app and mongodb+srv://frigg:${S.dbPassword}@cluster0.example.net/app`,
+            secrets: [S.dbPassword],
+            expectSanitized: (record) => {
+                expect(record.message).toContain('db.internal');
+            },
+        },
+        {
+            name: 'JWT',
+            level: 'info',
+            fields: () => ({ note: `id token ${S.jwt} received` }),
+            secrets: [S.jwt],
+        },
+        {
+            name: 'Bearer and Basic credentials',
+            level: 'info',
+            fields: () => ({
+                note: `Authorization: Bearer ${S.bearer}; Authorization: Basic ${Buffer.from(`u:${S.password}`).toString('base64')}`,
+            }),
+            secrets: [S.bearer, S.password],
+        },
+        {
+            name: 'base64 run',
+            level: 'info',
+            fields: () => ({ note: `blob ${S.base64Run} end` }),
+            secrets: [S.base64Run],
+        },
+        {
+            name: 'provider token prefixes',
+            level: 'warn',
+            message: () => `provider rejected ${PREFIXED_TOKENS.join(' and ')}`,
+            fields: () => ({ note: PREFIXED_TOKENS.join(',') }),
+            secrets: PREFIXED_TOKENS,
+        },
+        {
+            name: '40-hex token',
+            level: 'error',
+            message: () => `lookup failed for key ${S.hexToken}`,
+            secrets: [S.hexToken],
+        },
+        {
+            name: 'client_secret, signature and code pairs',
+            level: 'info',
+            fields: () => ({
+                note: `client_secret=${S.clientSecret} signature=${SIGNATURE_VALUE} code=${S.oauthCode}`,
+            }),
+            secrets: [S.clientSecret, SIGNATURE_VALUE, S.oauthCode],
+        },
+        {
+            name: 'JSON string',
+            level: 'info',
+            fields: () => ({ note: JSON.stringify({ token: S.accessToken, id: 7 }) }),
+            secrets: [S.accessToken],
+        },
+        {
+            name: 'k=v& string',
+            level: 'info',
+            fields: () => ({ note: `user=alice&password=${S.password}&next=/home` }),
+            secrets: [S.password],
+        },
+        {
+            name: 'URLSearchParams body',
+            level: 'debug',
+            fields: () => ({
+                body: new URLSearchParams({
+                    grant_type: 'authorization_code',
+                    code: S.oauthCode,
+                    code_verifier: S.codeVerifier,
+                    client_secret: S.clientSecret,
+                }),
+            }),
+            secrets: [S.oauthCode, S.codeVerifier, S.clientSecret],
+            expectSanitized: (record) => {
+                expect(JSON.stringify(record.body)).toContain('grant_type');
+            },
+        },
+        {
+            name: 'Headers, URL and Buffer',
+            level: 'debug',
+            fields: () => ({
+                headers: new Headers({ authorization: `Bearer ${S.bearer}`, 'x-frigg-api-key': S.friggApiKey }),
+                url: new URL(`https://user:${S.password}@api.example.com/x?access_token=${S.accessToken}`),
+                raw: Buffer.from(`secret=${S.clientSecret}`),
+            }),
+            secrets: [S.bearer, S.friggApiKey, S.password, S.accessToken, S.clientSecret],
+            expectSanitized: (record) => {
+                expect(JSON.stringify(record.url)).toContain('api.example.com');
+            },
+        },
+        {
+            name: 'OAuth callback params',
+            level: 'debug',
+            fields: () => ({ params: { code: S.oauthCode, state: 'abc123', code_verifier: S.codeVerifier } }),
+            secrets: [S.oauthCode, S.codeVerifier],
+            expectSanitized: (record) => {
+                expect(Object.keys(record.params)).toEqual(
+                    expect.arrayContaining(['code', 'state'])
+                );
+            },
+        },
+        {
+            name: 'hashword',
+            level: 'info',
+            fields: () => ({ user: { username: 'alice', hashword: S.hashword } }),
+            secrets: [S.hashword],
+            expectSanitized: (record) => {
+                expect(record.user.username).toBe('alice');
+            },
+        },
+        {
+            name: 'denied keys as bindings and top-level fields',
+            level: 'info',
+            bindings: () => ({ apiKey: S.friggApiKey }),
+            fields: () => ({ access_token: S.accessToken, id_token: S.idToken, cookies: [S.cookie] }),
+            secrets: [S.friggApiKey, S.accessToken, S.idToken, S.cookie],
+        },
+    ];
+}
+
+// A real Requester call that fails with 401. The URL carries a query key and
+// the request an Authorization header.
+async function requesterFetchError() {
+    const { Requester } = require('../../modules/requester/requester');
+    class TestRequester extends Requester {
+        async addAuthHeaders(headers) {
+            return { ...headers, Authorization: `Bearer ${S.bearer}` };
+        }
+    }
+    const response = {
+        status: 401,
+        ok: false,
+        bodyUsed: false,
+        headers: {
+            get: () => 'application/json',
+            raw: () => ({ 'content-type': ['application/json'] }),
+            [Symbol.iterator]: function* () {
+                yield ['content-type', 'application/json'];
+            },
+        },
+        json: async () => ({ access_token: S.accessToken }),
+        text: async () => `{"access_token":"${S.accessToken}"}`,
+    };
+    const requester = new TestRequester({
+        backOff: [],
+        requestTimeoutMs: 0,
+        fetch: async () => response,
+    });
+    return requester._get({ url: secretUrl }).then(
+        () => {
+            throw new Error('expected the request to fail');
+        },
+        (error) => error
+    );
+}
+
+module.exports = { vectors, requesterFetchError, secretUrl };

package/logs/__fixtures__/with-env.js

@@ -0,0 +1,45 @@
+const { createMemorySink } = require('../sinks');
+const { resetLoggerForTests } = require('../logger-runtime');
+
+function applyEnv(vars) {
+    const saved = {};
+    for (const [key, value] of Object.entries(vars)) {
+        saved[key] = Object.prototype.hasOwnProperty.call(process.env, key)
+            ? process.env[key]
+            : undefined;
+        if (value === undefined) delete process.env[key];
+        else process.env[key] = value;
+    }
+    return () => {
+        for (const [key, value] of Object.entries(saved)) {
+            if (value === undefined) delete process.env[key];
+            else process.env[key] = value;
+        }
+    };
+}
+
+// Sets env keys (undefined deletes), resets the logger to read them, and
+// passes a fresh memory sink to fn. Restores env and the test logger after.
+function withEnv(vars, fn) {
+    const restore = applyEnv(vars);
+    const sink = createMemorySink({ install: false });
+    resetLoggerForTests({ sinks: [sink] });
+    const done = () => {
+        restore();
+        resetLoggerForTests({ level: 'TRACE', sinks: [createMemorySink({ install: false })] });
+    };
+    let result;
+    try {
+        result = fn(sink);
+    } catch (error) {
+        done();
+        throw error;
+    }
+    if (result && typeof result.then === 'function') {
+        return result.finally(done);
+    }
+    done();
+    return result;
+}
+
+module.exports = { withEnv, applyEnv };

package/logs/context.js

@@ -0,0 +1,109 @@
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+const LOGGER_SCOPE_KEY = 'log';
+const INTEGRATION_KEYS = ['integrationId', 'integrationType', 'userId', 'version'];
+
+// Shared across jest module registries and nested core copies.
+const STORE_KEY = Symbol.for('@friggframework/core.logs.context');
+
+function als() {
+    if (!globalThis[STORE_KEY]) {
+        globalThis[STORE_KEY] = new AsyncLocalStorage();
+    }
+    return globalThis[STORE_KEY];
+}
+
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+function freezeCopy(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map(freezeCopy));
+    }
+    if (isPlainObject(value)) {
+        const copy = {};
+        for (const key of Object.keys(value)) {
+            copy[key] = freezeCopy(value[key]);
+        }
+        return Object.freeze(copy);
+    }
+    return value;
+}
+
+function assignDefined(target, source) {
+    for (const key of Object.keys(source)) {
+        if (source[key] !== undefined) target[key] = source[key];
+    }
+    return target;
+}
+
+function mergeStores(outer, inner) {
+    const merged = { ...(outer || {}) };
+    if (!inner || typeof inner !== 'object') return freezeCopy(merged);
+    for (const key of Object.keys(inner)) {
+        const value = inner[key];
+        if (value === undefined) continue;
+        if (key === LOGGER_SCOPE_KEY && isPlainObject(value)) {
+            merged[key] = assignDefined({ ...(merged[key] || {}) }, value);
+            continue;
+        }
+        merged[key] = value;
+    }
+    return freezeCopy(merged);
+}
+
+function runInContext(context, fn) {
+    const storage = als();
+    return storage.run(mergeStores(storage.getStore(), context), fn);
+}
+
+function getContext() {
+    return als().getStore() ?? null;
+}
+
+// The store is frozen per scope, so one scope object per store is enough.
+const EMPTY_SCOPE = Object.freeze({});
+const scopeByStore = new WeakMap();
+
+function getLoggerScope() {
+    const store = getContext();
+    if (!store) return EMPTY_SCOPE;
+    let scope = scopeByStore.get(store);
+    if (!scope) {
+        scope = {};
+        for (const key of INTEGRATION_KEYS) {
+            if (store[key] !== undefined) scope[key] = store[key];
+        }
+        // A set (hydrated) id beats a logger-only one, e.g. from a URL or a
+        // message body; a null id leaves the logger-only value in place.
+        const loggerKeys = store[LOGGER_SCOPE_KEY];
+        if (isPlainObject(loggerKeys)) {
+            for (const [key, value] of Object.entries(loggerKeys)) {
+                if (scope[key] === undefined || scope[key] === null) {
+                    scope[key] = value;
+                }
+            }
+        }
+        scope = Object.freeze(scope);
+        scopeByStore.set(store, scope);
+    }
+    return scope;
+}
+
+function hasOnlyLoggerKeys(store) {
+    if (!store || typeof store !== 'object') return false;
+    const keys = Object.keys(store);
+    return keys.length > 0 && keys.every((key) => key === LOGGER_SCOPE_KEY);
+}
+
+module.exports = {
+    LOGGER_SCOPE_KEY,
+    runInContext,
+    getContext,
+    getLoggerScope,
+    hasOnlyLoggerKeys,
+    isPlainObject,
+};

package/logs/contract-keys.js

@@ -0,0 +1,67 @@
+// Field names of the record contract (ADR-048 §3). A leaf: no requires.
+
+const REQUIRED_KEYS = ['timestamp', 'level', 'message', 'logger'];
+const RESOURCE_KEYS = ['appName', 'stage'];
+const TRACE_KEYS = ['trace_id', 'span_id', 'trace_flags'];
+const DROPPED_KEYS_FIELD = 'droppedKeys';
+const OWNED_KEYS = new Set([
+    ...REQUIRED_KEYS,
+    ...RESOURCE_KEYS,
+    ...TRACE_KEYS,
+    DROPPED_KEYS_FIELD,
+]);
+
+// Set by the scope builders (logs/context.js, core/invocation-scope.js,
+// core/create-handler.js) and the Module and IntegrationBase bindings.
+const SCOPE_KEYS = [
+    'integrationId',
+    'integrationType',
+    'userId',
+    'version',
+    'entityId',
+    'credentialId',
+    'requestId',
+    'messageId',
+    'receiveCount',
+    'processId',
+    'integrationEvent',
+    'handlerName',
+    'method',
+    'route',
+    'routeKey',
+    'invocation',
+];
+
+const CONTRACT_KEYS = [
+    ...new Set([...OWNED_KEYS, ...SCOPE_KEYS, 'eventName', 'statusCode', 'error']),
+];
+
+const RESERVED_KEYS = new Set([
+    'tenantId',
+    'type',
+    'time',
+    'record',
+    'errorType',
+    'errorMessage',
+    'stackTrace',
+    'service',
+    'env',
+    'host',
+    'source',
+    'status',
+    'severity',
+]);
+
+const PAYLOAD_KEYS = new Set(['body', 'rawBody', 'payload', 'response']);
+
+module.exports = {
+    REQUIRED_KEYS,
+    RESOURCE_KEYS,
+    TRACE_KEYS,
+    DROPPED_KEYS_FIELD,
+    OWNED_KEYS,
+    SCOPE_KEYS,
+    CONTRACT_KEYS,
+    RESERVED_KEYS,
+    PAYLOAD_KEYS,
+};

package/logs/debug-shims.js

@@ -0,0 +1,46 @@
+const util = require('node:util');
+const { getLogger } = require('./logger');
+const { getContext } = require('./context');
+const {
+    summarizeLambdaEvent,
+    toRequestInvocation,
+} = require('./summarize-event');
+
+// Deprecated. Kept for one major version; use getLogger or this.logger.
+const LEGACY_LOGGER_NAME = 'frigg.legacy';
+const FORMAT_DIRECTIVE = /%[sdifjoOc%]/;
+
+const legacy = () => getLogger(LEGACY_LOGGER_NAME);
+
+function debug(...messages) {
+    if (!messages.length) return;
+    const log = legacy();
+    if (!log.isLevelEnabled('DEBUG')) return;
+    const index = messages.findIndex((m) => typeof m === 'string');
+    if (index === 0 && FORMAT_DIRECTIVE.test(messages[0])) {
+        log.debug(util.format(...messages));
+        return;
+    }
+    const message = index === -1 ? '' : messages[index];
+    const args = messages.filter((_, i) => i !== index);
+    log.debug(message, args.length ? { args } : undefined);
+}
+
+function initDebugLog(...initMessages) {
+    if (getContext()?.log) return;
+    const log = legacy();
+    if (!log.isLevelEnabled('DEBUG')) return;
+    const event = initMessages.find((m) => m && typeof m === 'object');
+    log.debug('Debug log initialized', {
+        invocation: toRequestInvocation(summarizeLambdaEvent(event)),
+    });
+}
+
+function flushDebugLog(error) {
+    legacy().error('Unhandled error', {
+        eventName: 'frigg.legacy.error',
+        error: error || new Error('flushDebugLog called with empty error'),
+    });
+}
+
+module.exports = { debug, initDebugLog, flushDebugLog };

package/logs/denied-keys.js

@@ -0,0 +1,21 @@
+const { addDeniedKeys } = require('./redact');
+const { getLogger } = require('./logger');
+
+const warnedKeys = new Set();
+
+// addDeniedKeys plus one WARN per record-contract key it had to skip, so a
+// credential field named like a record field is visible wherever it is set.
+function registerDeniedKeys(keys) {
+    const ignored = addDeniedKeys(keys);
+    for (const key of ignored) {
+        if (warnedKeys.has(key)) continue;
+        warnedKeys.add(key);
+        getLogger('frigg.logger').warn(
+            'Credential field name is a record field; it stays visible in logs',
+            { eventName: 'frigg.logger.denied_key_ignored', key }
+        );
+    }
+    return ignored;
+}
+
+module.exports = { registerDeniedKeys };

package/logs/index.js

@@ -1,7 +1,18 @@
-const {debug, initDebugLog, flushDebugLog} = require('./logger');
+const { getLogger } = require('./logger');
+const { createMemorySink } = require('./sinks');
+const { resetLoggerForTests } = require('./logger-runtime');
+const { serializeError, toSanitizedSurrogate } = require('./serialize');
+const { redactValue } = require('./redact');
+const { debug, initDebugLog, flushDebugLog } = require('./debug-shims');
 
 module.exports = {
+    getLogger,
+    createMemorySink,
+    resetLoggerForTests,
+    serializeError,
+    redactValue,
+    toSanitizedSurrogate,
     debug,
     initDebugLog,
-    flushDebugLog
-}
+    flushDebugLog,
+};

package/logs/jest-logger-setup.js

@@ -0,0 +1,25 @@
+const { createMemorySink } = require('./sinks');
+const { resetLoggerForTests, takeViolationsForTests } = require('./logger-runtime');
+const { toContainNoSecretWindow } = require('./__fixtures__/matchers');
+
+expect.extend({ toContainNoSecretWindow });
+
+const resetToMemory = () =>
+    resetLoggerForTests({
+        level: 'TRACE',
+        sinks: [createMemorySink({ install: false })],
+        trackViolations: true,
+    });
+
+// Also at load: records written at require time must not reach fd 1.
+resetToMemory();
+
+beforeEach(resetToMemory);
+
+afterEach(() => {
+    const violations = takeViolationsForTests();
+    if (violations.length) {
+        const list = violations.map((v) => `${v.level} ${v.logger}: ${v.message}`).join('\n');
+        throw new Error(`frigg.* records at WARN or above need an eventName:\n${list}`);
+    }
+});