# Migration Guide: 11.21.1 → 11.21.2

## Overview

| Category | Details |
|----------|---------|
| **Breaking Changes** | None |
| **New Features** | BetterAuth auto-skip for tenant validation on IAM endpoints |
| **Bugfixes** | lodash security fix (CVE HIGH + MODERATE) |
| **Migration Effort** | < 5 minutes |

---

## Quick Migration

```bash
# Update package
pnpm add @lenne.tech/nest-server@11.21.2

# Verify build
pnpm run build

# Run tests
pnpm test
```

No code changes required. The new feature activates automatically with safe defaults.

---

## What's New in 11.21.2

### 1. BetterAuth Auto-Skip for Tenant Validation

**Affects:** Projects with both `multiTenancy` and `betterAuth` active.

When both features are enabled, IAM endpoints (sign-in, sign-up, sign-out, session, etc.)
now automatically skip `CoreTenantGuard` tenant validation when no `X-Tenant-Id` header is
present. This solves the chicken-and-egg problem where users couldn't authenticate because
they weren't yet a member of any tenant.

**Default behavior (`skipTenantCheck: true`):**

| Scenario | Behavior |
|----------|----------|
| No `X-Tenant-Id` header | Skip tenant validation (auth before tenant) |
| `X-Tenant-Id` header present | Validate normally (membership check + tenant context) |

The auto-skip applies to both REST controllers (`CoreBetterAuthController` subclasses)
and GraphQL resolvers (`CoreBetterAuthResolver` subclasses).

**If you previously used `@SkipTenantCheck()` on your IAM resolver/controller to work
around this issue, you can remove it** — the framework now handles this automatically.

### 2. Opt-Out for Tenant-Aware Authentication

If your project requires tenant context at login time (e.g., subdomain-based tenancy,
invite links with embedded tenant, SSO per tenant), disable the auto-skip:

```typescript
// config.env.ts
betterAuth: {
  skipTenantCheck: false, // IAM endpoints require valid X-Tenant-Id header
}
```

### 3. Security: lodash Update

`lodash` updated from 4.17.23 to 4.18.1, fixing:
- GHSA-r5fr-rjxr-66jc (HIGH — prototype pollution)
- GHSA-f23m-r3pf-42rh (MODERATE — prototype pollution)

A `pnpm.overrides` entry ensures all transitive dependencies also use the patched version.

### 4. Dependency Updates

| Package | From | To | Type |
|---------|------|----|------|
| `lodash` | 4.17.23 | 4.18.1 | Security fix |
| `dotenv` | 17.3.1 | 17.4.0 | Minor feature |
| `@swc/cli` | 0.8.0 | 0.8.1 | Patch |

Three unnecessary pnpm overrides were removed (`file-type`, `yauzl`, `flatted`).

---

## Compatibility Notes

- **Projects without `multiTenancy`:** Not affected. No behavior change.
- **Projects without `betterAuth`:** Not affected. No behavior change.
- **Projects with both features + default config:** IAM endpoints now work without `X-Tenant-Id` header. Previously, these would fail if the user wasn't a tenant member.
- **Projects with `@SkipTenantCheck()` on IAM endpoints:** The decorator continues to work but is no longer needed for this use case. Safe to remove.
- **Subdomain-based / invite-link tenancy:** Set `betterAuth.skipTenantCheck: false` to require tenant context on IAM endpoints.

---

## Module Documentation

### Tenant Module

- **README:** [src/core/modules/tenant/README.md](../src/core/modules/tenant/README.md) — See "BetterAuth (IAM) Integration" section
- **Integration Checklist:** [src/core/modules/tenant/INTEGRATION-CHECKLIST.md](../src/core/modules/tenant/INTEGRATION-CHECKLIST.md) — See § 9 "BetterAuth (IAM) Coexistence"

### BetterAuth Module

- **README:** [src/core/modules/better-auth/README.md](../src/core/modules/better-auth/README.md) — See "Multi-Tenancy Integration" section

---

## References

- [Configurable Features](../.claude/rules/configurable-features.md) — `betterAuth.skipTenantCheck` entry
- [Request Lifecycle](../docs/REQUEST-LIFECYCLE.md) — CoreTenantGuard flow with auto-skip
- [nest-server-starter](https://github.com/lenneTech/nest-server-starter) (reference implementation)
