@lenne.tech/nest-server 11.21.1 → 11.21.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.21.1",
+  "version": "11.21.2",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -97,7 +97,7 @@
     "class-validator": "0.15.1",
     "compression": "1.8.1",
     "cookie-parser": "1.4.7",
-    "dotenv": "17.3.1",
+    "dotenv": "17.4.0",
     "ejs": "5.0.1",
     "express": "5.2.1",
     "graphql": "16.13.2",
@@ -106,7 +106,7 @@
     "graphql-upload": "15.0.2",
     "js-sha256": "0.11.1",
     "json-to-graphql-query": "2.3.0",
-    "lodash": "4.17.23",
+    "lodash": "4.18.1",
     "mongodb": "7.1.1",
     "mongoose": "9.3.3",
     "multer": "2.1.1",
@@ -125,7 +125,7 @@
     "@nestjs/cli": "11.0.17",
     "@nestjs/schematics": "11.0.10",
     "@nestjs/testing": "11.1.17",
-    "@swc/cli": "0.8.0",
+    "@swc/cli": "0.8.1",
     "@swc/core": "1.15.21",
     "@types/compression": "1.8.1",
     "@types/cookie-parser": "1.4.10",
@@ -182,10 +182,7 @@
       "rollup@>=4.0.0 <4.60.1": "4.60.1",
       "ajv@<6.14.0": "6.14.0",
       "ajv@>=7.0.0-alpha.0 <8.18.0": "8.18.0",
-      "file-type@>=13.0.0 <21.3.2": "21.3.2",
       "undici@>=7.0.0 <7.24.0": "7.24.3",
-      "yauzl@<3.2.1": "3.2.1",
-      "flatted@<=3.4.1": "3.4.2",
       "srvx@<0.11.13": "0.11.13",
       "handlebars@>=4.0.0 <4.7.9": "4.7.9",
       "brace-expansion@<1.1.13": "1.1.13",
@@ -193,7 +190,8 @@
       "picomatch@<2.3.2": "2.3.2",
       "picomatch@>=4.0.0 <4.0.4": "4.0.4",
       "path-to-regexp@>=8.0.0 <8.4.0": "8.4.1",
-      "kysely@>=0.26.0 <0.28.15": "0.28.15"
+      "kysely@>=0.26.0 <0.28.15": "0.28.15",
+      "lodash@>=4.0.0 <4.18.0": "4.18.1"
     },
     "onlyBuiltDependencies": [
       "bcrypt",

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

@@ -2401,6 +2401,32 @@ interface IBetterAuthBase {
    */
   secret?: string;
 
+  /**
+   * Skip tenant validation on IAM endpoints.
+   *
+   * When true (default), IAM endpoints (sign-up, sign-in, sign-out, session, etc.)
+   * skip the CoreTenantGuard tenant membership check. This is the correct default
+   * because authentication typically happens BEFORE tenant context is established.
+   *
+   * Set to false for scenarios where tenant context is known at login time:
+   * - Subdomain-based tenancy (tenant-a.crm.example.com)
+   * - Invite links with embedded tenant (crm.example.com/invite/abc123)
+   * - Tenant-specific login pages (crm.example.com/login?org=tenant-a)
+   * - Tenant-specific auth policies (e.g., one tenant requires SSO)
+   *
+   * @default true
+   *
+   * @example
+   * ```typescript
+   * // Default: IAM endpoints skip tenant validation (correct for most cases)
+   * betterAuth: { skipTenantCheck: true }
+   *
+   * // Tenant-aware authentication (subdomain-based tenancy, invite links, etc.)
+   * betterAuth: { skipTenantCheck: false }
+   * ```
+   */
+  skipTenantCheck?: boolean;
+
   /**
    * Sign-up checks configuration.
    *

package/src/core/modules/better-auth/README.md

@@ -2137,4 +2137,23 @@ For frontend integration with Better-Auth, see the **[Integration Checklist](./I
 1. **Password Hashing**: Always hash passwords with SHA256 client-side before sending
 2. **2FA Redirect**: Check for `twoFactorRedirect: true` in sign-in response
 3. **Passkey Session**: Passkey auth returns session without user - call `validateSession()` to fetch user data
-4. **Credentials**: Use `credentials: 'include'` for cross-origin cookie handling
+4. **Credentials**: Use `credentials: 'include'` for cross-origin cookie handling
+
+---
+
+## Multi-Tenancy Integration
+
+When both BetterAuth and Multi-Tenancy (`multiTenancy: {}`) are active, IAM endpoints
+automatically skip tenant validation by default (`skipTenantCheck: true`). This is the
+correct default — authentication happens before tenant context is established.
+
+For tenant-aware authentication scenarios (subdomain-based tenancy, invite links, etc.),
+set `skipTenantCheck: false`:
+
+```typescript
+betterAuth: {
+  skipTenantCheck: false, // IAM endpoints require valid X-Tenant-Id header
+}
+```
+
+See the [CoreTenantModule README](../tenant/README.md#betterauth-iam-integration) for details.

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

@@ -133,6 +133,23 @@ import { SkipTenantCheck, Roles, RoleEnum } from '@lenne.tech/nest-server';
 async listMyTenants() { ... }
 ```
 
+### 9. BetterAuth (IAM) Coexistence
+
+When both `multiTenancy` and `betterAuth` are active, IAM endpoints (sign-in, sign-up, session, etc.)
+automatically skip tenant validation when no `X-Tenant-Id` header is sent (`betterAuth.skipTenantCheck: true`, default).
+If a header IS present, normal membership validation runs.
+
+For tenant-aware authentication (subdomain-based, invite links, SSO per tenant), opt out:
+
+```typescript
+// config.env.ts
+betterAuth: {
+  skipTenantCheck: false, // IAM endpoints require valid X-Tenant-Id header
+}
+```
+
+See [Tenant README — BetterAuth Integration](./README.md#betterauth-iam-integration) for details.
+
 ## Verification Checklist
 
 - [ ] `pnpm run build` succeeds
@@ -143,6 +160,7 @@ async listMyTenants() { ... }
 - [ ] Non-member gets 403 "Not a member of this tenant"
 - [ ] Unauthenticated + header → 403 "Authentication required for tenant access"
 - [ ] Public endpoint accessing tenantId-schema without context throws 403 (Safety Net)
+- [ ] IAM endpoints work without `X-Tenant-Id` header when `skipTenantCheck: true` (default)
 
 ## Security
 
@@ -162,4 +180,5 @@ async listMyTenants() { ... }
 | Querying membership without bypass               | Empty results due to tenant filter | Use `RequestContext.runWithBypassTenantGuard()`                            |
 | Public endpoint accessing tenantId-schema        | 403 Safety Net exception           | Use `@SkipTenantCheck()` + `RequestContext.runWithBypassTenantGuard()`     |
 | Passing user-supplied tenantId to create()       | Cross-tenant write possible        | Let plugin auto-set tenantId from context                                  |
-| Custom hierarchy doesn't match config            | Roles fail unexpectedly            | Ensure `createHierarchyRoles()` input matches `multiTenancy.roleHierarchy` |
+| Custom hierarchy doesn't match config            | Roles fail unexpectedly            | Ensure `createHierarchyRoles()` input matches `multiTenancy.roleHierarchy` |
+| `@SkipTenantCheck()` on BetterAuth handler       | Redundant since v11.21.2           | Remove — auto-skip handles this via `betterAuth.skipTenantCheck` (default) |

package/src/core/modules/tenant/README.md

@@ -207,6 +207,7 @@ multiTenancy: {
 ```
 
 **Cache behavior:**
+
 - **Positive-only:** Only active memberships are cached. Non-member lookups always hit the DB (security-first).
 - **Auto-invalidation:** `CoreTenantService.addMember/removeMember/updateMemberRole` automatically invalidate the cache.
 - **Config-change detection:** Cache is flushed when `multiTenancy` config changes (e.g., `roleHierarchy` update).
@@ -261,8 +262,40 @@ export class TenantMemberController {
 }
 ```
 
+### BetterAuth (IAM) Integration
+
+When both Multi-Tenancy and BetterAuth are active, IAM endpoints (sign-up, sign-in, sign-out,
+session, etc.) automatically skip tenant validation by default. This is because authentication
+typically happens before tenant context is established.
+
+**Behavior with `skipTenantCheck: true` (default):**
+
+- No `X-Tenant-Id` header → skip tenant validation, proceed without tenant context
+- `X-Tenant-Id` header IS provided → validate normally (membership check, tenant context set)
+
+The tenant is optional but respected when present. This allows tenant-aware auth flows
+(subdomain-based, invite links, etc.) to coexist with the default cross-tenant behavior.
+
+**Configuration:**
+
+```typescript
+// config.env.ts — Default: skip tenant validation on IAM endpoints (most projects)
+betterAuth: {
+  skipTenantCheck: true, // (default) No X-Tenant-Id header → skip; header present → validate
+}
+
+// config.env.ts — Tenant-aware auth (subdomain-based, invite links, SSO per tenant)
+betterAuth: {
+  skipTenantCheck: false, // IAM endpoints ALWAYS require valid X-Tenant-Id header
+}
+```
+
+When `skipTenantCheck: false`, IAM endpoints will require a valid `X-Tenant-Id` header
+and the user must be a member of that tenant for protected endpoints.
+
 ## Related
 
 - [Integration Checklist](./INTEGRATION-CHECKLIST.md)
 - [Configurable Features](../../../.claude/rules/configurable-features.md)
+
 - [Request Lifecycle](../../../docs/REQUEST-LIFECYCLE.md)

package/src/core/modules/tenant/core-tenant.guard.ts

@@ -52,11 +52,18 @@ interface CachedTenantIds {
  * - Tenant context (header present): checks against membership.role only (user.roles ignored)
  * - No tenant context: checks against user.roles
  *
+ * BetterAuth (IAM) auto-skip behavior (skipTenantCheck config, default: true):
+ * - No X-Tenant-Id header: skip tenant validation entirely (auth before tenant is the expected case)
+ * - X-Tenant-Id header IS present: fall through to normal validation (membership check + context)
+ * This allows tenant-aware auth flows (subdomain-based, invite links, etc.) to coexist with
+ * the default cross-tenant behavior. The tenant is optional but respected when provided.
+ *
  * Flow:
  * 1. Config check: multiTenancy enabled?
  * 2. Parse header (X-Tenant-Id, max 128 chars, trimmed)
  * 3. @SkipTenantCheck → role check against user.roles, no tenant context
  * 4. Read @Roles() metadata, filter out system roles
+ * 5. BetterAuth auto-skip (betterAuth.skipTenantCheck config + no header) → skip, no tenant context
  *
  * HEADER PRESENT:
  *   - System ADMIN (adminBypass: true) → set req.tenantId + isAdminBypass
@@ -190,18 +197,35 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
     const checkableRoles = hasNonSystemRoles ? roles.filter((r) => !isSystemRole(r)) : [];
     const minRequiredLevel = checkableRoles.length > 0 ? getMinRequiredLevel(checkableRoles) : undefined;
 
-    // @SkipTenantCheck → no tenant context, but role check against user.roles
-    const skipTenantCheck = this.reflector.getAllAndOverride<boolean>(SKIP_TENANT_CHECK_KEY, [
+    // @SkipTenantCheck decorator → no tenant context, but role check against user.roles
+    const hasSkipDecorator = this.reflector.getAllAndOverride<boolean>(SKIP_TENANT_CHECK_KEY, [
       context.getHandler(),
       context.getClass(),
     ]);
-    if (skipTenantCheck) {
-      if (checkableRoles.length > 0 && user) {
-        if (!isAdmin && !checkRoleAccess(checkableRoles, user.roles, undefined)) {
-          throw new ForbiddenException('Insufficient role');
-        }
+    if (hasSkipDecorator) {
+      return this.skipWithUserRoleCheck(checkableRoles, user, isAdmin);
+    }
+
+    // Auto-skip tenant check for BetterAuth (IAM) handlers when configured,
+    // but ONLY when no X-Tenant-Id header is present.
+    // - No header: skip tenant validation (auth before tenant is the expected case for most projects)
+    // - Header present: fall through to normal validation (membership check, tenant context set)
+    // This allows tenant-aware auth scenarios to coexist with the default cross-tenant behavior.
+    // Default config: betterAuth.skipTenantCheck = true (note: distinct from @SkipTenantCheck decorator above).
+    if (!hasSkipDecorator && !headerTenantId && this.isBetterAuthHandler(context)) {
+      const betterAuthConfig = ConfigService.configFastButReadOnly?.betterAuth;
+      // Boolean shorthand: `betterAuth: true` → skip, `betterAuth: false` → no skip
+      const shouldSkip =
+        betterAuthConfig !== null && betterAuthConfig !== undefined && typeof betterAuthConfig === 'object'
+          ? betterAuthConfig.skipTenantCheck !== false // default: true
+          : betterAuthConfig !== false; // true/undefined → skip; false → no skip
+
+      if (shouldSkip) {
+        this.logger.debug(
+          `BetterAuth auto-skip: ${context.getClass().name}::${context.getHandler().name} — no X-Tenant-Id header, skipping tenant validation`,
+        );
+        return this.skipWithUserRoleCheck(checkableRoles, user, isAdmin);
       }
-      return true;
     }
 
     // === HEADER PRESENT ===
@@ -212,7 +236,9 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
         request.tenantId = headerTenantId;
         request.isAdminBypass = true;
         const requiredRole = checkableRoles.length > 0 ? checkableRoles.join(',') : 'none';
-        this.logger.log(`Admin bypass: user ${user.id} accessing tenant ${headerTenantId} (required: ${requiredRole})`);
+        // Sanitize control characters to prevent log injection
+        const safeTenantId = headerTenantId.replace(/[\r\n\t]/g, '_');
+        this.logger.log(`Admin bypass: user ${user.id} accessing tenant ${safeTenantId} (required: ${requiredRole})`);
         return true;
       }
 
@@ -438,4 +464,54 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
       }
     }
   }
+
+  /**
+   * Skip tenant validation but still check non-system roles against user.roles.
+   * Shared by @SkipTenantCheck decorator path and BetterAuth auto-skip path.
+   */
+  private skipWithUserRoleCheck(checkableRoles: string[], user: any, isAdmin: boolean): true {
+    if (checkableRoles.length > 0) {
+      // Defense-in-depth: reject unauthenticated access even if RolesGuard is absent
+      if (!user) {
+        throw new ForbiddenException('Authentication required');
+      }
+      if (!isAdmin && !checkRoleAccess(checkableRoles, user.roles, undefined)) {
+        throw new ForbiddenException('Insufficient role');
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Check if the current request is handled by a BetterAuth (IAM) handler
+   * (controller or resolver). Used for auto-skip tenant check on IAM endpoints.
+   *
+   * Uses require() instead of import to avoid a circular dependency:
+   * tenant module → better-auth module (which may depend on tenant module indirectly).
+   * The require() is lazy and resolved only when needed (Node.js caches the result).
+   */
+  private isBetterAuthHandler(context: ExecutionContext): boolean {
+    const handler = context.getClass();
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { CoreBetterAuthController } =
+        require('../better-auth/core-better-auth.controller') as typeof import('../better-auth/core-better-auth.controller');
+      if (handler === CoreBetterAuthController || handler.prototype instanceof CoreBetterAuthController) {
+        return true;
+      }
+    } catch {
+      /* BetterAuth controller not available */
+    }
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { CoreBetterAuthResolver } =
+        require('../better-auth/core-better-auth.resolver') as typeof import('../better-auth/core-better-auth.resolver');
+      if (handler === CoreBetterAuthResolver || handler.prototype instanceof CoreBetterAuthResolver) {
+        return true;
+      }
+    } catch {
+      /* BetterAuth resolver not available */
+    }
+    return false;
+  }
 }