@futdevpro/nts-dynamo 1.15.64 → 1.15.68

package/__documentations/2026-05-17-static-client-serving-howto.md

@@ -1,144 +1,144 @@
-# Static client serving — how-to
-
-**Date:** 2026-05-17
-**Backlog:** [BL-20260417-001](../_specifications/BACKLOG.md) — DyNTS-kliens kiszolgálás képesség
-**Status:** ✅ done (audit + docs)
-
-## TL;DR
-
-A `DyNTS_App_Server` MÁR most ki tudja szolgálni a klienst (SPA-kat, statikus
-oldalakat) az API route-ok mellett ugyanazon a hoszton. Az implementáció
-2026-03-30 óta (commit `8ffe535`) része a frameworknek; a BL-20260417-001
-backlog entry post-dated a fejlesztést. Ez a how-to a meglévő capability-t
-dokumentálja.
-
-## Konfigurációs felület
-
-A static client serving akkor aktiválódik, ha a `DyNTS_App_Server`
-subclass-od `getStaticClientSettings()`-et override-olja és egy
-[`DyNTS_StaticClient_Settings`](../src/_models/interfaces/static-client-settings.interface.ts)
-objektumot ad vissza:
-
-```ts
-import { DyNTS_StaticClient_Settings } from '@futdevpro/nts-dynamo';
-
-export interface DyNTS_StaticClient_Settings {
-  root: string;                  // a static fájlok mappája (abszolút v. cwd-relatív)
-  fallbackPath?: string;          // SPA fallback (pl. 'index.html')
-  assetCacheMaxAge?: number;      // asset Cache-Control max-age (sec)
-  assetCacheImmutable?: boolean;  // 'immutable' direktíva (Angular hashed fájlokra)
-  fallbackCacheMaxAge?: number;   // fallback file Cache-Control max-age (sec)
-}
-```
-
-## Példa subclass (Angular SPA)
-
-```ts
-import path from 'path';
-import { DyNTS_App_Server, DyNTS_StaticClient_Settings } from '@futdevpro/nts-dynamo';
-
-export class MyApp_Server extends DyNTS_App_Server {
-  // ... egyéb override-ok (getAppParams, getPortSettings, getApiBasePath, stb.) ...
-
-  override getStaticClientSettings(): DyNTS_StaticClient_Settings | undefined {
-    return {
-      // Az Angular `dist/<app-name>` mappa abszolút path-ja
-      root: path.resolve(__dirname, '../../client/dist/my-app'),
-
-      // SPA — minden ismeretlen route a kliens-routerre megy
-      fallbackPath: 'index.html',
-
-      // Hashed assetek (Angular alapból ad nekik hash-et) — 1 év, immutable
-      assetCacheMaxAge: 31_536_000,
-      assetCacheImmutable: true,
-
-      // index.html-t SOHA ne cache-elje a böngésző (deploy után friss kell)
-      fallbackCacheMaxAge: 0,
-    };
-  }
-}
-```
-
-## Mit csinál a framework a háttérben
-
-A `DyNTS_App_Server.mountStaticClient()` ([app.server.ts ~1421-1484](../src/_services/server/app.server.ts))
-ezt automatikusan beállítja az API route-ok regisztrációja UTÁN:
-
-1. **`Express.static(root)` middleware** mount a `/` alatt. Ha `assetCacheMaxAge`
-   meg van adva, `setHeaders` callback-en keresztül beállítja a `Cache-Control:
-   max-age=<N>[, immutable]` header-t.
-2. **SPA fallback** (ha `fallbackPath` adott): minden ismeretlen GET kérésre
-   `res.sendFile(fallbackPath)` + `Cache-Control: max-age=<fallbackCacheMaxAge>`.
-3. **Default 404** (ha `fallbackPath` hiányzik): a beépített
-   [`DyNTS_defaultNotFoundPageHtml`](../src/_collections/default-not-found-page.const.ts)
-   kerül kiszolgálásra `status: 404` + `Content-Type: text/html`.
-4. **HTTP + HTTPS** mindkettő: a flow azonos a `this.openExpress` és
-   `this.secureExpress` instance-ekhez (ha mindkettő be van állítva).
-
-## Config matrix — mikor melyik mezőt használd
-
-| Use case | `root` | `fallbackPath` | `assetCacheMaxAge` | `assetCacheImmutable` | `fallbackCacheMaxAge` |
-|---|---|---|---|---|---|
-| **SPA** (Angular, React) hashed assetekkel | ✅ kötelező | `'index.html'` | `31_536_000` (1 év) | `true` | `0` (mindig friss) |
-| **SPA** dev mode (rebuild gyakori) | ✅ | `'index.html'` | `0` | `false` | `0` |
-| **Statikus oldal** (nincs SPA-router) | ✅ | hagyd ki | `3600` (1 óra) vagy ahogy jó | `false` | n/a |
-| **Csak API** (nincs frontend) | NE override-old a `getStaticClientSettings()`-et — akkor `undefined`-ot ad vissza és a `mountStaticClient` early-return-öl | | | | |
-
-## Asset + fallback cache stratégia (SPA)
-
-A két mező együttes használata az **alapja az Angular/React deploy-friendly caching**-nek:
-
-- **Hashed assetek** (`main.<hash>.js`, `styles.<hash>.css`, stb.) ÉLETBEN nem
-  változnak — biztonságosan `immutable` + 1 év max-age. A böngésző sose kérdezi
-  meg újra a szerverről, amíg a HTML egy új hash-elt nevet nem hivatkozik be.
-- **`index.html`** a "katalógus" ami a hashed assetekre mutat. Deploy után
-  AZONNAL friss kell legyen, különben a kliens régi assetekre hivatkozó régi
-  index.html-t kap → 404-ek a már nem létező hashed nevekre.
-  → `fallbackCacheMaxAge: 0` (no-cache).
-
-Az `assetCacheMaxAge` undefined-ja default (Express.static alapértelmezett) cache
-viselkedést hagy meg — production deploy-okra mindig explicit állítsd be.
-
-## Integration test minta
-
-A meglévő integration test fixture ([`DyNTS_AppIntegrationTest_Mock`](../src/_modules/mock/app-integration-test.mock.ts)) +
-spec ([app-extended.integration.spec.ts](../src/_modules/socket/app-extended.integration.spec.ts))
-mutatja a teljes flow-t:
-
-- A spec `beforeAll`-ban létrehoz egy temp dir-t, kitölti pár static fájllal,
-  beállítja a mock `integrationStaticRoot` static property-jét, majd elindítja
-  az appot.
-- A spec asszertálja:
-  - `started === true` (az app HTTP listenert kapott)
-  - GET nemlétező path → `404` + a default not-found HTML kiszolgálva
-  - GET `/index.html` → `200` + a temp dir-ben található static content
-  - GET `/api/test-0/test-base`, `/api/test-0/test-simple` → API kiszolgálva (az API
-    route-ok ELŐBB regisztráltak, mint a static fallback)
-- `afterAll`-ban leállítja az appot és kitakarítja a temp dir-t.
-
-## Edge case-ek + gotchák
-
-- **Mounting sorrend:** a `mountStaticClient` az `_routingModules` regisztráció
-  UTÁN fut, így az API route-ok prioritást élveznek. Tehát a `/api/...` mindig
-  az API-hoz megy, akkor is, ha a static root-ban véletlenül lenne `api/`
-  almappa.
-- **`fallbackPath` relatív** a `root`-hoz képest (`sendFile(fallbackPath, { root })`).
-- **Default 404 HTML:** szándékosan minimalista (`DyNTS_defaultNotFoundPageHtml`),
-  hogy ne ütközzön a kliens stílusával. Ha custom 404-et akarsz, add meg a
-  `fallbackPath`-t (az SPA-router majd kezelje belül a "page not found"-ot).
-- **CSP / security header-ek:** a `mountStaticClient` NEM állít be CSP-t —
-  ha kell, használj `helmet` middleware-t az API route-ok elé.
-
-## Releváns kód- és test-fájlok
-
-- [`src/_services/server/app.server.ts`](../src/_services/server/app.server.ts) — `mountStaticClient()` private + `getStaticClientSettings?()` opt-in override
-- [`src/_models/interfaces/static-client-settings.interface.ts`](../src/_models/interfaces/static-client-settings.interface.ts) — config interface
-- [`src/_collections/default-fallback-cache-max-age.const.ts`](../src/_collections/default-fallback-cache-max-age.const.ts) — default `0` (no-cache)
-- [`src/_collections/default-not-found-page.const.ts`](../src/_collections/default-not-found-page.const.ts) — default 404 HTML
-- [`src/_modules/mock/app-integration-test.mock.ts`](../src/_modules/mock/app-integration-test.mock.ts) — integration test fixture mintaként
-- [`__documentations/nts-integration-tests-2026-03-17.md`](./nts-integration-tests-2026-03-17.md) — első integration test bevezetése a unified host behavior-ra
-
-## Kapcsolódó backlog entry-k
-
-- **BL-20260420-001..004** (dynamo-nts) — `DyNTS_FileLog_Service` + admin endpoints. Mind ✅ done.
-- BL-20260417-001 (ez) — a kliens kiszolgálási képesség. ✅ done — implementáció már része a frameworknek; ez a doc a hivatkozás.
+# Static client serving — how-to
+
+**Date:** 2026-05-17
+**Backlog:** [BL-20260417-001](../_specifications/BACKLOG.md) — DyNTS-kliens kiszolgálás képesség
+**Status:** ✅ done (audit + docs)
+
+## TL;DR
+
+A `DyNTS_App_Server` MÁR most ki tudja szolgálni a klienst (SPA-kat, statikus
+oldalakat) az API route-ok mellett ugyanazon a hoszton. Az implementáció
+2026-03-30 óta (commit `8ffe535`) része a frameworknek; a BL-20260417-001
+backlog entry post-dated a fejlesztést. Ez a how-to a meglévő capability-t
+dokumentálja.
+
+## Konfigurációs felület
+
+A static client serving akkor aktiválódik, ha a `DyNTS_App_Server`
+subclass-od `getStaticClientSettings()`-et override-olja és egy
+[`DyNTS_StaticClient_Settings`](../src/_models/interfaces/static-client-settings.interface.ts)
+objektumot ad vissza:
+
+```ts
+import { DyNTS_StaticClient_Settings } from '@futdevpro/nts-dynamo';
+
+export interface DyNTS_StaticClient_Settings {
+  root: string;                  // a static fájlok mappája (abszolút v. cwd-relatív)
+  fallbackPath?: string;          // SPA fallback (pl. 'index.html')
+  assetCacheMaxAge?: number;      // asset Cache-Control max-age (sec)
+  assetCacheImmutable?: boolean;  // 'immutable' direktíva (Angular hashed fájlokra)
+  fallbackCacheMaxAge?: number;   // fallback file Cache-Control max-age (sec)
+}
+```
+
+## Példa subclass (Angular SPA)
+
+```ts
+import path from 'path';
+import { DyNTS_App_Server, DyNTS_StaticClient_Settings } from '@futdevpro/nts-dynamo';
+
+export class MyApp_Server extends DyNTS_App_Server {
+  // ... egyéb override-ok (getAppParams, getPortSettings, getApiBasePath, stb.) ...
+
+  override getStaticClientSettings(): DyNTS_StaticClient_Settings | undefined {
+    return {
+      // Az Angular `dist/<app-name>` mappa abszolút path-ja
+      root: path.resolve(__dirname, '../../client/dist/my-app'),
+
+      // SPA — minden ismeretlen route a kliens-routerre megy
+      fallbackPath: 'index.html',
+
+      // Hashed assetek (Angular alapból ad nekik hash-et) — 1 év, immutable
+      assetCacheMaxAge: 31_536_000,
+      assetCacheImmutable: true,
+
+      // index.html-t SOHA ne cache-elje a böngésző (deploy után friss kell)
+      fallbackCacheMaxAge: 0,
+    };
+  }
+}
+```
+
+## Mit csinál a framework a háttérben
+
+A `DyNTS_App_Server.mountStaticClient()` ([app.server.ts ~1421-1484](../src/_services/server/app.server.ts))
+ezt automatikusan beállítja az API route-ok regisztrációja UTÁN:
+
+1. **`Express.static(root)` middleware** mount a `/` alatt. Ha `assetCacheMaxAge`
+   meg van adva, `setHeaders` callback-en keresztül beállítja a `Cache-Control:
+   max-age=<N>[, immutable]` header-t.
+2. **SPA fallback** (ha `fallbackPath` adott): minden ismeretlen GET kérésre
+   `res.sendFile(fallbackPath)` + `Cache-Control: max-age=<fallbackCacheMaxAge>`.
+3. **Default 404** (ha `fallbackPath` hiányzik): a beépített
+   [`DyNTS_defaultNotFoundPageHtml`](../src/_collections/default-not-found-page.const.ts)
+   kerül kiszolgálásra `status: 404` + `Content-Type: text/html`.
+4. **HTTP + HTTPS** mindkettő: a flow azonos a `this.openExpress` és
+   `this.secureExpress` instance-ekhez (ha mindkettő be van állítva).
+
+## Config matrix — mikor melyik mezőt használd
+
+| Use case | `root` | `fallbackPath` | `assetCacheMaxAge` | `assetCacheImmutable` | `fallbackCacheMaxAge` |
+|---|---|---|---|---|---|
+| **SPA** (Angular, React) hashed assetekkel | ✅ kötelező | `'index.html'` | `31_536_000` (1 év) | `true` | `0` (mindig friss) |
+| **SPA** dev mode (rebuild gyakori) | ✅ | `'index.html'` | `0` | `false` | `0` |
+| **Statikus oldal** (nincs SPA-router) | ✅ | hagyd ki | `3600` (1 óra) vagy ahogy jó | `false` | n/a |
+| **Csak API** (nincs frontend) | NE override-old a `getStaticClientSettings()`-et — akkor `undefined`-ot ad vissza és a `mountStaticClient` early-return-öl | | | | |
+
+## Asset + fallback cache stratégia (SPA)
+
+A két mező együttes használata az **alapja az Angular/React deploy-friendly caching**-nek:
+
+- **Hashed assetek** (`main.<hash>.js`, `styles.<hash>.css`, stb.) ÉLETBEN nem
+  változnak — biztonságosan `immutable` + 1 év max-age. A böngésző sose kérdezi
+  meg újra a szerverről, amíg a HTML egy új hash-elt nevet nem hivatkozik be.
+- **`index.html`** a "katalógus" ami a hashed assetekre mutat. Deploy után
+  AZONNAL friss kell legyen, különben a kliens régi assetekre hivatkozó régi
+  index.html-t kap → 404-ek a már nem létező hashed nevekre.
+  → `fallbackCacheMaxAge: 0` (no-cache).
+
+Az `assetCacheMaxAge` undefined-ja default (Express.static alapértelmezett) cache
+viselkedést hagy meg — production deploy-okra mindig explicit állítsd be.
+
+## Integration test minta
+
+A meglévő integration test fixture ([`DyNTS_AppIntegrationTest_Mock`](../src/_modules/mock/app-integration-test.mock.ts)) +
+spec ([app-extended.integration.spec.ts](../src/_modules/socket/app-extended.integration.spec.ts))
+mutatja a teljes flow-t:
+
+- A spec `beforeAll`-ban létrehoz egy temp dir-t, kitölti pár static fájllal,
+  beállítja a mock `integrationStaticRoot` static property-jét, majd elindítja
+  az appot.
+- A spec asszertálja:
+  - `started === true` (az app HTTP listenert kapott)
+  - GET nemlétező path → `404` + a default not-found HTML kiszolgálva
+  - GET `/index.html` → `200` + a temp dir-ben található static content
+  - GET `/api/test-0/test-base`, `/api/test-0/test-simple` → API kiszolgálva (az API
+    route-ok ELŐBB regisztráltak, mint a static fallback)
+- `afterAll`-ban leállítja az appot és kitakarítja a temp dir-t.
+
+## Edge case-ek + gotchák
+
+- **Mounting sorrend:** a `mountStaticClient` az `_routingModules` regisztráció
+  UTÁN fut, így az API route-ok prioritást élveznek. Tehát a `/api/...` mindig
+  az API-hoz megy, akkor is, ha a static root-ban véletlenül lenne `api/`
+  almappa.
+- **`fallbackPath` relatív** a `root`-hoz képest (`sendFile(fallbackPath, { root })`).
+- **Default 404 HTML:** szándékosan minimalista (`DyNTS_defaultNotFoundPageHtml`),
+  hogy ne ütközzön a kliens stílusával. Ha custom 404-et akarsz, add meg a
+  `fallbackPath`-t (az SPA-router majd kezelje belül a "page not found"-ot).
+- **CSP / security header-ek:** a `mountStaticClient` NEM állít be CSP-t —
+  ha kell, használj `helmet` middleware-t az API route-ok elé.
+
+## Releváns kód- és test-fájlok
+
+- [`src/_services/server/app.server.ts`](../src/_services/server/app.server.ts) — `mountStaticClient()` private + `getStaticClientSettings?()` opt-in override
+- [`src/_models/interfaces/static-client-settings.interface.ts`](../src/_models/interfaces/static-client-settings.interface.ts) — config interface
+- [`src/_collections/default-fallback-cache-max-age.const.ts`](../src/_collections/default-fallback-cache-max-age.const.ts) — default `0` (no-cache)
+- [`src/_collections/default-not-found-page.const.ts`](../src/_collections/default-not-found-page.const.ts) — default 404 HTML
+- [`src/_modules/mock/app-integration-test.mock.ts`](../src/_modules/mock/app-integration-test.mock.ts) — integration test fixture mintaként
+- [`__documentations/nts-integration-tests-2026-03-17.md`](./nts-integration-tests-2026-03-17.md) — első integration test bevezetése a unified host behavior-ra
+
+## Kapcsolódó backlog entry-k
+
+- **BL-20260420-001..004** (dynamo-nts) — `DyNTS_FileLog_Service` + admin endpoints. Mind ✅ done.
+- BL-20260417-001 (ez) — a kliens kiszolgálási képesség. ✅ done — implementáció már része a frameworknek; ez a doc a hivatkozás.

package/__documentations/2026-06-01-fr041-cors-middleware.md

@@ -1,96 +1,96 @@
-# FR-041 — CORS middleware infrastructure (2026-06-01)
-
-**Commit**: `3d16d69` — v01.15.35 → v01.15.36
-**Parent**: `__agent/feature-requests/FR-041-subdomain-per-service-architecture.md`
-**Pattern**: `documentations/guidelines/development/cors-and-subdomain-architecture.md`
-
-## What
-
-Adds CORS middleware infrastructure to `DyNTS_AppServer`. After this commit, any subclass that wants to be reachable cross-origin overrides `getCorsSettings()` and returns a `DyNTS_Cors_Settings` object.
-
-## Why
-
-Pre-FR-041: every cross-service call was same-origin via gateway nginx proxy (e.g. `<app>.futdevpro.hu/auth-api/*` → `fdp-auth-service:39005/api/*`). No CORS needed because same-origin.
-
-Post-FR-041: each sister service exposed at its own subdomain (`auth.futdevpro.hu`, `social.futdevpro.hu`, etc.). Cross-origin requires CORS allowlist.
-
-Audit pre-FR-041: ZERO existing CORS implementation in the entire FDP stack (`grep -rn "cors\|Access-Control" dynamo-nts/src` returned 0 hits). Greenfield work.
-
-## Design
-
-### `DyNTS_Cors_Settings` interface
-
-`src/_models/interfaces/cors-settings.interface.ts`:
-
-```typescript
-export interface DyNTS_Cors_Settings {
-  allowedOrigins: string[] | ((origin: string) => boolean) | '*';
-  allowCredentials?: boolean;        // default true
-  allowedMethods?: string[];          // default GET/POST/PUT/DELETE/PATCH/OPTIONS
-  allowedHeaders?: string[];          // default Authorization/Content-Type/X-Admin-Key/X-Requested-With
-  exposedHeaders?: string[];          // default Content-Length/Content-Type
-  maxAgeSeconds?: number;             // default 86400 (24h preflight cache)
-}
-```
-
-### `mountCors(express)` protected method
-
-`src/_services/server/app.server.ts` (~line 1422):
-
-- Reads `this.getCorsSettings?.()` ONCE at mount time. Undefined → returns immediately (no CORS headers, back-compat).
-- Express middleware: for each request, checks Origin against allowlist. Match → echoes the origin (NOT wildcard, because credentials require an exact origin echo) + sets Methods/Headers/Expose/MaxAge/Vary.
-- OPTIONS preflight short-circuits with 204.
-
-### `getCorsSettings?()` optional override
-
-Added to the class as `getCorsSettings?(): DyNTS_Cors_Settings | undefined;`. Subclasses opt in by implementing it.
-
-## Mount-points
-
-`initOpenExpress()` + `initSecureExpress()` both call `mountCors(this.<express>)` after BodyParser, BEFORE route mounting. CORS preflight always intercepts before any route handler can interfere.
-
-Timing verified: `asyncConstruct` line 410 `getAppParams()` (sets env via `FDPNTS_setEnvBase`) → line 1018 `initOpenExpress()` (calls `mountCors`). Env is always set by the time `getCorsSettings()` runs.
-
-## Why hand-rolled (no `cors` npm dep)
-
-- ~30 lines, zero new dependency
-- Full control over Vary/credentials/preflight semantics
-- Aligns with FDP "no unnecessary deps" philosophy
-
-## Spec coverage
-
-`src/_models/interfaces/cors-settings.interface.spec.ts` — 5 specs covering all `allowedOrigins` shapes (array, predicate, wildcard) + credential defaults + custom headers.
-
-`npx jasmine` post-change: **1250/0** (146 pending pre-existing, all 5 new specs green).
-
-## Consumer pattern
-
-```typescript
-import { DyNTS_Cors_Settings } from '@futdevpro/nts-dynamo';
-import { FDPNTS_buildCorsSettings } from '@futdevpro/nts-fdp-templates';
-
-export class App extends DyNTS_App {
-  override getCorsSettings(): DyNTS_Cors_Settings | undefined {
-    return FDPNTS_buildCorsSettings();   // env-aware allowlist from FDP-templates
-  }
-}
-```
-
-First consumer: `LIVE-projects/fdp-auth-service` commit `1319368`.
-
-## What's NOT in this commit
-
-- Per-env allowlist source (lives in `fdp-templates v01.15.38`, commit `0f793c4`)
-- Helper for FDPNTS apps to bind that allowlist (lives in `fdp-templates-nts v01.15.45`, commit `6e748ee`)
-
-## Wave-3 cleanup candidates
-
-- Once every app overrides `getCorsSettings()`, consider making it abstract (no more optional `?`).
-- OPTIONS-without-origin-match returns 204 + no CORS headers (functional: browser denies). Could be improved to 403 for clearer security audit.
-
-## Cross-references
-
-- `documentations/guidelines/development/cors-and-subdomain-architecture.md`
-- `NPM-packages/fdp-templates/src/_constants/environment/fdp-cors-origins.const.ts` — allowlist
-- `NPM-packages/fdp-templates-nts/src/_collections/cors-settings.util.ts` — consumer helper
-- `LIVE-projects/fdp-auth-service/src/app.server.ts` — first consumer
+# FR-041 — CORS middleware infrastructure (2026-06-01)
+
+**Commit**: `3d16d69` — v01.15.35 → v01.15.36
+**Parent**: `__agent/feature-requests/FR-041-subdomain-per-service-architecture.md`
+**Pattern**: `documentations/guidelines/development/cors-and-subdomain-architecture.md`
+
+## What
+
+Adds CORS middleware infrastructure to `DyNTS_AppServer`. After this commit, any subclass that wants to be reachable cross-origin overrides `getCorsSettings()` and returns a `DyNTS_Cors_Settings` object.
+
+## Why
+
+Pre-FR-041: every cross-service call was same-origin via gateway nginx proxy (e.g. `<app>.futdevpro.hu/auth-api/*` → `fdp-auth-service:39005/api/*`). No CORS needed because same-origin.
+
+Post-FR-041: each sister service exposed at its own subdomain (`auth.futdevpro.hu`, `social.futdevpro.hu`, etc.). Cross-origin requires CORS allowlist.
+
+Audit pre-FR-041: ZERO existing CORS implementation in the entire FDP stack (`grep -rn "cors\|Access-Control" dynamo-nts/src` returned 0 hits). Greenfield work.
+
+## Design
+
+### `DyNTS_Cors_Settings` interface
+
+`src/_models/interfaces/cors-settings.interface.ts`:
+
+```typescript
+export interface DyNTS_Cors_Settings {
+  allowedOrigins: string[] | ((origin: string) => boolean) | '*';
+  allowCredentials?: boolean;        // default true
+  allowedMethods?: string[];          // default GET/POST/PUT/DELETE/PATCH/OPTIONS
+  allowedHeaders?: string[];          // default Authorization/Content-Type/X-Admin-Key/X-Requested-With
+  exposedHeaders?: string[];          // default Content-Length/Content-Type
+  maxAgeSeconds?: number;             // default 86400 (24h preflight cache)
+}
+```
+
+### `mountCors(express)` protected method
+
+`src/_services/server/app.server.ts` (~line 1422):
+
+- Reads `this.getCorsSettings?.()` ONCE at mount time. Undefined → returns immediately (no CORS headers, back-compat).
+- Express middleware: for each request, checks Origin against allowlist. Match → echoes the origin (NOT wildcard, because credentials require an exact origin echo) + sets Methods/Headers/Expose/MaxAge/Vary.
+- OPTIONS preflight short-circuits with 204.
+
+### `getCorsSettings?()` optional override
+
+Added to the class as `getCorsSettings?(): DyNTS_Cors_Settings | undefined;`. Subclasses opt in by implementing it.
+
+## Mount-points
+
+`initOpenExpress()` + `initSecureExpress()` both call `mountCors(this.<express>)` after BodyParser, BEFORE route mounting. CORS preflight always intercepts before any route handler can interfere.
+
+Timing verified: `asyncConstruct` line 410 `getAppParams()` (sets env via `FDPNTS_setEnvBase`) → line 1018 `initOpenExpress()` (calls `mountCors`). Env is always set by the time `getCorsSettings()` runs.
+
+## Why hand-rolled (no `cors` npm dep)
+
+- ~30 lines, zero new dependency
+- Full control over Vary/credentials/preflight semantics
+- Aligns with FDP "no unnecessary deps" philosophy
+
+## Spec coverage
+
+`src/_models/interfaces/cors-settings.interface.spec.ts` — 5 specs covering all `allowedOrigins` shapes (array, predicate, wildcard) + credential defaults + custom headers.
+
+`npx jasmine` post-change: **1250/0** (146 pending pre-existing, all 5 new specs green).
+
+## Consumer pattern
+
+```typescript
+import { DyNTS_Cors_Settings } from '@futdevpro/nts-dynamo';
+import { FDPNTS_buildCorsSettings } from '@futdevpro/nts-fdp-templates';
+
+export class App extends DyNTS_App {
+  override getCorsSettings(): DyNTS_Cors_Settings | undefined {
+    return FDPNTS_buildCorsSettings();   // env-aware allowlist from FDP-templates
+  }
+}
+```
+
+First consumer: `LIVE-projects/fdp-auth-service` commit `1319368`.
+
+## What's NOT in this commit
+
+- Per-env allowlist source (lives in `fdp-templates v01.15.38`, commit `0f793c4`)
+- Helper for FDPNTS apps to bind that allowlist (lives in `fdp-templates-nts v01.15.45`, commit `6e748ee`)
+
+## Wave-3 cleanup candidates
+
+- Once every app overrides `getCorsSettings()`, consider making it abstract (no more optional `?`).
+- OPTIONS-without-origin-match returns 204 + no CORS headers (functional: browser denies). Could be improved to 403 for clearer security audit.
+
+## Cross-references
+
+- `documentations/guidelines/development/cors-and-subdomain-architecture.md`
+- `NPM-packages/fdp-templates/src/_constants/environment/fdp-cors-origins.const.ts` — allowlist
+- `NPM-packages/fdp-templates-nts/src/_collections/cors-settings.util.ts` — consumer helper
+- `LIVE-projects/fdp-auth-service/src/app.server.ts` — first consumer