@futdevpro/nts-dynamo 1.15.117 → 1.15.119

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/_models/data-models/schema-migration.data-model.ts

@@ -0,0 +1,50 @@
+import { DyFM_DataModel_Params, DyFM_Metadata } from '@futdevpro/fsm-dynamo';
+
+/**
+ * **Migráció-nyilvántartó ("server info") LEDGER** — bedrock, újrahasználható az egész flottának.
+ * (A token-service app-lokál `SchemaMigration` mintájából emelve bedrock nts-be.)
+ *
+ * Egy-egy `migrationId` **PONTOSAN EGYSZER** fut le rendszerenként: a `DyNTS_Migration_Runner.runPending()`
+ * boot-on (az app `app.server.postProcess()`-éből) lekéri a már-alkalmazott ID-kat, a pending
+ * migrációkat lefuttatja, majd egy sort rögzít ide. A `migrationId` **unique index** → race-safe
+ * (két párhuzamos instance esetén az egyik `save`-je duplicate-key-re bukik → skip).
+ *
+ * A ledger a KÖTELEZŐ kanon-adatokat tartja: **mely migrációk futottak** (id + idő) + **mely app-verzió**
+ * alkalmazta (a `appliedVersion`-ökből a "mely verziók futottak" levezethető).
+ *
+ * Az app a saját DB-jében regisztrálja a `dyNTS_schemaMigration_dataParams`-t (`getGlobalServiceCollection
+ * ().dbModels`), így per-app saját `dynts_schema_migrations` collection-t kap.
+ */
+export class DyNTS_SchemaMigration extends DyFM_Metadata {
+
+  /** A migráció egyedi azonosítója (konvenció: `YYYY-MM-DD-NNN-descriptor`). */
+  migrationId?: string;
+
+  /** Alkalmazás időbélyege. */
+  appliedAt?: Date;
+
+  /** Az alkalmazó app-verzió (a `package.json` version-je — audit-trail + "mely verziók futottak"). */
+  appliedVersion?: string;
+
+  /** Diag — pl. `touched=<n>` vagy hiba-részletek. */
+  notes?: string;
+
+  constructor(set?: DyNTS_SchemaMigration) {
+    super(set);
+    if (set) {
+      Object.assign(this, set);
+    }
+  }
+}
+
+export const dyNTS_schemaMigration_dataParams: DyFM_DataModel_Params<DyNTS_SchemaMigration> =
+  new DyFM_DataModel_Params<DyNTS_SchemaMigration>({
+    dataName: 'dynts_schema_migrations',
+    addArchive: false,
+    properties: {
+      migrationId:    { type: 'string', required: true, unique: true, index: true },
+      appliedAt:      { type: 'date',   required: true },
+      appliedVersion: { type: 'string' },
+      notes:          { type: 'string' },
+    },
+  });

package/src/_models/interfaces/migration-entry.interface.ts

@@ -0,0 +1,19 @@
+/**
+ * Egy regisztrált deploy-integrált migráció leírója. Az app egy `DyNTS_MigrationEntry[]` registry-t
+ * ad át a `DyNTS_Migration_Runner.runPending(...)`-nek; a runner a pending (még nem alkalmazott)
+ * entry-ket **egyszer** futtatja le, sorrendben, majd a `DyNTS_SchemaMigration` ledgerbe rögzíti.
+ */
+export interface DyNTS_MigrationEntry {
+  /** Egyedi, monoton bővíthető ID (konvenció: `YYYY-MM-DD-NNN-descriptor`). A ledger ez alapján run-once-ol. */
+  id: string;
+
+  /** Rövid leíró (admin/debug/log). */
+  description: string;
+
+  /**
+   * A tényleges migráció-logika. Az app már-csatlakozott Mongo-kapcsolatát használja (a runner a
+   * `postProcess`-ből fut, ahol a DB már él). Hibára DOBHAT — a runner catch-eli, a `notes`-ba menti,
+   * és NEM állítja meg a boot-ot. Visszaad: `{ touched }` (a módosított dokumentumok száma — count/riport).
+   */
+  run: (issuer: string) => Promise<{ touched: number }>;
+}

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}`;
 

package/src/_services/core/migration-runner.service.spec.ts

@@ -0,0 +1,91 @@
+import { DyNTS_Migration_Runner } from './migration-runner.service';
+import { DyNTS_SchemaMigration } from '../../_models/data-models/schema-migration.data-model';
+import { DyNTS_MigrationEntry } from '../../_models/interfaces/migration-entry.interface';
+
+function entry(id: string, run: () => Promise<{ touched: number }>): DyNTS_MigrationEntry {
+  return { id: id, description: id, run: run };
+}
+
+describe('| DyNTS_Migration_Runner', () => {
+
+  describe('| selectPending (pure)', () => {
+    it('| kiszűri a már-alkalmazottakat, megőrzi a sorrendet', () => {
+      const migs: DyNTS_MigrationEntry[] = [
+        entry('a', async () => ({ touched: 0 })),
+        entry('b', async () => ({ touched: 0 })),
+        entry('c', async () => ({ touched: 0 })),
+      ];
+      const pending: DyNTS_MigrationEntry[] = DyNTS_Migration_Runner.selectPending(migs, new Set([ 'b' ]));
+      expect(pending.map((m) => m.id)).toEqual([ 'a', 'c' ]);
+    });
+
+    it('| mind alkalmazva → üres; üres registry → üres', () => {
+      const migs: DyNTS_MigrationEntry[] = [ entry('a', async () => ({ touched: 0 })) ];
+      expect(DyNTS_Migration_Runner.selectPending(migs, new Set([ 'a' ])).length).toBe(0);
+      expect(DyNTS_Migration_Runner.selectPending([], new Set()).length).toBe(0);
+    });
+  });
+
+  describe('| runPending (mock ledger)', () => {
+    let runner: DyNTS_Migration_Runner;
+    let saved: DyNTS_SchemaMigration[];
+    let appliedRecords: DyNTS_SchemaMigration[];
+
+    beforeEach(() => {
+      runner = DyNTS_Migration_Runner.getInstance();
+      saved = [];
+      appliedRecords = [];
+
+      const fakeLedger: any = { // ccap-review-disable-line no-any-type
+        dataDBService: { find: async (): Promise<DyNTS_SchemaMigration[]> => appliedRecords },
+        data: null,
+        saveData: async function (): Promise<void> { saved.push(this.data); appliedRecords.push(this.data); },
+      };
+
+      spyOn(runner as any, 'createLedgerDataService').and.returnValue(fakeLedger); // ccap-review-disable-line no-any-type
+    });
+
+    it('| a pending-et futtatja + rögzíti (id+version+touched), a már-alkalmazottat SKIP-eli', async () => {
+      appliedRecords.push(new DyNTS_SchemaMigration({ migrationId: 'm1' }));
+      const ran: string[] = [];
+
+      const migs: DyNTS_MigrationEntry[] = [
+        entry('m1', async () => { ran.push('m1'); return { touched: 1 }; }),
+        entry('m2', async () => { ran.push('m2'); return { touched: 5 }; }),
+      ];
+
+      const res = await runner.runPending(migs, '1.0.0');
+
+      expect(ran).toEqual([ 'm2' ]);          // m1 skip (már applied), m2 fut
+      expect(res.applied).toBe(1);
+      expect(res.skipped).toBe(1);
+      expect(saved[0].migrationId).toBe('m2');
+      expect(saved[0].appliedVersion).toBe('1.0.0');
+      expect(saved[0].notes).toBe('touched=5');
+    });
+
+    it('| RUN-ONCE: második sweep-en (m2 már a ledgerben) semmi nem fut', async () => {
+      appliedRecords.push(new DyNTS_SchemaMigration({ migrationId: 'm2' }));
+      const ran: string[] = [];
+      const migs: DyNTS_MigrationEntry[] = [ entry('m2', async () => { ran.push('m2'); return { touched: 0 }; }) ];
+
+      const res = await runner.runPending(migs, '1.0.0');
+      expect(ran.length).toBe(0);
+      expect(res.applied).toBe(0);
+      expect(res.skipped).toBe(1);
+    });
+
+    it('| BOOT-SAFE: egy hibás migráció NEM dob + NEM állítja meg a többit', async () => {
+      const ran: string[] = [];
+      const migs: DyNTS_MigrationEntry[] = [
+        entry('bad', async () => { throw new Error('boom'); }),
+        entry('good', async () => { ran.push('good'); return { touched: 2 }; }),
+      ];
+
+      const res = await runner.runPending(migs, '1.0.0');
+      expect(res.failed).toBe(1);
+      expect(res.applied).toBe(1);            // 'good' a hiba UTÁN is lefutott
+      expect(ran).toEqual([ 'good' ]);
+    });
+  });
+});

package/src/_services/core/migration-runner.service.ts

@@ -0,0 +1,106 @@
+import { DyFM_Error, DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_SingletonService } from '../base/singleton.service';
+import { DyNTS_DataService } from '../base/data.service';
+import {
+  DyNTS_SchemaMigration, dyNTS_schemaMigration_dataParams,
+} from '../../_models/data-models/schema-migration.data-model';
+import { DyNTS_MigrationEntry } from '../../_models/interfaces/migration-entry.interface';
+
+/** A `runPending` összesítő eredménye. */
+export interface DyNTS_MigrationRunResult {
+  applied: number;
+  skipped: number;
+  failed: number;
+}
+
+/**
+ * **Deploy-integrált migráció-futtató** — bedrock, újrahasználható. Az app a `app.server.postProcess()`-
+ * ből hívja: `DyNTS_Migration_Runner.getInstance().runPending(ALL_MIGRATIONS, appVersion)`.
+ *
+ * Mechanizmus (kanon `deploy-integrated-migrations.md`):
+ *  - Boot-on lekéri a `DyNTS_SchemaMigration` ledgerből a MÁR-alkalmazott `migrationId`-kat.
+ *  - A **pending** (még nem alkalmazott) entry-ket **sorrendben, egyszer** lefuttatja.
+ *  - Mindegyik után egy ledger-sort rögzít (`migrationId` + `appliedAt` + `appliedVersion` + `notes`).
+ *  - **RUN-ONCE:** a `migrationId` unique-index → re-boot / párhuzamos instance esetén skip (duplicate-key).
+ *  - **Boot-safe:** egy hibás migráció NEM állítja meg a boot-ot (catch + notes; a runner tovább megy).
+ */
+export class DyNTS_Migration_Runner extends DyNTS_SingletonService {
+
+  static getInstance(): DyNTS_Migration_Runner {
+    return DyNTS_Migration_Runner.getSingletonInstance();
+  }
+
+  /**
+   * TISZTA pending-szelekció (DB nélkül tesztelhető): azok az entry-k, amiknek az `id`-ja NINCS az
+   * `appliedIds`-ban. A regisztráció sorrendje megőrződik (a bővítés a tömb VÉGÉRE).
+   */
+  static selectPending(
+    migrations: DyNTS_MigrationEntry[],
+    appliedIds: Set<string>,
+  ): DyNTS_MigrationEntry[] {
+    return (migrations ?? []).filter((migration: DyNTS_MigrationEntry): boolean => !appliedIds.has(migration.id));
+  }
+
+  /** A ledger-DataService előállítása. `protected` → a spec felül tudja írni (mock-hoz). */
+  protected createLedgerDataService(issuer: string): DyNTS_DataService<DyNTS_SchemaMigration> {
+    return new DyNTS_DataService<DyNTS_SchemaMigration>(
+      new DyNTS_SchemaMigration(),
+      dyNTS_schemaMigration_dataParams,
+      issuer,
+    );
+  }
+
+  /**
+   * A pending migrációk lefuttatása + rögzítése.
+   *
+   * @param migrations - az app registry-je (`DyNTS_MigrationEntry[]`)
+   * @param appVersion - az app aktuális verziója (a ledger `appliedVersion`-jébe)
+   * @param issuer - opcionális issuer-cimke (default `DyNTS_Migration_Runner`)
+   */
+  async runPending(
+    migrations: DyNTS_MigrationEntry[],
+    appVersion: string,
+    issuer: string = 'DyNTS_Migration_Runner',
+  ): Promise<DyNTS_MigrationRunResult> {
+    const result: DyNTS_MigrationRunResult = { applied: 0, skipped: 0, failed: 0 };
+
+    DyFM_Log.info(`[dynts-migration] sweep start — ${migrations?.length ?? 0} migration(s) registered · appVersion=${appVersion}`);
+
+    const ledger_DS: DyNTS_DataService<DyNTS_SchemaMigration> = this.createLedgerDataService(issuer);
+
+    const applied: DyNTS_SchemaMigration[] = await ledger_DS.dataDBService.find({} as never);
+    const appliedIds: Set<string> = new Set(
+      applied.map((record: DyNTS_SchemaMigration): string => record.migrationId ?? ''),
+    );
+
+    const pending: DyNTS_MigrationEntry[] = DyNTS_Migration_Runner.selectPending(migrations, appliedIds);
+    result.skipped = (migrations?.length ?? 0) - pending.length;
+
+    for (const migration of pending) {
+      try {
+        DyFM_Log.info(`[dynts-migration] applying ${migration.id} — ${migration.description}`);
+        const outcome: { touched: number } = await migration.run(issuer);
+
+        // Atomikus claim — a unique-index dob duplicate-ra (race-safe, két párhuzamos instance).
+        ledger_DS.data = new DyNTS_SchemaMigration({
+          migrationId: migration.id,
+          appliedAt: new Date(),
+          appliedVersion: appVersion,
+          notes: `touched=${outcome?.touched ?? 0}`,
+        });
+        await ledger_DS.saveData();
+
+        DyFM_Log.success(`[dynts-migration] applied ${migration.id} (touched=${outcome?.touched ?? 0})`);
+        result.applied++;
+      } catch (error) {
+        // Egy hibás migráció NEM állíthatja meg a boot-ot (catch + log; a következő entry mehet).
+        DyFM_Error.logSimple(`[dynts-migration] FAILED ${migration.id}`, error);
+        result.failed++;
+      }
+    }
+
+    DyFM_Log.info(`[dynts-migration] sweep done — applied=${result.applied} skipped=${result.skipped} failed=${result.failed}`);
+    return result;
+  }
+}

package/src/index.ts

@@ -53,6 +53,7 @@ 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/client-safe-error.util';
 export * from './_collections/load-shed.util';
@@ -70,6 +71,9 @@ export * from './_models/control-models/system-control.control-model';
 // models/TYPES
 export * from './_models/types/db-update.type';
 
+// models/DATA-MODELS
+export * from './_models/data-models/schema-migration.data-model';
+
 
 // SERVICES
 // services/CORE
@@ -82,6 +86,7 @@ export * from './_services/core/global.service';
 export * from './_services/core/memory-guard.service';
 
 export * from './_services/core/service-collection.service';
+export * from './_services/core/migration-runner.service';
 
 // services/BASE
 export * from './_services/base/api.service-base';