@futdevpro/nts-dynamo 1.15.121 → 1.15.126

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}` },
+      });
+    }
+  }
+}

package/src/_models/interfaces/signed-url-verify-result.interface.ts

@@ -0,0 +1,13 @@
+/**
+ * Az aláírt-URL ellenőrzés (`DyNTS_SignedUrl_Util.verify`) strukturált eredménye.
+ *
+ * ⚠️ A `reason` **logba** való — a HTTP-válaszba **NEM** szivárogtatható: az elutasítás oka
+ * támadónak információ *(pl. „expired" vs. „signature-mismatch" megkülönböztetése)*.
+ *
+ * ⭐ **Miért strukturált eredmény és nem kivétel:** a `verify` SOHA nem dob, hogy a hívó gate-ek
+ * egységes, szivárgás-mentes választ tudjanak adni — a `reason` a **belső** diagnosztika.
+ */
+export interface DyNTS_SignedUrl_VerifyResult {
+  valid: boolean;
+  reason?: 'missing-secret' | 'missing-params' | 'expired' | 'signature-mismatch';
+}

package/src/index.ts

@@ -49,12 +49,14 @@ export * from './_models/interfaces/environment-settings.interface';
 export * from './_models/interfaces/global-service-settings.interface';
 export * from './_models/interfaces/global-settings.interface';
 export * from './_models/interfaces/routing-module-settings.interface';
+export * from './_models/interfaces/signed-url-verify-result.interface';
 export * from './_models/interfaces/static-client-settings.interface';
 export * from './_models/interfaces/cors-settings.interface';
 export * from './_models/interfaces/security-headers-settings.interface';
 export * from './_models/interfaces/db-query-options.interface';
 export * from './_models/interfaces/migration-entry.interface';
 export * from './_collections/security-headers.util';
+export * from './_collections/signed-url.util';
 export * from './_collections/client-safe-error.util';
 export * from './_collections/load-shed.util';
 export * from './_services/core/event-loop-diag.service';