@lenne.tech/nest-server 11.36.5 → 11.38.0

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

@@ -118,6 +118,13 @@ export interface IAuth {
    */
   preventUserEnumeration?: boolean;
 
+  /**
+   * Password-reset request behaviour.
+   *
+   * @since 11.38.0
+   */
+  passwordReset?: IAuthPasswordReset;
+
   /**
    * Rate limiting configuration for Legacy Auth endpoints
    *
@@ -154,23 +161,166 @@ export interface IAuth {
  * @since 11.7.1
  * @see https://github.com/lenneTech/nest-server/blob/develop/.claude/rules/module-deprecation.md
  */
+/**
+ * Interface for the legacy password-reset request endpoint
+ *
+ * @since 11.38.0
+ */
+/**
+ * Browser security headers set on every response.
+ *
+ * @since 11.38.0
+ */
+export interface ISecurityHeaders {
+  /**
+   * `Content-Security-Policy` value.
+   *
+   * **Opt-in on purpose — there is no safe default.** A CSP that does not match what the
+   * application loads breaks it rather than hardening it, and only the project knows that. This
+   * package additionally serves its own HTML from two surfaces (the Hub and the GraphQL
+   * playground), so any value shipped here would be wrong for somebody.
+   *
+   * @default undefined (no header)
+   */
+  contentSecurityPolicy?: string;
+
+  /**
+   * `X-Content-Type-Options: nosniff` — stops a browser from re-interpreting a response as a
+   * type the server did not declare, which is what turns an uploaded file into a script.
+   *
+   * @default true
+   */
+  contentTypeOptions?: boolean;
+
+  /**
+   * Whether the headers are set at all. `false` disables the middleware entirely.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * `X-Frame-Options` — clickjacking protection. `false` omits the header.
+   *
+   * @default 'DENY'
+   */
+  frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+
+  /**
+   * `Strict-Transport-Security`. `false` omits it.
+   *
+   * **Only ever sent on a request that actually arrived over HTTPS** — decided by
+   * `x-forwarded-proto`, falling back to the connection protocol, and never by configuration.
+   * A browser REMEMBERS this header: one sent from a dev server over `http://localhost` makes
+   * every project on that host unreachable over http for up to a year, with no way to undo it
+   * from the server. So it must not be possible to switch it on where it does not belong.
+   *
+   * Note this makes `trustProxy` load-bearing here too: behind a TLS-terminating proxy the
+   * connection reaching Node is plain http, so without a trusted forwarded header no production
+   * request looks secure and no HSTS is sent.
+   *
+   * @default `{ includeSubDomains: true, maxAge: 31536000, preload: false }`
+   */
+  hsts?: boolean | ISecurityHstsOptions;
+
+  /**
+   * `Referrer-Policy` — how much of the current URL travels to a third party. `false` omits it.
+   *
+   * @default 'strict-origin-when-cross-origin'
+   */
+  referrerPolicy?: false | string;
+
+  /**
+   * Whether to strip Express's `X-Powered-By`, which names the stack to an attacker and buys
+   * nothing.
+   *
+   * @default true
+   */
+  removePoweredBy?: boolean;
+}
+
+/**
+ * `Strict-Transport-Security` directives.
+ *
+ * @since 11.38.0
+ */
+export interface ISecurityHstsOptions {
+  /** Apply to every subdomain. @default true */
+  includeSubDomains?: boolean;
+
+  /** Lifetime in seconds. @default 31536000 (one year) */
+  maxAge?: number;
+
+  /**
+   * Add the `preload` directive.
+   *
+   * **Off by default.** It is a submission to a browser-vendor list that is slow and awkward to
+   * reverse and commits every subdomain — a decision for whoever owns the domain, not a framework
+   * default.
+   *
+   * @default false
+   */
+  preload?: boolean;
+}
+
+export interface IAuthPasswordReset {
+  /**
+   * Whether `POST /users/password/reset-request` answers identically for a known and an unknown
+   * address.
+   *
+   * **Defaults to `true`** — the safe answer. Set `false` only to restore the previous behaviour,
+   * where an unknown address produced HTTP 404 and a known one HTTP 201: a working oracle for
+   * "does this person have an account here", which matters most in a multi-tenant product, where
+   * it also answers "who works at which customer".
+   *
+   * Deliberately NOT the same switch as {@link IAuth.preventUserEnumeration}, which governs the
+   * SIGN-IN messages and defaults to `false` for backward compatibility. Two settings because the
+   * trade-offs differ: at sign-in the distinction is genuine UX ("wrong password" vs "unknown
+   * address"), while a reset request carries no password at all — the only thing given up here is
+   * the form's ability to say "we do not know this address".
+   *
+   * **The status code is the smaller half.** The response TIME also distinguishes the two cases:
+   * the known path writes a token and sends mail, the unknown path returns immediately. This
+   * option equalises what the framework controls, but a project whose `sendPasswordResetMail()`
+   * AWAITS the mail send still leaks the difference — the send is a network round trip, orders of
+   * magnitude above anything else in the request. See `src/server/modules/user/user.service.ts`
+   * for the reference implementation, which does not await it, and the 11.38.x migration guide.
+   *
+   * @default true
+   *
+   * @example
+   * ```typescript
+   * auth: {
+   *   // Restore the pre-11.38.0 behaviour — the reset form can then say "unknown address"
+   *   passwordReset: { preventUserEnumeration: false },
+   * }
+   * ```
+   */
+  preventUserEnumeration?: boolean;
+}
+
 export interface IAuthLegacyEndpoints {
   /**
    * Whether legacy auth endpoints are enabled.
    *
-   * Set to false to disable all legacy auth endpoints (GraphQL and REST).
-   * Use this after all users have migrated to BetterAuth (IAM).
+   * **Since 11.38.0 this defaults to `false`.** Legacy Auth is superseded by IAM
+   * (Better-Auth) and slated for removal. A project that registers the legacy module
+   * but never made a decision here used to keep a second, fully functional
+   * password-authentication surface open indefinitely; it now has to be asked for.
+   * Disabled endpoints answer HTTP 410 Gone.
    *
-   * Check migration status via the `betterAuthMigrationStatus` query.
+   * Set `true` while users are still migrating. `betterAuthMigrationStatus` →
+   * `canDisableLegacyAuth` says when it can go back off; the boot log reports the same
+   * figure on every start.
    *
    * **Environment Variable:** `LEGACY_AUTH_ENABLED`
    *
-   * @default true
+   * @default false (was `true` before 11.38.0)
    *
    * @example
    * ```typescript
-   * // Via environment variable
-   * enabled: process.env.LEGACY_AUTH_ENABLED !== 'false',
+   * // Via environment variable — note `=== 'true'`, not `!== 'false'`
+   * enabled: process.env.LEGACY_AUTH_ENABLED === 'true',
    * ```
    */
   enabled?: boolean;
@@ -179,15 +329,21 @@ export interface IAuthLegacyEndpoints {
    * Whether legacy GraphQL auth endpoints are enabled.
    * Affects: signIn, signUp, signOut, refreshToken mutations
    *
-   * @default true (inherits from `enabled`)
+   * Overrides `enabled` for this transport — except that an explicit
+   * `enabled: false` stays a hard off switch and cannot be reopened here.
+   *
+   * @default false (inherits from `enabled`, which defaults to false since 11.38.0)
    */
   graphql?: boolean;
 
   /**
    * Whether legacy REST auth endpoints are enabled.
-   * Affects: /auth/sign-in, /auth/sign-up, etc.
+   * Affects: /auth/signin, /auth/signup, etc.
+   *
+   * Overrides `enabled` for this transport — except that an explicit
+   * `enabled: false` stays a hard off switch and cannot be reopened here.
    *
-   * @default true (inherits from `enabled`)
+   * @default false (inherits from `enabled`, which defaults to false since 11.38.0)
    */
   rest?: boolean;
 }
@@ -378,6 +534,51 @@ export interface IBetterAuthEmailVerificationConfig {
    */
   passwordResetBrevoTemplateId?: number;
 
+  /**
+   * Where the password-reset mail sends the recipient.
+   *
+   * **Defaults to the APP**, derived as `<appUrl>/auth/reset-password?token=<token>` — the path the
+   * starter's reset page lives at.
+   *
+   * Without this, the link is the one Better-Auth generates, and that points at the **API**
+   * (`https://api.example.com/iam/reset-password/<token>?callbackURL=…`), which then redirects to
+   * the app. That works, but it puts a domain the recipient does not recognise into a password
+   * mail — precisely what people are trained to be suspicious of. In this stack an app and an API
+   * host are the norm, so the app is the better default.
+   *
+   * **What the API hop did, and what you give up.** Better-Auth's redirect route validates the
+   * token and its expiry before forwarding, so an expired link produced an error page instead of a
+   * form that fails on submit. Linking straight to the app moves that error later, to the moment
+   * the new password is submitted. It is NOT a security difference — the token ends up in the app
+   * URL either way, and the `callbackURL` origin check only exists because of the hop. If you want
+   * the early error back, either leave this unset or have the reset page validate the token before
+   * rendering.
+   *
+   * `{token}` is substituted anywhere in the value. Without the placeholder, `?token=<token>` is
+   * appended — so a page that reads a PATH parameter configures
+   * `https://example.com/auth/reset-password/{token}`.
+   *
+   * Set to `false` to keep Better-Auth's own link.
+   *
+   * Note this is separate from `email.passwordResetLink`, which serves the LEGACY
+   * `/users/password/reset-request` flow and appends the token as a path segment. Two flows, two
+   * conventions; a project using both should point them at the same page.
+   *
+   * @default `<appUrl>/auth/reset-password?token={token}`
+   * @since 11.38.0
+   *
+   * @example
+   * ```typescript
+   * betterAuth: {
+   *   emailVerification: {
+   *     // A page that reads the token from the path
+   *     passwordResetLink: 'https://example.com/auth/reset-password/{token}',
+   *   },
+   * }
+   * ```
+   */
+  passwordResetLink?: false | string;
+
   /**
    * Cooldown in seconds between resend requests for the same email address.
    * Prevents abuse by limiting how often verification emails can be resent.
@@ -2643,6 +2844,21 @@ export interface IServerOptions {
      *
      * @since 11.18.0
      */
+    /**
+     * Browser security headers (HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy).
+     *
+     * Set on EVERY response, including the ones a guard rejects — they are registered as
+     * middleware, so a `401` carries them too.
+     *
+     * `true` / `{}` / omitted → enabled with the safe defaults. `false` → no headers at all.
+     * A reverse proxy setting the same headers wins, because it writes last; this layer exists so
+     * that a deployment without one, or a local instance, is not bare.
+     *
+     * @default true
+     * @since 11.38.0
+     */
+    headers?: boolean | ISecurityHeaders;
+
     responseModelInterceptor?:
       | boolean
       | {

package/src/core/common/middlewares/security-headers.middleware.ts

@@ -0,0 +1,155 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import { Response as ExpressResponse, NextFunction, Request } from 'express';
+
+import { ISecurityHeaders } from '../interfaces/server-options.interface';
+import { ConfigService } from '../services/config.service';
+
+/**
+ * Sets the standard browser security headers on every response.
+ *
+ * WHY THIS IS IN THE FRAMEWORK AND NOT IN EACH PROJECT
+ *
+ * The same header set was being rebuilt by hand across the stack — one project inline in
+ * `main.ts`, another as its own middleware, a third about to. A freshly generated project sent
+ * none at all. Anything rebuilt per project drifts per project, and a header that is missing
+ * produces no error anywhere: it shows up in a pentest report months later.
+ *
+ * Putting it here also reaches EXISTING projects on their next update, which a change in the
+ * starter would not.
+ *
+ * ORDER MATTERS: THIS IS MIDDLEWARE, NOT AN INTERCEPTOR
+ *
+ * Registered through `CoreModule.configure()`, so it runs before guards and before the handler.
+ * That is deliberate — a `401` from a roles guard is still a response a browser renders, and it
+ * has to carry the headers too. An interceptor would miss every request rejected before the
+ * handler, which is precisely the set an attacker is most likely to be generating.
+ *
+ * NOT A REPLACEMENT FOR THE EDGE
+ *
+ * A reverse proxy (Traefik, Caddy, nginx) can set the same headers, and where one does, its
+ * values win — the proxy writes last. That is fine and intended: this layer exists so that a
+ * deployment WITHOUT such a proxy, or a local instance, is not bare. Defense in depth, not a
+ * turf claim.
+ */
+@Injectable()
+export class SecurityHeadersMiddleware implements NestMiddleware {
+  constructor(protected readonly configService: ConfigService) {}
+
+  use(req: Request, res: ExpressResponse, next: NextFunction): void {
+    const config = this.resolveConfig();
+    if (!config) {
+      return next();
+    }
+
+    // Express advertises itself by default. It tells an attacker which stack to target and buys
+    // nothing; `app.disable('x-powered-by')` would work too, but doing it here keeps the whole
+    // header policy in one readable place.
+    if (config.removePoweredBy) {
+      res.removeHeader('X-Powered-By');
+    }
+
+    if (config.contentTypeOptions) {
+      res.setHeader('X-Content-Type-Options', 'nosniff');
+    }
+
+    if (config.frameOptions) {
+      res.setHeader('X-Frame-Options', config.frameOptions);
+    }
+
+    if (config.referrerPolicy) {
+      res.setHeader('Referrer-Policy', config.referrerPolicy);
+    }
+
+    if (config.contentSecurityPolicy) {
+      res.setHeader('Content-Security-Policy', config.contentSecurityPolicy);
+    }
+
+    if (config.hsts && this.isSecureRequest(req)) {
+      const directives = [`max-age=${config.hsts.maxAge}`];
+      if (config.hsts.includeSubDomains) {
+        directives.push('includeSubDomains');
+      }
+      if (config.hsts.preload) {
+        directives.push('preload');
+      }
+      res.setHeader('Strict-Transport-Security', directives.join('; '));
+    }
+
+    next();
+  }
+
+  /**
+   * Whether this request actually arrived over HTTPS.
+   *
+   * **HSTS is decided by the protocol, never by configuration or environment.** A browser
+   * remembers the header: one `Strict-Transport-Security` sent from a dev server over
+   * `http://localhost` makes EVERY project on that host unreachable over http for up to a year,
+   * and there is no way to take it back from the server side. So an env flag must not be able to
+   * turn it on where it does not belong — the request itself has to say so.
+   *
+   * `x-forwarded-proto` is read first because in every deployment that terminates TLS at a proxy
+   * the connection reaching Node is plain http, and `req.secure` alone would answer "no" for
+   * every production request. That header is only trustworthy behind a proxy, which is what
+   * `trustProxy` exists to declare — and Express only populates `req.secure` from it when
+   * `trust proxy` is set, so both halves agree on the same configuration.
+   */
+  protected isSecureRequest(req: Request): boolean {
+    const forwarded = req.headers['x-forwarded-proto'];
+    if (typeof forwarded === 'string' && forwarded.length) {
+      // A proxy chain may append: "https,http". The client-facing hop is the first entry.
+      return forwarded.split(',')[0].trim().toLowerCase() === 'https';
+    }
+
+    return req.secure === true || req.protocol === 'https';
+  }
+
+  /**
+   * Resolves the effective policy, or `null` when the feature is switched off.
+   *
+   * Safe by default: an unconfigured project gets the full set except CSP. CSP is opt-in because
+   * a wrong one breaks the application rather than hardening it, and a correct one depends on
+   * what the project loads — this package cannot know that, and two of its own surfaces (the Hub
+   * and the GraphQL playground) serve their own HTML.
+   */
+  protected resolveConfig():
+    | null
+    | (Required<Omit<ISecurityHeaders, 'contentSecurityPolicy' | 'enabled' | 'hsts'>> & {
+        contentSecurityPolicy?: string;
+        hsts: null | { includeSubDomains: boolean; maxAge: number; preload: boolean };
+      }) {
+    const raw = this.configService.getFastButReadOnly('security')?.headers;
+
+    if (raw === false) {
+      return null;
+    }
+
+    const options: ISecurityHeaders = raw === true || raw === undefined ? {} : raw;
+    if (options.enabled === false) {
+      return null;
+    }
+
+    const hsts =
+      options.hsts === false ? null : options.hsts === true || options.hsts === undefined ? {} : options.hsts;
+
+    return {
+      contentSecurityPolicy: options.contentSecurityPolicy,
+      contentTypeOptions: options.contentTypeOptions !== false,
+      frameOptions: options.frameOptions === false ? undefined : (options.frameOptions ?? 'DENY'),
+      hsts: hsts
+        ? {
+            includeSubDomains: hsts.includeSubDomains !== false,
+            // One year. The value the major preload lists require, and long enough that it is a
+            // decision rather than a formality.
+            maxAge: typeof hsts.maxAge === 'number' ? hsts.maxAge : 31536000,
+            // NOT on by default: `preload` is a submission to a browser-vendor list that is
+            // slow and awkward to reverse, and it commits every subdomain. That belongs to
+            // whoever owns the domain, not to a framework default.
+            preload: hsts.preload === true,
+          }
+        : null,
+      referrerPolicy:
+        options.referrerPolicy === false ? undefined : (options.referrerPolicy ?? 'strict-origin-when-cross-origin'),
+      removePoweredBy: options.removePoweredBy !== false,
+    } as any;
+  }
+}

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

@@ -0,0 +1,104 @@
+# Auth Module (Legacy Auth)
+
+JWT-based email/password authentication: `signIn`, `signUp`, `logout`, `refreshToken` over GraphQL,
+and `POST /auth/signin`, `/auth/signup`, `/auth/logout`, `/auth/refresh-token` over REST.
+
+> **This module is deprecated in favour of IAM (Better-Auth) and will be removed.** Since 11.38.0
+> its endpoints are **off unless explicitly enabled**. New projects should not register it — the
+> one-argument `CoreModule.forRoot(envConfig)` never does. See
+> [`.claude/rules/module-deprecation.md`](../../../../.claude/rules/module-deprecation.md) for the
+> migration path.
+
+## When this module exists at all
+
+Only when a project passes the three-argument form:
+
+```typescript
+CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig);
+```
+
+The one-argument form (`CoreModule.forRoot(envConfig)`) registers IAM only, and nothing in this
+directory is loaded. If you are reading this while planning a new project, that is the form you
+want.
+
+## Enabling the endpoints
+
+Registering the module is no longer enough. Since 11.38.0 the endpoints answer **HTTP 410 Gone**
+until asked for:
+
+```typescript
+// config.env.ts
+auth: {
+  legacyEndpoints: { enabled: true },   // or LEGACY_AUTH_ENABLED=true
+},
+```
+
+The default flipped because a second, fully functional password-authentication surface that nobody
+chose is a liability: it is served by `CoreAuthService` rather than Better-Auth, so it bypasses
+every IAM-side control an operator may believe is now in force — two-factor, passkey enforcement,
+Better-Auth session revocation.
+
+Resolution is one exported function, `isLegacyEndpointEnabled(config, transport)`, shared by both
+transports so they cannot answer differently:
+
+| Configuration                               | Result                               |
+| ------------------------------------------- | ------------------------------------ |
+| `enabled: false`                            | off, whatever `graphql` / `rest` say |
+| per-transport flag set (`graphql` / `rest`) | that flag wins                       |
+| `enabled: true`                             | on                                   |
+| nothing set                                 | **off**                              |
+
+An explicit `enabled: false` is a hard off switch that a per-transport `true` cannot reopen — it is
+the setting a project reached for to close legacy down, and an upgrade must never widen it.
+
+## Knowing when you can turn it off
+
+`CoreLegacyAuthDeprecationInitializer` reports at every boot, in both directions:
+
+- while any endpoint is open: a deprecation warning plus the IAM migration percentage,
+- while all are closed but users are still unmigrated: a warning that those users cannot sign in,
+  naming the way back.
+
+Both are best-effort — the status read runs detached from the boot so it cannot delay readiness.
+The same figures are available on demand through the `betterAuthMigrationStatus` query
+(`canDisableLegacyAuth` is the signal to act on).
+
+## Relationship to IAM while both run
+
+The two systems share one user collection and keep each other's credentials in step:
+
+| Event                                       | Written by      | Mirrored into                         |
+| ------------------------------------------- | --------------- | ------------------------------------- |
+| Sign-up via IAM                             | IAM (scrypt)    | legacy (bcrypt)                       |
+| Sign-up via Legacy                          | legacy (bcrypt) | IAM, on first IAM sign-in (migration) |
+| Password reset via the legacy user endpoint | legacy          | IAM                                   |
+| Password reset via IAM                      | IAM             | legacy (11.38.0+)                     |
+| Password change via `update()`              | legacy          | IAM                                   |
+
+`CoreAuthService.signIn` **delegates to IAM** as soon as a user carries an `iamId`, so for a
+migrated user both endpoints answer from the IAM credential. That is worth knowing when debugging:
+a stale legacy bcrypt hash is invisible through either API and only surfaces if IAM is switched
+off.
+
+Hash formats differ irreversibly (`bcrypt(sha256(pw))` vs `scrypt(sha256(pw))`), which is why the
+mirrors exist rather than a one-off migration script.
+
+## Extending
+
+Standard Module Inheritance Pattern. Both endpoint guards are `protected` and must be called from
+an override:
+
+| Class                | Method to call                    |
+| -------------------- | --------------------------------- |
+| `CoreAuthResolver`   | `checkLegacyGraphQLEnabled(name)` |
+| `CoreAuthController` | `checkLegacyRESTEnabled(name)`    |
+
+Forgetting one re-opens a disabled endpoint. Use the exported `isLegacyEndpointEnabled()` rather
+than re-implementing the table if you override the check itself.
+
+## Related
+
+- [`.claude/rules/module-deprecation.md`](../../../../.claude/rules/module-deprecation.md) — the migration roadmap
+- [`.claude/rules/role-system.md`](../../../../.claude/rules/role-system.md) — `@Roles` vs `@UseGuards`, and why `refreshToken` is the one place `@UseGuards` is still required
+- [`../better-auth/README.md`](../better-auth/README.md) — the system replacing this one
+- [`../better-auth/INTEGRATION-CHECKLIST.md`](../better-auth/INTEGRATION-CHECKLIST.md) — integrating IAM

package/src/core/modules/auth/core-auth.controller.ts

@@ -22,6 +22,7 @@ import { CoreAuthModel } from './core-auth.model';
 import { LegacyAuthDisabledException } from './exceptions/legacy-auth-disabled.exception';
 import { AuthGuard } from './guards/auth.guard';
 import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard';
+import { isLegacyEndpointEnabled } from './helpers/legacy-endpoints.helper';
 import { CoreAuthSignInInput } from './inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from './inputs/core-auth-sign-up.input';
 import { ICoreAuthUser } from './interfaces/core-auth-user.interface';
@@ -70,23 +71,15 @@ export class CoreAuthController {
   /**
    * Check if legacy REST endpoints are enabled
    *
-   * Throws LegacyAuthDisabledException if:
-   * - config.auth.legacyEndpoints.enabled is false
-   * - config.auth.legacyEndpoints.rest is false
+   * Since 11.38.0 legacy endpoints are OFF unless a project asks for them — see
+   * `isLegacyEndpointEnabled()` for the full resolution table.
    *
    * @throws LegacyAuthDisabledException
    */
   protected checkLegacyRESTEnabled(endpointName: string): void {
     const authConfig = this.configService.getFastButReadOnly('auth');
-    const legacyConfig = authConfig?.legacyEndpoints;
 
-    // Check if legacy endpoints are globally disabled
-    if (legacyConfig?.enabled === false) {
-      throw new LegacyAuthDisabledException(endpointName);
-    }
-
-    // Check if REST endpoints specifically are disabled
-    if (legacyConfig?.rest === false) {
+    if (!isLegacyEndpointEnabled(authConfig?.legacyEndpoints, 'rest')) {
       throw new LegacyAuthDisabledException(endpointName);
     }
   }

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

@@ -12,6 +12,7 @@ import { RolesGuardRegistry } from './guards/roles-guard-registry';
 import { RolesGuard } from './guards/roles.guard';
 import { CoreAuthUserService } from './services/core-auth-user.service';
 import { CoreAuthService } from './services/core-auth.service';
+import { CoreLegacyAuthDeprecationInitializer } from './core-legacy-auth-deprecation.initializer';
 import { LegacyAuthRateLimiter } from './services/legacy-auth-rate-limiter.service';
 import { JwtRefreshStrategy } from './strategies/jwt-refresh.strategy';
 import { JwtStrategy } from './strategies/jwt.strategy';
@@ -64,6 +65,10 @@ export class CoreAuthModule {
     let providers: any[] = [
       // [Global] The GraphQLAuthGuard integrates the user into context
       ...rolesGuardProvider,
+      // Reports at boot that this deployment still exposes Legacy Auth, and how far the
+      // IAM migration has come. Registered here because this module exists only in
+      // legacy mode — an IAM-only project never loads it.
+      CoreLegacyAuthDeprecationInitializer,
       {
         provide: CoreAuthUserService,
         useClass: UserService,

package/src/core/modules/auth/core-auth.resolver.ts

@@ -15,6 +15,7 @@ import { CoreAuthModel } from './core-auth.model';
 import { LegacyAuthDisabledException } from './exceptions/legacy-auth-disabled.exception';
 import { AuthGuard } from './guards/auth.guard';
 import { LegacyAuthRateLimitGuard } from './guards/legacy-auth-rate-limit.guard';
+import { isLegacyEndpointEnabled } from './helpers/legacy-endpoints.helper';
 import { CoreAuthSignInInput } from './inputs/core-auth-sign-in.input';
 import { CoreAuthSignUpInput } from './inputs/core-auth-sign-up.input';
 import { ICoreAuthUser } from './interfaces/core-auth-user.interface';
@@ -62,23 +63,15 @@ export class CoreAuthResolver {
   /**
    * Check if legacy GraphQL endpoints are enabled
    *
-   * Throws LegacyAuthDisabledException if:
-   * - config.auth.legacyEndpoints.enabled is false
-   * - config.auth.legacyEndpoints.graphql is false
+   * Since 11.38.0 legacy endpoints are OFF unless a project asks for them — see
+   * `isLegacyEndpointEnabled()` for the full resolution table.
    *
    * @throws LegacyAuthDisabledException
    */
   protected checkLegacyGraphQLEnabled(endpointName: string): void {
     const authConfig = this.configService.getFastButReadOnly('auth');
-    const legacyConfig = authConfig?.legacyEndpoints;
 
-    // Check if legacy endpoints are globally disabled
-    if (legacyConfig?.enabled === false) {
-      throw new LegacyAuthDisabledException(endpointName);
-    }
-
-    // Check if GraphQL endpoints specifically are disabled
-    if (legacyConfig?.graphql === false) {
+    if (!isLegacyEndpointEnabled(authConfig?.legacyEndpoints, 'graphql')) {
       throw new LegacyAuthDisabledException(endpointName);
     }
   }