@futdevpro/nts-dynamo 1.15.122 → 1.15.127

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

@@ -1,126 +1,126 @@
-
-
-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,
-    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,
-    // Auto-load-shed 503 (BFR-OVERSEER-009 maradék) — opt-in; esszenciális útvonalak kivételével.
-    loadShedEnabled: false,
-    loadShedExemptPathParts: ['/health', '/readiness', '/status', '/diag'],
-  },
-  // Event-loop-lag diag (BFR-OVERSEER-007) — olcsó natív mérés, default ON (opt-out lehetséges).
-  eventLoopDiag: {
-    enabled: true,
-    pollIntervalMs: 5000,
-    maxHistoryCount: 120,
-  },
-
-  // 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,
-  },
-};
-
+
+
+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,
+    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,
+    // Auto-load-shed 503 (BFR-OVERSEER-009 maradék) — opt-in; esszenciális útvonalak kivételével.
+    loadShedEnabled: false,
+    loadShedExemptPathParts: ['/health', '/readiness', '/status', '/diag'],
+  },
+  // Event-loop-lag diag (BFR-OVERSEER-007) — olcsó natív mérés, default ON (opt-out lehetséges).
+  eventLoopDiag: {
+    enabled: true,
+    pollIntervalMs: 5000,
+    maxHistoryCount: 120,
+  },
+
+  // 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/signed-url.util.spec.ts

@@ -0,0 +1,198 @@
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_SignedUrl_Util } from './signed-url.util';
+
+/**
+ * ALÁÍRT-URL primitív tesztjei (AAA).
+ *
+ * ⭐ **Az ARANY-VEKTOR az első teszt, és ez a legfontosabb:** a hex értéket a ma ÉLŐ algoritmusból
+ * generáltuk *(az `fdp-ftp-service` `FtpUrlSignature_Util` verify- és a `master-prompter`
+ * `FtpUrlSigner_Util` sign-oldala — bit-azonosak)*. Ha ez a teszt elpirosodik, az azt jelenti,
+ * hogy a bedrock util **elcsúszott** az élő rendszertől, és a **már kiadott URL-ek elromlanának**.
+ *
+ * ⚠️ `nowMs` **mindenhol injektálva** — a tesztben nincs `Date.now()`, tehát nincs flake.
+ */
+describe('| DyNTS_SignedUrl_Util', () => {
+  const SECRET: string = 'golden-vector-secret';
+  const BACKSLASH: string = String.fromCharCode(92);
+
+  // --- ARANY-VEKTOR (az élő algoritmusból generálva) ---
+  const GOLDEN_PATH: string = '/accounts/acc-1/invoices/INV-2026-001.pdf';
+  const GOLDEN_EXP: number = 1767225600000;
+  const GOLDEN_HEX: string = 'a6c2d1ddf0fe4614e3b6130d4e22a9ef085377f73088d3f79aab548e8056c165';
+
+  it('1 | ARANY-VEKTOR — a mai algoritmus hexét adja (bitre)', () => {
+    const signature: string = DyNTS_SignedUrl_Util.sign(GOLDEN_PATH, GOLDEN_EXP, SECRET);
+
+    expect(signature).toBe(GOLDEN_HEX);
+  });
+
+  it('2 | normalizePath — vezető /-ek le, backslash → slash', () => {
+    expect(DyNTS_SignedUrl_Util.normalizePath('///a' + BACKSLASH + 'b/c')).toBe('a/b/c');
+  });
+
+  it('3 | buildCanonicalString — `<path>\\n<exp>`', () => {
+    expect(DyNTS_SignedUrl_Util.buildCanonicalString('a/b', 123)).toBe('a/b\n123');
+  });
+
+  it('4 | sign determinisztikus — kétszeri hívás azonos', () => {
+    const first: string = DyNTS_SignedUrl_Util.sign(GOLDEN_PATH, GOLDEN_EXP, SECRET);
+    const second: string = DyNTS_SignedUrl_Util.sign(GOLDEN_PATH, GOLDEN_EXP, SECRET);
+
+    expect(first).toBe(second);
+  });
+
+  it('5 | verify — érvényes aláírásra { valid: true }', () => {
+    const result = DyNTS_SignedUrl_Util.verify({
+      filePath: GOLDEN_PATH, expMs: GOLDEN_EXP, signature: GOLDEN_HEX,
+      secret: SECRET, nowMs: GOLDEN_EXP - 1000,
+    });
+
+    expect(result.valid).toBeTrue();
+    expect(result.reason).toBeUndefined();
+  });
+
+  it('6 | verify — LEJÁRT aláírásra { valid: false, reason: expired }', () => {
+    const result = DyNTS_SignedUrl_Util.verify({
+      filePath: GOLDEN_PATH, expMs: GOLDEN_EXP, signature: GOLDEN_HEX,
+      secret: SECRET, nowMs: GOLDEN_EXP + 1,
+    });
+
+    expect(result.valid).toBeFalse();
+    expect(result.reason).toBe('expired');
+  });
+
+  it('7 | verify — HAMIS aláírásra { valid: false, reason: signature-mismatch }', () => {
+    // ugyanolyan HOSSZÚ, de más tartalmú hex — a timing-safe ág fut le, nem a hossz-guard
+    const forged: string = 'b'.repeat(GOLDEN_HEX.length);
+
+    const result = DyNTS_SignedUrl_Util.verify({
+      filePath: GOLDEN_PATH, expMs: GOLDEN_EXP, signature: forged,
+      secret: SECRET, nowMs: GOLDEN_EXP - 1000,
+    });
+
+    expect(result.valid).toBeFalse();
+    expect(result.reason).toBe('signature-mismatch');
+  });
+
+  it('8 | verify — ELTÉRŐ HOSSZÚ aláírásra NEM dob (timingSafeEqual guard)', () => {
+    const shortSignature: string = 'abc';
+
+    // Act + Assert: a lényeg, hogy NEM dob — a `timingSafeEqual` eltérő hosszra dobna.
+    expect((): void => {
+      const result = DyNTS_SignedUrl_Util.verify({
+        filePath: GOLDEN_PATH, expMs: GOLDEN_EXP, signature: shortSignature,
+        secret: SECRET, nowMs: GOLDEN_EXP - 1000,
+      });
+
+      expect(result.valid).toBeFalse();
+    }).not.toThrow();
+  });
+
+  it('9 | verify — hiányzó exp/sig esetén { valid: false, reason: missing-params }', () => {
+    const noSignature = DyNTS_SignedUrl_Util.verify({
+      filePath: GOLDEN_PATH, expMs: GOLDEN_EXP, signature: undefined,
+      secret: SECRET, nowMs: GOLDEN_EXP - 1000,
+    });
+    const noExp = DyNTS_SignedUrl_Util.verify({
+      filePath: GOLDEN_PATH, expMs: undefined, signature: GOLDEN_HEX,
+      secret: SECRET, nowMs: GOLDEN_EXP - 1000,
+    });
+
+    expect(noSignature.reason).toBe('missing-params');
+    expect(noExp.reason).toBe('missing-params');
+  });
+
+  it('10 | verify — ÜRES secrettel SOHA nem true', () => {
+    const result = DyNTS_SignedUrl_Util.verify({
+      filePath: GOLDEN_PATH, expMs: GOLDEN_EXP, signature: GOLDEN_HEX,
+      secret: '', nowMs: GOLDEN_EXP - 1000,
+    });
+
+    expect(result.valid).toBeFalse();
+    expect(result.reason).toBe('missing-secret');
+  });
+
+  it('11 | sign — ÜRES secretre DOB (DyNTS-SURL-SIGN-NOSEC), nem ad csendben üres aláírást', () => {
+    let caught: DyFM_Error | undefined;
+
+    try {
+      DyNTS_SignedUrl_Util.sign(GOLDEN_PATH, GOLDEN_EXP, '');
+    } catch (error) {
+      caught = error as DyFM_Error;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught?._errorCode).toBe('DyNTS-SURL-SIGN-NOSEC');
+  });
+
+  it('12 | buildSignedUrl — base végi /-ek levágva, query helyes', () => {
+    const url: string = DyNTS_SignedUrl_Util.buildSignedUrl({
+      baseUrl: 'https://ftp.example.com///',
+      filePath: '/accounts/acc-1/f.pdf',
+      ttlMs: 60_000,
+      secret: SECRET,
+      nowMs: 1_000_000,
+    });
+
+    const expectedSignature: string =
+      DyNTS_SignedUrl_Util.sign('accounts/acc-1/f.pdf', 1_060_000, SECRET);
+    expect(url).toBe(
+      `https://ftp.example.com/accounts/acc-1/f.pdf?exp=1060000&sig=${expectedSignature}`,
+    );
+  });
+
+  it('13 | PATH-MANIPULÁCIÓ — aláírt path ≠ kért path → érvénytelen', () => {
+    const signature: string = DyNTS_SignedUrl_Util.sign('accounts/acc-1/f.pdf', GOLDEN_EXP, SECRET);
+
+    const result = DyNTS_SignedUrl_Util.verify({
+      filePath: 'accounts/acc-2/f.pdf',        // MÁSIK account
+      expMs: GOLDEN_EXP, signature, secret: SECRET, nowMs: GOLDEN_EXP - 1000,
+    });
+
+    expect(result.valid).toBeFalse();
+    expect(result.reason).toBe('signature-mismatch');
+  });
+
+  it('14 | nowMs injektálás — determinisztikus lejárat-határ (nincs Date.now a tesztben)', () => {
+    const atBoundary = DyNTS_SignedUrl_Util.verify({
+      filePath: GOLDEN_PATH, expMs: GOLDEN_EXP, signature: GOLDEN_HEX,
+      secret: SECRET, nowMs: GOLDEN_EXP,        // exp === now → MÉG érvényes
+    });
+    const afterBoundary = DyNTS_SignedUrl_Util.verify({
+      filePath: GOLDEN_PATH, expMs: GOLDEN_EXP, signature: GOLDEN_HEX,
+      secret: SECRET, nowMs: GOLDEN_EXP + 1,    // egy ms-mal később → lejárt
+    });
+
+    expect(atBoundary.valid).toBeTrue();
+    expect(afterBoundary.reason).toBe('expired');
+  });
+
+  it('15 | buildSignedUrl — ÜRES/hibás baseUrl-re DOB (DyNTS-SURL-URL-BADBASE), nem épít félkész URL-t', () => {
+    let caught: DyFM_Error | undefined;
+
+    try {
+      DyNTS_SignedUrl_Util.buildSignedUrl({
+        baseUrl: '   ', filePath: 'a/b.pdf', ttlMs: 1000, secret: SECRET, nowMs: 1,
+      });
+    } catch (error) {
+      caught = error as DyFM_Error;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught?._errorCode).toBe('DyNTS-SURL-URL-BADBASE');
+  });
+
+  it('16 | sign — nem-pozitív/nem-szám expMs-re DOB (DyNTS-SURL-SIGN-BADEXP)', () => {
+    let caught: DyFM_Error | undefined;
+
+    try {
+      DyNTS_SignedUrl_Util.sign(GOLDEN_PATH, Number.NaN, SECRET);
+    } catch (error) {
+      caught = error as DyFM_Error;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught?._errorCode).toBe('DyNTS-SURL-SIGN-BADEXP');
+  });
+});

package/src/_collections/signed-url.util.ts

@@ -0,0 +1,170 @@
+import * as Crypto from 'crypto';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_SignedUrl_VerifyResult } from '../_models/interfaces/signed-url-verify-result.interface';
+
+/**
+ * ALÁÍRT-URL primitív (HMAC-SHA256) — a böngésző-kiszolgálás (`<img src>`, nincs Bearer)
+ * auth-mechanizmusának generikus magja.
+ *
+ * A forrás-rendszer (ahol megvan a user auth-kontextusa) aláírja a `path + exp` kanonikus
+ * stringet a MEGOSZTOTT titokkal, és egy `…/<path>?exp=<ms>&sig=<hex>` URL-t ad ki; a kiszolgáló
+ * oldal ugyanezzel a titokkal validál. Az **aláírás maga a tamper-proof izoláció**: a path
+ * bármilyen módosítása érvényteleníti.
+ *
+ * ⚠️ **A SZERZŐDÉS BITRE KÖTÖTT — nem tervezési szabadság.** Ez az util a ma ÉLŐ algoritmust
+ * viszi tovább (az `fdp-ftp-service` verify- és a `master-prompter` sign-oldaláról mérve),
+ * hogy a **már kiadott URL-ek** ne romoljanak el:
+ *
+ * | Elem | Érték |
+ * |---|---|
+ * | Algoritmus | `HMAC-SHA256(secret, canonicalString)` → **hex** |
+ * | Kanonikus string | `` `<normalizedPath>\n<expMs>` `` — csak path + lejárat |
+ * | `normalizePath` | vezető `/`-ek le (`/^\/+/`), `\` → `/` |
+ * | Query | `?exp=<ms>&sig=<hex>` |
+ * | Összevetés | `Crypto.timingSafeEqual`, **előtte hossz-guard** |
+ * | Lejárat | `expMs < now` → érvénytelen; **nincs** beépített max-TTL (a hívó dönt) |
+ *
+ * **Miért `dynamo-nts` és nem `fsm-dynamo`:** node-`crypto` kell (`createHmac` +
+ * **`timingSafeEqual`**); izomorf rétegben a timing-safe összevetés elveszne, és a sign/verify
+ * két csomagba vágása pont azt a bitre-egyezést veszélyeztetné, amiért ez az util készül.
+ *
+ * **Két tudatos eltérés a mai duplikátumoktól:**
+ * 1. `sign`/`buildSignedUrl` üres secretre **DOB** — a mai forrás-oldal üres stringet ad vissza,
+ *    ami **csendes hiba**: a hívó észrevétlenül aláírás nélküli URL-t kaphat. A bedrock **hangos**;
+ *    a fallback-döntés a hívóé, de **tudatosan**.
+ * 2. `verify` **SOHA nem dob** — strukturált `{ valid, reason }`-t ad, hogy a gate-ek egységes,
+ *    szivárgás-mentes választ tudjanak adni.
+ */
+export class DyNTS_SignedUrl_Util {
+
+  /**
+   * Path normalizálás az aláíráshoz/validáláshoz: vezető `/`-ek le, `\` → `/`.
+   * A kanonikus string első fele — a két oldalnak **bit-azonosan** kell normalizálnia.
+   */
+  static normalizePath(filePath: string): string {
+    return (filePath ?? '').replace(/^\/+/, '').replace(/\\/g, '/');
+  }
+
+  /**
+   * A HMAC bemenete: `` `<normalizedPath>\n<expMs>` ``.
+   * **Publikus**, hogy tesztelhető és auditálható legyen (az arany-vektor erre épül).
+   */
+  static buildCanonicalString(filePath: string, expMs: number): string {
+    return `${DyNTS_SignedUrl_Util.normalizePath(filePath)}\n${expMs}`;
+  }
+
+  /**
+   * HMAC-SHA256 hex digest a kanonikus stringen.
+   *
+   * @throws `DyNTS-SURL-SIGN-NOSEC` — üres secret *(⚠️ NEM ad csendben üres aláírást)*
+   * @throws `DyNTS-SURL-SIGN-BADEXP` — nem-szám / nem-pozitív `expMs`
+   */
+  static sign(filePath: string, expMs: number, secret: string): string {
+    DyNTS_SignedUrl_Util._assertSecret(secret, filePath);
+    DyNTS_SignedUrl_Util._assertExp(expMs, filePath);
+
+    return Crypto
+      .createHmac('sha256', secret)
+      .update(DyNTS_SignedUrl_Util.buildCanonicalString(filePath, expMs), 'utf8')
+      .digest('hex');
+  }
+
+  /**
+   * Timing-safe aláírás-ellenőrzés + lejárat. ⚠️ **SOHA nem dob** — a hívó gate-nek egységes,
+   * szivárgás-mentes választ kell tudnia adni.
+   *
+   * `nowMs` injektálható → determinisztikus teszt (nincs `Date.now()` a tesztben).
+   */
+  static verify(params: {
+    filePath: string;
+    expMs: number | undefined;
+    signature: string | undefined;
+    secret: string;
+    nowMs?: number;
+  }): DyNTS_SignedUrl_VerifyResult {
+    if (!params.secret) {
+      return { valid: false, reason: 'missing-secret' };
+    }
+    if (!params.signature || typeof params.expMs !== 'number' || !Number.isFinite(params.expMs)) {
+      return { valid: false, reason: 'missing-params' };
+    }
+
+    const now: number = typeof params.nowMs === 'number' ? params.nowMs : Date.now();
+    if (params.expMs < now) {
+      return { valid: false, reason: 'expired' };
+    }
+
+    const expected: string = DyNTS_SignedUrl_Util.sign(params.filePath, params.expMs, params.secret);
+
+    // ⚠️ A `timingSafeEqual` ELTÉRŐ HOSSZÚ bufferre DOB — ezért kell a hossz-guard.
+    // A hossz nem titok: a hex digest hossza fix.
+    const signatureBuffer: Buffer = Buffer.from(params.signature, 'utf8');
+    const expectedBuffer: Buffer = Buffer.from(expected, 'utf8');
+    if (signatureBuffer.length !== expectedBuffer.length) {
+      return { valid: false, reason: 'signature-mismatch' };
+    }
+    if (!Crypto.timingSafeEqual(signatureBuffer, expectedBuffer)) {
+      return { valid: false, reason: 'signature-mismatch' };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Teljes aláírt URL: `` `<base>/<normalizedPath>?exp=<ms>&sig=<hex>` `` — a `base` végi
+   * `/`-ei levágva.
+   *
+   * @throws `DyNTS-SURL-URL-BADBASE` — üres/hibás `baseUrl` *(⚠️ NEM épít félkész URL-t)*
+   * @throws `DyNTS-SURL-SIGN-NOSEC` — üres secret
+   */
+  static buildSignedUrl(params: {
+    baseUrl: string;
+    filePath: string;
+    ttlMs: number;
+    secret: string;
+    nowMs?: number;
+  }): string {
+    const base: string = (params.baseUrl ?? '').trim().replace(/\/+$/, '');
+    if (!base) {
+      throw new DyFM_Error({
+        status: 500,
+        errorCode: 'DyNTS-SURL-URL-BADBASE',
+        message: 'Signed URL: "baseUrl" is empty or invalid — refusing to build a half-formed URL.',
+        additionalContent: { filePath: params.filePath },
+      });
+    }
+
+    const now: number = typeof params.nowMs === 'number' ? params.nowMs : Date.now();
+    const expMs: number = now + params.ttlMs;
+    const normalizedPath: string = DyNTS_SignedUrl_Util.normalizePath(params.filePath);
+    const signature: string = DyNTS_SignedUrl_Util.sign(normalizedPath, expMs, params.secret);
+
+    return `${base}/${normalizedPath}?exp=${expMs}&sig=${signature}`;
+  }
+
+  /** Üres secret → hangos hiba. ⚠️ A titok SOHA nem kerül a hiba-kontextusba. */
+  private static _assertSecret(secret: string, filePath: string): void {
+    if (!secret) {
+      throw new DyFM_Error({
+        status: 500,
+        errorCode: 'DyNTS-SURL-SIGN-NOSEC',
+        message: 'Signed URL: signing secret is not configured — refusing to sign silently.',
+        additionalContent: { filePath: DyNTS_SignedUrl_Util.normalizePath(filePath) },
+      });
+    }
+  }
+
+  /** Nem-szám / nem-pozitív lejárat → hangos hiba (a csendes `NaN`-os aláírás rosszabb). */
+  private static _assertExp(expMs: number, filePath: string): void {
+    if (typeof expMs !== 'number' || !Number.isFinite(expMs) || expMs <= 0) {
+      throw new DyFM_Error({
+        status: 500,
+        errorCode: 'DyNTS-SURL-SIGN-BADEXP',
+        message: 'Signed URL: "expMs" must be a finite positive number (epoch millis).',
+        additionalContent: { filePath: DyNTS_SignedUrl_Util.normalizePath(filePath), expMs: `${expMs}` },
+      });
+    }
+  }
+}