@futdevpro/nts-dynamo 1.15.154 → 1.15.156

package/build/_collections/field-encryption.util.d.ts

@@ -1,86 +1,86 @@
-import { DyFM_DataProperties } from '@futdevpro/fsm-dynamo';
-/**
- * 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 declare class DyNTS_FieldEncryption_Util {
-    static readonly ENV_KEY: string;
-    static readonly ENV_KEY_VERSION: string;
-    /** `hasEncryptedFields` cache per properties-objektum (referencia szerint). */
-    private static readonly _hasEncCache;
-    /** A titkosító kulcs env-ből (üres string, ha nincs beállítva). */
-    static getKey(): string;
-    /** Az aktuális kulcs-verzió (default 1). */
-    static getKeyVersion(): number;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-}
+import { DyFM_DataProperties } from '@futdevpro/fsm-dynamo';
+/**
+ * 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 declare class DyNTS_FieldEncryption_Util {
+    static readonly ENV_KEY: string;
+    static readonly ENV_KEY_VERSION: string;
+    /** `hasEncryptedFields` cache per properties-objektum (referencia szerint). */
+    private static readonly _hasEncCache;
+    /** A titkosító kulcs env-ből (üres string, ha nincs beállítva). */
+    static getKey(): string;
+    /** Az aktuális kulcs-verzió (default 1). */
+    static getKeyVersion(): number;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+}
 //# sourceMappingURL=field-encryption.util.d.ts.map

package/build/_collections/field-encryption.util.js

@@ -1,193 +1,193 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DyNTS_FieldEncryption_Util = void 0;
-const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
-const crypto_1 = require("@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).
- */
-class DyNTS_FieldEncryption_Util {
-    static ENV_KEY = 'FDP_CORE_DBCONTENT_CRYPT_KEY';
-    static ENV_KEY_VERSION = 'FDP_CORE_DBCONTENT_CRYPT_KEY_VERSION';
-    /** `hasEncryptedFields` cache per properties-objektum (referencia szerint). */
-    static _hasEncCache = new WeakMap();
-    /** A titkosító kulcs env-ből (üres string, ha nincs beállítva). */
-    static getKey() {
-        return process.env[this.ENV_KEY] ?? '';
-    }
-    /** Az aktuális kulcs-verzió (default 1). */
-    static getKeyVersion() {
-        const parsed = 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) {
-        if (!properties) {
-            return false;
-        }
-        const cached = this._hasEncCache.get(properties);
-        if (cached !== undefined) {
-            return cached;
-        }
-        let has = false;
-        for (const key in properties) {
-            const prop = 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(data, properties) {
-        if (data == null || !this.hasEncryptedFields(properties)) {
-            return data;
-        }
-        const key = this.getKey();
-        if (!key) {
-            throw new fsm_dynamo_1.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, '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(data, properties) {
-        if (data == null || !this.hasEncryptedFields(properties)) {
-            return data;
-        }
-        const key = this.getKey();
-        if (!key) {
-            return data;
-        }
-        return this._transform(data, properties, '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
-     */
-    static _toPlainIfDocument(value) {
-        // 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}.
-     */
-    static _transform(value, properties, mode, key, keyVersion) {
-        if (value == null || typeof value !== 'object') {
-            return value;
-        }
-        const plain = this._toPlainIfDocument(value); // ccap-review-disable-line no-any-type
-        const result = Array.isArray(plain) ? [...plain] : { ...plain }; // ccap-review-disable-line no-any-type
-        for (const propKey in properties) {
-            const prop = properties[propKey]; // ccap-review-disable-line no-any-type
-            if (!prop) {
-                continue;
-            }
-            if (prop.encrypt === true) {
-                const current = 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 !== '' && !crypto_1.DyFM_Crypto.isEncryptedDbValue(current)) {
-                        result[propKey] = crypto_1.DyFM_Crypto.encryptDbValue(current, key, keyVersion);
-                    }
-                }
-                else {
-                    // CSAK envelope-ot fejtünk vissza (legacy plaintext változatlan).
-                    if (crypto_1.DyFM_Crypto.isEncryptedDbValue(current)) {
-                        result[propKey] = crypto_1.DyFM_Crypto.decryptDbValue(current, key);
-                    }
-                }
-            }
-            else if (prop.subObjectParams) {
-                const current = result[propKey]; // ccap-review-disable-line no-any-type
-                if (current != null && typeof current === 'object') {
-                    if (Array.isArray(current)) {
-                        result[propKey] = current.map((item) => this._transform(item, prop.subObjectParams, mode, key, keyVersion));
-                    }
-                    else {
-                        result[propKey] = this._transform(current, prop.subObjectParams, mode, key, keyVersion);
-                    }
-                }
-            }
-        }
-        return result;
-    }
-}
-exports.DyNTS_FieldEncryption_Util = DyNTS_FieldEncryption_Util;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyNTS_FieldEncryption_Util = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const crypto_1 = require("@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).
+ */
+class DyNTS_FieldEncryption_Util {
+    static ENV_KEY = 'FDP_CORE_DBCONTENT_CRYPT_KEY';
+    static ENV_KEY_VERSION = 'FDP_CORE_DBCONTENT_CRYPT_KEY_VERSION';
+    /** `hasEncryptedFields` cache per properties-objektum (referencia szerint). */
+    static _hasEncCache = new WeakMap();
+    /** A titkosító kulcs env-ből (üres string, ha nincs beállítva). */
+    static getKey() {
+        return process.env[this.ENV_KEY] ?? '';
+    }
+    /** Az aktuális kulcs-verzió (default 1). */
+    static getKeyVersion() {
+        const parsed = 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) {
+        if (!properties) {
+            return false;
+        }
+        const cached = this._hasEncCache.get(properties);
+        if (cached !== undefined) {
+            return cached;
+        }
+        let has = false;
+        for (const key in properties) {
+            const prop = 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(data, properties) {
+        if (data == null || !this.hasEncryptedFields(properties)) {
+            return data;
+        }
+        const key = this.getKey();
+        if (!key) {
+            throw new fsm_dynamo_1.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, '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(data, properties) {
+        if (data == null || !this.hasEncryptedFields(properties)) {
+            return data;
+        }
+        const key = this.getKey();
+        if (!key) {
+            return data;
+        }
+        return this._transform(data, properties, '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
+     */
+    static _toPlainIfDocument(value) {
+        // 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}.
+     */
+    static _transform(value, properties, mode, key, keyVersion) {
+        if (value == null || typeof value !== 'object') {
+            return value;
+        }
+        const plain = this._toPlainIfDocument(value); // ccap-review-disable-line no-any-type
+        const result = Array.isArray(plain) ? [...plain] : { ...plain }; // ccap-review-disable-line no-any-type
+        for (const propKey in properties) {
+            const prop = properties[propKey]; // ccap-review-disable-line no-any-type
+            if (!prop) {
+                continue;
+            }
+            if (prop.encrypt === true) {
+                const current = 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 !== '' && !crypto_1.DyFM_Crypto.isEncryptedDbValue(current)) {
+                        result[propKey] = crypto_1.DyFM_Crypto.encryptDbValue(current, key, keyVersion);
+                    }
+                }
+                else {
+                    // CSAK envelope-ot fejtünk vissza (legacy plaintext változatlan).
+                    if (crypto_1.DyFM_Crypto.isEncryptedDbValue(current)) {
+                        result[propKey] = crypto_1.DyFM_Crypto.decryptDbValue(current, key);
+                    }
+                }
+            }
+            else if (prop.subObjectParams) {
+                const current = result[propKey]; // ccap-review-disable-line no-any-type
+                if (current != null && typeof current === 'object') {
+                    if (Array.isArray(current)) {
+                        result[propKey] = current.map((item) => this._transform(item, prop.subObjectParams, mode, key, keyVersion));
+                    }
+                    else {
+                        result[propKey] = this._transform(current, prop.subObjectParams, mode, key, keyVersion);
+                    }
+                }
+            }
+        }
+        return result;
+    }
+}
+exports.DyNTS_FieldEncryption_Util = DyNTS_FieldEncryption_Util;
 //# sourceMappingURL=field-encryption.util.js.map

package/build/_collections/get-environment-settings.util.d.ts

@@ -1,3 +1,3 @@
-import { DyNTS_Environment_Settings } from '../_models/interfaces/environment-settings.interface';
-export declare function DyNTS_getEnvironment_settings(): DyNTS_Environment_Settings;
+import { DyNTS_Environment_Settings } from '../_models/interfaces/environment-settings.interface';
+export declare function DyNTS_getEnvironment_settings(): DyNTS_Environment_Settings;
 //# sourceMappingURL=get-environment-settings.util.d.ts.map