@lenne.tech/nest-server 11.21.2 → 11.22.0

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
+```

package/CLAUDE.md

@@ -0,0 +1,172 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Quick Reference
+
+- [Commands](#common-development-commands) | [Architecture](#code-architecture) | [Guidelines](#development-guidelines) | [Troubleshooting](#debugging--troubleshooting)
+- **Detailed Rules**: See `.claude/rules/` for in-depth documentation
+
+## Self-Improvement Instructions
+
+**Claude Code must actively maintain and improve this file and `.claude/rules/`.**
+
+After significant development sessions, update with new learnings (patterns, pitfalls, best practices). Keep this file concise (~150 lines) and move detailed topics to `.claude/rules/`.
+
+## Living Documentation
+
+The following documents must be kept up to date when making changes that affect them:
+
+| Document | Update when... |
+|----------|---------------|
+| `docs/REQUEST-LIFECYCLE.md` | Adding/changing decorators, interceptors, guards, pipes, middleware, plugins, services, modules, or the request/response flow |
+| `migration-guides/` | Releasing MINOR or MAJOR versions (see `.claude/rules/migration-guides.md`) |
+| `.claude/rules/configurable-features.md` | Adding new configurable features |
+
+**Rule:** When a code change adds, removes, or modifies a feature listed in `docs/REQUEST-LIFECYCLE.md` (Features Overview, diagrams, decorator reference, configuration, etc.), update the document in the same commit or PR.
+
+## Project Overview
+
+**@lenne.tech/nest-server** - An extension layer on top of NestJS for building server applications with GraphQL and MongoDB.
+
+- **NPM**: https://www.npmjs.com/package/@lenne.tech/nest-server
+- **GitHub**: https://github.com/lenneTech/nest-server
+- **Starter Project**: https://github.com/lenneTech/nest-server-starter (reference for migrations)
+- **CLI**: https://github.com/lenneTech/cli (`lt server module <Name>`)
+- **Package Manager**: pnpm (development only, published to npm registry)
+
+## Common Development Commands
+
+```bash
+# Building & Running
+pnpm run build          # Build (outputs to dist/)
+pnpm start              # Start in local mode
+pnpm run start:dev      # Development mode with watch
+
+# Testing (ALWAYS run before completing changes)
+pnpm test               # Run E2E tests (Vitest)
+pnpm run test:cov       # With coverage
+pnpm run test:e2e-doh   # Debug open handles
+pnpm run test:cleanup   # Remove leftover test artifacts (.txt, .bin)
+
+# Linting & Formatting
+pnpm run lint           # ESLint check
+pnpm run lint:fix       # Auto-fix
+pnpm run format         # Prettier format
+
+# Package Development
+pnpm run build:dev      # Build for local development (use with pnpm link)
+pnpm run reinit         # Clean reinstall + tests + build
+```
+
+## Code Architecture
+
+**Two-Layer Structure:**
+- `src/core/` - Reusable framework components (exported)
+- `src/server/` - Internal test implementation (not exported)
+- `src/index.ts` - Public API exports
+
+**Key Components:**
+- `CoreModule` - Dynamic module with GraphQL (optional, disable via `graphQl: false`), MongoDB, security
+- `src/core/common/` - Decorators, helpers, interceptors, services
+- `src/core/modules/` - Auth, BetterAuth, ErrorCode, File, HealthCheck, Migrate, SystemSetup, Tus, User
+
+See `.claude/rules/architecture.md` for detailed documentation.
+See [`docs/REQUEST-LIFECYCLE.md`](docs/REQUEST-LIFECYCLE.md) for the complete request lifecycle, security architecture, and interceptor/decorator reference.
+
+## Development Guidelines
+
+### Core Principles
+
+1. **Module Inheritance Pattern** - Extend through inheritance, not hooks/events
+   - See `.claude/rules/module-inheritance.md`
+
+2. **Dynamic Integration** - Components opt-in, configurable, no package modification required
+
+3. **Backward Compatibility** - Changes affect all consuming projects
+
+4. **Test Coverage** - All changes must pass `pnpm test`
+
+5. **Export Management** - New public components → `src/index.ts`
+
+### Role System (Critical)
+
+System roles (`S_` prefix) are runtime checks only - **NEVER store in user.roles**:
+
+```typescript
+@Roles(RoleEnum.S_USER)      // Correct: runtime check
+roles: [RoleEnum.S_USER]      // WRONG: never store S_ roles!
+roles: [RoleEnum.ADMIN]       // Correct: real role
+```
+
+See `.claude/rules/role-system.md` for complete documentation.
+
+### Versioning
+
+`MAJOR.MINOR.PATCH` where MAJOR = NestJS version, MINOR = breaking changes, PATCH = non-breaking.
+
+See `.claude/rules/versioning.md` for release process.
+
+## Environment Configuration
+
+```typescript
+// config.env.ts supports:
+- Direct environment variables
+- NEST_SERVER_CONFIG JSON variable
+- NSC__* prefixed variables
+```
+
+**Key areas:** JWT, MongoDB, GraphQL, email, security, betterAuth
+
+## Debugging & Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Tests timeout | Ensure MongoDB running on localhost:27017 |
+| GraphQL introspection fails | Check `config.env.ts` introspection setting |
+| Module not found after adding | Verify export in `src/index.ts`, run `pnpm run build` |
+| Open handles in tests | Run `pnpm run test:e2e-doh` |
+
+## Best Practices
+
+1. **All code, comments, documentation in English**
+2. **Run tests before completing changes** - `pnpm test`
+3. **Follow existing patterns** for consistency
+4. **Never store S_ roles** in user.roles array
+5. **Use Module Inheritance Pattern** for core modules
+6. **Document breaking changes** in commits
+7. **Integration Checklists for Core Modules** - Every core module requiring project integration needs `INTEGRATION-CHECKLIST.md` (see `.claude/rules/core-modules.md`)
+8. **Don't add redundant @UseGuards** - `@Roles()` already handles JWT auth (see `.claude/rules/role-system.md`)
+9. **Fixed package versions only** - Never use `^`, `~`, or ranges in package.json (see `.claude/rules/package-management.md`)
+
+## Migration Guides
+
+When releasing MINOR or MAJOR versions, create migration guides in `migration-guides/`:
+- Use `migration-guides/TEMPLATE.md` as starting point
+- Always analyze `src/server/` and [nest-server-starter](https://github.com/lenneTech/nest-server-starter)
+- Ask developer for additional projects to analyze
+- See `.claude/rules/migration-guides.md` for complete process
+
+## Modular Rules
+
+Detailed documentation in `.claude/rules/`:
+
+| File | Content |
+|------|---------|
+| `module-inheritance.md` | Core architectural pattern for extending modules |
+| `role-system.md` | Role system, S_ prefix rules, @Roles vs @UseGuards |
+| `architecture.md` | Detailed code architecture |
+| `testing.md` | Test configuration and best practices |
+| `versioning.md` | Version strategy and release process |
+| `core-modules.md` | Path-scoped rules for `src/core/modules/` incl. Integration Checklist requirements |
+| `better-auth.md` | **Security-critical**: Better-Auth module rules (standard compliance, security, testing) |
+| `module-deprecation.md` | Legacy Auth → BetterAuth migration roadmap |
+| `migration-guides.md` | Process for creating version migration guides |
+| `configurable-features.md` | Configuration patterns: "Presence implies enabled" and "Boolean shorthand" (`true` / `{}`) |
+| `package-management.md` | Fixed package versions only - no `^`, `~`, or ranges |
+
+## In-Depth Documentation
+
+| File | Content |
+|------|---------|
+| [`docs/REQUEST-LIFECYCLE.md`](docs/REQUEST-LIFECYCLE.md) | Complete request lifecycle, security architecture, interceptor chain, decorator reference, CrudService pipeline, Safety Net, diagrams |

package/dist/core/common/interfaces/server-options.interface.d.ts

@@ -317,4 +317,14 @@ interface IBetterAuthWithPasskey extends IBetterAuthBase {
     passkey: IBetterAuthPasskeyEnabled;
     trustedOrigins: string[];
 }
+export interface ICoreModuleOverrides {
+    betterAuth?: {
+        controller?: Type<any>;
+        resolver?: Type<any>;
+    };
+    errorCode?: {
+        controller?: Type<any>;
+        service?: Type<any>;
+    };
+}
 export {};

package/dist/core/modules/better-auth/core-better-auth-user.mapper.js

@@ -533,32 +533,32 @@ let CoreBetterAuthUserMapper = class CoreBetterAuthUserMapper {
             const fullyMigratedUsers = usersWithBoth[0]?.count || 0;
             const pendingMigrationUsers = totalUsers - fullyMigratedUsers;
             const migrationPercentage = totalUsers > 0 ? Math.round((fullyMigratedUsers / totalUsers) * 100 * 100) / 100 : 0;
-            const pendingUsers = await usersCollection
-                .aggregate([
-                {
-                    $lookup: {
-                        as: 'accounts',
-                        foreignField: 'userId',
-                        from: 'account',
-                        localField: '_id',
-                    },
-                },
-                {
-                    $match: {
-                        $or: [
-                            { iamId: { $exists: false } },
-                            { iamId: null },
-                            {
-                                $and: [{ iamId: { $exists: true, $ne: null } }, { 'accounts.providerId': { $ne: 'credential' } }],
-                            },
-                        ],
-                    },
-                },
-                { $limit: 100 },
-                { $project: { email: 1 } },
-            ])
+            const usersWithoutIamId = await usersCollection
+                .find({ $or: [{ iamId: { $exists: false } }, { iamId: null }] })
+                .limit(100)
+                .project({ email: 1 })
                 .toArray();
-            const pendingUserEmails = pendingUsers.map((u) => u.email).filter(Boolean);
+            const remaining = 100 - usersWithoutIamId.length;
+            let usersWithIamButNoAccount = [];
+            if (remaining > 0) {
+                usersWithIamButNoAccount = await usersCollection
+                    .aggregate([
+                    { $match: { iamId: { $exists: true, $ne: null } } },
+                    {
+                        $lookup: {
+                            as: 'accounts',
+                            foreignField: 'userId',
+                            from: 'account',
+                            localField: '_id',
+                        },
+                    },
+                    { $match: { 'accounts.providerId': { $ne: 'credential' } } },
+                    { $limit: remaining },
+                    { $project: { email: 1 } },
+                ])
+                    .toArray();
+            }
+            const pendingUserEmails = [...usersWithoutIamId, ...usersWithIamButNoAccount].map((u) => u.email).filter(Boolean);
             const canDisableLegacyAuth = totalUsers > 0 && fullyMigratedUsers === totalUsers;
             return {
                 canDisableLegacyAuth,