@lenne.tech/nest-server 11.21.3 → 11.22.1

package/.claude/rules/module-inheritance.md

@@ -0,0 +1,97 @@
+# Module Inheritance Pattern
+
+**This is a fundamental architectural pattern that MUST be followed for all new modules in `src/core/modules/`.**
+
+## Why Inheritance Over Hooks/Events
+
+Core modules (like `AuthModule`, `BetterAuthModule`, `FileModule`) are designed to be **extended through inheritance** in consuming projects, not manipulated through hooks, events, or other workarounds. This provides:
+
+1. **Full Control**: Projects can override methods and precisely define what happens before/after `super()` calls
+2. **Flexibility**: Parts of the parent implementation can be skipped entirely for custom logic
+3. **Type Safety**: TypeScript inheritance ensures proper typing and IDE support
+4. **Robustness**: No runtime event systems or hooks that can fail silently
+
+## Pattern Structure
+
+```typescript
+// src/core/modules/example/core-example.resolver.ts (in nest-server)
+@Resolver()
+export class CoreExampleResolver {
+  async someMethod() { /* base implementation */ }
+}
+
+// src/server/modules/example/example.resolver.ts (in consuming project)
+@Resolver()
+export class ExampleResolver extends CoreExampleResolver {
+  override async someMethod() {
+    // Custom pre-processing
+    const result = await super.someMethod();  // Or skip for full override
+    // Custom post-processing
+    return result;
+  }
+}
+```
+
+## Module Registration Options
+
+Core modules should support both:
+
+1. **Auto-registration** (`autoRegister: true`) - For simple projects without customization
+2. **Manual registration** (`autoRegister: false`, default) - Projects integrate via extended module
+
+```typescript
+// config.env.ts - auto-registration for simple projects
+betterAuth: { autoRegister: true }
+
+// server.module.ts - manual registration with custom resolver (recommended)
+BetterAuthModule.forRoot({ config, resolver: CustomResolver })
+```
+
+## Examples in Codebase
+
+- `CoreAuthService` → extended by project's `AuthService`
+- `CoreBetterAuthResolver` → extended by project's `BetterAuthResolver`
+- `CoreUserService` → extended by project's `UserService`
+
+## Critical: Call Protected Helper Methods When Overriding
+
+When overriding methods that have **protected helper methods** in the parent class, you MUST call these helpers in your override. Otherwise, important functionality (guards, checks, validation) will be bypassed.
+
+### Example: AuthResolver Override Pattern
+
+```typescript
+// WRONG: Missing checkLegacyGraphQLEnabled call
+@Mutation(() => Auth)
+override async signIn(...): Promise<Auth> {
+  // Bug: Legacy endpoint check is bypassed!
+  const result = await this.authService.signIn(input, serviceOptions);
+  return this.processCookies(ctx, result);
+}
+
+// CORRECT: Call the protected check method
+@Mutation(() => Auth)
+override async signIn(...): Promise<Auth> {
+  this.checkLegacyGraphQLEnabled('signIn');  // Required!
+  const result = await this.authService.signIn(input, serviceOptions);
+  return this.processCookies(ctx, result);
+}
+```
+
+### Protected Helper Methods to Call
+
+| Core Class | Method | Purpose |
+|------------|--------|---------|
+| `CoreAuthResolver` | `checkLegacyGraphQLEnabled(name)` | Throws HTTP 410 if legacy endpoints disabled |
+| `CoreAuthController` | `checkLegacyRESTEnabled(name)` | Throws HTTP 410 if legacy endpoints disabled |
+
+**Rule**: When you override a method, check if the parent calls any `protected` helper methods. If so, call them in your override too.
+
+## Checklist for New Core Modules
+
+When adding new core modules, ensure:
+
+- [ ] Base classes in `src/core/modules/` with `Core` prefix
+- [ ] Methods are `protected` or `public` (not `private`) to allow override
+- [ ] `autoRegister` option defaults to `false`
+- [ ] Clear documentation for extension points
+- [ ] Export base classes via `src/index.ts`

package/.claude/rules/package-management.md

@@ -0,0 +1,112 @@
+# Package Management Rules
+
+This document defines the rules for managing dependencies in package.json.
+
+## Package Manager: pnpm
+
+This project uses **pnpm** for development. The `packageManager` field in `package.json` ensures the correct version is used (via Corepack).
+
+```bash
+# Install dependencies
+pnpm install
+
+# Add a new package (fixed version)
+pnpm add express@4.18.2
+
+# Add a dev dependency
+pnpm add -D typescript@5.3.3
+
+# Remove a package
+pnpm remove package-name
+```
+
+## Fixed Versions Only
+
+**All package versions in package.json MUST be exact (fixed) versions.**
+
+### Rules
+
+| Allowed | Not Allowed |
+|---------|-------------|
+| `"express": "4.18.2"` | `"express": "^4.18.2"` |
+| `"typescript": "5.3.3"` | `"typescript": "~5.3.3"` |
+| `"lodash": "4.17.21"` | `"lodash": ">=4.0.0"` |
+| | `"lodash": "4.x"` |
+| | `"lodash": "*"` |
+
+### Why Fixed Versions?
+
+1. **Reproducibility**: Every installation produces identical `node_modules`
+2. **Stability**: No surprise breaking changes from automatic minor/patch updates
+3. **Security Control**: Updates are intentional and reviewed, not automatic
+4. **Debugging**: Easier to identify which version introduced issues
+5. **Framework Responsibility**: As a framework, we must ensure consuming projects get predictable behavior
+
+### When Adding New Packages
+
+```bash
+# CORRECT: Install with exact version
+pnpm add express@4.18.2
+
+# Then verify package.json has exact version (no ^ or ~)
+```
+
+If pnpm adds `^` automatically, manually remove it from package.json.
+
+### When Updating Packages
+
+```bash
+# Use pnpm update or manually update
+pnpm update package-name
+
+# Or manually edit package.json with exact version
+```
+
+Always:
+1. Update to exact version
+2. Run `pnpm install`
+3. Run `pnpm test`
+4. Verify no regressions
+
+### Checking for Version Ranges
+
+To find packages with version ranges:
+
+```bash
+# Find all dependencies with ^ or ~
+grep -E '"\^|"~' package.json
+```
+
+### Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| pnpm adds `^` by default | Remove `^` after install |
+| Copying from other projects | Verify versions are fixed |
+| Using `pnpm add package` without version | Specify exact version: `pnpm add package@1.2.3` |
+
+## devDependencies
+
+The same rules apply to devDependencies. All versions must be fixed.
+
+## peerDependencies
+
+peerDependencies may use ranges when necessary for compatibility with consuming projects, but this should be minimized.
+
+## Lock File
+
+The `pnpm-lock.yaml` file must always be committed. It provides additional reproducibility even if someone accidentally introduces a version range.
+
+## Overrides
+
+Package overrides are configured in the `pnpm.overrides` section of `package.json`:
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "lodash": "4.17.23"
+    }
+  }
+}
+```

package/.claude/rules/role-system.md

@@ -0,0 +1,146 @@
+# Role System (RoleEnum)
+
+The role system distinguishes between **real roles** and **system roles**.
+
+## Real Roles
+
+Actual roles stored in `user.roles` array in the database:
+
+- `RoleEnum.ADMIN` - Administrator role
+
+## System Roles (S_ Prefix)
+
+System roles are used for **runtime checks only** and must **NEVER** be stored in `user.roles`:
+
+| Role | Purpose | Check Logic |
+|------|---------|-------------|
+| `S_USER` | User is logged in | `currentUser` exists |
+| `S_VERIFIED` | User is verified | `user.verified \|\| user.verifiedAt \|\| user.emailVerified` |
+| `S_CREATOR` | User created the object | `object.createdBy === user.id` |
+| `S_SELF` | User is accessing own data | `object.id === user.id` |
+| `S_EVERYONE` | Public access | Always true |
+| `S_NO_ONE` | Locked access | Always false |
+
+## Critical Rule
+
+```typescript
+// CORRECT: Using S_ roles in decorators (runtime checks)
+@Roles(RoleEnum.S_USER)
+@Restricted(RoleEnum.S_VERIFIED)
+
+// WRONG: Storing S_ roles in user.roles array
+roles: [RoleEnum.S_USER]  // NEVER do this!
+
+// CORRECT: Empty roles or real roles only
+roles: []                  // Empty array
+roles: [RoleEnum.ADMIN]    // Real role
+```
+
+The `S_` prefix indicates a **system check**, not an actual role. These are evaluated dynamically at runtime based on context (current user, request, object being accessed).
+
+## Role Decorators
+
+- `@Roles(RoleEnum.ADMIN)` - Method-level authorization
+- `@Restricted(RoleEnum.S_VERIFIED)` - Field-level access control
+
+## Hierarchy Roles (Multi-Tenancy)
+
+When `multiTenancy` is configured, hierarchy roles replace the old `S_TENANT_*` system roles:
+
+```typescript
+import { DefaultHR, createHierarchyRoles } from '@lenne.tech/nest-server';
+
+// Default hierarchy
+@Roles(DefaultHR.MEMBER)   // any active member (level >= 1)
+@Roles(DefaultHR.MANAGER)  // at least manager level (level >= 2)
+@Roles(DefaultHR.OWNER)    // highest level (level >= 3)
+
+// Custom hierarchy
+const HR = createHierarchyRoles({ viewer: 1, editor: 2, admin: 3, owner: 4 });
+@Roles(HR.EDITOR)           // requires level >= 2
+
+// Normal (non-hierarchy) roles
+@Roles('auditor')           // exact match only, no level compensation
+```
+
+**System role OR semantics in CoreTenantGuard:** System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives **before** real roles. Method-level system roles take precedence over class-level ones (e.g., class `S_EVERYONE` + method `S_USER` → `S_USER` applies). When a system role grants access and `X-Tenant-Id` header is present, membership is still validated to set tenant context — a non-member gets 403 with `S_USER`/`S_VERIFIED` (admin bypass applies).
+
+**Tenant context rule for real roles:** When `X-Tenant-Id` header is present, only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass). Without header, `user.roles` is checked.
+
+Hierarchy roles use **level comparison** (higher includes lower). Normal roles use **exact match**.
+
+Both work in `@Roles()` (method-level) and `@Restricted()` (field-level) via unified `checkRoleAccess()`.
+
+## Role Check Implementation
+
+The role system is evaluated in:
+- `RolesGuard` / `BetterAuthRolesGuard` - Checks method-level `@Roles()` decorators (passes through non-system roles to `CoreTenantGuard` when multiTenancy active)
+- `CoreTenantGuard` - Validates tenant membership and checks hierarchy/normal roles
+- `CheckResponseInterceptor` - Filters fields based on `@Restricted()` decorators
+- `CheckSecurityInterceptor` - Processes `securityCheck()` methods
+
+## @Roles vs @UseGuards
+
+**IMPORTANT: `@Roles()` already handles JWT authentication internally.**
+
+```typescript
+// CORRECT: @Roles alone is sufficient for authentication + authorization
+@Query(() => SomeModel)
+@Roles(RoleEnum.ADMIN)
+async someAdminQuery(): Promise<SomeModel> { }
+
+// WRONG: Don't add @UseGuards when @Roles is present
+@Query(() => SomeModel)
+@Roles(RoleEnum.ADMIN)
+@UseGuards(AuthGuard(AuthGuardStrategy.JWT))  // REDUNDANT - Roles already handles this
+async someAdminQuery(): Promise<SomeModel> { }
+```
+
+The `@Roles()` decorator combined with `RolesGuard` automatically:
+1. Validates the JWT token
+2. Extracts the user from the token
+3. Checks if the user has the required role
+
+### When @UseGuards IS Required
+
+`@UseGuards(AuthGuard(...))` is only needed in these specific cases:
+
+| Case | Example | Reason |
+|------|---------|--------|
+| **Refresh Token** | `@UseGuards(AuthGuard(AuthGuardStrategy.JWT_REFRESH))` | Different strategy than standard JWT |
+| **Custom Strategies** | `@UseGuards(AuthGuard(AuthGuardStrategy.CUSTOM))` | Non-standard authentication flow |
+
+```typescript
+// CORRECT: refreshToken needs JWT_REFRESH strategy (not standard JWT)
+@Mutation(() => CoreAuthModel)
+@Roles(RoleEnum.S_EVERYONE)
+@UseGuards(AuthGuard(AuthGuardStrategy.JWT_REFRESH))  // Required - different strategy!
+async refreshToken(...): Promise<CoreAuthModel> { }
+
+// CORRECT: Standard endpoints - @Roles is sufficient
+@Mutation(() => CoreAuthModel)
+@Roles(RoleEnum.S_USER)  // Handles JWT auth automatically
+async logout(...): Promise<boolean> { }
+
+@Query(() => User)
+@Roles(RoleEnum.ADMIN)  // Handles JWT auth automatically
+async getUser(...): Promise<User> { }
+```
+
+### Common Mistake: Redundant Guards
+
+When reviewing code, watch for this anti-pattern:
+
+```typescript
+// WRONG: Redundant - @Roles(S_USER) already validates JWT
+@Roles(RoleEnum.S_USER)
+@UseGuards(AuthGuard(AuthGuardStrategy.JWT))  // DELETE THIS
+async someMethod() { }
+
+// WRONG: Redundant - @Roles(ADMIN) already validates JWT
+@Roles(RoleEnum.ADMIN)
+@UseGuards(AuthGuard(AuthGuardStrategy.JWT))  // DELETE THIS
+async adminMethod() { }
+```
+
+**Rule of thumb:** If `@Roles()` uses any role OTHER than `S_EVERYONE`, you don't need `@UseGuards(AuthGuard(JWT))`.

package/.claude/rules/testing.md

@@ -0,0 +1,120 @@
+# Testing Configuration
+
+## Test Framework
+
+- **Vitest** - Primary test framework (migrated from Jest)
+- Configuration: `vitest.config.ts`
+- Test files: `tests/` directory with `.e2e-spec.ts` suffix
+
+## Running Tests
+
+```bash
+# Run all E2E tests (default)
+pnpm test
+
+# Run with coverage
+pnpm run test:cov
+
+# Run in CI mode
+pnpm run test:ci
+
+# Debug open handles
+pnpm run test:e2e-doh
+
+# Clean up leftover test artifacts (.txt, .bin files from failed file upload tests)
+pnpm run test:cleanup
+```
+
+## Test Environment
+
+- Environment: `NODE_ENV=local`
+- Database: Local MongoDB instance (`mongodb://127.0.0.1/nest-server-local`)
+- Test helper: `src/test/test.helper.ts`
+- Coverage: Collected from `src/**/*.{ts,js}`
+
+## Test Best Practices
+
+1. **Always run tests before completing changes**: `pnpm test`
+2. **Production-ready = all tests pass** without errors
+3. **Use TestHelper** for GraphQL and REST API testing
+4. **Clean up test data** in `afterAll` hooks
+5. **Unique test data** - Use timestamps/random strings to avoid conflicts
+
+## Test File Structure
+
+```typescript
+import { Test, TestingModule } from '@nestjs/testing';
+import { TestHelper } from '../../src';
+
+describe('Feature Name', () => {
+  let testHelper: TestHelper;
+
+  beforeAll(async () => {
+    const moduleFixture = await Test.createTestingModule({
+      imports: [ServerModule],
+    }).compile();
+
+    const app = moduleFixture.createNestApplication();
+    await app.init();
+    testHelper = new TestHelper(app);
+  });
+
+  afterAll(async () => {
+    // Cleanup test data
+    await app.close();
+  });
+
+  it('should do something', async () => {
+    const result = await testHelper.graphQl({
+      name: 'someQuery',
+      type: TestGraphQLType.QUERY,
+      fields: ['id', 'name'],
+    });
+    expect(result.data.someQuery).toBeDefined();
+  });
+});
+```
+
+## WebSocket/Subscription Tests
+
+When testing GraphQL subscriptions, use `httpServer.listen(0)` instead of `app.listen()`:
+
+```typescript
+// CORRECT: No startup log, dynamic port
+await app.init();
+const httpServer = app.getHttpServer();
+await new Promise<void>((resolve) => {
+  httpServer.listen(0, '127.0.0.1', () => resolve());
+});
+const port = httpServer.address().port;
+testHelper = new TestHelper(app, `ws://127.0.0.1:${port}/graphql`);
+
+// Cleanup in afterAll
+if (httpServer) {
+  await new Promise<void>((resolve) => httpServer.close(() => resolve()));
+}
+await app.close();
+```
+
+```typescript
+// WRONG: Produces "Nest application successfully started" log
+await app.init();
+await app.listen(3030);
+```
+
+**Why:**
+- `app.listen()` triggers NestJS startup log -> noisy test output
+- Dynamic port (`0`) avoids port conflicts between parallel tests
+- Explicit `httpServer.close()` prevents open handle warnings
+
+## TestHelper Reference
+
+Full documentation for TestHelper (REST, GraphQL, Cookie support):
+`src/test/README.md` (also available in `node_modules/@lenne.tech/nest-server/src/test/README.md`)
+
+## Common Test Issues
+
+- **Tests timeout**: Ensure MongoDB is running
+- **Open handles**: Use `pnpm run test:e2e-doh` to debug
+- **Data conflicts**: Use unique identifiers per test
+- **"NestApplication successfully started" log**: Use `httpServer.listen()` instead of `app.listen()`

package/.claude/rules/versioning.md

@@ -0,0 +1,53 @@
+# Versioning Strategy
+
+## Version Schema: `MAJOR.MINOR.PATCH`
+
+| Part    | Meaning                                                            |
+|---------|--------------------------------------------------------------------|
+| `MAJOR` | Mirrors the NestJS major version (e.g., `11.x.x` = NestJS 11)      |
+| `MINOR` | Breaking changes or significant restructuring                      |
+| `PATCH` | Improvements (bugfixes) or additions (new features) - non-breaking |
+
+## Examples
+
+- `11.0.0` -> Initial release for NestJS 11
+- `11.1.0` -> Breaking change or major restructuring within NestJS 11
+- `11.1.5` -> Bugfix or new feature (backward compatible)
+
+## Important Rules
+
+1. **Document breaking changes** clearly in commit messages when incrementing MINOR version
+2. **Update nest-server-starter** with migration instructions for breaking changes
+3. **Consider downstream impact** - this package is used by multiple projects
+
+## Release Process
+
+1. Make changes and ensure all tests pass (`pnpm test`)
+2. Update version in `package.json`
+3. Build the package (`pnpm run build`)
+4. Publish to npm
+5. Update and test in [nest-server-starter](https://github.com/lenneTech/nest-server-starter)
+6. Commit changes to starter with migration notes
+
+## Package Distribution
+
+- **NPM Package**: `@lenne.tech/nest-server`
+- **Main entry**: `dist/index.js`
+- **Types**: `dist/index.d.ts`
+- **Public APIs**: Exported from `src/index.ts`
+
+## Package Development Commands
+
+```bash
+# Build for local development (use with pnpm link)
+pnpm run build:dev
+
+# Create tarball for integration testing
+pnpm run build:pack
+
+# Clean reinstall with tests and build
+pnpm run reinit
+
+# Watch for changes
+pnpm run watch
+```