@nestledjs/api 2.8.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestledjs/api",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "generators": "./generators.json",
   "type": "commonjs",
   "main": "./src/index.js",

package/src/config/files/src/lib/config.service.ts__tmpl__

@@ -6,6 +6,10 @@ import { CookieOptions } from 'express'
 export class ConfigService {
   constructor(public readonly config: NestConfigService) {}
 
+  get environment(): string {
+    return this.config.getOrThrow<string>('environment')
+  }
+
   get apiUrl(): string {
     return this.config.getOrThrow<string>('apiUrl')
   }
@@ -52,10 +56,26 @@ export class ConfigService {
     return this.config.getOrThrow<string>('siteUrl')
   }
 
+  get emailProvider(): string {
+    const provider = this.config.get<string>('email.provider')
+    if (provider) {
+      return provider
+    }
+
+    // Auto-detect: if SMTP is configured, use it; otherwise use mock
+    const smtpHost = this.config.get<string>('smtp.host')
+    return smtpHost ? 'smtp' : 'mock'
+  }
+
+  get frontendUrl(): string {
+    return this.config.getOrThrow<string>('frontend.url')
+  }
+
   get mailerConfig() {
     return {
       host: this.config.getOrThrow<string>('smtp.host'),
       port: this.config.getOrThrow<string>('smtp.port'),
+      secure: this.config.get<boolean>('smtp.secure') || false,
       auth: {
         user: this.config.getOrThrow<string>('smtp.user'),
         pass: this.config.getOrThrow<string>('smtp.pass'),
@@ -63,6 +83,23 @@ export class ConfigService {
     }
   }
 
+  get twilio() {
+    return {
+      accountSid: this.config.get('twilio.accountSid'),
+      authToken: this.config.get('twilio.authToken'),
+      fromNumber: this.config.get('twilio.fromNumber'),
+    }
+  }
+
+  get stripe() {
+    return {
+      secretKey: this.config.get<string>('STRIPE_SECRET_KEY') || '',
+      publishableKey: this.config.get<string>('STRIPE_PUBLISHABLE_KEY') || '',
+      webhookSecret: this.config.get<string>('STRIPE_WEBHOOK_SECRET') || '',
+      currency: this.config.get<string>('STRIPE_CURRENCY') || 'usd',
+    }
+  }
+
   get prismaOptimizeEnabled(): boolean {
     return this.config.get<boolean>('prisma.optimize.enabled') ?? false
   }

package/src/config/files/src/lib/configuration.ts__tmpl__

@@ -1,39 +1,66 @@
 export const configuration = () => ({
   prefix: 'api',
   environment: process.env['NODE_ENV'],
-  host: process.env['HOST'],
+  host: process.env['HOST'] ?? '0.0.0.0',
   port: parseInt(process.env['PORT'] ?? '3000', 10),
   apiUrl: process.env['API_URL'],
   api: {
     cookie: {
       name: process.env['API_COOKIE_NAME'],
-      secret: process.env['API_COOKIE_SECRET'] || 'secret',
+      secret: process.env['API_COOKIE_SECRET'] ?? 'secret',
       options: {
-        domain: process.env['API_COOKIE_DOMAIN'],
+        // Only set cookie domain if it is a valid registrable domain. Avoid 'localhost' or IPs.
+        ...(() => {
+          const dom = (process.env['API_COOKIE_DOMAIN'] ?? '').trim()
+          if (!dom || dom === 'localhost' || dom === '127.0.0.1' || dom === '[::1]') {
+            return {}
+          }
+          return { domain: dom }
+        })(),
         httpOnly: true,
+        secure: process.env['NODE_ENV'] === 'production',
+        sameSite: 'lax',
+        path: '/',
       },
     },
     cors: {
-      origin: [process.env['WEB_URL']],
+      origin: (process.env['ALLOWED_ORIGINS'] ?? '').split(',').map(o => o.trim()).filter(o => o.length > 0),
     },
   },
-  siteUrl: process.env['SITE_URL'] || process.env['API_URL']?.replace('/api', ''),
+  siteUrl: process.env['SITE_URL'] ?? process.env['API_URL']?.replace('/api', ''),
   app: {
     email: process.env['APP_EMAIL'],
     supportEmail: process.env['APP_SUPPORT_EMAIL'],
     adminEmails: process.env['APP_ADMIN_EMAILS'],
     name: process.env['APP_NAME'],
   },
+  email: {
+    provider: process.env['EMAIL_PROVIDER'] ?? 'smtp',
+  },
   smtp: {
     host: process.env['SMTP_HOST'],
     port: process.env['SMTP_PORT'],
     user: process.env['SMTP_USER'],
     pass: process.env['SMTP_PASS'],
   },
-  prisma: {
-    optimize: {
-      enabled: process.env['OPTIMIZE_ENABLED'] === 'true',
-      apiKey: process.env['OPTIMIZE_API_KEY'],
+  twoFactor: {
+    // Issuer name shown in authenticator apps
+    issuer: process.env['TWO_FACTOR_ISSUER'] ?? process.env['APP_NAME'] ?? 'MyApp',
+    // Window for time drift (in 30-second increments, 2 = 60 seconds tolerance)
+    window: parseInt(process.env['TWO_FACTOR_WINDOW'] ?? '2', 10),
+    // Encryption key for storing secrets (should be 32 characters)
+    encryptionKey: process.env['TWO_FACTOR_ENCRYPTION_KEY'] ?? process.env['JWT_SECRET'],
+  },
+  oauth: {
+    google: {
+      clientId: process.env['GOOGLE_OAUTH_CLIENT_ID'],
+      clientSecret: process.env['GOOGLE_OAUTH_CLIENT_SECRET'],
+      enabled: !!(process.env['GOOGLE_OAUTH_CLIENT_ID'] && process.env['GOOGLE_OAUTH_CLIENT_SECRET']),
+    },
+    github: {
+      clientId: process.env['GITHUB_OAUTH_CLIENT_ID'],
+      clientSecret: process.env['GITHUB_OAUTH_CLIENT_SECRET'],
+      enabled: !!(process.env['GITHUB_OAUTH_CLIENT_ID'] && process.env['GITHUB_OAUTH_CLIENT_SECRET']),
     },
   },
 })

package/src/config/files/src/lib/validation.ts__tmpl__

@@ -2,25 +2,27 @@ import * as Joi from 'joi'
 
 export const validationSchema = Joi.object({
   NODE_ENV: Joi.string().valid('development', 'production', 'test'),
-  HOST: Joi.alternatives()
-    .try(
-      Joi.string().ip({ version: ['ipv4', 'ipv6'] }),
-      Joi.string().hostname(),
-    )
-    .default('localhost'),
+  HOST: Joi.alternatives().try(
+    Joi.string().ip(), // Allow IP addresses like 0.0.0.0, 127.0.0.1
+    Joi.string().hostname(), // Allow hostnames like localhost, example.com
+  ).default('localhost'),
   PORT: Joi.number().default(3000),
   WEB_PORT: Joi.number().default(4200),
-  WEB_URL: Joi.string().default(`http://${process.env['HOST'] || 'localhost'}:${process.env['WEB_PORT']}`),
+  WEB_URL: Joi.string().default(
+    `http://${process.env['HOST'] || 'localhost'}:${process.env['WEB_PORT']}`,
+  ),
   API_COOKIE_DOMAIN: Joi.string().default('localhost'),
   API_COOKIE_NAME: Joi.string().default('__session'),
-  API_URL: Joi.string().default(`http://${process.env['HOST'] || 'localhost'}:${process.env['PORT']}/api`),
-  APP_NAME: Joi.string().required(),
-  APP_EMAIL: Joi.string().email().required(),
-  APP_SUPPORT_EMAIL: Joi.string().email().required(),
-  APP_ADMIN_EMAILS: Joi.string().required(),
-  SITE_URL: Joi.string().uri().required(),
-  SMTP_HOST: Joi.string().required(),
-  SMTP_PORT: Joi.string().required(),
-  SMTP_USER: Joi.string().required(),
-  SMTP_PASS: Joi.string().required(),
+  API_URL: Joi.string().default(
+    `http://${process.env['HOST'] || 'localhost'}:${process.env['PORT']}/api`,
+  ),
+  APP_NAME: Joi.string().default('BizToBiz'), // Made optional with default
+  APP_EMAIL: Joi.string().email().default('admin@example.com'), // Made optional with default
+  APP_SUPPORT_EMAIL: Joi.string().email().default('support@example.com'), // Made optional with default
+  APP_ADMIN_EMAILS: Joi.string().default('admin@example.com'), // Made optional with default
+  SITE_URL: Joi.string().uri().default('http://localhost:4200'), // Made optional with default
+  SMTP_HOST: Joi.string().default('localhost'), // Made optional with default
+  SMTP_PORT: Joi.string().default('587'), // Made optional with default
+  SMTP_USER: Joi.string().default('user'), // Made optional with default
+  SMTP_PASS: Joi.string().default('pass'), // Made optional with default
 })

package/src/prisma/generator.js

@@ -6,6 +6,7 @@ const devkit_1 = require("@nx/devkit");
 const utils_1 = require("@nestledjs/utils");
 function generateLibraries(tree_1) {
     return tslib_1.__awaiter(this, arguments, void 0, function* (tree, options = {}) {
+        const npmScope = (0, utils_1.getNpmScope)(tree);
         const templateRootPath = (0, devkit_1.joinPathFragments)(__dirname, './files');
         const overwrite = options.overwrite === true;
         // Create prisma.config.ts at workspace root via template (idempotent)
@@ -68,7 +69,7 @@ function generateLibraries(tree_1) {
             // Add db-update convenience script to regenerate CRUD, models, custom, and SDK
             if (!json.scripts['db-update']) {
                 json.scripts['db-update'] =
-                    'nx g @nestledjs/api:generate-crud && pnpm generate:models && nx g @nestledjs/api:custom && nx g @nestledjs/shared:sdk';
+                    `pnpm prisma:generate && nx g @${npmScope}/api:generate-crud && pnpm generate:models && nx g @${npmScope}/api:custom && nx g @${npmScope}/shared:sdk`;
             }
             return json;
         });

package/src/prisma/generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../../../../generators/api/src/prisma/generator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generator.js","sourceRoot":"","sources":["../../../../../generators/api/src/prisma/generator.ts"],"names":[],"mappings":"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"}

package/src/utils/files/src/index.ts__tmpl__

@@ -1,7 +1,12 @@
 export * from './lib/guards/gql-auth.guard'
 export * from './lib/guards/gql-auth-admin.guard'
+export * from './lib/guards/gql-organization-scoped.guard'
+export * from './lib/guards/permissions.guard'
+export * from './lib/guards/subscription.guard'
 export * from './lib/decorators/ctx-user.decorator'
-export * from './lib/types/nest-context-type'
+export * from './lib/decorators/ctx-organization.decorator'
+export * from './lib/services/auth-cache.service'
+export * from './lib/services/auth-loader.service'
 
 // Explicitly export types for webpack compatibility
-export type { NestContextType } from './lib/types/nest-context-type'
+export type { OrganizationContext, NestContextType } from './lib/types/nest-context-type'

package/src/utils/files/src/lib/decorators/ctx-organization.decorator.ts__tmpl__

@@ -0,0 +1,41 @@
+import { createParamDecorator, ExecutionContext, UnauthorizedException } from '@nestjs/common'
+import { GqlExecutionContext } from '@nestjs/graphql'
+import { OrganizationContext } from '../types/nest-context-type'
+
+/**
+ * Extract organization context from GraphQL request
+ * Throws UnauthorizedException if no organization context is found
+ */
+export const CtxOrganization = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext): OrganizationContext => {
+    const gqlContext = GqlExecutionContext.create(ctx).getContext()
+    const organizationContext = gqlContext.req.organizationContext
+
+    if (!organizationContext) {
+      throw new UnauthorizedException(
+        'Organization context required. Please set X-Organization-ID header or ensure user has an active organization.'
+      )
+    }
+
+    return organizationContext
+  }
+)
+
+/**
+ * Extract organization ID from context
+ * Throws UnauthorizedException if no organization context is found
+ */
+export const CtxOrganizationId = createParamDecorator(
+  (data: unknown, ctx: ExecutionContext): string => {
+    const gqlContext = GqlExecutionContext.create(ctx).getContext()
+    const organizationContext = gqlContext.req.organizationContext
+
+    if (!organizationContext) {
+      throw new UnauthorizedException(
+        'Organization context required. Please set X-Organization-ID header or ensure user has an active organization.'
+      )
+    }
+
+    return organizationContext.organizationId
+  }
+)

package/src/utils/files/src/lib/decorators/ctx-user.decorator.ts__tmpl__

@@ -1,6 +1,6 @@
-import { createParamDecorator } from '@nestjs/common'
+import { createParamDecorator, ExecutionContext } from '@nestjs/common'
 import { GqlExecutionContext } from '@nestjs/graphql'
 
-export const CtxUser = createParamDecorator(
-  (data, ctx) => GqlExecutionContext.create(ctx).getContext().req.user,
-)
+export const CtxUser = createParamDecorator((data: unknown, ctx: ExecutionContext) => {
+  return GqlExecutionContext.create(ctx).getContext().req.user
+})

package/src/utils/files/src/lib/guards/gql-auth-admin.guard.ts__tmpl__

@@ -5,8 +5,6 @@ import { User } from '@<%= npmScope %>/api/core/models'
 
 @Injectable()
 export class GqlAuthAdminGuard extends AuthGuard('jwt') {
-  private readonly _roles: string[] = ['Admin']
-
   override getRequest(context: ExecutionContext) {
     const ctx = GqlExecutionContext.create(context)
 
@@ -22,18 +20,19 @@ export class GqlAuthAdminGuard extends AuthGuard('jwt') {
     const ctx = GqlExecutionContext.create(context)
     const req = ctx.getContext().req
 
-    if (!req || !req.user) {
+    if (!req?.user) {
       return false
     }
     const hasAccess = this.hasAccess(req.user)
 
     if (!hasAccess) {
-      throw new ForbiddenException(`You need to have Admin access`)
+      throw new ForbiddenException(`You need to have Super Admin access`)
     }
     return req && req.user && this.hasAccess(req.user)
   }
 
   private hasAccess(user: User): boolean {
-    return !!(user.role && this._roles.includes(user.role))
+    // Only super admins can access admin-protected routes
+    return !!user.isSuperAdmin
   }
 }

package/src/utils/files/src/lib/guards/gql-organization-scoped.guard.ts__tmpl__

@@ -0,0 +1,43 @@
+import { ExecutionContext, Injectable, ForbiddenException } from '@nestjs/common'
+import { GqlExecutionContext } from '@nestjs/graphql'
+import { AuthGuard } from '@nestjs/passport'
+import { OrganizationContext } from '../types/nest-context-type'
+
+/**
+ * Guard that requires both authentication AND organization context.
+ * Use this guard for resolvers that operate on organization-scoped data.
+ */
+@Injectable()
+export class GqlOrganizationScopedGuard extends AuthGuard('jwt') {
+  override getRequest(context: ExecutionContext): any {
+    const ctx = GqlExecutionContext.create(context)
+    return ctx.getContext().req
+  }
+
+  override async canActivate(context: ExecutionContext): Promise<boolean> {
+    // First, run the standard JWT authentication
+    const canActivate = await super.canActivate(context)
+    if (!canActivate) {
+      return false
+    }
+
+    // Then check for organization context
+    const req = this.getRequest(context)
+    const organizationContext: OrganizationContext | undefined = req.organizationContext
+
+    if (!organizationContext) {
+      throw new ForbiddenException(
+        'Organization context is required for this operation. Please set an active organization.'
+      )
+    }
+
+    // Check if organization context is complete
+    if (!organizationContext.organizationId || !organizationContext.roleId) {
+      throw new ForbiddenException(
+        'Invalid organization context. Please ensure you have a valid membership in the organization.'
+      )
+    }
+
+    return true
+  }
+}

package/src/utils/files/src/lib/guards/permissions.guard.ts__tmpl__

@@ -0,0 +1,101 @@
+import { Injectable, CanActivate, ExecutionContext, ForbiddenException, SetMetadata } from '@nestjs/common'
+import { Reflector } from '@nestjs/core'
+import { GqlExecutionContext } from '@nestjs/graphql'
+import { OrganizationContext } from '../types/nest-context-type'
+
+export const PERMISSIONS_KEY = 'permissions'
+
+export interface PermissionRequirement {
+  subject: string
+  action: string
+}
+
+/**
+ * Decorator to require specific permissions for a resolver/mutation
+ * Usage: @RequirePermissions({ subject: 'organization', action: 'update' })
+ */
+export const RequirePermissions = (...permissions: PermissionRequirement[]) =>
+  SetMetadata(PERMISSIONS_KEY, permissions)
+
+/**
+ * Guard that checks if the user has required permissions in their current organization
+ */
+@Injectable()
+export class PermissionsGuard implements CanActivate {
+  constructor(private reflector: Reflector) {}
+
+  canActivate(context: ExecutionContext): boolean {
+    const requiredPermissions = this.reflector.getAllAndOverride<PermissionRequirement[]>(
+      PERMISSIONS_KEY,
+      [context.getHandler(), context.getClass()]
+    )
+
+    if (!requiredPermissions || requiredPermissions.length === 0) {
+      return true
+    }
+
+    const gqlContext = GqlExecutionContext.create(context).getContext()
+    const organizationContext: OrganizationContext | undefined = gqlContext.req.organizationContext
+
+    if (!organizationContext) {
+      throw new ForbiddenException('Organization context required for this operation')
+    }
+
+    const hasAllPermissions = requiredPermissions.every(required =>
+      organizationContext.permissions.some(
+        p => p.subject === required.subject && p.action === required.action
+      )
+    )
+
+    if (!hasAllPermissions) {
+      const missingPermissions = requiredPermissions
+        .filter(
+          required =>
+            !organizationContext.permissions.some(
+              p => p.subject === required.subject && p.action === required.action
+            )
+        )
+        .map(p => `${p.subject}:${p.action}`)
+
+      throw new ForbiddenException(
+        `Missing required permissions: ${missingPermissions.join(', ')}. Current role: ${organizationContext.roleName}`
+      )
+    }
+
+    return true
+  }
+}
+
+/**
+ * Helper function to check permissions programmatically in services
+ */
+export function hasPermission(
+  organizationContext: OrganizationContext | undefined,
+  subject: string,
+  action: string
+): boolean {
+  if (!organizationContext) {
+    return false
+  }
+
+  return organizationContext.permissions.some(
+    p => p.subject === subject && p.action === action
+  )
+}
+
+/**
+ * Helper function to require permission or throw
+ */
+export function requirePermission(
+  organizationContext: OrganizationContext | undefined,
+  subject: string,
+  action: string
+): void {
+  if (!hasPermission(organizationContext, subject, action)) {
+    throw new ForbiddenException(
+      `Missing required permission: ${subject}:${action}${
+        organizationContext ? `. Current role: ${organizationContext.roleName}` : ''
+      }`
+    )
+  }
+}

package/src/utils/files/src/lib/guards/subscription.guard.ts__tmpl__

@@ -0,0 +1,79 @@
+import { Injectable, CanActivate, ExecutionContext, HttpException, HttpStatus } from '@nestjs/common'
+import { GqlExecutionContext } from '@nestjs/graphql'
+import { SubscriptionStatus } from '@<%= npmScope %>/api/prisma'
+import { ApiCoreDataAccessService } from '@<%= npmScope %>/api/core/data-access'
+
+/**
+ * Subscription Guard - Protects resolvers by requiring an active subscription.
+ */
+@Injectable()
+export class SubscriptionGuard implements CanActivate {
+  constructor(private readonly prisma: ApiCoreDataAccessService) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const ctx = GqlExecutionContext.create(context)
+    const { req } = ctx.getContext()
+
+    const user = req.user
+    if (!user) {
+      throw new HttpException('Authentication required', HttpStatus.UNAUTHORIZED)
+    }
+
+    const activeOrganizationId = user.activeOrganizationId
+    if (!activeOrganizationId) {
+      throw new HttpException(
+        'No active organization. Please select an organization.',
+        HttpStatus.FORBIDDEN,
+      )
+    }
+
+    const subscription = await this.prisma.subscription.findUnique({
+      where: { organizationId: activeOrganizationId },
+      include: { plan: true },
+    })
+
+    if (!subscription) {
+      throw new HttpException(
+        'No subscription found. Please subscribe to a plan to access this feature.',
+        HttpStatus.PAYMENT_REQUIRED,
+      )
+    }
+
+    const validStatuses: SubscriptionStatus[] = [
+      SubscriptionStatus.ACTIVE,
+      SubscriptionStatus.TRIALING,
+    ]
+
+    if (!validStatuses.includes(subscription.status)) {
+      if (subscription.status === SubscriptionStatus.PAST_DUE) {
+        const gracePeriodDays = 3
+        const currentPeriodEnd = subscription.stripeCurrentPeriodEnd
+        if (currentPeriodEnd) {
+          const gracePeriodEnd = new Date(currentPeriodEnd)
+          gracePeriodEnd.setDate(gracePeriodEnd.getDate() + gracePeriodDays)
+
+          if (new Date() <= gracePeriodEnd) {
+            return true
+          }
+        }
+      }
+
+      throw new HttpException(
+        `Subscription is ${subscription.status.toLowerCase()}. Please update your payment method.`,
+        HttpStatus.PAYMENT_REQUIRED,
+      )
+    }
+
+    if (subscription.cancelAtPeriodEnd && subscription.stripeCurrentPeriodEnd) {
+      const periodEnd = new Date(subscription.stripeCurrentPeriodEnd)
+      if (new Date() > periodEnd) {
+        throw new HttpException(
+          'Subscription has expired. Please renew your subscription.',
+          HttpStatus.PAYMENT_REQUIRED,
+        )
+      }
+    }
+
+    return true
+  }
+}

package/src/utils/files/src/lib/services/auth-cache.service.ts__tmpl__

@@ -0,0 +1,232 @@
+import { Injectable, Logger, OnModuleInit } from '@nestjs/common'
+import { Redis } from 'ioredis'
+import { OrganizationContext } from '../types/nest-context-type'
+
+const SESSION_TTL = 15 * 60 // 15 minutes
+const MEMBERSHIP_TTL = 10 * 60 // 10 minutes
+const USER_ORG_TTL = 10 * 60 // 10 minutes
+
+export interface CachedSession {
+  userId: string
+  email: string
+  isSuperAdmin: boolean
+  activeOrganizationId?: string
+}
+
+export interface CachedMembership {
+  organizationId: string
+  userId: string
+  roleId: string
+  roleName: string
+  permissions: Array<{ subject: string; action: string }>
+}
+
+@Injectable()
+export class AuthCacheService implements OnModuleInit {
+  private readonly logger = new Logger(AuthCacheService.name)
+  private redis: Redis | null = null
+  private isConnected = false
+
+  async onModuleInit() {
+    const redisUrl = process.env['REDIS_URL']
+    if (!redisUrl) {
+      this.logger.warn('REDIS_URL not configured - auth caching disabled')
+      return
+    }
+
+    try {
+      this.redis = new Redis(redisUrl, {
+        maxRetriesPerRequest: 3,
+        retryDelayOnFailover: 100,
+        lazyConnect: true,
+      })
+
+      this.redis.on('connect', () => {
+        this.isConnected = true
+        this.logger.log('Redis connected for auth caching')
+      })
+
+      this.redis.on('error', (err) => {
+        this.isConnected = false
+        this.logger.warn(`Redis error: ${err.message}`)
+      })
+
+      this.redis.on('close', () => {
+        this.isConnected = false
+      })
+
+      await this.redis.connect()
+    } catch (error) {
+      this.logger.warn(`Failed to connect to Redis: ${error}`)
+      this.redis = null
+    }
+  }
+
+  private get available(): boolean {
+    return this.redis !== null && this.isConnected
+  }
+
+  // Session caching
+  private sessionKey(userId: string): string {
+    return `auth:session:${userId}`
+  }
+
+  async getSession(userId: string): Promise<CachedSession | null> {
+    if (!this.available) return null
+
+    try {
+      const data = await this.redis!.get(this.sessionKey(userId))
+      return data ? JSON.parse(data) : null
+    } catch (error) {
+      this.logger.debug(`Cache miss for session ${userId}: ${error}`)
+      return null
+    }
+  }
+
+  async setSession(userId: string, session: CachedSession): Promise<void> {
+    if (!this.available) return
+
+    try {
+      await this.redis!.setex(
+        this.sessionKey(userId),
+        SESSION_TTL,
+        JSON.stringify(session)
+      )
+    } catch (error) {
+      this.logger.debug(`Failed to cache session: ${error}`)
+    }
+  }
+
+  async invalidateSession(userId: string): Promise<void> {
+    if (!this.available) return
+
+    try {
+      await this.redis!.del(this.sessionKey(userId))
+    } catch (error) {
+      this.logger.debug(`Failed to invalidate session: ${error}`)
+    }
+  }
+
+  // Membership context caching
+  private membershipKey(userId: string, organizationId: string): string {
+    return `auth:membership:${userId}:${organizationId}`
+  }
+
+  async getMembershipContext(
+    userId: string,
+    organizationId: string
+  ): Promise<OrganizationContext | null> {
+    if (!this.available) return null
+
+    try {
+      const data = await this.redis!.get(this.membershipKey(userId, organizationId))
+      return data ? JSON.parse(data) : null
+    } catch (error) {
+      this.logger.debug(`Cache miss for membership ${userId}:${organizationId}: ${error}`)
+      return null
+    }
+  }
+
+  async setMembershipContext(
+    userId: string,
+    organizationId: string,
+    context: OrganizationContext
+  ): Promise<void> {
+    if (!this.available) return
+
+    try {
+      await this.redis!.setex(
+        this.membershipKey(userId, organizationId),
+        MEMBERSHIP_TTL,
+        JSON.stringify(context)
+      )
+    } catch (error) {
+      this.logger.debug(`Failed to cache membership context: ${error}`)
+    }
+  }
+
+  async invalidateMembership(userId: string, organizationId: string): Promise<void> {
+    if (!this.available) return
+
+    try {
+      await this.redis!.del(this.membershipKey(userId, organizationId))
+    } catch (error) {
+      this.logger.debug(`Failed to invalidate membership: ${error}`)
+    }
+  }
+
+  async invalidateAllMembershipsForUser(userId: string): Promise<void> {
+    if (!this.available) return
+
+    try {
+      const pattern = `auth:membership:${userId}:*`
+      const keys = await this.redis!.keys(pattern)
+      if (keys.length > 0) {
+        await this.redis!.del(...keys)
+      }
+    } catch (error) {
+      this.logger.debug(`Failed to invalidate all memberships for user: ${error}`)
+    }
+  }
+
+  async invalidateAllMembershipsForOrganization(organizationId: string): Promise<void> {
+    if (!this.available) return
+
+    try {
+      const pattern = `auth:membership:*:${organizationId}`
+      const keys = await this.redis!.keys(pattern)
+      if (keys.length > 0) {
+        await this.redis!.del(...keys)
+      }
+    } catch (error) {
+      this.logger.debug(`Failed to invalidate all memberships for org: ${error}`)
+    }
+  }
+
+  // User active organization caching
+  private userOrgKey(userId: string): string {
+    return `auth:user-org:${userId}`
+  }
+
+  async getUserActiveOrganization(userId: string): Promise<string | null> {
+    if (!this.available) return null
+
+    try {
+      return await this.redis!.get(this.userOrgKey(userId))
+    } catch (error) {
+      this.logger.debug(`Cache miss for user org ${userId}: ${error}`)
+      return null
+    }
+  }
+
+  async setUserActiveOrganization(userId: string, organizationId: string): Promise<void> {
+    if (!this.available) return
+
+    try {
+      await this.redis!.setex(this.userOrgKey(userId), USER_ORG_TTL, organizationId)
+    } catch (error) {
+      this.logger.debug(`Failed to cache user org: ${error}`)
+    }
+  }
+
+  async invalidateUserActiveOrganization(userId: string): Promise<void> {
+    if (!this.available) return
+
+    try {
+      await this.redis!.del(this.userOrgKey(userId))
+    } catch (error) {
+      this.logger.debug(`Failed to invalidate user org: ${error}`)
+    }
+  }
+
+  // Role change invalidation
+  async onRolePermissionsChanged(roleId: string, organizationId: string): Promise<void> {
+    // When role permissions change, invalidate all memberships for that organization
+    await this.invalidateAllMembershipsForOrganization(organizationId)
+  }
+
+  async onUserRoleChanged(userId: string, organizationId: string): Promise<void> {
+    // When a user's role changes, invalidate their membership context
+    await this.invalidateMembership(userId, organizationId)
+  }
+}

package/src/utils/files/src/lib/services/auth-loader.service.ts__tmpl__

@@ -0,0 +1,176 @@
+import { Injectable, Scope } from '@nestjs/common'
+import DataLoader from 'dataloader'
+import { ApiCoreDataAccessService } from '@<%= npmScope %>/api/core/data-access'
+import { AuthCacheService } from './auth-cache.service'
+import { OrganizationContext } from '../types/nest-context-type'
+
+interface MembershipKey {
+  userId: string
+  organizationId: string
+}
+
+interface MembershipWithRole {
+  id: string
+  userId: string
+  organizationId: string
+  role: {
+    id: string
+    name: string
+    permissions: Array<{
+      permission: {
+        subject: string
+        action: string
+      }
+    }>
+  }
+}
+
+/**
+ * Request-scoped DataLoader service for batching auth lookups.
+ * Uses three-tier caching: request → Redis → database
+ */
+@Injectable({ scope: Scope.REQUEST })
+export class AuthLoaderService {
+  private membershipLoader: DataLoader<string, MembershipWithRole | null>
+
+  constructor(
+    private readonly prisma: ApiCoreDataAccessService,
+    private readonly authCache: AuthCacheService
+  ) {
+    this.membershipLoader = new DataLoader<string, MembershipWithRole | null>(
+      async (keys) => this.batchLoadMemberships(keys as string[]),
+      {
+        cacheKeyFn: (key) => key,
+      }
+    )
+  }
+
+  private membershipKeyToString(key: MembershipKey): string {
+    return `${key.userId}:${key.organizationId}`
+  }
+
+  private stringToMembershipKey(str: string): MembershipKey {
+    const [userId, organizationId] = str.split(':')
+    return { userId, organizationId }
+  }
+
+  private async batchLoadMemberships(
+    keys: string[]
+  ): Promise<(MembershipWithRole | null)[]> {
+    const membershipKeys = keys.map((k) => this.stringToMembershipKey(k))
+
+    // Build WHERE conditions for batch query
+    const conditions = membershipKeys.map((k) => ({
+      userId: k.userId,
+      organizationId: k.organizationId,
+    }))
+
+    // Batch fetch all memberships with their roles and permissions
+    const memberships = await this.prisma.organizationMembership.findMany({
+      where: {
+        OR: conditions,
+      },
+      include: {
+        role: {
+          include: {
+            permissions: {
+              include: {
+                permission: true,
+              },
+            },
+          },
+        },
+      },
+    })
+
+    // Map results back to original key order
+    const membershipMap = new Map<string, MembershipWithRole>()
+    for (const membership of memberships) {
+      const key = this.membershipKeyToString({
+        userId: membership.userId,
+        organizationId: membership.organizationId,
+      })
+      membershipMap.set(key, membership as MembershipWithRole)
+    }
+
+    return keys.map((key) => membershipMap.get(key) || null)
+  }
+
+  /**
+   * Load membership context with three-tier caching
+   */
+  async loadMembershipContext(
+    userId: string,
+    organizationId: string
+  ): Promise<OrganizationContext | null> {
+    // Tier 1: Check Redis cache
+    const cached = await this.authCache.getMembershipContext(userId, organizationId)
+    if (cached) {
+      return cached
+    }
+
+    // Tier 2: Use DataLoader (request-scoped batch caching)
+    const key = this.membershipKeyToString({ userId, organizationId })
+    const membership = await this.membershipLoader.load(key)
+
+    if (!membership) {
+      return null
+    }
+
+    // Build organization context from membership
+    const context: OrganizationContext = {
+      organizationId: membership.organizationId,
+      userId: membership.userId,
+      roleId: membership.role.id,
+      roleName: membership.role.name,
+      permissions: membership.role.permissions.map((rp) => ({
+        subject: rp.permission.subject,
+        action: rp.permission.action,
+      })),
+    }
+
+    // Tier 3: Store in Redis for future requests
+    await this.authCache.setMembershipContext(userId, organizationId, context)
+
+    return context
+  }
+
+  /**
+   * Preload multiple membership contexts (useful for batch operations)
+   */
+  async preloadMembershipContexts(
+    keys: MembershipKey[]
+  ): Promise<Map<string, OrganizationContext | null>> {
+    const results = new Map<string, OrganizationContext | null>()
+
+    await Promise.all(
+      keys.map(async (key) => {
+        const context = await this.loadMembershipContext(key.userId, key.organizationId)
+        results.set(this.membershipKeyToString(key), context)
+      })
+    )
+
+    return results
+  }
+
+  /**
+   * Clear the request-scoped DataLoader cache
+   */
+  clearCache(): void {
+    this.membershipLoader.clearAll()
+  }
+}
+
+/**
+ * Factory function for creating AuthLoaderService
+ * Use this when you need to inject the service with its dependencies
+ */
+export const AUTH_LOADER_SERVICE = 'AUTH_LOADER_SERVICE'
+
+export const authLoaderServiceFactory = {
+  provide: AUTH_LOADER_SERVICE,
+  useFactory: (prisma: ApiCoreDataAccessService, authCache: AuthCacheService) => {
+    return new AuthLoaderService(prisma, authCache)
+  },
+  inject: [ApiCoreDataAccessService, AuthCacheService],
+}

package/src/utils/files/src/lib/types/nest-context-type.ts__tmpl__

@@ -1,4 +1,18 @@
+import { Request, Response } from 'express'
+import { User } from '@<%= npmScope %>/api/core/models'
+
+export interface OrganizationContext {
+  organizationId: string
+  userId: string
+  roleId: string
+  roleName: string
+  permissions: Array<{ subject: string; action: string }>
+}
+
 export interface NestContextType {
-  req: Request
+  req: Request & {
+    user?: User
+    organizationContext?: OrganizationContext
+  }
   res: Response
 }