# Migration Guide: 11.15.0 → 11.15.3

## Overview

| Category | Details |
|----------|---------|
| **Breaking Changes** | None |
| **New Features** | Cross-subdomain cookie Boolean Shorthand, middleware domain fix |
| **Bugfixes** | Fixed middleware not setting cookie domain, fixed `auto-install-peers` in `.npmrc` |
| **Migration Effort** | None required — update package only. New feature is opt-in. |

---

## Quick Migration

```bash
# Update package
pnpm install @lenne.tech/nest-server@11.15.3

# Verify build
pnpm run build

# Run tests
pnpm test
```

No code changes required. All changes are backward compatible.

---

## What's New in 11.15.3

### 1. Cross-Subdomain Cookie Boolean Shorthand

When your API and other services run on different subdomains (e.g., `api.example.com` and `ws.example.com`), authentication cookies are not shared by default. This feature provides a simple Boolean Shorthand to enable cross-subdomain cookie sharing.

**New recommended configuration:**

```typescript
// config.env.ts
const config = {
  baseUrl: 'https://api.dev.example.com',
  appUrl: 'https://dev.example.com',
  betterAuth: {
    crossSubDomainCookies: true, // Domain auto-derived → 'dev.example.com'
  },
};
```

**Domain resolution order:** `appUrl` hostname → `baseUrl` hostname (with `api.` prefix stripped) → `baseUrl` hostname as-is.

**Replaces the verbose `options.advanced` passthrough:**

```typescript
// OLD (still works, but not recommended)
betterAuth: {
  options: {
    advanced: {
      crossSubDomainCookies: { domain: 'example.com' },
    },
  },
}

// NEW (recommended)
betterAuth: {
  crossSubDomainCookies: true, // or { domain: 'example.com' }
}
```

**Boolean Shorthand options:**

| Value | Behavior |
|-------|----------|
| `undefined` | Disabled (default, backward compatible) |
| `true` or `{}` | Enabled, domain auto-derived from `baseUrl` hostname |
| `{ domain: 'example.com' }` | Enabled with explicit domain |
| `false` or `{ enabled: false }` | Disabled |

**What this does:**
- Sets the `domain` attribute on all authentication cookies (`iam.session_token`, and `token` if Legacy Auth is active)
- Enables cookie sharing between subdomains (e.g., `api.example.com` ↔ `ws.example.com`)
- Configures both Better-Auth's native handler AND nest-server's own cookie helper (controller + middleware)
- Automatically disabled for localhost (not meaningful for cross-subdomain)

**Important:** `crossSubDomainCookies` handles only the **cookie domain** (browser sends cookies to subdomains). Better-Auth also validates request origins via `trustedOrigins` (server accepts requests from subdomains). Both are required. `trustedOrigins` is auto-derived from `baseUrl`/`appUrl`, but additional subdomains (e.g., `https://ws.example.com`) must be added explicitly via `trustedOrigins`.

**Documentation:** [Better-Auth README — Cross-Subdomain Cookies](../src/core/modules/better-auth/README.md#cross-subdomain-cookies-v11151)

### 2. Middleware Cookie Domain Fix

**Bug:** The API middleware (`CoreBetterAuthApiMiddleware`) did not read the cookie domain from the config, causing cookies set by the middleware (e.g., after Passkey authentication) to lack the `domain` attribute even when cross-subdomain cookies were configured.

**Fix:** The middleware now reads the domain via `CoreBetterAuthService.getCookieDomain()`, consistent with the controller.

### 3. Fixed `auto-install-peers` in `.npmrc`

Added `auto-install-peers=false` to `.npmrc` to prevent pnpm from automatically installing peer dependencies. This ensures consistent lockfile generation and aligns with the project's fixed-version package management strategy.

This fix is internal to the package development workflow and does not affect consuming projects.

---

## Compatibility Notes

- All existing configurations continue to work without changes
- The `options.advanced` passthrough still works as before — the new `crossSubDomainCookies` top-level property is an alternative, not a replacement
- When both `crossSubDomainCookies` (top-level) and `options.advanced.crossSubDomainCookies` are set, the top-level value is applied first, then `options.advanced` is deep-merged on top (so the passthrough wins)
- No changes to authentication behavior unless `crossSubDomainCookies` is explicitly configured

---

## Module Documentation

### Better-Auth Module

- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md)
- **Integration Checklist:** [src/core/modules/better-auth/INTEGRATION-CHECKLIST.md](../src/core/modules/better-auth/INTEGRATION-CHECKLIST.md)
- **Reference Implementation:** `src/server/modules/auth/`
