@futdevpro/nts-dynamo 1.15.117 → 1.15.118

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

@@ -0,0 +1,109 @@
+import { DyFM_DataProperties } from '@futdevpro/fsm-dynamo';
+import { DyFM_Crypto } from '@futdevpro/fsm-dynamo/crypto';
+
+import { DyNTS_FieldEncryption_Util } from './field-encryption.util';
+
+/**
+ * AT-REST field-encryption transzform-util tesztjei (AAA). Lefedi: opt-in no-op, create- ÉS
+ * update-alakú doc, roundtrip, legacy-plaintext, beágyazott (subObjectParams tömb), immutabilitás,
+ * idempotencia, kulcs-hiány.
+ */
+describe('| DyNTS_FieldEncryption_Util', () => {
+  const KEY: string = 'db-content-crypt-key-abcdefgh';
+
+  // encrypt:true a `secret` mezőn; a `name` sima; a `steps[]` beágyazott, benne encrypt:true `prompt`.
+  const encProps: DyFM_DataProperties<any> = {
+    name: { key: 'name', type: 'string' },
+    secret: { key: 'secret', type: 'string', encrypt: true },
+    steps: {
+      key: 'steps', type: 'object[]',
+      subObjectParams: {
+        prompt: { key: 'prompt', type: 'string', encrypt: true },
+        label: { key: 'label', type: 'string' },
+      },
+    },
+  } as unknown as DyFM_DataProperties<any>;
+
+  const plainProps: DyFM_DataProperties<any> = {
+    name: { key: 'name', type: 'string' },
+    email: { key: 'email', type: 'string' },
+  } as unknown as DyFM_DataProperties<any>;
+
+  beforeEach(() => { process.env.FDP_CORE_DBCONTENT_CRYPT_KEY = KEY; });
+  afterEach(() => { delete process.env.FDP_CORE_DBCONTENT_CRYPT_KEY; });
+
+  it('| opt-in: encrypt:true mező nélküli modell → NO-OP (ugyanaz a referencia)', () => {
+    const data = { name: 'x', email: 'y' };
+    expect(DyNTS_FieldEncryption_Util.encryptDoc(data, plainProps)).toBe(data);
+    expect(DyNTS_FieldEncryption_Util.decryptDoc(data, plainProps)).toBe(data);
+  });
+
+  it('| CREATE-alak (nincs _id): encrypt:true mezőt envelope-ba teszi, a simát nem bántja', () => {
+    const data: any = { name: 'plain-name', secret: 'top-secret' };
+    const enc: any = DyNTS_FieldEncryption_Util.encryptDoc(data, encProps);
+
+    expect(DyFM_Crypto.isEncryptedDbValue(enc.secret)).toBe(true);
+    expect(enc.name).toBe('plain-name');
+    // immutabilitás: az eredeti NEM változott
+    expect(data.secret).toBe('top-secret');
+  });
+
+  it('| UPDATE-alak (van _id): ugyanúgy titkosít (a modifyData/findByIdAndUpdate útra)', () => {
+    const data: any = { _id: 'abc123', name: 'n', secret: 'updated-secret' };
+    const enc: any = DyNTS_FieldEncryption_Util.encryptDoc(data, encProps);
+
+    expect(enc._id).toBe('abc123');
+    expect(DyFM_Crypto.isEncryptedDbValue(enc.secret)).toBe(true);
+    expect(DyNTS_FieldEncryption_Util.decryptDoc(enc, encProps).secret).toBe('updated-secret');
+  });
+
+  it('| roundtrip: encrypt → decrypt visszaadja az eredetit', () => {
+    const data: any = { name: 'n', secret: 'a hosszú ő/ű prompt' };
+    const enc: any = DyNTS_FieldEncryption_Util.encryptDoc(data, encProps);
+    const dec: any = DyNTS_FieldEncryption_Util.decryptDoc(enc, encProps);
+
+    expect(dec.secret).toBe('a hosszú ő/ű prompt');
+  });
+
+  it('| beágyazott tömb (subObjectParams): a steps[].prompt titkosítva/visszafejtve, label érintetlen', () => {
+    const data: any = { name: 'n', steps: [ { prompt: 'p1', label: 'l1' }, { prompt: 'p2', label: 'l2' } ] };
+    const enc: any = DyNTS_FieldEncryption_Util.encryptDoc(data, encProps);
+
+    expect(DyFM_Crypto.isEncryptedDbValue(enc.steps[0].prompt)).toBe(true);
+    expect(enc.steps[0].label).toBe('l1');
+    expect(data.steps[0].prompt).toBe('p1'); // eredeti nem mutálódott
+
+    const dec: any = DyNTS_FieldEncryption_Util.decryptDoc(enc, encProps);
+    expect(dec.steps[0].prompt).toBe('p1');
+    expect(dec.steps[1].prompt).toBe('p2');
+  });
+
+  it('| decrypt: legacy plaintext (envelope nélkül) VÁLTOZATLAN', () => {
+    const data: any = { name: 'n', secret: 'legacy plaintext, még nem migrált' };
+    const dec: any = DyNTS_FieldEncryption_Util.decryptDoc(data, encProps);
+    expect(dec.secret).toBe('legacy plaintext, még nem migrált');
+  });
+
+  it('| idempotens: már-envelope értéket nem titkosít újra', () => {
+    const enc1: any = DyNTS_FieldEncryption_Util.encryptDoc({ secret: 's' }, encProps);
+    const enc2: any = DyNTS_FieldEncryption_Util.encryptDoc(enc1, encProps);
+    expect(enc2.secret).toBe(enc1.secret);
+  });
+
+  it('| üres/undefined encrypt:true értéket NEM titkosít (a crypto arra dobna)', () => {
+    const enc: any = DyNTS_FieldEncryption_Util.encryptDoc({ name: 'n', secret: '' }, encProps);
+    expect(enc.secret).toBe('');
+  });
+
+  it('| kulcs-hiány + encrypt:true mező → encrypt DOB (fail-loud misconfig)', () => {
+    delete process.env.FDP_CORE_DBCONTENT_CRYPT_KEY;
+    expect(() => DyNTS_FieldEncryption_Util.encryptDoc({ secret: 's' }, encProps)).toThrow();
+  });
+
+  it('| kulcs-hiány READ-en NEM dob (a read ne törjön) → az envelope visszafejtetlen marad', () => {
+    const enc: any = DyNTS_FieldEncryption_Util.encryptDoc({ secret: 's' }, encProps);
+    delete process.env.FDP_CORE_DBCONTENT_CRYPT_KEY;
+    const dec: any = DyNTS_FieldEncryption_Util.decryptDoc(enc, encProps);
+    expect(dec.secret).toBe(enc.secret); // envelope marad, nincs throw
+  });
+});

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

@@ -0,0 +1,173 @@
+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());
+  }
+
+  /**
+   * 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).
+   */
+  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 result: any = Array.isArray(value) ? [ ...(value as any[]) ] : { ...(value 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;
+  }
+}

package/src/_services/base/db.service.encryption.spec.ts

@@ -0,0 +1,76 @@
+import {
+  DyFM_DataModel_Params,
+  DyFM_Metadata,
+  DyFM_BasicProperty_Type,
+} from '@futdevpro/fsm-dynamo';
+import { DyFM_Crypto } from '@futdevpro/fsm-dynamo/crypto';
+import * as mongoose from 'mongoose';
+
+import { DyNTS_DBService } from './db.service';
+import { DyNTS_FieldEncryption_Util } from '../../_collections/field-encryption.util';
+
+class EncMeta extends DyFM_Metadata {
+  name: string = '';
+  secret: string = '';
+}
+
+const encParams: DyFM_DataModel_Params<EncMeta> = new DyFM_DataModel_Params<EncMeta>({
+  dataName: 'test_enc_data',
+  properties: {
+    name: { key: 'name', type: DyFM_BasicProperty_Type.string },
+    secret: { key: 'secret', type: DyFM_BasicProperty_Type.string, encrypt: true },
+  },
+});
+
+/**
+ * AT-REST encryption a DB-layer create/update útján. A `createData`/`modifyData` mongoose-hívása
+ * DB-kapcsolat nélkül nem futtatható végig (l. db.service.spec: mongoose.model getter-only), de:
+ *  - a `findByIdAndUpdate` INSTANCE-property-ként spy-olható → az UPDATE-út (a findByIdAndUpdate
+ *    hook-bypass caveat) igazolható;
+ *  - a CREATE-út az AZONOS `encryptDoc`-ot hívja `new this.dataModel()` ELŐTT → spy-val igazolható,
+ *    hogy a persist előtt lefut (a save DB nélkül elhasal, de már az encrypt UTÁN).
+ */
+describe('| DyNTS_DBService at-rest field-encryption (create + update path)', () => {
+  let db: DyNTS_DBService<EncMeta>;
+  const KEY: string = 'db-content-crypt-key-abcdefgh';
+
+  beforeEach(() => {
+    process.env.FDP_CORE_DBCONTENT_CRYPT_KEY = KEY;
+    db = new DyNTS_DBService<EncMeta>(encParams);
+  });
+
+  afterEach(() => {
+    delete process.env.FDP_CORE_DBCONTENT_CRYPT_KEY;
+    delete (mongoose.models as Record<string, unknown>)['test_enc_data'];
+  });
+
+  it('| UPDATE: modifyData → a findByIdAndUpdate CIPHERTEXT-et kap (hook-bypass ellenére), a return plaintext', async () => {
+    const spy: jasmine.Spy = spyOn(db['dataModel'], 'findByIdAndUpdate').and.returnValue(Promise.resolve({}) as never);
+
+    const result: EncMeta = await db.modifyData({ _id: 'id1', name: 'n', secret: 'plain-secret' } as EncMeta, 'issuer');
+
+    const persisted: any = spy.calls.mostRecent().args[1]; // ccap-review-disable-line no-any-type
+    expect(DyFM_Crypto.isEncryptedDbValue(persisted.secret)).toBe(true); // DB-be ciphertext ment
+    expect(persisted.name).toBe('n');                                    // sima mező érintetlen
+    expect(result.secret).toBe('plain-secret');                          // a hívó plaintextet kap vissza
+  });
+
+  it('| CREATE: createData a persist (new dataModel/save) ELŐTT titkosít (encryptDoc a create-adattal)', async () => {
+    const encSpy: jasmine.Spy = spyOn(DyNTS_FieldEncryption_Util, 'encryptDoc').and.callThrough();
+
+    // A .save() DB-kapcsolat nélkül buffer-elne (~10s). Kikapcsoljuk a bufferelést → GYORS fail.
+    const prevBuffer: boolean | undefined = mongoose.get('bufferCommands') as boolean | undefined;
+    mongoose.set('bufferCommands', false);
+    try {
+      await db.createData({ name: 'n', secret: 'plain-secret' } as EncMeta, 'issuer');
+    } catch {
+      // A .save() DB nélkül elhasal — a lényeg, hogy az encrypt-transzform ELŐTTE lefutott.
+    } finally {
+      mongoose.set('bufferCommands', prevBuffer ?? true);
+    }
+
+    expect(encSpy).toHaveBeenCalled();
+    const passed: any = encSpy.calls.mostRecent().args[0]; // ccap-review-disable-line no-any-type
+    expect(passed.secret).toBe('plain-secret');
+  });
+});

package/src/_services/base/db.service.ts

@@ -16,6 +16,7 @@ import {
   DyFM_Object
 } from '@futdevpro/fsm-dynamo';
 import { DyNTS_archiveSuffix } from '../../_collections/archive.util';
+import { DyNTS_FieldEncryption_Util } from '../../_collections/field-encryption.util';
 import { DyNTS_DBUpdate } from '../../_models/types/db-update.type';
 import { DyNTS_DBQueryOptions } from '../../_models/interfaces/db-query-options.interface';
 import { DyNTS_global_settings } from '../../_collections/global-settings.const';
@@ -100,7 +101,11 @@ export class DyNTS_DBService<T extends DyFM_Metadata> {
     data.__createdBy = issuer;
     data.__lastModifiedBy = issuer;
 
-    const dataModel = new this.dataModel(data);
+    // AT-REST field-encryption (opt-in): az encrypt:true mezőket a persist ELŐTT titkosítjuk, egy
+    // KLÓNON (a hívó `data`-ja plaintext marad). NO-OP, ha nincs encrypt:true mező.
+    const encData: T = DyNTS_FieldEncryption_Util.encryptDoc(data, this.dataParams.properties);
+
+    const dataModel = new this.dataModel(encData);
     const newData: T = await dataModel.save().then((res): T => {
       if (res) {
         return res?.toObject() as T;
@@ -157,12 +162,18 @@ export class DyNTS_DBService<T extends DyFM_Metadata> {
       data.__lastModifiedBy = issuer;
     }
 
-    /** 
-     * EZ A SZAR TELJESEN SZAR, nem friss, nem a db-be mentett adatokat ad vissza, 
-     * átír random value-kat össze vissza, WTF 
+    // AT-REST field-encryption (opt-in): az encrypt:true mezőket a persist ELŐTT titkosítjuk, egy
+    // KLÓNON. KRITIKUS: a `findByIdAndUpdate` MEGKERÜLI a mongoose settereket/pre-save-hookokat, ezért
+    // a titkosítás itt, app-rétegben történik (nem mongoose-hookban). A hívó `data`-ja plaintext marad,
+    // így a `stringifyDataId(data)` alant no-op decrypttel a plaintextet adja vissza. NO-OP enc-mező nélkül.
+    const encData: T = DyNTS_FieldEncryption_Util.encryptDoc(data, this.dataParams.properties);
+
+    /**
+     * EZ A SZAR TELJESEN SZAR, nem friss, nem a db-be mentett adatokat ad vissza,
+     * átír random value-kat össze vissza, WTF
      * */
-    /* let newData: T = */ 
-    await this.dataModel.findByIdAndUpdate(data._id, data)/* .then((res) => {
+    /* let newData: T = */
+    await this.dataModel.findByIdAndUpdate(data._id, encData)/* .then((res) => {
       if (res) {
         //return res?.toObject() as T;
       } else {
@@ -1277,6 +1288,11 @@ export class DyNTS_DBService<T extends DyFM_Metadata> {
   // PRIVATE FUNCTIONS
 
   private stringifyDataId(data: T, fnName: string): T {
+    // AT-REST field-decryption (opt-in): ez a KÖZÖS read+write post-processor (minden read + a
+    // create/modify EREDMÉNYE is átmegy rajta), ezért itt fejtjük vissza az encrypt:true envelope-
+    // mezőket load után. NO-OP, ha nincs encrypt:true mező (ugyanaz a referencia — nulla változás).
+    data = DyNTS_FieldEncryption_Util.decryptDoc(data, this.dataParams.properties);
+
     if (data?._id && (typeof data._id !== 'string' || typeof data._id === 'object')) {
       data._id = `${data._id}`;