@lenne.tech/nest-server 11.32.3 → 11.33.0

package/.claude/rules/architecture.md

@@ -38,6 +38,19 @@ Key areas: JWT, MongoDB, GraphQL, email, security, static assets
 | **Security** | Response/security interceptors, input validation pipes |
 | **Scalars** | Custom GraphQL scalars (Date, JSON, Any) |
 | **Services** | CRUD operations, email (Mailjet/SMTP), template rendering |
+| **Central infrastructure (optional)** | `CoreRedisService` + `CoreRedisPubSub` (`redis` config), `CoreS3Service` (`s3` config), `RateLimitStore`, the `installGracefulShutdown()` helper. All inert without their config — see below |
+
+### Optional central infrastructure
+
+`CoreRedisService` and `CoreS3Service` are always provided and exported by `CoreModule`, but stay
+**inert unless configured** (`redis` / `s3`, "presence implies enabled"). Their client libraries are
+OPTIONAL peer dependencies, lazy-imported at bootstrap, so a project that uses neither installs
+nothing extra. They exist so process-local state can become shared state when a deployment runs more
+than one replica: rate-limit counters, cron deduplication, GraphQL subscriptions, tenant-cache
+invalidation, Hub collectors and file storage all pick the distributed path automatically when the
+config is present, and keep their previous single-process behaviour when it is not. Inject them with
+`@Optional()` and always keep the non-configured fallback path — that is the pattern every core
+consumer follows. See `.claude/rules/configurable-features.md` for the full option reference.
 
 ## Core Modules (`src/core/modules/`)
 
@@ -98,6 +111,8 @@ Whether such a cycle throws depends on **which module the graph is entered throu
 
 Repo-wide cycles went from **10 → 5**, and **every DI token in `src/core/` now lives in an import-free leaf**. The five that remain are, per an SWC-emit audit, **not runtime cycles at all** — type-only imports that madge reports but both compilers erase (their emits are empty).
 
+Since 11.33.0 madge reports a **sixth**: `server/modules/user/user.module.ts ↔ server/modules/file/file.module.ts`. That one IS a real runtime cycle, and it is deliberate — the avatar upload needs `FileService` to reach the central file storage while `FileModule` already imported `UserModule`. It is a NestJS *module* cycle, not a TDZ hazard: both sides declare it with `forwardRef()`, and nothing on either side dereferences the other at class-definition time. It lives in `src/core/`-external `src/server/`, which vendor consumers do not receive.
+
 Both invariants are enforced by `tests/unit/import-cycle-invariants.spec.ts`, which fails if a token reappears in a `*.module.ts` / `*.service.ts` or if a leaf grows an import. That matters, because the guard below catches the *crash*, not the *disarming* of a safety property — those are different things, and only the second one is silent.
 
 | Module | Token / type leaf |
@@ -107,6 +122,7 @@ Both invariants are enforced by `tests/unit/import-cycle-invariants.spec.ts`, wh
 | `tus` | `tus.constants.ts` (`TUS_CONFIG`) |
 | `tenant` | `core-tenant.enums.ts` |
 | `auth` | `interfaces/auth-provider.interface.ts` |
+| `common/services` | `core-cron-jobs.registry.ts` (the cron infrastructure refs `CoreCronJobs` reads — `import type` only, so its emit is empty). Unlike the better-auth registry it IS barrel-exported: `setCronJobsInfrastructure()` / `getCronJobsInfrastructure()` are public, because a project may register its own connection or Redis service |
 | `common/helpers` | `id.helper.ts` (ID cluster, out of `db.helper`) + `clone.helper.ts` (`clone`/`deepFreeze`, out of `input.helper`) |
 | `common/inputs` | `FilterInput` + `CombinedFilterInput` merged into `filter.input.ts` — declaration order is load-bearing |
 | `common/decorators` | `restricted.decorator` is on **zero** cycles; its exports are hoisted `function` declarations (TDZ-immune) as defense in depth |

package/.claude/rules/configurable-features.md

@@ -248,8 +248,8 @@ This pattern is currently applied to:
 
 | Feature | Config Path | Pattern | Default Values |
 |---------|-------------|---------|----------------|
-| Legacy Auth Rate Limiting | `auth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60` |
-| BetterAuth Rate Limiting | `betterAuth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60` |
+| Legacy Auth Rate Limiting | `auth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60`. Counters live in a `RateLimitStore`: `RedisRateLimitStore` when `redis` is configured (limit enforced EXACTLY across replicas instead of `max × replicas`), else `InMemoryRateLimitStore` (previous behavior). On a Redis outage it degrades to the in-memory counter and logs once per transition — never a 500, never "allowed". `check()` / `reset()` / `clear()` are ASYNC since 11.33.0; `getStats().activeEntries` is `-1` on the Redis store |
+| BetterAuth Rate Limiting | `betterAuth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60`. Same `RateLimitStore` selection, degradation and async signatures as the Legacy Auth row (namespace `better-auth`) |
 | BetterAuth JWT Plugin | `betterAuth.jwt` | Boolean Shorthand | `expiresIn: '15m'` |
 | BetterAuth 2FA Plugin | `betterAuth.twoFactor` | Boolean Shorthand | `appName: 'Nest Server'` |
 | BetterAuth Passkey Plugin | `betterAuth.passkey` | Boolean Shorthand | `rpName: 'Nest Server'` |
@@ -265,12 +265,20 @@ This pattern is currently applied to:
 | Response Model Interceptor | `security.responseModelInterceptor` | Boolean Shorthand | `true` (enabled), `debug: false` |
 | Translate Response Interceptor | `security.translateResponseInterceptor` | Boolean Shorthand | `true` (enabled) |
 | Secret Fields Removal | `security.secretFields` | Array | `['password', 'verificationToken', ...]` |
-| Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `CoreTenantGuard.invalidateUser(userId)` / `invalidateAll()` |
+| Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `invalidateUser(userId)` / `invalidateAll()` are **instance** methods on the singleton `CoreTenantGuard` — inject it and call `this.tenantGuard?.invalidateUser(userId)`, never `CoreTenantGuard.invalidateUser(...)` (there is no static). With `redis` configured, both additionally BROADCAST the invalidation to every replica (`<keyPrefix>:tenant-cache:invalidate` pub/sub); without Redis they clear the local process only, so other replicas stay stale until `cacheTtlMs`. A received broadcast clears locally without re-publishing |
 | BetterAuth Tenant Skip | `betterAuth.skipTenantCheck` | Explicit Boolean | `true` (default). When `true` and no `X-Tenant-Id` header is sent, IAM endpoints (controller + resolver) skip `CoreTenantGuard` tenant validation. When header IS present, normal membership validation runs regardless. Set `false` for tenant-aware auth scenarios (subdomain-based, invite links, SSO per tenant) |
 | Debug Process Input | `debugProcessInput` | Explicit Boolean | `false` (default). When `true`, logs a debug message when `prepareInput()` changes the input type during `process()`. Has performance cost due to `JSON.stringify` on every `process()` call — enable only for debugging |
 | JSONTransport Production Guard | `email.smtp` with `jsonTransport` | Runtime Guard | Throws `Error` when `email.smtp` has a truthy `jsonTransport` property in `production` or `staging` environments (read from config `env` field). JSONTransport silently discards all outgoing mail — the guard prevents accidental misconfiguration that causes password-reset, 2FA, and verification emails to vanish. Use `{ jsonTransport: true }` only in CI/e2e/local environments |
 | Cookies | `cookies` | Boolean Shorthand (default true) | `true` (enabled), `exposeTokenInBody: false`. When enabled: loads `cookie-parser`, sets CORS `credentials: true`, sets signed httpOnly session cookies. When `exposeTokenInBody: true`: token stays in response body alongside cookies (for hybrid JWT+Cookie auth). JWT via `Authorization: Bearer` always works independently. **BetterAuth cookie name (since v11.27.6):** `createBetterAuthInstance()` pins `advanced.useSecureCookies: false` so BetterAuth's native handlers read the same UNPREFIXED `<cookiePrefix>.session_token` the helper writes (fixes a `401` split-brain on 2FA/passkey/`/token`); the `Secure` attribute is still applied on an `https://` baseURL via `advanced.defaultCookieAttributes`. Opt back into the `__Secure-` prefix with `betterAuth.options.advanced.useSecureCookies: true` only when BetterAuth manages cookies entirely |
 | CORS | `cors` | Boolean Shorthand | `enabled: true`, `allowAll: false`, `deriveAppUrl: true`. Origins come from `appUrl`/`baseUrl`, resolved by the shared `resolveServerUrls()` helper (`cookies.helper.ts`) that ALL three CORS layers use (GraphQL, REST, BetterAuth `trustedOrigins`) — they can no longer drift. `appUrl` resolution: explicit → derived from a **host-split** localhost `baseUrl` (its `api.` label strips to a sibling host: `https://api.crm.localhost` → `https://crm.localhost`, as served by `lt dev up`; the port is preserved) → localhost default (`http://localhost:3001`, only for `env: local`/`ci`/`e2e` with a **port-split** localhost `baseUrl` — one host, API `:3000`, app `:3001`; `https://api.localhost` strips to the bare `localhost` the API already answers on and is therefore a port split, not a host split) → derived from `baseUrl` by stripping a leading `api.` label (`https://api.example.com` → `https://example.com`). **Security:** the derived origin receives credentialed CORS; set `deriveAppUrl: false` when the apex domain is not trusted, then list the frontend origin via `appUrl`/`allowedOrigins` (a host-split localhost `baseUrl` then falls back to the localhost default). The derivation never yields a bare TLD (`https://api.dev` unchanged) and never emits the opaque `null` origin (non-http(s) `baseUrl` passes through verbatim). `allowAll: true` mirrors the request origin for REST/GraphQL, but BetterAuth's `trustedOrigins` still resolve to `[appUrl]` (+ passkey origins) — an origin check has no "allow everything" mode, so a separately hosted frontend must appear in `appUrl`/`allowedOrigins` (or set `betterAuth.trustedOrigins` explicitly). `enabled: false` disables CORS on all layers including BetterAuth (`trustedOrigins: []`, which still trusts BetterAuth's own `baseURL`). Explicit `betterAuth.trustedOrigins` always takes precedence |
+| Central Redis | `redis` | Boolean Shorthand + Presence Implies Enabled | `host: 'localhost'`, `port: 6379`, `db: 0`, `keyPrefix: <package.json name, slugified>` (per APPLICATION, not per framework — a constant default silently collides when two apps share one Redis; set it explicitly when sharing IS intended); `url` (takes precedence over host/port/db/credentials), `username`/`password`, `options` (passed to the ioredis constructor). `true` / `{}` enables with defaults; `{ enabled: false }` pre-configures without enabling; **absent = every consumer keeps its process-local fallback** (that fallback is the whole backward-compatibility story of 11.33.0). Requires the OPTIONAL peer `ioredis` — configured-but-missing **fails the boot** with a named error rather than crashing on first use. `keyPrefix` is applied by the framework per key, NOT as ioredis `keyPrefix` (that would collide with BullMQ's own prefix). One `CoreRedisService` serves all features: shared client (`getClient()`), one cached subscriber (`getSubscriber()` — a subscribing client cannot run commands), dedicated connections (`createClient(label)`); all are tracked and quit on shutdown. Switches on automatically: exact cross-replica rate limits via `RedisRateLimitStore` (see the Legacy Auth / BetterAuth / AI rate-limit rows), cron dedup (see Cron Job Deduplication row), `CoreRedisPubSub` as `PUB_SUB` for cluster-wide GraphQL subscriptions (**payloads must be JSON-serializable — `Date`, class instances, `Map`/`Set`, `undefined` do not survive**), tenant-cache invalidation broadcast, Hub collector mirroring, MCP session registry (turns a wrong-replica request from a misleading `404` into a `409` — `/ai/mcp` still REQUIRES sticky sessions, sessions are not portable) |
+| File Access Roles | `file.downloadRoles`, `file.uploadRoles`, `file.deleteRoles` | Config-Driven Role List | `[RoleEnum.ADMIN]` each. **These are the only breaking change a single-replica project gets in 11.33.0** — six members moved from `@Roles(S_EVERYONE)` to these knobs: `GET /files/id/:id`, `GET /files/:filename` and `getFileInfo` (`downloadRoles`), `uploadFile` / `uploadFiles` (`uploadRoles`), `deleteFile` (`deleteRoles`). Plain role STRINGS, not `RoleEnum` members, so project roles work (`['company-admin', 'editor']`). Applied at boot by `applyFileRoles()` via `Reflect.defineMetadata('roles', …)` on the base-class methods — the same runtime mechanism `CorePermissionsModule` uses, because the value is only known from config. **`[]`, a non-array, or an array holding a non-string is REJECTED with a warning and the default applies** — an all-empty role set reads to the guards as "no roles required" and would OPEN the route, the exact opposite of the intent. **ADMIN is always unioned in**: both `CoreFileController` and `CoreFileResolver` carry a class-level `@Roles(RoleEnum.ADMIN)` and the guards UNION class + handler metadata, so these knobs can grant but never exclude admins. Both classes also carry `@SkipTenantCheck()` — GridFS and the S3 metadata collection are reached outside Mongoose, so `mongooseTenantPlugin` never scopes them and a role name alone cannot express a per-tenant rule; roles resolve against `user.roles`, never `membership.role`. **A subclass that OVERRIDES a member opts out permanently** (decorator metadata lives on the function object, and an override is a different function) — inherit the member instead. Roles are the coarse filter only; per-file rules belong in `CoreFileService.checkRights()`, which now receives `currentUser` and can read raw metadata via `getRawFileInfo()`. Implementation: `src/core/modules/file/file-roles.helper.ts` (`FILE_ROLE_DEFAULTS`, `applyFileRoles`) |
+| TUS Roles | `tus.roles` | Config-Driven Role List | `[RoleEnum.S_USER]` (was `S_EVERYONE` — breaking). A TUS upload writes into the SAME store the download routes guard, and the termination extension (on by default) can delete from it, so anonymous writes into a store only privileged callers may read is the wrong way round. Applied by `TusModule.applyRoles()` onto the registered controller class **and** onto `handleTus` / `handleTusWithId`. Same rejection rule as the file roles: `[]` / non-array / non-string → warning + `DEFAULT_TUS_CONFIG.roles`. **`OPTIONS` is deliberately exempt**: `handleTusOptions` / `handleTusOptionsWithId` keep their own handler-level `@Roles(RoleEnum.S_EVERYONE)`, because that is the CORS preflight — browsers send it WITHOUT credentials, and it returns server capabilities only. Gating it would make every browser upload fail before the first byte. `CoreTusController` also carries `@SkipTenantCheck()`. A custom controller is covered as long as it INHERITS the handlers; one that re-declares `@All()` / `@Roles()` carries its own metadata and thereby opts out — the documented way to hard-code a policy config must not be able to change. **Set `roles: [RoleEnum.S_EVERYONE]` explicitly if you accept attachments on a public form.** Implementation: `src/core/modules/tus/tus.module.ts`, `src/core/modules/tus/interfaces/tus-config.interface.ts` |
+| File Storage | `file.storage` + `file.storageDir` + `s3` | Explicit Enum with DERIVED default | `'filesystem' \| 'gridfs' \| 's3'`. **Unset → derived**, most capable first: `'s3'` when `s3.bucket` is set, else `'gridfs'` when `mongoose.uri` is set, else `'filesystem'`. **Set → enforced**: an unavailable store FAILS THE BOOT (`assertFileStorageAvailable()`), it never falls back — a silent fallback puts files in a store the operator does not believe they are in, unrecoverably. A DERIVED driver is enforced too (`s3.bucket` set but `s3Service` not forwarded to `super()` → boot error). Metadata always lives in MongoDB whichever driver holds the bytes (`fs.files` / `s3-files` / `filesystem-files`) — it has to stay queryable for `findFileInfo()` and `checkRights()`. Reads consult ALL stores so switching drivers is forward-only with no migration; writes go to the active driver only. `'filesystem'` is pod-local: not shared between replicas, lost on restart unless `storageDir` is a mounted volume. `s3`: `bucket` (required — the one thing S3 cannot default, hence the eligibility test), `region: 'us-east-1'`, `forcePathStyle: false`, `stagingBucket: bucket`, `presignedDownloads: false` (`true`/`{}` → `expiresInSeconds: 300`), `endpoint` (MinIO/RustFS), `accessKeyId`/`secretAccessKey` (omit → AWS default credential chain), `enabled: false` to pre-configure. Requires the OPTIONAL peer `@aws-sdk/client-s3`, plus `@aws-sdk/s3-request-presigner` for presigned downloads. `presignedDownloads` makes `GET /files/id/:id` answer `302` to a time-limited S3 URL instead of streaming — the URL is a bearer capability, authorized once at issue time. The resolved driver is logged at boot (`[CoreFileStorage] File storage: …`) |
+| TUS S3 Staging | `tus.s3Staging` | Explicit Boolean (default ON when S3 configured) | `true` when `s3` is configured, otherwise inert. Stages in-progress uploads in `s3.stagingBucket` via `@tus/s3-store` instead of `tus.uploadDir` on local disk, so resumable uploads survive replica restarts and need no sticky sessions. Set `false` to force local disk. Missing OPTIONAL peer `@tus/s3-store` → warning + fall back to local disk (NOT a boot failure). **Give the staging bucket a lifecycle rule expiring incomplete multipart uploads** — the framework's own expiration cleanup is skipped in S3 mode (S3 is the right place for that policy), so aborted uploads otherwise accumulate parts nothing removes |
+| Cron Job Deduplication | per job: `distributed` in `CronJobConfig` | Explicit Boolean | **`true` when `redis` is configured, otherwise `false`** — a single-replica project that upgrades must not silently gain a `cron-locks` collection, a lease write per tick, and a new way for a tick to be skipped. A Redis-less multi-replica fleet opts in per job with `distributed: true` (MongoDB lease). Mechanism: BullMQ job scheduler when Redis + the OPTIONAL peer `bullmq` are present AND `cronTime` is a string without `utcOffset`; otherwise local timer + lease (Redis `SET NX`, else a TTL-indexed `cron-locks` document). Tick lease TTL 3600 s. **Leases fail open** — an unreachable lease store runs the tick everywhere rather than stopping all scheduled work fleet-wide. **`runOnInit` (default `true`) deduplicates over a FIXED per-job key with a 300 s TTL**, because replicas do not share a boot instant: replicas booting within 5 min run the startup tick once between them, and a replica restarting inside that window SKIPS its startup tick — set `distributed: false` on jobs whose `runOnInit` work is per-process (warming a process-local cache). No constructor change needed: `CoreModule` fills `core-cron-jobs.registry.ts` via `CoreCronJobsInitializer` and `CoreCronJobs` reads it lazily; explicit `{ connection, redisService }` in `CoreCronJobsOptions` wins. With neither source it warns once and every replica runs every tick |
+| Shutdown Delay | `shutdownDelayMs` | Numeric Sentinel — Family B (`0` = off) | `0` (default, no delay, no log). Waits N ms **in the SIGTERM/SIGINT handler, before `close()` is entered**, so a load balancer can finish deregistering while the instance is still fully healthy. NOT a lifecycle hook: `close()` runs `onModuleDestroy` → `beforeApplicationShutdown` → dispose → `onApplicationShutdown`, so a delay in `beforeApplicationShutdown` would wait with every module already torn down while the socket still accepts — worse than no delay. **Requires `installGracefulShutdown(app)` in main.ts, which REPLACES `server.enableShutdownHooks()`** — keeping both makes Nest close the app in parallel with the wait, so the delay silently never happens. At delay `0` the helper IS `enableShutdownHooks()`. **Keep the value well below the orchestrator grace period AND leave room for the drain that follows**: Compose `stop_grace_period` 10s, Kubernetes `terminationGracePeriodSeconds` 30s, and `installProcessDiagnostics()` force-exits after 30s — exceed any and the process is SIGKILLed mid-wait with no hook running. Warns above `10000`, capped at `60000`. Non-numeric / negative values behave like `0` |
+| Trust Proxy | `trustProxy` | Explicit Value (pass-through, Express default) | `false` (Express's own default — the forwarded chain is not trusted). Passed verbatim to `app.set('trust proxy', …)` by `CoreTrustProxyInitializer`, a `CoreModule` provider, so a consumer inherits it by upgrading and needs no `main.ts` edit. Accepts `false` / a hop count (`1`, `2`) / `'loopback'` / a subnet list — **not** Express's predicate function: the value must survive `NEST_SERVER_CONFIG` / `NSC__*` (JSON) and the ConfigService deep clone. **This is what makes `request.ip` correct, and every IP-keyed rate limit depends on it**: unset behind Caddy/nginx/an ingress, `req.ip` is the PROXY address for every request, so all clients share ONE bucket and `auth.rateLimit.max` throttles everybody at once — exactly fleet-wide once `redis` is configured. Trusting MORE hops than exist is the opposite failure: a client prepends its own header entry and picks a fresh bucket per request. Applied at module init (inside `app.init()`/`listen()`, i.e. AFTER `main.ts`), so a configured value wins over a hand-written `app.set()`; an UNSET value is never applied, which keeps `app.set('trust proxy', fn)` in `main.ts` available as the escape hatch for the predicate form. **Unset + an IP-keyed limiter enabled (`auth.rateLimit` / `betterAuth.rateLimit`) logs a boot warning naming the shared-bucket consequence**; `trustProxy: false` is the explicit "nothing proxies me" answer that silences it. The AI limiter keys on the user id and is unaffected |
 | AI Assistant | `ai` | Presence Implies Enabled | Core: `maxIterations: 5`, `defaultMode: 'auto'` (or `'plan'`), `rateLimit` (presence implies enabled: `max: 20`, `windowSeconds: 60`), `systemPrompt`, `documentation` (injected into the system prompt), `encryptionSecret`. **DB-backed LLM connections** (`aiConnections`, admin CRUD) with AES-256-GCM-encrypted API keys (`AiCryptoService`, secret from `ai.encryptionSecret` / `NSC__AI__ENCRYPTION_SECRET` / `SECRETS_ENCRYPTION_KEY`; `apiKeyEncrypted` is a global `secretFields` entry, never returned — only `hasApiKey`); optional `defaultConnection` one-time seed. **Provider abstraction** (`ILlmProvider`, default `OpenAiCompatibleProvider` for any OpenAI-compatible endpoint via `fetch`; per-connection `supportsNativeTools`/`supportsJsonResponse` capabilities, emulated tool calling when native tools are unavailable). **Tool registry** (`AiToolRegistry`, tools self-register, role-filtered; tools may be `mutating`/`destructive` and define `authorize()` for pre-flight data-level checks). **Plan mode** (`input.mode: 'plan'`): full plan → pre-flight authorize ALL steps → all-or-nothing execution with a translated (de/en) error when any step is not permitted. **Confirmation policy**: `confirmation.mutating: { default, enforced }` + client `input.requireConfirmation` (ignored when enforced); `destructive` always confirms. **Client metadata** (`input.metadata`: URL/nav/console logs, untrusted+capped). **Multi-turn conversations** (`aiConversations`, owner-scoped). **SSE streaming** (`POST /ai/stream`). **Audit** (`audit: false` → persist to `aiInteractions`, admin-readable). **Token budgets** (`budget: { period: 'day'|'month'|'none', user: { maxTokens?, maxPrompts? }, tenant: { maxTokens?, maxPrompts? } }`, requires audit): per-user AND per-tenant limits with config defaults; admins override per user/tenant at runtime (`aiBudgetLimits`, `CoreAiBudgetService`). Resolution: override → default → unlimited (missing/0 = unlimited). Enforced before the run (HTTP 429 + translated). Each response carries a compact `budget` summary (promptTokens, usedTokens, remainingTokens, resetAt); full breakdown via `aiUsage` query / `GET /ai/usage`. **Self-optimizing prompts**: the system prompt is assembled from keyed fragments (`CoreAiPromptBuilderService` ships built-in defaults; works with zero rows). Admin-editable overrides per slot (`aiSlots`, admin CRUD, `/ai/slots`) scoped by `key`/`locale`/`capability`/`tenantId`, with tenant override/reset semantics and placeholder tokens resolved at run time via the placeholder registry. **Governed learning loop** (`promptLearning: { enabled: true, autoApply: false }`): tool errors record `suggested` hints (`aiPromptHints`, admin CRUD, `/ai/prompt-hints`) that only reach the prompt once admin-approved (or auto-approved when `autoApply`); hints only ADD guidance, never relax permissions. **Context window** (`contextWindow`, default 8192; auto-detected per connection via `ILlmProvider.detectContextWindow()` — Ollama `/api/show` probe / known-model table / Claude alias — and persisted): per-user/session history is trimmed (oldest non-system turns dropped, last truncated) and tool-results capped to `maxToolResultChars` (default 12000) so a session never overflows the model. A connection's window can be seeded via `ai.defaultConnection.contextWindow` (validated: a non-positive/non-integer value is dropped with a warning). **Capability drift check** (`capabilityDriftCheck`, default `false`): opt-in boot self-check that probes each enabled connection with an EXPLICIT `supportsNativeTools`/`supportsJsonResponse` (built with those flags cleared so the endpoint is actually re-probed) and logs a warning on mismatch — the stored value is never changed. OFF by default because it makes outbound calls to the LLM endpoints on every boot; also skipped in the ci/e2e runners. **Deferred tool schemas** (`deferToolSchemas`, default `false`): the system-prompt tool catalog then lists only tool NAMES + descriptions instead of full JSON schemas, and the model fetches a schema on demand via the built-in `search_tools` meta-tool — with a large registry the schemas alone can dominate a small context window. `deferToolSummaryChars` (default `0` = untruncated) additionally caps each description in that DEFERRED catalog: whole sentences up to the cap (always at least the first), word-boundary cut when the first sentence already exceeds it, and a `…` marker appended ON TOP of the cap. The default of `0` keeps the saving opt-in, so enabling `deferToolSchemas` alone never changes what a description says; set roughly 200–400 alongside it to actually reclaim the context. Both apply to EMULATED providers only — a connection with `supportsNativeTools: true` receives every full description + schema via `buildToolSchemas()` regardless, so truncation and the banner are skipped there rather than asserting a cut the tool payload contradicts. The omitted tail is where preconditions and role restrictions usually live — the catalog banner tells the model to fetch the full text via `search_tools` first, but this is model GUIDANCE only: authorization is enforced server-side by the registry's role filter (`forUser()`), the execution-time re-check, and the `mutating`/`destructive` flags read by the confirmation gate — never by what the catalog shows. (`AiTool.authorize()` runs in PLAN MODE only; in auto mode and over MCP, data-level checks must live inside `execute()`.) **MCP server** (`mcp: false` → `/ai/mcp` Streamable HTTP, Bearer auth, lazy `@modelcontextprotocol/sdk`; `mcp: { oauth: true, oauthSecret }` adds OAuth 2.1 — HMAC tokens + PKCE S256 + dynamic registration via `mountAiMcpOAuth(app)` in main.ts). Overrides via `CoreModule.forRoot(env, { ai: { budgetService, connectionResolver, connectionService, controller, conversationService, interactionService, mcpClientService, modeService, placeholderRegistry, preferenceService, promptBuilder, promptHintService, promptService, resolver, service, slotService, toolGrantService, toolPolicyService } })` |
 
 ## Module Override Pattern (via `ICoreModuleOverrides`)

package/.claude/rules/testing.md

@@ -6,14 +6,73 @@
 
 | Runner | Config | Test files | Needs MongoDB |
 |--------|--------|-----------|:-------------:|
-| Unit | `vitest.config.ts` | `src/**/*.spec.ts`, `tests/unit/**/*.spec.ts` | No |
+| Unit | `vitest.config.ts` | `tests/unit/**/*.spec.ts` | No |
 | E2E | `vitest-e2e.config.ts` | `tests/**/*.e2e-spec.ts`, `tests/stories/**/*.story.test.ts` | Yes |
 
+**Test files NEVER live in `src/`.** Not a style preference — `src/` is this framework's shipping
+artifact: `package.json` → `files` ships all of `src` recursively into the npm tarball, and
+vendor-mode consumers copy `src/core/` into their own tree as first-class project code (the CLI's
+`convertCloneToVendored` applies no spec filter). A co-located spec therefore reaches every consumer
+as a test file they neither run nor maintain, re-delivered on every core update. Co-location is a
+fine default for an application; for a library whose `src/` IS the delivery, separation wins.
+
+Enforced twice: the unit runner's glob no longer looks at `src/` at all, and
+`tests/unit/test-file-placement.spec.ts` fails on any `.spec.ts`/`.test.ts` found there — so a
+misplaced test surfaces as a failure rather than as silently skipped coverage.
+
+| Kind | Where | Suffix |
+|------|-------|--------|
+| Unit | `tests/unit/` | `*.spec.ts` |
+| E2E / integration | `tests/` | `*.e2e-spec.ts` |
+| Story (e2e-grade) | `tests/stories/` | `*.story.test.ts` |
+| Type-only (compiled, never run) | `tests/types/` | `*.type-test.ts` |
+
 A file matching neither pattern would run nowhere. `tests/unit/test-file-routing.spec.ts` asserts
 that every `*.spec.ts` / `*.test.ts` in the repo is claimed by **exactly one** runner, so a
 mis-named suite fails the build instead of silently passing. Type-only tests
 (`tests/types/*.type-test.ts`) are compiled by `pnpm run test:types`, never executed.
 
+## Infrastructure containers (Redis + S3)
+
+**Seven** e2e suites talk to a **real** Redis and/or a **real** S3-compatible store rather than a
+mock, and they **fail loudly** when it is missing — a silently skipped infrastructure test is how an
+untested driver ships:
+
+| Suite | Needs |
+|-------|-------|
+| `tests/redis-infra.e2e-spec.ts` | Redis |
+| `tests/redis-consumers.e2e-spec.ts` | Redis |
+| `tests/multi-replica.e2e-spec.ts` | Redis |
+| `tests/s3-infra.e2e-spec.ts` | S3 |
+| `tests/file-storage-s3.e2e-spec.ts` | S3 |
+| `tests/redis-s3-bootstrap.e2e-spec.ts` | Redis + S3 |
+| `tests/graceful-shutdown.e2e-spec.ts` | Redis + S3 |
+
+`tests/global-setup.ts` starts both containers automatically, so `pnpm test` works from a clean
+machine with no manual docker command. It is idempotent (a running container is reused) and never
+fatal: without Docker every other suite still runs, and the seven above report their own actionable
+error.
+
+```bash
+pnpm run test:infra          # start + wait for readiness (also runs automatically)
+pnpm run test:infra:status   # what is running
+pnpm run test:infra:down     # stop and remove
+```
+
+| | Redis | S3 (RustFS) |
+|---|---|---|
+| Port | 6380 (6379 is an auth-protected TurboOps Redis on lt dev machines) | 9102 |
+| Container | `nest-server-2985-redis` | `nest-server-2985-rustfs` |
+
+**CI provisions its own** containers in `.github/workflows/*.yml` and sets `LT_TEST_INFRA=0` so the
+automatic start stays out of the way. Same images, same ports — only who starts them differs. Set
+`LT_TEST_INFRA=0` locally too if you want to manage them yourself.
+
+**Bucket cleanup:** every suite that creates a bucket names it per run and removes it in `afterAll`
+via `tests/helpers/s3-test-cleanup.ts`. Emptying and deleting belong together — a bucket cannot be
+deleted while it holds objects — which is why that lives in one helper rather than per suite. Before
+it existed, two empty buckets leaked into the store per run.
+
 ## Running Tests
 
 ```bash
@@ -49,6 +108,47 @@ pnpm run test:cleanup
 - DB lifecycle (`tests/db-lifecycle.reporter.ts`): run passes → DB dropped immediately + stale run DBs from crashed/failed runs collected; run fails → DB kept for debugging. Additionally `tests/global-setup.ts` runs a **startup sweep** (shared `isStaleTestDb()` predicate, dead-PID/age guarded) — leftovers are removed when the NEXT run starts, which survives SIGKILL (check watchdog) and `--reporter` CLI overrides. An externally set `MONGODB_URI` (CI) opts out of the scheme.
 - Run governor (`tests/e2e-run-slots.ts`): machine-wide slot dir (`<tmpdir>/lt-e2e-run-slots`) caps concurrent e2e runs across ALL lt projects/sessions (default 2 on ≥8 cores). Further runs wait, logging `[e2e-governor] waiting…` every 15s (keeps the check watchdog fed — a queued run is NOT hung). The e2e config counts foreign slots at load time and drops to low-resource mode (reduced forks, raised timeouts) when another run is active — deterministic, unlike the lagging 1-min load average (kept as second signal). Knobs: `LT_E2E_MAX_RUNS` (0 disables), `LT_E2E_SLOT_DIR`, `LT_E2E_SLOT_TIMEOUT` (fail-open).
 - `retry: 2` (e2e) is deliberate — with `retry: 5`, one spec file with broken app/socket state ground through 6 attempts × 30s timeout × 22 tests ≈ an hour at 0% CPU (looked like a deadlock; the check watchdog killed it). Never raise retry to paper over contention.
+- Infrastructure containers (E2E only, the **seven** specs listed under "Infrastructure containers"
+  above) round-trip against a REAL Redis and/or a REAL S3-compatible store.
+  `redis-s3-bootstrap` boots the assembled `CoreModule` with both
+  configured — the only test that covers the WIRING, which fakes and directly-constructed
+  services cannot: an unresolvable provider or a lifecycle hook that throws on a real
+  connection would pass every other spec and fail on a consumer's first `nest start`. `multi-replica` is the acceptance test for the
+  distributed features: it builds TWO independent service instances sharing one Redis and
+  asserts the properties a second replica must preserve — a scheduled tick and a startup tick
+  each run exactly once, one rate limit is enforced instead of one per replica, and a severed
+  Redis still yields a decision instead of an error. Single-instance specs against fakes cannot
+  show any of that: a limiter counting per process, or a lease key differing per instance,
+  passes them and fails here. `redis-consumers` covers the framework's own Redis consumers seen
+  from two replicas, `file-storage-s3` runs `CoreFileService` against a real bucket, and
+  `graceful-shutdown` needs real connections for `installGracefulShutdown()` to close.
+  Five of the seven preflight the connection in `beforeAll` and throw a written diagnosis —
+  `redis-infra`, `s3-infra` and `multi-replica` quote the full `docker run` line, `redis-consumers`
+  and `file-storage-s3` name the port and how to start it. So a forgotten container is a ~2s clear
+  error instead of a 43s opaque `MaxRetriesPerRequestError`. The other two fail fast without a
+  custom message: `graceful-shutdown` probes with `connectTimeout: 2000` /
+  `maxRetriesPerRequest: 1` and lets the raw connect error surface, and `redis-s3-bootstrap` has no
+  separate probe at all — its `beforeAll` IS the boot.
+
+  ```bash
+  docker run -d --name nest-server-2985-redis -p 6380:6379 redis:7.4-alpine
+  docker run -d --name nest-server-2985-rustfs -p 9102:9000 -e RUSTFS_ROOT_USER=rustfs -e RUSTFS_ROOT_PASSWORD=rustfs-secret -e RUSTFS_VOLUMES=/data rustfs/rustfs:1.0.0-rc.1 server /data
+  ```
+
+  Both tags are pinned, and these hints must stay identical to the tags in
+  `scripts/test-infra.mjs` / `.github/actions/test-infra/action.yml`. `containerMatches()` compares
+  the running container's image against the pinned one, so a hint that says `:latest` starts a
+  container the next `pnpm test` tears down and recreates.
+
+  | Service | Port | Overridable via |
+  |---------|------|-----------------|
+  | Redis | 6380 | `REDIS_HOST`, `REDIS_PORT` |
+  | RustFS (S3) | 9102 | `S3_ENDPOINT`, `S3_ACCESS_KEY`, `S3_SECRET_KEY` |
+
+  **Why 6380 and not 6379:** on lt dev machines 6379 is occupied by an auth-protected TurboOps
+  Redis. Binding the test container to 6380 keeps the two apart — no auth setup, no cross-wiring.
+  CI (`.github/workflows/build.yml` / `publish.yml`) maps the same ports and waits for readiness
+  before installing dependencies.
 - Test helper: `src/test/test.helper.ts`
 - Coverage: Collected from `src/**/*.{ts,js}`. The two runners are separate vitest processes, so
   they write separate reports (`coverage/unit`, `coverage/e2e`) rather than overwriting each other.

package/CLAUDE.md

@@ -142,6 +142,7 @@ pnpm run reinit         # Clean reinstall + tests + build
 - `src/core/modules/` - Auth, BetterAuth, ErrorCode, File, HealthCheck, Hub, Migrate, Permissions, SystemSetup, Tus, User
   - **Hub** - Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 16 panels, runtime collectors, mailbox, admin actions). See `src/core/modules/hub/README.md`.
   - **Permissions** - ADMIN-gated security-map report (routes + roles + `@Restricted` fields); also surfaced in the Hub's "Routes / Permissions" panel.
+- **Optional central infrastructure** (11.33.0+) - `CoreRedisService` (`redis` config) and `CoreS3Service` (`s3` config) turn process-local state into shared state for multi-replica deployments: rate-limit counters, cron deduplication, GraphQL subscriptions, tenant-cache invalidation, Hub collectors, file storage (`file.storage: 's3'`; the driver is otherwise derived — S3 → GridFS → filesystem — and an unavailable one fails the boot rather than falling back) and TUS staging. Both are inert without their config, and their client libraries are **optional peer dependencies** (`ioredis`, `bullmq`, `@aws-sdk/client-s3`, `@aws-sdk/s3-request-presigner`, `@tus/s3-store`) — a project that uses neither installs nothing extra. When adding a distributed feature, always keep the non-configured fallback path.
 
 See `.claude/rules/architecture.md` for detailed documentation.
 See [`docs/REQUEST-LIFECYCLE.md`](docs/REQUEST-LIFECYCLE.md) for the complete request lifecycle, security architecture, and interceptor/decorator reference.
@@ -236,6 +237,10 @@ file is missing (default: tolerate with a warning) — see `src/core/modules/mig
 
 1. **All code, comments, documentation in English**
 2. **Run tests before completing changes** - `pnpm test`
+2b. **Never put test files in `src/`** — unit tests go to `tests/unit/*.spec.ts`, e2e to
+   `tests/*.e2e-spec.ts`, stories to `tests/stories/*.story.test.ts`. `src/` ships in the npm
+   tarball and is copied verbatim into vendor-mode consumer projects, so a co-located spec becomes
+   part of THEIR codebase. Enforced by `tests/unit/test-file-placement.spec.ts`.
 3. **Follow existing patterns** for consistency
 4. **Never store S_ roles** in user.roles array
 5. **Use Module Inheritance Pattern** for core modules

package/FRAMEWORK-API.md

@@ -1,6 +1,6 @@
 # @lenne.tech/nest-server — Framework API Reference
 
-> Auto-generated from source code on 2026-07-24 (v11.32.3)
+> Auto-generated from source code on 2026-08-11 (v11.33.0)
 > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
 
 ## CoreModule.forRoot()
@@ -29,6 +29,7 @@
   - `version?`: `string | undefined` — Semantic version of the running build (e.g. from package.json / meta.json).
   - `errorCode?`: `IErrorCode | undefined` — Configuration for the error code module
   - `execAfterInit?`: `string | undefined` — Exec a command after server is initialized
+  - `file?`: `IFileConfig | undefined` — Configuration of the file module: where the bytes live (`storage`) and who
   - `filter?`: `{ maxLimit?: number; } | undefined` — Filter configuration and defaults
   - `graphQl?`: `false | { driver?: ApolloDriverConfig; enableSubscriptionAuth?: boolean; maxC...` — Configuration of the GraphQL module
   - `healthCheck?`: `{ configs?: { build?: { enabled?: boolean; }; database?: { enabled?: boolean;...` — Whether to activate health check endpoints
@@ -42,11 +43,15 @@
   - `multiTenancy?`: `IMultiTenancy | undefined` (default: `undefined (disabled)`) — Multi-tenancy configuration for tenant-based data isolation.
   - `permissions?`: `boolean | IPermissions | undefined` (default: `undefined (disabled)`) — Permissions report module (development tool).
   - `port?`: `number | undefined` — Port number of the server
+  - `redis?`: `boolean | IRedisConfig | undefined` (default: `undefined (disabled)`) — Optional central Redis connection used by all distributed features
+  - `s3?`: `IS3Config | undefined` (default: `undefined (disabled)`) — Optional central S3-compatible object storage (AWS S3, MinIO, ...).
   - `security?`: `{ checkResponseInterceptor?: boolean | { checkObjectItself?: boolean; debug?:...` — Configuration for security pipes and interceptors
   - `sha256?`: `boolean | undefined` — Whether to enable verification and automatic encryption for received passwords that are not in sha256 format
+  - `shutdownDelayMs?`: `number | undefined` (default: `0 (no delay)`) — Delay in milliseconds between receiving a shutdown signal and starting the
   - `staticAssets?`: `{ options?: ServeStaticOptions; path?: string; } | undefined` — Configuration for useStaticAssets
   - `systemSetup?`: `ISystemSetup | undefined` — System setup configuration for initial admin creation.
   - `templates?`: `{ engine?: string; path?: string; } | undefined` — Templates
+  - `trustProxy?`: `string | number | boolean | string[] | undefined` (default: `false (Express default — the forwarded chain is not trusted)`) — Express `trust proxy` setting — how far up the `X-Forwarded-For` chain this app believes.
   - `tus?`: `boolean | ITusConfig | undefined` — TUS resumable upload configuration.
 
 ### IBetterAuth (type alias: IBetterAuthWithoutPasskey | IBetterAuthWithPasskey)
@@ -145,6 +150,56 @@ When `passkey` is enabled, `trustedOrigins` is required (compile-time enforcemen
   - `supportsNativeTools?`: `boolean | undefined` — Native function/tool-calling support. Omit to auto-detect by probing the
   - `supportsVision?`: `boolean | undefined` — Whether the model supports image input.
 
+### IFileConfig
+
+  - `deleteRoles?`: `string[] | undefined` (default: `['admin']`) — Roles allowed to DELETE files (`deleteFile` mutation).
+  - `downloadRoles?`: `string[] | undefined` (default: `['admin']`) — Roles allowed to DOWNLOAD files and read file info
+  - `storage?`: `"filesystem" | "gridfs" | "s3" | undefined` (default: `derived — see above`) — Storage driver for CoreFileService. Three equivalent options:
+  - `storageDir?`: `string | undefined` (default: `'uploads/files'`) — Directory for the `'filesystem'` storage driver.
+  - `uploadRoles?`: `string[] | undefined` (default: `['admin']`) — Roles allowed to UPLOAD files (`uploadFile` / `uploadFiles` mutations).
+
+### IRedisConfig
+
+  - `db?`: `number | undefined` (default: `0`) — Redis database index
+  - `enabled?`: `boolean | undefined` (default: `true (when config object is present)`) — Whether Redis is enabled.
+  - `host?`: `string | undefined` (default: `'localhost'`) — Redis host
+  - `keyPrefix?`: `string | undefined` (default: `the slugified `name` from package.json, or 'nest-server' if unreadable`) — Prefix prepended to every framework-managed Redis key
+  - `options?`: `Record<string, unknown> | undefined` (default: `undefined`) — Additional ioredis options passed through to the client constructor
+  - `password?`: `string | undefined` (default: `undefined (no auth)`) — Redis password
+  - `port?`: `number | undefined` (default: `6379`) — Redis port
+  - `url?`: `string | undefined` (default: `undefined`) — Full Redis connection URL (e.g. 'redis://user:pass@host:6379/0').
+  - `username?`: `string | undefined` (default: `undefined`) — Redis username (Redis 6+ ACL)
+
+### IS3Config
+
+  - `accessKeyId?`: `string | undefined` (default: `undefined`) — Access key ID.
+  - `autoCreateBucket?`: `boolean | undefined` (default: `false`) — Create the configured buckets at startup when they do not exist.
+  - `bucket`: `string` — Bucket for files stored via CoreFileService
+  - `enabled?`: `boolean | undefined` (default: `true (when config object is present)`) — Whether S3 is enabled.
+  - `endpoint?`: `string | undefined` (default: `undefined`) — Custom endpoint URL for S3-compatible services (MinIO, RustFS, ...).
+  - `forcePathStyle?`: `boolean | undefined` (default: `false`) — Use path-style addressing (required by most self-hosted S3 services).
+  - `presignedDownloads?`: `boolean | { expiresInSeconds?: number; } | undefined` (default: `false`) — Serve downloads as presigned URL redirects instead of streaming
+  - `region?`: `string | undefined` (default: `'us-east-1'`) — AWS region
+  - `secretAccessKey?`: `string | undefined` (default: `undefined`) — Secret access key.
+  - `stagingBucket?`: `string | undefined` (default: `same as `bucket``) — Bucket used as staging area for resumable TUS uploads.
+
+### ITusConfig
+
+  - `allowedHeaders?`: `string[] | undefined` (default: `[] (no additional headers needed)`) — Additional allowed HTTP headers for TUS requests (beyond
+  - `allowedTypes?`: `string[] | undefined` (default: `undefined (all types allowed)`) — Allowed MIME types for uploads.
+  - `checksum?`: `boolean | undefined` (default: `true`) — Checksum extension configuration.
+  - `concatenation?`: `boolean | undefined` (default: `true`) — Concatenation extension configuration.
+  - `creation?`: `boolean | ITusCreationConfig | undefined` (default: `true`) — Creation extension configuration.
+  - `creationWithUpload?`: `boolean | undefined` (default: `true`) — Creation With Upload extension configuration.
+  - `enabled?`: `boolean | undefined` (default: `true (enabled by default)`) — Whether tus uploads are enabled.
+  - `expiration?`: `boolean | ITusExpirationConfig | undefined` (default: `{ expiresIn: '24h' }`) — Expiration extension configuration.
+  - `maxSize?`: `number | undefined` (default: `50 * 1024 * 1024 * 1024 (50 GB)`) — Maximum upload size in bytes
+  - `path?`: `string | undefined` (default: `'/tus'`) — Base path for tus endpoints
+  - `roles?`: `string[] | undefined` (default: `['s_user']`) — Roles allowed to use the tus endpoints (create, write, read offset, terminate).
+  - `s3Staging?`: `boolean | undefined` (default: `true (when S3 is usable)`) — Stage upload chunks in the configured S3 bucket (`IServerOptions.s3`,
+  - `termination?`: `boolean | undefined` (default: `true`) — Termination extension configuration.
+  - `uploadDir?`: `string | undefined` (default: `'uploads/tus'`) — Directory for temporary upload chunks.
+
 ### ICoreModuleOverrides
 
   - `ai?`: `{ budgetService?: Type<any>; connectionResolver?: Type<any>; connectionServic...` — Override AI module collaborators with project-specific subclasses.
@@ -190,7 +245,7 @@ When `passkey` is enabled, `trustedOrigins` is required (compile-time enforcemen
 
   - `enabled?`: `boolean | undefined` (default: `false`) — Whether rate limiting is enabled
   - `max?`: `number | undefined` (default: `10`) — Maximum number of requests within the time window
-  - `maxEntries?`: `number | undefined` (default: `10000`) — Maximum number of entries in the in-memory rate limit store.
+  - `maxEntries?`: `number | undefined` (default: `10000`) — Maximum number of distinct counters this limiter may hold — the bound on the keyspace a
   - `message?`: `string | undefined` — Custom message when rate limit is exceeded
   - `skipEndpoints?`: `string[] | undefined` — Endpoints to skip rate limiting entirely
   - `strictEndpoints?`: `string[] | undefined` — Endpoints to apply stricter rate limiting (e.g., sign-in, sign-up)
@@ -287,7 +342,7 @@ Generic: `CrudService<Model, CreateInput, UpdateInput>`
 | `auth` | — | `src/core/modules/auth/` |
 | `better-auth` | README, CHECKLIST | `src/core/modules/better-auth/` |
 | `error-code` | CHECKLIST | `src/core/modules/error-code/` |
-| `file` | README | `src/core/modules/file/` |
+| `file` | README, CHECKLIST | `src/core/modules/file/` |
 | `health-check` | — | `src/core/modules/health-check/` |
 | `hub` | README, CHECKLIST | `src/core/modules/hub/` |
 | `migrate` | README | `src/core/modules/migrate/` |

package/bin/migrate.js

@@ -93,7 +93,17 @@ if (require.main === module) {
     }
   }
 
-  // Load and run the CLI
-  const { main } = require(cliPath);
-  main();
+  // Load and run the CLI.
+  //
+  // Prefer runCli(): it drains stdout and then exits explicitly, so a handle left
+  // behind by MongoDB/GridFS cannot keep the process alive after the work is done
+  // (a migration step that never returns blocks the container before the server
+  // ever starts). main() is the fallback for a dist built before runCli existed —
+  // it resolves normally but relies on the event loop draining by itself.
+  const cli = require(cliPath);
+  const run = cli.runCli || cli.main;
+  Promise.resolve(run()).catch((error) => {
+    console.error('Fatal error:', error);
+    process.exitCode = 1;
+  });
 }

package/dist/core/common/helpers/content-disposition.helper.d.ts

@@ -0,0 +1 @@
+export declare function buildContentDisposition(filename?: string): string;

package/dist/core/common/helpers/content-disposition.helper.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildContentDisposition = buildContentDisposition;
+const NON_ATTR_CHAR = /['()*]/g;
+const NON_QUOTABLE_ASCII = /[^\x20-\x21\x23-\x5B\x5D-\x7E]/g;
+function toExtValue(filename) {
+    return encodeURIComponent(filename).replace(NON_ATTR_CHAR, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+function buildContentDisposition(filename) {
+    const name = filename || 'download';
+    const quotable = name.replace(NON_QUOTABLE_ASCII, '_');
+    return `attachment; filename="${quotable}"; filename*=UTF-8''${toExtValue(name)}`;
+}
+//# sourceMappingURL=content-disposition.helper.js.map

package/dist/core/common/helpers/content-disposition.helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-disposition.helper.js","sourceRoot":"","sources":["../../../../src/core/common/helpers/content-disposition.helper.ts"],"names":[],"mappings":";;AAqFA,0DAIC;AAhED,MAAM,aAAa,GAAG,SAAS,CAAC;AAehC,MAAM,kBAAkB,GAAG,iCAAiC,CAAC;AAK7D,SAAS,UAAU,CAAC,QAAgB;IAClC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC,OAAO,CACzC,aAAa,EACb,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAC9D,CAAC;AACJ,CAAC;AAmCD,SAAgB,uBAAuB,CAAC,QAAiB;IACvD,MAAM,IAAI,GAAG,QAAQ,IAAI,UAAU,CAAC;IACpC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;IACvD,OAAO,yBAAyB,QAAQ,uBAAuB,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;AACpF,CAAC"}

package/dist/core/common/helpers/file.helper.d.ts

@@ -1,17 +1,36 @@
 import { MulterOptions } from '@nestjs/platform-express/multer/interfaces/multer-options.interface';
+import type { FileUploadSource } from '../../modules/file/interfaces/file-upload.interface';
+export interface UploadAllowList {
+    extensions: readonly string[];
+    mimeTypes: readonly string[];
+}
+export declare const IMAGE_UPLOAD_ALLOW_LIST: UploadAllowList;
+export declare const SCRIPTABLE_UPLOAD_MIME_TYPES: readonly string[];
+export declare const SCRIPTABLE_UPLOAD_EXTENSIONS: readonly string[];
+export interface MulterFileFilterOptions {
+    allowScriptableTypes?: boolean;
+}
 export default class FileHelper {
     static multerRandomFileName(numberOfDigits?: number): (req: any, file: any, cb: any) => void;
-    static multerFileFilter(fileTypeRegex?: RegExp): (req: any, file: any, cb: any) => any;
+    static multerFileFilter(accept?: RegExp | UploadAllowList, options?: MulterFileFilterOptions): (req: any, file: any, cb: any) => any;
     static multerOptionsForImageUpload(options: {
+        allowList?: UploadAllowList;
         destination?: string;
         fileSize?: number;
         fileTypeRegex?: RegExp;
     }): MulterOptions;
 }
-export declare function multerFileFilter(fileTypeRegex?: RegExp): (req: any, file: any, cb: any) => any;
+export declare function multerFileFilter(accept?: RegExp | UploadAllowList, options?: MulterFileFilterOptions): (req: any, file: any, cb: any) => any;
 export declare function multerOptionsForImageUpload(options: {
+    allowList?: UploadAllowList;
     destination?: string;
     fileSize?: number;
     fileTypeRegex?: RegExp;
+    memory?: boolean;
 }): MulterOptions;
+export declare function multerFileToUpload(file: {
+    buffer?: Buffer;
+    mimetype?: string;
+    originalname?: string;
+}): FileUploadSource;
 export declare function multerRandomFileName(numberOfDigits?: number): (req: any, file: any, cb: any) => void;

package/dist/core/common/helpers/file.helper.js

@@ -1,47 +1,103 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCRIPTABLE_UPLOAD_EXTENSIONS = exports.SCRIPTABLE_UPLOAD_MIME_TYPES = exports.IMAGE_UPLOAD_ALLOW_LIST = void 0;
 exports.multerFileFilter = multerFileFilter;
 exports.multerOptionsForImageUpload = multerOptionsForImageUpload;
+exports.multerFileToUpload = multerFileToUpload;
 exports.multerRandomFileName = multerRandomFileName;
+const crypto_1 = require("crypto");
 const multer_1 = require("multer");
 const path_1 = require("path");
+const stream_1 = require("stream");
+exports.IMAGE_UPLOAD_ALLOW_LIST = {
+    extensions: ['.jpeg', '.jpg', '.png'],
+    mimeTypes: ['image/jpeg', 'image/png'],
+};
+exports.SCRIPTABLE_UPLOAD_MIME_TYPES = [
+    'application/javascript',
+    'application/xhtml+xml',
+    'application/xml',
+    'image/svg+xml',
+    'text/html',
+    'text/javascript',
+    'text/xml',
+];
+exports.SCRIPTABLE_UPLOAD_EXTENSIONS = [
+    '.htm',
+    '.html',
+    '.js',
+    '.mjs',
+    '.svg',
+    '.xhtml',
+    '.xml',
+];
 class FileHelper {
     static multerRandomFileName(numberOfDigits = 32) {
         return multerRandomFileName(numberOfDigits);
     }
-    static multerFileFilter(fileTypeRegex = /jpeg|jpg|png/) {
-        return multerFileFilter(fileTypeRegex);
+    static multerFileFilter(accept = exports.IMAGE_UPLOAD_ALLOW_LIST, options) {
+        return multerFileFilter(accept, options);
     }
     static multerOptionsForImageUpload(options) {
         return multerOptionsForImageUpload(options);
     }
 }
 exports.default = FileHelper;
-function multerFileFilter(fileTypeRegex = /jpeg|jpg|png/) {
+function normalizeMimeType(value) {
+    return String(value || '')
+        .split(';')[0]
+        .trim()
+        .toLowerCase();
+}
+function multerFileFilter(accept = exports.IMAGE_UPLOAD_ALLOW_LIST, options) {
     return (req, file, cb) => {
-        const mimetype = fileTypeRegex.test(file.mimetype);
-        const extName = fileTypeRegex.test((0, path_1.extname)(file.originalname).toLowerCase());
-        if (mimetype && extName) {
+        const mimeType = normalizeMimeType(file?.mimetype);
+        const extension = (0, path_1.extname)(String(file?.originalname || '')).toLowerCase();
+        if (!options?.allowScriptableTypes &&
+            (exports.SCRIPTABLE_UPLOAD_MIME_TYPES.includes(mimeType) || exports.SCRIPTABLE_UPLOAD_EXTENSIONS.includes(extension))) {
+            return cb(new Error(`File upload rejected: ${mimeType || 'unknown type'} may execute as script`));
+        }
+        const accepted = accept instanceof RegExp
+            ? accept.test(mimeType) && accept.test(extension)
+            : accept.mimeTypes.includes(mimeType) && accept.extensions.includes(extension);
+        if (accepted) {
             return cb(null, true);
         }
-        cb(`Error: File upload only supports the following filetypes - ${fileTypeRegex}`);
+        cb(new Error(`File upload only supports the following filetypes - ${describeAccept(accept)}`));
     };
 }
+function describeAccept(accept) {
+    return accept instanceof RegExp ? String(accept) : accept.extensions.join(', ');
+}
 function multerOptionsForImageUpload(options) {
     const config = {
         fileSize: 1024 * 1024,
-        fileTypeRegex: /jpeg|jpg|png/,
         ...options,
     };
+    const accept = config.fileTypeRegex ?? config.allowList ?? exports.IMAGE_UPLOAD_ALLOW_LIST;
     return {
-        fileFilter: config.fileTypeRegex ? multerFileFilter(config.fileTypeRegex) : undefined,
+        fileFilter: multerFileFilter(accept),
         limits: {
             fileSize: config.fileSize ? config.fileSize : undefined,
         },
-        storage: (0, multer_1.diskStorage)({
-            destination: config.destination ? config.destination : undefined,
-            filename: multerRandomFileName(),
-        }),
+        storage: config.memory
+            ? (0, multer_1.memoryStorage)()
+            : (0, multer_1.diskStorage)({
+                destination: config.destination ? config.destination : undefined,
+                filename: multerRandomFileName(),
+            }),
+    };
+}
+function multerFileToUpload(file) {
+    if (!file?.buffer) {
+        throw new Error('multerFileToUpload() needs an in-memory upload: pass `memory: true` to the multer options ' +
+            '(a disk-stored file has no buffer).');
+    }
+    return {
+        createReadStream: () => stream_1.Readable.from(file.buffer),
+        encoding: '7bit',
+        filename: file.originalname || (0, crypto_1.randomBytes)(16).toString('hex'),
+        mimetype: file.mimetype || 'application/octet-stream',
     };
 }
 function multerRandomFileName(numberOfDigits = 32) {

package/dist/core/common/helpers/file.helper.js.map

@@ -1 +1 @@
-{"version":3,"file":"file.helper.js","sourceRoot":"","sources":["../../../../src/core/common/helpers/file.helper.ts"],"names":[],"mappings":";;AAuCA,4CAUC;AAKD,kEAkCC;AAMD,oDAYC;AAzGD,mCAAqC;AACrC,+BAA+B;AAM/B,MAAqB,UAAU;IAKtB,MAAM,CAAC,oBAAoB,CAAC,cAAc,GAAG,EAAE;QACpD,OAAO,oBAAoB,CAAC,cAAc,CAAC,CAAC;IAC9C,CAAC;IAKM,MAAM,CAAC,gBAAgB,CAAC,aAAa,GAAG,cAAc;QAC3D,OAAO,gBAAgB,CAAC,aAAa,CAAC,CAAC;IACzC,CAAC;IAKM,MAAM,CAAC,2BAA2B,CAAC,OAIzC;QACC,OAAO,2BAA2B,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;CACF;AA1BD,6BA0BC;AAKD,SAAgB,gBAAgB,CAAC,aAAa,GAAG,cAAc;IAC7D,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE;QACvB,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,IAAA,cAAO,EAAC,IAAI,CAAC,YAAY,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;QAE7E,IAAI,QAAQ,IAAI,OAAO,EAAE,CAAC;YACxB,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACxB,CAAC;QACD,EAAE,CAAC,8DAA8D,aAAa,EAAE,CAAC,CAAC;IACpF,CAAC,CAAC;AACJ,CAAC;AAKD,SAAgB,2BAA2B,CAAC,OAI3C;IAEC,MAAM,MAAM,GAAG;QACb,QAAQ,EAAE,IAAI,GAAG,IAAI;QACrB,aAAa,EAAE,cAAc;QAC7B,GAAG,OAAO;KACX,CAAC;IAEF,OAAO;QAEL,UAAU,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS;QAGrF,MAAM,EAAE;YAEN,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;SACxD;QAID,OAAO,EAAE,IAAA,oBAAW,EAAC;YAInB,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS;YAGhE,QAAQ,EAAE,oBAAoB,EAAE;SACjC,CAAC;KACH,CAAC;AACJ,CAAC;AAMD,SAAgB,oBAAoB,CAAC,cAAc,GAAG,EAAE;IACtD,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE;QAEvB,MAAM,UAAU,GAAG,KAAK,CAAC,cAAc,CAAC;aACrC,IAAI,CAAC,IAAI,CAAC;aACV,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;aACtD,IAAI,CAAC,EAAE,CAAC,CAAC;QAIZ,EAAE,CAAC,IAAI,EAAE,GAAG,UAAU,GAAG,IAAA,cAAO,EAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;IACzD,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"file.helper.js","sourceRoot":"","sources":["../../../../src/core/common/helpers/file.helper.ts"],"names":[],"mappings":"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"}

package/dist/core/common/helpers/graceful-shutdown.helper.d.ts

@@ -0,0 +1,2 @@
+import { INestApplication } from '@nestjs/common';
+export declare function installGracefulShutdown<T extends INestApplication>(app: T): T;