@lenne.tech/nest-server 11.37.0 → 11.39.0

package/src/core/common/helpers/input.helper.ts

@@ -856,3 +856,40 @@ export function typeofArray(arr: any[], strict = false): string {
   }
   return type;
 }
+
+/**
+ * Whether a value is safe to use as the right-hand side of a Mongoose equality filter.
+ *
+ * ── The hole this closes ───────────────────────────────────────────────────────
+ * A controller parameter declared as `@Body('token') token: string` has
+ * `metatype === String`, and `MapAndValidatePipe` short-circuits on exactly that shape:
+ * `if (!value || typeof value !== 'object' || !metatype || isBasicType(metatype)) return value`.
+ * The declared type is erased at runtime, so nothing checks it — a JSON object reaches the
+ * service verbatim.
+ *
+ * `findOne({ passwordResetToken: token })` with `token = { $ne: null }` therefore selects the
+ * first user holding ANY live reset token, and the caller sets that person's password without
+ * ever seeing their mail. Confirmed by probe against the real route, not by reading.
+ *
+ * Express parses query strings with `qs` in extended mode, so `?token[$ne]=` produces the same
+ * object without a JSON body at all — `@Query('token') token: string` is exposed identically.
+ *
+ * `{ $ne: null }` is the takeover primitive; `null` is the quieter one, because MongoDB matches
+ * MISSING fields against `null` and selects a user who never requested anything.
+ *
+ * ── Why a guard at the sink rather than `mongoose.set('sanitizeFilter', true)` ──
+ * The global switch wraps every object-valued filter in `$eq`, which would break the framework's
+ * own operator-bearing queries (`$in`, `$ne`, `$gt` in the filter helpers) unless each is wrapped
+ * in `mongoose.trusted()`. That is a fleet-wide audit, not a fix. This guard is exact: it says
+ * "this particular value came from a client and must be a plain string".
+ *
+ * Rejects an empty string too — `findOne({ token: '' })` is never a legitimate credential lookup,
+ * and `undefined` would be stripped from the filter entirely by Mongoose, turning the query into
+ * `findOne({})` and matching the first document in the collection.
+ *
+ * @param value - the raw value as it arrived from the transport
+ * @returns whether it may be used as a filter value
+ */
+export function isQueryableString(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
+}

package/src/core/common/helpers/service.helper.ts

@@ -18,7 +18,15 @@ import { clone, plainToInstanceClean, processDeep } from './input.helper';
 // Fields like refreshTokens/tempTokens are kept — they are needed for token validation
 // and process flows (password reset, email verification). The CheckSecurityInterceptor
 // removes those from HTTP responses as a separate layer.
-const SECRET_FIELD_NAMES = Object.freeze(['password', 'verificationToken', 'passwordResetToken']);
+const SECRET_FIELD_NAMES = Object.freeze([
+  'password',
+  'verificationToken',
+  'passwordResetToken',
+  // `S_NO_ONE` covers Model instances; this list is what runs on a plain-object path (`.lean()`,
+  // `aggregate`, a spread). Its sibling token has always been here — the timestamp says "a reset
+  // is pending for this account", which is exactly what the field's own JSDoc calls attacker-useful.
+  'passwordResetTokenExpiresAt',
+]);
 
 /**
  * Helper class for services

package/src/core/common/interceptors/check-security.interceptor.ts

@@ -21,6 +21,7 @@ export class CheckSecurityInterceptor implements NestInterceptor {
       'password',
       'verificationToken',
       'passwordResetToken',
+      'passwordResetTokenExpiresAt',
       'refreshTokens',
       'tempTokens',
       'apiKeyEncrypted',

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,211 @@ 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;
+
+  /**
+   * How long a LEGACY password-reset token stays valid, in minutes.
+   *
+   * **Before 11.38.0 it never expired at all.** `resetPassword()` looked the token up by value and
+   * nothing else, while the exception it threw on a miss read "Invalid or expired password reset
+   * token" — a message describing a check that did not exist. A reset link is a bearer credential
+   * for full account takeover, so an unbounded one means a mail sitting in an archive, a forwarded
+   * message or a restored backup opens the account years later.
+   *
+   * That gap became more reachable in this very release, which is why it is closed here: until now
+   * a project relying on the default mailed a link containing the word `undefined`, so the eternal
+   * token was unusable by accident. Repairing the link without adding an expiry would have turned a
+   * dead credential into a live and permanent one.
+   *
+   * The IAM flow already expires its token after one hour (Better-Auth's
+   * `resetPasswordTokenExpiresIn`), so 60 matches the half of the framework that had it right.
+   *
+   * **Value semantics — the two ends mean different things, deliberately:**
+   *
+   * | Value | Meaning |
+   * |-------|---------|
+   * | unset | 60 minutes |
+   * | a positive number | that many minutes |
+   * | `0` | **no expiry** — restores the pre-11.38.0 behaviour |
+   * | negative, `NaN`, non-numeric | 60 minutes, i.e. the safe default rather than "unbounded" |
+   *
+   * `0` opting OUT while an invalid value falls back to the DEFAULT is intentional: switching the
+   * expiry off is a decision somebody has to state, and a typo in an environment variable must
+   * never be the thing that states it.
+   *
+   * **Upgrade note:** a token minted before this release carries no expiry timestamp and is treated
+   * as expired. Anyone holding an unredeemed reset mail must request a new one — which, for every
+   * project that relied on the default link, is the first one that will actually work.
+   *
+   * @default 60
+   *
+   * @example
+   * ```typescript
+   * auth: {
+   *   passwordReset: { tokenExpiresInMinutes: 15 },
+   * }
+   * ```
+   */
+  tokenExpiresInMinutes?: number;
+}
+
 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 +374,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;
 }
@@ -337,6 +538,12 @@ export interface IBetterAuthEmailVerificationConfig {
    * When not set, the verification link points directly to the backend
    * endpoint which handles verification and redirects.
    *
+   * Since 11.38.0 the generated link carries the recipient's address as well —
+   * `{callbackURL}?token=<token>&email=<address>`. The verification page needs it to offer
+   * "send a new email" once the token has expired, and it cannot recover the address itself:
+   * that value lives inside the token's JWT payload, and reading it there would mean rendering
+   * data from an unverified signature.
+   *
    * @default undefined (backend-handled verification)
    * @since 11.13.0
    */
@@ -378,6 +585,57 @@ 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.
+   *
+   * **Resolution order**, first hit wins: this option → the caller's `redirectTo` → `<appUrl>/auth/
+   * reset-password` → Better-Auth's own URL. `false` is a hard opt-out that a `redirectTo` does not
+   * override.
+   *
+   * Note this is separate from `email.passwordResetLink`, which serves the LEGACY
+   * `/users/password/reset-request` flow. Both DEFAULTS point at the same page with `?token=`; what
+   * still differs is the fallback for a configured value without a placeholder — `?token=` here, a
+   * path segment there. A project using both should point them at the same page, and writing
+   * `{token}` in both makes them identical.
+   *
+   * @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.
@@ -1983,7 +2241,50 @@ export interface IServerOptions {
     mailjet?: MailjetOptions;
 
     /**
-     * Password reset link for email
+     * Base of the link in the LEGACY password-reset mail (`/users/password/reset-request`).
+     *
+     * Three cases, and the difference between them is where the token lands:
+     *
+     * | Value                                   | Link the recipient gets                  |
+     * | --------------------------------------- | ---------------------------------------- |
+     * | contains `{token}`                      | placeholder replaced, wherever it sits   |
+     * | set, but no `{token}`                   | token appended as a PATH segment         |
+     * | not set (the default below)             | `?token=<token>`, per the default's shape |
+     *
+     * **Copying the default is safe; writing your own base is where it gets sharp.** The default
+     * carries `{token}`, so pasting it lands in row one and behaves exactly as leaving the option
+     * out. A base WITHOUT the placeholder lands in row two instead — same URL, different link. That
+     * is deliberate: it is the convention the legacy flow has always used, and changing it would
+     * silently break every project whose page reads a path parameter. It is also easy to walk into
+     * by accident, so the framework logs a warning at boot for any configured value without a
+     * placeholder. The way to silence it is to write `{token}` where you want the token, which
+     * states the convention in the place it applies instead of leaving it implicit.
+     *
+     * Build the link with `CoreUserService.buildPasswordResetLink(token)` rather than by
+     * concatenation. It returns `null` when it can resolve nothing — which is the difference
+     * between sending no mail and sending one whose link reads `undefined/<token>`. The latter
+     * happened in a downstream project and reached real recipients: the request succeeds, the mail
+     * arrives, it looks right, and only the click reveals it, to somebody who by definition has no
+     * second way in.
+     *
+     * Note this is separate from `betterAuth.emailVerification.passwordResetLink`, which serves the
+     * IAM flow. Both DEFAULTS now point at the same page with `?token=`; what still differs is the
+     * fallback for a configured value without a placeholder — path segment here, `?token=` there.
+     * A project using both flows should point them at the same page, and writing `{token}` in both
+     * makes them identical.
+     *
+     * @default `<appUrl>/auth/reset-password?token={token}`
+     * @since 11.38.0
+     *
+     * @example
+     * ```typescript
+     * email: {
+     *   // A page that reads the token from the path. Spelling out `{token}` is what keeps the
+     *   // boot warning quiet — `'https://example.com/auth/reset-password'` produces the same
+     *   // link, but leaves the reader guessing which convention was meant.
+     *   passwordResetLink: 'https://example.com/auth/reset-password/{token}',
+     * }
+     * ```
      */
     passwordResetLink?: string;
 
@@ -2643,6 +2944,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;
+  }
+}