@lenne.tech/nest-server 11.32.4 → 11.33.0

package/src/core/modules/better-auth/core-better-auth-rate-limiter.service.ts

@@ -1,6 +1,14 @@
-import { Injectable, Logger } from '@nestjs/common';
+import { Injectable, Logger, Optional } from '@nestjs/common';
 
 import { IBetterAuthRateLimit } from '../../common/interfaces/server-options.interface';
+import { CoreRedisService } from '../../common/services/core-redis.service';
+import {
+  InMemoryRateLimitStore,
+  rateLimitKey,
+  rateLimitKeyPrefix,
+  RateLimitStore,
+  RedisRateLimitStore,
+} from '../../common/services/rate-limit-store';
 
 /**
  * Result of a rate limit check
@@ -32,14 +40,6 @@ export interface RateLimitResult {
   resetIn: number;
 }
 
-/**
- * Rate limit entry for tracking requests
- */
-interface RateLimitEntry {
-  count: number;
-  resetTime: number;
-}
-
 /**
  * Default rate limiting configuration
  */
@@ -54,10 +54,11 @@ const DEFAULT_CONFIG: Required<IBetterAuthRateLimit> = {
 };
 
 /**
- * In-memory rate limiter for Better-Auth endpoints
+ * Rate limiter for Better-Auth endpoints
  *
  * This service provides rate limiting to protect against brute-force attacks
- * on authentication endpoints. It uses an in-memory store with automatic cleanup.
+ * on authentication endpoints. Counters live in a {@link RateLimitStore}: shared
+ * via Redis when `ServerOptions.redis` is configured, process-local otherwise.
  *
  * Features:
  * - Configurable request limits and time windows
@@ -68,7 +69,7 @@ const DEFAULT_CONFIG: Required<IBetterAuthRateLimit> = {
  *
  * @example
  * ```typescript
- * const result = rateLimiter.check('192.168.1.1', '/iam/sign-in');
+ * const result = await rateLimiter.check('192.168.1.1', '/iam/sign-in');
  * if (!result.allowed) {
  *   throw new TooManyRequestsException(rateLimiter.getMessage());
  * }
@@ -76,15 +77,11 @@ const DEFAULT_CONFIG: Required<IBetterAuthRateLimit> = {
  */
 @Injectable()
 export class CoreBetterAuthRateLimiter {
-  private readonly logger = new Logger(CoreBetterAuthRateLimiter.name);
-  private readonly store = new Map<string, RateLimitEntry>();
-  private config: Required<IBetterAuthRateLimit> = DEFAULT_CONFIG;
-  private cleanupInterval: NodeJS.Timeout | null = null;
-
-  constructor() {
-    // Start cleanup interval (every 5 minutes)
-    this.startCleanup();
-  }
+  protected readonly logger = new Logger(CoreBetterAuthRateLimiter.name);
+  protected config: Required<IBetterAuthRateLimit> = DEFAULT_CONFIG;
+  protected store?: RateLimitStore;
+
+  constructor(@Optional() protected readonly coreRedisService?: CoreRedisService) {}
 
   /**
    * Configure the rate limiter
@@ -112,7 +109,7 @@ export class CoreBetterAuthRateLimiter {
    * @param path - Request path (relative to basePath)
    * @returns Rate limit check result
    */
-  check(ip: string, path: string): RateLimitResult {
+  async check(ip: string, path: string): Promise<RateLimitResult> {
     // If rate limiting is disabled, always allow
     if (!this.config.enabled) {
       return {
@@ -137,48 +134,18 @@ export class CoreBetterAuthRateLimiter {
 
     // Determine the limit for this endpoint
     const limit = this.getLimit(path);
-    const key = this.getKey(ip, path);
-    const now = Date.now();
-
-    // Get or create entry
-    let entry = this.store.get(key);
-
-    if (!entry || now >= entry.resetTime) {
-      // Evict oldest entries if store exceeds maxEntries
-      if (!entry && this.store.size >= this.config.maxEntries) {
-        this.evictOldest();
-      }
-
-      // Create new entry or reset expired one
-      entry = {
-        count: 1,
-        resetTime: now + this.config.windowSeconds * 1000,
-      };
-      this.store.set(key, entry);
+    const { count, resetIn } = await this.getStore().hit(this.getKey(ip, path), this.config.windowSeconds);
 
-      return {
-        allowed: true,
-        current: 1,
-        limit,
-        remaining: limit - 1,
-        resetIn: this.config.windowSeconds,
-      };
-    }
-
-    // Increment count
-    entry.count++;
-
-    const resetIn = Math.ceil((entry.resetTime - now) / 1000);
-    const allowed = entry.count <= limit;
-    const remaining = Math.max(0, limit - entry.count);
+    const allowed = count <= limit;
+    const remaining = Math.max(0, limit - count);
 
     if (!allowed) {
-      this.logger.warn(`Rate limit exceeded for IP ${this.maskIp(ip)} on ${path}: ${entry.count}/${limit}`);
+      this.logger.warn(`Rate limit exceeded for IP ${this.maskIp(ip)} on ${path}: ${count}/${limit}`);
     }
 
     return {
       allowed,
-      current: entry.count,
+      current: count,
       limit,
       remaining,
       resetIn,
@@ -204,74 +171,53 @@ export class CoreBetterAuthRateLimiter {
    *
    * @param ip - Client IP address
    */
-  reset(ip: string): void {
-    // Remove all entries for this IP
-    for (const key of this.store.keys()) {
-      if (key.startsWith(`${ip}:`)) {
-        this.store.delete(key);
-      }
-    }
+  async reset(ip: string): Promise<void> {
+    await this.getStore().resetByPrefix(rateLimitKeyPrefix(ip));
   }
 
   /**
    * Clear all rate limit entries (useful for testing)
    */
-  clear(): void {
-    this.store.clear();
+  async clear(): Promise<void> {
+    await this.getStore().clear();
   }
 
   /**
    * Get statistics about the rate limiter
+   *
+   * `activeEntries` is `-1` when a Redis store is in use — the entry count is
+   * not cheaply known there.
    */
   getStats(): { activeEntries: number; enabled: boolean } {
     return {
-      activeEntries: this.store.size,
+      activeEntries: this.store?.size() ?? 0,
       enabled: this.config.enabled,
     };
   }
 
   /**
-   * Stop the cleanup interval (for graceful shutdown)
+   * Stop the in-memory cleanup interval (for graceful shutdown)
    */
   onModuleDestroy(): void {
-    if (this.cleanupInterval) {
-      clearInterval(this.cleanupInterval);
-      this.cleanupInterval = null;
-    }
+    // Not `instanceof InMemoryRateLimitStore`: a RedisRateLimitStore owns an in-memory fallback
+    // whose cleanup interval would otherwise outlive the app.
+    this.store?.destroy?.();
   }
 
   /**
-   * Evict the oldest entries when the store exceeds maxEntries.
-   * First removes all expired entries, then removes entries closest to expiry
-   * until the store is at 90% capacity.
+   * Lazily select the counter store: Redis when configured and enabled,
+   * process-local otherwise.
    */
-  private evictOldest(): void {
-    const now = Date.now();
-    let evicted = 0;
-
-    // First pass: remove all expired entries
-    for (const [key, entry] of this.store.entries()) {
-      if (now >= entry.resetTime) {
-        this.store.delete(key);
-        evicted++;
-      }
-    }
-
-    // If still over limit, remove entries with earliest resetTime (oldest)
-    if (this.store.size >= this.config.maxEntries) {
-      const targetSize = Math.floor(this.config.maxEntries * 0.9);
-      const entries = [...this.store.entries()].sort((a, b) => a[1].resetTime - b[1].resetTime);
-
-      for (const [key] of entries) {
-        if (this.store.size <= targetSize) break;
-        this.store.delete(key);
-        evicted++;
-      }
-    }
-
-    if (evicted > 0) {
-      this.logger.warn(`Evicted ${evicted} rate limit entries (store was at capacity: ${this.config.maxEntries})`);
+  protected getStore(): RateLimitStore {
+    if (!this.store) {
+      // `maxEntries` bounds BOTH stores: process-local entries here, distinct Redis counter keys
+      // per window there. A project that tightened the cap must not have it silently ignored the
+      // moment `redis` is configured.
+      this.store = this.coreRedisService?.enabled
+        ? new RedisRateLimitStore(this.coreRedisService, 'better-auth', this.config.maxEntries)
+        : new InMemoryRateLimitStore(this.config.maxEntries);
     }
+    return this.store;
   }
 
   /**
@@ -300,7 +246,10 @@ export class CoreBetterAuthRateLimiter {
   private getKey(ip: string, path: string): string {
     // Group similar endpoints together
     const endpoint = this.normalizeEndpoint(path);
-    return `${ip}:${endpoint}`;
+    // rateLimitKey(), not string concatenation: an IP that itself contains the separator (every
+    // IPv6 address does) would otherwise straddle the ip/endpoint boundary and share a counter
+    // with a different caller.
+    return rateLimitKey(ip, endpoint);
   }
 
   /**
@@ -333,34 +282,4 @@ export class CoreBetterAuthRateLimiter {
     const parts = ip.split(':');
     return `${parts[0]}:****`;
   }
-
-  /**
-   * Start periodic cleanup of expired entries
-   */
-  private startCleanup(): void {
-    // Clean up every 5 minutes
-    this.cleanupInterval = setInterval(
-      () => {
-        const now = Date.now();
-        let cleaned = 0;
-
-        for (const [key, entry] of this.store.entries()) {
-          if (now >= entry.resetTime) {
-            this.store.delete(key);
-            cleaned++;
-          }
-        }
-
-        if (cleaned > 0) {
-          this.logger.debug(`Cleaned up ${cleaned} expired rate limit entries`);
-        }
-      },
-      5 * 60 * 1000,
-    );
-
-    // Prevent the interval from keeping the process alive
-    if (this.cleanupInterval.unref) {
-      this.cleanupInterval.unref();
-    }
-  }
 }

package/src/core/modules/better-auth/core-better-auth-user.mapper.ts

@@ -658,7 +658,13 @@ export class CoreBetterAuthUserMapper {
             lastName: sessionUser.name.split(' ').slice(1).join(' '),
           }),
         ...(sessionUser.emailVerified !== undefined && { verified: sessionUser.emailVerified }),
-        ...(sessionUser.image && { avatar: sessionUser.image }),
+        // Deliberately NOT `avatar: sessionUser.image`. `image` is a Better-Auth BUILT-IN column,
+        // so it is client-writable through `POST /iam/update-user` — it is not covered by
+        // PROTECTED_INPUT_FALSE_KEYS, which only locks the fields this framework adds. Copying it
+        // here wrote an attacker-chosen value into `avatar` through a NATIVE driver update, past
+        // both the `S_NO_ONE` input restriction on the field and every Mongoose plugin. Since the
+        // avatar endpoint deletes the file the previous value points at, that turned "set your own
+        // image" into "delete any file in the store". The avatar upload is the only writer.
         iamId: sessionUser.id,
         updatedAt: new Date(),
         ...processedAdditionalData,

package/src/core/modules/file/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,108 @@
+# File Module Integration Checklist
+
+## Reference Implementation
+
+- Local: `node_modules/@lenne.tech/nest-server/src/server/modules/file/`
+- GitHub: https://github.com/lenneTech/nest-server/tree/develop/src/server/modules/file
+
+## Required Files (Create in Order)
+
+### 1. FileService
+
+**Create:** `src/server/modules/file/file.service.ts`
+**Copy from:** Reference implementation.
+
+Override `checkRights()` here if any file needs a per-file rule (owner, tenant, published flag).
+Roles alone cannot express that — see step 4.
+
+### 2. FileController
+
+**Create:** `src/server/modules/file/file.controller.ts`
+**Copy from:** Reference implementation.
+
+**Do NOT override `getFileById` / `getFile`.** Role metadata lives on the function object, so an
+override carries its own and opts the route out of `file.downloadRoles` permanently. Worse, an
+override that omits `@Get(...)` unregisters the route entirely — 404 for everyone, with no error
+and no warning. Add your project's own endpoints (upload, info, delete) alongside the inherited
+ones instead.
+
+### 3. FileModule
+
+**Create:** `src/server/modules/file/file.module.ts`
+**Copy from:** Reference implementation.
+
+Register `FileController` and `FileService`. `CoreFileResolver` is **not** registered by any core
+module — add it (or a subclass) yourself only if you want the GraphQL surface.
+
+### 4. Configure access
+
+**Edit:** `src/config.env.ts`
+
+```typescript
+file: {
+  storage: 'gridfs',                // 'filesystem' | 'gridfs' | 's3' — omit to derive it
+  storageDir: 'uploads/files',      // only for 'filesystem'
+  downloadRoles: [RoleEnum.ADMIN],  // GET /files/id/:id, GET /files/:filename, getFileInfo
+  uploadRoles:   [RoleEnum.ADMIN],  // uploadFile, uploadFiles (GraphQL)
+  deleteRoles:   [RoleEnum.ADMIN],  // deleteFile (GraphQL)
+},
+tus: {
+  roles: [RoleEnum.S_USER],         // resumable uploads
+},
+```
+
+**WHY you may not need `storage` at all:** left unset it is derived — `'s3'` when `s3.bucket` is
+configured, else `'gridfs'` when a database is, else `'filesystem'`. Set it when you want the choice
+pinned regardless of what else is in the config. Either way, an unavailable store **fails the boot**
+instead of silently falling back — see the module README, "Storage drivers".
+
+**WHY these default to ADMIN:** the file store is one bucket shared by every feature of the project
+— GridFS or S3, whichever `file.storage` selects — and the ObjectIds naming its blobs are not secrets:
+one upload of your own bounds the id space enough to brute-force neighbours. Anything wider is a
+decision worth making explicitly.
+
+**WHY roles are not enough:** they answer "may this caller reach the endpoint", never "may this
+caller have THIS file". For the latter, write an owner or tenant into the metadata at upload time
+(`createFile(file, { metadata: { ownerId } })`) and compare it in `checkRights()` via
+`getRawFileInfo()` / `getRawFileInfoByName()`. The public `getFileInfo()` strips restricted fields
+and is unusable for the decision. `getRawFileInfo()` checks S3 metadata first, then GridFS, so the
+same rule works under either `file.storage`.
+
+### 5. Decide how the frontend fetches files
+
+A browser `<img src>` or `<a download>` cannot send an `Authorization` header, and a CORS preflight
+sends no credentials at all. With anything stricter than `S_EVERYONE`, markup-driven requests only
+work when the session travels as a **cookie** on a same-site request.
+
+If some files are genuinely public and others are not, do not solve it with a role list. Either
+record a visibility flag in the metadata and branch in `checkRights()`, or expose a separate public
+route for exactly the public files and leave the core routes gated.
+
+## Verification Checklist
+
+- [ ] `pnpm run build` succeeds
+- [ ] Anonymous `GET /files/id/<id>` answers **401**
+- [ ] A signed-in non-privileged user answers **403** (not 401 — a 401 makes SPA auth layers log the
+      user out)
+- [ ] A caller holding a configured role downloads successfully
+- [ ] If you set `file.downloadRoles`, the value actually takes effect — if it does not, something
+      in your controller is overriding the member (see step 2)
+- [ ] TUS upload works for a signed-in user and is refused anonymously
+- [ ] The boot log names the driver you expect (`[CoreFileStorage] File storage: …`)
+- [ ] With `file.storage: 's3'`: a per-file rule in `checkRights()` still fires (it reads S3 metadata
+      via `getRawFileInfo()`), and any presigned-download expiry is short enough for your audience
+- [ ] With `file.storage: 'filesystem'`: `storageDir` is a **mounted volume** if the container is
+      ever restarted or scaled — the directory is pod-local
+- [ ] `OPTIONS /tus` answers without credentials (browser preflight)
+- [ ] Avatars / images in the frontend still render for the roles that should see them
+
+## Common Mistakes
+
+| Mistake                                            | Symptom                                  | Fix                                                                                                                    |
+| -------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Overriding `getFileById` to add Swagger decorators | `file.downloadRoles` silently ignored    | Don't override; document at class level                                                                                |
+| Overriding without re-declaring `@Get(...)`        | Route 404s for everyone, no error logged | Don't override                                                                                                         |
+| `downloadRoles: []`                                | Warning logged, default applied          | Use a non-empty array; `[]` would read as "no roles required" and open the route                                       |
+| Expecting `metadata` back from `getFileInfo()`     | `undefined`                              | Use `getRawFileInfo()` inside `checkRights()`                                                                          |
+| `downloadRoles: ['member']` with multiTenancy      | Works from code, fails from `<img>`      | Both file classes carry `@SkipTenantCheck()`; roles resolve against `user.roles`. Use `checkRights()` for tenant rules |
+| Signed-in user can upload via TUS but not download | 403 on their own file                    | `tus.roles` and `file.downloadRoles` are separate. Add an owner to the metadata and authorize per file                 |