@lenne.tech/nest-server 12.2.0 → 12.3.1

package/migration-guides/12.2.x-to-12.3.x.md

@@ -0,0 +1,440 @@
+# Migration Guide: 12.2.x → 12.3.x
+
+## 12.3.0 contains breaking changes
+
+The version number moves only the MINOR digit (the MAJOR follows NestJS). Read §1–§3, §7 and §8 before you update: none
+of them needs code in a typical project, but each one changes what a running application does.
+
+## Overview
+
+| Category | Details |
+|---|---|
+| **Breaking Changes** | E-mail verification no longer signs the user in (§1). A prompt continues only the caller's own AI conversation, `CoreAiConversationService.appendMessage()` takes the owner and the protected `CoreAiService.persistTurn()` the run as a third parameter (§2). Non-canonical paths under the Better-Auth base path answer 400, and the IAM rate limit tells routes apart, with half the limit on sign-in and sign-up (§3). `emailAndPassword.disableSignUp: true` closes social sign-up too (§7). `AiTool.authorize()` runs on every path, and MCP asks before a destructive tool or refuses a client that cannot ask (§8) |
+| **New Features** | `socialProviders.<name>.disableSignUp` opens or closes sign-up for one provider (§7). `ai.mcp.confirmation` and a per-user switch (`GET/PUT /ai/settings`), `context.authorization` for tools, `destructiveHint` annotations in `tools/list` (§8). `ai.nativeToolCatalog`, a warning for a crowded context window (§9). `ai.mcp.stateless`, consent page `texts` / `styles` (§10). `CoreTenantService.purgeTenantData()` and `deleteAllMembers()` remove a tenant's data (§11) |
+| **Bugfixes** | Login CSRF through a forwarded verification link (§1), turns written into another user's AI conversation (§2), rate limiter bypass through dot segments and an IAM rate limit that never told routes apart over HTTP (§3), a planned end of the SSE hint stream logged as a lost session (§4), a sync push that applied a change chained to a refused one in the same request on another writer's version (§5), an open redirect through `/authorize` of the MCP OAuth endpoints (§6), new accounts through social login while sign-up was switched off (§7), tool checks and admin tool policies that MCP and auto mode skipped (§8), tool descriptions sent twice to native connections and native tool definitions missing from the context budget (§9), cached memberships that kept a deleted tenant reachable for up to `cacheTtlMs` after `invalidateTenant()` (§11) |
+| **Dependencies** | `@nestjs/graphql` 14.1.0 → 14.1.2, `@nestjs/apollo` 14.1.1 → 14.1.2, `@nestjs/swagger` 12.0.5 → 12.1.0, `@tus/server` 2.4.6 → 2.4.7, `@tus/file-store` 2.1.1 → 2.1.2, `jose` 6.2.13 → 6.2.15, `nodemailer` 10.3.0 → 10.3.1. Tested optional peers raised: `bullmq` 6.5.1 → 6.5.4, `@aws-sdk/client-s3`, `@aws-sdk/lib-storage`, `@aws-sdk/s3-request-presigner` 3.1159.0 → 3.1161.0, `@tus/s3-store` 2.0.9 → 2.1.0, `kysely` 0.29.7 → 0.29.8 — `pnpm run update` raises them where a project pins them. Development: `vitest` 5.0.5 → 5.1.0 together with `vite` 8.3.4 → 8.3.5 (Dependencies) |
+| **Migration Effort** | Usually none. A frontend whose verify page expects a session: one redirect. A project calling `appendMessage()` or overriding `persistTurn()`: one argument. A deployment with a tight `betterAuth.rateLimit.max`: check the value (§3). A project that closed sign-up but wants new users through a social provider: one flag on that provider (§7). A project using destructive AI tools over MCP: check the clients, offer users the switch (§8) |
+
+## Quick Migration
+
+```bash
+pnpm add @lenne.tech/nest-server@12.3.0
+pnpm run update   # nest-server-starter based projects: aligns the pins the framework raised
+pnpm run build
+pnpm test
+```
+
+**Vendor mode**: run `/lt-dev:backend:update-nest-server-core` as usual.
+
+### Dependencies
+
+`pnpm run update` raises the pins a project shares with the framework: `@nestjs/graphql`, `@nestjs/apollo` and
+`@nestjs/swagger` (patch and minor releases of NestJS, no API change), the optional peers it tests against, and the
+development tooling. Nothing else in a project changes.
+
+**`vite` may leave 8.3.4 now.** The 12.0.x guide (§12) asked to keep `vite` at 8.3.4 while `vitest` was 5.0.5: that
+combination crashed a run with a `globalSetup` or an own reporter after every test was green (`code.charCodeAt is not a
+function`, vitest-dev/vitest#11682). `vitest` 5.1.0 carries the fix. Raise both together — `vite` 8.3.5 with `vitest`
+below 5.1.0 still crashes.
+
+## 1. Auto sign-in after e-mail verification is off by default
+
+`betterAuth.emailVerification.autoSignInAfterVerification` defaulted to `true`; it is now `false`, which is
+Better-Auth's own default.
+
+With the option on, `GET /iam/verify-email` creates a session for the account the link belongs to in whatever browser
+opens the link. A verification link travels by mail, so it can be forwarded: someone who signs up with their own
+address and sends the unopened link to someone else has that person's browser signed in to the sender's account, and
+what the recipient enters there (payment data, documents, messages) lands with the sender (login CSRF).
+
+**What changes:** after clicking the link the user is verified but not signed in, and signs in once.
+`CoreBetterAuthEmailVerificationService.shouldAutoSignIn()` answers `false` accordingly.
+
+**What to check:** a frontend whose verify page assumes a session afterwards should send the user to the sign-in, for
+example with a "verified, please sign in" message. The nuxt-base-starter's verify page already does ("Jetzt
+anmelden").
+
+**To keep the previous behaviour** — only where a verification link reaches nobody but its owner:
+
+```typescript
+// config.env.ts
+betterAuth: {
+  emailVerification: {
+    autoSignInAfterVerification: true,
+  },
+},
+```
+
+Only the boolean `true` switches it on (`NSC__*` variables turn `true` into a boolean). Any other value — the string
+`"true"` in `NEST_SERVER_CONFIG`, `1`, `yes` — is read as off, in what Better-Auth receives and in what
+`shouldAutoSignIn()` answers alike.
+
+## 2. A prompt continues only the caller's own AI conversation
+
+`POST /ai/prompt`, `POST /ai/stream` and the GraphQL `aiPrompt` accepted any `conversationId` and wrote the new turns
+into that conversation, also when it belonged to another user. Now a `conversationId` the caller did not create —
+another user's, or one that does not exist — counts as no conversation: the run reads no history, writes nothing, uses
+no conversation-scoped tool grants, and its response carries no `conversationId`. **Administrators are no exception**:
+they still read every conversation (`getAiConversation`, `findAiConversations` with `all`), but continue only their
+own.
+
+`CoreAiConversationService.appendMessage()` checks the owner itself and has a third parameter:
+
+**Before:**
+```typescript
+await this.conversationService.appendMessage(conversationId, { content, role: 'user' });
+```
+
+**After:**
+```typescript
+// The id of the user the turn belongs to; anyone else's turn is not written.
+await this.conversationService.appendMessage(conversationId, { content, role: 'user' }, currentUser.id);
+```
+
+A call without it fails to compile (TS2554). A subclass that overrides `appendMessage()` and does not call `super`
+must check the owner itself — `isOwnedBy(id, userId)` is the new public helper for it.
+
+The protected `CoreAiService.persistTurn()`, which calls `appendMessage()`, takes the run as a third parameter for the
+same reason — the owner comes from `run.currentUser`:
+
+```typescript
+// Before: protected async persistTurn(input, response)
+protected override async persistTurn(input: CoreAiPromptInput, response: CoreAiResponse, run: AiRunContext) {
+  // … your own steps …
+  await super.persistTurn(input, response, run);
+}
+```
+
+An override that still calls `super.persistTurn(input, response)` fails to compile (TS2554).
+
+## 3. Requests under the Better-Auth base path
+
+### Non-canonical paths answer 400
+
+Every check under the base path (`/iam` by default) — rate limiter, controller routes, the forwarding to Better-Auth —
+read the path as sent, while Better-Auth routes the path after `new URL()` resolved it. `/iam/callback/../sign-in/email`
+therefore passed the rate limiter as a skipped OAuth callback and ran as a sign-in.
+
+`CoreBetterAuthPathGuardMiddleware` now runs first under the base path and answers **400** (`#LTNS_0305: Invalid
+request path`) for a path with a `.` or `..` segment (also `%2e`-encoded), a backslash, an encoded `/` or `\`, or a
+`#`. No Better-Auth route needs any of them; a client that sends one has a bug. It is registered by
+`CoreBetterAuthModule` itself — nothing to add.
+
+### The IAM rate limit tells routes apart
+
+The rate-limit middleware read `req.path`, which is `/` for a middleware Nest mounts under the base path. So every IAM
+request of a client shared one counter with the full limit, the skip list (`/session`, `/callback`) and the halved
+limit for sign-in, sign-up and the password routes never applied over HTTP.
+
+Now a client IP has one counter per route NAME — the last path segment — so `/sign-in/email` and `/sign-up/email` (both
+`email`) share one counter. `/session` and `/callback` are not counted, and the strict routes (sign-in, sign-up, the
+password reset and change routes) get half of `betterAuth.rateLimit.max`, rounded up. The skip and strict lists match
+whole path segments, case-insensitively, as Express routes.
+
+**What to check:** a deployment that set `betterAuth.rateLimit.max` (the nest-server-starter reads it from
+`IAM_RATE_LIMIT_MAX`) gets half of it for the e-mail sign-in and sign-up now, and the two count together — with
+`max: 10`, five attempts per window for both combined. Behind a shared NAT or proxy, sign-ups use up the same budget as
+sign-ins. Raise the value if that is too tight. A single-page app that polls `/iam/session` no longer uses up the
+limit.
+
+## 4. SSE hint stream: a planned end logs on debug
+
+`GET /sync/hints` ends its stream on every re-check (`graphQl.subscriptionRevalidationMs`) and the client reconnects.
+Every such planned end logged `Closing GraphQL WebSocket of user …: Session no longer valid` at log level. It now logs
+`Closing SSE hint stream of user …` on debug; an end an invalidation causes (role change, sign-out) stays at log level.
+
+`registerWsConnection()` takes two optional fields for a long-lived channel of a project's own: `channel` (the name in
+the log line, default `GraphQL WebSocket`) and `endsOnRecheck` (every re-check ends the connection). GraphQL WebSockets
+log as before.
+
+## 5. Sync push: a change chained to a refused one is held back
+
+A client sends the changes of one record with chained base versions, also in one push (protocol §6.2). The server
+applied every item on its own: when the first item conflicted with another writer's version 2, the second — base
+`2` — matched that version and was stored on data the client never saw, while the client dropped it locally.
+
+Once an item of a record is not stored (`conflict`, `rejected`, `not_found`, `retry`), the later items of that record
+in the same push are now held back: answered `retry` behind a `retry`, otherwise `conflict` with the current record
+(`not_found` when the caller may not see one). Items of other records are unaffected.
+
+The server holds back within one request only. Protocol §11 now says what a client does across requests: it sends a
+later change of a record only in the same request as the change before it, or after that one came back `applied` or
+`merged`, and drops or rebases the later changes of a record whose change was `rejected` or `not_found`. **Check your
+client** if it splits its queue into several requests (the protocol caps a push at
+`sync.push.maxItems`, 100 by default): after a `retry` it must keep the record's later changes back until the next
+sync. A client that sent a single change per record and request to avoid the defect may send chains in one request
+again; across requests it still waits for each answer.
+
+## 6. MCP OAuth: no error redirect to a self-registered URI
+
+Only with `ai.mcp.oauth: true`. Dynamic client registration accepts any redirect URI, and the MCP SDK sent an error
+it found after the client check (a missing `code_challenge`, a wrong `response_type`) to that URI with a 302. A client
+registered with a foreign URI turned one crafted `/authorize` link into a redirect from the API's own domain to any
+site. Such an error is now answered with `400` and `{ error, error_description }`. Registration stays open, so
+claude.ai, ChatGPT, Cursor and Claude Code connect as before; the user's Allow and Deny on the consent page still
+redirect.
+
+The built-in Deny now needs the consent form's CSRF token, as Allow always did; a Deny without it shows the form again.
+A consent UI of your own (`authorizeConsent()` override) should check its token on Deny too — see the AI module's
+INTEGRATION-CHECKLIST.
+
+## 7. Social login creates no account while sign-up is switched off
+
+Only with `betterAuth.emailAndPassword.disableSignUp: true` and at least one social provider. The flag closed
+`/sign-up/email` only. Better-Auth decides a social sign-up per provider, and each provider got only its `clientId` and
+`clientSecret`, so whoever signed in with Google, GitHub etc. for the first time got an account in a project that had
+closed self-registration (accounts only through an admin or an invitation).
+
+**What changes:** every configured provider now receives the flag. A first sign-in through a provider by somebody who
+has no account is refused (the OAuth callback redirects with `error=signup_disabled`, `/sign-in/social` with an
+`idToken` answers 401 `signup disabled`). Users who already have an account keep signing in, also through a provider
+they have not used before: Better-Auth checks the flag only when no user exists for the address.
+
+**What to check:** a project that closed sign-up on purpose needs nothing. A project that closed e-mail sign-up but
+wants new users through a provider opens that one deliberately:
+
+```typescript
+// config.env.ts
+betterAuth: {
+  emailAndPassword: { disableSignUp: true },
+  socialProviders: {
+    google: { clientId: '...', clientSecret: '...', disableSignUp: false }, // new users through Google
+    github: { clientId: '...', clientSecret: '...' },                       // follows disableSignUp: closed
+  },
+},
+```
+
+`disableSignUp: true` on a provider closes sign-up for that provider alone, while sign-up stays open elsewhere. Only a
+boolean counts there: any other value, such as the string `"false"` in `NEST_SERVER_CONFIG`, follows
+`emailAndPassword.disableSignUp`. `GET /iam/features` keeps reporting `signUpEnabled` from the global flag. Plugins a
+project registers itself through `betterAuth.options.plugins` (Generic OAuth, Magic Link, …) are not covered; set their
+own sign-up options.
+
+## 8. AI tools: `authorize()` on every path, confirmation over MCP
+
+Only with the `ai` module. Two gates held in the chat's plan mode alone:
+
+- **`AiTool.authorize()`** ran in plan mode only. Auto mode (the default) and `/ai/mcp` called `execute()` directly,
+  so a data-level check a tool placed there ("may this user change record 42?") did not run for most callers.
+- **`destructive` / `mutating`** were read by the chat only. Over MCP a destructive tool ran on the first call, and an
+  admin's `aiToolPolicies` rules (`deny`, `ask`) did not apply at all.
+
+**What changes:**
+
+- `authorize()` runs before every execution — auto mode, plan mode (for the whole plan, and again per step), MCP — on
+  the arguments that will run, after the PreToolUse hooks. A thrown `authorize()`, a missing answer or an `allowed`
+  that is not exactly `true` refuses the call. The model receives `TOOL_NOT_AVAILABLE` with the `reason` (keep it
+  free of anything the user may not know); a refusal is no longer a learning signal. Return `data` to hand what the
+  check loaded to `execute()` as `context.authorization.data`.
+- `tools/call` applies the admin's tool policies (`deny` refuses, `ask` asks), then `authorize()`, then asks the user
+  through **MCP elicitation** before a `destructive` tool, and before a `mutating` one when `ai.confirmation.mutating`
+  says so (`enforced`, else `default`). Only an explicit yes runs the tool. **A client without the `elicitation`
+  capability gets an error result for such a tool.**
+- Each user may switch the question off for themselves, like a "bypass permissions" mode: `PUT /ai/settings` with
+  `{ "mcpConfirmation": false }` (GraphQL `updateAiSettings`), read with `GET /ai/settings` (`aiSettings`). The choice
+  is stored per user in the new `aiUserSettings` collection / table, created at boot like every AI model.
+  `authorize()` and the admin's `deny` / `ask` rules apply whatever the user chose.
+- `tools/list` carries `annotations` (`destructiveHint`, `readOnlyHint: false`) for `destructive` and `mutating`
+  tools. A tool with neither flag carries none, so it is never advertised as read-only.
+
+**What to check:**
+
+1. **Tools with `authorize()`:** it now runs in auto mode and over MCP too. A check written for plan mode only (for
+   example one that refuses whatever it does not expect) refuses those callers from now on. A tool without
+   `authorize()` is unchanged.
+2. **MCP clients:** whether yours support elicitation. Where a client you need cannot ask, choose the default for the
+   deployment:
+
+```typescript
+// config.env.ts
+ai: {
+  mcp: {
+    confirmation: true,                                // default: asks, each user may switch it off
+    // confirmation: false,                            // asks nobody, each user may switch it on
+    // confirmation: { default: true, enforced: true } // asks everybody, nobody may switch it off (403 #LTNS_0609)
+  },
+},
+```
+
+   Only `false` / `default: false` switch the default off and only `enforced: true` enforces; any other value keeps
+   asking.
+3. **Your frontend:** offer the switch where users manage their AI settings — `mcpConfirmationEnforced: true` in the
+   answer means it is fixed and should be shown disabled.
+
+**API changes:** `CoreAiMcpService.mcpCallTool()` takes an optional fourth parameter (`{ confirm }`), its constructor
+two optional services (`CoreAiUserSettingService`, `CoreAiToolPolicyService`). `CoreAiController` and
+`CoreAiResolver` receive `CoreAiUserSettingService` as an injected property, so a project subclass keeps its
+constructor. `CoreModule.forRoot(env, { ai: { userSettingService } })` replaces the new store.
+
+## 9. AI: names-only tool catalog for native connections, a context window that counts the tools
+
+Only with the `ai` module and a connection that uses native tool calling (`supportsNativeTools: true`, detected
+automatically).
+
+**What changes:**
+
+- The system prompt's tool catalog lists **tool names only** for such a connection in auto mode. Descriptions and
+  parameter schemas reach the model through the native `tools` payload as before. Until now the catalog repeated them,
+  so every tool was sent twice. Emulated connections and plan mode keep the full catalog.
+- The native tool definitions count against the context budget, so older turns are summarized or dropped before the
+  window overflows rather than after.
+- When the system prompt and the tool definitions take more than half of a connection's input budget, the framework
+  logs one warning per connection and process. It names the numbers and says whether the window is the connection's
+  own or the `ai.contextWindow` fallback. Until now the only trace was a debug line, and the user's message was cut
+  without notice.
+
+**What to check:**
+
+1. Nothing for most projects. A model that picks tools noticeably worse without the descriptions in the prompt gets
+   the old catalog back:
+
+```typescript
+// config.env.ts
+ai: {
+  nativeToolCatalog: 'full', // default 'names'
+},
+```
+
+2. A project test that guards the prompt size: it measures against the `ai.contextWindow` fallback, so it guards
+   connections without a window of their own. Keep it, and name it that way. Raising its limit removes the guard.
+3. `deferToolSummaryChars` never applied to native connections in auto mode and still does not. It applies to emulated
+   connections and plan mode.
+
+## 10. MCP without sessions, and the consent page's wording and look
+
+Both are opt-in; nothing changes without configuration.
+
+**`ai.mcp.stateless: true`** serves `/ai/mcp` without sessions.
+- Every POST builds its own server and transport for the authenticated user, and no `mcp-session-id` is issued.
+- A session id a client still sends is ignored. GET and DELETE answer `405` with `Allow: POST`.
+- Any replica answers any request, so `/ai/mcp` no longer needs sticky sessions behind a load balancer.
+- There are no server-initiated requests in this mode, so the server cannot ask the user (§8). A tool that needs
+  confirmation is refused unless the user switched the question off (`PUT /ai/settings`) or
+  `ai.mcp.confirmation` is `false`.
+- `testHelper.mcpSession()` follows the setting: no session id is expected or sent, and `sessionId` is `''`.
+
+```typescript
+// config.env.ts
+ai: { mcp: { oauth: true, stateless: true } },
+```
+
+**Consent page wording and CSS.** A subclass of `CoreAiMcpOAuthService` overriding `renderConsentPage(view)` calls
+`renderMcpOAuthConsentPage(view, { texts, styles })`.
+- `texts` replaces single texts per locale. They stay escaped.
+- `styles` is CSS appended inside the page's `<style>` element. A `<` in it is neutralized, so the CSS cannot end that
+  element, and the page's CSP blocks external loads.
+- Fill both from code or configuration only.
+- The page's scripts and security headers stay internal and are not exported.
+
+## 11. Removing a tenant
+
+The core had no way to delete a tenant's data: a project had to find every place itself, and the ones that are not a
+`tenantId` field (API tokens, the AI settings with `scope: 'tenant'`, the AI connections' `tenantIds`) were the easy ones
+to miss. When a project deletes its tenant record, it now calls:
+
+```typescript
+const report = await this.tenantService.purgeTenantData(tenantId); // { TenantMember: 4, Invoice: 120, ApiToken: 2 }
+await this.tenantService.purgeTenantData(tenantId, { dryRun: true }); // counts only
+await this.tenantService.purgeTenantData(tenantId, { exclude: ['AuditEntry'] });
+```
+
+- Every way in goes first: the memberships (`deleteAllMembers()`, new as well), with every member's cached access
+  ending at once, and the tenant's API tokens, which need no member.
+- Then every registered model with a `tenantId` path, on MongoDB and SQL, the project's own models included; the core
+  models that name the tenant in another field; and the AI connections — one only this tenant could use is deleted,
+  from a shared one the tenant is removed.
+- Not deleted: models in `multiTenancy.excludeSchemas` or `exclude`, users, and files. Delete a tenant's files through
+  `CoreFileService` first; only the project knows which ones are the tenant's. Users stay also where `User` carries a
+  `tenantId`: delete per-tenant users through the user service first, which also ends their Better-Auth sessions.
+- A project reference the core does not know of: override the protected `purgeTenantRecords()` and call `super`.
+- The purge runs as a system operation. Call it only from a route that checked who may delete the tenant.
+
+**Also changed:** `CoreTenantGuard.invalidateTenant()` clears the tenant's cached memberships and every cached tenant
+list that contains it, on every replica with Redis. Before, it forgot only the `isTenantActive` answer: where a project
+removed a tenant's memberships without calling `invalidateUser()` (a deleted tenant) and no `isTenantActive` answered
+`false`, the cached memberships kept the members in for up to `cacheTtlMs`. A tenant switched off through
+`isTenantActive` was already refused at once. Nothing to change in a project.
+
+## Compatibility Notes
+
+| Pattern | Status |
+|---|---|
+| Frontend verify page that leads to the sign-in | Unchanged |
+| Frontend verify page that expects a session after the link | Redirect to the sign-in, or set `autoSignInAfterVerification: true` (§1) |
+| Project calling `appendMessage()` | Pass the owner id (§2) |
+| Project subclass of `CoreAiService` overriding `prompt()` | Call `super.prompt()`, or the conversation is not scoped (§2) |
+| Project subclass of `CoreAiService` overriding `persistTurn()` | Take `run` as third parameter and pass it to `super` (§2) |
+| Project controller extending `CoreBetterAuthController` | Unchanged; the path guard runs before it |
+| Custom `betterAuth.rateLimit.skipEndpoints` / `strictEndpoints` | Matched by whole segments now: `/session` no longer covers `/sessions-export` |
+| Sync client pushing chained changes of one record in one request | Unchanged; behind a refused item the rest of the chain is answered `conflict` (or `retry`) instead of being applied (§5) |
+| MCP client sending a malformed `/authorize` request | Gets a `400` page in the browser instead of an error redirect (§6) |
+| Own MCP OAuth consent UI (`authorizeConsent()` override) | Unchanged; check the CSRF token on Deny too (§6) |
+| Sync client splitting a record's changes across requests | Keep a later change back until the one before it was stored, drop it after `rejected` / `not_found` (§5, protocol §11) |
+| `disableSignUp: true` without social providers | Unchanged |
+| `disableSignUp: true` with social providers, new users only through admins or invitations | Unchanged in intent; social login no longer creates accounts (§7) |
+| `disableSignUp: true` with a provider meant for self-registration | Set `disableSignUp: false` on that provider (§7) |
+| AI tool without `authorize()` | Unchanged |
+| AI tool whose `authorize()` was written for plan mode | Runs in auto mode and over MCP too (§8) |
+| Destructive AI tool used through an MCP client with elicitation | The user is asked first (§8) |
+| Destructive AI tool used through an MCP client without elicitation | Refused until the user switches confirmation off, or `ai.mcp.confirmation` is `false` (§8) |
+| Project subclass of `CoreAiController` / `CoreAiResolver` | Unchanged; the settings service is property-injected (§8) |
+| Native AI connection | Catalog lists names only; `ai.nativeToolCatalog: 'full'` restores it (§9) |
+| `/ai/mcp` behind a load balancer without sticky sessions | Set `ai.mcp.stateless: true` (§10) |
+| Destructive AI tool over MCP with `ai.mcp.stateless` | Refused unless the user or `ai.mcp.confirmation` switched the question off (§10) |
+| Override of `fitMessagesToContext()` / `compactMessages()` | Unchanged; both take an optional third parameter, the tokens reserved for native tool definitions (§9) |
+| Project deleting tenants with its own clean-up | Replace it with `purgeTenantData()`, or keep it and add what it misses (§11) |
+| Project subclass of `CoreTenantService` | Unchanged; the MongoDB connection the purge reads is property-injected (§11) |
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| User not signed in after clicking the verification link | §1 | Expected; lead to the sign-in, or opt in |
+| TS2554 on `appendMessage()` or `super.persistTurn()` | §2 | Pass the owner id, or the run, as third argument |
+| A continued AI conversation answers without history, no `conversationId` in the response | The conversation belongs to another user (also for admins) | Continue only conversations the caller created |
+| 400 `#LTNS_0305` on an IAM request | The path carries a dot segment, a backslash, an encoded separator or a `#` | Fix the client's URL |
+| 429 on sign-in earlier than before | The strict limit (half of `max`) applies now, shared by e-mail sign-in and sign-up | Raise `betterAuth.rateLimit.max` |
+| New users land on the error page with `error=signup_disabled` after a social login | §7: `disableSignUp: true` covers social providers | Expected; or set `disableSignUp: false` on the provider |
+| MCP answers "needs the user's confirmation, and this MCP client cannot ask for it" | §8: destructive tool, client without elicitation | Use a client with elicitation, or let the user switch it off (`PUT /ai/settings`) |
+| `TOOL_NOT_AVAILABLE` in auto mode for a tool that worked before | §8: its `authorize()` refuses | Fix the check, or return `{ allowed: true }` where it should pass |
+| 403 `#LTNS_0609` on `PUT /ai/settings` | §8: `ai.mcp.confirmation.enforced` | Expected |
+| Warning "the system prompt and tool definitions take ~N of M input tokens" | §9: the window is crowded | Set the connection's `contextWindow`, or shrink the catalog |
+
+## Module Documentation
+
+### Better-Auth
+
+- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md) — "Email Verification", "Rate Limiting", "Disable Sign-Up"
+- **Integration Checklist:** [src/core/modules/better-auth/INTEGRATION-CHECKLIST.md](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
+- **Key Files:** `better-auth.config.ts` (the verification options Better-Auth receives, `buildSocialProviders()`),
+  `core-better-auth-path-guard.middleware.ts`, `core-better-auth-rate-limiter.service.ts`
+
+### AI
+
+- **README:** [src/core/modules/ai/README.md](../src/core/modules/ai/README.md)
+- **Key Files:** `services/core-ai.service.ts` (`scopeConversation()`, `executeToolCall()`), `services/core-ai-conversation.service.ts`
+  (`isOwnedBy()`, `appendMessage()`), `helpers/ai-tool-authorization.helper.ts`, `services/core-ai-mcp.service.ts`
+  (`mcpCallTool()`), `services/core-ai-user-setting.service.ts`
+- **README sections:** "Plan mode", "Authorization and confirmation over MCP"
+
+### AI (MCP OAuth)
+
+- **README:** [src/core/modules/ai/README.md](../src/core/modules/ai/README.md) — "OAuth 2.1", consent page
+- **Integration Checklist:** [src/core/modules/ai/INTEGRATION-CHECKLIST.md](../src/core/modules/ai/INTEGRATION-CHECKLIST.md) — own consent UI
+- **Key Files:** `helpers/ai-mcp-oauth.helper.ts` (`mountAiMcpOAuthRouter()`), `services/core-ai-mcp-oauth.service.ts` (`authorizeConsent()`)
+
+### Multi-Tenancy
+
+- **README:** [src/core/modules/tenant/README.md](../src/core/modules/tenant/README.md) — "Removing a Tenant"
+- **Key Files:** `core-tenant.service.ts` (`purgeTenantData()`, `purgeTenantRecords()`, `deleteAllMembers()`),
+  `core-tenant.guard.ts` (`clearTenant()`)
+
+### Sync
+
+- **README:** [src/core/modules/sync/README.md](../src/core/modules/sync/README.md) — hint stream log lines, held-back push items
+- **Protocol:** [docs/offline-sync-protocol.md](../docs/offline-sync-protocol.md) §6.2, §6.3
+
+## References
+
+- nest-server-starter: no code change; it keeps Better-Auth's defaults, configures neither `disableSignUp` nor a social
+  provider, does not call `appendMessage()`, and configures no `ai` module

package/migration-guides/12.3.0-to-12.3.1.md

@@ -0,0 +1,136 @@
+# Migration Guide: 12.3.0 → 12.3.1
+
+## Overview
+
+| Category             | Details                                                                                                                                                                                                                                                                       |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Security**         | better-auth 1.7.16: closes the better-auth advisories published on 2026-11-03 — social sign-in, passkeys, e-mail change, revoked sessions with a session cache — and brings better-call 1.4.5 (§1) |
+| **New Features**     | `GET /ai/status`: a public answer whether the AI module is on and whether MCP runs (§2)                                                                                                                                                                                       |
+| **Bugfixes**         | `betterAuth.passkey.userVerification`, `residentKey` and `authenticatorAttachment` take effect — they never reached the passkey plugin before (§3). The HTTP safety net strips secret fields under their SQL column names too, so a native SQL row returned by a route no longer hands out `password_reset_token` and the other secrets (§4)                                                                                                                             |
+| **Breaking Changes** | The better-auth peer range starts at 1.7.16 (was 1.7.12). A project pinning an older version gets a peer warning, and keeps the vulnerability, until it raises the pin (§1). A project that set one of the three passkey options now gets what it configured (§3)            |
+| **Migration Effort** | Raise the better-auth trio to 1.7.16 in the API **and** in the app, in the same change (§1). Check §3 if your `betterAuth.passkey` block sets `userVerification`, `residentKey` or `authenticatorAttachment` |
+
+## Quick Migration
+
+```bash
+# API (projects/api)
+pnpm add better-auth@1.7.16 @better-auth/passkey@1.7.16 @better-auth/core@1.7.16
+pnpm add @lenne.tech/nest-server@12.3.1
+pnpm run update   # nest-server-starter based projects
+
+# App (projects/app) — together with @lenne.tech/nuxt-extensions, see its release notes
+pnpm add better-auth@1.7.16 @better-auth/passkey@1.7.16
+
+pnpm run build && pnpm test
+```
+
+Vendor-mode projects pick it up with the core update (`/lt-dev:backend:update-nest-server-core`) and raise the trio in
+their own `package.json`.
+
+## 1. better-auth 1.7.16 (security)
+
+better-auth 1.7.16 closes the better-auth advisories published on 2026-11-03. Whether one reaches your project depends
+on the features it uses; the ones that can matter for a nest-server project:
+
+| Advisory              | Affects you when                                                  |
+| --------------------- | ----------------------------------------------------------------- |
+| GHSA-fvxx-76fc-893x   | revoked sessions stayed valid with secondary storage or the cookie cache |
+| GHSA-9hm7-xhfp-cx58   | social sign-in (`socialProviders`): an unverified provider e-mail counted as verified |
+| GHSA-gv75-j3v8-3crm   | passkeys: origin and user verification were not enforced         |
+| GHSA-hwq2-v29r-p69r   | e-mail change: links stayed valid after the address changed hands |
+| GHSA-48c2-w96j-mv3m   | the Kysely / Drizzle adapter on MySQL with serial ids (nest-server uses ObjectId hex ids) |
+
+It also pins better-call 1.4.5, which fixes GHSA-23w8-wx9r-vm57 (values a router middleware returns were shared between
+requests). That one is not reachable through nest-server, on 1.7.12 as on 1.7.16: better-auth's handler, which
+nest-server calls for every `/iam/*` request it forwards, builds a new router around a per-request copy of its context,
+so no two requests share one, and nest-server's direct `api.*` calls do not go through a router at all. 1.4.5 is a
+second layer there, not the reason for this release.
+
+**Raise all three packages in the API and in the app together.** better-auth is a wire protocol between nest-server
+and nuxt-extensions; the two ends must not run different minors, and the peer ranges of both libraries now start at
+1.7.16. `pnpm run update` does not raise these pins — the project owns them.
+
+**Installing before 2026-11-04 21:24 UTC.** pnpm's `minimumReleaseAge` (24 h) refuses the new versions until then.
+To take the fix the same day, exempt exactly these versions in `pnpm-workspace.yaml` (each carries SLSA provenance
+from the projects' own GitHub Actions) and drop the entries with your next maintenance — after that time they change
+nothing:
+
+```yaml
+minimumReleaseAgeExclude:
+  - '@better-auth/core@1.7.16'
+  - '@better-auth/drizzle-adapter@1.7.16'
+  - '@better-auth/kysely-adapter@1.7.16'
+  - '@better-auth/memory-adapter@1.7.16'
+  - '@better-auth/mongo-adapter@1.7.16'
+  - '@better-auth/passkey@1.7.16'
+  - '@better-auth/prisma-adapter@1.7.16'
+  - '@better-auth/telemetry@1.7.16'
+  - better-auth@1.7.16
+  - better-call@1.4.5
+```
+
+Never override `better-call` alone instead: better-auth pins it exactly, and an override puts a combination into the
+tree that nobody tested.
+
+## 2. `GET /ai/status`
+
+A frontend asks before anybody signs in whether it shows the assistant at all:
+
+| Server                         | Answer                         |
+| ------------------------------ | ------------------------------ |
+| `ai` configured, `ai.mcp` off  | `200 { "mcp": false }`         |
+| `ai` configured, `ai.mcp` on   | `200 { "mcp": true }`          |
+| no `ai` (or `enabled: false`)  | `404` — the route does not exist |
+
+The route is public and names no user data; every other `/ai` route keeps its roles. A project controller extending
+`CoreAiController` inherits it. nuxt-extensions reads it through its AI status composable. Nothing to configure.
+
+## 3. Passkey options take effect
+
+`betterAuth.passkey.userVerification`, `residentKey` and `authenticatorAttachment` were handed to the passkey plugin
+at the top level of its options, where it never reads them: it takes them from `authenticatorSelection`. Every project
+therefore ran on the plugin's defaults (`residentKey` and `userVerification` `"preferred"`, no attachment), whatever it
+configured. Since 12.3.1 the framework passes them where the plugin reads them.
+
+Nothing changes for a project that sets none of the three. A project that sets one gets what it configured, and
+better-auth 1.7.16 now enforces `userVerification: 'required'`: a passkey that answers without user verification (no
+biometric or PIN check) is refused at registration and at sign-in. That is the point of the setting — check it is what
+you want before you update:
+
+```typescript
+// config.env.ts
+betterAuth: {
+  passkey: {
+    userVerification: 'required',          // refuses passkeys without biometric/PIN verification
+    residentKey: 'required',               // registration creates a discoverable credential
+    authenticatorAttachment: 'platform',   // only built-in authenticators (Touch ID, Windows Hello)
+  },
+},
+```
+
+## 4. Secret fields are stripped under their SQL column names too
+
+`CheckSecurityInterceptor` removes the fields of `security.secretFields` (`password`, `verificationToken`,
+`passwordResetToken`, `refreshTokens`, `tempTokens`, `apiKeyEncrypted`, … plus your own) from every response as
+a safety net. It compared the field names only. A row read through `store.native(reason)` or `store.raw(reason)`
+on a SQL source carries the snake_case columns (`password_reset_token`), so a route that returned such a row
+unchanged — a `SELECT *` or `RETURNING *` — dropped `password` (spelled alike) and handed every other secret to
+the client.
+
+Since 12.3.1 each secret field is also stripped under its column name, your own entries in `security.secretFields`
+included. Nothing to change. Still: a route should map a native row to the fields the client needs rather than rely
+on the safety net — see `.claude/rules/persistence.md` → "Native access in three tiers".
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+| ------- | ----- | --- |
+| `ERR_PNPM_NO_MATURE_MATCHING_VERSION` for better-auth 1.7.16 | installed before 2026-11-04 21:24 UTC | add the `minimumReleaseAgeExclude` entries from §1, or wait |
+| `unmet peer better-auth@">=1.7.16 <1.8.0"` | the project still pins an older better-auth | raise the trio (§1) |
+| The app shows no assistant although `ai` is configured | the API answers `/ai/status` with 404 — it runs a version before 12.3.1 | update the API |
+| Passkey registration or sign-in fails after the update for some users | `betterAuth.passkey.userVerification: 'required'` now takes effect, and their authenticator answered without user verification | keep `'required'` and let those users use a verifying authenticator, or set `'preferred'` |
+
+## Module Documentation
+
+- AI module: [`src/core/modules/ai/README.md`](../src/core/modules/ai/README.md) → "Is the assistant available?"
+- Better-Auth: [`src/core/modules/better-auth/INTEGRATION-CHECKLIST.md`](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)