@mojaloop/sdk-scheme-adapter 24.14.0 → 24.15.1

package/CHANGELOG.md

@@ -1,4 +1,24 @@
 # Changelog: [mojaloop/sdk-scheme-adapter](https://github.com/mojaloop/sdk-scheme-adapter)
+### [24.15.1](https://github.com/mojaloop/sdk-scheme-adapter/compare/v24.15.0...v24.15.1) (2025-10-08)
+
+
+### Chore
+
+* created a separate file for SdkServer ([#619](https://github.com/mojaloop/sdk-scheme-adapter/issues/619)) ([063087e](https://github.com/mojaloop/sdk-scheme-adapter/commit/063087eefcf63dd293d29d6fb45020490f887daf))
+* **sbom:** update sbom [skip ci] ([b2cf810](https://github.com/mojaloop/sdk-scheme-adapter/commit/b2cf8101be59023e3be7a5da5510eff26c0b7648))
+
+## [24.15.0](https://github.com/mojaloop/sdk-scheme-adapter/compare/v24.14.0...v24.15.0) (2025-10-08)
+
+
+### Features
+
+* added trace_flags param ([#620](https://github.com/mojaloop/sdk-scheme-adapter/issues/620)) ([f19d92f](https://github.com/mojaloop/sdk-scheme-adapter/commit/f19d92f9b56b7a0f90120c3dc519218927bec0e2))
+
+
+### Chore
+
+* **sbom:** update sbom [skip ci] ([7f5f7a5](https://github.com/mojaloop/sdk-scheme-adapter/commit/7f5f7a568085edcf04a5d9ca6103b1e949ba52cf))
+
 ## [24.14.0](https://github.com/mojaloop/sdk-scheme-adapter/compare/v24.13.0...v24.14.0) (2025-10-08)
 
 

package/CLAUDE.md

@@ -21,6 +21,8 @@ The project consists of multiple modules organized using Nx workspace.
 
 
 **Critical File Locations:**
+- Main server class: `modules/api-svc/src/SdkServer.js`
+- Entry point: `modules/api-svc/src/index.js`
 - Models: `modules/api-svc/src/lib/model/`
 - Handlers: `modules/api-svc/src/{Inbound,Outbound}Server/handlers.js`
 - Config: `modules/*/src/config/default.json`

package/README.md

@@ -159,6 +159,23 @@ _Note that these instructions are for Linux based systems. For Mac and/or Window
 
 You can now examine the code of the Mock DFSP backend to understand how it implements the scheme-adapter simplified inbound API.
 
+
+## Observability Configuration
+
+### TRACE_FLAGS
+
+Controls the trace flags value in the W3C Trace Context `traceparent` header generated by the SDK.
+
+- **Environment Variable**: `TRACE_FLAGS`
+- **Format**: Two-character lowercase hexadecimal string (00-ff)
+- **Default**: `01` (sampled flag set)
+- **Example**: `TRACE_FLAGS=00` or `TRACE_FLAGS=01`
+
+The trace flags field indicates trace sampling options according to the [W3C Trace Context specification](https://www.w3.org/TR/trace-context/):
+- `00`: No flags set (not sampled)
+- `01`: Sampled flag set (trace should be sampled)
+- Custom values can be used for specific observability requirements
+
 ## Testing
 
 ### Unit Tests

package/modules/api-svc/src/InboundServer/handlers.js

@@ -51,7 +51,7 @@ const extractBodyHeadersSourceFspId = ctx => ({
 });
 
 const extractTraceHeaders = ctx => {
-    const { traceparent = generateTraceparent(), tracestate } = ctx.request.headers;
+    const { traceparent = generateTraceparent(undefined, ctx.state.conf.traceFlags), tracestate } = ctx.request.headers;
 
     const traceHeaders = {
         traceparent,

package/modules/api-svc/src/SdkServer.js

@@ -0,0 +1,560 @@
+/*****
+ License
+ --------------
+ Copyright © 2020-2025 Mojaloop Foundation
+ The Mojaloop files are made available by the Mojaloop Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+ Contributors
+ --------------
+ This is the official list of the Mojaloop project contributors for this file.
+ Names of the original copyright holders (individuals or organizations)
+ should be listed with a '*' in the first column. People who have
+ contributed from an organization can be listed under the organization
+ that actually holds the copyright for their contributions (see the
+ Mojaloop Foundation for an example). Those individuals should have
+ their names indented and be marked with a '-'. Email address can be added
+ optionally within square brackets <email>.
+
+ * Mojaloop Foundation
+ * Eugen Klymniuk <eugen.klymniuk@infitx.com>
+
+ --------------
+ ******/
+
+'use strict';
+
+const EventEmitter = require('node:events');
+const http = require('node:http');
+const https = require('node:https');
+const _ = require('lodash');
+
+const InboundServer = require('./InboundServer');
+const OutboundServer = require('./OutboundServer');
+const OAuthTestServer = require('./OAuthTestServer');
+const { BackendEventHandler } = require('./BackendEventHandler');
+const { FSPIOPEventHandler } = require('./FSPIOPEventHandler');
+const { MetricsServer, MetricsClient } = require('./lib/metrics');
+const TestServer = require('./TestServer');
+const ControlAgent = require('./ControlAgent');
+
+const Cache = require('./lib/cache');
+const { createAuthClient } = require('./lib/utils');
+const { logger } = require('./lib/logger');
+
+const PING_INTERVAL_MS = 30_000;
+
+const createCache = (config) => new Cache({
+    logger,
+    cacheUrl: config.cacheUrl,
+    enableTestFeatures: config.enableTestFeatures,
+    subscribeTimeoutSeconds:  config.requestProcessingTimeoutSeconds,
+});
+
+/**
+ * Class that creates and manages http servers that expose the SDK Scheme Adapter APIs.
+ */
+class SdkServer extends EventEmitter {
+    constructor(conf, logger) {
+        super({ captureExceptions: true });
+        this.conf = conf;
+        this.logger = logger;
+        this.cache = createCache(conf);
+
+        this.metricsClient = new MetricsClient();
+        this.metricsServer = new MetricsServer({
+            port: this.conf.metrics.port,
+            logger: this.logger
+        });
+
+        // Create shared Mojaloop agents for switch communication (used by both servers)
+        this.mojaloopSharedAgents = this._createMojaloopSharedAgents(this.conf);
+
+        this.oidc = createAuthClient(conf, logger);
+        this.oidc.auth.on('error', (msg) => {
+            this.emit('error', 'OIDC auth error in InboundApi', msg);
+        });
+
+        this.inboundServer = new InboundServer(
+            this.conf,
+            this.logger,
+            this.cache,
+            this.oidc,
+            this.mojaloopSharedAgents,
+        );
+        this.inboundServer.on('error', (...args) => {
+            this.logger.isErrorEnabled && this.logger.push({ args }).error('Unhandled error in Inbound Server');
+            this.emit('error', 'Unhandled error in Inbound Server');
+        });
+
+        this.outboundServer = new OutboundServer(
+            this.conf,
+            this.logger,
+            this.cache,
+            this.metricsClient,
+            this.oidc,
+            this.mojaloopSharedAgents,
+        );
+        this.outboundServer.on('error', (...args) => {
+            this.logger.isErrorEnabled && this.logger.push({ args }).error('Unhandled error in Outbound Server');
+            this.emit('error', 'Unhandled error in Outbound Server');
+        });
+
+        if (this.conf.oauthTestServer.enabled) {
+            this.oauthTestServer = new OAuthTestServer({
+                clientKey: this.conf.oauthTestServer.clientKey,
+                clientSecret: this.conf.oauthTestServer.clientSecret,
+                port: this.conf.oauthTestServer.listenPort,
+                logger: this.logger,
+            });
+        }
+
+        if (this.conf.enableTestFeatures) {
+            this.testServer = new TestServer({
+                config: this.conf,
+                port: this.conf.test.port,
+                logger: this.logger,
+                cache: this.cache,
+            });
+        }
+
+        if (this.conf.backendEventHandler.enabled) {
+            this.backendEventHandler = new BackendEventHandler({
+                config: this.conf,
+                logger: this.logger,
+            });
+        }
+
+        if (this.conf.fspiopEventHandler.enabled) {
+            this.fspiopEventHandler = new FSPIOPEventHandler({
+                config: this.conf,
+                logger: this.logger,
+                cache: this.cache,
+                oidc: this.oidc,
+            });
+        }
+    }
+
+    _shouldUpdateInboundServer(newConf) {
+        const isInboundDifferent = !_.isEqual(this.conf.inbound, newConf.inbound);
+        const isOutboundDifferent = !_.isEqual(this.conf.outbound, newConf.outbound);
+        const isPeerJWSKeysDifferent = !_.isEqual(this.conf.peerJWSKeys, newConf.peerJWSKeys);
+        const isJwsSigningKeyDifferent = !_.isEqual(this.conf.jwsSigningKey, newConf.jwsSigningKey);
+
+        if (isInboundDifferent) {
+            this.logger.debug('Inbound config is different', {
+                oldInbound: this.conf.inbound,
+                newInbound: newConf.inbound
+            });
+        }
+        if (isOutboundDifferent) {
+            this.logger.debug('Outbound config is different (checked in inbound update)', {
+                oldOutbound: this.conf.outbound,
+                newOutbound: newConf.outbound
+            });
+        }
+
+        if (isPeerJWSKeysDifferent) {
+            this.logger.debug('Peer JWS Keys config is different', {
+                oldPeerJWSKeys: this.conf.peerJWSKeys,
+                newPeerJWSKeys: newConf.peerJWSKeys
+            });
+        }
+
+        if (isJwsSigningKeyDifferent) {
+            this.logger.debug('JWS Signing Key config is different', {
+                oldJwsSigningKey: this.conf.jwsSigningKey,
+                newJwsSigningKey: newConf.jwsSigningKey
+            });
+        }
+
+        return isInboundDifferent || isOutboundDifferent || isPeerJWSKeysDifferent || isJwsSigningKeyDifferent;
+    }
+
+    _shouldUpdateOutboundServer(newConf) {
+        const isOutboundDifferent = !_.isEqual(this.conf.outbound, newConf.outbound);
+        const isJwsSigningKeyDifferent = !_.isEqual(this.conf.jwsSigningKey, newConf.jwsSigningKey);
+
+        if (isOutboundDifferent) {
+            this.logger.debug('Outbound config is different', {
+                oldOutbound: this.conf.outbound,
+                newOutbound: newConf.outbound
+            });
+        }
+
+        if (isJwsSigningKeyDifferent) {
+            this.logger.debug('JWS Signing Key config is different', {
+                oldJwsSigningKey: this.conf.jwsSigningKey,
+                newJwsSigningKey: newConf.jwsSigningKey
+            });
+        }
+
+        return isOutboundDifferent || isJwsSigningKeyDifferent;
+    }
+
+    /**
+     * Starts periodic polling of Management API for configuration updates.
+     * Only runs if PM4ML enabled and a polling interval configured.
+     */
+    _startConfigPolling() {
+        if (!this.conf.pm4mlEnabled || !this.conf.control.mgmtAPIPollIntervalMs) {
+            this.logger.info('No failsafe config polling configured');
+            return;
+        }
+
+        this.logger.info('starting failsafe config polling from Management API...', { intervalMs: this.conf.control.mgmtAPIPollIntervalMs });
+
+        this._configPollInterval = setInterval(
+            () => this._pollConfigFromMgmtAPI(),
+            this.conf.control.mgmtAPIPollIntervalMs
+        );
+
+        // Unref so it doesn't prevent process exit
+        this._configPollInterval.unref();
+    }
+
+    /**
+     * Polls Management API for configuration updates.
+     * Reuses the existing persistent WebSocket client (this.controlClient).
+     * Skips polling if:
+     * - Another config update is in progress
+     * - WebSocket client is not connected
+     */
+    async _pollConfigFromMgmtAPI() {
+        // Race condition prevention: skip if restart in progress
+        if (this._configUpdateInProgress) {
+            this.logger.info('config updating already in progress, skipping poll');
+            return;
+        }
+
+        // WebSocket readyState: 0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED
+        if (this.controlClient?.readyState !== 1) {
+            this.logger.warn('Control client not ready (not OPEN), skipping poll', { readyState: this.controlClient?.readyState });
+            return;
+        }
+
+        try {
+            const newConfig = await this.controlClient.getUpdatedConfig();
+            if (!newConfig) {
+                this.logger.warn('No config received from polling');
+                return;
+            }
+            this.logger.verbose('polling config from mgmt-api is done, checking for config changes...');
+
+            const mergedConfig = _.merge({}, this.conf, newConfig);
+            await this.restart(mergedConfig, { source: 'polling' });
+        } catch (err) {
+            this.logger.error('error in polling config from Management API: ', err);
+        }
+    }
+
+    /** Stops the config polling interval. */
+    _stopConfigPolling() {
+        if (this._configPollInterval) {
+            this.logger.verbose('stopping config polling');
+            clearInterval(this._configPollInterval);
+            this._configPollInterval = null;
+        }
+    }
+
+    async start() {
+        await this.cache.connect();
+        await this.oidc.auth.start();
+
+        // We only start the control client if we're running within Mojaloop Payment Manager.
+        // The control server is the Payment Manager Management API Service.
+        // We only start the client to connect to and listen to the Management API service for
+        // management protocol messages e.g configuration changes, certificate updates etc.
+        if (this.conf.pm4mlEnabled) {
+            const RESTART_INTERVAL_MS = 10000;
+            this.controlClient = await ControlAgent.createConnectedControlAgentWs(this.conf, this.logger);
+            this.controlClient.on(ControlAgent.EVENT.RECONFIGURE, this.restart.bind(this));
+
+            const schedulePing = () => {
+                clearTimeout(this.pingTimeout);
+                this.pingTimeout = setTimeout(() => {
+                    this.logger.error('Ping timeout, possible broken connection. Restarting server...');
+                    this.restart(_.merge({}, this.conf, {
+                        control: { stopped: Date.now() }
+                    }));
+                }, PING_INTERVAL_MS + this.conf.control.mgmtAPILatencyAssumption);
+            };
+
+            this.controlClient.on('ping', () => {
+                this.logger.debug('Received ping from control server');
+                schedulePing();
+            });
+
+            this.controlClient.on('close', () => {
+                clearTimeout(this.pingTimeout);
+                setTimeout(() => {
+                    this.logger.debug('Control client closed. Restarting server...');
+                    this.restart(_.merge({}, this.conf, {
+                        control: { stopped: Date.now() }
+                    }));
+                }, RESTART_INTERVAL_MS);
+            });
+
+            schedulePing();
+            this._startConfigPolling();
+        }
+
+        await Promise.all([
+            this.inboundServer.start(),
+            this.outboundServer.start(),
+            this.metricsServer.start(),
+            this.testServer?.start(),
+            this.oauthTestServer?.start(),
+            this.backendEventHandler?.start(),
+            this.fspiopEventHandler?.start(),
+        ]);
+    }
+
+    async restart(newConf, options = {}) {
+        const source = options.source || 'websocket'; // Track source of restart call - websocket or polling
+
+        // Race condition prevention
+        if (this._configUpdateInProgress) {
+            this.logger.info('restart already in progress, skipping', { source });
+            return;
+        }
+
+        const restartActionsTaken = {};
+        this.logger.debug('Server is restarting...', { source });
+        this._configUpdateInProgress = true;
+
+        try {
+            let oldCache;
+            const updateCache = !_.isEqual(this.conf.cacheUrl, newConf.cacheUrl)
+            || !_.isEqual(this.conf.enableTestFeatures, newConf.enableTestFeatures);
+            if (updateCache) {
+                oldCache = this.cache;
+                await this.cache.disconnect();
+                this.cache = createCache(newConf);
+                await this.cache.connect();
+                restartActionsTaken.updateCache = true;
+            }
+
+            const updateOIDC = !_.isEqual(this.conf.oidc, newConf.oidc)
+            || !_.isEqual(this.conf.outbound.tls, newConf.outbound.tls);
+            if (updateOIDC) {
+                this.oidc.auth.stop();
+                this.oidc = createAuthClient(newConf, this.logger);
+                this.oidc.auth.on('error', (msg) => {
+                    this.emit('error', 'OIDC auth error in InboundApi', msg);
+                });
+                await this.oidc.auth.start();
+                restartActionsTaken.updateOIDC = true;
+            }
+
+            this.logger.isDebugEnabled && this.logger.push({ oldConf: this.conf.inbound, newConf: newConf.inbound }).debug('Inbound server configuration');
+            const updateInboundServer = this._shouldUpdateInboundServer(newConf);
+            if (updateInboundServer) {
+                const stopStartLabel = 'InboundServer stop/start duration';
+                // eslint-disable-next-line no-console
+                console.time(stopStartLabel); // todo: remove console.time
+                await this.inboundServer.stop();
+
+                this.mojaloopSharedAgents = this._createMojaloopSharedAgents(newConf);
+                this.inboundServer = new InboundServer(
+                    newConf,
+                    this.logger,
+                    this.cache,
+                    this.oidc,
+                    this.mojaloopSharedAgents,
+                );
+                this.inboundServer.on('error', (...args) => {
+                    const errMessage = 'Unhandled error in Inbound Server';
+                    this.logger.push({ args }).error(errMessage);
+                    this.emit('error', errMessage);
+                });
+                await this.inboundServer.start();
+                // eslint-disable-next-line no-console
+                console.timeEnd(stopStartLabel);
+                restartActionsTaken.updateInboundServer = true;
+            }
+
+            this.logger.isDebugEnabled && this.logger.push({ oldConf: this.conf.outbound, newConf: newConf.outbound }).debug('Outbound server configuration');
+            const updateOutboundServer = this._shouldUpdateOutboundServer(newConf);
+            if (updateOutboundServer) {
+                const stopStartLabel = 'OutboundServer stop/start duration';
+                // eslint-disable-next-line no-console
+                console.time(stopStartLabel);
+                await this.outboundServer.stop();
+
+                this.mojaloopSharedAgents = this._createMojaloopSharedAgents(newConf);
+                this.outboundServer = new OutboundServer(
+                    newConf,
+                    this.logger,
+                    this.cache,
+                    this.metricsClient,
+                    this.oidc,
+                    this.mojaloopSharedAgents,
+                );
+                this.outboundServer.on('error', (...args) => {
+                    const errMessage = 'Unhandled error in Outbound Server';
+                    this.logger.push({ args }).error(errMessage);
+                    this.emit('error', errMessage);
+                });
+                await this.outboundServer.start();
+                // eslint-disable-next-line no-console
+                console.timeEnd(stopStartLabel);
+                restartActionsTaken.updateOutboundServer = true;
+            }
+
+            const updateFspiopEventHandler = !_.isEqual(this.conf.outbound, newConf.outbound)
+            && this.conf.fspiopEventHandler.enabled;
+            if (updateFspiopEventHandler) {
+                await this.fspiopEventHandler.stop();
+                this.fspiopEventHandler = new FSPIOPEventHandler({
+                    config: newConf,
+                    logger: this.logger,
+                    cache: this.cache,
+                    oidc: this.oidc,
+                });
+                await this.fspiopEventHandler.start();
+                restartActionsTaken.updateFspiopEventHandler = true;
+            }
+
+            const updateControlClient = !_.isEqual(this.conf.control, newConf.control);
+            if (updateControlClient) {
+                await this.controlClient?.stop();
+                if (this.conf.pm4mlEnabled) {
+                    const RESTART_INTERVAL_MS = 10000;
+
+                    const schedulePing = () => {
+                        clearTimeout(this.pingTimeout);
+                        this.pingTimeout = setTimeout(() => {
+                            this.logger.error('Ping timeout, possible broken connection. Restarting server...');
+                            this.restart(_.merge({}, newConf, {
+                                control: { stopped: Date.now() }
+                            }));
+                        }, PING_INTERVAL_MS + this.conf.control.mgmtAPILatencyAssumption);
+                    };
+
+                    schedulePing();
+
+                    this.controlClient = await ControlAgent.createConnectedControlAgentWs(newConf, this.logger);
+                    this.controlClient.on(ControlAgent.EVENT.RECONFIGURE, this.restart.bind(this));
+
+                    this.controlClient.on('ping', () => {
+                        this.logger.debug('Received ping from control server');
+                        schedulePing();
+                    });
+
+                    this.controlClient.on('close', () => {
+                        clearTimeout(this.pingTimeout);
+                        setTimeout(() => {
+                            this.logger.debug('Control client closed. Restarting server...');
+                            this.restart(_.merge({}, newConf, {
+                                control: { stopped: Date.now() }
+                            }));
+                        }, RESTART_INTERVAL_MS);
+                    });
+
+                    restartActionsTaken.updateControlClient = true;
+                }
+            }
+
+            const updateOAuthTestServer = !_.isEqual(newConf.oauthTestServer, this.conf.oauthTestServer);
+            if (updateOAuthTestServer) {
+                await this.oauthTestServer?.stop();
+                if (this.conf.oauthTestServer.enabled) {
+                    this.oauthTestServer = new OAuthTestServer({
+                        clientKey: newConf.oauthTestServer.clientKey,
+                        clientSecret: newConf.oauthTestServer.clientSecret,
+                        port: newConf.oauthTestServer.listenPort,
+                        logger: this.logger,
+                    });
+                    await this.oauthTestServer.start();
+                    restartActionsTaken.updateOAuthTestServer = true;
+                }
+            }
+
+            const updateTestServer = !_.isEqual(newConf.test.port, this.conf.test.port);
+            if (updateTestServer) {
+                await this.testServer?.stop();
+                if (this.conf.enableTestFeatures) {
+                    this.testServer = new TestServer({
+                        port: newConf.test.port,
+                        logger: this.logger,
+                        cache: this.cache,
+                        config: newConf.test,
+                    });
+                    await this.testServer.start();
+                    restartActionsTaken.updateTestServer = true;
+                }
+            }
+
+            this.conf = newConf;
+
+            await oldCache?.disconnect();
+
+            if (Object.keys(restartActionsTaken).length > 0) {
+                this.logger.info('Server is restarted', { restartActionsTaken, source });
+            } else {
+                this.logger.verbose('Server not restarted, no config changes detected', { source });
+            }
+        } catch (err) {
+            this.logger.error('error in Server restart: ', err);
+        } finally {
+            this._configUpdateInProgress = false;
+        }
+    }
+
+    stop() {
+        this._stopConfigPolling();
+
+        clearTimeout(this.pingTimeout);
+        this.oidc.auth.stop();
+        this.controlClient?.removeAllListeners();
+        this.inboundServer.removeAllListeners();
+        return Promise.all([
+            this.cache.disconnect(),
+            this.inboundServer.stop(),
+            this.outboundServer.stop(),
+            this.metricsServer.stop(),
+            this.oauthTestServer?.stop(),
+            this.testServer?.stop(),
+            this.controlClient?.stop(),
+            this.backendEventHandler?.stop(),
+            this.fspiopEventHandler?.stop(),
+        ]);
+    }
+
+    _createMojaloopSharedAgents(conf) {
+        const httpAgent = new http.Agent({
+            keepAlive: true,
+            maxSockets: conf.outbound?.maxSockets || 256,
+        });
+
+        // Create HTTPS agent based on TLS configuration for Mojaloop switch communication
+        const httpsAgentOptions = {
+            keepAlive: true,
+            maxSockets: conf.outbound?.maxSockets || 256,
+        };
+
+        // Apply TLS configuration if mTLS is enabled for switch communication
+        if (conf.outbound?.tls?.mutualTLS?.enabled && conf.outbound?.tls?.creds) {
+            Object.assign(httpsAgentOptions, conf.outbound.tls.creds);
+        }
+
+        const httpsAgent = new https.Agent(httpsAgentOptions);
+
+        // Prevent accidental logging of agent internals
+        httpAgent.toJSON = () => ({ type: 'HttpAgent', keepAlive: httpAgent.keepAlive });
+        httpsAgent.toJSON = () => ({ type: 'HttpsAgent', keepAlive: httpsAgent.keepAlive });
+
+        this.logger.isInfoEnabled && this.logger.info('Created shared HTTP and HTTPS agents for Mojaloop switch communication');
+
+        return {
+            httpAgent,
+            httpsAgent
+        };
+    }
+}
+
+module.exports = SdkServer;

package/modules/api-svc/src/config.js

@@ -282,4 +282,8 @@ module.exports = {
         backoffFactor: env.get('GET_TRANSFER_REQUEST_RETRY_BACKOFF_FACTOR').default('2').asIntPositive(),
     },
     patchNotificationGraceTimeMs: env.get('PATCH_NOTIFICATION_GRACE_TIME_MS').default('15000').asIntPositive(),
+
+    // W3C Trace Context specification - trace flags for traceparent header
+    // Must be a two-character lowercase hex string (00-ff)
+    traceFlags: env.get('TRACE_FLAGS').default('01').asString(),
 };