@lenne.tech/nest-server 11.32.4 → 11.33.0

package/src/core/common/interfaces/server-options.interface.ts

@@ -555,8 +555,21 @@ export interface IBetterAuthRateLimit {
   max?: number;
 
   /**
-   * Maximum number of entries in the in-memory rate limit store.
-   * When exceeded, the oldest entries are evicted to prevent unbounded memory growth.
+   * Maximum number of distinct counters this limiter may hold — the bound on the keyspace a
+   * caller can create, since both parts of a counter key are caller-influenced.
+   *
+   * It means slightly different things per store, because the two have different pressures:
+   * - **In-memory store**: live entries in the process. Beyond it, expired entries are evicted
+   *   first; if everything is still live, new keys fold into shared coarse counters.
+   * - **Redis store** (`redis` configured): NEW counters per window, across all replicas. Beyond
+   *   it, further new keys fold into the same coarse counters until the window rolls over.
+   *
+   * Either way, saturation degrades towards a COARSER limit — unrelated clients then share a
+   * counter and are throttled earlier than their own traffic warrants — never towards no limit.
+   *
+   * Only Better-Auth exposes this knob. The Legacy Auth limiter has no equivalent config key and
+   * uses the same `10000` default on both stores.
+   *
    * @default 10000
    */
   maxEntries?: number;
@@ -815,6 +828,112 @@ export interface IErrorCode {
   autoRegister?: boolean;
 }
 
+/**
+ * Interface for the file module (GridFS)
+ *
+ * All three knobs take PLAIN ROLE STRINGS, not `RoleEnum` members, because
+ * `@Roles()` itself is `(...roles: string[])`. A project may therefore gate the
+ * routes with its own role names (`'company-admin'`, `'editor'`) exactly as it
+ * would in a hand-written `@Roles()` call — see `RoleEnum` for the system roles
+ * (`S_USER`, `S_VERIFIED`, …) that keep their special meaning.
+ *
+ * The defaults are deliberately restrictive: a single GridFS bucket is shared by
+ * every feature of the consuming project, and the ids identifying its blobs are
+ * ObjectIds — not secrets. Widening any of these is a decision the project owner
+ * has to make explicitly, and it belongs in `config.env.ts` where it is
+ * reviewable, rather than in a decorator override where it is not.
+ *
+ * ROLES ARE THE COARSE FILTER ONLY. They answer "may this caller reach the
+ * route at all", never "may this caller have THIS file". For per-file rules —
+ * owner, tenant, published-flag — override `CoreFileService.checkRights()`,
+ * which receives the `currentUser` and the resolved file metadata.
+ *
+ * ⚠ With `multiTenancy` active, a non-system role is validated against
+ * `membership.role` rather than `user.roles` (see `CoreTenantGuard`). Since
+ * GridFS is accessed through the native driver, `mongooseTenantPlugin` never
+ * runs on `fs.files` — the bucket is NOT tenant-scoped. A per-tenant rule must
+ * therefore be expressed in `checkRights()`, not by a role name alone.
+ */
+export interface IFileConfig {
+  /**
+   * Roles allowed to DELETE files (`deleteFile` mutation).
+   *
+   * Kept separate from `uploadRoles` on purpose: "everyone signed in may upload"
+   * is a common and reasonable policy, "everyone signed in may delete anyone's
+   * file" almost never is.
+   *
+   * @default ['admin']
+   */
+  deleteRoles?: string[];
+
+  /**
+   * Roles allowed to DOWNLOAD files and read file info
+   * (`GET /files/id/:id`, `GET /files/:filename`, `getFileInfo` query).
+   *
+   * Note for browser-rendered files: an `<img src>` or `<a href>` cannot send an
+   * `Authorization` header, so anything stricter than `S_EVERYONE` only works
+   * for those tags when the session travels as a cookie.
+   *
+   * @default ['admin']
+   */
+  downloadRoles?: string[];
+
+  /**
+   * Storage driver for CoreFileService. Three equivalent options:
+   *
+   * - `'s3'`         — an S3-compatible bucket (needs `s3`). The only driver that
+   *                    survives horizontal scaling.
+   * - `'gridfs'`     — MongoDB GridFS. No extra infrastructure; bytes share the database.
+   * - `'filesystem'` — the local disk (`storageDir`). Pod-local: not shared between
+   *                    replicas and lost on restart unless the path is a mounted volume.
+   *
+   * **Set explicitly and it is enforced.** If the chosen store is not available,
+   * the boot FAILS rather than falling back — a silent fallback would put files
+   * in a store the operator does not believe they are in, with no way to tell
+   * afterwards which file went where.
+   *
+   * **Left unset, it is derived**, most capable first:
+   * 1. `'s3'` when `s3.bucket` is configured
+   * 2. `'gridfs'` when a database is configured
+   * 3. `'filesystem'` when neither is
+   *
+   * A configured-but-unreachable database is an error in its own right (Mongoose
+   * fails the boot), never a reason to fall through to the disk.
+   *
+   * **Metadata always lives in the database**, whichever driver stores the bytes:
+   * filename, content type, length and the custom `metadata` a per-file rule
+   * reads have to be queryable. Only a project running without a database at all
+   * has to keep its own bookkeeping.
+   *
+   * Orthogonal to the role knobs above: this decides WHERE the bytes live, they
+   * decide WHO may reach them. A per-file rule in `checkRights()` works under
+   * every driver — `getRawFileInfo()` checks all metadata stores.
+   *
+   * @default derived — see above
+   */
+  storage?: 'filesystem' | 'gridfs' | 's3';
+
+  /**
+   * Directory for the `'filesystem'` storage driver.
+   *
+   * Relative paths resolve against the process working directory. The directory
+   * is created on first write.
+   *
+   * @default 'uploads/files'
+   */
+  storageDir?: string;
+
+  /**
+   * Roles allowed to UPLOAD files (`uploadFile` / `uploadFiles` mutations).
+   *
+   * This does NOT cover TUS resumable uploads, which are served by their own
+   * controller — configure those via `tus.roles`.
+   *
+   * @default ['admin']
+   */
+  uploadRoles?: string[];
+}
+
 /**
  * Interface for JWT configuration (main and refresh)
  */
@@ -1792,6 +1911,12 @@ export interface IServerOptions {
    */
   execAfterInit?: string;
 
+  /**
+   * Configuration of the file module: where the bytes live (`storage`) and who
+   * may reach them (`downloadRoles` / `uploadRoles` / `deleteRoles`).
+   */
+  file?: IFileConfig;
+
   /**
    * Filter configuration and defaults
    */
@@ -2123,6 +2248,35 @@ export interface IServerOptions {
    */
   port?: number;
 
+  /**
+   * Optional central Redis connection used by all distributed features
+   * (rate limiting, cron deduplication, GraphQL subscriptions, caches, Hub collectors).
+   *
+   * Follows the "presence implies enabled" pattern:
+   * - undefined: no Redis — all features fall back to their process-local behavior
+   * - true or {}: enabled with defaults (localhost:6379, db 0)
+   * - { enabled: false, ... }: pre-configured but disabled
+   *
+   * Requires the optional peer dependency `ioredis` to be installed.
+   *
+   * @default undefined (disabled)
+   */
+  redis?: boolean | IRedisConfig;
+
+  /**
+   * Optional central S3-compatible object storage (AWS S3, MinIO, ...).
+   *
+   * Used by CoreFileService (when `file.storage: 's3'`) and as TUS upload staging.
+   * Follows the "presence implies enabled" pattern; without this config,
+   * files stay in GridFS and TUS stages on local disk as before.
+   *
+   * Requires the optional peer dependency `@aws-sdk/client-s3`
+   * (and `@aws-sdk/s3-request-presigner` for presigned downloads).
+   *
+   * @default undefined (disabled)
+   */
+  s3?: IS3Config;
+
   /**
    * Configuration for security pipes and interceptors
    */
@@ -2391,6 +2545,24 @@ export interface IServerOptions {
    */
   sha256?: boolean;
 
+  /**
+   * Delay in milliseconds between receiving a shutdown signal and starting the
+   * NestJS shutdown sequence. Gives load balancers time to deregister the
+   * instance before in-flight connections are drained (zero-downtime deploys).
+   *
+   * 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.
+   *
+   * Keep it well below the orchestrator grace period and leave room for the
+   * drain that follows (Compose 10s, Kubernetes 30s, diagnostics watchdog 30s);
+   * exceeding any of them means SIGKILL mid-wait and no shutdown hook runs.
+   * Warns above 10000, capped at 60000.
+   *
+   * @default 0 (no delay)
+   */
+  shutdownDelayMs?: number;
+
   /**
    * Configuration for useStaticAssets
    */
@@ -2458,6 +2630,58 @@ export interface IServerOptions {
     path?: string;
   };
 
+  /**
+   * Express `trust proxy` setting — how far up the `X-Forwarded-For` chain this app believes.
+   *
+   * **This is what makes `request.ip` correct, and every IP-keyed rate limit depends on it.**
+   * Express derives `req.ip` from the forwarded chain only as far as this setting allows and
+   * otherwise reports the socket peer. Left unset (Express default `false`), an app behind Caddy,
+   * nginx or a Kubernetes ingress sees the PROXY's address on every request — so all clients
+   * collapse onto ONE rate-limit bucket and `auth.rateLimit.max` throttles everybody at once
+   * instead of throttling one attacker. With `redis` configured that limit is enforced exactly
+   * fleet-wide, which makes the collapse total rather than per replica.
+   *
+   * Setting it wrong in the other direction is a bypass: trusting more hops than actually sit in
+   * front of the app lets a client prepend its own `X-Forwarded-For` entry and pick a fresh bucket
+   * per request. Count the hops.
+   *
+   * Accepted values (passed through to `app.set('trust proxy', …)` verbatim):
+   * - `false` — trust nothing, use the socket address (Express default). Also the explicit
+   *   "no proxy in front of me" answer, which silences the boot warning below.
+   * - `1` / `2` / … — trust exactly N hops closest to this app. The usual answer: one reverse
+   *   proxy is `1`, proxy behind a CDN is `2`.
+   * - `'loopback'` / `'linklocal'` / `'uniquelocal'` — trust those address ranges.
+   * - `'10.0.0.0/8'`, `['loopback', '10.0.0.0/8']` — trust specific addresses or subnets.
+   * - `true` — trust the LEFTMOST entry, i.e. whatever the client sent. Never use this on a
+   *   public deployment; it hands every caller its own rate-limit bucket.
+   *
+   * A predicate function is deliberately NOT accepted here, although Express supports one: this
+   * value must survive `NEST_SERVER_CONFIG` / `NSC__*` (JSON) and the ConfigService deep clone,
+   * and hop counts, ranges and subnet lists already cover every real deployment shape. If you do
+   * need a predicate, leave `trustProxy` unset and call `app.set('trust proxy', fn)` in your own
+   * `main.ts` — an unset value is never applied, so nothing overwrites it.
+   *
+   * Applied by `CoreModule` during module init, which happens inside `app.init()` / `app.listen()`
+   * — i.e. AFTER your `main.ts` runs. A configured value therefore takes precedence over an
+   * `app.set('trust proxy', …)` of your own.
+   *
+   * When this is unset and an IP-keyed rate limiter (`auth.rateLimit` / `betterAuth.rateLimit`) is
+   * enabled, the framework logs a warning at boot naming the shared-bucket consequence.
+   *
+   * @default false (Express default — the forwarded chain is not trusted)
+   * @since 11.33.0
+   *
+   * @example
+   * ```typescript
+   * // One reverse proxy (Caddy / nginx / ingress) in front of the app
+   * trustProxy: 1,
+   *
+   * // Nothing in front of the app — explicit, and silences the boot warning
+   * trustProxy: false,
+   * ```
+   */
+  trustProxy?: boolean | number | string | string[];
+
   /**
    * TUS resumable upload configuration.
    *
@@ -2488,6 +2712,178 @@ export interface IServerOptions {
   tus?: boolean | ITusConfig;
 }
 
+/**
+ * Central Redis connection configuration (see IServerOptions.redis).
+ *
+ * All distributed features share this single configuration. Individual features
+ * automatically use Redis when this is enabled and fall back to their
+ * process-local behavior when it is not.
+ */
+export interface IRedisConfig {
+  /**
+   * Redis database index
+   * @default 0
+   */
+  db?: number;
+
+  /**
+   * Whether Redis is enabled.
+   * Presence of the config object implies true.
+   * @default true (when config object is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * Redis host
+   * @default 'localhost'
+   */
+  host?: string;
+
+  /**
+   * Prefix prepended to every framework-managed Redis key
+   * (rate limits, locks, caches, Hub collectors, BullMQ queue prefix).
+   *
+   * Defaults to your own `package.json` name, slugified (`@acme/api` → `acme-api`),
+   * so two applications sharing one Redis do not collide. Set it explicitly only
+   * when sharing IS intended — giving two applications the same prefix makes one
+   * application's BullMQ worker consume the other's scheduled jobs.
+   *
+   * Note: applied by the framework per key — NOT passed as ioredis `keyPrefix`,
+   * which would conflict with BullMQ's own prefix handling.
+   *
+   * @default the slugified `name` from package.json, or 'nest-server' if unreadable
+   */
+  keyPrefix?: string;
+
+  /**
+   * Additional ioredis options passed through to the client constructor
+   * (e.g. `tls`, `sentinels`, `retryStrategy`).
+   * @default undefined
+   */
+  options?: Record<string, unknown>;
+
+  /**
+   * Redis password
+   * @default undefined (no auth)
+   */
+  password?: string;
+
+  /**
+   * Redis port
+   * @default 6379
+   */
+  port?: number;
+
+  /**
+   * Full Redis connection URL (e.g. 'redis://user:pass@host:6379/0').
+   * Takes precedence over host/port/db/password/username.
+   * @default undefined
+   */
+  url?: string;
+
+  /**
+   * Redis username (Redis 6+ ACL)
+   * @default undefined
+   */
+  username?: string;
+}
+
+/**
+ * S3-compatible object storage configuration (see IServerOptions.s3).
+ * Works with AWS S3, MinIO, RustFS and other S3-compatible services.
+ */
+export interface IS3Config {
+  /**
+   * Access key ID.
+   * Falls back to the AWS SDK default credential chain when omitted
+   * (environment variables, instance profiles, ...).
+   * @default undefined
+   */
+  accessKeyId?: string;
+
+  /**
+   * Create the configured buckets at startup when they do not exist.
+   *
+   * Off by default: production buckets normally come from infrastructure code, and their
+   * credentials often carry no `CreateBucket` permission. Turn it on for a self-hosted
+   * MinIO/RustFS or a local dev stack. Either way the server verifies the buckets at boot and
+   * logs an actionable error when one is missing, instead of letting the first upload fail with
+   * an opaque 500.
+   *
+   * @default false
+   */
+  autoCreateBucket?: boolean;
+
+  /**
+   * Bucket for files stored via CoreFileService
+   */
+  bucket: string;
+
+  /**
+   * Whether S3 is enabled.
+   * Presence of the config object implies true.
+   * @default true (when config object is present)
+   */
+  enabled?: boolean;
+
+  /**
+   * Custom endpoint URL for S3-compatible services (MinIO, RustFS, ...).
+   * Omit for AWS S3.
+   * @default undefined
+   */
+  endpoint?: string;
+
+  /**
+   * Use path-style addressing (required by most self-hosted S3 services).
+   * @default false
+   */
+  forcePathStyle?: boolean;
+
+  /**
+   * Serve downloads as presigned URL redirects instead of streaming
+   * through the API (offloads traffic from the server).
+   * `true` / `{}` enables with defaults.
+   *
+   * The issued URL is a session-less BEARER CAPABILITY: it is authorized once, at issue time, and
+   * afterwards anyone holding the string can download the object until it expires — there is no
+   * revocation short of deleting the object or rotating the signing credentials.
+   * @default false
+   */
+  presignedDownloads?:
+    | boolean
+    | {
+        /**
+         * Presigned URL validity in seconds.
+         *
+         * Keep it just long enough for a download to START. Values above 900s are accepted but
+         * warned about at boot, and anything above 604800s (the AWS SigV4 maximum, 7 days) is
+         * capped — a longer signature is rejected by S3 rather than honored.
+         * @default 300
+         */
+        expiresInSeconds?: number;
+      };
+
+  /**
+   * AWS region
+   * @default 'us-east-1'
+   */
+  region?: string;
+
+  /**
+   * Secret access key.
+   * Falls back to the AWS SDK default credential chain when omitted.
+   * @default undefined
+   */
+  secretAccessKey?: string;
+
+  /**
+   * Bucket used as staging area for resumable TUS uploads.
+   * Configure a lifecycle rule on this bucket to expire aborted uploads.
+   * @default same as `bucket`
+   */
+  stagingBucket?: string;
+}
+
 export interface ISystemSetup {
   /**
    * Whether system setup is enabled.
@@ -2613,6 +3009,46 @@ export interface ITusConfig {
    */
   path?: string;
 
+  /**
+   * Roles allowed to use the tus endpoints (create, write, read offset, terminate).
+   *
+   * Takes plain role strings, like `@Roles()` itself, so a project can use its
+   * own role names here.
+   *
+   * A tus upload writes into the SAME file store that `file.downloadRoles`
+   * guards — GridFS or S3, whichever `file.storage` selects — so leaving this at
+   * `S_EVERYONE` while the download side is restricted means anonymous callers
+   * may write into, and with the termination extension delete from, a store
+   * only privileged callers may read. That asymmetry is rarely intended;
+   * `S_USER` is the safer default for anything reachable from the internet.
+   *
+   * `OPTIONS` is exempt — it is the CORS preflight, which browsers send without
+   * credentials, and it returns only server capabilities.
+   *
+   * @default ['s_user']
+   */
+  roles?: string[];
+
+  /**
+   * Stage upload chunks in the configured S3 bucket (`IServerOptions.s3`,
+   * `stagingBucket`) instead of local disk, so resumable uploads survive
+   * replica restarts and work without sticky sessions.
+   *
+   * **On by default whenever S3 is usable** — a configured `s3` block with a
+   * `bucket` is enough, no opt-in needed. Set to `false` to force local disk.
+   *
+   * "Usable" is the same test `file.storage`'s automatic default uses: a bucket
+   * must be named. An `s3` block without one is ignored entirely (with a
+   * warning), so staging can never be switched on against a bucket that does
+   * not exist.
+   *
+   * Independent of `file.storage`: chunks may stage in S3 while finished files
+   * are written to GridFS, or the other way round.
+   *
+   * @default true (when S3 is usable)
+   */
+  s3Staging?: boolean;
+
   /**
    * Termination extension configuration.
    * Allows deleting uploads via DELETE.
@@ -2622,6 +3058,7 @@ export interface ITusConfig {
 
   /**
    * Directory for temporary upload chunks.
+   * Only used when uploads are NOT staged in S3 (see `s3Staging`).
    * @default 'uploads/tus'
    */
   uploadDir?: string;

package/src/core/common/services/core-cron-jobs.initializer.ts

@@ -0,0 +1,39 @@
+import { Injectable, OnApplicationShutdown, OnModuleInit, Optional } from '@nestjs/common';
+import { InjectConnection } from '@nestjs/mongoose';
+import { Connection } from 'mongoose';
+
+import { setCronJobsInfrastructure } from './core-cron-jobs.registry';
+import { CoreRedisService } from './core-redis.service';
+
+/**
+ * Populates the cron-jobs infrastructure registry at bootstrap so that
+ * CoreCronJobs subclasses get multi-replica deduplication (Redis/BullMQ or
+ * Mongo lease) WITHOUT any constructor changes in consumer projects.
+ *
+ * Registered as a CoreModule provider; consumers never interact with it.
+ */
+@Injectable()
+export class CoreCronJobsInitializer implements OnApplicationShutdown, OnModuleInit {
+  constructor(
+    @InjectConnection() protected readonly connection: Connection,
+    @Optional() protected readonly redisService?: CoreRedisService,
+  ) {}
+
+  onModuleInit(): void {
+    setCronJobsInfrastructure({
+      connection: this.connection,
+      redisService: this.redisService?.enabled ? this.redisService : undefined,
+    });
+  }
+
+  /**
+   * Drop the module-global references again.
+   *
+   * The registry outlives the application that filled it, so without this a closed app leaves its
+   * (now closed) Mongoose connection and Redis service behind for whatever app starts next in the
+   * same process — a test suite, or any host that creates more than one application.
+   */
+  onApplicationShutdown(): void {
+    setCronJobsInfrastructure({});
+  }
+}

package/src/core/common/services/core-cron-jobs.registry.ts

@@ -0,0 +1,45 @@
+/**
+ * Runtime registry for the optional cron-job infrastructure.
+ *
+ * `CoreCronJobs` is abstract and instantiated by the consuming project, so the
+ * framework cannot inject the Mongoose connection or `CoreRedisService` into it.
+ * Registering them here instead keeps multi-replica deduplication working WITHOUT
+ * any change to an existing subclass — the same shape as
+ * `core-better-auth.registry.ts`.
+ *
+ * The file uses only `import type`, which both tsc and SWC erase entirely, so it
+ * emits no `require()` at all and is a true leaf: it can never be mid-evaluation
+ * when someone imports it (see .claude/rules/architecture.md → "DI Token Placement
+ * (SWC-Safe)"). Its exports are hoisted `function` declarations for the same reason.
+ *
+ * @internal Populated by CoreModule. `CoreCronJobs` reads it lazily on every access,
+ * so a registration that happens after the service was constructed still takes effect.
+ */
+
+import type { CoreRedisService } from './core-redis.service';
+import type { Connection } from 'mongoose';
+
+export interface CronJobsInfrastructure {
+  /** Mongoose connection used for the per-tick MongoDB lease */
+  connection?: Connection;
+
+  /** Central Redis service; enables the BullMQ job-scheduler mode */
+  redisService?: CoreRedisService;
+}
+
+let infrastructure: CronJobsInfrastructure = {};
+
+/**
+ * Returns the registered cron-job infrastructure; empty when nothing was registered.
+ */
+export function getCronJobsInfrastructure(): CronJobsInfrastructure {
+  return infrastructure;
+}
+
+/**
+ * Registers the cron-job infrastructure. Pass `{}` to clear it (tests).
+ * @internal
+ */
+export function setCronJobsInfrastructure(value: CronJobsInfrastructure): void {
+  infrastructure = value ?? {};
+}