@lenne.tech/nest-server 11.41.3 → 11.41.5

package/src/core/modules/auth/guards/roles.guard.ts

@@ -14,11 +14,13 @@ import { resolveGuardRequest } from '../../../common/helpers/execution-context-r
 import { firstValueFrom, isObservable } from 'rxjs';
 
 import { RoleEnum } from '../../../common/enums/role.enum';
+import { ApiTokenKind } from '../../api-token/core-api-token.constants';
+import { enforceApiTokenRoute } from '../../api-token/core-api-token.helpers';
 import { BetterAuthTokenService } from '../../better-auth/better-auth-token.service';
 import { BetterAuthenticatedUser } from '../../better-auth/better-auth.types';
 import { CoreBetterAuthService } from '../../better-auth/core-better-auth.service';
 import { ErrorCode } from '../../error-code';
-import { isMultiTenancyActive, isSystemRole, mergeRolesMetadata } from '../../tenant/core-tenant.helpers';
+import { delegatesRolesToTenantGuard, isSystemRole, mergeRolesMetadata } from '../../tenant/core-tenant.helpers';
 import { AuthGuardStrategy } from '../auth-guard-strategy.enum';
 import { ExpiredTokenException } from '../exceptions/expired-token.exception';
 import { InvalidTokenException } from '../exceptions/invalid-token.exception';
@@ -145,6 +147,25 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
       throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
+    // API tokens are decided BEFORE the public-route shortcut below: a token is denied on every route
+    // that does not declare @ApiTokenScopes(), public ones included (see core-api-token.helpers).
+    // A tenant token is fully decided there. A user token was authenticated by CoreApiTokenMiddleware,
+    // so Passport — which only knows JWTs — must not see it: its user goes straight to the role checks.
+    const apiTokenKind = enforceApiTokenRoute({
+      controllerClass: context.getClass(),
+      handler: context.getHandler(),
+      request: this.getRequest(context),
+    });
+    if (apiTokenKind === ApiTokenKind.TENANT) {
+      return true;
+    }
+    if (apiTokenKind === ApiTokenKind.USER) {
+      if (roles.some((value) => !!value) && !roles.includes(RoleEnum.S_EVERYONE)) {
+        this.handleRequest(null, this.getRequest(context).user, null, context);
+      }
+      return true;
+    }
+
     // If no roles required, or S_EVERYONE is set, allow access without authentication
     // This allows public endpoints (without @Roles decorator or with S_EVERYONE) to work
     //
@@ -323,7 +344,7 @@ export class RolesGuard extends AuthGuard(AuthGuardStrategy.JWT) {
       // When multiTenancy active: pass through ALL non-system roles to CoreTenantGuard.
       // CoreTenantGuard handles hierarchy (level) and non-hierarchy (exact) checks
       // against membership.role (tenant) or user.roles (no tenant).
-      if (user && isMultiTenancyActive() && roles.some((r) => !isSystemRole(r))) {
+      if (user && delegatesRolesToTenantGuard() && roles.some((r) => !isSystemRole(r))) {
         return user;
       }
 

package/src/core/modules/better-auth/better-auth-roles.guard.ts

@@ -11,8 +11,10 @@ import { GqlExecutionContext } from '@nestjs/graphql';
 import { resolveGuardRequest } from '../../common/helpers/execution-context-request.helper';
 
 import { RoleEnum } from '../../common/enums/role.enum';
+import { ApiTokenKind } from '../api-token/core-api-token.constants';
+import { enforceApiTokenRoute } from '../api-token/core-api-token.helpers';
 import { ErrorCode } from '../error-code';
-import { isMultiTenancyActive, isSystemRole, mergeRolesMetadata } from '../tenant/core-tenant.helpers';
+import { delegatesRolesToTenantGuard, isSystemRole, mergeRolesMetadata } from '../tenant/core-tenant.helpers';
 import { BetterAuthTokenService } from './better-auth-token.service';
 import { BetterAuthenticatedUser } from './better-auth.types';
 import { getBetterAuthTokenService } from './core-better-auth.registry';
@@ -97,13 +99,25 @@ export class BetterAuthRolesGuard implements CanActivate {
       throw new ForbiddenException(ErrorCode.ACCESS_DENIED);
     }
 
+    // API tokens are decided BEFORE the public-route shortcut below: a token is denied on every route
+    // that does not declare @ApiTokenScopes(), public ones included. A tenant token is fully decided
+    // there; a user token continues through the ordinary checks as its user (see core-api-token.helpers).
+    const request = this.getRequest(context);
+    const apiTokenKind = enforceApiTokenRoute({
+      controllerClass: context.getClass(),
+      handler: context.getHandler(),
+      request,
+    });
+    if (apiTokenKind === ApiTokenKind.TENANT) {
+      return true;
+    }
+
     // If no roles required, or S_EVERYONE is set, allow access without authentication
     if (!roles || !roles.some((value) => !!value) || roles.includes(RoleEnum.S_EVERYONE)) {
       return true;
     }
 
-    // Get request and check for user (set by BetterAuth middleware)
-    const request = this.getRequest(context);
+    // Check for user (set by BetterAuth middleware or CoreApiTokenMiddleware)
     let user = request?.user;
 
     // If user isn't set (e.g., middleware didn't run in test environment),
@@ -129,7 +143,7 @@ export class BetterAuthRolesGuard implements CanActivate {
     // When multiTenancy active: pass through ALL non-system roles to CoreTenantGuard.
     // CoreTenantGuard handles hierarchy (level) and non-hierarchy (exact) checks
     // against membership.role (tenant) or user.roles (no tenant).
-    if (isMultiTenancyActive() && roles.some((r) => !isSystemRole(r))) {
+    if (delegatesRolesToTenantGuard() && roles.some((r) => !isSystemRole(r))) {
       return true;
     }
 

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

@@ -1,6 +1,7 @@
 import { Injectable, Logger, NestMiddleware } from '@nestjs/common';
 import { NextFunction, Request, Response } from 'express';
 
+import { hasApiTokenCredential } from '../api-token/core-api-token.helpers';
 import { isLegacyJwt } from './core-better-auth-token.helper';
 import { BetterAuthSessionUser, CoreBetterAuthUserMapper, MappedUser } from './core-better-auth-user.mapper';
 import { convertExpressHeaders, extractSessionToken } from './core-better-auth-web.helper';
@@ -54,6 +55,13 @@ export class CoreBetterAuthMiddleware implements NestMiddleware {
       return next();
     }
 
+    // Leave API tokens to CoreApiTokenMiddleware (recognised by their configured prefix, `apiTokens`).
+    // Not even the cookie fallback may run: a request that presents a token is a token request, and a
+    // session cookie riding along must not turn it into a session request with the user's full rights.
+    if (hasApiTokenCredential(req)) {
+      return next();
+    }
+
     // Strategy 1: Try Authorization header (Bearer token) - takes precedence
     // The Authorization header is explicitly set by the client, so it should
     // override cookies which are implicitly sent by the browser.

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

@@ -34,6 +34,7 @@ import { CoreBetterAuthChallengeService } from './core-better-auth-challenge.ser
 import { CoreBetterAuthEmailVerificationService } from './core-better-auth-email-verification.service';
 import { CoreBetterAuthRateLimitMiddleware } from './core-better-auth-rate-limit.middleware';
 import { CoreBetterAuthRateLimiter } from './core-better-auth-rate-limiter.service';
+import { revokeApiTokensOfUser } from '../api-token/core-api-token.registry';
 import { getInFlightResetPassword } from './core-better-auth-password-reset.registry';
 import { CoreBetterAuthSignUpValidatorService } from './core-better-auth-signup-validator.service';
 import { CoreBetterAuthUserMapper } from './core-better-auth-user.mapper';
@@ -825,6 +826,33 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
    * They access the service via static reference since Better-Auth hooks run outside DI context.
    * @internal
    */
+  /**
+   * Revoke the user's API tokens after an IAM password reset — only when the reset also ends the
+   * user's sessions (`betterAuth.emailAndPassword.revokeSessionsOnPasswordReset`). A no-op without
+   * `apiTokens`. Never fails the reset: the credential is already written, so a failure is reported,
+   * not thrown. `protected` so a project can decide differently.
+   */
+  protected static async revokeApiTokensAfterPasswordReset(
+    user: { email?: string; id?: string } | undefined,
+  ): Promise<void> {
+    const revokeSessions =
+      this.configServiceInstance?.getFastButReadOnly('betterAuth.emailAndPassword.revokeSessionsOnPasswordReset') ===
+      true;
+    if (!revokeSessions || (!user?.email && !user?.id)) {
+      return;
+    }
+    try {
+      const revoked = await revokeApiTokensOfUser({ email: user.email, iamId: user.id });
+      if (revoked) {
+        this.logger.log(`Revoked ${revoked} API token(s) after the password reset of ${maskEmail(user.email ?? '')}`);
+      }
+    } catch (error) {
+      this.logger.error(
+        `Could not revoke the API tokens after a password reset: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
   /**
    * `protected` rather than `private`: the callbacks it returns include `onPasswordReset`, which
    * decides what mirroring a reset into the legacy store means for a deployment. A project with a
@@ -860,6 +888,11 @@ export class CoreBetterAuthModule implements NestModule, OnModuleInit {
         }
       },
       onPasswordReset: async ({ user }) => {
+        // A reset that ends the user's sessions ends their API tokens too — a user token is a session
+        // in all but lifetime, and left alive it keeps the credential the reset was meant to retire
+        // working. Before the legacy mirror below, which returns early on IAM-only deployments.
+        await this.revokeApiTokensAfterPasswordReset(user);
+
         // Mirror the new password into the legacy bcrypt store, so a deployment running
         // Legacy Auth next to IAM does not keep the OLD password valid on the legacy path
         // after a reset — including a reset performed BECAUSE the old one leaked.

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

@@ -240,9 +240,12 @@ How the lock works, regardless of which entry point uses it:
 
 This ensures that in a cluster with multiple nodes, migrations run on only one machine at a time.
 
-**Active by default for `migrate up`.** Stores built by `createMigrationStore()` use the
-lock collection `migrations_lock` unless another name is given, and `MigrationRunner.up()`
-(the CLI's `up` command) acquires that lock around the whole run. This matters because the
+**Active by default for `migrate up` and `migrate down`.** Stores built by `createMigrationStore()` use the
+lock collection `migrations_lock` unless another name is given, and `MigrationRunner.up()` / `.down()`
+(the CLI's `up` / `down` commands) acquire that lock around the whole run. `down` joined later (DEV-2728): a
+rollback is typically run while a deploy is failing, i.e. while replicas restart and each boots into
+`migrate up` — outside the lock the two rewrote the migration state concurrently. `migrate list` only
+reads and stays unlocked. This matters because the
 container entrypoint runs migrations on **every** boot: without the lock, N replicas
 starting together each read the same empty state and apply the same pending migration N
 times. A replica that waited re-reads the state inside the lock and finds nothing pending.
@@ -530,10 +533,15 @@ Enable it via any of:
 | `NSC__MIGRATE__STRICT=1\|true\|yes` env var  | CLI **and** programmatic runners (resolved in the `MigrationRunner` constructor) |
 | `new MigrationRunner({ strict: true, ... })` | programmatic                                                                     |
 
-**Recommended for production images:** set `NSC__MIGRATE__STRICT=true` in the container
-environment. In an immutable image, a recorded-but-missing migration file can only mean a
-broken build (empty/miscopied `migrations/` directory) or a state-store mismatch (wrong
-database) — both are conditions where refusing to boot is correct.
+**Off by default, on only when a project explicitly wants it.** Deleting migration files that
+ran everywhere is a normal practice — a new instance never needs them, and git history restores
+them if ever needed — and under strict mode every such deletion would refuse the boot. Turn it on
+for images that must carry the FULL migration history. Where the history is complete by
+design, a recorded-but-missing file can only mean a broken build (empty/miscopied
+`migrations/` directory) or a state-store mismatch (wrong database), and refusing to boot is
+correct. This is independent of the entrypoint's failure policy: a migration that RAN AND
+FAILED aborts the container start by default (`MIGRATIONS_ALLOW_FAILURE=true` opts out per
+deploy), whatever `strict` says.
 
 ### Programmatic usage (MigrationRunner)
 

package/src/core/modules/migrate/migration-runner.ts

@@ -297,8 +297,17 @@ export class MigrationRunner {
 
   /**
    * Rollback the last migration (down)
+   *
+   * Serialized through the same lock as `up()`. A rollback is typically run while a deploy
+   * is failing, i.e. exactly while replicas restart and each boots into `migrate up`; outside
+   * the lock the two would read and rewrite the migration state concurrently, and one of them
+   * would save a state that no longer matches the database.
    */
   async down(): Promise<void> {
+    await withMigrationLock(this.options.stateStore, () => this.runDown());
+  }
+
+  protected async runDown(): Promise<void> {
     const { _endMigration, _startMigration } = await import('./helpers/migration.helper');
 
     const state = await this.options.stateStore.loadAsync();

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

@@ -357,6 +357,23 @@ betterAuth: {
 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.
 
+## API Tokens
+
+`apiTokens` (see `src/core/modules/api-token/README.md`) adds bearer tokens that respect every rule in
+this module:
+
+- A **TENANT token** belongs to one tenant, is managed by members holding `apiTokens.manageRole`, and
+  acts with the LOWEST role of `roleHierarchy` inside that tenant only — an `X-Tenant-Id` naming another
+  tenant is refused, and `@SkipTenantCheck()` does not unbind it. The boot refuses a hierarchy in which
+  that lowest role would reach the manage role.
+- A **USER token** acts as its user through the ordinary membership checks of `CoreTenantGuard`, with
+  global roles removed (no admin bypass), optionally restricted to one tenant and capped by
+  `maxTenantRole`.
+
+Both are denied on routes without `@ApiTokenScopes()`. **Call `CoreApiTokenService.deleteAllForTenant()`
+when you delete a tenant — nothing does it for you**: the core has no tenant model to notice the
+deletion, and a tenant token does not depend on any member, so it keeps authenticating until then.
+
 ## Related
 
 - [Integration Checklist](./INTEGRATION-CHECKLIST.md)

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

@@ -0,0 +1,36 @@
+/**
+ * Whether a tenant guard is actually REGISTERED in this process — as opposed to merely configured.
+ *
+ * `RolesGuard` and `BetterAuthRolesGuard` hand every non-system role over to the tenant guard when
+ * multi-tenancy is on, because that guard resolves them against the membership. Deciding that from
+ * CONFIGURATION alone meant: whenever configuration and registration were out of step, a role such
+ * as `RoleEnum.ADMIN` was handed to a guard that never ran, and every authenticated caller passed.
+ * The role guards therefore delegate only while this registry reports an active tenant guard.
+ *
+ * Counted, not flagged: `CoreTenantModule` registers (so a project's own guard class counts too), and
+ * so does `CoreTenantGuard` itself (for setups that list it as an APP_GUARD directly). Each disposer
+ * releases exactly its own registration.
+ *
+ * A true leaf: no imports (see `.claude/rules/architecture.md` → "DI Token Placement (SWC-Safe)").
+ */
+
+let activeTenantGuards = 0;
+
+/**
+ * Record an active tenant guard. Returns a disposer that releases this registration exactly once.
+ */
+export function registerActiveTenantGuard(): () => void {
+  activeTenantGuards++;
+  let released = false;
+  return () => {
+    if (!released) {
+      released = true;
+      activeTenantGuards = Math.max(0, activeTenantGuards - 1);
+    }
+  };
+}
+
+/** Is at least one tenant guard registered in this process? */
+export function hasActiveTenantGuard(): boolean {
+  return activeTenantGuards > 0;
+}

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

@@ -19,8 +19,16 @@ import { resolveGuardRequest } from '../../common/helpers/execution-context-requ
 import { ConfigService } from '../../common/services/config.service';
 import { ResolvedTenantContext, setTenantContextResolver } from '../../common/services/core-tenant-context.registry';
 import { CoreRedisService } from '../../common/services/core-redis.service';
+import { ApiTokenKind } from '../api-token/core-api-token.constants';
+import {
+  capApiTokenTenantRole,
+  enforceApiTokenRoute,
+  getApiTokenContext,
+  getApiTokenTenantRestriction,
+} from '../api-token/core-api-token.helpers';
 import { ErrorCode } from '../error-code/error-codes';
 import { CoreTenantMemberModel } from './core-tenant-member.model';
+import { registerActiveTenantGuard } from './core-tenant-guard.registry';
 import { SKIP_TENANT_CHECK_KEY } from './core-tenant.decorators';
 import { TENANT_MEMBER_MODEL_TOKEN, TenantMemberStatus } from './core-tenant.enums';
 import {
@@ -165,8 +173,14 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     setTenantContextResolver({
       resolve: (user, headerTenantId) => this.resolveTenantContext(user, headerTenantId),
     });
+
+    // Lets the role guards delegate non-system roles to this guard — only while it exists.
+    this.releaseTenantGuard = registerActiveTenantGuard();
   }
 
+  /** Releases this guard's registration (see core-tenant-guard.registry.ts). */
+  private releaseTenantGuard?: () => void;
+
   /**
    * Answer "which tenant is this caller in?" WITHOUT an Express request.
    *
@@ -253,6 +267,8 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
   }
 
   onModuleDestroy(): void {
+    this.releaseTenantGuard?.();
+
     if (this.invalidationListener) {
       try {
         const subscriber = this.redisService?.getSubscriber();
@@ -324,11 +340,27 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       return true;
     }
 
+    // API tokens (see core-api-token.helpers): a TENANT token is fully decided there — scopes, roles,
+    // binding to its own tenant. A USER token passed its scope check and continues below as its user,
+    // through the same membership validation as a session; only its restrictions are added on top.
+    const apiTokenKind = enforceApiTokenRoute({
+      controllerClass: context.getClass(),
+      handler: context.getHandler(),
+      request,
+    });
+    if (apiTokenKind === ApiTokenKind.TENANT) {
+      return true;
+    }
+    // A user token restricted to one tenant is bound to it like a header naming it — the helper has
+    // already refused a header naming any other tenant.
+    const apiTokenTenant = getApiTokenTenantRestriction(request.user);
+
     // Parse tenant header
     const headerName = (config.headerName ?? 'x-tenant-id').toLowerCase();
     const rawHeader = request.headers?.[headerName] as string | undefined;
     const headerTenantId =
-      rawHeader && typeof rawHeader === 'string' && rawHeader.length <= 128 ? rawHeader.trim() : undefined;
+      apiTokenTenant ??
+      (rawHeader && typeof rawHeader === 'string' && rawHeader.length <= 128 ? rawHeader.trim() : undefined);
 
     // Two role sets for different purposes:
     //
@@ -367,7 +399,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
         const membership = await this.findMembershipCached(request.user.id, headerTenantId);
         if (membership) {
           request.tenantId = headerTenantId;
-          request.tenantRole = membership.role as string;
+          request.tenantRole = capApiTokenTenantRole(request.user, membership.role as string) ?? undefined;
         }
       }
       return true;
@@ -380,10 +412,11 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     // 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(),
-    ]);
+    // A tenant-restricted user token stays bound to its tenant even on @SkipTenantCheck() routes:
+    // skipping the check would drop the binding, and the restriction is the whole point of the token.
+    const hasSkipDecorator =
+      !apiTokenTenant &&
+      this.reflector.getAllAndOverride<boolean>(SKIP_TENANT_CHECK_KEY, [context.getHandler(), context.getClass()]);
 
     // S_USER check — any authenticated user satisfies this system role.
     //
@@ -488,7 +521,9 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
         throw new ForbiddenException('Not a member of this tenant');
       }
 
-      const memberRole = membership.role as string;
+      // A user token with maxTenantRole acts with the lower of its cap and the membership role; `null`
+      // (a role the hierarchy cannot compare with the cap) satisfies no tenant role at all.
+      const memberRole = capApiTokenTenantRole(user, membership.role as string);
 
       // Check role access if roles are required (hierarchy + normal, against membership.role).
       //
@@ -509,7 +544,8 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
         // The length guard is NOT redundant here (unlike the `.some()` above): checkRoleAccess
         // returns TRUE for an empty required-roles list, so calling it with no tenant roles would
         // grant access to a handler that only ever required a global role.
-        const satisfiedByTenant = tenantRoles.length > 0 && checkRoleAccess(tenantRoles, undefined, memberRole);
+        const satisfiedByTenant =
+          tenantRoles.length > 0 && memberRole !== null && checkRoleAccess(tenantRoles, undefined, memberRole);
 
         if (!satisfiedGlobally && !satisfiedByTenant) {
           throw new ForbiddenException('Insufficient tenant role');
@@ -519,7 +555,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       // Set validated tenant context on request (consumed by RequestContextMiddleware
       // lazy getter → context.tenantId / context.tenantRole, and by @CurrentTenant() via RequestContext)
       request.tenantId = headerTenantId;
-      request.tenantRole = memberRole;
+      request.tenantRole = memberRole ?? undefined;
       return true;
     }
 
@@ -573,7 +609,10 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
     }
 
     const userId = request.user.id;
-    const ttl = this.cacheTtlMs;
+    // A user token's maxTenantRole changes which memberships reach minLevel, so its answer is computed
+    // per request instead of shared through the per-user cache.
+    const capped = !!getApiTokenContext(request.user)?.maxTenantRole;
+    const ttl = capped ? 0 : this.cacheTtlMs;
 
     // When cache is enabled, check process-level cache
     if (ttl > 0) {
@@ -600,7 +639,8 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       const hierarchy = getRoleHierarchy();
       ids = memberships
         .filter((m) => {
-          const level = hierarchy[m.role as string] ?? 0;
+          const role = capApiTokenTenantRole(request.user, m.role as string);
+          const level = role === null ? 0 : (hierarchy[role] ?? 0);
           return level >= minLevel;
         })
         .map((m) => m.tenant as string);
@@ -808,7 +848,7 @@ export class CoreTenantGuard implements CanActivate, OnApplicationBootstrap, OnM
       throw new ForbiddenException('Not a member of this tenant');
     }
     request.tenantId = headerTenantId;
-    request.tenantRole = membership.role as string;
+    request.tenantRole = capApiTokenTenantRole(user, membership.role as string) ?? undefined;
     return true;
   }
 

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

@@ -1,6 +1,9 @@
+import { Logger } from '@nestjs/common';
+
 import { isForbiddenMembershipRole, isGlobalOnlyRole, looksLikeSystemRole } from '../../common/enums/role.enum';
 import { ConfigService } from '../../common/services/config.service';
 import { RoleScope, roleScopeRegistry, RoleScopeSource } from './core-role-scope.registry';
+import { hasActiveTenantGuard } from './core-tenant-guard.registry';
 import { DEFAULT_ROLE_HIERARCHY } from './core-tenant.enums';
 
 /**
@@ -172,6 +175,33 @@ export function isMultiTenancyActive(): boolean {
   return !!config && config.enabled !== false;
 }
 
+let warnedAboutMissingTenantGuard = false;
+
+/**
+ * Should a role guard hand non-system roles over to the tenant guard?
+ *
+ * Only when multi-tenancy is on AND a tenant guard is actually registered. Configured-but-absent is
+ * not "someone else checks it" — it is "nobody checks it", so the role guard then resolves the roles
+ * itself against `user.roles` (fail-closed) and says so once.
+ */
+export function delegatesRolesToTenantGuard(): boolean {
+  if (!isMultiTenancyActive()) {
+    return false;
+  }
+  if (hasActiveTenantGuard()) {
+    return true;
+  }
+  if (!warnedAboutMissingTenantGuard) {
+    warnedAboutMissingTenantGuard = true;
+    new Logger('CoreTenantModule').warn(
+      'multiTenancy is configured but no tenant guard is registered — the role guards check non-system roles ' +
+        'against user.roles themselves instead of delegating them. Register CoreTenantModule (CoreModule does so ' +
+        'automatically when multiTenancy is set).',
+    );
+  }
+  return false;
+}
+
 /**
  * Check if a role is a hierarchy role (present in the configured role hierarchy).
  * Returns false when multiTenancy is disabled to avoid false positives.

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

@@ -1,9 +1,10 @@
-import { CanActivate, DynamicModule, Global, Module, Type } from '@nestjs/common';
+import { CanActivate, DynamicModule, Global, Module, OnModuleDestroy, OnModuleInit, Type } from '@nestjs/common';
 import { APP_GUARD } from '@nestjs/core';
 import { MongooseModule, SchemaFactory, getModelToken } from '@nestjs/mongoose';
 import { Model } from 'mongoose';
 
 import { roleScopeRegistry } from './core-role-scope.registry';
+import { registerActiveTenantGuard } from './core-tenant-guard.registry';
 import { CoreTenantMemberModel } from './core-tenant-member.model';
 import { TENANT_MEMBER_MODEL_TOKEN } from './core-tenant.enums';
 import { assertRoleVocabularyIsCoherent, configRoleScopeSource } from './core-tenant.helpers';
@@ -58,7 +59,23 @@ export interface CoreTenantModuleOptions {
  */
 @Global()
 @Module({})
-export class CoreTenantModule {
+export class CoreTenantModule implements OnModuleDestroy, OnModuleInit {
+  /** Releases this module's tenant-guard registration (see core-tenant-guard.registry.ts). */
+  private releaseTenantGuard?: () => void;
+
+  /**
+   * Tell the role guards that a tenant guard really runs, so they may hand non-system roles to it.
+   * Registered by the MODULE, not only by CoreTenantGuard, because `forRoot({ guard })` may register
+   * a project's own guard class instead.
+   */
+  onModuleInit(): void {
+    this.releaseTenantGuard = registerActiveTenantGuard();
+  }
+
+  onModuleDestroy(): void {
+    this.releaseTenantGuard?.();
+  }
+
   static forRoot(options: CoreTenantModuleOptions = {}): DynamicModule {
     // Teach the role-scope registry which roles are global and which are tenant-scoped, then
     // refuse to boot on a vocabulary that cannot be enforced coherently (a tenant role named after

package/src/core/modules/user/core-user.service.ts

@@ -13,6 +13,7 @@ import { ConfigService } from '../../common/services/config.service';
 import { CrudService } from '../../common/services/crud.service';
 import { ErrorCode } from '../error-code/error-codes';
 import { EmailService } from '../../common/services/email.service';
+import { revokeApiTokensOfUser } from '../api-token/core-api-token.registry';
 import { CoreModelConstructor } from '../../common/types/core-model-constructor.type';
 import { CoreUserModel } from './core-user.model';
 import { CoreUserCreateInput } from './inputs/core-user-create.input';
@@ -362,6 +363,19 @@ export abstract class CoreUserService<
           }
         }
 
+        // The legacy reset ends every legacy session above (refreshTokens), so it ends the user's
+        // API tokens too — left alive, they keep the credential the reset was meant to retire
+        // working. A no-op without `apiTokens`; never fails the reset.
+        try {
+          await revokeApiTokensOfUser({ email: dbObject.email, userId: dbObject.id });
+        } catch (error) {
+          this.userServiceLogger.error(
+            `Could not revoke the API tokens after the password reset of ${maskEmail(dbObject.email)}: ${
+              error instanceof Error ? error.message : 'Unknown error'
+            }`,
+          );
+        }
+
         return updatedUser;
       },
       { dbObject, serviceOptions },

package/src/core.module.ts

@@ -59,6 +59,7 @@ import { CoreHubModule } from './core/modules/hub/core-hub.module';
 import { isHubEnabled, isHubQueriesEnabled } from './core/modules/hub/hub-config.helper';
 import { CorePermissionsModule } from './core/modules/permissions/core-permissions.module';
 import { CoreSystemSetupModule } from './core/modules/system-setup/core-system-setup.module';
+import { CoreApiTokenModule } from './core/modules/api-token/core-api-token.module';
 import { CoreTenantModule } from './core/modules/tenant/core-tenant.module';
 
 /**
@@ -579,6 +580,17 @@ export class CoreModule implements NestModule {
       imports.push(CoreTenantModule.forRoot({ modelName: membershipModelName }));
     }
 
+    // Add CoreApiTokenModule when apiTokens is configured (boolean shorthand, presence implies enabled).
+    // Independent of multiTenancy: user tokens work without it; tenant tokens and tenant restrictions
+    // switch on by themselves when CoreTenantModule is registered as well.
+    const apiTokensConfig = config.apiTokens;
+    if (
+      apiTokensConfig === true ||
+      (typeof apiTokensConfig === 'object' && apiTokensConfig !== null && apiTokensConfig.enabled !== false)
+    ) {
+      imports.push(CoreApiTokenModule.forRoot({ ...overrides?.apiToken }));
+    }
+
     // Set exports
     const exports: any[] = [
       ConfigService,

package/src/index.ts

@@ -125,6 +125,18 @@ export * from './core/common/types/required-at-least-one.type';
 export * from './core/common/types/string-or-object-id.type';
 export * from './core/common/types/wrapper.type';
 
+// =====================================================================================================================
+// Core - Modules - API tokens
+// =====================================================================================================================
+
+export * from './core/modules/api-token/core-api-token.constants';
+export * from './core/modules/api-token/core-api-token.decorators';
+export * from './core/modules/api-token/core-api-token.helpers';
+export * from './core/modules/api-token/core-api-token.middleware';
+export * from './core/modules/api-token/core-api-token.model';
+export * from './core/modules/api-token/core-api-token.module';
+export * from './core/modules/api-token/core-api-token.service';
+
 // =====================================================================================================================
 // Core - Modules - Auth
 // =====================================================================================================================