@lenne.tech/nest-server 11.21.1 → 11.21.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.21.1",
+  "version": "11.21.3",
   "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/better-auth/core-better-auth-user.mapper.ts

@@ -1019,32 +1019,36 @@ export class CoreBetterAuthUserMapper {
       const migrationPercentage = totalUsers > 0 ? Math.round((fullyMigratedUsers / totalUsers) * 100 * 100) / 100 : 0;
 
       // Get emails of pending users (limit to 100)
-      const pendingUsers = await usersCollection
-        .aggregate([
-          {
-            $lookup: {
-              as: 'accounts',
-              foreignField: 'userId',
-              from: 'account',
-              localField: '_id',
-            },
-          },
-          {
-            $match: {
-              $or: [
-                { iamId: { $exists: false } },
-                { iamId: null },
-                {
-                  $and: [{ iamId: { $exists: true, $ne: null } }, { 'accounts.providerId': { $ne: 'credential' } }],
-                },
-              ],
-            },
-          },
-          { $limit: 100 },
-          { $project: { email: 1 } },
-        ])
+      // Two-phase approach: first get users without iamId (no $lookup needed),
+      // then check users with iamId but missing credential account
+      const usersWithoutIamId = await usersCollection
+        .find({ $or: [{ iamId: { $exists: false } }, { iamId: null }] })
+        .limit(100)
+        .project({ email: 1 })
         .toArray();
-      const pendingUserEmails = pendingUsers.map((u) => u.email).filter(Boolean);
+
+      const remaining = 100 - usersWithoutIamId.length;
+      let usersWithIamButNoAccount: { email?: string }[] = [];
+      if (remaining > 0) {
+        usersWithIamButNoAccount = await usersCollection
+          .aggregate([
+            { $match: { iamId: { $exists: true, $ne: null } } },
+            {
+              $lookup: {
+                as: 'accounts',
+                foreignField: 'userId',
+                from: 'account',
+                localField: '_id',
+              },
+            },
+            { $match: { 'accounts.providerId': { $ne: 'credential' } } },
+            { $limit: remaining },
+            { $project: { email: 1 } },
+          ])
+          .toArray();
+      }
+
+      const pendingUserEmails = [...usersWithoutIamId, ...usersWithIamButNoAccount].map((u) => u.email).filter(Boolean);
 
       // Can disable legacy auth only if ALL users are fully migrated
       const canDisableLegacyAuth = totalUsers > 0 && fullyMigratedUsers === totalUsers;

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

@@ -88,15 +88,19 @@ export class CoreBetterAuthService implements OnModuleInit {
     try {
       const db = this.connection.db;
 
-      // Session collection: token lookup (getSessionByToken) and user+expiry lookup (getActiveSessionForUser)
-      await db.collection('session').createIndex({ token: 1 });
-      await db.collection('session').createIndex({ userId: 1, expiresAt: 1 });
-
-      // Users collection: iamId lookup (mapSessionUser uses $or with email and iamId)
-      // email is typically already indexed by Mongoose schema, but iamId may not be
-      await db.collection('users').createIndex({ iamId: 1 }, { sparse: true });
-
-      this.logger.debug('Performance indices ensured on session and users collections');
+      // All indices are idempotent (no-op if already exists) and independent — run in parallel
+      await Promise.all([
+        // Session: token lookup (getSessionByToken) and user+expiry lookup (getActiveSessionForUser)
+        db.collection('session').createIndex({ token: 1 }),
+        db.collection('session').createIndex({ userId: 1, expiresAt: 1 }),
+        // Users: iamId lookup (mapSessionUser uses $or with email and iamId)
+        db.collection('users').createIndex({ iamId: 1 }, { sparse: true }),
+        // Account: userId lookup ($lookup in getMigrationStatus) and providerId filtering
+        db.collection('account').createIndex({ userId: 1 }),
+        db.collection('account').createIndex({ providerId: 1, userId: 1 }),
+      ]);
+
+      this.logger.debug('Performance indices ensured on session, users, and account collections');
     } catch (error) {
       // Non-fatal: indices improve performance but are not required for correctness
       this.logger.warn(`Could not create performance indices: ${error instanceof Error ? error.message : 'unknown'}`);

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

@@ -121,7 +121,18 @@ Normal (non-hierarchy) roles also work:
 async viewAuditLog(...) { ... }
 ```
 
-### 8. Skip Tenant Check for Non-Tenant Endpoints
+### 8. System Roles as OR Alternatives
+
+System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives **before** real role checks in `CoreTenantGuard`. If a system role grants access, real roles in the same `@Roles()` are alternatives, not requirements.
+
+When `X-Tenant-Id` header is present and a system role grants access:
+
+- `S_EVERYONE`: public — membership is optionally enriched but never blocks
+- `S_USER`/`S_VERIFIED`: membership is validated (403 if not a member; admin bypass applies)
+
+`@SkipTenantCheck()` suppresses membership validation for `S_USER`/`S_VERIFIED` paths — authentication/verification is still enforced, but no membership check runs even with a header present.
+
+### 9. Skip Tenant Check for Non-Tenant Endpoints
 
 Use `@SkipTenantCheck()` for endpoints that intentionally work without tenant context:
 
@@ -133,6 +144,23 @@ import { SkipTenantCheck, Roles, RoleEnum } from '@lenne.tech/nest-server';
 async listMyTenants() { ... }
 ```
 
+### 10. 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 +171,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 +191,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

@@ -138,9 +138,33 @@ Roles not in `roleHierarchy` use exact match — no higher role can compensate:
 async auditLog(@CurrentTenant() tenantId: string) { ... }
 ```
 
+### System Roles as OR Alternatives
+
+When `@Roles()` includes system roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`), `CoreTenantGuard` checks them **before** real roles in priority order. If a system role is satisfied, access is granted immediately — real roles in the same decorator are OR alternatives, not additional requirements.
+
+```typescript
+@Roles(RoleEnum.ADMIN)    // Class: admin can always access all methods
+@Controller('users')
+class UserController {
+  @Roles(RoleEnum.S_USER)  // Method: any authenticated user (extends class ADMIN via OR)
+  getProfile() { ... }     // → admin OR authenticated user can access
+
+  @Roles(RoleEnum.S_EVERYONE) // Method: public endpoint (extends class ADMIN via OR)
+  getPublicInfo() { ... }     // → anyone can access
+}
+```
+
+**Method-level system roles take precedence** for the system role check. Class `@Roles(S_EVERYONE)` does not make a method `@Roles(S_USER)` endpoint public — the method's `S_USER` applies.
+
+| System Role | No Header             | Header Present                                     |
+| ----------- | --------------------- | -------------------------------------------------- |
+| S_EVERYONE  | Pass (public)         | Pass + optional tenant context enrichment          |
+| S_USER      | Pass if authenticated | Pass if authenticated member; admin bypass applies |
+| S_VERIFIED  | Pass if verified      | Pass if verified member; admin bypass applies      |
+
 ### Tenant Context Rule
 
-**When a tenant header is present:** Only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass).
+**When a tenant header is present:** For real role checks, only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass). For system role checks (`S_USER`, `S_VERIFIED`), membership is validated to set tenant context (`tenantId`, `tenantRole`), but access depends on membership existence, not role level.
 
 **When no tenant header:** `user.roles` is checked instead. Hierarchy roles use level comparison, normal roles use exact match.
 
@@ -161,6 +185,7 @@ async listMyTenants() { ... }
 ```
 
 Note: `@SkipTenantCheck()` with hierarchy roles still checks `user.roles` (no tenant context).
+It also suppresses tenant membership validation for `S_USER`/`S_VERIFIED` system role paths — when set, these roles still enforce authentication/verification but skip the membership check even when a tenant header is present.
 
 ### Admin Bypass
 
@@ -207,6 +232,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 +287,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

@@ -47,16 +47,31 @@ interface CachedTenantIds {
  * - Plugin level: Safety net — ForbiddenException when tenantId-schema accessed without context
  *
  * Role check semantics:
+ * - System roles are OR alternatives, checked in order before real roles:
+ *   S_EVERYONE → immediate pass; S_USER → pass if authenticated; S_VERIFIED → pass if verified
+ * - When a system role grants access and X-Tenant-Id header is present, membership is still
+ *   validated to set tenant context (tenantId + tenantRole) on the request.
  * - Hierarchy roles (in roleHierarchy config): level comparison — higher includes lower
  * - Normal roles (not in roleHierarchy): exact match — no compensation by higher role
  * - 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
+ * 3. Read @Roles() metadata (method + class level)
+ * 4. System role early-exit checks (OR alternatives):
+ *    S_EVERYONE → pass immediately
+ *    S_USER → pass if authenticated (+ optional membership check when header present)
+ *    S_VERIFIED → pass if user is verified (+ optional membership check when header present)
+ * 5. @SkipTenantCheck → role check against user.roles, no tenant context
+ * 6. BetterAuth auto-skip (betterAuth.skipTenantCheck config + no header) → skip, no tenant context
  *
  * HEADER PRESENT:
  *   - System ADMIN (adminBypass: true) → set req.tenantId + isAdminBypass
@@ -177,33 +192,137 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
     const headerTenantId =
       rawHeader && typeof rawHeader === 'string' && rawHeader.length <= 128 ? rawHeader.trim() : undefined;
 
-    // Read @Roles() metadata and filter to non-system roles
+    // Two role sets for different purposes:
+    //
+    // 1. systemCheckRoles (method-takes-precedence): Used for system role early-returns.
+    //    Method-level system roles override class-level ones to prevent e.g. class @Roles(S_EVERYONE)
+    //    from making a method @Roles(S_USER) endpoint public.
+    //
+    // 2. roles (OR/merged): Used for real role checks (checkableRoles).
+    //    Class-level roles serve as a base that method-level roles extend.
+    //    E.g., class @Roles(ADMIN) + method @Roles('editor') → both are alternatives.
+    //
+    // S_EVERYONE check — access is always granted; no authentication or membership required.
+    //
+    // Header handling for S_EVERYONE:
+    //   - No header → return true immediately (no tenant context needed)
+    //   - Header present + authenticated user that IS a member → optionally enrich with tenant
+    //     context (sets request.tenantId/tenantRole) so downstream consumers can use it.
+    //     Access is NOT blocked if user is not a member — S_EVERYONE means public access.
     const rolesMetadata = this.reflector.getAll<string[][]>('roles', [context.getHandler(), context.getClass()]);
     const roles = mergeRolesMetadata(rolesMetadata);
+    const methodRoles: string[] = rolesMetadata[0] ?? [];
+    const systemCheckRoles = methodRoles.length > 0 ? methodRoles : roles;
+
+    // Defense-in-depth: S_NO_ONE is normally caught by RolesGuard/BetterAuthRolesGuard upstream,
+    // but guard it here too in case CoreTenantGuard runs standalone (e.g., custom guard chains).
+    if (roles.includes(RoleEnum.S_NO_ONE)) {
+      throw new ForbiddenException('Access denied');
+    }
+
+    const sEveryoneGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_EVERYONE);
+    if (sEveryoneGrantsAccess) {
+      // Optionally enrich with tenant context when header is present and user is an active member.
+      // Never block access — S_EVERYONE endpoints are always public.
+      if (headerTenantId && request.user?.id) {
+        const membership = await this.findMembershipCached(request.user.id, headerTenantId);
+        if (membership) {
+          request.tenantId = headerTenantId;
+          request.tenantRole = membership.role as string;
+        }
+      }
+      return true;
+    }
 
     const user = request.user;
     const adminBypass = config.adminBypass !== false;
     const isAdmin = adminBypass && user?.roles?.includes(RoleEnum.ADMIN);
 
-    // Filter to checkable (non-system) roles only when needed (avoids array allocation on fast paths)
-    const hasNonSystemRoles = roles.some((r) => !isSystemRole(r));
-    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, [
+    // Read @SkipTenantCheck early — it suppresses tenant membership validation for system roles too.
+    // When set, S_USER and S_VERIFIED still enforce authentication/verification, but no membership
+    // check is performed even when a tenant header is present.
+    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');
-        }
+
+    // S_USER check — any authenticated user satisfies this system role.
+    //
+    // OR semantics: if S_USER is in the active role set, a logged-in user gets through.
+    // Real roles in the same @Roles() are ignored when S_USER is satisfied (they are alternatives).
+    // Example: @Roles(S_USER, 'owner') → a plain logged-in user passes (owner is an alternative, not required).
+    //
+    // Tenant header behavior: when X-Tenant-Id is present and @SkipTenantCheck is NOT set,
+    // membership is validated so that tenant context (tenantId, tenantRole) is set on the request.
+    // A non-member will still get 403 when a tenant header is provided (unless @SkipTenantCheck).
+    const sUserGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_USER);
+    if (sUserGrantsAccess) {
+      if (!user) {
+        throw new ForbiddenException('Authentication required');
+      }
+      if (headerTenantId && !hasSkipDecorator) {
+        return this.handleSystemRoleWithTenantHeader(user, headerTenantId, request, isAdmin);
+      }
+      return true;
+    }
+
+    // S_VERIFIED check — any verified authenticated user satisfies this system role.
+    //
+    // A user is considered verified when any of these properties is truthy:
+    //   user.verified, user.verifiedAt, user.emailVerified
+    //
+    // Tenant header behavior: same as S_USER — membership is validated when header is present
+    // (unless @SkipTenantCheck is set).
+    const sVerifiedGrantsAccess: boolean = systemCheckRoles.includes(RoleEnum.S_VERIFIED);
+    if (sVerifiedGrantsAccess) {
+      if (!user) {
+        throw new ForbiddenException('Authentication required');
+      }
+      const isVerified = !!(user.verified || user.verifiedAt || user.emailVerified);
+      if (!isVerified) {
+        throw new ForbiddenException('Verification required');
+      }
+      if (headerTenantId && !hasSkipDecorator) {
+        return this.handleSystemRoleWithTenantHeader(user, headerTenantId, request, isAdmin);
       }
       return true;
     }
 
+    // Extract checkable (non-system) roles from the merged set.
+    // System roles that grant access (S_EVERYONE, S_USER, S_VERIFIED) have been
+    // early-returned above. Remaining system roles (S_SELF, S_CREATOR) are object-level
+    // and handled by interceptors.
+    const checkableRoles = roles.filter((r: string) => !isSystemRole(r));
+
+    const minRequiredLevel = checkableRoles.length > 0 ? getMinRequiredLevel(checkableRoles) : undefined;
+
+    // @SkipTenantCheck decorator → no tenant context, but role check against user.roles
+    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);
+      }
+    }
+
     // === HEADER PRESENT ===
     if (headerTenantId) {
       // Admin bypass: set req.tenantId so plugin filters (read by RequestContextMiddleware
@@ -212,7 +331,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.debug(`Admin bypass: user ${user.id} accessing tenant ${safeTenantId} (required: ${requiredRole})`);
         return true;
       }
 
@@ -438,4 +559,90 @@ export class CoreTenantGuard implements CanActivate, OnModuleDestroy {
       }
     }
   }
+
+  /**
+   * Validate tenant membership for a request that was granted access via a system role
+   * (S_USER or S_VERIFIED). When a tenant header is present, the user must be an active member
+   * of that tenant — unless the user is an admin with adminBypass enabled.
+   *
+   * On success, sets request.tenantId and request.tenantRole for downstream consumers.
+   *
+   * @param user - The authenticated request user
+   * @param headerTenantId - The validated, non-empty tenant ID from the request header
+   * @param request - The HTTP/GraphQL request object
+   * @param isAdmin - Whether the user has admin bypass privileges
+   */
+  private async handleSystemRoleWithTenantHeader(
+    user: any,
+    headerTenantId: string,
+    request: any,
+    isAdmin: boolean,
+  ): Promise<true> {
+    // Admin bypass: same behavior as the HEADER PRESENT admin path below
+    if (isAdmin) {
+      request.tenantId = headerTenantId;
+      request.isAdminBypass = true;
+      const safeTenantId = headerTenantId.replace(/[\r\n\t]/g, '_');
+      this.logger.debug(`Admin bypass (system-role path): user ${user.id} accessing tenant ${safeTenantId}`);
+      return true;
+    }
+
+    const membership = await this.findMembershipCached(user.id, headerTenantId);
+    if (!membership) {
+      throw new ForbiddenException('Not a member of this tenant');
+    }
+    request.tenantId = headerTenantId;
+    request.tenantRole = membership.role as string;
+    return true;
+  }
+
+  /**
+   * 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;
+  }
 }