@lenne.tech/nest-server 11.25.2 → 11.25.3

package/FRAMEWORK-API.md

@@ -1,6 +1,6 @@
 # @lenne.tech/nest-server — Framework API Reference
 
-> Auto-generated from source code on 2026-04-20 (v11.25.2)
+> Auto-generated from source code on 2026-04-23 (v11.25.3)
 > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
 
 ## CoreModule.forRoot()

package/migration-guides/11.25.0-to-11.25.3.md

@@ -0,0 +1,203 @@
+# Migration Guide: 11.25.0 → 11.25.3
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | `cookies` option on `TestHelper.graphQl()` for cookie-based auth in GraphQL tests (11.25.1) |
+| **Bugfixes** | Removed incorrect `@deprecated` tag from the 3-parameter `CoreModule.forRoot()` signature (11.25.2); hardened `scripts/check-server-start.sh` cleanup to avoid hanging CI runs (11.25.3) |
+| **Security** | Added `uuid@<14.0.0` override (GHSA-w5hq-g745-h8pq, transitive via `@compodoc/compodoc`) — framework-internal, no consumer action needed (11.25.3) |
+| **Migration Effort** | None required — update package only. New feature is opt-in. |
+
+---
+
+## Quick Migration
+
+```bash
+# Update package
+pnpm install @lenne.tech/nest-server@11.25.3
+
+# Verify build
+pnpm run build
+
+# Run tests
+pnpm test
+```
+
+No code changes required. All changes are backward compatible.
+
+---
+
+## What's New in 11.25.1
+
+### `cookies` Option on `TestHelper.graphQl()`
+
+Since v11.25.0 cookies are enabled by default. Before v11.25.1, `TestHelper.graphQl()` could only authenticate via JWT (`token` option) — mirroring production cookie flows in GraphQL tests required manual `Cookie` header construction. v11.25.1 adds a first-class `cookies` option to `TestGraphQLOptions`, identical in behavior to the existing `cookies` option on `TestRestOptions`.
+
+**Three usage modes:**
+
+```typescript
+// 1. Plain session token string (recommended)
+//    -> Auto-detected and converted via buildBetterAuthCookies() to all
+//    relevant cookie names (iam.session_token, token)
+await testHelper.graphQl({
+  name: 'me',
+  type: TestGraphQLType.QUERY,
+  fields: ['id', 'email'],
+  cookies: sessionToken, // e.g. raw token from DB `session` collection
+});
+
+// 2. Pre-formatted cookie string (contains = or ;)
+//    -> Used as-is as a Cookie header
+await testHelper.graphQl({
+  name: 'me',
+  type: TestGraphQLType.QUERY,
+  fields: ['id'],
+  cookies: 'iam.session_token=abc.signature; other=value',
+});
+
+// 3. Record<string, string>
+//    -> Joined into a Cookie header
+await testHelper.graphQl({
+  name: 'me',
+  type: TestGraphQLType.QUERY,
+  fields: ['id'],
+  cookies: { 'iam.session_token': 'abc.signature' },
+});
+```
+
+**Combined with `token`:**
+
+Both headers are sent. The server's middleware token priority remains: `Authorization: Bearer` header first, then JWT cookie, then session cookie.
+
+```typescript
+await testHelper.graphQl({
+  name: 'me',
+  type: TestGraphQLType.QUERY,
+  fields: ['id'],
+  token: jwtToken,         // -> Authorization header
+  cookies: sessionToken,   // -> Cookie header (ignored when JWT is valid)
+});
+```
+
+**Reference test:** [`tests/stories/graphql-cookie-auth.story.test.ts`](../tests/stories/graphql-cookie-auth.story.test.ts) covers all three modes plus combined JWT + cookie usage.
+
+### When to Use
+
+- **JWT-only tests:** Continue using `token` alone — no change needed.
+- **Cookie-based tests:** Use `cookies` with the plain session-token string (simplest form).
+- **Hybrid flows:** Pass both `token` and `cookies` to exercise fallback behavior.
+
+This matches the production default since v11.25.0 (cookies enabled by default, JWT via `Authorization: Bearer` works independently).
+
+---
+
+## What's Fixed in 11.25.2
+
+### `@deprecated` Tag Removed from 3-Parameter `CoreModule.forRoot()`
+
+The 3-parameter signature used by projects running Legacy Auth alongside BetterAuth was incorrectly marked `@deprecated` in `src/core.module.ts`, which caused IDE/TypeScript deprecation warnings for valid usage.
+
+```typescript
+// This is valid and supported — no longer emits a deprecation warning
+CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(envConfig.jwt), envConfig);
+```
+
+**No action needed.** If your editor was showing a strike-through on this call in 11.25.0 / 11.25.1, it will disappear after upgrading. The signature remains fully supported for projects migrating from Legacy Auth to BetterAuth. See [module-deprecation.md](../.claude/rules/module-deprecation.md) for the long-term roadmap.
+
+---
+
+## What's Fixed in 11.25.3
+
+### `scripts/check-server-start.sh` Cleanup Hardened
+
+The CI helper script `scripts/check-server-start.sh` (used by `pnpm run check`) previously streamed server logs via a background `tail -f` and `wait`ed on both PIDs on `EXIT`. On macOS/bash this pattern hung intermittently because `tail -f` does not always honor `SIGTERM` while blocked on the kqueue watch, leaving `pnpm run check` stuck.
+
+**Changes:**
+- `tail -f` removed; the relevant log excerpt is printed at the end instead.
+- Server process is killed with `SIGTERM` → ~2 s grace window → `SIGKILL` without `wait`ing on the child.
+- `disown` suppresses the `Terminated: 15` noise in bash job output.
+
+**No consumer impact.** The script is CI-only and not shipped to downstream projects. If your project has copied an older version of this script, you can optionally sync it — but nothing breaks if you leave it as-is.
+
+### `uuid@<14.0.0` Security Override (Framework-Internal)
+
+A new `pnpm.overrides` entry was added in this repo's `package.json` to patch a missing buffer bounds check in `uuid` v3/v5/v6 (GHSA-w5hq-g745-h8pq), pulled in transitively via `@compodoc/compodoc → @compodoc/live-server → http-auth`.
+
+**No consumer action needed.** The override lives in the framework's own `package.json`; it is not inherited by downstream projects through `@lenne.tech/nest-server`. If your own project depends on `@compodoc/compodoc` (or any other package that transitively pulls vulnerable `uuid` versions), follow the same pattern from [`.claude/rules/package-management.md`](../.claude/rules/package-management.md) in your own `pnpm.overrides`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "uuid@<14.0.0": "14.0.0"
+    }
+  }
+}
+```
+
+---
+
+## Compatibility Notes
+
+### TestHelper Cookies (REST + GraphQL symmetry)
+
+Before 11.25.1, only `testHelper.rest()` and `testHelper.download()`/`downloadBuffer()` supported `cookies`. From 11.25.1 on, `testHelper.graphQl()` exposes the same option with identical semantics, so test suites can switch an endpoint between REST and GraphQL without rewriting the auth setup.
+
+### No Changes to Production Runtime
+
+11.25.1–11.25.3 are strictly test-helper, documentation and CI improvements. No runtime behavior, security semantics, or configuration defaults change compared to v11.25.0.
+
+---
+
+## Troubleshooting
+
+### `testHelper.graphQl({ cookies: sessionToken })` returns 401
+
+**Cause:** The session token may be stale (parallel test run invalidated it) or not yet written to the DB.
+
+**Fix:** Re-fetch the session token before each GraphQL call (same pattern used for REST):
+
+```typescript
+const token = await getSessionTokenFromDb(user.email);
+await testHelper.graphQl({ ..., cookies: token });
+```
+
+See [`tests/stories/graphql-cookie-auth.story.test.ts`](../tests/stories/graphql-cookie-auth.story.test.ts) for the reference setup (Mongo client, fresh-token helper, parallel-safe email generator).
+
+### IDE still shows strike-through on `CoreModule.forRoot(CoreAuthService, AuthModule.forRoot(...), envConfig)`
+
+**Cause:** TypeScript declaration cache / stale `node_modules/@lenne.tech/nest-server/dist/core.module.d.ts`.
+
+**Fix:** Reinstall the package and restart the TS server:
+
+```bash
+pnpm install @lenne.tech/nest-server@11.25.3
+# VS Code: Command Palette → "TypeScript: Restart TS Server"
+```
+
+---
+
+## Module Documentation
+
+### Test Helper
+- **Interface:** [src/test/test.helper.ts](../src/test/test.helper.ts) — `TestGraphQLOptions.cookies`
+- **README:** [src/test/README.md](../src/test/README.md) — TestHelper usage (REST, GraphQL, cookies)
+- **Reference Story:** [tests/stories/graphql-cookie-auth.story.test.ts](../tests/stories/graphql-cookie-auth.story.test.ts)
+
+### Core Module
+- **Source:** [src/core.module.ts](../src/core.module.ts) — `CoreModule.forRoot()` overloads
+- **Deprecation Roadmap:** [.claude/rules/module-deprecation.md](../.claude/rules/module-deprecation.md)
+
+### Infrastructure
+- **Check Script:** [scripts/check-server-start.sh](../scripts/check-server-start.sh)
+- **Package Overrides:** [.claude/rules/package-management.md](../.claude/rules/package-management.md)
+
+---
+
+## References
+
+- [Migration Guide 11.24.x → 11.25.0](./11.24.x-to-11.25.0.md) (cookies default change, CORS unification)
+- [Configurable Features Pattern](../.claude/rules/configurable-features.md)
+- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.25.2",
+  "version": "11.25.3",
   "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",
@@ -199,7 +199,8 @@
       "kysely@>=0.26.0 <0.28.16": "Security: SQL injection - transitive via better-auth",
       "lodash@>=4.0.0 <4.18.0": "Security: CVE in lodash@4.17.x - transitive via @nestjs/graphql. 4.18.1 is the latest patched version",
       "defu@<=6.1.6": "Security: prototype pollution via __proto__ key - transitive via better-auth",
-      "follow-redirects@<=1.15.11": "Security: Custom Authentication Headers leak on cross-domain redirect (GHSA-r4q5-vmmm-2653) - transitive via axios>@getbrevo/brevo and axios>node-mailjet"
+      "follow-redirects@<=1.15.11": "Security: Custom Authentication Headers leak on cross-domain redirect (GHSA-r4q5-vmmm-2653) - transitive via axios>@getbrevo/brevo and axios>node-mailjet",
+      "uuid@<14.0.0": "Security: Missing buffer bounds check in v3/v5/v6 (GHSA-w5hq-g745-h8pq) - transitive via @compodoc/compodoc and @compodoc/compodoc>@compodoc/live-server>http-auth"
     },
     "overrides": {
       "axios@<1.15.0": "1.15.0",
@@ -219,7 +220,8 @@
       "kysely@>=0.26.0 <0.28.16": "0.28.16",
       "lodash@>=4.0.0 <4.18.0": "4.18.1",
       "defu@<=6.1.6": "6.1.7",
-      "follow-redirects@<=1.15.11": "1.16.0"
+      "follow-redirects@<=1.15.11": "1.16.0",
+      "uuid@<14.0.0": "14.0.0"
     },
     "onlyBuiltDependencies": [
       "bcrypt",