@lenne.tech/nest-server 11.20.1 → 11.21.1

package/src/core/modules/tenant/INTEGRATION-CHECKLIST.md

@@ -0,0 +1,165 @@
+# Tenant Module Integration Checklist
+
+## Reference Implementation
+
+- Local: `node_modules/@lenne.tech/nest-server/src/server/modules/tenant/` (when available)
+- GitHub: https://github.com/lenneTech/nest-server/tree/develop/src/core/modules/tenant
+
+## Quick Start (Auto-Registration)
+
+For projects that don't need custom tenant logic:
+
+```typescript
+// config.env.ts
+multiTenancy: {},
+```
+
+That's it. CoreModule auto-registers the tenant module, guard, and service.
+
+> **Note:** Auto-registration uses default model/guard/service. For custom implementations, use manual registration with `CoreTenantModule.forRoot({ service: CustomTenantService })` in your ServerModule.
+
+## Custom Integration (Manual Registration)
+
+### 1. Create TenantMember Model
+
+**Create:** `src/server/modules/tenant/tenant-member.model.ts`
+
+```typescript
+import { Schema } from '@nestjs/mongoose';
+import { CoreTenantMemberModel } from '@lenne.tech/nest-server';
+
+@Schema({ timestamps: true })
+export class TenantMember extends CoreTenantMemberModel {
+  // Add custom fields here if needed
+}
+```
+
+### 2. Create Custom Service (Optional)
+
+**Create:** `src/server/modules/tenant/tenant.service.ts`
+
+Extend `CoreTenantService` to add custom logic (notifications, tenant creation, etc.).
+
+### 3. Register in ServerModule
+
+**Modify:** `src/server/server.module.ts`
+
+```typescript
+import { CoreTenantModule } from '@lenne.tech/nest-server';
+import { TenantMember } from './modules/tenant/tenant-member.model';
+import { TenantService } from './modules/tenant/tenant.service';
+
+@Module({
+  imports: [
+    CoreTenantModule.forRoot({
+      memberModel: TenantMember,
+      service: TenantService,
+    }),
+    // ...
+  ],
+})
+export class ServerModule {}
+```
+
+### 4. Define Hierarchy Roles (Recommended)
+
+**Create:** `src/server/modules/tenant/roles.ts`
+
+```typescript
+import { createHierarchyRoles } from '@lenne.tech/nest-server';
+
+// Must match roleHierarchy in config.env.ts (or use DefaultHR for defaults)
+export const HR = createHierarchyRoles({ member: 1, manager: 2, owner: 3 });
+// HR.MEMBER = 'member', HR.MANAGER = 'manager', HR.OWNER = 'owner'
+```
+
+Or use the built-in `DefaultHR` for the default hierarchy:
+
+```typescript
+import { DefaultHR } from '@lenne.tech/nest-server';
+// DefaultHR.MEMBER, DefaultHR.MANAGER, DefaultHR.OWNER
+```
+
+### 5. Add Tenant Header to API Calls
+
+All tenant-scoped requests must include:
+
+```
+X-Tenant-Id: <tenant-id>
+```
+
+### 6. Add tenantId to Scoped Models
+
+Models that should be tenant-scoped need a `tenantId` field:
+
+```typescript
+@Prop({ type: String })
+tenantId: string;
+```
+
+The tenant plugin automatically filters and populates this field.
+
+### 7. Use Hierarchy Roles on Protected Endpoints
+
+```typescript
+import { Roles, CurrentTenant, DefaultHR } from '@lenne.tech/nest-server';
+
+@Roles(DefaultHR.MEMBER)   // any active member
+async listItems(@CurrentTenant() tenantId: string) { ... }
+
+@Roles(DefaultHR.MANAGER)  // at least manager level
+async updateItem(...) { ... }
+
+@Roles(DefaultHR.OWNER)    // highest level only
+async deleteItem(...) { ... }
+```
+
+Normal (non-hierarchy) roles also work:
+
+```typescript
+@Roles('auditor')  // exact match against membership.role
+async viewAuditLog(...) { ... }
+```
+
+### 8. Skip Tenant Check for Non-Tenant Endpoints
+
+Use `@SkipTenantCheck()` for endpoints that intentionally work without tenant context:
+
+```typescript
+import { SkipTenantCheck, Roles, RoleEnum } from '@lenne.tech/nest-server';
+
+@SkipTenantCheck()
+@Roles(RoleEnum.S_USER)
+async listMyTenants() { ... }
+```
+
+## Verification Checklist
+
+- [ ] `pnpm run build` succeeds
+- [ ] `pnpm test` passes
+- [ ] Request with `X-Tenant-Id` header only returns tenant data
+- [ ] Request without header + hierarchy role checks user.roles and filters tenantIds
+- [ ] Admin user can access any tenant (if adminBypass: true)
+- [ ] Non-member gets 403 "Not a member of this tenant"
+- [ ] Unauthenticated + header → 403 "Authentication required for tenant access"
+- [ ] Public endpoint accessing tenantId-schema without context throws 403 (Safety Net)
+
+## Security
+
+> **Defense-in-Depth:** The guard validates membership and sets `req.tenantId`. The Mongoose plugin only uses this validated value (via RequestContext) — never the raw header. Additionally, the plugin's Safety Net throws `ForbiddenException` when a tenantId-scoped schema is accessed without valid tenant context.
+
+> **Tenant overrides user.roles:** When a tenant header is present, only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass). This prevents users from claiming higher privileges via `user.roles` when operating within a specific tenant.
+
+> **Cross-tenant writes:** Never pass user-supplied `tenantId` directly to `create()` or `new Model()`. The plugin only auto-sets `tenantId` on new documents when no explicit value is provided. Accepting user-supplied values bypasses the auto-set and could allow cross-tenant writes.
+
+## Common Mistakes
+
+| Mistake                                          | Symptom                            | Fix                                                                        |
+| ------------------------------------------------ | ---------------------------------- | -------------------------------------------------------------------------- |
+| Missing `tenantId` field on model                | Data not filtered by tenant        | Add `@Prop({ type: String }) tenantId: string`                             |
+| Forgetting `X-Tenant-Id` header                  | 403 or Safety Net exception        | Add header to all tenant-scoped API calls                                  |
+| Using only `@Roles(S_USER)` for tenant endpoints | No tenant membership check         | Use `@Roles(DefaultHR.MEMBER)` for tenant-level access                     |
+| Querying membership without bypass               | Empty results due to tenant filter | Use `RequestContext.runWithBypassTenantGuard()`                            |
+| Public endpoint accessing tenantId-schema        | 403 Safety Net exception           | Use `@SkipTenantCheck()` + `RequestContext.runWithBypassTenantGuard()`     |
+| Passing user-supplied tenantId to create()       | Cross-tenant write possible        | Let plugin auto-set tenantId from context                                  |
+| Custom hierarchy doesn't match config            | Roles fail unexpectedly            | Ensure `createHierarchyRoles()` input matches `multiTenancy.roleHierarchy` |

package/src/core/modules/tenant/README.md

@@ -0,0 +1,268 @@
+# CoreTenantModule
+
+Header-based multi-tenancy for @lenne.tech/nest-server.
+
+## Overview
+
+Enables tenant-based data isolation where:
+
+- Users can be members of multiple tenants
+- The active tenant is selected per-request via `X-Tenant-Id` header
+- Data is automatically filtered by tenant (via the existing Mongoose tenant plugin)
+- Tenant membership and roles are validated per-request
+
+## Architecture
+
+```
+Request + X-Tenant-Id Header
+  -> RequestContextMiddleware (lazy getters for tenant context)
+  -> Auth Middleware (sets req.user)
+  -> CoreTenantGuard (validates membership, sets req.tenantId)
+  -> Mongoose Tenant Plugin (filters queries by context.tenantId)
+```
+
+**Defense-in-depth:** Two layers of protection:
+
+1. **Guard level:** CoreTenantGuard validates membership and sets `tenantId` (only after successful check)
+2. **Plugin level:** Safety Net — throws `ForbiddenException` when a tenantId-scoped schema is accessed without valid tenant context
+
+## Configuration
+
+```typescript
+// config.env.ts
+
+// Disabled (default) - zero overhead
+// multiTenancy: undefined
+
+// Enabled with defaults
+multiTenancy: {},
+
+// Enabled with custom settings
+multiTenancy: {
+  headerName: 'x-tenant-id',        // Header name (default: 'x-tenant-id')
+  membershipModel: 'TenantMember',  // Mongoose model name (default)
+  adminBypass: true,                 // System admins bypass membership (default: true)
+  excludeSchemas: ['User', 'Session'], // Schemas without tenant filtering
+  cacheTtlMs: 30000,                // Membership cache TTL in ms (default: 30s, 0 = disabled)
+  roleHierarchy: {                   // Custom role hierarchy (default below)
+    member: 1,
+    manager: 2,
+    owner: 3,
+  },
+},
+
+// Pre-configured but disabled
+multiTenancy: { enabled: false },
+```
+
+## Components
+
+| Component                | Purpose                                                |
+| ------------------------ | ------------------------------------------------------ |
+| `CoreTenantMemberModel`  | User-tenant membership (join table with role + status) |
+| `CoreTenantGuard`        | APP_GUARD validating tenant header + membership        |
+| `CoreTenantService`      | Membership CRUD (add, remove, update role, find)       |
+| `@SkipTenantCheck()`     | Method/class decorator to skip tenant validation       |
+| `@CurrentTenant()`       | Parameter decorator extracting validated tenant ID     |
+| `TenantMemberStatus`     | Enum: ACTIVE, INVITED, SUSPENDED                       |
+| `DefaultHR`              | Type-safe constants for default hierarchy roles        |
+| `createHierarchyRoles()` | Generate type-safe constants from custom hierarchy     |
+
+## Usage
+
+### Protecting Endpoints with Hierarchy Roles
+
+Use `@Roles()` with hierarchy role strings. Higher levels include lower levels (level comparison).
+
+```typescript
+import { Roles, CurrentTenant, DefaultHR } from '@lenne.tech/nest-server';
+
+@Controller('projects')
+export class ProjectController {
+  @Get()
+  @Roles(DefaultHR.MEMBER) // any active member (level >= 1)
+  async list(@CurrentTenant() tenantId: string) {
+    return this.projectService.find({ tenantId });
+  }
+
+  @Put(':id')
+  @Roles(DefaultHR.MANAGER) // at least manager level (level >= 2)
+  async update(@Param('id') id: string, @Body() body: UpdateDto) {
+    return this.projectService.update(id, body);
+  }
+
+  @Delete(':id')
+  @Roles(DefaultHR.OWNER) // highest level only (level >= 3)
+  async delete(@Param('id') id: string) {
+    return this.projectService.delete(id);
+  }
+}
+```
+
+### Hierarchy Roles
+
+The role hierarchy defines levels where higher includes lower:
+
+| Role Key  | Level | Can Access                 |
+| --------- | ----- | -------------------------- |
+| `owner`   | 3     | Everything                 |
+| `manager` | 2     | MANAGER + MEMBER endpoints |
+| `member`  | 1     | MEMBER endpoints only      |
+
+Multiple roles can share the same level (e.g., `editor: 2, manager: 2` → equivalent access).
+
+### Custom Hierarchy
+
+```typescript
+// config.env.ts
+multiTenancy: {
+  roleHierarchy: { viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 },
+}
+
+// roles.ts — type-safe constants
+import { createHierarchyRoles } from '@lenne.tech/nest-server';
+export const HR = createHierarchyRoles({ viewer: 1, editor: 2, manager: 2, admin: 3, owner: 4 });
+// HR.VIEWER = 'viewer', HR.EDITOR = 'editor', HR.MANAGER = 'manager', HR.ADMIN = 'admin', HR.OWNER = 'owner'
+
+// resolver.ts
+@Roles(HR.EDITOR)  // requires level >= 2 (editor, manager, admin, owner all pass)
+```
+
+### Normal (Non-Hierarchy) Roles
+
+Roles not in `roleHierarchy` use exact match — no higher role can compensate:
+
+```typescript
+// membership.role = 'auditor' → @Roles('auditor') passes, @Roles('manager') fails
+@Roles('auditor')
+async auditLog(@CurrentTenant() tenantId: string) { ... }
+```
+
+### Tenant Context Rule
+
+**When a tenant header is present:** Only `membership.role` is checked. `user.roles` is ignored (except ADMIN bypass).
+
+**When no tenant header:** `user.roles` is checked instead. Hierarchy roles use level comparison, normal roles use exact match.
+
+```typescript
+// Example: user.roles=['manager'], tenant membership.role='member'
+// @Roles(DefaultHR.MANAGER) with X-Tenant-Id header → 403 (member < manager)
+// @Roles(DefaultHR.MANAGER) without header → 200 (user.roles manager(2) >= manager(2))
+```
+
+### Skipping Tenant Checks
+
+Use `@SkipTenantCheck()` for endpoints that intentionally work without tenant context:
+
+```typescript
+@SkipTenantCheck()
+@Roles(RoleEnum.S_USER)
+async listMyTenants() { ... }
+```
+
+Note: `@SkipTenantCheck()` with hierarchy roles still checks `user.roles` (no tenant context).
+
+### Admin Bypass
+
+System admins (`RoleEnum.ADMIN`) bypass the membership check by default.
+Disable with `multiTenancy: { adminBypass: false }`.
+
+### Filtering Without Header
+
+| User State                     | Filter Applied                                                      |
+| ------------------------------ | ------------------------------------------------------------------- |
+| Not authenticated, no context  | Safety Net: `ForbiddenException` on tenantId-schemas                |
+| Authenticated, no memberships  | Safety Net: `ForbiddenException` on tenantId-schemas                |
+| Authenticated, has memberships | `{ tenantId: { $in: [user's tenant IDs] } }`                        |
+| Authenticated + hierarchy role | `{ tenantId: { $in: [qualified tenant IDs] } }` (filtered by level) |
+| Admin without header           | No filter (sees all data via `isAdminBypass`)                       |
+
+## Extending via Module Inheritance
+
+```typescript
+@Injectable()
+export class TenantService extends CoreTenantService {
+  override async addMember(tenantId: string, userId: string, role?: string) {
+    const member = await super.addMember(tenantId, userId, role);
+    await this.notificationService.sendInvite(userId, tenantId);
+    return member;
+  }
+}
+
+// module
+CoreTenantModule.forRoot({ service: TenantService });
+```
+
+## Performance Considerations
+
+### Membership Cache (since 11.21.1)
+
+The `CoreTenantGuard` uses an in-memory TTL cache for membership lookups and tenant ID resolution. This avoids repeated DB queries when the same user accesses the same tenant across multiple requests.
+
+```typescript
+// config.env.ts — configure or disable the cache
+multiTenancy: {
+  cacheTtlMs: 30000, // default: 30s. Set to 0 to disable.
+}
+```
+
+**Cache behavior:**
+- **Positive-only:** Only active memberships are cached. Non-member lookups always hit the DB (security-first).
+- **Auto-invalidation:** `CoreTenantService.addMember/removeMember/updateMemberRole` automatically invalidate the cache.
+- **Config-change detection:** Cache is flushed when `multiTenancy` config changes (e.g., `roleHierarchy` update).
+- **Bounded:** Max 500 entries with FIFO eviction. Memory overhead: ~100-250 KB.
+
+**Important:** The cache is process-local. In horizontally scaled deployments (multiple instances), membership changes on one instance are not reflected on other instances until the TTL expires. Set `cacheTtlMs: 0` for security-sensitive deployments.
+
+### Manual Cache Invalidation
+
+When extending `CoreTenantService` with custom membership mutation methods, call `invalidateUser()` after changes:
+
+```typescript
+@Injectable()
+export class TenantService extends CoreTenantService {
+  async customMembershipChange(tenantId: string, userId: string) {
+    // ... your logic ...
+    this.tenantGuard?.invalidateUser(userId);
+  }
+}
+```
+
+Use `invalidateAll()` to flush the entire cache (e.g., after bulk operations).
+
+### SkipTenantCheck
+
+For high-frequency endpoints that don't access tenant-scoped data, use `@SkipTenantCheck()` to avoid the membership lookup entirely.
+
+## Security Notes
+
+> **Defense-in-Depth:** The Mongoose tenant plugin uses `tenantId` from `RequestContext`, which is only set by `CoreTenantGuard` after successful membership validation. The raw `X-Tenant-Id` header is **never** used directly for filtering. Even if the guard is bypassed (e.g., via `@SkipTenantCheck()`), the plugin's Safety Net throws `ForbiddenException` when a tenantId-scoped schema is accessed without valid tenant context.
+
+> **Explicit tenantId on writes:** The plugin only auto-sets `tenantId` on new documents when no explicit value is provided. Service-layer code that accepts user-supplied `tenantId` as a creation parameter could allow cross-tenant writes. Never pass user-supplied `tenantId` directly to `create()` or `new Model()`.
+
+### Secured Membership Controller Example
+
+When building a tenant management UI, protect membership endpoints:
+
+```typescript
+@Controller('tenants/:tenantId/members')
+export class TenantMemberController {
+  @Get()
+  @Roles(DefaultHR.MANAGER)
+  async listMembers(@CurrentTenant() tenantId: string) {
+    return this.tenantService.findMemberships(tenantId);
+  }
+
+  @Post()
+  @Roles(DefaultHR.OWNER)
+  async addMember(@CurrentTenant() tenantId: string, @Body() body: AddMemberDto) {
+    return this.tenantService.addMember(tenantId, body.userId, body.role);
+  }
+}
+```
+
+## Related
+
+- [Integration Checklist](./INTEGRATION-CHECKLIST.md)
+- [Configurable Features](../../../.claude/rules/configurable-features.md)
+- [Request Lifecycle](../../../docs/REQUEST-LIFECYCLE.md)

package/src/core/modules/tenant/core-tenant-member.model.ts

@@ -0,0 +1,121 @@
+import { UnauthorizedException } from '@nestjs/common';
+import { ObjectType } from '@nestjs/graphql';
+import { Schema } from '@nestjs/mongoose';
+
+import { Restricted } from '../../common/decorators/restricted.decorator';
+import { UnifiedField } from '../../common/decorators/unified-field.decorator';
+import { RoleEnum } from '../../common/enums/role.enum';
+import { CorePersistenceModel } from '../../common/models/core-persistence.model';
+import { RequestContext } from '../../common/services/request-context.service';
+import { DefaultHR, TenantMemberStatus } from './core-tenant.enums';
+import { checkRoleAccess } from './core-tenant.helpers';
+
+/**
+ * Core tenant member model (join table: User <-> Tenant).
+ *
+ * Represents a user's membership in a tenant with a specific role and status.
+ * This model is automatically excluded from tenant filtering (it is tenant-spanning).
+ *
+ * Projects can extend this model to add custom fields.
+ */
+@ObjectType({ description: 'Tenant membership', isAbstract: true })
+@Restricted(RoleEnum.S_USER)
+@Schema({ timestamps: true })
+export class CoreTenantMemberModel extends CorePersistenceModel {
+  /**
+   * ID of the user who invited this member
+   */
+  @UnifiedField({
+    description: 'ID of the inviting user',
+    isOptional: true,
+    mongoose: { type: String },
+    roles: RoleEnum.S_USER,
+  })
+  invitedBy: string = undefined;
+
+  /**
+   * Date when the user joined the tenant
+   */
+  @UnifiedField({
+    description: 'Date when the user joined',
+    isOptional: true,
+    mongoose: { type: Date },
+    roles: RoleEnum.S_USER,
+    type: Date,
+  })
+  joinedAt: Date = undefined;
+
+  /**
+   * Role within the tenant (string matching a key in the configured role hierarchy)
+   */
+  @UnifiedField({
+    description: 'Tenant role',
+    mongoose: { default: 'member', type: String },
+    roles: RoleEnum.S_USER,
+    type: () => String,
+  })
+  role: string = undefined;
+
+  /**
+   * Membership status
+   */
+  @UnifiedField({
+    description: 'Membership status',
+    mongoose: { default: TenantMemberStatus.ACTIVE, enum: Object.values(TenantMemberStatus), type: String },
+    roles: RoleEnum.S_USER,
+    type: () => String,
+  })
+  status: TenantMemberStatus = undefined;
+
+  /**
+   * Tenant ID (= tenantId for data isolation)
+   */
+  @UnifiedField({
+    description: 'Tenant ID',
+    mongoose: { index: true, type: String },
+    roles: RoleEnum.S_USER,
+  })
+  tenant: string = undefined;
+
+  /**
+   * User ID (reference to User collection)
+   */
+  @UnifiedField({
+    description: 'User ID',
+    mongoose: { index: true, type: String },
+    roles: RoleEnum.S_USER,
+  })
+  user: string = undefined;
+
+  /**
+   * Verification of the user's rights to access the properties of this object.
+   *
+   * Allows access when:
+   * - force mode is enabled
+   * - the requesting user owns this membership (user.id === this.user)
+   * - the requesting user is a system admin
+   * - the requesting user is at least a manager-level member of the same tenant
+   */
+  override securityCheck(user: any, force?: boolean): this {
+    if (force) return this;
+    if (!user) throw new UnauthorizedException('Access to tenant membership denied');
+
+    // Own membership or system admin
+    if (user.id === this.user || user.hasRole?.(RoleEnum.ADMIN)) return this;
+
+    // Tenant manager/owner of the same tenant can view members.
+    // context.tenantId is the guard-validated tenant ID (not the raw header),
+    // see RequestContextMiddleware which reads req.tenantId.
+    const context = RequestContext.get();
+    const tenantRole = context?.tenantRole;
+    if (
+      tenantRole &&
+      checkRoleAccess([DefaultHR.MANAGER], undefined, tenantRole) &&
+      context?.tenantId === this.tenant
+    ) {
+      return this;
+    }
+
+    throw new UnauthorizedException('Access to tenant membership denied');
+  }
+}

package/src/core/modules/tenant/core-tenant.decorators.ts

@@ -0,0 +1,46 @@
+import { createParamDecorator, SetMetadata } from '@nestjs/common';
+
+import { RequestContext } from '../../common/services/request-context.service';
+
+/**
+ * Metadata key for @SkipTenantCheck() decorator.
+ */
+export const SKIP_TENANT_CHECK_KEY = 'skipTenantCheck';
+
+/**
+ * Method/class decorator that opts out of tenant checks for a specific endpoint.
+ * When present, CoreTenantGuard skips all tenant validation and does not set
+ * tenantId or isAdminBypass on the request.
+ *
+ * Use this for endpoints that intentionally work without tenant context,
+ * e.g., listing available tenants, user profile endpoints, etc.
+ *
+ * @example
+ * ```typescript
+ * @SkipTenantCheck()
+ * @Roles(RoleEnum.S_USER)
+ * async listMyTenants() { ... }
+ * ```
+ */
+export const SkipTenantCheck = () => SetMetadata(SKIP_TENANT_CHECK_KEY, true);
+
+/**
+ * Parameter decorator that extracts the validated tenant ID from the current request.
+ * Returns `undefined` if no tenant header is set or the endpoint has @SkipTenantCheck().
+ *
+ * Reads from RequestContext (set by CoreTenantGuard → req.tenantId →
+ * RequestContextMiddleware lazy getter → context.tenantId), so it works
+ * consistently across HTTP and GraphQL without context-type switching.
+ *
+ * @example
+ * ```typescript
+ * @Get('projects')
+ * @Roles(DefaultHR.MEMBER)
+ * async listProjects(@CurrentTenant() tenantId: string | undefined) {
+ *   // tenantId comes from X-Tenant-Id header, validated by CoreTenantGuard
+ * }
+ * ```
+ */
+export const CurrentTenant = createParamDecorator((): string | undefined => {
+  return RequestContext.get()?.tenantId;
+});

package/src/core/modules/tenant/core-tenant.enums.ts

@@ -0,0 +1,77 @@
+/**
+ * Injection token for the TenantMember Mongoose model.
+ * Use this constant instead of the string literal 'TenantMember' in @InjectModel() and getModelToken().
+ */
+export const TENANT_MEMBER_MODEL_TOKEN = 'TenantMember';
+
+/**
+ * Membership status for tenant members.
+ */
+export enum TenantMemberStatus {
+  ACTIVE = 'ACTIVE',
+  /** Reserved for future invitation workflow (not yet used in core logic) */
+  INVITED = 'INVITED',
+  SUSPENDED = 'SUSPENDED',
+}
+
+/**
+ * Default role hierarchy for tenant membership.
+ * Keys are role names (stored in membership documents), values are numeric levels.
+ * Higher value = more privileges. Multiple roles can share the same level.
+ *
+ * Can be customized via `multiTenancy.roleHierarchy` in config.
+ *
+ * Hierarchy roles use level comparison: a higher level includes all lower levels.
+ * Non-hierarchy roles (not in this config) use exact match only.
+ *
+ * @example Custom hierarchy:
+ * ```typescript
+ * const roleHierarchy = { viewer: 1, editor: 2, manager: 2, owner: 3 };
+ * const HR = createHierarchyRoles(roleHierarchy);
+ * // HR.VIEWER = 'viewer', HR.EDITOR = 'editor', HR.MANAGER = 'manager', HR.OWNER = 'owner'
+ * ```
+ */
+export const DEFAULT_ROLE_HIERARCHY: Record<string, number> = {
+  member: 1,
+  manager: 2,
+  owner: 3,
+};
+
+/**
+ * Generate typed UPPER_CASE constants from a role hierarchy config.
+ * Provides type-safe role strings for use with @Roles() and @Restricted() decorators.
+ *
+ * @example
+ * ```typescript
+ * const hierarchy = { viewer: 1, editor: 2, manager: 2, owner: 3 };
+ * const HR = createHierarchyRoles(hierarchy);
+ * // HR.VIEWER = 'viewer', HR.EDITOR = 'editor', HR.MANAGER = 'manager', HR.OWNER = 'owner'
+ *
+ * @Roles(HR.EDITOR) // requires at least level 2
+ * ```
+ *
+ * @returns Object with UPPER_CASE keys mapped to the original lowercase role name strings.
+ *          E.g. `{ viewer: 1, owner: 3 }` → `{ VIEWER: 'viewer', OWNER: 'owner' }`.
+ */
+export function createHierarchyRoles<T extends Record<string, number>>(
+  hierarchy: T,
+): { [K in keyof T as Uppercase<string & K>]: string & K } {
+  const result = {} as any;
+  for (const key of Object.keys(hierarchy)) {
+    result[key.toUpperCase()] = key;
+  }
+  return result;
+}
+
+/**
+ * Type-safe constants for the default role hierarchy.
+ * Convenience export for projects using the default { member: 1, manager: 2, owner: 3 } hierarchy.
+ *
+ * @example
+ * ```typescript
+ * @Roles(DefaultHR.MEMBER)   // any active member (level >= 1)
+ * @Roles(DefaultHR.MANAGER)  // at least manager level (level >= 2)
+ * @Roles(DefaultHR.OWNER)    // highest level only (level >= 3)
+ * ```
+ */
+export const DefaultHR = createHierarchyRoles(DEFAULT_ROLE_HIERARCHY);