@futdevpro/nts-dynamo 1.15.151 → 1.15.153

package/src/_collections/field-encryption.util.ts

@@ -1,222 +1,222 @@
-import {
-  DyFM_DataProperties,
-  DyFM_Error,
-} from '@futdevpro/fsm-dynamo';
-import { DyFM_Crypto } from '@futdevpro/fsm-dynamo/crypto';
-
-/**
- * AT-REST field-encryption transzform (Option B, bedrock). A DBService a közös írási úton
- * (`createData` / `modifyData`) a persist ELŐTT titkosítja, a read-post-processor
- * (`stringifyDataId`) a load UTÁN visszafejti az `encrypt:true` mezőket.
- *
- * **App-rétegben fut, NEM mongoose-hook** — a `modifyData` `findByIdAndUpdate`-je megkerüli a
- * mongoose settereket/pre-save-hookokat, ezért a transzform explicit itt történik.
- *
- * **Opt-in, default-off:** ha egy modell egyetlen mezője sem `encrypt:true`, a transzform tiszta
- * NO-OP (ugyanaz az objektum-referencia, nincs klónozás, nincs viselkedés-változás, kulcs sem kell).
- *
- * **Legacy-plaintext biztonságos:** a read-transzform CSAK a `DYENC1:` envelope-értékeket fejti vissza
- * (`isEncryptedDbValue`); a régi, még nem migrált plaintext értékek változatlanul jönnek vissza.
- *
- * Kulcs: `FDP_CORE_DBCONTENT_CRYPT_KEY` (Keystore/CI-env). Verzió: `FDP_CORE_DBCONTENT_CRYPT_KEY_VERSION`
- * (default 1) — a kulcs-rotációhoz (a verzió az envelope-ban utazik).
- */
-export class DyNTS_FieldEncryption_Util {
-  static readonly ENV_KEY: string = 'FDP_CORE_DBCONTENT_CRYPT_KEY';
-  static readonly ENV_KEY_VERSION: string = 'FDP_CORE_DBCONTENT_CRYPT_KEY_VERSION';
-
-  /** `hasEncryptedFields` cache per properties-objektum (referencia szerint). */
-  private static readonly _hasEncCache: WeakMap<object, boolean> = new WeakMap();
-
-  /** A titkosító kulcs env-ből (üres string, ha nincs beállítva). */
-  static getKey(): string {
-    return process.env[this.ENV_KEY] ?? '';
-  }
-
-  /** Az aktuális kulcs-verzió (default 1). */
-  static getKeyVersion(): number {
-    const parsed: number = Number(process.env[this.ENV_KEY_VERSION]);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
-  }
-
-  /**
-   * True, ha a properties-fa (rekurzívan a `subObjectParams`-on át) tartalmaz `encrypt:true` mezőt.
-   * Cache-elt (a properties-objektum immutábilis a modell-élettartam alatt).
-   */
-  static hasEncryptedFields(properties?: DyFM_DataProperties<any>): boolean {
-    if (!properties) {
-      return false;
-    }
-
-    const cached: boolean | undefined = this._hasEncCache.get(properties);
-    if (cached !== undefined) {
-      return cached;
-    }
-
-    let has: boolean = false;
-    for (const key in properties) {
-      const prop: any = properties[key]; // ccap-review-disable-line no-any-type
-      if (!prop) {
-        continue;
-      }
-      if (prop.encrypt === true) {
-        has = true;
-        break;
-      }
-      if (prop.subObjectParams && this.hasEncryptedFields(prop.subObjectParams)) {
-        has = true;
-        break;
-      }
-    }
-
-    this._hasEncCache.set(properties, has);
-    return has;
-  }
-
-  /**
-   * Titkosítja a doc `encrypt:true` mezőit persist előtt. **Klónt ad vissza** — az eredeti (hívó)
-   * objektumot NEM mutálja (különben a `this.data` ciphertextté válna). NO-OP, ha nincs enc-mező.
-   * @throws ha van enc-mező, de a kulcs env-var nincs beállítva (fail-loud misconfiguration).
-   */
-  static encryptDoc<T>(data: T, properties?: DyFM_DataProperties<any>): T {
-    if (data == null || !this.hasEncryptedFields(properties)) {
-      return data;
-    }
-
-    const key: string = this.getKey();
-    if (!key) {
-      throw new DyFM_Error({
-        status: 500,
-        errorCode: 'DyNTS-ENC-KEY-MISSING',
-        message:
-          `At-rest encryption: "${this.ENV_KEY}" env-var is not set, but a model field is encrypt:true. ` +
-          `Set the key in the Keystore/CI-env and redeploy.`,
-      });
-    }
-
-    return this._transform(data, properties as DyFM_DataProperties<any>, 'encrypt', key, this.getKeyVersion());
-  }
-
-  /**
-   * Visszafejti a doc `encrypt:true` mezőit load után. CSAK a `DYENC1:` envelope-értékeket bántja
-   * (legacy plaintext változatlan). NO-OP, ha nincs enc-mező. Kulcs hiányában read-en NEM dob
-   * (a read ne törjön el) — az envelope-értékek visszafejtetlenül maradnak (a hívó látja + a hiba loggolt).
-   */
-  static decryptDoc<T>(data: T, properties?: DyFM_DataProperties<any>): T {
-    if (data == null || !this.hasEncryptedFields(properties)) {
-      return data;
-    }
-
-    const key: string = this.getKey();
-    if (!key) {
-      return data;
-    }
-
-    return this._transform(data, properties as DyFM_DataProperties<any>, 'decrypt', key, this.getKeyVersion());
-  }
-
-  /**
-   * Egy mongoose-**Document** sima objektummá alakítása (más érték változatlanul jön vissza).
-   *
-   * @description 🔴 **MIÉRT KELL** (BFR-MASTERPROMPTER-027, 2026-08-14): a `_transform` sekély spreaddel
-   *   klónoz. Egy mongoose-Documentnek viszont az adatok NEM saját mezői — azok a belső `_doc`-ban
-   *   ülnek —, ezért a `{ ...doc }` a **belső burkot** másolja (`$__`, `$isNew`, `_doc`), és az eredmény
-   *   **már nem Document**, tehát a `JSON.stringify` sem hívja a `toJSON()`-ját. A kliens így
-   *   `{"$__":…,"$isNew":…,"_doc":{…}}`-t kap `_id` nélkül.
-   *
-   *   **Élesben mérve** (`test.master-prompter.hu`, 2026-08-14): a `flow` lista-endpoint válaszának
-   *   első elemén a kulcsok `["$__","$isNew","_doc"]`, `_id: undefined` → a kliens-oldali linkek
-   *   `/editor/undefined`-ra mutattak, a törlés `missing pathParam: "flowId"`-vel állt meg. Az EGYEDI
-   *   get ugyanakkor ép volt — mert a `DyNTS_DBService` az egyedi olvasásoknál **már `toObject()`-et**
-   *   hív (`db.service.ts` getDataById / getDataByDependencyId / findByIdAndUpdate / findOneAndUpdate),
-   *   a **lista-metódusok (11 db) viszont NYERS Documentet adnak tovább**. Titkosítás nélküli
-   *   modelleknél ez ártalmatlan (a `res.send` a `toJSON()`-on át szerializál), `encrypt:true` mező
-   *   esetén viszont a spread elrontja.
-   *
-   *   **Miért ITT javítjuk, és nem a 11 DB-metódusban:** (1) ez az EGY pont mind a 11 utat rendezi;
-   *   (2) a 11 metódus visszatérési TÍPUSÁT megváltoztatni (Document → sima objektum) minden modell
-   *   minden fogyasztóját érintené — az itteni javítás viszont **csak az `encrypt:true` modelleket**
-   *   érinti, ahol a `_transform` amúgy is **már ma is** sima (csak ROSSZ) objektumot ad vissza.
-   *   Vagyis a változás nem tud elrontani olyat, ami ma működik.
-   *
-   *   `toJSON()`-t használunk (nem `toObject()`-et): a titkosítás bevezetése ELŐTT a nyers Document a
-   *   `res.send`-en át a `JSON.stringify` → `toJSON()` úton szerializálódott, tehát ez adja vissza
-   *   **bitre ugyanazt a kimeneti alakot** (schema-transzformok, virtuals, `__v`-kezelés együtt).
-   *
-   * @param value tetszőleges érték
-   * @returns a Document sima alakja, vagy az eredeti érték
-   */
-  private static _toPlainIfDocument(value: any): any { // ccap-review-disable-line no-any-type
-    // A `$__` a mongoose-Document SAJÁT mezője — pontosan ez szivárgott ki a hibás payloadba,
-    // ezért ez a legpontosabb (és mongoose-import nélküli) diszkriminátor.
-    if (
-      value != null
-      && typeof value === 'object'
-      && typeof value.toJSON === 'function'
-      && Object.prototype.hasOwnProperty.call(value, '$__')
-    ) {
-      return value.toJSON();
-    }
-
-    return value;
-  }
-
-  /**
-   * Rekurzív per-field walk: az `encrypt:true` mezőket titkosítja/visszafejti, a `subObjectParams`-os
-   * mezőkbe (objektum VAGY objektum-tömb) leszáll. Immutábilis: minden érintett konténert sekélyen
-   * klónoz (az eredetit nem mutálja); a nem-érintett ágakat referencia szerint megosztja (read-only).
-   *
-   * ⚠️ A klónozás ELŐTT a mongoose-Documentek sima objektummá alakulnak — lásd {@link _toPlainIfDocument}.
-   */
-  private static _transform<T>(
-    value: T,
-    properties: DyFM_DataProperties<any>,
-    mode: 'encrypt' | 'decrypt',
-    key: string,
-    keyVersion: number,
-  ): T {
-    if (value == null || typeof value !== 'object') {
-      return value;
-    }
-
-    const plain: any = this._toPlainIfDocument(value); // ccap-review-disable-line no-any-type
-    const result: any = Array.isArray(plain) ? [ ...(plain as any[]) ] : { ...(plain as any) }; // ccap-review-disable-line no-any-type
-
-    for (const propKey in properties) {
-      const prop: any = properties[propKey]; // ccap-review-disable-line no-any-type
-      if (!prop) {
-        continue;
-      }
-
-      if (prop.encrypt === true) {
-        const current: any = result[propKey]; // ccap-review-disable-line no-any-type
-
-        if (mode === 'encrypt') {
-          // Üres/undefined/null-t NEM titkosítunk (a DyFM_Crypto ezekre dob); már-envelope-ot sem (idempotens).
-          if (current != null && current !== '' && !DyFM_Crypto.isEncryptedDbValue(current)) {
-            result[propKey] = DyFM_Crypto.encryptDbValue(current, key, keyVersion);
-          }
-        } else {
-          // CSAK envelope-ot fejtünk vissza (legacy plaintext változatlan).
-          if (DyFM_Crypto.isEncryptedDbValue(current)) {
-            result[propKey] = DyFM_Crypto.decryptDbValue(current, key);
-          }
-        }
-      } else if (prop.subObjectParams) {
-        const current: any = result[propKey]; // ccap-review-disable-line no-any-type
-
-        if (current != null && typeof current === 'object') {
-          if (Array.isArray(current)) {
-            result[propKey] = current.map(
-              (item: any): any => this._transform(item, prop.subObjectParams, mode, key, keyVersion), // ccap-review-disable-line no-any-type
-            );
-          } else {
-            result[propKey] = this._transform(current, prop.subObjectParams, mode, key, keyVersion);
-          }
-        }
-      }
-    }
-
-    return result as T;
-  }
-}
+import {
+  DyFM_DataProperties,
+  DyFM_Error,
+} from '@futdevpro/fsm-dynamo';
+import { DyFM_Crypto } from '@futdevpro/fsm-dynamo/crypto';
+
+/**
+ * AT-REST field-encryption transzform (Option B, bedrock). A DBService a közös írási úton
+ * (`createData` / `modifyData`) a persist ELŐTT titkosítja, a read-post-processor
+ * (`stringifyDataId`) a load UTÁN visszafejti az `encrypt:true` mezőket.
+ *
+ * **App-rétegben fut, NEM mongoose-hook** — a `modifyData` `findByIdAndUpdate`-je megkerüli a
+ * mongoose settereket/pre-save-hookokat, ezért a transzform explicit itt történik.
+ *
+ * **Opt-in, default-off:** ha egy modell egyetlen mezője sem `encrypt:true`, a transzform tiszta
+ * NO-OP (ugyanaz az objektum-referencia, nincs klónozás, nincs viselkedés-változás, kulcs sem kell).
+ *
+ * **Legacy-plaintext biztonságos:** a read-transzform CSAK a `DYENC1:` envelope-értékeket fejti vissza
+ * (`isEncryptedDbValue`); a régi, még nem migrált plaintext értékek változatlanul jönnek vissza.
+ *
+ * Kulcs: `FDP_CORE_DBCONTENT_CRYPT_KEY` (Keystore/CI-env). Verzió: `FDP_CORE_DBCONTENT_CRYPT_KEY_VERSION`
+ * (default 1) — a kulcs-rotációhoz (a verzió az envelope-ban utazik).
+ */
+export class DyNTS_FieldEncryption_Util {
+  static readonly ENV_KEY: string = 'FDP_CORE_DBCONTENT_CRYPT_KEY';
+  static readonly ENV_KEY_VERSION: string = 'FDP_CORE_DBCONTENT_CRYPT_KEY_VERSION';
+
+  /** `hasEncryptedFields` cache per properties-objektum (referencia szerint). */
+  private static readonly _hasEncCache: WeakMap<object, boolean> = new WeakMap();
+
+  /** A titkosító kulcs env-ből (üres string, ha nincs beállítva). */
+  static getKey(): string {
+    return process.env[this.ENV_KEY] ?? '';
+  }
+
+  /** Az aktuális kulcs-verzió (default 1). */
+  static getKeyVersion(): number {
+    const parsed: number = Number(process.env[this.ENV_KEY_VERSION]);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 1;
+  }
+
+  /**
+   * True, ha a properties-fa (rekurzívan a `subObjectParams`-on át) tartalmaz `encrypt:true` mezőt.
+   * Cache-elt (a properties-objektum immutábilis a modell-élettartam alatt).
+   */
+  static hasEncryptedFields(properties?: DyFM_DataProperties<any>): boolean {
+    if (!properties) {
+      return false;
+    }
+
+    const cached: boolean | undefined = this._hasEncCache.get(properties);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    let has: boolean = false;
+    for (const key in properties) {
+      const prop: any = properties[key]; // ccap-review-disable-line no-any-type
+      if (!prop) {
+        continue;
+      }
+      if (prop.encrypt === true) {
+        has = true;
+        break;
+      }
+      if (prop.subObjectParams && this.hasEncryptedFields(prop.subObjectParams)) {
+        has = true;
+        break;
+      }
+    }
+
+    this._hasEncCache.set(properties, has);
+    return has;
+  }
+
+  /**
+   * Titkosítja a doc `encrypt:true` mezőit persist előtt. **Klónt ad vissza** — az eredeti (hívó)
+   * objektumot NEM mutálja (különben a `this.data` ciphertextté válna). NO-OP, ha nincs enc-mező.
+   * @throws ha van enc-mező, de a kulcs env-var nincs beállítva (fail-loud misconfiguration).
+   */
+  static encryptDoc<T>(data: T, properties?: DyFM_DataProperties<any>): T {
+    if (data == null || !this.hasEncryptedFields(properties)) {
+      return data;
+    }
+
+    const key: string = this.getKey();
+    if (!key) {
+      throw new DyFM_Error({
+        status: 500,
+        errorCode: 'DyNTS-ENC-KEY-MISSING',
+        message:
+          `At-rest encryption: "${this.ENV_KEY}" env-var is not set, but a model field is encrypt:true. ` +
+          `Set the key in the Keystore/CI-env and redeploy.`,
+      });
+    }
+
+    return this._transform(data, properties as DyFM_DataProperties<any>, 'encrypt', key, this.getKeyVersion());
+  }
+
+  /**
+   * Visszafejti a doc `encrypt:true` mezőit load után. CSAK a `DYENC1:` envelope-értékeket bántja
+   * (legacy plaintext változatlan). NO-OP, ha nincs enc-mező. Kulcs hiányában read-en NEM dob
+   * (a read ne törjön el) — az envelope-értékek visszafejtetlenül maradnak (a hívó látja + a hiba loggolt).
+   */
+  static decryptDoc<T>(data: T, properties?: DyFM_DataProperties<any>): T {
+    if (data == null || !this.hasEncryptedFields(properties)) {
+      return data;
+    }
+
+    const key: string = this.getKey();
+    if (!key) {
+      return data;
+    }
+
+    return this._transform(data, properties as DyFM_DataProperties<any>, 'decrypt', key, this.getKeyVersion());
+  }
+
+  /**
+   * Egy mongoose-**Document** sima objektummá alakítása (más érték változatlanul jön vissza).
+   *
+   * @description 🔴 **MIÉRT KELL** (BFR-MASTERPROMPTER-027, 2026-08-14): a `_transform` sekély spreaddel
+   *   klónoz. Egy mongoose-Documentnek viszont az adatok NEM saját mezői — azok a belső `_doc`-ban
+   *   ülnek —, ezért a `{ ...doc }` a **belső burkot** másolja (`$__`, `$isNew`, `_doc`), és az eredmény
+   *   **már nem Document**, tehát a `JSON.stringify` sem hívja a `toJSON()`-ját. A kliens így
+   *   `{"$__":…,"$isNew":…,"_doc":{…}}`-t kap `_id` nélkül.
+   *
+   *   **Élesben mérve** (`test.master-prompter.hu`, 2026-08-14): a `flow` lista-endpoint válaszának
+   *   első elemén a kulcsok `["$__","$isNew","_doc"]`, `_id: undefined` → a kliens-oldali linkek
+   *   `/editor/undefined`-ra mutattak, a törlés `missing pathParam: "flowId"`-vel állt meg. Az EGYEDI
+   *   get ugyanakkor ép volt — mert a `DyNTS_DBService` az egyedi olvasásoknál **már `toObject()`-et**
+   *   hív (`db.service.ts` getDataById / getDataByDependencyId / findByIdAndUpdate / findOneAndUpdate),
+   *   a **lista-metódusok (11 db) viszont NYERS Documentet adnak tovább**. Titkosítás nélküli
+   *   modelleknél ez ártalmatlan (a `res.send` a `toJSON()`-on át szerializál), `encrypt:true` mező
+   *   esetén viszont a spread elrontja.
+   *
+   *   **Miért ITT javítjuk, és nem a 11 DB-metódusban:** (1) ez az EGY pont mind a 11 utat rendezi;
+   *   (2) a 11 metódus visszatérési TÍPUSÁT megváltoztatni (Document → sima objektum) minden modell
+   *   minden fogyasztóját érintené — az itteni javítás viszont **csak az `encrypt:true` modelleket**
+   *   érinti, ahol a `_transform` amúgy is **már ma is** sima (csak ROSSZ) objektumot ad vissza.
+   *   Vagyis a változás nem tud elrontani olyat, ami ma működik.
+   *
+   *   `toJSON()`-t használunk (nem `toObject()`-et): a titkosítás bevezetése ELŐTT a nyers Document a
+   *   `res.send`-en át a `JSON.stringify` → `toJSON()` úton szerializálódott, tehát ez adja vissza
+   *   **bitre ugyanazt a kimeneti alakot** (schema-transzformok, virtuals, `__v`-kezelés együtt).
+   *
+   * @param value tetszőleges érték
+   * @returns a Document sima alakja, vagy az eredeti érték
+   */
+  private static _toPlainIfDocument(value: any): any { // ccap-review-disable-line no-any-type
+    // A `$__` a mongoose-Document SAJÁT mezője — pontosan ez szivárgott ki a hibás payloadba,
+    // ezért ez a legpontosabb (és mongoose-import nélküli) diszkriminátor.
+    if (
+      value != null
+      && typeof value === 'object'
+      && typeof value.toJSON === 'function'
+      && Object.prototype.hasOwnProperty.call(value, '$__')
+    ) {
+      return value.toJSON();
+    }
+
+    return value;
+  }
+
+  /**
+   * Rekurzív per-field walk: az `encrypt:true` mezőket titkosítja/visszafejti, a `subObjectParams`-os
+   * mezőkbe (objektum VAGY objektum-tömb) leszáll. Immutábilis: minden érintett konténert sekélyen
+   * klónoz (az eredetit nem mutálja); a nem-érintett ágakat referencia szerint megosztja (read-only).
+   *
+   * ⚠️ A klónozás ELŐTT a mongoose-Documentek sima objektummá alakulnak — lásd {@link _toPlainIfDocument}.
+   */
+  private static _transform<T>(
+    value: T,
+    properties: DyFM_DataProperties<any>,
+    mode: 'encrypt' | 'decrypt',
+    key: string,
+    keyVersion: number,
+  ): T {
+    if (value == null || typeof value !== 'object') {
+      return value;
+    }
+
+    const plain: any = this._toPlainIfDocument(value); // ccap-review-disable-line no-any-type
+    const result: any = Array.isArray(plain) ? [ ...(plain as any[]) ] : { ...(plain as any) }; // ccap-review-disable-line no-any-type
+
+    for (const propKey in properties) {
+      const prop: any = properties[propKey]; // ccap-review-disable-line no-any-type
+      if (!prop) {
+        continue;
+      }
+
+      if (prop.encrypt === true) {
+        const current: any = result[propKey]; // ccap-review-disable-line no-any-type
+
+        if (mode === 'encrypt') {
+          // Üres/undefined/null-t NEM titkosítunk (a DyFM_Crypto ezekre dob); már-envelope-ot sem (idempotens).
+          if (current != null && current !== '' && !DyFM_Crypto.isEncryptedDbValue(current)) {
+            result[propKey] = DyFM_Crypto.encryptDbValue(current, key, keyVersion);
+          }
+        } else {
+          // CSAK envelope-ot fejtünk vissza (legacy plaintext változatlan).
+          if (DyFM_Crypto.isEncryptedDbValue(current)) {
+            result[propKey] = DyFM_Crypto.decryptDbValue(current, key);
+          }
+        }
+      } else if (prop.subObjectParams) {
+        const current: any = result[propKey]; // ccap-review-disable-line no-any-type
+
+        if (current != null && typeof current === 'object') {
+          if (Array.isArray(current)) {
+            result[propKey] = current.map(
+              (item: any): any => this._transform(item, prop.subObjectParams, mode, key, keyVersion), // ccap-review-disable-line no-any-type
+            );
+          } else {
+            result[propKey] = this._transform(current, prop.subObjectParams, mode, key, keyVersion);
+          }
+        }
+      }
+    }
+
+    return result as T;
+  }
+}