@newrelic/preflight 1.6.11 → 1.6.13

package/dist/config.d.ts

@@ -6,6 +6,8 @@ import type { PersonalAlertThresholds } from './alerts/types.js';
 export interface McpServerConfig {
     readonly licenseKey?: string;
     readonly accountId?: string;
+    /** Config-file schema version. Defaults to 1; see CURRENT_CONFIG_VERSION. */
+    readonly configVersion: number;
     readonly appName: string;
     readonly developer: string;
     readonly teamId: string | null;
@@ -32,31 +34,40 @@ export interface McpServerConfig {
     readonly nrApiKey: string | null;
     readonly digestWebhookUrl: string | null;
     readonly digestSchedule: string;
+    /** Default: 90. `null` disables retention (only reachable via an explicit `null` in config.json). */
     readonly retainSessionsDays: number | null;
     readonly personalAlertThresholds: PersonalAlertThresholds;
-    readonly otlpEndpoint: string | null;
-    readonly otlpHeaders: Readonly<Record<string, string>>;
-    readonly transport: 'nr-events-api' | 'otlp' | 'both';
     readonly mode: 'cloud' | 'local' | 'both';
     readonly platformTarget?: PlatformTarget;
-    /** Enable the local OTLP/HTTP receiver. Default: false. */
-    readonly otlpReceiverEnabled: boolean;
-    /** Port for the local OTLP/HTTP receiver. Default: 4318. */
-    readonly otlpReceiverPort: number;
-    /** Bind address for the local OTLP/HTTP receiver. Default: '127.0.0.1'. */
-    readonly otlpReceiverBindAddress: string;
     /**
-     * OTLP forward endpoint — where to relay received spans.
-     * Defaults to New Relic US OTLP endpoint when licenseKey is present.
-     * Set to null to disable forwarding (receive and enrich only, then drop).
+     * OTLP-related config, grouped to match the `dashboard`/`alerts` nesting
+     * precedent. The config-file schema also still accepts the legacy flat
+     * top-level keys (`otlpEndpoint`, `otlpReceiverPort`, etc.) for backward
+     * compatibility — see `pickOtlpValue()` in loadMcpConfig().
      */
-    readonly otlpForwardEndpoint: string | null;
-    /**
-     * HTTP headers added to every OTLP forward request (e.g. `{ 'api-key': licenseKey }`).
-     * Defaults to `{ 'api-key': licenseKey }` when licenseKey is present.
-     * Configurable via NR_AI_OTLP_FORWARD_HEADERS (comma-separated key=value pairs).
-     */
-    readonly otlpForwardHeaders: Readonly<Record<string, string>>;
+    readonly otlp: {
+        readonly endpoint: string | null;
+        readonly headers: Readonly<Record<string, string>>;
+        readonly transport: 'nr-events-api' | 'otlp' | 'both';
+        /** Enable the local OTLP/HTTP receiver. Default: false. */
+        readonly receiverEnabled: boolean;
+        /** Port for the local OTLP/HTTP receiver. Default: 4318. */
+        readonly receiverPort: number;
+        /** Bind address for the local OTLP/HTTP receiver. Default: '127.0.0.1'. */
+        readonly receiverBindAddress: string;
+        /**
+         * OTLP forward endpoint — where to relay received spans.
+         * Defaults to New Relic US OTLP endpoint when licenseKey is present.
+         * Set to null to disable forwarding (receive and enrich only, then drop).
+         */
+        readonly forwardEndpoint: string | null;
+        /**
+         * HTTP headers added to every OTLP forward request (e.g. `{ 'api-key': licenseKey }`).
+         * Defaults to `{ 'api-key': licenseKey }` when licenseKey is present.
+         * Configurable via NR_AI_OTLP_FORWARD_HEADERS (comma-separated key=value pairs).
+         */
+        readonly forwardHeaders: Readonly<Record<string, string>>;
+    };
     readonly dashboard: {
         readonly port: number;
         readonly host: string;
@@ -78,6 +89,7 @@ export interface McpServerConfig {
 export declare const DEFAULT_STORAGE_PATH: string;
 export type PlatformTarget = 'native' | 'wsl-windows-cc' | 'wsl-linux-cc';
 export declare const ConfigFileSchema: z.ZodObject<{
+    configVersion: z.ZodOptional<z.ZodNumber>;
     licenseKey: z.ZodOptional<z.ZodString>;
     accountId: z.ZodOptional<z.ZodString>;
     appName: z.ZodOptional<z.ZodString>;
@@ -116,6 +128,11 @@ export declare const ConfigFileSchema: z.ZodObject<{
         otlp: "otlp";
         both: "both";
     }>>;
+    otlpReceiverEnabled: z.ZodOptional<z.ZodBoolean>;
+    otlpReceiverPort: z.ZodOptional<z.ZodNumber>;
+    otlpReceiverBindAddress: z.ZodOptional<z.ZodString>;
+    otlpForwardEndpoint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    otlpForwardHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     mode: z.ZodOptional<z.ZodEnum<{
         both: "both";
         cloud: "cloud";
@@ -126,11 +143,20 @@ export declare const ConfigFileSchema: z.ZodObject<{
         "wsl-windows-cc": "wsl-windows-cc";
         "wsl-linux-cc": "wsl-linux-cc";
     }>>;
-    otlpReceiverEnabled: z.ZodOptional<z.ZodBoolean>;
-    otlpReceiverPort: z.ZodOptional<z.ZodNumber>;
-    otlpReceiverBindAddress: z.ZodOptional<z.ZodString>;
-    otlpForwardEndpoint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    otlpForwardHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    otlp: z.ZodOptional<z.ZodObject<{
+        endpoint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        transport: z.ZodOptional<z.ZodEnum<{
+            "nr-events-api": "nr-events-api";
+            otlp: "otlp";
+            both: "both";
+        }>>;
+        receiverEnabled: z.ZodOptional<z.ZodBoolean>;
+        receiverPort: z.ZodOptional<z.ZodNumber>;
+        receiverBindAddress: z.ZodOptional<z.ZodString>;
+        forwardEndpoint: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        forwardHeaders: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$loose>>;
     alerts: z.ZodOptional<z.ZodObject<{
         personal: z.ZodOptional<z.ZodObject<{
             dailyCostUsd: z.ZodOptional<z.ZodNumber>;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -9,8 +9,21 @@ import { REDACTION_PATTERNS as DEFAULT_REDACTION_PATTERNS } from './redaction-pa
 import { resolveRecordContent } from './record-content-gate.js';
 const logger = createLogger('mcp-config');
 export const DEFAULT_STORAGE_PATH = resolve(homedir(), '.newrelic-preflight');
+// Applied only when neither the env var nor the config file specify
+// retainSessionsDays at all — an explicit `null` in config.json still means
+// "retention disabled" (see the resolution logic below).
+const DEFAULT_RETAIN_SESSIONS_DAYS = 90;
+/**
+ * Bump when a change to config.json's shape is non-additive (a field is
+ * renamed, moved, or removed) so a future migration path has something to
+ * branch on. Every change to date has been additive — including the `otlp`
+ * nested object below, which was introduced as an accept-both addition
+ * rather than a breaking rename — so this has never moved past 1.
+ */
+const CURRENT_CONFIG_VERSION = 1;
 export const ConfigFileSchema = z
     .object({
+    configVersion: z.number().int().optional(),
     licenseKey: z.string().optional(),
     accountId: z.string().optional(),
     appName: z.string().optional(),
@@ -37,16 +50,32 @@ export const ConfigFileSchema = z
     digestWebhookUrl: z.string().nullable().optional(),
     digestSchedule: z.string().optional(),
     retainSessionsDays: z.number().nullable().optional(),
+    // Legacy flat OTLP fields — deprecated in favor of the nested `otlp`
+    // object below, but still accepted for backward compatibility (using
+    // one logs a deprecation warning; see pickOtlpValue() in loadMcpConfig).
     otlpEndpoint: z.string().nullable().optional(),
     otlpHeaders: z.record(z.string(), z.string()).optional(),
     transport: z.enum(['nr-events-api', 'otlp', 'both']).optional(),
-    mode: z.enum(['cloud', 'local', 'both']).optional(),
-    platformTarget: z.enum(['native', 'wsl-windows-cc', 'wsl-linux-cc']).optional(),
     otlpReceiverEnabled: z.boolean().optional(),
     otlpReceiverPort: z.number().optional(),
     otlpReceiverBindAddress: z.string().optional(),
     otlpForwardEndpoint: z.string().nullable().optional(),
     otlpForwardHeaders: z.record(z.string(), z.string()).optional(),
+    mode: z.enum(['cloud', 'local', 'both']).optional(),
+    platformTarget: z.enum(['native', 'wsl-windows-cc', 'wsl-linux-cc']).optional(),
+    otlp: z
+        .object({
+        endpoint: z.string().nullable().optional(),
+        headers: z.record(z.string(), z.string()).optional(),
+        transport: z.enum(['nr-events-api', 'otlp', 'both']).optional(),
+        receiverEnabled: z.boolean().optional(),
+        receiverPort: z.number().optional(),
+        receiverBindAddress: z.string().optional(),
+        forwardEndpoint: z.string().nullable().optional(),
+        forwardHeaders: z.record(z.string(), z.string()).optional(),
+    })
+        .passthrough()
+        .optional(),
     alerts: z
         .object({
         personal: z
@@ -161,18 +190,25 @@ function envBool(key, defaultValue) {
         return false;
     return defaultValue;
 }
+// Applied to every return path of envInt (not just the parsed-env-var one) so
+// a bounds-checked call site is protected uniformly regardless of whether the
+// value actually came from the env var or from its (often config-file- or
+// CLI-derived) `defaultValue` argument.
+function clampNumber(value, bounds) {
+    if (bounds?.min !== undefined && value < bounds.min)
+        return bounds.min;
+    if (bounds?.max !== undefined && value > bounds.max)
+        return bounds.max;
+    return value;
+}
 function envInt(key, defaultValue, bounds) {
     const val = process.env[key];
     if (val === undefined)
-        return defaultValue;
+        return clampNumber(defaultValue, bounds);
     const parsed = parseInt(val, 10);
     if (Number.isNaN(parsed))
-        return defaultValue;
-    if (bounds?.min !== undefined && parsed < bounds.min)
-        return bounds.min;
-    if (bounds?.max !== undefined && parsed > bounds.max)
-        return bounds.max;
-    return parsed;
+        return clampNumber(defaultValue, bounds);
+    return clampNumber(parsed, bounds);
 }
 function envLogLevel(key, defaultValue) {
     const val = process.env[key]?.toLowerCase();
@@ -255,6 +291,20 @@ function parseOtlpHeaders(headerString) {
     }
     return result;
 }
+// Resolves a config-file OTLP field: the new nested `otlp.X` value wins when
+// present; otherwise falls back to the legacy flat top-level key, recording
+// its name in `used` so the caller can warn about exactly the legacy keys
+// that were actually consulted (not merely present-but-shadowed by a nested
+// value for the same field).
+function pickOtlpValue(nested, flat, legacyKey, used) {
+    if (nested !== undefined)
+        return nested;
+    if (flat !== undefined) {
+        used.push(legacyKey);
+        return flat;
+    }
+    return undefined;
+}
 /**
  * Validate the alerts.rulesPath value. The path is read from the user's
  * config file or NR_AI_ALERTS_RULES_PATH env var; both are user-controlled
@@ -294,6 +344,21 @@ function validateRulesPath(rawPath, storagePath) {
     }
     return resolved;
 }
+// Config-file-sourced numeric fields (budgets, retention) validate positivity
+// only on the env-var path today — a negative/zero value in config.json
+// silently disables the guardrail with no warning, unlike every other
+// malformed-input path in this file (see validateRulesPath, dashboard.host,
+// parseProxyUpstreams). Callers decide their own fallback value; this only
+// validates and logs.
+function validateFilePositiveNumber(value, fieldName) {
+    if (Number.isFinite(value) && value > 0)
+        return true;
+    logger.warn(`${fieldName} in config file must be a positive number — ignoring value`, {
+        fieldName,
+        value,
+    });
+    return false;
+}
 function parseProxyUpstreams(envValue, fileValue) {
     // Env var takes precedence (JSON string)
     if (envValue) {
@@ -363,6 +428,16 @@ export function loadMcpConfig(cliOptions) {
         'antiPatternCountMax',
     ]);
     const knownDashboardKeys = new Set(['port', 'host', 'openOnStart']);
+    const knownOtlpKeys = new Set([
+        'endpoint',
+        'headers',
+        'transport',
+        'receiverEnabled',
+        'receiverPort',
+        'receiverBindAddress',
+        'forwardEndpoint',
+        'forwardHeaders',
+    ]);
     if (file.alerts && typeof file.alerts === 'object') {
         const alerts = file.alerts;
         const unknownAlertsKeys = Object.keys(alerts).filter((k) => !knownAlertsKeys.has(k));
@@ -393,6 +468,15 @@ export function loadMcpConfig(cliOptions) {
             });
         }
     }
+    if (file.otlp && typeof file.otlp === 'object') {
+        const unknownOtlpKeys = Object.keys(file.otlp).filter((k) => !knownOtlpKeys.has(k));
+        if (unknownOtlpKeys.length > 0) {
+            logger.warn('Unknown keys in otlp config (ignored)', {
+                unknownFields: unknownOtlpKeys,
+                path: configFilePath,
+            });
+        }
+    }
     // --- Resolve mode early so we can gate licenseKey/accountId requirements ---
     // File mode is already validated by the zod schema in loadConfigFile.
     const VALID_MODES = ['cloud', 'local', 'both'];
@@ -442,6 +526,7 @@ export function loadMcpConfig(cliOptions) {
     const config = {
         licenseKey,
         accountId,
+        configVersion: typeof file.configVersion === 'number' ? file.configVersion : CURRENT_CONFIG_VERSION,
         appName: process.env.NEW_RELIC_AI_MCP_APP_NAME ??
             (typeof file.appName === 'string' ? file.appName : 'preflight'),
         model: process.env.NEW_RELIC_AI_MODEL ??
@@ -472,7 +557,11 @@ export function loadMcpConfig(cliOptions) {
                 if (Number.isFinite(v) && v > 0)
                     return v;
             }
-            return typeof file.sessionBudgetUsd === 'number' ? file.sessionBudgetUsd : null;
+            if (typeof file.sessionBudgetUsd !== 'number')
+                return null;
+            return validateFilePositiveNumber(file.sessionBudgetUsd, 'sessionBudgetUsd')
+                ? file.sessionBudgetUsd
+                : null;
         })(),
         dailyBudgetUsd: (() => {
             const raw = process.env.NEW_RELIC_AI_DAILY_BUDGET_USD;
@@ -481,7 +570,11 @@ export function loadMcpConfig(cliOptions) {
                 if (Number.isFinite(v) && v > 0)
                     return v;
             }
-            return typeof file.dailyBudgetUsd === 'number' ? file.dailyBudgetUsd : null;
+            if (typeof file.dailyBudgetUsd !== 'number')
+                return null;
+            return validateFilePositiveNumber(file.dailyBudgetUsd, 'dailyBudgetUsd')
+                ? file.dailyBudgetUsd
+                : null;
         })(),
         weeklyBudgetUsd: (() => {
             const raw = process.env.NEW_RELIC_AI_WEEKLY_BUDGET_USD;
@@ -490,13 +583,20 @@ export function loadMcpConfig(cliOptions) {
                 if (Number.isFinite(v) && v > 0)
                     return v;
             }
-            return typeof file.weeklyBudgetUsd === 'number' ? file.weeklyBudgetUsd : null;
+            if (typeof file.weeklyBudgetUsd !== 'number')
+                return null;
+            return validateFilePositiveNumber(file.weeklyBudgetUsd, 'weeklyBudgetUsd')
+                ? file.weeklyBudgetUsd
+                : null;
         })(),
-        port: cliOptions?.port ??
+        // clampNumber wraps the whole expression, not just envInt's own bounds
+        // param, because cliOptions?.port short-circuits envInt (and its
+        // clamping) entirely when a CLI value is supplied.
+        port: clampNumber(cliOptions?.port ??
             envInt('NEW_RELIC_AI_MCP_PORT', typeof file.port === 'number' ? file.port : 9847, {
                 min: 1,
                 max: 65535,
-            }),
+            }), { min: 1, max: 65535 }),
         logLevel: cliOptions?.logLevel ??
             envLogLevel('NEW_RELIC_AI_MCP_LOG_LEVEL', typeof file.logLevel === 'string' &&
                 ['debug', 'info', 'warn', 'error'].includes(file.logLevel)
@@ -517,83 +617,128 @@ export function loadMcpConfig(cliOptions) {
                 if (Number.isFinite(v) && v > 0)
                     return v;
             }
-            return typeof file.retainSessionsDays === 'number' ? file.retainSessionsDays : null;
-        })(),
-        otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??
-            (typeof file.otlpEndpoint === 'string' ? file.otlpEndpoint : null),
-        otlpHeaders: (() => {
-            const envValue = process.env.OTEL_EXPORTER_OTLP_HEADERS;
-            if (envValue)
-                return parseOtlpHeaders(envValue);
-            return typeof file.otlpHeaders === 'object' && file.otlpHeaders !== null
-                ? file.otlpHeaders
-                : {};
-        })(),
-        transport: process.env.NEW_RELIC_AI_TRANSPORT === 'otlp'
-            ? 'otlp'
-            : process.env.NEW_RELIC_AI_TRANSPORT === 'both'
-                ? 'both'
-                : typeof file.transport === 'string' &&
-                    (file.transport === 'otlp' || file.transport === 'both')
-                    ? file.transport
-                    : 'nr-events-api',
-        mode,
-        otlpReceiverEnabled: envBool('NR_AI_OTLP_RECEIVER_ENABLED', typeof file.otlpReceiverEnabled === 'boolean' ? file.otlpReceiverEnabled : false),
-        otlpReceiverPort: envInt('NR_AI_OTLP_RECEIVER_PORT', typeof file.otlpReceiverPort === 'number' ? file.otlpReceiverPort : 4318, { min: 1, max: 65535 }),
-        otlpReceiverBindAddress: (() => {
-            const envVal = process.env.NR_AI_OTLP_RECEIVER_BIND_ADDRESS;
-            if (envVal !== undefined && envVal !== '')
-                return envVal;
-            if (typeof file.otlpReceiverBindAddress === 'string' && file.otlpReceiverBindAddress !== '') {
-                return file.otlpReceiverBindAddress;
+            if (typeof file.retainSessionsDays === 'number') {
+                // An invalid (non-positive) value falls back to the default rather
+                // than null — null already has a distinct, intentional meaning
+                // (explicit opt-out, handled below); a typo'd negative number is a
+                // mistake, not an opt-out.
+                return validateFilePositiveNumber(file.retainSessionsDays, 'retainSessionsDays')
+                    ? file.retainSessionsDays
+                    : DEFAULT_RETAIN_SESSIONS_DAYS;
             }
-            return '127.0.0.1';
-        })(),
-        otlpForwardEndpoint: (() => {
-            const envVal = process.env.NR_AI_OTLP_FORWARD_ENDPOINT;
-            // Default to the NR OTLP endpoint only when not in local mode. Local users
-            // may still set the value explicitly via env or config file (e.g. to point
-            // at a self-hosted collector); we just don't synthesize a NR default for them.
-            const defaultEndpoint = mode !== 'local' && licenseKey !== undefined ? 'https://otlp.nr-data.net' : null;
-            const endpoint = envVal !== undefined
-                ? envVal || null
-                : typeof file.otlpForwardEndpoint === 'string'
-                    ? file.otlpForwardEndpoint || null
-                    : defaultEndpoint;
-            if (endpoint === null)
+            // Explicit `null` in the config file is a deliberate opt-out — distinct
+            // from the key being absent entirely, which falls through to the default.
+            if (file.retainSessionsDays === null)
                 return null;
-            try {
-                const url = new URL(endpoint);
-                if (url.protocol === 'https:')
-                    return endpoint;
-                if (url.protocol === 'http:') {
-                    logger.warn('OTLP forward endpoint uses http:// instead of https:// — TLS not enabled', {
+            return DEFAULT_RETAIN_SESSIONS_DAYS;
+        })(),
+        mode,
+        // The 8 OTLP-related fields are grouped here (matching the dashboard/alerts
+        // nesting precedent). Each still accepts the legacy flat top-level key for
+        // backward compatibility — pickOtlpValue() prefers the nested `otlp.X`
+        // value and records which legacy keys were actually consulted so exactly
+        // those can be named in a single deprecation warning below.
+        otlp: (() => {
+            const fileOtlp = file.otlp ?? {};
+            const usedLegacyOtlpKeys = [];
+            const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??
+                pickOtlpValue(typeof fileOtlp.endpoint === 'string' ? fileOtlp.endpoint : undefined, typeof file.otlpEndpoint === 'string' ? file.otlpEndpoint : undefined, 'otlpEndpoint', usedLegacyOtlpKeys) ??
+                null;
+            const headers = (() => {
+                const envValue = process.env.OTEL_EXPORTER_OTLP_HEADERS;
+                if (envValue)
+                    return parseOtlpHeaders(envValue);
+                return (pickOtlpValue(typeof fileOtlp.headers === 'object' && fileOtlp.headers !== null
+                    ? fileOtlp.headers
+                    : undefined, typeof file.otlpHeaders === 'object' && file.otlpHeaders !== null
+                    ? file.otlpHeaders
+                    : undefined, 'otlpHeaders', usedLegacyOtlpKeys) ?? {});
+            })();
+            const transportValue = process.env.NEW_RELIC_AI_TRANSPORT === 'otlp'
+                ? 'otlp'
+                : process.env.NEW_RELIC_AI_TRANSPORT === 'both'
+                    ? 'both'
+                    : (pickOtlpValue(fileOtlp.transport === 'otlp' || fileOtlp.transport === 'both'
+                        ? fileOtlp.transport
+                        : undefined, file.transport === 'otlp' || file.transport === 'both' ? file.transport : undefined, 'transport', usedLegacyOtlpKeys) ?? 'nr-events-api');
+            const receiverEnabled = envBool('NR_AI_OTLP_RECEIVER_ENABLED', pickOtlpValue(typeof fileOtlp.receiverEnabled === 'boolean' ? fileOtlp.receiverEnabled : undefined, typeof file.otlpReceiverEnabled === 'boolean' ? file.otlpReceiverEnabled : undefined, 'otlpReceiverEnabled', usedLegacyOtlpKeys) ?? false);
+            const receiverPort = envInt('NR_AI_OTLP_RECEIVER_PORT', pickOtlpValue(typeof fileOtlp.receiverPort === 'number' ? fileOtlp.receiverPort : undefined, typeof file.otlpReceiverPort === 'number' ? file.otlpReceiverPort : undefined, 'otlpReceiverPort', usedLegacyOtlpKeys) ?? 4318, { min: 1, max: 65535 });
+            const receiverBindAddress = (() => {
+                const envVal = process.env.NR_AI_OTLP_RECEIVER_BIND_ADDRESS;
+                if (envVal !== undefined && envVal !== '')
+                    return envVal;
+                return (pickOtlpValue(typeof fileOtlp.receiverBindAddress === 'string' && fileOtlp.receiverBindAddress !== ''
+                    ? fileOtlp.receiverBindAddress
+                    : undefined, typeof file.otlpReceiverBindAddress === 'string' && file.otlpReceiverBindAddress !== ''
+                    ? file.otlpReceiverBindAddress
+                    : undefined, 'otlpReceiverBindAddress', usedLegacyOtlpKeys) ?? '127.0.0.1');
+            })();
+            const forwardEndpoint = (() => {
+                const envVal = process.env.NR_AI_OTLP_FORWARD_ENDPOINT;
+                // Default to the NR OTLP endpoint only when not in local mode. Local users
+                // may still set the value explicitly via env or config file (e.g. to point
+                // at a self-hosted collector); we just don't synthesize a NR default for them.
+                const defaultEndpoint = mode !== 'local' && licenseKey !== undefined ? 'https://otlp.nr-data.net' : null;
+                const fileValue = pickOtlpValue(typeof fileOtlp.forwardEndpoint === 'string' ? fileOtlp.forwardEndpoint : undefined, typeof file.otlpForwardEndpoint === 'string' ? file.otlpForwardEndpoint : undefined, 'otlpForwardEndpoint', usedLegacyOtlpKeys);
+                const endpoint = envVal !== undefined
+                    ? envVal || null
+                    : fileValue !== undefined
+                        ? fileValue || null
+                        : defaultEndpoint;
+                if (endpoint === null)
+                    return null;
+                try {
+                    const url = new URL(endpoint);
+                    if (url.protocol === 'https:')
+                        return endpoint;
+                    if (url.protocol === 'http:') {
+                        logger.warn('OTLP forward endpoint uses http:// instead of https:// — TLS not enabled', { endpoint });
+                        return endpoint;
+                    }
+                    logger.warn('OTLP forward endpoint has unexpected protocol', {
                         endpoint,
+                        protocol: url.protocol,
                     });
                     return endpoint;
                 }
-                logger.warn('OTLP forward endpoint has unexpected protocol', {
-                    endpoint,
-                    protocol: url.protocol,
-                });
-                return endpoint;
-            }
-            catch (_err) {
-                logger.error('OTLP forward endpoint is not a valid URL', { endpoint });
-                return null;
-            }
-        })(),
-        otlpForwardHeaders: (() => {
-            const envValue = process.env.NR_AI_OTLP_FORWARD_HEADERS;
-            if (envValue !== undefined)
-                return parseOtlpHeaders(envValue);
-            if (typeof file.otlpForwardHeaders === 'object' && file.otlpForwardHeaders !== null) {
-                return file.otlpForwardHeaders;
+                catch (_err) {
+                    logger.error('OTLP forward endpoint is not a valid URL', { endpoint });
+                    return null;
+                }
+            })();
+            const forwardHeaders = (() => {
+                const envValue = process.env.NR_AI_OTLP_FORWARD_HEADERS;
+                if (envValue !== undefined)
+                    return parseOtlpHeaders(envValue);
+                const fileValue = pickOtlpValue(typeof fileOtlp.forwardHeaders === 'object' && fileOtlp.forwardHeaders !== null
+                    ? fileOtlp.forwardHeaders
+                    : undefined, typeof file.otlpForwardHeaders === 'object' && file.otlpForwardHeaders !== null
+                    ? file.otlpForwardHeaders
+                    : undefined, 'otlpForwardHeaders', usedLegacyOtlpKeys);
+                if (fileValue !== undefined)
+                    return fileValue;
+                // Don't synthesize a NR api-key header default in local mode — the licenseKey
+                // may be present in the env from another tool, and we must not leak it to a
+                // forward target the user didn't explicitly configure.
+                return mode !== 'local' && licenseKey !== undefined ? { 'api-key': licenseKey } : {};
+            })();
+            if (usedLegacyOtlpKeys.length > 0) {
+                logger.warn('Config file uses deprecated flat OTLP fields — move these under a nested "otlp" object', 
+                // Field name deliberately avoids "key"/"keys" — the logger's redact()
+                // treats any key-shaped property name as secret-bearing and would
+                // replace the whole array with '***' (see SECRET_KEY_RE).
+                { legacyFieldNames: usedLegacyOtlpKeys, path: configFilePath });
             }
-            // Don't synthesize a NR api-key header default in local mode — the licenseKey
-            // may be present in the env from another tool, and we must not leak it to a
-            // forward target the user didn't explicitly configure.
-            return mode !== 'local' && licenseKey !== undefined ? { 'api-key': licenseKey } : {};
+            return {
+                endpoint,
+                headers,
+                transport: transportValue,
+                receiverEnabled,
+                receiverPort,
+                receiverBindAddress,
+                forwardEndpoint,
+                forwardHeaders,
+            };
         })(),
         personalAlertThresholds: (() => {
             const fileThresholds = file.alerts?.personal;