@lenne.tech/nest-server 11.43.0 → 11.43.1

package/migration-guides/11.43.0-to-11.43.1.md

@@ -0,0 +1,73 @@
+# Migration Guide: 11.43.0 → 11.43.1
+
+## Overview
+
+| Category             | Details                                                                                                  |
+| -------------------- | -------------------------------------------------------------------------------------------------------- |
+| **Bugfixes**         | Bearer JWTs issued by Better-Auth are accepted again when only the server's `baseUrl` is set (`NSC__BASE_URL`, every `lt dev up`) — they answered **401** on every request since 11.10.3 (§1) |
+| **New Features**     | None                                                                                                     |
+| **Framework API**    | `CoreBetterAuthService.getBaseUrl()` returns the ORIGIN of the base URL the Better-Auth instance runs on (§1). No changed signatures, no new exports |
+| **Dependencies**     | Unchanged                                                                                                |
+| **Breaking Changes** | None                                                                                                     |
+| **Migration Effort** | None. A workaround that set `betterAuth.baseUrl` next to `baseUrl` can be removed (§1)                   |
+
+## 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.
+
+## 1. Bearer JWTs answered 401 when only the server `baseUrl` was set
+
+Better-Auth signs every JWT with `iss` and `aud` set to the base URL it runs on. `createBetterAuthInstance()`
+resolves that base URL as `betterAuth.baseUrl` → the server's `baseUrl` → the localhost default, and Better-Auth
+stores the **origin** of the result. The framework verified Bearer JWTs against
+`CoreBetterAuthService.getBaseUrl()`, which read only `betterAuth.baseUrl` and otherwise answered
+`http://localhost:3000`.
+
+So as soon as a deployment set the server's `baseUrl` without also setting `betterAuth.baseUrl`, the two disagreed,
+and every Bearer JWT was refused with `401 #LTNS_0100` (`unexpected "iss" claim value` in the debug log). That is the
+configuration `nest-server-starter` ships (`baseUrl: process.env.BASE_URL`), every stage that sets `NSC__BASE_URL`,
+and every `lt dev up`. Cookie sessions were unaffected, so the defect surfaced only for clients in JWT mode — for
+example `@lenne.tech/nuxt-extensions` once it switches to JWT after the login, which then received 401 on every
+request.
+
+`getBaseUrl()` now reads the base URL off the live Better-Auth instance and returns its origin — exactly the value
+Better-Auth signs with. A trailing slash, a path or a default port in the configured value
+(`https://api.example.com/`, `https://example.com/api`, `https://api.example.com:443`) is not part of the claim and
+no longer causes a mismatch either.
+
+**What to check:**
+
+- **You set `betterAuth.baseUrl` (or `NSC__BETTER_AUTH__BASE_URL`) only to work around this:** it can go. It still
+  wins over the server's `baseUrl` when set, so leaving it in place changes nothing.
+- **Your own code calls `getBaseUrl()`:** it now returns the URL Better-Auth actually runs on, as an origin. Code
+  that joined an absolute path onto it (`new URL('/iam/sign-in/email', getBaseUrl())`) keeps working; code that
+  relied on a path being part of the returned value must append that path itself. With only the server's `baseUrl`
+  set, it now answers that URL instead of `http://localhost:3000`.
+- **A vendor-mode project patched `getBaseUrl()` locally** for the same reason: the patch becomes obsolete with this
+  core update and can be dropped.
+
+## Compatibility Notes
+
+| Pattern | Status |
+| ------- | ------ |
+| Only `baseUrl` / `NSC__BASE_URL` set (starter default, `lt dev up`) | Bearer JWTs accepted again |
+| `betterAuth.baseUrl` set explicitly | Unchanged |
+| Neither set (`local` / `ci` / `e2e` defaults) | Unchanged — both sides use `http://localhost:3000` |
+| Cookie-only clients | Unchanged |
+| A JWT naming another issuer | Still refused |
+
+## Troubleshooting
+
+**Bearer requests still answer 401 after the update**
+Decode the token (`iss` claim) and compare it with `getBaseUrl()`. They must be identical. If they differ, check
+whether `betterAuth.options.baseURL` overrides the base URL with something that is not an absolute URL — then the
+framework falls back to the configured value.
+
+## Module Documentation
+
+- [Better-Auth module](../src/core/modules/better-auth/README.md)
+- Implementation: `src/core/modules/better-auth/core-better-auth.service.ts` → `getBaseUrl()`, `verifyJwksToken()`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.43.0",
+  "version": "11.43.1",
   "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",

package/src/core/modules/better-auth/core-better-auth.service.ts

@@ -697,9 +697,27 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
   }
 
   /**
-   * Gets the base URL for better-auth
+   * Gets the base URL Better-Auth runs on: the ORIGIN of the `baseURL` the live instance was built with.
+   *
+   * Read off the instance rather than off `betterAuth.baseUrl`, because `createBetterAuthInstance()`
+   * resolves it as `betterAuth.baseUrl` → the server's `baseUrl` → localhost default. Better-Auth signs
+   * every JWT with the origin of that value as `iss` and `aud` (`createAuthContext()` stores
+   * `new URL(baseURL).origin`), so this answers the origin too — a trailing slash, a path or a default
+   * port in the configured string is not part of the claim. Until 11.43.1 this read only
+   * `betterAuth.baseUrl` and answered `http://localhost:3000` whenever just the server's `baseUrl` was
+   * set (`NSC__BASE_URL`, and every `lt dev up`), so the framework refused every Bearer JWT Better-Auth
+   * had issued. Without an instance (Better-Auth disabled) it falls back to the configured value.
    */
   getBaseUrl(): string {
+    const instanceBaseUrl = (this.getInstance() as unknown as { options?: { baseURL?: unknown } } | null)?.options
+      ?.baseURL;
+    if (typeof instanceBaseUrl === 'string' && instanceBaseUrl) {
+      try {
+        return new URL(instanceBaseUrl).origin;
+      } catch {
+        // Not an absolute URL: Better-Auth cannot derive an origin from it either, so use the configured value.
+      }
+    }
     return this.config.baseUrl || 'http://localhost:3000';
   }
 
@@ -710,8 +728,8 @@ export class CoreBetterAuthService implements OnApplicationBootstrap, OnModuleIn
    * `createBetterAuthInstance()` pins `useSecureCookies: false` (for the cookie NAME) and restores
    * the transport flag through `advanced.defaultCookieAttributes.secure` on an `https://` base URL;
    * a project may override either. Reading the instance rather than re-deriving from a URL gives
-   * exactly the answer Better-Auth applies — including the base URL it actually uses, which
-   * {@link getBaseUrl} does not know when only the server's `baseUrl` is set.
+   * exactly the answer Better-Auth applies — including the base URL it actually uses, the same source
+   * {@link getBaseUrl} reads since 11.43.1.
    *
    * The framework's own cookie helper mirrors this, so a session cookie carries `Secure` no matter
    * which path wrote it.