@futdevpro/nts-dynamo 1.15.86 → 1.15.89

package/src/_collections/global-settings.const.ts

@@ -1,109 +1,117 @@
-
-
-import { DyNTS_RouteSecurity } from '../_enums/route-security.enum';
-import { DyNTS_Global_Settings } from '../_models/interfaces/global-settings.interface';
-import { DyNTS_SocketSecurity } from '../_modules/socket/_enums/socket-security.enum';
-import { DyNTS_getEnvironment_settings } from './get-environment-settings.util';
-
-/**
- * Default configuration used across the NodeTS framework.
- * These values can be overridden when bootstrapping the server.
- */
-export const DyNTS_global_settings: DyNTS_Global_Settings = {
-  baseUrl: '/api',
-  systemVersion: 'unknown-version',
-  defaultRouteSecurity: DyNTS_RouteSecurity.open,
-  defaultSocketSecurity: DyNTS_SocketSecurity.open,
-  
-  defaultPageSize: 10,
-  archiveListAfter: 100,
-  env_settings: DyNTS_getEnvironment_settings(),
-  
-  autoResolveEndpointCirculationErrors: true,
-  compactErrorResponse: true,
-
-  log_settings: {
-    highDetailedLogs: false,
-    
-    setup: false,
-  
-    request: true,
-    requestsContent: false,
-    responseContent: false,
-    requestStackLocation: false,
-  
-    socket_allEvents: true,
-    socket_mainEvents: true,
-    socket_eventContent: false,
-  
-    api_events: true,
-    api_requestContents: false,
-    api_requestSettings: false,
-    api_responseContents: false,
-    api_errors: true,
-  
-    detailedErrors: false,
-
-    server_debug: false,
-
-    logs_endpoint: {
-      enabled: false,
-      maxEntries: 2000,
-    },
-  },
-
-  autoResearchIssues: true,
-
-  // Auth-service kötelező alapból (régi viselkedés). Public / no-auth szervereknél
-  // `auth_settings.optional = true` → getAuthService() undefined-ot ad dobás helyett,
-  // és a startup 'Authentication Service missing!' warn is elmarad.
-  auth_settings: {
-    optional: false,
-  },
-
-  bot_settings: null,
-
-  openAi_settings: null,
-
-  dias_settings: null,
-
-  assistant_settings: null,
-
-  docChunking: {
-    maxChunkSize: 1000,
-    maxChunkCount: 1000,
-  },
-
-  // FR-193 — bedrock OOM korai-figyelmeztető heap-watchdog. Default-on: minden nts-szerver
-  // megkapja a heap-nyomás-figyelést a base App startup-ban (lásd DyNTS_MemoryGuard). Csak
-  // MEGFIGYELÉS + tartós rögzítés a near-OOM küszöböknél — nem változtat a viselkedésen.
-  memoryGuard: {
-    enabled: true,
-    pollIntervalMs: 10000,
-    heapWarningThreshold: 85,
-    heapCriticalThreshold: 95,
-    recoveryMargin: 10,
-    maxHistoryCount: 100,
-    // GC-thrash precursor (a %-küszöb által gyakran KÉSŐN/sosem fogott OOM) + crash-entry + opcionális graceful-exit.
-    gcWarningFraction: 0.40,
-    gcCriticalFraction: 0.60,
-    installCrashHandlers: true,
-    exitOnSustainedCritical: false,
-    sustainedCriticalPolls: 3,
-    exitCode: 137,
-    bootGraceMs: 60000,
-  },
-
-  // FR-258 / SR-4 — proactive collection-growth monitor (companion to memoryGuard). Periodically
-  // samples each collection's document count (scan-free estimatedDocumentCount) and warns into the
-  // Errors-sink BEFORE an unbounded collection can be loaded into heap and OOM. Observation only —
-  // never deletes (retention SR-1/SR-2 does the deleting). Slow cadence (5 min) — growth is slow.
-  collectionGrowthMonitor: {
+
+
+import { DyNTS_RouteSecurity } from '../_enums/route-security.enum';
+import { DyNTS_Global_Settings } from '../_models/interfaces/global-settings.interface';
+import { DyNTS_SocketSecurity } from '../_modules/socket/_enums/socket-security.enum';
+import { DyNTS_getEnvironment_settings } from './get-environment-settings.util';
+
+/**
+ * Default configuration used across the NodeTS framework.
+ * These values can be overridden when bootstrapping the server.
+ */
+export const DyNTS_global_settings: DyNTS_Global_Settings = {
+  baseUrl: '/api',
+  systemVersion: 'unknown-version',
+  defaultRouteSecurity: DyNTS_RouteSecurity.open,
+  defaultSocketSecurity: DyNTS_SocketSecurity.open,
+  
+  defaultPageSize: 10,
+  archiveListAfter: 100,
+  env_settings: DyNTS_getEnvironment_settings(),
+  
+  autoResolveEndpointCirculationErrors: true,
+  compactErrorResponse: true,
+
+  log_settings: {
+    highDetailedLogs: false,
+    
+    setup: false,
+  
+    request: true,
+    requestsContent: false,
+    responseContent: false,
+    requestStackLocation: false,
+  
+    socket_allEvents: true,
+    socket_mainEvents: true,
+    socket_eventContent: false,
+  
+    api_events: true,
+    api_requestContents: false,
+    api_requestSettings: false,
+    api_responseContents: false,
+    api_errors: true,
+  
+    detailedErrors: false,
+
+    server_debug: false,
+
+    logs_endpoint: {
+      enabled: false,
+      maxEntries: 2000,
+    },
+  },
+
+  autoResearchIssues: true,
+
+  // Auth-service kötelező alapból (régi viselkedés). Public / no-auth szervereknél
+  // `auth_settings.optional = true` → getAuthService() undefined-ot ad dobás helyett,
+  // és a startup 'Authentication Service missing!' warn is elmarad.
+  auth_settings: {
+    optional: false,
+  },
+
+  bot_settings: null,
+
+  openAi_settings: null,
+
+  dias_settings: null,
+
+  assistant_settings: null,
+
+  docChunking: {
+    maxChunkSize: 1000,
+    maxChunkCount: 1000,
+  },
+
+  // BFR-MASTERPROMPTER-011 / SEC-R2-8 — security response-headerek default-ON (safe-by-default
+  // készlet: x-powered-by removal + SAMEORIGIN + nosniff + strict-origin-when-cross-origin;
+  // HSTS AUTO csak prod-on; CSP opt-in). Per-app tweak az overrideDynamoNTSGlobalSettings()-ben.
+  securityHeaders: {
     enabled: true,
-    pollIntervalMs: 300000,
-    sizeThresholdDocCount: 250000,
-    growthRateThresholdPct: 50,
-    reAlertCooldownMs: 3600000,
+    removePoweredBy: true,
   },
-};
 
+  // FR-193 — bedrock OOM korai-figyelmeztető heap-watchdog. Default-on: minden nts-szerver
+  // megkapja a heap-nyomás-figyelést a base App startup-ban (lásd DyNTS_MemoryGuard). Csak
+  // MEGFIGYELÉS + tartós rögzítés a near-OOM küszöböknél — nem változtat a viselkedésen.
+  memoryGuard: {
+    enabled: true,
+    pollIntervalMs: 10000,
+    heapWarningThreshold: 85,
+    heapCriticalThreshold: 95,
+    recoveryMargin: 10,
+    maxHistoryCount: 100,
+    // GC-thrash precursor (a %-küszöb által gyakran KÉSŐN/sosem fogott OOM) + crash-entry + opcionális graceful-exit.
+    gcWarningFraction: 0.40,
+    gcCriticalFraction: 0.60,
+    installCrashHandlers: true,
+    exitOnSustainedCritical: false,
+    sustainedCriticalPolls: 3,
+    exitCode: 137,
+    bootGraceMs: 60000,
+  },
+
+  // FR-258 / SR-4 — proactive collection-growth monitor (companion to memoryGuard). Periodically
+  // samples each collection's document count (scan-free estimatedDocumentCount) and warns into the
+  // Errors-sink BEFORE an unbounded collection can be loaded into heap and OOM. Observation only —
+  // never deletes (retention SR-1/SR-2 does the deleting). Slow cadence (5 min) — growth is slow.
+  collectionGrowthMonitor: {
+    enabled: true,
+    pollIntervalMs: 300000,
+    sizeThresholdDocCount: 250000,
+    growthRateThresholdPct: 50,
+    reAlertCooldownMs: 3600000,
+  },
+};
+

package/src/_collections/sample.env

@@ -1,21 +1,21 @@
-
-
-ENV={REPLACE_ENV}
-
-MONGO_URL={REPLACE_ATLASDB_URI}
-
-DISCORD_BOT_TOKEN={REPLACE_DISCORD_BOT_TOKEN}
-DISCORD_BOT_CLIENT_ID={REPLACE_DISCORD_BOT_CLIENT_ID}
-DISCORD_GUILD_ID={REPLACE_DISCORD_GUILD_ID}
-DISCORD_BOT_OAUTH2_URL={REPLACE_DISCORD_BOT_OAUTH2_URL}
-
-OPENAI_API_KEY={REPLACE_OPENAI_API_KEY}
-OPENAI_ORGANIZATION={REPLACE_OPENAI_ORGANIZATION}
-OPENAI_PROJECT={REPLACE_OPENAI_PROJECT}
-OPENAI_TTS_API_KEY={REPLACE_OPENAI_TTS_API_KEY}
-
-ELEVENLABS_API_KEY={REPLACE_ELEVENLABS_API_KEY}
-
-CLICKUP_API_KEY={REPLACE_CLICKUP_API_KEY}
-CLICKUP_WORKSPACE_ID={REPLACE_CLICKUP_WORKSPACE_ID}
-CLICKUP_SPACE_ID={REPLACE_CLICKUP_SPACE_ID}
+
+
+ENV={REPLACE_ENV}
+
+MONGO_URL={REPLACE_ATLASDB_URI}
+
+DISCORD_BOT_TOKEN={REPLACE_DISCORD_BOT_TOKEN}
+DISCORD_BOT_CLIENT_ID={REPLACE_DISCORD_BOT_CLIENT_ID}
+DISCORD_GUILD_ID={REPLACE_DISCORD_GUILD_ID}
+DISCORD_BOT_OAUTH2_URL={REPLACE_DISCORD_BOT_OAUTH2_URL}
+
+OPENAI_API_KEY={REPLACE_OPENAI_API_KEY}
+OPENAI_ORGANIZATION={REPLACE_OPENAI_ORGANIZATION}
+OPENAI_PROJECT={REPLACE_OPENAI_PROJECT}
+OPENAI_TTS_API_KEY={REPLACE_OPENAI_TTS_API_KEY}
+
+ELEVENLABS_API_KEY={REPLACE_ELEVENLABS_API_KEY}
+
+CLICKUP_API_KEY={REPLACE_CLICKUP_API_KEY}
+CLICKUP_WORKSPACE_ID={REPLACE_CLICKUP_WORKSPACE_ID}
+CLICKUP_SPACE_ID={REPLACE_CLICKUP_SPACE_ID}

package/src/_collections/security-headers.util.spec.ts

@@ -0,0 +1,98 @@
+import { DyFM_EnvironmentFlag } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_createSecurityHeadersMiddleware, DyNTS_resolveSecurityHeaders } from './security-headers.util';
+import { DyNTS_SecurityHeaders_Settings } from '../_models/interfaces/security-headers-settings.interface';
+
+describe('DyNTS_resolveSecurityHeaders', () => {
+  // AAA: Arrange-Act-Assert
+
+  it('| defaults: pontosan a safe-készlet (3 header), HSTS NÉLKÜL test env-en', () => {
+    const headers = DyNTS_resolveSecurityHeaders({ enabled: true }, DyFM_EnvironmentFlag.test);
+
+    expect(headers['X-Frame-Options']).toBe('SAMEORIGIN');
+    expect(headers['X-Content-Type-Options']).toBe('nosniff');
+    expect(headers['Referrer-Policy']).toBe('strict-origin-when-cross-origin');
+    expect(headers['Strict-Transport-Security']).toBeUndefined();
+    expect(headers['Content-Security-Policy']).toBeUndefined();
+    expect(Object.keys(headers).length).toBe(3);
+  });
+
+  it('| prod env → HSTS AUTO-on a default max-age + includeSubDomains értékkel', () => {
+    const headers = DyNTS_resolveSecurityHeaders({ enabled: true }, DyFM_EnvironmentFlag.prod);
+
+    expect(headers['Strict-Transport-Security']).toBe('max-age=15768000; includeSubDomains');
+  });
+
+  it('| explicit hsts.enabled=true → HSTS test env-en IS (+preload flag)', () => {
+    const headers = DyNTS_resolveSecurityHeaders(
+      { enabled: true, hsts: { enabled: true, maxAgeSeconds: 300, includeSubDomains: false, preload: true } },
+      DyFM_EnvironmentFlag.test,
+    );
+
+    expect(headers['Strict-Transport-Security']).toBe('max-age=300; preload');
+  });
+
+  it('| hsts: false → prod-on SINCS HSTS', () => {
+    const headers = DyNTS_resolveSecurityHeaders({ enabled: true, hsts: false }, DyFM_EnvironmentFlag.prod);
+
+    expect(headers['Strict-Transport-Security']).toBeUndefined();
+  });
+
+  it('| csp string → Content-Security-Policy; cspReportOnly → Report-Only header-név', () => {
+    const csp: string = "default-src 'self'";
+    const normal = DyNTS_resolveSecurityHeaders({ enabled: true, csp: csp }, DyFM_EnvironmentFlag.test);
+    const reportOnly = DyNTS_resolveSecurityHeaders(
+      { enabled: true, csp: csp, cspReportOnly: true },
+      DyFM_EnvironmentFlag.test,
+    );
+
+    expect(normal['Content-Security-Policy']).toBe(csp);
+    expect(reportOnly['Content-Security-Policy']).toBeUndefined();
+    expect(reportOnly['Content-Security-Policy-Report-Only']).toBe(csp);
+  });
+
+  it('| per-header false → kimarad; permissionsPolicy opt-in string → jelen', () => {
+    const headers = DyNTS_resolveSecurityHeaders(
+      { enabled: true, frameOptions: false, referrerPolicy: false, permissionsPolicy: 'camera=()' },
+      DyFM_EnvironmentFlag.test,
+    );
+
+    expect(headers['X-Frame-Options']).toBeUndefined();
+    expect(headers['Referrer-Policy']).toBeUndefined();
+    expect(headers['Permissions-Policy']).toBe('camera=()');
+    expect(headers['X-Content-Type-Options']).toBe('nosniff');
+  });
+
+  it('| additionalHeaders merge (felülírással)', () => {
+    const headers = DyNTS_resolveSecurityHeaders(
+      { enabled: true, additionalHeaders: { 'X-Custom': 'v1', 'X-Frame-Options': 'DENY' } },
+      DyFM_EnvironmentFlag.test,
+    );
+
+    expect(headers['X-Custom']).toBe('v1');
+    expect(headers['X-Frame-Options']).toBe('DENY');
+  });
+
+  it('| enabled: false → üres map', () => {
+    const headers = DyNTS_resolveSecurityHeaders({ enabled: false, csp: 'x' }, DyFM_EnvironmentFlag.prod);
+
+    expect(Object.keys(headers).length).toBe(0);
+  });
+});
+
+describe('DyNTS_createSecurityHeadersMiddleware', () => {
+  it('| a middleware minden resolvelt headert setHeader-öl és next()-et hív', () => {
+    const settings: DyNTS_SecurityHeaders_Settings = { enabled: true };
+    const middleware = DyNTS_createSecurityHeadersMiddleware(settings, DyFM_EnvironmentFlag.test);
+
+    const setHeaderCalls: [string, string][] = [];
+    const res: any = { setHeader: (k: string, v: string): void => { setHeaderCalls.push([k, v]); } };
+    let nextCalled: boolean = false;
+
+    middleware({} as any, res, ((): void => { nextCalled = true; }) as any);
+
+    expect(nextCalled).toBe(true);
+    expect(setHeaderCalls.length).toBe(3);
+    expect(setHeaderCalls.map((c: [string, string]): string => c[0])).toContain('X-Frame-Options');
+  });
+});

package/src/_collections/security-headers.util.ts

@@ -0,0 +1,96 @@
+import * as Express from 'express';
+
+import { DyFM_EnvironmentFlag } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_SecurityHeaders_Settings } from '../_models/interfaces/security-headers-settings.interface';
+
+/**
+ * A security response-headerek TISZTA (Express-mentes, unit-tesztelhető) resolvere
+ * (BFR-MASTERPROMPTER-011 / SEC-R2-8). A `DyNTS_App.mountSecurityHeaders` ebből épít middleware-t.
+ *
+ * **HSTS AUTO-env-gate**: ha a `hsts` beállítás nem explicit, CSAK prod environment-en emittálunk
+ * (a test-környezeti sticky-HSTS elkerülésére); explicit `hsts.enabled` felülbírálja mindkét irányba.
+ */
+export function DyNTS_resolveSecurityHeaders(
+  settings: DyNTS_SecurityHeaders_Settings,
+  environment: DyFM_EnvironmentFlag,
+): Record<string, string> {
+  const headers: Record<string, string> = {};
+
+  if (!settings.enabled) {
+    return headers;
+  }
+
+  // Clickjacking-védelem — default SAMEORIGIN.
+  const frameOptions: string | false = settings.frameOptions ?? 'SAMEORIGIN';
+  if (frameOptions) {
+    headers['X-Frame-Options'] = frameOptions;
+  }
+
+  // MIME-sniffing tiltás — default nosniff.
+  const contentTypeOptions: string | false = settings.contentTypeOptions ?? 'nosniff';
+  if (contentTypeOptions) {
+    headers['X-Content-Type-Options'] = contentTypeOptions;
+  }
+
+  // Referrer-szivárgás korlátozás — default strict-origin-when-cross-origin.
+  const referrerPolicy: string | false = settings.referrerPolicy ?? 'strict-origin-when-cross-origin';
+  if (referrerPolicy) {
+    headers['Referrer-Policy'] = referrerPolicy;
+  }
+
+  // Permissions-Policy — opt-in (app-specifikus feature-készlet).
+  if (settings.permissionsPolicy) {
+    headers['Permissions-Policy'] = settings.permissionsPolicy;
+  }
+
+  // HSTS — AUTO-env-gate: default CSAK prod-on; explicit enabled felülbírál.
+  if (settings.hsts !== false) {
+    const hstsExplicitlyEnabled: boolean = settings.hsts?.enabled === true;
+    const hstsExplicitlyDisabled: boolean = settings.hsts?.enabled === false;
+    const hstsAutoOn: boolean = environment === DyFM_EnvironmentFlag.prod;
+
+    if (!hstsExplicitlyDisabled && (hstsExplicitlyEnabled || hstsAutoOn)) {
+      const maxAge: number = settings.hsts?.maxAgeSeconds ?? 15768000;
+      const includeSubDomains: string = (settings.hsts?.includeSubDomains ?? true) ? '; includeSubDomains' : '';
+      const preload: string = settings.hsts?.preload ? '; preload' : '';
+      headers['Strict-Transport-Security'] = `max-age=${maxAge}${includeSubDomains}${preload}`;
+    }
+  }
+
+  // CSP — opt-in string; a Report-Only header-név a fokozatos bevezetéshez.
+  if (settings.csp) {
+    const cspHeaderName: string = settings.cspReportOnly
+      ? 'Content-Security-Policy-Report-Only'
+      : 'Content-Security-Policy';
+    headers[cspHeaderName] = settings.csp;
+  }
+
+  // Tetszőleges további headerek (merge, felülírással).
+  if (settings.additionalHeaders) {
+    for (const [key, value] of Object.entries(settings.additionalHeaders)) {
+      headers[key] = value;
+    }
+  }
+
+  return headers;
+}
+
+/**
+ * Express-middleware factory a resolvelt headerekből. A headereket boot-kor EGYSZER resolvoljuk
+ * (a settings boot után nem változik), a middleware kérésenként csak setHeader-öl.
+ */
+export function DyNTS_createSecurityHeadersMiddleware(
+  settings: DyNTS_SecurityHeaders_Settings,
+  environment: DyFM_EnvironmentFlag,
+): Express.Handler {
+  const resolvedHeaders: Record<string, string> = DyNTS_resolveSecurityHeaders(settings, environment);
+  const headerEntries: [string, string][] = Object.entries(resolvedHeaders);
+
+  return (req: Express.Request, res: Express.Response, next: Express.NextFunction): void => {
+    for (const [key, value] of headerEntries) {
+      res.setHeader(key, value);
+    }
+    next();
+  };
+}