@futdevpro/nts-dynamo 1.15.127 → 1.15.129

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

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