@lenne.tech/nest-server 11.38.0 → 11.40.0

package/.claude/rules/configurable-features.md

@@ -235,6 +235,25 @@ Rules:
    (`Number.isFinite(ttl) && ttl > 0`), or a "disabled" value silently becomes an
    expiry of `now + NaN` — every lookup misses while the cache grows.
 
+### Family C — `0` = NO LIMIT, but an INVALID value falls back to the DEFAULT
+
+A third shape, and it exists because Family A's rule is wrong for one class of knob. Family A says
+"negative and `NaN` behave like `0`", i.e. a misconfigured value degrades to *unbounded*. That is
+right for a cap on tool-description length. It is exactly backwards for a knob that bounds the
+lifetime of a **credential**.
+
+| Config | `0` | invalid (negative, `NaN`, `''`, a word) |
+|--------|-----|------------------------------------------|
+| `auth.passwordReset.tokenExpiresInMinutes` | never expires — the explicit opt-out | **the default (60)**, never "unbounded" |
+
+The asymmetry is the protection: switching off the expiry of an account-takeover credential is a
+decision somebody has to state, and a typo in an environment variable must never be the thing that
+states it. Note `Number('')` is `0`, so an empty value has to be rejected *before* the coercion or
+it reads as a deliberate opt-out.
+
+**When adding a knob, ask what a misconfiguration should cost.** If the answer is "a bound nobody
+intended to remove", it belongs here and not in Family A.
+
 ### Both families
 
 **Warn when the knob is inert.** If a value only takes effect together with another
@@ -273,10 +292,13 @@ This pattern is currently applied to:
 
 | Feature | Config Path | Pattern | Default Values |
 |---------|-------------|---------|----------------|
-| Password-Reset Link (IAM) | `betterAuth.emailVerification.passwordResetLink` | Explicit Value with derived default | **`<appUrl>/auth/reset-password?token={token}` since 11.38.0.** Before, the mail carried the link Better-Auth generates, which points at the **API** (`https://api.example.com/iam/reset-password/<token>?callbackURL=…`) and redirects to the app from there. It works, but puts a domain the recipient does not recognise into a password mail — what people are trained to check before clicking. In this stack app and API hosts are the norm, so the app is the better default. **What it gives up:** Better-Auth's redirect route validates the token and its expiry BEFORE forwarding, so an expired link produced an error page rather than a form that fails on submit; linking straight to the app moves that error later. It is **not** a security difference — the token reaches the app URL either way, and the `callbackURL` origin check exists only because of the hop it removes. `{token}` is substituted anywhere in the value (so a PATH-parameter page configures `…/reset-password/{token}`); without the placeholder `?token=` is appended. A relative value resolves against `appUrl`. `false` keeps Better-Auth's link, including the early validation. Falls back to Better-Auth's link when no `appUrl` can be resolved — a guessed host would 404, which is worse than a working link. Separate from `email.passwordResetLink`, which serves the LEGACY flow and appends the token as a path segment. Implementation: `core-better-auth-email-verification.service.ts` → `buildPasswordResetUrl()` |
+| Password-Reset Link (IAM) | `betterAuth.emailVerification.passwordResetLink` | Explicit Value with derived default | **`<appUrl>/auth/reset-password?token={token}` since 11.38.0.** Before, the mail carried the link Better-Auth generates, which points at the **API** (`https://api.example.com/iam/reset-password/<token>?callbackURL=…`) and redirects to the app from there. It works, but puts a domain the recipient does not recognise into a password mail — what people are trained to check before clicking. In this stack app and API hosts are the norm, so the app is the better default. **What it gives up:** Better-Auth's redirect route validates the token and its expiry BEFORE forwarding, so an expired link produced an error page rather than a form that fails on submit; linking straight to the app moves that error later. It is **not** a security difference — the token reaches the app URL either way, and the `callbackURL` origin check exists only because of the hop it removes. `{token}` is substituted anywhere in the value (so a PATH-parameter page configures `…/reset-password/{token}`); without the placeholder `?token=` is appended. A relative value resolves against `appUrl`. `false` keeps Better-Auth's link, including the early validation. Falls back to Better-Auth's link when no `appUrl` can be resolved — a guessed host would 404, which is worse than a working link. Separate from `email.passwordResetLink`, which serves the LEGACY flow. Since 11.38.0 both DEFAULTS produce `?token=`; the path-segment rule applies only to a CONFIGURED legacy value without `{token}` (a boot warning names that divergence). Resolution order here gained a step: explicit config → the caller's validated `redirectTo` → `<appUrl>/auth/reset-password` → Better-Auth's own link; `false` still wins over a `redirectTo`. Implementation: `core-better-auth-email-verification.service.ts` → `buildPasswordResetUrl()` |
 | Security Headers | `security.headers` | Boolean Shorthand — **safe default** | **ON without configuration** (11.38.0+). `X-Content-Type-Options: nosniff`, `X-Frame-Options: DENY`, `Referrer-Policy: strict-origin-when-cross-origin`, `X-Powered-By` removed. HSTS `max-age=31536000; includeSubDomains`, **`preload` off** (it commits every subdomain to a browser-vendor list that is awkward to reverse — the domain owner's decision, not a framework default). **No CSP** — a wrong one breaks the app rather than hardening it, and this package serves its own HTML from the Hub and the GraphQL playground; set `contentSecurityPolicy` explicitly if you want one. Registered as MIDDLEWARE, not an interceptor, so a request a guard rejects carries the headers too — those are the responses an attacker generates most of. **HSTS is decided by the request protocol, never by configuration**: `x-forwarded-proto` first (first hop of a chain), connection protocol as fallback. A browser REMEMBERS the header, so one sent from a dev server over `http://localhost` makes every project on that host unreachable over http for up to a year, unrecoverably — which is why no flag can switch it on where it does not belong. This also makes `trustProxy` load-bearing: behind a TLS-terminating proxy the inward connection is plain http. A reverse proxy setting the same headers wins (it writes last); this layer exists so a deployment without one, or a local instance, is not bare. `false` disables everything. Implementation: `common/middlewares/security-headers.middleware.ts` |
 | Password-Reset Enumeration | `auth.passwordReset.preventUserEnumeration` | Explicit Boolean — **safe default** | **`true` since 11.38.0.** `POST /users/password/reset-request` answers identically for a known and an unknown address; before, it answered 404 vs 201, a working oracle for "does this person have an account", which in a multi-tenant product also answers who works at which customer. Deliberately NOT the same switch as `auth.preventUserEnumeration` (which governs SIGN-IN messages and defaults to `false`): at sign-in the distinction is genuine UX, while a reset request carries no password at all — the only thing given up is the form's ability to say "unknown address". **The status code is the smaller half.** Response TIME separates the cases far more: the known path sends mail, a network round trip orders of magnitude above everything else. `setPasswordResetTokenForEmail()` returns `null` instead of throwing and still generates a token so the CPU cost matches, but the send lives in the CALLER — a `sendPasswordResetMail()` that AWAITS it leaks the difference regardless. The reference implementation (`src/server/modules/user/user.service.ts`) does not await; copy that shape. Set `false` to restore the pre-11.38.0 behaviour |
 | Legacy Auth Endpoints | `auth.legacyEndpoints` | **Explicit Opt-In** (a fourth shape — see below) | **`enabled: false` since 11.38.0** (was `true`). The legacy password-authentication surface — `signIn`/`signUp`/`logout`/`refreshToken` over GraphQL, `/auth/*` over REST — is reachable only when asked for. Disabled endpoints answer HTTP 410 Gone. Only relevant for the three-argument `CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(...), envConfig)`; the one-argument form never registers the module. Resolution, via the exported `isLegacyEndpointEnabled(config, transport)`: `enabled: false` wins over everything; else a per-transport boolean (`graphql` / `rest`) wins; else `enabled === true`; else **off**. The asymmetry is deliberate — an explicit `enabled: false` is a HARD off switch that a per-transport `true` cannot reopen, because it is the setting a project reached for to close legacy down and an upgrade must never widen it. Non-boolean values (config arrives as JSON through `NSC__*`) are read as "not set", so the string `'false'` cannot switch a transport ON by truthiness. `CoreLegacyAuthDeprecationInitializer` reports both directions at boot: a warning while the surface is open, and a warning when it is closed while users are still unmigrated. Env var: `LEGACY_AUTH_ENABLED`, matched strictly against `'true'`. Implementation: `auth/helpers/legacy-endpoints.helper.ts` |
+| Password-Reset Token Lifetime | `auth.passwordReset.tokenExpiresInMinutes` | **Numeric Sentinel — Family C** (see above) | **60 minutes since 11.38.0. Before that the legacy reset token NEVER expired** — `resetPassword()` looked it up by value and compared no time, while the exception it threw read "Invalid or expired password reset token", claiming a check that did not exist. A reset link takes over an EXISTING account, so an unbounded one means a mail in an archive or a restored backup opens that account years later. The IAM half already expired after an hour (Better-Auth's `resetPasswordTokenExpiresIn`); only the legacy half had nothing. `0` opts out; an invalid value falls back to 60, never to unbounded. **A token minted before 11.38.0 carries no timestamp and is treated as EXPIRED** — reading "no timestamp" as "valid forever" would preserve the defect permanently rather than for a migration window. An expired token is answered exactly like an unknown one (404, same message) and deleted on sight. Model field `passwordResetTokenExpiresAt`, `@Restricted(S_NO_ONE)`. Implementation: `core-user.service.ts` → `passwordResetTokenExpiryMinutes()` / `isPasswordResetTokenExpired()` |
+| Legacy Password-Reset Link | `email.passwordResetLink` | Explicit Value with derived default | **`<appUrl>/auth/reset-password?token={token}` since 11.38.0.** Two conventions live here and which applies depends on whether the option is set AT ALL: unset yields `?token=`, the same string written out yields a PATH segment. That is deliberate — a project that configures such a value has a page built for a path parameter, and moving it silently would break the flow this release repairs — and because it is not guessable, `CoreUserService` **warns once at boot** when a configured value carries no `{token}`. The warning names a precondition: `{token}` is substituted by `buildPasswordResetLink()` and nothing else, so a caller still concatenating by hand must switch FIRST or it mails the placeholder verbatim. Returns `null` rather than a string containing `undefined`; resolves `appUrl` through `resolveServerUrls` (localhost defaults, host-split `baseUrl`) and honours `cors.deriveAppUrl` |
+| SMTP TLS Mode | `email.smtp.secure` + `SMTP_REQUIRE_TLS` | Derived from the port | **`secure` follows `SMTP_PORT` unless set to `'true'`/`'false'`.** It is not an independent setting: 465 negotiates TLS immediately, everything else upgrades via STARTTLS. The production profile shipped 587 + `secure: true` — a pair that cannot connect — so a deployment configuring only host and credentials sent NO mail, invisibly, because authentication mail is not awaited. Only the two canonical values override; anything else defers to the port, which is the only rule under which no input produces an unconnectable pair. `requireTLS` defaults to **true**: `secure: false` alone means opportunistic STARTTLS, and an on-path attacker stripping the capability line gets credentials and a live reset link in plaintext. `EmailService` warns once when the resolved pair cannot connect — reported, not overruled. Implementation: `config.helper.ts` → `resolveSmtpSecure()` / `isImpossibleSmtpTlsCombination()` |
 | Legacy Auth Rate Limiting | `auth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60`. Counters live in a `RateLimitStore`: `RedisRateLimitStore` when `redis` is configured (limit enforced EXACTLY across replicas instead of `max × replicas`), else `InMemoryRateLimitStore` (previous behavior). On a Redis outage it degrades to the in-memory counter and logs once per transition — never a 500, never "allowed". `check()` / `reset()` / `clear()` are ASYNC since 11.33.0; `getStats().activeEntries` is `-1` on the Redis store |
 | BetterAuth Rate Limiting | `betterAuth.rateLimit` | Presence Implies Enabled | `max: 10`, `windowSeconds: 60`. Same `RateLimitStore` selection, degradation and async signatures as the Legacy Auth row (namespace `better-auth`) |
 | BetterAuth JWT Plugin | `betterAuth.jwt` | Boolean Shorthand | `expiresIn: '15m'` |
@@ -311,6 +333,7 @@ This pattern is currently applied to:
 | Cron Job Deduplication | per job: `distributed` in `CronJobConfig` | Explicit Boolean | **`true` when `redis` is configured, otherwise `false`** — a single-replica project that upgrades must not silently gain a `cron-locks` collection, a lease write per tick, and a new way for a tick to be skipped. A Redis-less multi-replica fleet opts in per job with `distributed: true` (MongoDB lease). Mechanism: BullMQ job scheduler when Redis + the OPTIONAL peer `bullmq` are present AND `cronTime` is a string without `utcOffset`; otherwise local timer + lease (Redis `SET NX`, else a TTL-indexed `cron-locks` document). Tick lease TTL 3600 s. **Leases fail open** — an unreachable lease store runs the tick everywhere rather than stopping all scheduled work fleet-wide. **`runOnInit` (default `true`) deduplicates over a FIXED per-job key with a 300 s TTL**, because replicas do not share a boot instant: replicas booting within 5 min run the startup tick once between them, and a replica restarting inside that window SKIPS its startup tick — set `distributed: false` on jobs whose `runOnInit` work is per-process (warming a process-local cache). No constructor change needed: `CoreModule` fills `core-cron-jobs.registry.ts` via `CoreCronJobsInitializer` and `CoreCronJobs` reads it lazily; explicit `{ connection, redisService }` in `CoreCronJobsOptions` wins. With neither source it warns once and every replica runs every tick |
 | Shutdown Delay | `shutdownDelayMs` | Numeric Sentinel — Family B (`0` = off) | `0` (default, no delay, no log). Waits N ms **in the SIGTERM/SIGINT handler, before `close()` is entered**, so a load balancer can finish deregistering while the instance is still fully healthy. NOT a lifecycle hook: `close()` runs `onModuleDestroy` → `beforeApplicationShutdown` → dispose → `onApplicationShutdown`, so a delay in `beforeApplicationShutdown` would wait with every module already torn down while the socket still accepts — worse than no delay. **Requires `installGracefulShutdown(app)` in main.ts, which REPLACES `server.enableShutdownHooks()`** — keeping both makes Nest close the app in parallel with the wait, so the delay silently never happens. At delay `0` the helper IS `enableShutdownHooks()`. **Keep the value well below the orchestrator grace period AND leave room for the drain that follows**: Compose `stop_grace_period` 10s, Kubernetes `terminationGracePeriodSeconds` 30s, and `installProcessDiagnostics()` force-exits after 30s — exceed any and the process is SIGKILLed mid-wait with no hook running. Warns above `10000`, capped at `60000`. Non-numeric / negative values behave like `0` |
 | Trust Proxy | `trustProxy` | Explicit Value (pass-through, Express default) | `false` (Express's own default — the forwarded chain is not trusted). Passed verbatim to `app.set('trust proxy', …)` by `CoreTrustProxyInitializer`, a `CoreModule` provider, so a consumer inherits it by upgrading and needs no `main.ts` edit. Accepts `false` / a hop count (`1`, `2`) / `'loopback'` / a subnet list — **not** Express's predicate function: the value must survive `NEST_SERVER_CONFIG` / `NSC__*` (JSON) and the ConfigService deep clone. **This is what makes `request.ip` correct, and every IP-keyed rate limit depends on it**: unset behind Caddy/nginx/an ingress, `req.ip` is the PROXY address for every request, so all clients share ONE bucket and `auth.rateLimit.max` throttles everybody at once — exactly fleet-wide once `redis` is configured. Trusting MORE hops than exist is the opposite failure: a client prepends its own header entry and picks a fresh bucket per request. Applied at module init (inside `app.init()`/`listen()`, i.e. AFTER `main.ts`), so a configured value wins over a hand-written `app.set()`; an UNSET value is never applied, which keeps `app.set('trust proxy', fn)` in `main.ts` available as the escape hatch for the predicate form. **Unset + an IP-keyed limiter enabled (`auth.rateLimit` / `betterAuth.rateLimit`) logs a boot warning naming the shared-bucket consequence**; `trustProxy: false` is the explicit "nothing proxies me" answer that silences it. The AI limiter keys on the user id and is unaffected |
+| AI Egress Allowlist (SSRF) | `ai.allowedBaseUrlHosts` | Explicit Value — **unset = permissive**, malformed = INTERPRETED or reported, never silently off | `undefined` → no restriction, so a local provider (Ollama on `localhost:11434`) works out of the box. Set → only those hosts are reachable, matched against `URL.host` (incl. port) and `URL.hostname`. **Accepts an array OR a comma-separated string, and the string form is not a convenience** — it is what the framework's own env mapping produces: `NSC__AI__ALLOWED_BASE_URL_HOSTS` becomes `{ ai: { allowedBaseUrlHosts: '<string>' } }` and lodash `merge` assigns that scalar straight over a configured array. Until 11.39.x a bare `!Array.isArray(...) -> return` read that as "not configured" and skipped the check entirely, so the canonical `NSC__` spelling silently disabled SSRF egress control with no log line at all. Entries are trimmed, lowercased and stripped of a fully-qualifying trailing dot, and the SAME normalisation is applied to the URL, so neither side wins by spelling one DNS name differently; a bare hostname entry matches any port, and an entry naming the scheme's default port (`example.com:443` on https) also matches the portless URL. A value that is neither array nor string carries no hostnames — the allowlist is then inactive and that is LOGGED as an error, because from the outside it looks exactly like "correctly unset". Enforced on **all three** outbound paths (`chat()`, the capability `probe()`, and `probeContextWindow()` — the last was unguarded before 11.39.x and is reachable from an ordinary user prompt via `detectAndPersistCapabilities()`, before the rate limit). Implementation: `openai-compatible.provider.ts` → `assertBaseUrlAllowed()` / `resolveAllowedBaseUrlHosts()` |
 | AI Assistant | `ai` | Presence Implies Enabled | Core: `maxIterations: 5`, `defaultMode: 'auto'` (or `'plan'`), `rateLimit` (presence implies enabled: `max: 20`, `windowSeconds: 60`), `systemPrompt`, `documentation` (injected into the system prompt), `encryptionSecret`. **DB-backed LLM connections** (`aiConnections`, admin CRUD) with AES-256-GCM-encrypted API keys (`AiCryptoService`, secret from `ai.encryptionSecret` / `NSC__AI__ENCRYPTION_SECRET` / `SECRETS_ENCRYPTION_KEY`; `apiKeyEncrypted` is a global `secretFields` entry, never returned — only `hasApiKey`); optional `defaultConnection` one-time seed. **Provider abstraction** (`ILlmProvider`, default `OpenAiCompatibleProvider` for any OpenAI-compatible endpoint via `fetch`; per-connection `supportsNativeTools`/`supportsJsonResponse` capabilities, emulated tool calling when native tools are unavailable). **Tool registry** (`AiToolRegistry`, tools self-register, role-filtered; tools may be `mutating`/`destructive` and define `authorize()` for pre-flight data-level checks). **Plan mode** (`input.mode: 'plan'`): full plan → pre-flight authorize ALL steps → all-or-nothing execution with a translated (de/en) error when any step is not permitted. **Confirmation policy**: `confirmation.mutating: { default, enforced }` + client `input.requireConfirmation` (ignored when enforced); `destructive` always confirms. **Client metadata** (`input.metadata`: URL/nav/console logs, untrusted+capped). **Multi-turn conversations** (`aiConversations`, owner-scoped). **SSE streaming** (`POST /ai/stream`). **Audit** (`audit: false` → persist to `aiInteractions`, admin-readable). **Token budgets** (`budget: { period: 'day'|'month'|'none', user: { maxTokens?, maxPrompts? }, tenant: { maxTokens?, maxPrompts? } }`, requires audit): per-user AND per-tenant limits with config defaults; admins override per user/tenant at runtime (`aiBudgetLimits`, `CoreAiBudgetService`). Resolution: override → default → unlimited (missing/0 = unlimited). Enforced before the run (HTTP 429 + translated). Each response carries a compact `budget` summary (promptTokens, usedTokens, remainingTokens, resetAt); full breakdown via `aiUsage` query / `GET /ai/usage`. **Self-optimizing prompts**: the system prompt is assembled from keyed fragments (`CoreAiPromptBuilderService` ships built-in defaults; works with zero rows). Admin-editable overrides per slot (`aiSlots`, admin CRUD, `/ai/slots`) scoped by `key`/`locale`/`capability`/`tenantId`, with tenant override/reset semantics and placeholder tokens resolved at run time via the placeholder registry. **Governed learning loop** (`promptLearning: { enabled: true, autoApply: false }`): tool errors record `suggested` hints (`aiPromptHints`, admin CRUD, `/ai/prompt-hints`) that only reach the prompt once admin-approved (or auto-approved when `autoApply`); hints only ADD guidance, never relax permissions. **Context window** (`contextWindow`, default 8192; auto-detected per connection via `ILlmProvider.detectContextWindow()` — Ollama `/api/show` probe / known-model table / Claude alias — and persisted): per-user/session history is trimmed (oldest non-system turns dropped, last truncated) and tool-results capped to `maxToolResultChars` (default 12000) so a session never overflows the model. A connection's window can be seeded via `ai.defaultConnection.contextWindow` (validated: a non-positive/non-integer value is dropped with a warning). **Capability drift check** (`capabilityDriftCheck`, default `false`): opt-in boot self-check that probes each enabled connection with an EXPLICIT `supportsNativeTools`/`supportsJsonResponse` (built with those flags cleared so the endpoint is actually re-probed) and logs a warning on mismatch — the stored value is never changed. OFF by default because it makes outbound calls to the LLM endpoints on every boot; also skipped in the ci/e2e runners. **Deferred tool schemas** (`deferToolSchemas`, default `false`): the system-prompt tool catalog then lists only tool NAMES + descriptions instead of full JSON schemas, and the model fetches a schema on demand via the built-in `search_tools` meta-tool — with a large registry the schemas alone can dominate a small context window. `deferToolSummaryChars` (default `0` = untruncated) additionally caps each description in that DEFERRED catalog: whole sentences up to the cap (always at least the first), word-boundary cut when the first sentence already exceeds it, and a `…` marker appended ON TOP of the cap. The default of `0` keeps the saving opt-in, so enabling `deferToolSchemas` alone never changes what a description says; set roughly 200–400 alongside it to actually reclaim the context. Both apply to EMULATED providers only — a connection with `supportsNativeTools: true` receives every full description + schema via `buildToolSchemas()` regardless, so truncation and the banner are skipped there rather than asserting a cut the tool payload contradicts. The omitted tail is where preconditions and role restrictions usually live — the catalog banner tells the model to fetch the full text via `search_tools` first, but this is model GUIDANCE only: authorization is enforced server-side by the registry's role filter (`forUser()`), the execution-time re-check, and the `mutating`/`destructive` flags read by the confirmation gate — never by what the catalog shows. (`AiTool.authorize()` runs in PLAN MODE only; in auto mode and over MCP, data-level checks must live inside `execute()`.) **MCP server** (`mcp: false` → `/ai/mcp` Streamable HTTP, Bearer auth, lazy `@modelcontextprotocol/sdk`; `mcp: { oauth: true, oauthSecret }` adds OAuth 2.1 — HMAC tokens + PKCE S256 + dynamic registration via `mountAiMcpOAuth(app)` in main.ts). Overrides via `CoreModule.forRoot(env, { ai: { budgetService, connectionResolver, connectionService, controller, conversationService, interactionService, mcpClientService, modeService, placeholderRegistry, preferenceService, promptBuilder, promptHintService, promptService, resolver, service, slotService, toolGrantService, toolPolicyService } })` |
 
 ## Module Override Pattern (via `ICoreModuleOverrides`)

package/.claude/rules/module-inheritance.md

@@ -83,6 +83,8 @@ override async signIn(...): Promise<Auth> {
 |------------|--------|---------|
 | `CoreAuthResolver` | `checkLegacyGraphQLEnabled(name)` | Throws HTTP 410 if legacy endpoints disabled |
 | `CoreAuthController` | `checkLegacyRESTEnabled(name)` | Throws HTTP 410 if legacy endpoints disabled |
+| `OpenAiCompatibleProvider` | `resolveAllowedBaseUrlHosts()` | Normalises the SSRF egress allowlist (CSV string, case, trailing dot) and reports a malformed value. An override of `assertBaseUrlAllowed()` that re-reads `ConfigService` directly silently loses all of it — including the string form the framework's own `NSC__` mapping produces, which is the shape that used to switch the control off |
+| `OpenAiCompatibleProvider` | `assertBaseUrlAllowed(url)` | Call it before ANY new outbound `fetch` you add to a provider. It already guards `chat()`, `probe()` and `probeContextWindow()`; a fourth path that forgets it is a hole the allowlist's own tests cannot see unless they assert on `fetch` |
 
 **Rule**: When you override a method, check if the parent calls any `protected` helper methods. If so, call them in your override too.
 

package/.claude/rules/package-management.md

@@ -151,7 +151,7 @@ Two ordering rules, both enforced by the contract test:
 | Rule | Why |
 |------|-----|
 | `packageManager` is exact (`x.y.z+sha512.<hash>`), never a range | Same fixed-version rule as dependencies; corepack rejects ranges outright |
-| `engines.pnpm` tracks the pin's major (`^<major>.0.0`) | A soft gate that warns pnpm 10 users. It is not a pin and cannot tell CI what to install |
+| `engines.pnpm` tracks the pin's major (`^<major>.0.0`) | A soft gate that warns pnpm 10 users. It is not a pin and cannot tell CI what to install. Note it is deliberately looser than what the check chains rely on: `pnpm peers check` is a pnpm 11 subcommand, and `^11.0.0` does not guarantee the minor that introduced it. The real guarantee is `packageManager`, which is exact — this range is not the place to encode a floor |
 | Never declare `devEngines.packageManager` | npm/npx abort with `EBADDEVENGINES`; corepack rejects ranges inside it |
 | Never pass `version:` to `pnpm/action-setup` | Two sources drift; the action hard-errors on a mismatch |
 | Never `RUN corepack …` | Absent on Node >= 25 |
@@ -168,7 +168,8 @@ Two ordering rules, both enforced by the contract test:
 
 Package overrides live in the `overrides:` section of **`pnpm-workspace.yaml`** (they moved out of `package.json`'s `pnpm.overrides` in the pnpm 11 upgrade). They force transitive dependencies to a security-patched version.
 
-**Keep the set minimal.** On the pnpm 11 upgrade the list was pruned from 36 to the 9 still load-bearing — an override is only necessary if removing it lets the package resolve back INTO its vulnerable range (verify with a with/without lockfile diff; `pnpm audit` is the arbiter). Each surviving entry carries its CVE rationale as a comment. Remove an entry once its parent dependency ships a fixed version.
+**Keep the set minimal.** On the pnpm 11 upgrade the list was pruned from 36 to the 9 then still
+load-bearing (it has since grown back to 17 as new advisories landed) — an override is only necessary if removing it lets the package resolve back INTO its vulnerable range (verify with a with/without lockfile diff; `pnpm audit` is the arbiter). Each surviving entry carries its CVE rationale as a comment. Remove an entry once its parent dependency ships a fixed version.
 
 ### Rule: Override Targets MUST Be Fixed Versions
 
@@ -214,6 +215,120 @@ The fix was to change every override target to a fixed version:
 "@apollo/server": "5.5.0"
 ```
 
+### Overrides AGE, and a stale one is a lock rather than a no-op
+
+**Rule: when a new advisory raises the patch line for a package you already override, RAISE the
+existing entry. Never add a second one beside it.**
+
+Both failure modes below were hit on the same day, in this repo and in `nest-server-starter`, and
+neither is what the "unbounded target" warning above describes. An override is not a fact you record
+once; it is a claim about a moving patch line.
+
+**Mode 1 — the floor is overtaken.** The entry keeps doing exactly what it was written to do, and
+that becomes the problem:
+
+```yaml
+# Written in August for two advisories patched >= 3.1.4
+'fast-uri@>=3.0.0 <3.1.5': '3.1.5'
+```
+
+Four newer advisories then land, patched `>= 3.1.6`. The entry now **pins** every matching path at
+3.1.5 — below the new line. Adding a second, higher entry does not help: the narrower key claims
+its paths first, and the tree ends up carrying *both* versions while `audit` still reports the
+vulnerability. It looks addressed in the file and is not.
+
+**Mode 2 — the target itself becomes vulnerable.** Worse, because nothing about the entry looks
+wrong:
+
+```yaml
+# Target was clean when written; a later advisory covers >=6.14.2 <=6.15.3
+'qs@>=6.11.1 <=6.15.1': '6.15.3'
+```
+
+The override is now actively pinning the tree to a vulnerable version, and the narrow key hides it
+from a casual read.
+
+**How to spot both — and the check that does NOT work.** "The same package appears twice under
+`overrides:`" is the obvious heuristic and it is wrong: several packages legitimately need one entry
+per major, because different majors coexist in the tree. This repo has three `brace-expansion`
+entries (1.x, 2.x, 5.x) and two for `js-yaml` (4.x, 5.x), all correct. Flagging those trains the
+reader to ignore the check.
+
+The reliable tells are narrower:
+
+1. **`pnpm audit` reports a package you already override.** That is never "transitive, pre-existing,
+   not our problem" — it means the entry itself is the cause, in one of the two modes above.
+2. **Two entries for the same package within ONE major**, one of them floored below the other's
+   target. That is the stale-versus-new collision; the narrower key wins and the higher entry is
+   decoration.
+3. **The lockfile resolves two versions of the package inside one major.** Beware `@types/x`, which
+   looks like a second resolution of `x` and is not.
+
+**This is automated now — `pnpm run check:overrides`.** The guard (`scripts/check-overrides.mjs`)
+cross-references every `overrides:` entry against a live `pnpm audit` report and reports four
+classes: **TOO LOW** (the override resolves and still delivers a version the advisory covers — modes
+1 and 2 above), **NOT MATCHING** (the selector no longer reaches the path it was written for), plus
+**NO FIX** and **UNUSED** as warnings. It runs inside `check`, `check:fix`, `check:naf` and
+`check:raw`, and in CI on both `build.yml` and `publish.yml`. The three tells above are still how you
+*read* a report by hand; the guard is what makes sure somebody does. `--audit-file` and
+`--advisory-file` make a run reproducible offline, and CI passes `--audit-file` so the
+cannot-obtain-a-report skip (correct on a laptop, a silent pass on a runner) is unreachable there.
+
+**The fix in both cases is one entry, floored below the current patch line, targeting a version at
+or above it:**
+
+```yaml
+'fast-uri@<3.1.6': '3.1.6'
+'qs@<6.16.0': '6.16.0'
+```
+
+**Two constraints on the target, both learned the hard way:**
+
+1. **Stay within the major.** A newer major usually exists; crossing one to fix a *transitive*
+   advisory is the shape that broke a project in April 2026 (see the incident above).
+2. **The newest patch may be refused.** This repo enforces a `minimumReleaseAge` supply-chain
+   policy, and a version published inside that window fails the install with
+   `ERR_PNPM_NO_MATURE_MATCHING_VERSION`. Take the oldest version that clears every advisory — which
+   is the right instinct regardless of the policy.
+
+### Suppressions age the same way, and worse
+
+`auditConfig.ignoreGhsas` in `pnpm-workspace.yaml` suppresses an advisory outright. It is the other
+half of the problem above, and the blinder half.
+
+An override at least stays visible: `pnpm audit` keeps reporting its package, so a stale entry can be
+caught by reading the report against the file. **A suppressed advisory is removed from
+`pnpm audit --json` entirely** — `advisories` drops it and `muted` comes back empty. Once a GHSA is
+listed there, no audit run ever mentions it again. If upstream ships a fix tomorrow, nothing says so.
+
+That is not hypothetical either. `GHSA-mh99-v99m-4gvg` was suppressed on 2026-07-28 with a
+justification that was correct in every detail: the newest 1.x was 1.1.16 and carried no length
+guard, and the one remaining path could not be lifted. **1.1.17 — the backport the entry said did not
+exist — was published on 2026-07-29, one day later.** The entry sat obsolete for five weeks, and
+nothing in the repo could have said so.
+
+**Rules for an entry here:**
+
+1. **Name the advisory, the affected path, and why it cannot be fixed** — not just why it is
+   tolerable.
+2. **Record what you verified and when**, with a re-verification trigger ("re-check when @nestjs/cli
+   drops fork-ts-checker-webpack-plugin"). A justification without a date cannot be audited later.
+3. **Assume it will stop being true without telling you.** Ask, before adding it: *what will notice
+   when this expires?* If the answer is "nothing", the entry is a liability regardless of how good
+   today's reasoning is.
+4. **Prefer an override.** A suppression is the last resort, for an advisory with no patched version
+   anywhere. A drifted override is at least still visible.
+
+`pnpm run check:overrides` re-checks every listed GHSA against the GitHub Advisory API and **fails**
+on `FIX AVAILABLE` (a `first_patched_version` now exists) or on a withdrawn advisory. An unreachable
+API is reported as `UNVERIFIED` and tolerated locally — but **fails under `CI`**, because a skip
+nobody reads is indistinguishable from a check that ran.
+
+One consequence worth knowing before you reach for this mechanism: the guard fires when the advisory
+has a patched version for **any** affected range. That makes `ignoreGhsas` nearly unusable for an
+advisory that is fixed *somewhere* but unfixable on *your* path — which is the honest outcome, since
+that case is an override problem, not a suppression problem.
+
 ### Safe Override Workflow
 
 When adding an override to fix a vulnerability:

package/.claude/rules/testing.md

@@ -266,7 +266,7 @@ pnpm run check:mutations -- --id=<id>       # one mutation
 pnpm run check:mutations -- --list          # the registry, without running anything
 pnpm run check:mutations -- --allow-dirty   # when the fix and its evidence share a working tree
 pnpm run check:mutations -- --jobs=4        # N mutations at a time (default: 2, or 4 on >=12 cores)
-pnpm run check:mutations -- --no-infra      # only the 27 that need no MongoDB
+pnpm run check:mutations -- --no-infra      # only the 63 that need no MongoDB
 pnpm run check:mutations -- --since=<ref>   # only mutations touching files changed since <ref>
 ```
 
@@ -284,8 +284,11 @@ when the registry, a vitest config or a setup file changed, since those can move
 **Why the gate does not cache per-mutation verdicts instead.** It runs ONCE PER RELEASE, not per
 commit, so selective re-running would save ~10 minutes a release. The price is a cache that has to
 model each spec's full dependency closure correctly, and getting that wrong produces a stale PASS
-for a test that has since gone vacuous — exactly what the gate is there to prevent. Bad trade at 70
-mutations. Worth revisiting around 100, where the full run approaches half an hour.
+for a test that has since gone vacuous — exactly what the gate is there to prevent. Bad trade
+at 109 mutations — past the threshold this paragraph has carried since the gate was written,
+now reached exactly. The full run is approaching half an hour. **The re-evaluation is due now**: the
+next person to add a mutation should decide whether selective re-running has become worth its
+failure mode (a stale PASS for a test that has since gone vacuous), not bump this number again.
 
 Not part of `pnpm run check` — it edits source and re-runs whole e2e suites. It belongs in review
 and on the publish path. It is also reachable on demand, without cutting a release:
@@ -324,9 +327,9 @@ exactly the environment where the answer matters.
 
 ### The cost is vitest's cold start, not the tests
 
-Worth knowing before optimising the wrong thing: the specs behind all 43 e2e mutations add up to
+Worth knowing before optimising the wrong thing: the specs behind all 46 e2e mutations add up to
 **~40 seconds**. The step takes ~740s. The remaining ~700s is paying vitest's startup — process
-spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 70 times.
+spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 109 times.
 That work is largely single-threaded I/O and barely scales with cores: the full registry measures
 **744s on a 12-core laptop and 777s on a 4-vCPU CI runner**.
 
@@ -370,6 +373,209 @@ When a change adds or edits a test that claims to fix or pin a bug:
 4. **"Is the mutation the defect, or a proxy for it?"** A mutation that breaks everything proves
    nothing about the specific behaviour.
 
+## `disableConsoleIntercept` — why both runners set it
+
+**Rule: both vitest configs in THIS repo set `disableConsoleIntercept: true`, because both were
+measured and both showed exposure. Do not remove it to get per-file console attribution back
+without reading this first — and do not copy it into another repo without measuring there.**
+
+It is the fix for an `EnvironmentTeardownError` that failed `pnpm run check` roughly **1 run in
+10**, with every test green:
+
+```
+EnvironmentTeardownError: [vitest-worker]: Closing rpc while "onUserConsoleLog" was pending
+ Test Files  108 passed (108)
+      Tests  2300 passed | 1 skipped (2301)
+     Errors  1 error
+```
+
+### The mechanism
+
+vitest normally replaces `globalThis.console` in every worker (`setupConsoleLogSpy()`) and
+forwards each write to the main thread as an `onUserConsoleLog` RPC. At worker teardown
+`execute()` does **not** await those calls — it rejects whatever is still in flight:
+
+```js
+rpc.$rejectPendingCalls(({ method, reject }) =>
+  reject(new EnvironmentTeardownError(`Closing rpc while "${method}" was pending`)))
+```
+
+The rejection surfaces as an unhandled error and fails the run. So a console write from the last
+test of a file can lose a race against its own cleanup.
+
+`disableConsoleIntercept: true` skips `setupConsoleLogSpy()` entirely, so the custom console is
+never installed. Worker-side, `rpc.onUserConsoleLog` has exactly ONE caller — `sendLog()` inside
+that console (`vitest/dist/chunks/console.*.js`); every other reference is main-process reporter
+code. No spy, no caller, nothing that can be pending. **That is a structural fix, not a reduced
+probability** — which matters, because the rate is load-dependent and no number of green runs
+would have proved it.
+
+### The cost, and why it is not what it looks like
+
+The obvious reading — "you lose the `stdout | <file>` prefix" — is wrong, and both configs said so
+until it was measured. With the intercept ON, the default reporter **swallows console output from
+PASSING tests entirely** in a piped run (which is how CI and every piped `check` runs). Removing it
+does not strip a prefix; it makes previously invisible output appear:
+
+```
+nest-server unit    disableConsoleIntercept: false -> 0 visible lines
+                    disableConsoleIntercept: true  -> 8-9 visible lines
+```
+
+The range is not sloppiness: three of those lines are the rate-limit-store capacity warning, whose
+count depends on how many counters a run happens to create, so the total moves between runs. Quote a
+range when a measurement varies — a single number invites the next reader to treat a normal 8 as a
+regression from 9 and go looking for it.
+
+**And count the writes, not one phrasing of them.** A first attempt at re-measuring this grepped for
+`Configured for|No local config` and reported **1**, because the other seven lines are a hub-buffer
+warning, a ConfigService merge notice, three rate-limit warnings and two dev auth URLs — none of
+which match those words. That reads as "no exposure" and is the same artefact as counting reporter
+output, arrived at from a different direction. Diff a flag-off run against a flag-on run instead;
+the difference IS the answer, and it cannot be narrowed by a pattern.
+
+Measure by flipping the value IN THE CONFIG. A CLI override does not win against a config value —
+a first attempt at this measurement was worthless for exactly that reason.
+
+**And it does not point the same way in every suite.** In an e2e config, where the reporter DOES
+print passing-test output, the intercept adds a header line per write, so removing it roughly
+halves the volume. Same flag, opposite ledger.
+
+That direction is the finding; do not quote a figure for it. The `57 → 37` this line used to carry
+came from a comment in the starter's own config (`vitest-e2e.config.ts:96`, "this run went from 57
+visible lines to 37") that nobody here has re-run, and whose scope is ambiguous — the paragraph
+above it discusses a single-spec run, so the numbers may describe one file or the whole suite.
+**Where a number has not been measured, state the direction and stop.** The claim that matters —
+that the ledger flips in an e2e config, because that reporter does print passing-test output — needs
+no figure at all, and a figure nobody can source invites the next reader to treat it as a baseline.
+
+### Not a rule to apply blindly — measure both sides
+
+`nest-server` sets it in both runners because both showed exposure. That is a finding here, not a
+default. `nest-server-starter` deliberately sets it ONLY in the e2e config, `nuxt-base-starter`
+and `offers` set it nowhere — each after measuring.
+
+The trap is the measurement itself. Counting `grep -cE '^(stdout|stderr) \| '` reports what the
+REPORTER PRINTS, not the RPC traffic — so a suite with 114 suppressed writes measures 0 and looks
+immune. That artefact produced a wrong "zero exposure" verdict in the starter before
+`nuxt-base-starter` caught it. The honest procedure is:
+
+1. Exposure — does the suite make `console.*` calls at all? (Nest `Logger` output does not count;
+   it bypasses the intercept.)
+2. Cost — visible lines with the flag versus without, flipped in the config.
+3. Does it actually flake? Write COUNT does not predict the race; write TIMING relative to the end
+   of a file does. The starter's unit suite makes 114 writes and did not flake in 15 runs;
+   nest-server's makes 9 and flaked about 1 in 10.
+
+Where a suite flakes AND the noise cost is high, the better fix is neither option: silence the
+writes at the source. `nuxt-base-starter` measures 0 writes and 0 noise because its
+`tests/unit/setup.ts` mocks `console.debug`/`console.info` globally.
+
+### Three things that made this expensive to diagnose
+
+1. **It is a race, not a late log.** Every spec involved `await`s correctly. Hunting for an
+   unawaited promise finds nothing and sends you the wrong way.
+2. **The reported file is not the cause.** vitest attributes the unhandled rejection to whichever
+   file's worker was running ("It doesn't mean the error was thrown inside the file itself").
+   The file it named logs nothing of its own.
+3. **A wrong explanation survives five green runs.** The first diagnosis here — a keep-alive
+   socket holding a handle — was plausible, fitted the observation, and was WRONG; a bisect with
+   the suspected file excluded still reproduced it. At ~1 in 10, a handful of green runs is not
+   evidence of anything. Bisect, or do not claim a cause.
+
+### Where the output actually came from
+
+Worth recording, because `tests/setup.ts` looks like it already handles this and does not — and
+because the obvious remedy is the wrong one.
+
+**Only raw `console.*` calls feed the RPC. Nest `Logger` output does not.** vitest replaces
+`globalThis.console` and nothing else; it does not patch `process.stdout`/`stderr`. Nest's
+`ConsoleLogger` writes straight to those streams, so its output reaches the terminal without ever
+becoming an `onUserConsoleLog` call. Verified both ways: a `[Nest] … DEBUG …` line carries no
+`stdout | <file>` prefix, while every attributed line traces to a bare `console.*`.
+
+The consequence is the useful part: **silencing the Nest logger does nothing for this flake.**
+`Logger.overrideLogger(['error','fatal'])` — and any per-spec capture of `logger.error` — is noise
+reduction, not a fix. Reaching for it because the loud lines look like the culprit is a dead end.
+
+The writes that actually fed the RPC:
+
+| Source | Call |
+|--------|------|
+| `common/helpers/config.helper.ts` | `console.info` — "Configured for: …", "No local config.json found!" |
+| `common/services/config.service.ts` | `console.warn` from `mergeConfig` |
+| `common/services/rate-limit-store.ts` | `console.warn` from `InMemoryRateLimitStore.hit` |
+| `modules/hub/hub-buffer.ts` | `console.debug` from `readShared` |
+| `modules/better-auth/…-email-verification.service.ts` | `console.log` from `logAuthUrlForDevelopment` |
+
+### Separately: capture the error output a spec EXPECTS
+
+Independent of the flake, and still worth doing — `captureExpectedLogs()` in
+`tests/helpers/expected-log-output.ts`. A spec that deliberately drives a failure path (SMTP down,
+Redis refused, GridFS chunks missing) otherwise prints `logger.error` plus stack traces on a GREEN
+run. That is the same "output that is always there is output nobody reads" argument the rest of
+this file makes, and the helper RETURNS what was logged so the message becomes an assertion rather
+than noise. Four specs use it; three gained a real assertion in the process, and one —
+`'re-throws a send failure after logging it'` — had never asserted the half of its name after the
+comma.
+
+Do not reach for a global silence instead: `Logger.overrideLogger([])` would also silence the
+failing run, removing the diagnostics you need exactly when something breaks.
+
+## A catch that asserts nothing makes its test pass on every outcome
+
+**Rule: a `catch` block in a test either asserts something that could be false, or rethrows. Never
+`expect(error).toBeDefined()`, and never an empty body.**
+
+The shape, which reads as careful error handling and is the opposite:
+
+```typescript
+try {
+  const response = await testHelper.rest('/iam/two-factor/enable', { statusCode: 200 });
+  expect(response).toBeDefined();
+} catch (error) {
+  expect(error).toBeDefined();   // ← both branches assert "something happened"
+}
+```
+
+`testHelper.rest()` throws when the status does not match — that is what passing `statusCode` is
+for. The catch swallows exactly that throw. The case is green whether the endpoint works, answers
+404, 500s, or is not routed at all.
+
+### What it was hiding, measured
+
+Removing the swallow from `better-auth-plugins.story.test.ts` turns **17 of its 45 cases red**. All
+are status-code mismatches — `404` where `200` was declared, `400` where `401` was, and the reverse.
+None describes a broken user path. They are expectations written against assumptions nobody could
+check, because the catch hid the answer for the whole life of the test.
+
+### Why they were not simply fixed
+
+Writing down what each endpoint currently answers would be **worse than leaving them**: it turns a
+test that checks nothing into one that certifies possibly-wrong behaviour, and freezes it. Deciding
+what each endpoint *should* answer is real investigation — 40 blocks across 6 suites — and belongs
+in its own change.
+
+`tests/unit/swallowing-catch-baseline.spec.ts` therefore locks the count at its current value
+instead. It may fall, never rise; a new suite gaining the pattern fails separately from the total,
+because a flat total can still hide a migration into a fresh file. When you fix a batch, lower the
+baseline in the same commit — the failure message tells you the number.
+
+### The sibling shape: a guard that is never false
+
+```typescript
+it('should build the frontend URL', () => {
+  if (config.callbackURL) {      // ← set in NO environment of this repo
+    expect(url).toContain('token=');
+  }
+});
+```
+
+Two such cases lived in `better-auth-email-verification.story.test.ts` and asserted nothing for
+their entire life. They were deleted once `tests/unit/verification-link.spec.ts` covered the
+behaviour unconditionally. **A guard that depends on configuration must be checked against the
+configuration that actually exists** — `grep` for the key in `config.env.ts` before trusting one.
+
 ## Known coverage gap: no load-test baseline for the auth endpoints
 
 There is no `tests/k6/` in this repository — no config, no endpoint scripts, no baselines. That is
@@ -392,6 +598,33 @@ The vector predates 11.38.0 — Better-Auth already hashed on reset — so this
 factor roughly doubling, not a new exposure. It is not scaffolded here because a load profile
 belongs with a running API and an agreed traffic shape, not bolted onto a static review.
 
+## A test that reads `CI` answers differently on a runner
+
+**Rule: when a spec drives behaviour that depends on the `CI` environment variable, it must PIN the
+variable — never inherit it.** Otherwise the assertion means one thing on a laptop and another on a
+runner, and the laptop is where it gets written.
+
+`scripts/check-overrides.mjs` is the case: an unverified suppression is TOLERATED locally and
+ESCALATED to a hard failure under `CI`, deliberately, because a skip nobody reads is
+indistinguishable from a check that ran. `tests/unit/check-overrides.guard.spec.ts` spawns that
+guard, so every case it runs inherits whatever `CI` the surrounding process has.
+
+One case did not pin it, asserted `status === 0`, and passed locally for its whole life. It failed
+the release CI run for 11.40.0 — the first time it had ever executed on a runner. The fix is one
+line (`env: { CI: '' }`); the point is that nothing would have found it earlier, because the
+environment that breaks it is the one nobody runs tests in by hand.
+
+**Before a release, run the unit suite the way a runner sees it:**
+
+```bash
+CI=true npx vitest run --config vitest.config.ts --reporter=dot
+```
+
+Deliberately NOT wired into `check`. It would run all 2381 unit tests a second time — about 40s on
+every local check — to protect against a class that currently has exactly one member, and CI itself
+already catches it at the cost of one failed PR run. Revisit that trade if a second env-dependent
+spec appears; the balance is about how many, not about principle.
+
 ## Consumer gate: the starter runs BEFORE publish, not after
 
 `pnpm run check:consumer` builds the tarball (`pnpm pack`), installs it into a **throwaway copy** of

package/CLAUDE.md

@@ -24,7 +24,8 @@ The following documents must be kept up to date when making changes that affect
 | `.claude/rules/configurable-features.md` | Adding new configurable features |
 | `src/templates/*.ejs` + `tests/unit/email-templates.spec.ts` | Changing a mail template — a template is never imported, type-checked or linted, so the only thing binding it to its caller is the variable names inside it. Add the caller's data shape to the spec |
 | `FRAMEWORK-API.md` | Auto-regenerated by `pnpm run build` — verify after adding interfaces, CrudService methods, or core modules |
-| `.claude/rules/testing.md` | Changing the test-runner split, the per-run DB lifecycle or its **drop guard**, the run governor, the infrastructure containers, or the regression-evidence gate. This row exists because the drop guard — the one thing standing between a test run and a developer's data — went undocumented for its whole life: nothing in this table pointed at the file that describes everything around it |
+| `.claude/rules/package-management.md` | Changing the `overrides:` set, adding or removing an `auditConfig.ignoreGhsas` suppression, or changing the `check:overrides` guard. Same reasoning as the row below: the guard exists because an override and a suppression both decay in silence — and a guard nobody knows about decays exactly the same way |
+| `.claude/rules/testing.md` | Changing the test-runner split, the per-run DB lifecycle or its **drop guard**, the run governor, the infrastructure containers, the regression-evidence gate, or **`disableConsoleIntercept`** (both runners set it; removing it to get per-file console attribution back re-arms an `EnvironmentTeardownError` that fails `check` roughly 1 run in 10 with every test green). This row exists because the drop guard — the one thing standing between a test run and a developer's data — went undocumented for its whole life: nothing in this table pointed at the file that describes everything around it |
 
 **Rule:** When a code change adds, removes, or modifies a feature listed in `docs/REQUEST-LIFECYCLE.md` (Features Overview, diagrams, decorator reference, configuration, etc.), update the document in the same commit or PR.
 
@@ -131,6 +132,17 @@ pnpm run lint:fix       # Auto-fix
 pnpm run format         # oxfmt format
 
 # Import-cycle / SWC safety (part of `check`)
+# Supply-chain guards (part of `check`)
+pnpm run check:overrides # Cross-checks every pnpm override and every auditConfig.ignoreGhsas
+                        # suppression against live advisory data. The only step that catches an
+                        # override whose target drifted BELOW the advisory's fixed-in version:
+                        # `pnpm audit` reports the advisory, but nothing otherwise says that a
+                        # supposed remedy for it is already sitting in pnpm-workspace.yaml.
+                        # Also catches a suppression upstream has since patched — those are
+                        # invisible to `pnpm audit` by design, so nothing else can.
+                        # See .claude/rules/package-management.md → "Overrides AGE"
+pnpm peers check        # pnpm 11 builtin: unmet/missing peer dependencies, read from the lockfile
+
 pnpm run check:swc-tdz  # SWC→CJS build, loads EVERY module as its own entry point.
                         # The only step that catches a temporal-dead-zone crash from an
                         # import cycle — tsc, vitest and oxlint are all blind to it.

package/FRAMEWORK-API.md

@@ -1,6 +1,6 @@
 # @lenne.tech/nest-server — Framework API Reference
 
-> Auto-generated from source code on 2026-09-02 (v11.38.0)
+> Auto-generated from source code as of 2026-09-04 (v11.40.0)
 > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
 
 ## CoreModule.forRoot()
@@ -109,7 +109,7 @@ When `passkey` is enabled, `trustedOrigins` is required (compile-time enforcemen
 
 ### IAi
 
-  - `allowedBaseUrlHosts?`: `string[] | undefined` — Optional SSRF allowlist for connection base URLs. When set (non-empty), the
+  - `allowedBaseUrlHosts?`: `string | string[] | undefined` — Optional SSRF allowlist for connection base URLs. When set (non-empty), the
   - `audit?`: `boolean | undefined` (default: `false`) — Persist an audit record (`aiInteractions`) for every prompt run (admin-readable).
   - `budget?`: `{ period?: "day" | "month" | "none"; tenant?: { maxPrompts?: number; maxToken...` — Token/prompt budgets for AI prompts, enforced before a run (HTTP 429 + translated
   - `capabilityDriftCheck?`: `boolean | undefined` (default: `false`) — Opt-in boot self-check: after startup, probe each enabled connection that declares

package/dist/config.env.js

@@ -7,6 +7,7 @@ const path_1 = require("path");
 const role_enum_1 = require("./core/common/enums/role.enum");
 const config_helper_1 = require("./core/common/helpers/config.helper");
 dotenv.config({ quiet: true });
+const productionSmtpPort = parseInt(process.env.SMTP_PORT || '587', 10);
 const config = {
     ci: {
         auth: {
@@ -591,8 +592,9 @@ const config = {
                     user: process.env.SMTP_USER,
                 },
                 host: process.env.SMTP_HOST,
-                port: parseInt(process.env.SMTP_PORT || '587', 10),
-                secure: process.env.SMTP_SECURE !== 'false',
+                port: productionSmtpPort,
+                requireTLS: process.env.SMTP_REQUIRE_TLS !== 'false',
+                secure: (0, config_helper_1.resolveSmtpSecure)(process.env.SMTP_SECURE, productionSmtpPort),
             },
         },
         env: 'production',