@lenne.tech/nest-server 11.42.11 → 11.42.13

package/docs/REQUEST-LIFECYCLE.md

@@ -167,7 +167,7 @@ JWT-based authentication for existing projects:
 | **REST Endpoints** | `GET /files/id/:id`, `GET /files/:filename` (core, gated by `file.downloadRoles`, default ADMIN); `POST /files/upload`, `DELETE /files/:id` (project-specific) |
 | **GraphQL Endpoints** | `getFileInfo` (`file.downloadRoles`), `uploadFile` / `uploadFiles` (`file.uploadRoles`), `deleteFile` (`file.deleteRoles`) — all default ADMIN |
 | **File access control** | Roles are the coarse filter; per-file rules go in `CoreFileService.checkRights()` using metadata written at upload time. Cover BOTH the `id` and the `filename` branch — the filename route authorizes on the by-name lookup alone when presigned S3 downloads are on, and `deleteFileByName()` always does. Working reference: `src/server/modules/file/file.service.ts` (with `file.downloadRoles: [S_USER]` in `src/config.env.ts`, so the rule is actually reached). Both file classes carry `@SkipTenantCheck()` — GridFS is not tenant-scoped |
-| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })`. Configured by `TusModule.forRoot({ config })`, else the server config's `tus` key (11.42.9+). Switched-off `creation` / `termination` answer 501 (enforced by `CoreTusService`, not `@tus/server`); upload URLs follow the path the upload was created at |
+| **TUS Module** | Resumable uploads via tus.io protocol (creation, termination, expiration), gated by `tus.roles` (default `S_USER`); `OPTIONS` stays public for the CORS preflight. Records owner and, with `multiTenancy` only, the validated tenant at upload creation; a custom service plugs in via `TusModule.forRoot({ service })`. Configured by `TusModule.forRoot({ config })`, else the server config's `tus` key (11.42.9+). Switched-off `creation` / `termination` answer 501 (enforced by `CoreTusService`, not `@tus/server`); upload URLs follow the path the upload was created at. The response that completes an upload carries the stored file's ID as `X-File-Id` (11.42.13+, listed in `Access-Control-Expose-Headers`) — the last segment of the TUS URL is the upload id, not the file id |
 | **GridFS Migration** | Completed TUS uploads auto-migrate to GridFS |
 | **CORS Support** | Automatic CORS headers for browser uploads |
 

package/docs/error-codes.md

@@ -162,6 +162,76 @@ All error codes follow the format: `#PREFIX_XXXX: Description`
 
 ---
 
+### LTNS_0103: notTenantMember
+
+**Message:** Not a member of this tenant
+
+**Description:** Thrown by the CoreTenantGuard when the `X-Tenant-Id` header names a tenant the user has no active membership in
+
+**Solution:** Send the header of a tenant the user belongs to, or add the membership
+
+**Translations:**
+- DE: Sie sind kein Mitglied dieses Mandanten.
+- EN: You are not a member of this tenant.
+
+---
+
+### LTNS_0104: insufficientTenantRole
+
+**Message:** Insufficient tenant role
+
+**Description:** Thrown by the CoreTenantGuard when the membership role in the header's tenant does not satisfy the required tenant role
+
+**Solution:** Raise the membership role or use an endpoint with a lower requirement
+
+**Translations:**
+- DE: Ihre Rolle in diesem Mandanten reicht für diese Aktion nicht aus.
+- EN: Your role in this tenant does not allow this action.
+
+---
+
+### LTNS_0105: insufficientRole
+
+**Message:** Insufficient role
+
+**Description:** Thrown by the CoreTenantGuard when `user.roles` does not meet the required role — without a tenant header, or on a `@SkipTenantCheck` route
+
+**Solution:** Grant the role, or send the tenant header so the membership role is checked
+
+**Translations:**
+- DE: Ihre Rolle reicht für diese Aktion nicht aus.
+- EN: Your role does not allow this action.
+
+---
+
+### LTNS_0106: tenantInactive
+
+**Message:** Tenant is inactive
+
+**Description:** Thrown by the CoreTenantGuard when `multiTenancy.isTenantActive` reports the header's tenant as switched off
+
+**Solution:** Reactivate the tenant, then call `invalidateTenant(tenantId)`
+
+**Translations:**
+- DE: Dieser Mandant ist deaktiviert.
+- EN: This tenant is deactivated.
+
+---
+
+### LTNS_0107: verificationRequired
+
+**Message:** Verification required
+
+**Description:** Thrown by the CoreTenantGuard on an `S_VERIFIED` endpoint for a user who is not verified
+
+**Solution:** Complete the verification of the account
+
+**Translations:**
+- DE: Für diese Aktion muss Ihr Konto verifiziert sein.
+- EN: Your account must be verified for this action.
+
+---
+
 ## User Errors (LTNS_0200-LTNS_0299)
 
 ### LTNS_0200: emailAlreadyExists

package/migration-guides/11.42.10-to-11.42.11.md

@@ -6,7 +6,7 @@
 | -------------------- | -------------------------------------------------------------------------------------------------------- |
 | **Framework API**    | No change                                                                                                |
 | **Test tooling**     | e2e low-resource cap fixed for Vitest 4, e2e run governor hardened, two `check.mjs` false greens closed (§1–§3) — reaches your project only through this guide |
-| **Tests**            | A race in tests that upload to a route a role guard refuses (§4)                                         |
+| **Tests**            | A race in tests that upload to a route a role guard refuses (§4); a red unit file in starter-derived monorepos (§7) |
 | **Documentation**    | `lt dev` exports `NSC__MONGOOSE__URI`, never `MONGODB_URI`; two older guides corrected (§5)              |
 | **Dependencies**     | `nodemailer` 10.1.0 (minor, no API change); dev tooling (§6)                                             |
 | **Breaking Changes** | None                                                                                                     |
@@ -88,7 +88,9 @@ release.
 
 ## 4. Tests that upload to a refused route: send no file
 
-Already in projects generated from **starter 11.41.9 or later** (for the avatar upload test).
+For the avatar upload test, already in projects generated from **starter 11.41.9 or later**. The two upload
+refusals in `tests/modules/file-rest.e2e-spec.ts` (401 and 403 on `/files/upload`) still attached a file until
+**starter 11.42.11**.
 
 When a role guard refuses a multipart upload route, it answers before the file interceptor reads the body. A
 test that still attaches a file races that answer: the 401/403 arrives while the client is writing the
@@ -137,6 +139,20 @@ redoing unless you adapted a script to the wrong name.
 Unchanged on purpose: `express` stays 5.2.1, because `@nestjs/platform-express` 11.2.7 pins it exactly — a
 direct bump would put two copies of express into your tree. `better-auth` stays on 1.7.7, the current release.
 
+## 7. Starter-derived monorepos: a red `audit-suppression-scope.spec.ts`
+
+Fixed in **starter 11.42.11**; affects projects generated from **starter 11.41.7 or later** inside a
+fullstack monorepo.
+
+`tests/unit/audit-suppression-scope.spec.ts` read `pnpm-workspace.yaml` from the API project at COLLECTION
+time. In a monorepo the API has no `pnpm-workspace.yaml` of its own (it lives at the workspace root), so the
+whole file failed to load with `ENOENT` and the unit suite went red without a single test running. The
+starter now reads the file inside the test and guards the monorepo layout with
+`tests/unit/hoisted-layout.spec.ts`; copy both from the current starter.
+
+Optional, also new in starter 11.42.11: its `scripts/check.mjs` ends a hanging `pnpm audit` after a timeout
+(`CHECK_AUDIT_TIMEOUT`) and reports it as not checked, instead of stalling the whole `check`.
+
 ## Compatibility Notes
 
 | Pattern | Status |

package/migration-guides/11.42.11-to-11.42.12.md

@@ -0,0 +1,142 @@
+# Migration Guide: 11.42.11 → 11.42.12
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Security**         | Password-reset and verification links are no longer printed on deployed `develop` / `test` stages (§1); auth cookies carry `Secure` on every https deployment, whatever the environment is called (§2) |
+| **Framework API**    | Additive only: `isLocalEnv()`, `CoreBetterAuthService.usesSecureCookies()`, optional `secureTransport` / `baseUrl` arguments on the cookie helpers |
+| **Dependencies**     | None for the package. The repository's own audit suppression for GHSA-ch52-4w7c-c8xp is gone (§3)        |
+| **Breaking Changes** | None                                                                                                     |
+| **Migration Effort** | None for most projects. Check §1 if you read auth links from a log outside `local` / `ci` / `e2e`, and §2 if you override a cookie-writing method |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update. No code or configuration change is required unless one
+of the checks in §1 or §2 applies to you.
+
+## 1. Auth links are printed only in local environments
+
+`CoreBetterAuthEmailVerificationService.logAuthUrlForDevelopment()` prints the verification and password-reset
+link to stdout so a developer can follow it without a mail server. The URL carries a live bearer token — a reset
+link changes the password outright.
+
+Until this release the link was printed everywhere except `production` and `staging`. The deployed `develop` and
+`test` stages of a starter-based project are neither, so they wrote live reset links into their log pipeline,
+where read access to the logs was enough to take over an account.
+
+| Environment (`env`, else `NODE_ENV`) | Before | After |
+| ------------------------------------ | ------ | ----- |
+| `local`, `ci`, `e2e`                 | printed | printed |
+| `develop`, `test`, `development`, any other name, none at all | printed | **not printed** |
+| `production`, `staging`, `NODE_ENV=production` | not printed | not printed |
+
+`LT_LOG_AUTH_URLS` gained a value:
+
+| Value | Effect |
+| ----- | ------ |
+| unset | the table above |
+| `1`   | also print in an environment that is not in the list — for a developer machine with a different environment name |
+| `0`   | print nowhere, not even locally |
+
+`production` and `staging` never print, whatever the variable says.
+
+**What to check:**
+
+- **Your local environment has another name** (e.g. `development`): set `LT_LOG_AUTH_URLS=1` in your local
+  `.env`. Never set it on a deployment.
+- **A script or CI job reads `[EMAIL VERIFICATION]` / `[PASSWORD RESET]` from the API log** — fine as long as it
+  runs the API as `local`, `ci` or `e2e` (`lt dev up`, `lt dev test` and the starter's e2e scripts do). Against a
+  deployed stage, read the mail instead (Hub mailbox, Mailpit), which is what that stage should have been doing.
+
+The decision uses the new exported helper `isLocalEnv(env)`, which reads the existing `LOCALHOST_URL_ENVS`
+(`local`, `ci`, `e2e`). The SSRF guard's private-target allowance (`privateOutboundTargetsAllowed()`) now reads
+the same helper; its behaviour is unchanged.
+
+## 2. Auth cookies carry `Secure` on every https deployment
+
+The session cookie is written by two paths: Better-Auth's own handlers (2FA, social callback, passkey) and the
+framework's cookie helper (sign-in and sign-up through `CoreBetterAuthController`, the API middleware, and the
+legacy `token` / `refreshToken` cookies). Better-Auth sets `Secure` from an `https://` base URL. The framework
+helper set it only for `production` / `staging` — so on an https `develop` or `test` stage the cookie that
+establishes the session went out without `Secure`, while Better-Auth's handlers set it on the same deployment.
+
+Now:
+
+| Cookie | `Secure` when |
+| ------ | ------------- |
+| Better-Auth session cookie written by the framework | Better-Auth's own cookies are secure (read off the instance: `CoreBetterAuthService.usesSecureCookies()`), or the environment is production-like |
+| Legacy `token` / `refreshToken` | `baseUrl` starts with `https://`, or the environment is production-like |
+
+`Secure` is only ever added, never removed. A project that switched it off on purpose
+(`betterAuth.options.advanced.defaultCookieAttributes.secure: false`) keeps that outside production and staging.
+
+**What to check:**
+
+- **A deployment whose `baseUrl` says `https://` but whose browsers reach the API over plain http** now loses the
+  framework-written session cookie too — browsers drop a `Secure` cookie received over http. Better-Auth's own
+  handlers already behaved this way, so such a deployment had broken 2FA and social sign-in before. Fix the
+  `baseUrl` or serve https.
+- **You override a cookie-writing method.** The new inputs reach the helpers only if the caller passes them:
+
+  ```typescript
+  // A CoreAuthController / CoreAuthResolver subclass that overrides processCookies()
+  const baseUrl = this.configService.getFastButReadOnly<string>('baseUrl');
+  return setLegacyAuthCookies(res, result, cookiesConfig, env, baseUrl);
+
+  // Code that builds its own Better-Auth cookie helper
+  createCookieHelper(basePath, { ...options, secureTransport: this.betterAuthService.usesSecureCookies() });
+  ```
+
+  Without the argument the helper keeps the previous, environment-only rule — nothing breaks, the fix just does
+  not reach that path.
+- **Your tests stub `CoreBetterAuthService`**: no change needed. The controller calls `usesSecureCookies()`
+  optionally, so a stub without it keeps the previous behaviour.
+
+## 3. Audit suppression GHSA-ch52-4w7c-c8xp removed (repository only)
+
+This repository no longer lists GHSA-ch52-4w7c-c8xp (`http-cache-semantics <= 4.2.0`, dev tooling only:
+`@swc/cli` > … > `cacheable-request`) in `auditConfig.ignoreGhsas`. Its lockfile now resolves 4.3.0, which
+`cacheable-request`'s `^4.2.0` takes on any fresh resolve. Nothing here reaches the published package.
+
+4.3.0 is **not a fix**: its max-stale code is identical to 4.2.0's. It only lies outside the advisory's declared
+range, because the advisory was written as "up to the newest release" and never followed. The maintainer disputes
+the report (kornelski/http-cache-semantics#56); a withdrawal request is open (github/advisory-database#10139),
+and an independent re-test there reproduces the behaviour through 4.3.0, so a range extension is possible.
+
+**For starter-derived projects** that carry the same entry (nest-server-starter 11.41.7 – 11.42.11):
+
+- Lockfile on 4.3.0 (`pnpm why http-cache-semantics`): remove the entry from `ignoreGhsas` together with its row in
+  `tests/unit/audit-suppression-scope.spec.ts`. On 4.3.0 the entry hides nothing and would swallow the advisory
+  unseen the day its range is extended; without it, that day turns `pnpm audit` red, which is the moment to
+  re-argue the dev-only case.
+- Lockfile still on 4.2.0: `pnpm update http-cache-semantics` first, then as above. Keep the entry instead if
+  your resolve cannot move.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| npm-mode and vendor-mode projects without cookie-related overrides | Nothing to do |
+| `lt dev up` / `lt dev test` / starter e2e scripts reading auth links from the log | Unchanged — they run as `local` / `e2e` |
+| Subclass overriding `processCookies()` (legacy) | Pass `baseUrl` (§2), otherwise unchanged behaviour |
+| Custom `createCookieHelper()` call | Pass `secureTransport` (§2), otherwise unchanged behaviour |
+| Test stubs of `CoreBetterAuthService` | Compatible |
+
+## Troubleshooting
+
+**The `[PASSWORD RESET]` / `[EMAIL VERIFICATION]` line disappeared from your local log**
+Your environment is not named `local`, `ci` or `e2e`. Set `LT_LOG_AUTH_URLS=1` locally (§1).
+
+**After the update, sign-in succeeds but the next request is anonymous on a non-production stage**
+The browser dropped the now-`Secure` session cookie because the page or API is served over http while `baseUrl`
+says https. Serve https or correct `baseUrl` (§2).
+
+## Module Documentation
+
+- [Better-Auth module README](../src/core/modules/better-auth/README.md) — `usesSecureCookies()`
+- [Configurable features](../.claude/rules/configurable-features.md) — Cookies row, Outbound URL Guard row

package/migration-guides/11.42.12-to-11.42.13.md

@@ -0,0 +1,154 @@
+# Migration Guide: 11.42.12 → 11.42.13
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | `CoreTenantGuard` refusals carry translatable error codes (§1); `GET /files/id/:id` answers 404 instead of 500 for an id that is not an ObjectId (§3) |
+| **New Features**     | A finished TUS upload names the stored file in the `X-File-Id` response header (§2)                      |
+| **Framework API**    | Additive only: `ErrorCode.NOT_TENANT_MEMBER` … `VERIFICATION_REQUIRED` (`LTNS_0103`–`LTNS_0107`), `TUS_FILE_ID_HEADER`, `CoreFileService.isMalformedFileId()` (protected) |
+| **Dependencies**     | None for the package                                                                                     |
+| **Breaking Changes** | None. Status codes and access decisions are unchanged; only the message text of five tenant refusals gains a prefix (§1) |
+| **Migration Effort** | None for most projects. Check §1 if you compare a tenant refusal message for exact equality, and §2 if your frontend derives a file id from the TUS URL |
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server
+```
+
+Vendor-mode projects pick it up with the core update. No code or configuration change is required unless one of
+the checks below applies to you.
+
+## 1. Tenant guard refusals are translatable
+
+Five of the guard's 403 refusals were thrown as plain English strings. Without the `#LTNS_XXXX:` prefix the
+frontend error translation could not map them, so users saw the raw English text in a toast.
+
+| Code        | Message (unchanged wording)   | Refused because                                                                          |
+| ----------- | ----------------------------- | ---------------------------------------------------------------------------------------- |
+| `LTNS_0103` | `Not a member of this tenant` | the tenant header names a tenant the user has no active membership in                     |
+| `LTNS_0104` | `Insufficient tenant role`    | the membership role does not satisfy the required tenant role                             |
+| `LTNS_0105` | `Insufficient role`           | `user.roles` does not meet the required role (no header, or a `@SkipTenantCheck` route)   |
+| `LTNS_0106` | `Tenant is inactive`          | `multiTenancy.isTenantActive` reports the header's tenant as switched off                 |
+| `LTNS_0107` | `Verification required`       | an `S_VERIFIED` endpoint, and the user is not verified                                    |
+
+The response `message` is now e.g. `#LTNS_0103: Not a member of this tenant`. Status code (403), exception class
+and the decision itself are unchanged. German and English translations ship in the error catalog
+(`GET /i18n/errors/:locale`), so `nuxt-extensions` translates them without any change.
+
+**What to check:**
+
+- **You compare the message for exact equality** (`toBe('Insufficient role')`, `message === '…'`): switch to a
+  substring match or, better, to the code:
+
+  ```typescript
+  // Before
+  expect(res.body.message).toBe('Not a member of this tenant');
+
+  // After
+  expect(res.body.message).toBe(ErrorCode.NOT_TENANT_MEMBER);
+  // or, tolerant of both versions
+  expect(res.body.message).toContain('Not a member of this tenant');
+  ```
+
+  Substring matches (`toContain`, log filters) keep working unchanged — the original wording stays behind the
+  code.
+- **Your product does not call them tenants:** override the translations in your own error registry
+  (`errorCode.additionalErrorRegistry`). It is registered after the core, and translations are merged per code,
+  so your entry for `LTNS_0103` wins.
+
+## 2. A finished TUS upload names the stored file (`X-File-Id`)
+
+Until now a client knew only the TUS URL after an upload. Its last segment is the TUS **upload** id — a key of the
+staging store, not of the file store — and `/files/id/<upload-id>` cannot answer with the file. The response that
+completes an upload now carries the ID of the stored file:
+
+```
+HTTP/1.1 204 No Content
+Upload-Offset: 52428800
+X-File-Id: 6720c1f0a2b4c8e9d0f1a2b3
+Access-Control-Expose-Headers: …, X-File-Id
+```
+
+- Sent on the completing request only: the last `PATCH`, or the `POST` of a creation-with-upload. Creation and
+  partial `PATCH`es store nothing yet and carry no header.
+- Listed in `Access-Control-Expose-Headers`, so a browser on a separate app origin can read it.
+- The name is exported as `TUS_FILE_ID_HEADER`.
+
+With `tus-js-client`:
+
+```typescript
+let fileId: string | undefined;
+const upload = new Upload(file, {
+  endpoint: '/tus',
+  onAfterResponse: (_req, res) => {
+    const id = res.getHeader('X-File-Id');
+    if (id) {
+      fileId = id;
+    }
+  },
+  onSuccess: () => {
+    // use `/files/id/${fileId}` — NOT the last segment of `upload.url`
+  },
+});
+```
+
+**What to check:**
+
+- **Your frontend takes the last segment of the TUS URL as the file id:** read `X-File-Id` instead. Treat a
+  missing header (an older server, see the next point) as "no file id known" — never fall back to the URL.
+- **You override `onUploadComplete()`:** nothing to change as long as the override calls
+  `super.onUploadComplete(upload)` with the `upload` it received — both `await super…` and `return super…` keep
+  compiling and keep the header. An override that never calls `super` (it stores the file itself) completes the
+  upload without `X-File-Id`. The method's signature did not change.
+
+## 3. `GET /files/id/:id` answers 404 for an id that is not an ObjectId
+
+An id that is not a 24-character hex string — typically a TUS upload id (32 hex characters) taken for the file id,
+see §2 — reached `new ObjectId()` and threw a `BSONError`, so the route answered **500**. It now answers exactly
+like an unknown id: `404` with `ErrorCode.FILE_NOT_FOUND`.
+
+The guard sits in `CoreFileService` (`getFileInfo`, `resolveFile`, `getFileStream`, `getBuffer`,
+`getDownloadUrl`, `getRawFileInfo`, `deleteFile`, `duplicateById`), so every route built on those methods
+benefits — including a project's own `GET /files/info/:id` / `DELETE /files/:id`. Only strings are judged; an
+`ObjectId` instance keeps its previous path.
+
+**What to check:**
+
+- **Your files use ids that are not ObjectIds** (unusual — every core store keys by ObjectId): override the new
+  protected `isMalformedFileId(id)` in your `FileService` to accept them.
+- **A monitor or test expected the 500:** it now gets 404.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| npm-mode and vendor-mode projects without tenant-message comparisons or TUS overrides | Nothing to do |
+| Tests or frontends matching tenant refusals with `toContain` / a substring | Compatible |
+| Tests comparing a tenant refusal message with `toBe` / `===` | Compare against `ErrorCode.*` (§1) |
+| `TusService extends CoreTusService` overriding `onUploadComplete()` and calling `super` | Compatible, header included |
+| `onUploadComplete()` override that does not call `super` | Compatible, no `X-File-Id` (§2) |
+| `FileService extends CoreFileService` with a `checkRights()` that reads `getRawFileInfo()` | Compatible; a malformed id now reaches it as `null` |
+
+## Troubleshooting
+
+**The browser never sees `X-File-Id` although the server sends it**
+The header is exposed by the tus server itself. If a proxy rewrites `Access-Control-Expose-Headers`, add
+`X-File-Id` there as well.
+
+**`X-File-Id` is missing on the completing response**
+Check for an `onUploadComplete()` override that does not call `super.onUploadComplete(upload)`, or that passes it a
+copy of `upload` (§2).
+
+**A tenant refusal shows in English although the frontend translates errors**
+The frontend translation loads the catalog from `GET /i18n/errors/:locale`. Make sure the error-code module is
+registered (it is by default) and the catalog contains `LTNS_0103`–`LTNS_0107`.
+
+## Module Documentation
+
+- [Tenant module README](../src/core/modules/tenant/README.md) — "Refusal Codes"
+- [Error codes](../docs/error-codes.md) — `LTNS_0103`–`LTNS_0107`
+- [TUS module README](../src/core/modules/tus/README.md) — "The ID of the Stored File", "Custom Upload Handler"
+- [TUS integration checklist](../src/core/modules/tus/INTEGRATION-CHECKLIST.md)
+- [File module README](../src/core/modules/file/README.md) — "Error responses"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.42.11",
+  "version": "11.42.13",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -213,7 +213,7 @@
     "oxfmt": "0.71.0",
     "oxlint": "1.87.0",
     "rimraf": "6.1.3",
-    "smtp-server": "3.19.19",
+    "smtp-server": "3.19.21",
     "ts-node": "10.9.2",
     "tsconfig-paths": "4.2.0",
     "tsx": "4.23.15",

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

@@ -51,23 +51,37 @@ export interface AuthCookieDefaultOptions {
  *
  * - `httpOnly: true` — prevents JavaScript access (XSS mitigation)
  * - `sameSite: 'lax'` — CSRF mitigation
- * - `secure: isProductionLikeEnv(env)` — HTTPS-only in production/staging
+ * - `secure` — HTTPS-only on an `https://` `baseUrl`, and always in production/staging
  *
- * Used by both Legacy Auth and BetterAuth cookie helpers for consistent security.
+ * Used by the Legacy Auth cookie helper. (The BetterAuth helper decides `secure` the same way, but
+ * reads the https half off the Better-Auth instance.)
  *
  * @param env - App-level environment from `IServerOptions.env` (e.g. `'production'`, `'staging'`, `'ci'`).
  *              Falls back to `process.env.NODE_ENV === 'production'` if absent.
+ * @param baseUrl - The server's `IServerOptions.baseUrl`. An `https://` value sets `secure` whatever
+ *              the environment is called — since 11.42.12, because the deployed `develop` / `test`
+ *              stages of a starter-based project are not production-like and got cookies without it.
  *
  * @since 11.25.0
  */
-export function getDefaultAuthCookieOptions(env?: string): AuthCookieDefaultOptions {
+export function getDefaultAuthCookieOptions(env?: string, baseUrl?: string): AuthCookieDefaultOptions {
   return {
     httpOnly: true,
     sameSite: 'lax',
-    secure: isProductionLikeEnv(env),
+    secure: isProductionLikeEnv(env) || isHttpsUrl(baseUrl),
   };
 }
 
+/**
+ * Whether a URL uses https, the transport signal for the `Secure` cookie attribute (Better-Auth
+ * derives its own the same way). Trimmed and case-insensitive; anything that is not a string is not.
+ *
+ * @since 11.42.12
+ */
+function isHttpsUrl(url: unknown): boolean {
+  return typeof url === 'string' && url.trim().toLowerCase().startsWith('https://');
+}
+
 /**
  * Asserts that the cookies configuration is safe for production/staging environments.
  *
@@ -114,6 +128,7 @@ export function assertCookiesProductionSafe(
  * @param result - Auth result containing `token` and `refreshToken` (modified in place)
  * @param cookies - The `cookies` config value from IServerOptions
  * @param env - App-level env from `IServerOptions.env` (used for `secure` flag derivation)
+ * @param baseUrl - `IServerOptions.baseUrl`; an `https://` value sets `secure` too (since 11.42.12)
  * @returns The (possibly modified) result object
  *
  * @since 11.25.0
@@ -123,12 +138,13 @@ export function setLegacyAuthCookies<T extends { refreshToken?: string; token?:
   result: T,
   cookies: boolean | ICookiesConfig | undefined,
   env?: string,
+  baseUrl?: string,
 ): T {
   if (!isCookiesEnabled(cookies)) {
     return result;
   }
 
-  const cookieOptions = getDefaultAuthCookieOptions(env);
+  const cookieOptions = getDefaultAuthCookieOptions(env, baseUrl);
 
   // If result is absent or not an object, clear any existing cookies (logout path)
   if (!result || typeof result !== 'object') {
@@ -261,12 +277,40 @@ export const LOCALHOST_URL_DEFAULTS = {
 } as const;
 
 /**
- * Environments that fall back to {@link LOCALHOST_URL_DEFAULTS} when no URLs are configured.
+ * The LOCAL environments: they run on a developer machine or in a test job, never as a deployment.
+ *
+ * They fall back to {@link LOCALHOST_URL_DEFAULTS} when no URLs are configured, and
+ * {@link isLocalEnv} reads this list for every other "local only" decision (the SSRF guard's
+ * private targets, the auth-link log). One list, so the decisions cannot drift apart.
+ *
+ * Deliberately NOT `development` or `test`: in projects built from nest-server-starter `test` is a
+ * DEPLOYED stage (often the customer's QA stage), and `develop`/`development` name a deployed dev
+ * stage as often as a laptop.
  *
  * @since 11.27.5
  */
 export const LOCALHOST_URL_ENVS: readonly string[] = ['ci', 'e2e', 'local'];
 
+/**
+ * Checks whether the given environment is local ({@link LOCALHOST_URL_ENVS}: `local`, `ci`, `e2e`),
+ * matched trimmed and case-insensitively.
+ *
+ * Not the complement of {@link isProductionLikeEnv}. That one answers "must this be hardened?" and
+ * names only the environments that obviously hold real users; everything it does not name counts
+ * as non-production, including the deployed `develop` and `test` stages of a starter-based project.
+ * Use this one when the question is the opposite — "may this run without protection?" — so that an
+ * environment nobody listed stays protected. An unknown or missing name answers `false`.
+ *
+ * @since 11.42.12
+ */
+export function isLocalEnv(env?: string): boolean {
+  return LOCALHOST_URL_ENVS.includes(
+    String(env ?? '')
+      .trim()
+      .toLowerCase(),
+  );
+}
+
 /**
  * The hostname label stripped from `baseUrl` to derive `appUrl`.
  */

package/src/core/common/helpers/outbound-url.helper.ts

@@ -3,6 +3,7 @@ import { BlockList, isIP } from 'node:net';
 import { Agent, buildConnector, fetch as undiciFetch } from 'undici';
 
 import { ConfigService } from '../services/config.service';
+import { isLocalEnv } from './cookies.helper';
 
 /**
  * Requests to a URL a USER entered — a webhook, an export target, an ERP address.
@@ -53,12 +54,6 @@ for (const [network, prefix] of [
   blocked.addSubnet(network, prefix, 'ipv6');
 }
 
-/**
- * Environments in which internal targets are allowed unless configured otherwise. Deliberately NOT
- * `test`: in projects built from nest-server-starter that is a DEPLOYED stage.
- */
-const LOCAL_ENVIRONMENTS = new Set(['ci', 'e2e', 'local']);
-
 /** Thrown for a target that is, or resolves to, an internal address. */
 export class OutboundUrlBlockedError extends Error {
   constructor(
@@ -93,10 +88,9 @@ export function privateOutboundTargetsAllowed(): boolean {
   if (flag === false || flag === 'false') {
     return false;
   }
-  const env = String(config?.env ?? process.env.NODE_ENV ?? '')
-    .trim()
-    .toLowerCase();
-  return LOCAL_ENVIRONMENTS.has(env);
+  // Internal targets are allowed only in the local environments (`isLocalEnv`), deliberately not
+  // in `test`: in projects built from nest-server-starter that is a DEPLOYED stage.
+  return isLocalEnv(config?.env ?? process.env.NODE_ENV);
 }
 
 /** Whether an IP address is internal. A hostname (not an IP) answers false — resolve it first. */

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

@@ -192,6 +192,7 @@ export class CoreAuthController {
   protected processCookies(res: ResponseType, result: any) {
     const cookiesConfig = this.configService.getFastButReadOnly<boolean | ICookiesConfig>('cookies');
     const env = this.configService.getFastButReadOnly<string>('env');
-    return setLegacyAuthCookies(res, result, cookiesConfig, env);
+    const baseUrl = this.configService.getFastButReadOnly<string>('baseUrl');
+    return setLegacyAuthCookies(res, result, cookiesConfig, env, baseUrl);
   }
 }

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

@@ -174,6 +174,7 @@ export class CoreAuthResolver {
   protected processCookies(ctx: { res: ResponseType }, result: any) {
     const cookiesConfig = this.configService.getFastButReadOnly<boolean | ICookiesConfig>('cookies');
     const env = this.configService.getFastButReadOnly<string>('env');
-    return setLegacyAuthCookies(ctx.res, result, cookiesConfig, env);
+    const baseUrl = this.configService.getFastButReadOnly<string>('baseUrl');
+    return setLegacyAuthCookies(ctx.res, result, cookiesConfig, env, baseUrl);
   }
 }

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

@@ -1505,6 +1505,7 @@ export class MyService {
 | `getBasePath()`                      | Get the base path for endpoints            |
 | `getBaseUrl()`                       | Get the base URL                           |
 | `getCookieDomain()`                  | Get resolved cross-subdomain cookie domain |
+| `usesSecureCookies()`                | Whether Better-Auth's cookies carry Secure |
 | `getSession(req)`                    | Get current session from request           |
 | `revokeSession(token)`               | Revoke a session (logout)                  |
 | `isSessionExpiringSoon(session, t?)` | Check if session is expiring soon          |

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

@@ -172,6 +172,7 @@ export class CoreBetterAuthApiMiddleware implements NestMiddleware {
           env,
           legacyCookieEnabled: false, // Middleware doesn't need legacy cookie
           secret: config?.secret, // Required for cookie signing
+          secureTransport: this.betterAuthService.usesSecureCookies?.() === true, // Same `Secure` rule as Better-Auth
         },
         this.logger,
       );