# 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)
