@wildo-ai/saas-backend-lib 1.0.1

package/src/security/scim/controllers/scim.backend.controller.ts

@@ -0,0 +1,1066 @@
+/**
+ * SCIM 2.0 User Provisioning Controller — Step 20
+ *
+ * Receives user lifecycle events from identity providers (Okta, Azure AD, OneLogin)
+ * via SCIM 2.0 protocol (RFC 7643 Core Schema, RFC 7644 Protocol).
+ *
+ * Decision 13: Lean SCIM — Users only in v1, no Groups, no generic adapter.
+ * Critical Note #8: One controller, Users only, future extensions documented in code comments.
+ * Critical Note #9: Follows billing's ManualControllersOptions pattern for conditional mounting.
+ *
+ * Bearer token auth: extracts token from Authorization header, hashes it,
+ * looks up ScimTokenBase, validates isActive/expiresAt,
+ * creates ExecutionContext with executionType: ORG_API_KEY.
+ *
+ * Reuses EnterpriseUserProvisioningService from Step 15 for:
+ * - createOrgUser() — user + profile + org member + identity link creation
+ * - updateOrgUser() — profile attribute updates
+ * - deactivateOrgUser() — set user status to INACTIVE
+ */
+
+import 'reflect-metadata';
+import { injectable, inject } from 'inversify';
+import { createHash } from 'crypto';
+import type { Request, Response, NextFunction } from 'express';
+import { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { ErrorHandlerService } from '~wildo-backend-lib/errors/services/error-handler.backend.service';
+import type { ServicesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/services/services-registry-handler.backend.service';
+import type { Resources_PaginatedResult } from '@wildo-ai/saas-models';
+import { AuthExecutionContextFactoryBackendService } from '~wildo-backend-lib/security/authentications/services/auth-execution-context-factory.backend.service';
+import { EnterpriseUserProvisioningBackendService, type EnterpriseProvisioningConfig } from '~wildo-backend-lib/security/authentications/services/admin-config/enterprise-user-provisioning.backend.service';
+import type { NormalizedUserProfile, ProvisioningConnectionContext } from '~wildo-backend-lib/security/authentications/models/sso-connection.backend.schemas';
+import { AuditLogsBackendService } from '~wildo-backend-lib/compliance/audit-trails/services/audit-logs.backend.service';
+import { AbstractControllerBackendService } from '~wildo-backend-lib/base-classes/services/controllers/abstract-controller.backend.service';
+import {
+  CoreResourceType,
+  UserStatus,
+  ErrorType,
+  isWildoBackendError,
+  AuthScopeType,
+  WildoHeaderKeys,
+} from '@wildo-ai/saas-models';
+import type { User } from '@wildo-ai/saas-models';
+import type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+import type { ScimTokenBase } from '@wildo-ai/saas-models';
+import {
+  SCIM_USER_ATTRIBUTE_MAP,
+  SCIM_SCHEMAS,
+  SCIM_CONTENT_TYPE,
+  SCIM_SERVICE_PROVIDER_CONFIG,
+  SCIM_USER_SCHEMA_DEFINITION,
+  SCIM_RESOURCE_TYPES,
+  type SCIMPatchOperation,
+  type SCIMBulkRequest,
+  type SCIMBulkOperationResponse,
+} from '~wildo-backend-lib/security/scim/models/scim-protocol.backend.schemas';
+import { parseSCIMFilter } from '~wildo-backend-lib/security/scim/utils/scim-filter-parser';
+import { formatUserAsSCIM, formatListAsSCIM, formatSCIMError } from '~wildo-backend-lib/security/scim/utils/scim-response-formatter';
+import { AuthOrganizationConfigurationService } from '~wildo-backend-lib/security/authentications/services/admin-config/auth-organization-configuration.service';
+import { RateLimitBackendService } from '~wildo-backend-lib/errors/services/rate-limit.backend.service';
+import type { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';
+import { isScimProvisioningEnabledForOrg } from '~wildo-backend-lib/organizations/services/scim-provisioning-gate.backend.utils';
+
+@injectable()
+export class SCIMControllerBackendService extends AbstractControllerBackendService {
+  private readonly SCIM_RATE_LIMIT_MAX_REQUESTS = 300;  // per token per minute
+  private readonly SCIM_RATE_LIMIT_WINDOW_SECONDS = 60;
+
+  constructor(
+    @inject(SAAS_SERVICE_TYPES.Logger) logger: LoggerService,
+    @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) errorBuilder: ErrorBuilderBackendService,
+    @inject(SAAS_SERVICE_TYPES.ErrorHandlerService) errorHandler: ErrorHandlerService,
+    @inject(SAAS_SERVICE_TYPES.ServicesRegistryHandlerService) private readonly servicesRegistryHandler: ServicesRegistryHandlerBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthExecutionContextFactory) private readonly authEcFactory: AuthExecutionContextFactoryBackendService,
+    @inject(SAAS_SERVICE_TYPES.EnterpriseUserProvisioningService) private readonly provisioningService: EnterpriseUserProvisioningBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuditLogsService) private readonly auditLogsService: AuditLogsBackendService,
+    @inject(SAAS_SERVICE_TYPES.AuthOrganizationConfigurationService) private readonly orgConfigService: AuthOrganizationConfigurationService,
+    @inject(SAAS_SERVICE_TYPES.RateLimitBackendService) private readonly rateLimitService: RateLimitBackendService,
+    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfigService: AppConfigurationService,
+  ) {
+    super(logger, errorBuilder, errorHandler, 'SCIMController');
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Route Setup
+  // ═══════════════════════════════════════════════════════════════
+
+  protected setupRoutes(): void {
+    // SCIM Discovery endpoints (no auth required for ServiceProviderConfig per RFC 7644 §4)
+    this.router.get('/scim/v2/ServiceProviderConfig', this.asyncHandler(this._handleServiceProviderConfig.bind(this)));
+    this.logRouteRegistration('GET', '/scim/v2/ServiceProviderConfig', 'SCIM ServiceProviderConfig');
+
+    this.router.get('/scim/v2/Schemas', this.asyncHandler(this._handleSchemas.bind(this)));
+    this.logRouteRegistration('GET', '/scim/v2/Schemas', 'SCIM Schemas');
+
+    this.router.get('/scim/v2/ResourceTypes', this.asyncHandler(this._handleResourceTypes.bind(this)));
+    this.logRouteRegistration('GET', '/scim/v2/ResourceTypes', 'SCIM ResourceTypes');
+
+    // All /Users endpoints require bearer token auth
+    const authMiddleware = this._scimBearerAuthMiddleware.bind(this);
+
+    this.router.post('/scim/v2/Users', authMiddleware, this.asyncHandler(this._handleCreateUser.bind(this)));
+    this.logRouteRegistration('POST', '/scim/v2/Users', 'SCIM Create User');
+
+    this.router.get('/scim/v2/Users', authMiddleware, this.asyncHandler(this._handleListUsers.bind(this)));
+    this.logRouteRegistration('GET', '/scim/v2/Users', 'SCIM List Users');
+
+    this.router.get('/scim/v2/Users/:id', authMiddleware, this.asyncHandler(this._handleGetUser.bind(this)));
+    this.logRouteRegistration('GET', '/scim/v2/Users/:id', 'SCIM Get User');
+
+    this.router.put('/scim/v2/Users/:id', authMiddleware, this.asyncHandler(this._handleReplaceUser.bind(this)));
+    this.logRouteRegistration('PUT', '/scim/v2/Users/:id', 'SCIM Replace User');
+
+    this.router.patch('/scim/v2/Users/:id', authMiddleware, this.asyncHandler(this._handlePatchUser.bind(this)));
+    this.logRouteRegistration('PATCH', '/scim/v2/Users/:id', 'SCIM Patch User');
+
+    this.router.delete('/scim/v2/Users/:id', authMiddleware, this.asyncHandler(this._handleDeleteUser.bind(this)));
+    this.logRouteRegistration('DELETE', '/scim/v2/Users/:id', 'SCIM Delete User');
+
+    // Bulk operations (Step 21)
+    this.router.post('/scim/v2/Bulk', authMiddleware, this.asyncHandler(this._handleBulk.bind(this)));
+    this.logRouteRegistration('POST', '/scim/v2/Bulk', 'SCIM Bulk Operations');
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Bearer Token Auth Middleware
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _scimBearerAuthMiddleware(req: Request, res: Response, next: NextFunction): Promise<void> {
+    const authHeader = req.headers[WildoHeaderKeys.AUTHORIZATION];
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      res.status(401).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+        formatSCIMError(401, 'Bearer token required', 'invalidValue')
+      );
+      return;
+    }
+
+    const plainToken = authHeader.substring(7);
+    if (!plainToken) {
+      res.status(401).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+        formatSCIMError(401, 'Bearer token is empty', 'invalidValue')
+      );
+      return;
+    }
+
+    const tokenHash = this._hashToken(plainToken);
+
+    try {
+      const ec = await this._getInternalExecutionContext();
+      const token = await this.servicesRegistryHandler.read<ScimTokenBase & { organizationId: string }>(CoreResourceType.ORGANIZATION_SCIM_TOKENS, ec, { tokenHash });
+
+      if (!token) {
+        this._logSCIMOperation('auth_failed', { reason: 'token_not_found' });
+        res.status(401).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(401, 'Invalid bearer token')
+        );
+        return;
+      }
+
+      if (!token.isActive) {
+        this._logSCIMOperation('auth_failed', { reason: 'token_inactive', tokenId: token._id });
+        res.status(401).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(401, 'Token has been revoked')
+        );
+        return;
+      }
+
+      if (token.expiresAt && new Date(token.expiresAt) < new Date()) {
+        this._logSCIMOperation('auth_failed', { reason: 'token_expired', tokenId: token._id });
+        res.status(401).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(401, 'Token has expired')
+        );
+        return;
+      }
+
+      // Per-token rate limiting (Step 21 — CORE-9: Redis-backed, distributed)
+      try {
+        await this.rateLimitService.checkRateLimit(
+          `scim:token:${token._id}`,
+          this.SCIM_RATE_LIMIT_MAX_REQUESTS,
+          this.SCIM_RATE_LIMIT_WINDOW_SECONDS,
+        );
+      } catch (e) {
+        if (isWildoBackendError(e) && (e as { type?: string }).type === ErrorType.RATE_LIMIT) {
+          this._logSCIMOperation('rate_limited', { tokenId: token._id, organizationId: token.organizationId });
+          res.status(429).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+            formatSCIMError(429, 'Rate limit exceeded. Try again later.', 'tooMany')
+          );
+          return;
+        }
+        throw e;
+      }
+
+      // Attach org + scope context and EC to request for downstream handlers
+      const tokenRecord = token as Record<string, unknown>;
+      (req as SCIMAuthenticatedRequest).scimContext = {
+        organizationId: token.organizationId,
+        scopeType: (tokenRecord.scopeType as AuthScopeType) ?? AuthScopeType.ORGANIZATION,
+        scopeId: (tokenRecord.scopeId as string) ?? token.organizationId,
+        tokenId: token._id,
+        tokenDisplayName: token.displayName,
+      };
+      (req as SCIMAuthenticatedRequest).scimEc = ec;
+
+      // W5.10: Check if SCIM provisioning is enabled for this org's type
+      const scimEnabled = await this._isScimProvisioningEnabledForOrg(ec, token.organizationId);
+      if (!scimEnabled) {
+        this._logSCIMOperation('scim_disabled_for_org_type', { organizationId: token.organizationId });
+        res.status(403).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(403, 'SCIM provisioning is not enabled for this organization type', 'invalidValue')
+        );
+        return;
+      }
+
+      // Update lastUsedAt asynchronously (fire-and-forget)
+      this.servicesRegistryHandler.update(CoreResourceType.ORGANIZATION_SCIM_TOKENS, ec, token._id, { lastUsedAt: new Date() }).catch(() => {
+        // Non-fatal — don't fail the request if lastUsedAt update fails
+      });
+
+      const scimCtx = (req as SCIMAuthenticatedRequest).scimContext;
+      this._logSCIMOperation('auth_success', {
+        tokenId: token._id,
+        organizationId: token.organizationId,
+        scopeType: scimCtx.scopeType,
+        scopeId: scimCtx.scopeId,
+        method: req.method,
+        path: req.path,
+      });
+
+      next();
+    } catch (error) {
+      if (isWildoBackendError(error)) {
+        res.status(500).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(500, 'Internal authentication error')
+        );
+        return;
+      }
+      res.status(500).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+        formatSCIMError(500, 'Internal server error')
+      );
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Discovery Endpoints
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _handleServiceProviderConfig(_req: Request, res: Response): Promise<void> {
+    res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(SCIM_SERVICE_PROVIDER_CONFIG);
+  }
+
+  private async _handleSchemas(_req: Request, res: Response): Promise<void> {
+    res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json({
+      schemas: [SCIM_SCHEMAS.LIST_RESPONSE],
+      totalResults: 1,
+      startIndex: 1,
+      itemsPerPage: 1,
+      Resources: [SCIM_USER_SCHEMA_DEFINITION],
+    });
+  }
+
+  private async _handleResourceTypes(_req: Request, res: Response): Promise<void> {
+    res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json({
+      schemas: [SCIM_SCHEMAS.LIST_RESPONSE],
+      totalResults: SCIM_RESOURCE_TYPES.length,
+      startIndex: 1,
+      itemsPerPage: SCIM_RESOURCE_TYPES.length,
+      Resources: SCIM_RESOURCE_TYPES,
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // POST /scim/v2/Users — Create User
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _handleCreateUser(req: Request, res: Response): Promise<void> {
+    const ctx = this._getSCIMContext(req);
+    const body = req.body;
+
+    this._logSCIMOperation('create_user', { organizationId: ctx.organizationId, scopeType: ctx.scopeType, scopeId: ctx.scopeId, tokenId: ctx.tokenId });
+
+    const profile = this._mapSCIMBodyToProfile(body);
+    if (!profile.email) {
+      res.status(400).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+        formatSCIMError(400, 'userName (email) is required', 'invalidValue')
+      );
+      return;
+    }
+
+    try {
+      const ec = (req as SCIMAuthenticatedRequest).scimEc;
+      const orgConfig = await this._getProvisioningConfig(ec, ctx.organizationId);
+      const connection = this._buildSCIMConnection(ctx);
+
+      const result = await this.provisioningService.createOrgUser(profile, connection, orgConfig);
+
+      const userProfile = await this._getUserProfile(ec, result.user._id);
+      const baseUrl = this._getBaseUrl(req);
+      const scimUser = formatUserAsSCIM(result.user, userProfile, baseUrl, body.externalId);
+
+      this._logSCIMOperation('user_created', {
+        organizationId: ctx.organizationId,
+        scopeType: ctx.scopeType,
+        scopeId: ctx.scopeId,
+        userId: result.user._id,
+        isNew: result.isNew,
+        tokenId: ctx.tokenId,
+      });
+
+      // H8: Audit SCIM user provisioned
+      this.auditLogsService.logSCIMUserProvisioned({
+        organizationId: ctx.organizationId,
+        userId: result.user._id,
+        email: profile.email,
+        isNewUser: result.isNew,
+        provisionedVia: `scim:${ctx.tokenDisplayName}`,
+        authSource: 'scim',
+      }).catch(() => {});
+
+      res.status(201).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).set(WildoHeaderKeys.LOCATION, scimUser.meta.location).json(scimUser);
+    } catch (error) {
+      this._handleSCIMError(res, error, 'create_user');
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // GET /scim/v2/Users/:id — Get User
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _handleGetUser(req: Request, res: Response): Promise<void> {
+    const ctx = this._getSCIMContext(req);
+    const userId = req.params.id as string;
+
+    try {
+      const ec = (req as SCIMAuthenticatedRequest).scimEc;
+      const user = await this._findUserInOrg(ec, userId, ctx.organizationId);
+
+      if (!user) {
+        res.status(404).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(404, `User ${userId} not found`)
+        );
+        return;
+      }
+
+      const profile = await this._getUserProfile(ec, userId);
+      const identityLink = await this._getUserIdentityLink(ec, userId, ctx.organizationId);
+      const baseUrl = this._getBaseUrl(req);
+      const scimUser = formatUserAsSCIM(user, profile, baseUrl, identityLink?.providerUserId);
+
+      res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(scimUser);
+    } catch (error) {
+      this._handleSCIMError(res, error, 'get_user');
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // GET /scim/v2/Users — List Users (with filter + pagination)
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _handleListUsers(req: Request, res: Response): Promise<void> {
+    const ctx = this._getSCIMContext(req);
+    const filter = req.query.filter as string | undefined;
+    const startIndex = Math.max(1, parseInt(req.query.startIndex as string) || 1);
+    const count = Math.min(200, Math.max(1, parseInt(req.query.count as string) || 100));
+
+    try {
+      const ec = (req as SCIMAuthenticatedRequest).scimEc;
+      const mongoFilter = parseSCIMFilter(filter);
+
+      // Scope to organization via org member lookup
+      const orgMembers = await this.servicesRegistryHandler.list<{ userId: string }>(
+        CoreResourceType.ORGANIZATION_MEMBERS, ec, { organizationId: ctx.organizationId },
+        undefined, { paginated: false },
+      ) as { userId: string }[];
+      const memberUserIds = orgMembers.map((m) => m.userId);
+
+      if (memberUserIds.length === 0) {
+        const baseUrl = this._getBaseUrl(req);
+        res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(formatListAsSCIM([], 0, startIndex, baseUrl));
+        return;
+      }
+
+      // Combine SCIM filter with org scope
+      const combinedFilter = {
+        ...mongoFilter,
+        _id: { $in: memberUserIds },
+      };
+
+      const page = Math.max(1, Math.floor((startIndex - 1) / count) + 1);
+      const usersResult = await this.servicesRegistryHandler.list<User>(
+        CoreResourceType.USERS, ec, combinedFilter,
+        { page, limit: count },
+        { paginated: true },
+      ) as Resources_PaginatedResult<User>;
+
+      const users = (usersResult.data || []) as User[];
+      const totalCount = usersResult.pagination?.total ?? users.length;
+
+      // Hydrate profiles
+      const usersWithProfiles = await Promise.all(
+        users.map(async (user) => {
+          const profile = await this._getUserProfile(ec, user._id);
+          const identityLink = await this._getUserIdentityLink(ec, user._id, ctx.organizationId);
+          return { user, profile, externalId: identityLink?.providerUserId };
+        })
+      );
+
+      const baseUrl = this._getBaseUrl(req);
+      const response = formatListAsSCIM(usersWithProfiles, totalCount, startIndex, baseUrl);
+
+      res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(response);
+    } catch (error) {
+      this._handleSCIMError(res, error, 'list_users');
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // PUT /scim/v2/Users/:id — Replace User (full update)
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _handleReplaceUser(req: Request, res: Response): Promise<void> {
+    const ctx = this._getSCIMContext(req);
+    const userId = req.params.id as string;
+    const body = req.body;
+
+    this._logSCIMOperation('replace_user', { organizationId: ctx.organizationId, scopeType: ctx.scopeType, scopeId: ctx.scopeId, userId, tokenId: ctx.tokenId });
+
+    try {
+      const ec = (req as SCIMAuthenticatedRequest).scimEc;
+      const user = await this._findUserInOrg(ec, userId, ctx.organizationId);
+
+      if (!user) {
+        res.status(404).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(404, `User ${userId} not found`)
+        );
+        return;
+      }
+
+      const profile = this._mapSCIMBodyToProfile(body);
+      const orgConfig = await this._getProvisioningConfig(ec, ctx.organizationId);
+
+      // Update profile attributes
+      await this.provisioningService.updateOrgUser(userId, {
+        firstName: profile.firstName,
+        lastName: profile.lastName,
+        displayName: profile.displayName,
+      }, orgConfig);
+
+      // Handle active status change
+      if (body.active === false && user.status !== UserStatus.INACTIVE) {
+        await this.provisioningService.deactivateOrgUser(userId, orgConfig);
+      } else if (body.active === true && user.status !== UserStatus.ACTIVE) {
+        await this.servicesRegistryHandler.update(CoreResourceType.USERS, ec, userId, { status: UserStatus.ACTIVE });
+      }
+
+      const updatedUser = await this._findUserInOrg(ec, userId, ctx.organizationId);
+      const updatedProfile = await this._getUserProfile(ec, userId);
+      const identityLink = await this._getUserIdentityLink(ec, userId, ctx.organizationId);
+      const baseUrl = this._getBaseUrl(req);
+      const scimUser = formatUserAsSCIM(updatedUser || user, updatedProfile, baseUrl, identityLink?.providerUserId);
+
+      this._logSCIMOperation('user_replaced', { organizationId: ctx.organizationId, scopeType: ctx.scopeType, scopeId: ctx.scopeId, userId, tokenId: ctx.tokenId });
+
+      // H8: Audit SCIM user updated (replace)
+      this.auditLogsService.logSCIMUserUpdated({
+        organizationId: ctx.organizationId,
+        userId,
+        operation: 'replace',
+        updatedAttributes: ['profile', body.active !== undefined ? 'active' : undefined].filter(Boolean) as string[],
+      }).catch(() => {});
+
+      res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(scimUser);
+    } catch (error) {
+      this._handleSCIMError(res, error, 'replace_user');
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // PATCH /scim/v2/Users/:id — Partial Update (RFC 7644 §3.5.2)
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _handlePatchUser(req: Request, res: Response): Promise<void> {
+    const ctx = this._getSCIMContext(req);
+    const userId = req.params.id as string;
+    const body = req.body;
+
+    this._logSCIMOperation('patch_user', { organizationId: ctx.organizationId, scopeType: ctx.scopeType, scopeId: ctx.scopeId, userId, tokenId: ctx.tokenId });
+
+    if (!body.Operations || !Array.isArray(body.Operations)) {
+      res.status(400).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+        formatSCIMError(400, 'PATCH requires Operations array', 'invalidSyntax')
+      );
+      return;
+    }
+
+    try {
+      const ec = (req as SCIMAuthenticatedRequest).scimEc;
+      const user = await this._findUserInOrg(ec, userId, ctx.organizationId);
+
+      if (!user) {
+        res.status(404).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(404, `User ${userId} not found`)
+        );
+        return;
+      }
+
+      const orgConfig = await this._getProvisioningConfig(ec, ctx.organizationId);
+      const profileUpdates: Record<string, string> = {};
+      let statusChange: 'activate' | 'deactivate' | null = null;
+
+      for (const op of body.Operations as SCIMPatchOperation[]) {
+        const normalizedOp = op.op?.toLowerCase() as 'add' | 'remove' | 'replace';
+
+        if (normalizedOp === 'add' || normalizedOp === 'replace') {
+          if (op.path) {
+            // Single attribute update
+            this._applyPatchAttribute(op.path, op.value, profileUpdates, (s) => { statusChange = s; });
+          } else if (op.value && typeof op.value === 'object') {
+            // Bulk attribute update (no path — value is an object of attributes)
+            const valueObj = op.value as Record<string, unknown>;
+            for (const [key, val] of Object.entries(valueObj)) {
+              this._applyPatchAttribute(key, val, profileUpdates, (s) => { statusChange = s; });
+            }
+          }
+        } else if (normalizedOp === 'remove' && op.path) {
+          const scimAttr = op.path;
+          const dbField = (SCIM_USER_ATTRIBUTE_MAP as Record<string, string>)[scimAttr];
+          if (dbField && dbField !== '_active' && dbField !== 'email') {
+            profileUpdates[dbField] = '';
+          }
+        }
+      }
+
+      // Apply profile updates
+      if (Object.keys(profileUpdates).length > 0) {
+        await this.provisioningService.updateOrgUser(userId, profileUpdates as Record<string, string>, orgConfig);
+      }
+
+      // Apply status change
+      if (statusChange === 'deactivate') {
+        await this.provisioningService.deactivateOrgUser(userId, orgConfig);
+      } else if (statusChange === 'activate') {
+        await this.servicesRegistryHandler.update(CoreResourceType.USERS, ec, userId, { status: UserStatus.ACTIVE });
+      }
+
+      // Return updated user
+      const updatedUser = await this._findUserInOrg(ec, userId, ctx.organizationId);
+      const updatedProfile = await this._getUserProfile(ec, userId);
+      const identityLink = await this._getUserIdentityLink(ec, userId, ctx.organizationId);
+      const baseUrl = this._getBaseUrl(req);
+      const scimUser = formatUserAsSCIM(updatedUser || user, updatedProfile, baseUrl, identityLink?.providerUserId);
+
+      this._logSCIMOperation('user_patched', {
+        organizationId: ctx.organizationId,
+        scopeType: ctx.scopeType,
+        scopeId: ctx.scopeId,
+        userId,
+        operations: body.Operations.length,
+        tokenId: ctx.tokenId,
+      });
+
+      // H8: Audit SCIM user updated (patch)
+      const patchedAttrs = Object.keys(profileUpdates);
+      if (statusChange) patchedAttrs.push('active');
+      this.auditLogsService.logSCIMUserUpdated({
+        organizationId: ctx.organizationId,
+        userId,
+        operation: 'patch',
+        updatedAttributes: patchedAttrs,
+      }).catch(() => {});
+
+      res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(scimUser);
+    } catch (error) {
+      this._handleSCIMError(res, error, 'patch_user');
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // DELETE /scim/v2/Users/:id — Deactivate User
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _handleDeleteUser(req: Request, res: Response): Promise<void> {
+    const ctx = this._getSCIMContext(req);
+    const userId = req.params.id as string;
+
+    this._logSCIMOperation('delete_user', { organizationId: ctx.organizationId, scopeType: ctx.scopeType, scopeId: ctx.scopeId, userId, tokenId: ctx.tokenId });
+
+    try {
+      const ec = (req as SCIMAuthenticatedRequest).scimEc;
+      const user = await this._findUserInOrg(ec, userId, ctx.organizationId);
+
+      if (!user) {
+        res.status(404).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(404, `User ${userId} not found`)
+        );
+        return;
+      }
+
+      const orgConfig = await this._getProvisioningConfig(ec, ctx.organizationId);
+      await this.provisioningService.deactivateOrgUser(userId, orgConfig);
+
+      this._logSCIMOperation('user_deactivated', { organizationId: ctx.organizationId, scopeType: ctx.scopeType, scopeId: ctx.scopeId, userId, tokenId: ctx.tokenId });
+
+      // H8: Audit SCIM user deactivated
+      this.auditLogsService.logSCIMUserDeactivated({
+        organizationId: ctx.organizationId,
+        userId,
+        email: user.email,
+      }).catch(() => {});
+
+      res.status(204).end();
+    } catch (error) {
+      this._handleSCIMError(res, error, 'delete_user');
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // POST /scim/v2/Bulk — Bulk Operations (Step 21)
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _handleBulk(req: Request, res: Response): Promise<void> {
+    const ctx = this._getSCIMContext(req);
+    const body = req.body as SCIMBulkRequest;
+
+    if (!body.Operations || !Array.isArray(body.Operations)) {
+      res.status(400).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+        formatSCIMError(400, 'Bulk request requires Operations array', 'invalidSyntax')
+      );
+      return;
+    }
+
+    if (body.Operations.length > 100) {
+      res.status(413).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+        formatSCIMError(413, 'Bulk request exceeds maximum of 100 operations', 'tooMany')
+      );
+      return;
+    }
+
+    this._logSCIMOperation('bulk_start', {
+      organizationId: ctx.organizationId,
+      scopeType: ctx.scopeType,
+      scopeId: ctx.scopeId,
+      operationCount: body.Operations.length,
+      tokenId: ctx.tokenId,
+    });
+
+    const results: SCIMBulkOperationResponse[] = [];
+    let errorCount = 0;
+    const failOnErrors = body.failOnErrors || 0;
+
+    for (const op of body.Operations) {
+      if (failOnErrors > 0 && errorCount >= failOnErrors) {
+        results.push({
+          method: op.method,
+          bulkId: op.bulkId,
+          status: '412',
+          response: formatSCIMError(412, 'Processing stopped due to failOnErrors threshold'),
+        });
+        continue;
+      }
+
+      try {
+        const result = await this._executeBulkOperation(op, ctx, req);
+        results.push(result);
+        if (parseInt(result.status) >= 400) {
+          errorCount++;
+        }
+      } catch {
+        errorCount++;
+        results.push({
+          method: op.method,
+          bulkId: op.bulkId,
+          status: '500',
+          response: formatSCIMError(500, 'Internal error processing bulk operation'),
+        });
+      }
+    }
+
+    this._logSCIMOperation('bulk_complete', {
+      organizationId: ctx.organizationId,
+      scopeType: ctx.scopeType,
+      scopeId: ctx.scopeId,
+      totalOperations: body.Operations.length,
+      errors: errorCount,
+      tokenId: ctx.tokenId,
+    });
+
+    res.set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json({
+      schemas: [SCIM_SCHEMAS.BULK_RESPONSE],
+      Operations: results,
+    });
+  }
+
+  private async _executeBulkOperation(
+    op: SCIMBulkRequest['Operations'][0],
+    ctx: SCIMRequestContext,
+    req: Request,
+  ): Promise<SCIMBulkOperationResponse> {
+    const pathMatch = op.path?.match(/\/Users(?:\/(.+))?$/);
+    if (!pathMatch) {
+      return { method: op.method, bulkId: op.bulkId, status: '400', response: formatSCIMError(400, 'Invalid path') };
+    }
+    const userId = pathMatch[1];
+    const ec = (req as SCIMAuthenticatedRequest).scimEc;
+    const orgConfig = await this._getProvisioningConfig(ec, ctx.organizationId);
+    const baseUrl = this._getBaseUrl(req);
+
+    switch (op.method) {
+      case 'POST': {
+        if (!op.data) {
+          return { method: 'POST', bulkId: op.bulkId, status: '400', response: formatSCIMError(400, 'Missing data for POST') };
+        }
+        const profile = this._mapSCIMBodyToProfile(op.data);
+        if (!profile.email) {
+          return { method: 'POST', bulkId: op.bulkId, status: '400', response: formatSCIMError(400, 'userName required') };
+        }
+        const connection = this._buildSCIMConnection(ctx);
+        const result = await this.provisioningService.createOrgUser(profile, connection, orgConfig);
+
+        // H8: Audit bulk SCIM user provisioned
+        this.auditLogsService.logSCIMUserProvisioned({
+          organizationId: ctx.organizationId,
+          userId: result.user._id,
+          email: profile.email,
+          isNewUser: result.isNew,
+          provisionedVia: `scim:bulk:${ctx.tokenDisplayName}`,
+          authSource: 'scim',
+        }).catch(() => {});
+
+        return {
+          method: 'POST',
+          bulkId: op.bulkId,
+          location: `${baseUrl}/Users/${result.user._id}`,
+          status: '201',
+        };
+      }
+
+      case 'PUT': {
+        if (!userId || !op.data) {
+          return { method: 'PUT', bulkId: op.bulkId, status: '400', response: formatSCIMError(400, 'User ID and data required') };
+        }
+        const user = await this._findUserInOrg(ec, userId, ctx.organizationId);
+        if (!user) {
+          return { method: 'PUT', bulkId: op.bulkId, status: '404', response: formatSCIMError(404, `User ${userId} not found`) };
+        }
+        const putProfile = this._mapSCIMBodyToProfile(op.data);
+        await this.provisioningService.updateOrgUser(userId, {
+          firstName: putProfile.firstName,
+          lastName: putProfile.lastName,
+          displayName: putProfile.displayName,
+        }, orgConfig);
+
+        // H8: Audit bulk SCIM user updated (replace)
+        this.auditLogsService.logSCIMUserUpdated({
+          organizationId: ctx.organizationId,
+          userId,
+          operation: 'replace',
+          updatedAttributes: ['profile'],
+        }).catch(() => {});
+
+        return { method: 'PUT', bulkId: op.bulkId, location: `${baseUrl}/Users/${userId}`, status: '200' };
+      }
+
+      case 'PATCH': {
+        if (!userId || !op.data) {
+          return { method: 'PATCH', bulkId: op.bulkId, status: '400', response: formatSCIMError(400, 'User ID and data required') };
+        }
+        const patchUser = await this._findUserInOrg(ec, userId, ctx.organizationId);
+        if (!patchUser) {
+          return { method: 'PATCH', bulkId: op.bulkId, status: '404', response: formatSCIMError(404, `User ${userId} not found`) };
+        }
+        // Simplified: apply operations from data
+        const operations = (op.data as Record<string, unknown>).Operations as SCIMPatchOperation[] | undefined;
+        const bulkPatchedAttrs: string[] = [];
+        if (operations) {
+          const patchProfileUpdates: Record<string, string> = {};
+          let patchStatusChange: 'activate' | 'deactivate' | null = null;
+          for (const patchOp of operations) {
+            const normalizedOp = patchOp.op?.toLowerCase() as 'add' | 'remove' | 'replace';
+            if (normalizedOp === 'add' || normalizedOp === 'replace') {
+              if (patchOp.path) {
+                this._applyPatchAttribute(patchOp.path, patchOp.value, patchProfileUpdates, (s) => { patchStatusChange = s; });
+              }
+            }
+          }
+          if (Object.keys(patchProfileUpdates).length > 0) {
+            await this.provisioningService.updateOrgUser(userId, patchProfileUpdates, orgConfig);
+          }
+          if (patchStatusChange === 'deactivate') {
+            await this.provisioningService.deactivateOrgUser(userId, orgConfig);
+          }
+          bulkPatchedAttrs.push(...Object.keys(patchProfileUpdates));
+          if (patchStatusChange) bulkPatchedAttrs.push('active');
+        }
+
+        // H8: Audit bulk SCIM user updated (patch)
+        this.auditLogsService.logSCIMUserUpdated({
+          organizationId: ctx.organizationId,
+          userId,
+          operation: 'patch',
+          updatedAttributes: bulkPatchedAttrs,
+        }).catch(() => {});
+
+        return { method: 'PATCH', bulkId: op.bulkId, location: `${baseUrl}/Users/${userId}`, status: '200' };
+      }
+
+      case 'DELETE': {
+        if (!userId) {
+          return { method: 'DELETE', bulkId: op.bulkId, status: '400', response: formatSCIMError(400, 'User ID required') };
+        }
+        const deleteUser = await this._findUserInOrg(ec, userId, ctx.organizationId);
+        if (!deleteUser) {
+          return { method: 'DELETE', bulkId: op.bulkId, status: '404', response: formatSCIMError(404, `User ${userId} not found`) };
+        }
+        await this.provisioningService.deactivateOrgUser(userId, orgConfig);
+
+        // H8: Audit bulk SCIM user deactivated
+        this.auditLogsService.logSCIMUserDeactivated({
+          organizationId: ctx.organizationId,
+          userId,
+          email: deleteUser.email,
+        }).catch(() => {});
+
+        return { method: 'DELETE', bulkId: op.bulkId, status: '204' };
+      }
+
+      default:
+        return { method: op.method, bulkId: op.bulkId, status: '400', response: formatSCIMError(400, `Unsupported method: ${op.method}`) };
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // PATCH Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  private _applyPatchAttribute(
+    path: string,
+    value: unknown,
+    profileUpdates: Record<string, string>,
+    onStatusChange: (change: 'activate' | 'deactivate') => void,
+  ): void {
+    const attrMap = SCIM_USER_ATTRIBUTE_MAP as Record<string, string>;
+    const dbField = attrMap[path];
+
+    if (path === 'active' || dbField === '_active') {
+      const isActive = value === true || value === 'true';
+      onStatusChange(isActive ? 'activate' : 'deactivate');
+      return;
+    }
+
+    if (dbField && dbField !== 'email') {
+      profileUpdates[dbField] = String(value ?? '');
+    }
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // SCIM Body → NormalizedUserProfile
+  // ═══════════════════════════════════════════════════════════════
+
+  private _mapSCIMBodyToProfile(body: Record<string, unknown>): NormalizedUserProfile {
+    const userName = body.userName as string | undefined;
+    const name = body.name as Record<string, string> | undefined;
+    const emails = body.emails as Array<{ value: string; primary?: boolean }> | undefined;
+
+    // Determine email: prefer userName, then primary email, then first email
+    let email = userName || '';
+    if (!email && emails?.length) {
+      const primary = emails.find(e => e.primary);
+      email = primary?.value || emails[0]?.value || '';
+    }
+
+    return {
+      providerUserId: (body.externalId as string) || '',
+      email: email.toLowerCase(),
+      emailVerified: true, // SCIM-provisioned users are trusted
+      firstName: name?.givenName,
+      lastName: name?.familyName,
+      displayName: (body.displayName as string) || undefined,
+      rawClaims: body,
+    };
+  }
+
+  private _buildSCIMConnection(ctx: SCIMRequestContext): ProvisioningConnectionContext {
+    return {
+      source: 'scim',
+      providerRef: 'scim',
+      displayName: 'SCIM Directory Provisioning',
+      organization: {
+        organizationId: ctx.organizationId,
+        connectionId: `scim:${ctx.tokenId}`,
+        allowedDomains: [],
+        autoCreateUsers: true,
+        autoVerifyEmail: true,
+      },
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // User Lookup Helpers
+  // ═══════════════════════════════════════════════════════════════
+
+  private async _findUserInOrg(ec: ExecutionContext<any>, userId: string, organizationId: string): Promise<User | null> {
+    try {
+      // Verify user exists
+      const user = await this.servicesRegistryHandler.read<User>(CoreResourceType.USERS, ec, { _id: userId });
+      if (!user) return null;
+
+      const membership = await this.servicesRegistryHandler.read(CoreResourceType.ORGANIZATION_MEMBERS, ec, { userId, organizationId });
+      if (!membership) return null;
+
+      return user;
+    } catch {
+      return null;
+    }
+  }
+
+  private async _getUserProfile(ec: ExecutionContext<any>, userId: string): Promise<{ firstName?: string; lastName?: string; displayName?: string; avatarUrl?: string } | null> {
+    try {
+      const profile = await this.servicesRegistryHandler.read(CoreResourceType.USER_PROFILES, ec, { userId });
+      return profile as { firstName?: string; lastName?: string; displayName?: string; avatarUrl?: string } | null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async _getUserIdentityLink(ec: ExecutionContext<any>, userId: string, organizationId: string): Promise<{ providerUserId?: string } | null> {
+    try {
+      const link = await this.servicesRegistryHandler.read(CoreResourceType.USER_IDENTITY_LINKS, ec, {
+        userId,
+        connectionType: 'enterprise',
+        organizationId,
+      });
+      return link as { providerUserId?: string } | null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async _getProvisioningConfig(ec: ExecutionContext<any>, organizationId: string): Promise<EnterpriseProvisioningConfig> {
+    let allowedDomains: string[] = [];
+    try {
+      const ssoConfig = await this.orgConfigService.loadSSOConfig(ec, AuthScopeType.ORGANIZATION, organizationId);
+      if (ssoConfig) {
+        // Only include domains that have passed DNS verification (H4)
+        allowedDomains = ssoConfig.domains.verifiedDomains.filter(
+          d => ssoConfig.domains.domainVerificationStatus[d] === 'verified',
+        );
+      }
+    } catch {
+      this.logDebug('Failed to load org SSO config for SCIM provisioning (non-fatal)', { organizationId });
+    }
+
+    return {
+      organizationId,
+      autoCreateUsers: true,
+      autoVerifyEmail: true,
+      allowedDomains,
+    };
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Structured Logging (Step 21)
+  // ═══════════════════════════════════════════════════════════════
+
+  private _logSCIMOperation(operation: string, context: Record<string, unknown>): void {
+    this.logDebug(`SCIM: ${operation}`, {
+      scimOperation: operation,
+      ...context,
+    });
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Error Handling
+  // ═══════════════════════════════════════════════════════════════
+
+  private _handleSCIMError(res: Response, error: unknown, operation: string): void {
+    this._logSCIMOperation(`${operation}_error`, { error: error instanceof Error ? error.message : String(error) });
+
+    if (isWildoBackendError(error)) {
+      const wildoError = error as { statusCode?: number; type?: string; message?: string };
+      const status = wildoError.statusCode || 500;
+
+      // Map common errors to SCIM-specific responses
+      if (status === 409 || wildoError.type === 'uniqueness') {
+        res.status(409).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(409, 'User already exists', 'uniqueness')
+        );
+        return;
+      }
+      if (status === 404) {
+        res.status(404).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+          formatSCIMError(404, wildoError.message || 'Resource not found')
+        );
+        return;
+      }
+
+      res.status(status).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+        formatSCIMError(status, wildoError.message || 'Server error')
+      );
+      return;
+    }
+
+    res.status(500).set(WildoHeaderKeys.CONTENT_TYPE, SCIM_CONTENT_TYPE).json(
+      formatSCIMError(500, 'Internal server error')
+    );
+  }
+
+  // ═══════════════════════════════════════════════════════════════
+  // Utilities
+  // ═══════════════════════════════════════════════════════════════
+
+  private _hashToken(plainToken: string): string {
+    return createHash('sha256').update(plainToken).digest('hex');
+  }
+
+  private async _isScimProvisioningEnabledForOrg(ec: ExecutionContext<any>, organizationId: string): Promise<boolean> {
+    if (!this.appConfigService.isInitialized()) return true;
+
+    type OrgTypeWithScim = { scimProvisioning?: { enabled: boolean; syncFrequencyHours?: number } };
+    const organizationTypes = (this.appConfigService.config as { organizationTypes?: Record<string, OrgTypeWithScim> })?.organizationTypes;
+
+    try {
+      return await isScimProvisioningEnabledForOrg(ec, {
+        organizationId,
+        organizationTypes,
+        servicesRegistryHandler: this.servicesRegistryHandler,
+      });
+    } catch {
+      return true;
+    }
+  }
+
+  private _getSCIMContext(req: Request): SCIMRequestContext {
+    return (req as SCIMAuthenticatedRequest).scimContext;
+  }
+
+  private _getBaseUrl(req: Request): string {
+    const proto = req.headers[WildoHeaderKeys.FORWARDED_PROTO];
+    const protocol = (Array.isArray(proto) ? proto[0] : proto) || req.protocol || 'https';
+    const h = req.headers[WildoHeaderKeys.FORWARDED_HOST] || req.headers.host;
+    const host = (Array.isArray(h) ? h[0] : h) || 'localhost';
+    return `${protocol}://${host}/api/v1/scim/v2`;
+  }
+
+  private async _getInternalExecutionContext(): Promise<ExecutionContext<any>> {
+    return this.authEcFactory.createForSystemAuthOperation(this.authEcFactory.getUsersCreateOperationPath());
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Request Context Types
+// ═══════════════════════════════════════════════════════════════
+
+interface SCIMRequestContext {
+  organizationId: string;
+  scopeType: AuthScopeType;
+  scopeId: string;
+  tokenId: string;
+  tokenDisplayName: string;
+}
+
+interface SCIMAuthenticatedRequest extends Request {
+  scimContext: SCIMRequestContext;
+  scimEc: ExecutionContext<any>;
+}