@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/runtime/services/execution-context-creator.backend.service.js

@@ -0,0 +1,1525 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Container, inject, injectable } from 'inversify';
+import 'reflect-metadata';
+import { CORE_APP_ROLES, CoreResourceType, OrganizationMemberStatus, ResourcePrimaryScope, WildoHeaderKeys } from '@wildo-ai/saas-models';
+import { ApiKeyStatus, CoreResourceOperation, ErrorCustomMessageReference, ErrorType, ExecutionContext_ExecutionType, ResourceOperationVariantType, ResourcesConfig_OperationPathUtils, TokenAuthenticationPolicy, UserStatus, isWildoBackendError } from '@wildo-ai/saas-models';
+// =====================================================
+// Socket Authentication Types (reuses existing ExecutionContext types)
+// =====================================================
+import { LoggerService } from '../../monitoring/logger/services/logger.service.js';
+import { ExecutionContext } from '../../runtime/models/execution-context.backend.schemas.js';
+import { AppConfigurationService } from '../../config/services/app-configuration.backend.service.js';
+import { JwtClaim_App_Auth_Schema } from '../../security/authentications/models/authentications.backend.schemas.js';
+import { JwtBackendService } from '../../security/jwt/services/jwt.backend.service.js';
+import { RepositoriesRegistryHandlerBackendService } from '../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
+import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { ResourcesRegistryBackendService } from '../../resources/services/resources-registry.backend.service.js';
+import { ExecutionContextHandlerBackendService } from './execution-context-handler.backend.service.js';
+import { ConsumableTokenBackendService } from '../../security/consumable-tokens/services/consumable-token.backend.service.js';
+import { RedisService } from '../../databases/services/redis.service.js';
+import { AUTH_REDIS_KEYS } from '../../security/authentications/models/auth-constants.backend.js';
+let ExecutionContextCreatorBackendService = class ExecutionContextCreatorBackendService {
+    logger;
+    appConfigService;
+    errorBuilder;
+    executionContextHandlerService;
+    jwtService;
+    resourcesRegistryService;
+    repositoriesRegistry;
+    consumableTokenService;
+    redisService;
+    container;
+    logDebug;
+    constructor(logger, appConfigService, errorBuilder, executionContextHandlerService, jwtService, resourcesRegistryService, repositoriesRegistry, consumableTokenService, redisService, container) {
+        this.logger = logger;
+        this.appConfigService = appConfigService;
+        this.errorBuilder = errorBuilder;
+        this.executionContextHandlerService = executionContextHandlerService;
+        this.jwtService = jwtService;
+        this.resourcesRegistryService = resourcesRegistryService;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.consumableTokenService = consumableTokenService;
+        this.redisService = redisService;
+        this.container = container;
+        this.logDebug = this.logger.debugByType('ExecutionContextCreator');
+        this.logger.setDebugTypeLogging('ExecutionContextCreator', false);
+    }
+    /**
+     * Anonymous session handling eventually calls back into the services registry,
+     * so we resolve it lazily to avoid a hard DI cycle during backend startup.
+     */
+    getAnonymousSessionService() {
+        return this.container.get(SAAS_SERVICE_TYPES.AnonymousSessionService);
+    }
+    createInternalSystemRoles() {
+        return [
+            {
+                roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                relatedPrimaryScope: ResourcePrimaryScope.APPLICATION,
+            }
+        ];
+    }
+    async populateApplicationIdIfNeeded(executionContext, forcePopulate = false) {
+        // Check if applicationId is already set
+        const applicationIdUndefinedOrNull = executionContext.initiatorIds?.applicationId === undefined ||
+            executionContext.initiatorIds?.applicationId === null;
+        // Populate if needed
+        const needsPopulation = (executionContext.operation.resourcePrimaryScope === ResourcePrimaryScope.APPLICATION &&
+            applicationIdUndefinedOrNull) || forcePopulate;
+        if (!needsPopulation) {
+            return;
+        }
+        // initiatorIds should always exist (validated in ExecutionContext constructor)
+        if (!executionContext.initiatorIds) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'ExecutionContext.initiatorIds is null - this should not happen after validation. Check ExecutionContext construction.'
+                }
+            });
+        }
+        // Fetch APPLICATION record
+        const appRepository = this.repositoriesRegistry.getRepository(CoreResourceType.APPLICATION);
+        const currentApplication = await appRepository.read(executionContext, {}); // only one application for the whole applications
+        if (!currentApplication) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'No APPLICATION record found in database. The application must be seeded with an APPLICATION record during initialization.'
+                }
+            });
+        }
+        executionContext.initiatorIds.applicationId = currentApplication._id;
+    }
+    async getApplicationId() {
+        const appReadOp = this.resourcesRegistryService.getOperationPathDefault(CoreResourceType.APPLICATION, CoreResourceOperation.READ);
+        const execCtx = await this.createForInternalOperation({
+            operation: appReadOp,
+            contextResourcesFieldIdentifier: new Map(),
+            initiatorIds: null, // Null for internal operations
+            initiatorRoles: [{ roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }],
+        });
+        const appRepository = this.repositoriesRegistry.getRepository(CoreResourceType.APPLICATION);
+        const currentApplication = await appRepository.read(execCtx, {});
+        if (!currentApplication) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'No APPLICATION record found in database. The application must be seeded with an APPLICATION record during initialization.'
+                }
+            });
+        }
+        return currentApplication._id;
+    }
+    async createExecutionContext(params) {
+        this.logDebug('Creating ExecutionContext', { executionType: params.executionType, operationIdentifier: params.operation.operationIdentifier, resourceIdentifier: params.operation.resourceIdentifier });
+        const operation = this.resourcesRegistryService.getOperationFromPath(params.operation);
+        await this.executionContextHandlerService.validateOperation(operation);
+        const executionContext = new ExecutionContext(operation, params.executionType, params.contextResourcesFieldIdentifier, params.initiatorIds ?? {}, // Use nullish coalescing - handles both null and undefined
+        params.initiatorRoles ?? [], params.relationshipContexts ?? []);
+        if (operation.resourcePrimaryScope === ResourcePrimaryScope.APPLICATION) {
+            await this.populateApplicationIdIfNeeded(executionContext);
+        }
+        this.logDebug('ExecutionContext created successfully', { executionType: executionContext.executionType, contextResourcesCount: executionContext.getContextResourceIds().size, hasExecutionContext_InitiatorIds: !!executionContext.initiatorIds, initiatorRolesCount: executionContext.initiatorRoles.length });
+        return executionContext;
+    }
+    async createForInternalOperation(params) {
+        return this.createExecutionContext({
+            ...params,
+            executionType: ExecutionContext_ExecutionType.INTERNALLY_INITIATED_REQUEST,
+        });
+    }
+    /**
+     * Create an internal execution context for a custom batch definition.
+     *
+     * Custom batches are authored outside the resource-operation registry, so some
+     * of them point at semantic operation identifiers that do not exist as concrete
+     * `CRON_JOB` / `BATCH_JOB` registry variants. We still bootstrap through a real
+     * registered operation for validation and creator-side initialization, then
+     * correct the operation to the custom batch's synthetic identity.
+     */
+    async createForInternalCustomBatch(params) {
+        const { batchOperationContext, contextResourcesFieldIdentifier, relationshipContexts } = params;
+        const resourceConfig = this.resourcesRegistryService
+            .getResourcesRegistry()
+            .resourceConfigurations[batchOperationContext.resourceIdentifier];
+        if (!resourceConfig) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: `Custom batch '${batchOperationContext.operationIdentifier}' targets unknown resource '${batchOperationContext.resourceIdentifier}'`,
+                    resourceIdentifier: batchOperationContext.resourceIdentifier,
+                    operationIdentifier: batchOperationContext.operationIdentifier,
+                }
+            });
+        }
+        const expectedVariantType = batchOperationContext.cronJobExpression
+            ? ResourceOperationVariantType.CRON_JOB
+            : ResourceOperationVariantType.BATCH_JOB;
+        const exactVariantMatches = resourceConfig.operations.filter((operation) => operation.operationIdentifier === batchOperationContext.operationIdentifier
+            && operation.variantType === expectedVariantType);
+        if (exactVariantMatches.length > 1) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: `Custom batch operation resolution is ambiguous for '${batchOperationContext.resourceIdentifier}.${batchOperationContext.operationIdentifier}'`,
+                    resourceIdentifier: batchOperationContext.resourceIdentifier,
+                    operationIdentifier: batchOperationContext.operationIdentifier,
+                    expectedVariantType,
+                    matchedCount: exactVariantMatches.length,
+                }
+            });
+        }
+        const bootstrapOperation = exactVariantMatches[0]
+            ?? this.resolveBootstrapOperationForCustomBatch(resourceConfig, batchOperationContext.operationIdentifier);
+        const bootstrapContext = await this.createForInternalOperation({
+            operation: ResourcesConfig_OperationPathUtils.extractOperationPath(bootstrapOperation),
+            contextResourcesFieldIdentifier,
+            initiatorIds: null,
+            initiatorRoles: this.createInternalSystemRoles(),
+            relationshipContexts,
+        });
+        const syntheticBatchOperation = expectedVariantType === ResourceOperationVariantType.CRON_JOB
+            ? {
+                ...bootstrapOperation,
+                operationIdentifier: batchOperationContext.operationIdentifier,
+                variantType: ResourceOperationVariantType.CRON_JOB,
+                cronExpression: batchOperationContext.cronJobExpression ?? '',
+                isOperationDefault: false,
+                roles: [],
+            }
+            : {
+                ...bootstrapOperation,
+                operationIdentifier: batchOperationContext.operationIdentifier,
+                variantType: ResourceOperationVariantType.BATCH_JOB,
+                isOperationDefault: false,
+                roles: [],
+            };
+        return bootstrapContext.withOperation(syntheticBatchOperation);
+    }
+    async createForPublicOperation(params) {
+        return this.createExecutionContext({
+            ...params,
+            executionType: ExecutionContext_ExecutionType.PUBLIC_EXECUTION,
+        });
+    }
+    /**
+     * Create internal execution context for system operations (no specific operation context needed).
+     * Convenience method for queue services, tracking, and other internal operations.
+     *
+     * Uses a generic "system" operation that grants full access within the application scope.
+     * This is used by queue services for internal DB operations that don't have a specific user context.
+     */
+    async createForInternalSystemOperation() {
+        // Use a generic internal operation for system-level access
+        const operationPath = this.resourcesRegistryService.getOperationPathDefault(CoreResourceType.APPLICATION, CoreResourceOperation.READ);
+        const systemOperation = this.resourcesRegistryService.getOperationFromPath(operationPath);
+        return this.createForInternalOperation({
+            operation: systemOperation,
+            contextResourcesFieldIdentifier: new Map(),
+            initiatorIds: null, // Null for internal operations
+            initiatorRoles: this.createInternalSystemRoles(),
+            relationshipContexts: [],
+        });
+    }
+    resolveBootstrapOperationForCustomBatch(resourceConfig, operationIdentifier) {
+        const sameIdentifierOperation = resourceConfig.operations.find((operation) => operation.operationIdentifier === operationIdentifier);
+        if (sameIdentifierOperation) {
+            return sameIdentifierOperation;
+        }
+        const defaultReadOperation = resourceConfig.operations.find((operation) => operation.operationIdentifier === CoreResourceOperation.READ && operation.isOperationDefault);
+        if (defaultReadOperation) {
+            return defaultReadOperation;
+        }
+        const firstDefaultOperation = resourceConfig.operations.find((operation) => operation.isOperationDefault);
+        if (firstDefaultOperation) {
+            return firstDefaultOperation;
+        }
+        const fallbackOperation = resourceConfig.operations[0];
+        if (fallbackOperation) {
+            return fallbackOperation;
+        }
+        throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+                message: `Custom batch '${operationIdentifier}' cannot bootstrap an execution context because resource '${resourceConfig.resourceIdentifier}' exposes no operations`,
+                resourceIdentifier: resourceConfig.resourceIdentifier,
+                operationIdentifier,
+            }
+        });
+    }
+    /**
+     * Create an ExecutionContext for a webhook callback.
+     *
+     * Webhook events are not tied to a single resource operation — a single event
+     * (e.g., invoice.paid) may trigger multiple operations (update subscription, create invoice record, adjust credits).
+     * Uses APPLICATION.READ as a generic "entry" operation for the pipeline.
+     * Capability handlers create per-resource sub-contexts via createForSubCall() for specific operations.
+     *
+     * @param resolvedScope - Scope identifiers resolved from the webhook event payload
+     * @param parsedEvent - The parsed webhook event (for providerRef metadata)
+     */
+    async createForWebhookCallback(resolvedScope, parsedEvent) {
+        // Use a generic APPLICATION.READ operation as the entry point
+        const operationPath = this.resourcesRegistryService.getOperationPathDefault(CoreResourceType.APPLICATION, CoreResourceOperation.READ);
+        const operation = this.resourcesRegistryService.getOperationFromPath(operationPath);
+        // Map all resolved scope fields to initiatorIds
+        const initiatorIds = {
+            applicationId: resolvedScope.applicationId,
+            organizationId: resolvedScope.organizationId,
+            userId: resolvedScope.userId,
+            webhookProviderId: parsedEvent.providerRef,
+        };
+        const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.WEBHOOK_CALLBACK, new Map(), initiatorIds, [], // No roles — webhooks are trusted after signature verification
+        []);
+        await this.populateApplicationIdIfNeeded(executionContext);
+        return executionContext;
+    }
+    /**
+     * Reconstruct ExecutionContext from serialized data (for queue workers).
+     *
+     * This method:
+     * 1. Deserializes the operationPathJson to get the OperationPath
+     * 2. Gets the full Operation from the registry
+     * 3. Reconstructs ExecutionContext with the original execution type, initiator IDs, and roles
+     *
+     * @param executionContextJson - Serialized execution context data (optional for CUSTOM_BATCH/SCHEDULED_CRON)
+     * @param operationPathJson - Serialized operation path from JobPayload (optional for CUSTOM_BATCH)
+     * @returns Reconstructed ExecutionContext ready for execution
+     */
+    async reconstructFromSerializedData(executionContextJson, operationPathJson) {
+        // Import dynamically to avoid circular dependencies
+        const { ResourceSerializationUtils } = await import('@wildo-ai/saas-models');
+        // If no serialized data, return internal system context
+        if (!executionContextJson || !operationPathJson) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.JOB_EXECUTION_CONTEXT_INVALID,
+                context: { message: 'Cannot reconstruct ExecutionContext from undefined serialized data' },
+            });
+        }
+        // Deserialize the data
+        const ctxData = ResourceSerializationUtils.deserializeExecutionContextData(executionContextJson);
+        const operationPath = ResourceSerializationUtils.deserializeOperationPath(operationPathJson);
+        // Get the full operation from registry
+        const operation = this.resourcesRegistryService.getOperationFromPath(operationPath);
+        // Convert contextResourcesFieldIdentifier from plain object to Map
+        // Note: The schema accepts Map<string, string> but the actual ExecutionContext uses Map<ResourceFieldIdentifier, string | string[]>
+        // We convert arrays to comma-separated strings for factory param compatibility
+        const contextResourcesMap = new Map();
+        if (ctxData.contextResourcesFieldIdentifier) {
+            Object.entries(ctxData.contextResourcesFieldIdentifier).forEach(([key, value]) => {
+                // Convert arrays to first value (most common case) or comma-separated for compatibility
+                const stringValue = Array.isArray(value) ? value[0] ?? '' : value;
+                contextResourcesMap.set(key, stringValue);
+            });
+        }
+        // Convert relationshipContexts
+        const relationshipContexts = ctxData.relationshipContexts || [];
+        // Reconstruct ExecutionContext based on original execution type
+        if (ctxData.executionType === ExecutionContext_ExecutionType.INTERNALLY_INITIATED_REQUEST) {
+            return this.createForInternalOperation({
+                operation,
+                contextResourcesFieldIdentifier: contextResourcesMap,
+                initiatorIds: ctxData.initiatorIds,
+                initiatorRoles: ctxData.initiatorRoles,
+                relationshipContexts,
+            });
+        }
+        else if (ctxData.executionType === ExecutionContext_ExecutionType.PUBLIC_EXECUTION) {
+            return this.createForPublicOperation({
+                operation,
+                contextResourcesFieldIdentifier: contextResourcesMap,
+                initiatorIds: ctxData.initiatorIds,
+                initiatorRoles: ctxData.initiatorRoles,
+                relationshipContexts,
+            });
+        }
+        else if (ctxData.executionType === ExecutionContext_ExecutionType.ANONYMOUS_SESSION) {
+            // W7.3a: Reconstruct anonymous session context with anonymousUserId from serialized initiatorIds
+            return this.createExecutionContext({
+                executionType: ExecutionContext_ExecutionType.ANONYMOUS_SESSION,
+                operation,
+                contextResourcesFieldIdentifier: contextResourcesMap,
+                initiatorIds: ctxData.initiatorIds,
+                initiatorRoles: ctxData.initiatorRoles ?? [{ roles: [CORE_APP_ROLES.APP_ANONYMOUS], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }],
+                relationshipContexts,
+            });
+        }
+        else if (ctxData.executionType === ExecutionContext_ExecutionType.WEBHOOK_CALLBACK) {
+            // Webhook callback — reconstruct with the resolved scope from initiatorIds
+            return this.createForWebhookCallback({
+                applicationId: ctxData.initiatorIds?.applicationId,
+                organizationId: ctxData.initiatorIds?.organizationId,
+                userId: ctxData.initiatorIds?.userId,
+            }, {
+                providerRef: ctxData.initiatorIds?.webhookProviderId ?? 'unknown',
+                endpointKey: 'reconstructed',
+                eventId: 'reconstructed',
+                eventType: 'reconstructed',
+            });
+        }
+        else {
+            // USER_REQUEST, API_KEY, etc. - use createExecutionContext
+            return this.createExecutionContext({
+                executionType: ctxData.executionType,
+                operation,
+                contextResourcesFieldIdentifier: contextResourcesMap,
+                initiatorIds: ctxData.initiatorIds,
+                initiatorRoles: ctxData.initiatorRoles,
+                relationshipContexts,
+            });
+        }
+    }
+    /**
+     * Create a new ExecutionContext for an internal sub-call.
+     * Inherits security context from parent but uses the correct operation for the sub-resource.
+     *
+     * @param parentContext - The parent execution context to inherit from
+     * @param resourceType - The resource type for the sub-call
+     * @param operationIdentifier - The operation (READ, LIST, etc.)
+     * @param options - ServiceOptions with variantKey, dataMode
+     * @param resourceId - Optional resource ID for single-resource operations (undefined for LIST)
+     * @param relationshipContext - Optional relationship context tracking how we got to this sub-resource.
+     *                             Should be provided when there's an FK relationship between parent and sub-resource.
+     *                             Example: { resourceType: 'USER_SELF', relationshipField: 'userId', resourceId: '...' }
+     */
+    async createForSubCall(parentContext, resourceType, operationIdentifier, options, resourceId, relationshipContext) {
+        // 0. Validate parent context exists
+        if (!parentContext) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: 'Parent context is required for sub-calls. Use createForInternalOperation for top-level internal operations.'
+                }
+            });
+        }
+        // 1. Cycle detection and depth check
+        const currentDepth = parentContext.getSubCallDepth();
+        const MAX_DEPTH = 15;
+        if (currentDepth >= MAX_DEPTH) {
+            throw this.errorBuilder.buildError(ErrorType.INTERNAL, parentContext, {
+                customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                context: {
+                    message: `Max sub-call depth (${MAX_DEPTH}) exceeded. Possible circular dependency.`,
+                    resourceType,
+                    operationIdentifier,
+                    currentDepth
+                }
+            });
+        }
+        // 2a. Instance-level cycle detection (UPDATE/DELETE — same resourceType:resourceId visited before)
+        if (resourceId) {
+            const visitKey = `${resourceType}:${resourceId}`;
+            if (parentContext.hasVisitedResource(visitKey)) {
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, parentContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        message: `Circular dependency detected: ${visitKey} already visited in call chain.`,
+                        visitKey,
+                        resourceType,
+                        operationIdentifier
+                    }
+                });
+            }
+        }
+        // 2b. Type-level cycle detection for nested CREATE.
+        // CREATE has no resourceId, so the instance-level check above is skipped.
+        // Instead, detect schema-level cycles by checking if the child resource type
+        // already appears as a parent in the relationship context chain.
+        // Example: A→B→A cycle would have relationshipContexts=[{resourceType:A},{resourceType:B}]
+        // and we're about to create another A — the chain proves a cycle.
+        //
+        // Performance: O(n) where n = relationship chain depth, typically <5. Negligible.
+        if (operationIdentifier === CoreResourceOperation.CREATE && relationshipContext) {
+            const ancestorResourceTypes = parentContext.relationshipContexts.map(rc => rc.resourceType);
+            if (ancestorResourceTypes.includes(resourceType)) {
+                const chainDescription = [...ancestorResourceTypes, resourceType].join(' → ');
+                throw this.errorBuilder.buildError(ErrorType.INTERNAL, parentContext, {
+                    customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+                    context: {
+                        message: `Circular dependency in nested CREATE: resource type "${resourceType}" already appears as an ancestor in the relationship chain. Chain: ${chainDescription}`,
+                        resourceType,
+                        operationIdentifier,
+                        chainDescription,
+                    }
+                });
+            }
+        }
+        // 3. Get the correct operation path (with fallback to default if variant not found)
+        let operationPath;
+        if (options?.variantKey) {
+            try {
+                operationPath = this.resourcesRegistryService.getOperationPath(resourceType, operationIdentifier, options.variantKey);
+            }
+            catch {
+                // Fallback to default variant with warning log
+                this.logger.warn(`Variant '${options.variantKey}' not found for ${resourceType}.${operationIdentifier}, falling back to default`);
+                operationPath = this.resourcesRegistryService.getOperationPathDefault(resourceType, operationIdentifier);
+            }
+        }
+        else {
+            operationPath = this.resourcesRegistryService.getOperationPathDefault(resourceType, operationIdentifier);
+        }
+        // 4. Get the operation configuration
+        const operation = this.resourcesRegistryService.getOperationFromPath(operationPath);
+        // 5. Build contextual FK fields: INHERIT from parent + add new
+        const contextResourcesFieldIdentifier = new Map(parentContext.getContextResourceIds());
+        if (resourceId) {
+            const allFieldIds = this.resourcesRegistryService.getAllResourceFieldIdentifiers();
+            const fieldIdentifier = allFieldIds[resourceType];
+            if (fieldIdentifier) {
+                contextResourcesFieldIdentifier.set(fieldIdentifier, resourceId);
+            }
+        }
+        // 6. Build relationship contexts: inherit from parent + add new relationship if provided
+        const relationshipContexts = [...parentContext.relationshipContexts];
+        if (relationshipContext) {
+            relationshipContexts.push(relationshipContext);
+        }
+        // 7. Build visited resources set: inherit from parent + add current
+        const visitedResources = new Set(parentContext.getVisitedResources());
+        if (resourceId) {
+            visitedResources.add(`${resourceType}:${resourceId}`);
+        }
+        // 8. Create new context inheriting from parent
+        // Note: ExecutionType and requestUUID inherited (same request flow)
+        return new ExecutionContext(operation, parentContext.executionType, // Inherit - same origin
+        contextResourcesFieldIdentifier, // Inherit parent + add new
+        parentContext.initiatorIds, // Inherit (readonly, passed as reference)
+        [...parentContext.initiatorRoles], // Inherit (spread to new array)
+        relationshipContexts, // Inherit parent + add new relationship
+        parentContext.requestUUID, // INHERIT - same request trace
+        currentDepth + 1, // Increment depth for next level
+        visitedResources, // Track visited for cycle detection
+        parentContext.activeUserType);
+    }
+    async createExecutionContextFromRequest(req, operation, initiatorInfo) {
+        this.logDebug('Creating execution context from request', { operation: operation.operationIdentifier, url: req.url, method: req.method });
+        // ── Token and authentication sources ──
+        const queryToken = req.query?.consumable_token;
+        const headerToken = req.headers[WildoHeaderKeys.CONSUMABLE_TOKEN];
+        const tokenAuthConfig = 'tokenAuthentication' in operation ? operation.tokenAuthentication : undefined;
+        const policy = tokenAuthConfig?.policy;
+        // ── GATE 1: Query token present — route by policy ──
+        if (queryToken) {
+            if (!tokenAuthConfig) {
+                // Trap 6: operation doesn't accept token authentication
+                throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_NOT_ACCEPTED_FOR_OPERATION,
+                    context: { operationIdentifier: operation.operationIdentifier },
+                });
+            }
+            if (policy === TokenAuthenticationPolicy.ALTERNATIVE) {
+                this.logDebug('Consumable token provided, processing ALTERNATIVE token authentication');
+                const expectedTypes = tokenAuthConfig.types || [];
+                const consumableTokenObject = await this.consumableTokenService.validateToken(queryToken, expectedTypes.length > 0 ? expectedTypes : undefined);
+                // Build context from typed token fields (Trap 3: no untyped metadata bag)
+                const tokenContext = {};
+                if (consumableTokenObject.organizationId) {
+                    tokenContext.organizationId = consumableTokenObject.organizationId;
+                }
+                if (consumableTokenObject.relatedId) {
+                    const resourceFieldIdentifier = this.resolveResourceFieldIdentifier(operation);
+                    if (resourceFieldIdentifier) {
+                        tokenContext[resourceFieldIdentifier] = consumableTokenObject.relatedId;
+                    }
+                }
+                if (consumableTokenObject.userId) {
+                    tokenContext.userId = consumableTokenObject.userId;
+                }
+                const initiatorCriticalParamsValue = this.validateParameterCoherence(req, initiatorInfo, tokenContext);
+                const relationshipContexts = this.buildRelationshipContexts(initiatorInfo, initiatorCriticalParamsValue);
+                const initiatorIds = {
+                    consumableTokenId: consumableTokenObject._id,
+                    organizationId: consumableTokenObject.organizationId,
+                    userId: consumableTokenObject.userId,
+                    ...this.extractInitiatorIds(initiatorCriticalParamsValue),
+                };
+                const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.CONSUMABLE_TOKEN, new Map(Object.entries(initiatorCriticalParamsValue)), initiatorIds, consumableTokenObject.roles || [], relationshipContexts);
+                executionContext.setConsumableTokenValue(queryToken);
+                if (operation.resourcePrimaryScope === ResourcePrimaryScope.APPLICATION) {
+                    await this.populateApplicationIdIfNeeded(executionContext);
+                }
+                return executionContext;
+            }
+            // ADDITIVE: query token is irrelevant — fall through to JWT/API-key auth
+        }
+        // ── GATE 2: JWT / API-key authentication ──
+        const authHeader = req.headers[WildoHeaderKeys.AUTHORIZATION];
+        if (authHeader) {
+            let executionContext;
+            if (authHeader.startsWith('sk_org_') || authHeader.startsWith('sk_app_')) {
+                executionContext = await this.handleApiKeyAuthentication(authHeader, req, operation, initiatorInfo);
+            }
+            else {
+                const token = this.parseBearerToken(authHeader);
+                executionContext = await this.handleJwtAuthentication(token, req, operation, initiatorInfo);
+                const reAuthToken = req.headers[WildoHeaderKeys.REAUTH_TOKEN];
+                if (reAuthToken) {
+                    executionContext.setReAuthTokenValue(reAuthToken);
+                }
+            }
+            // ── GATE 3: ADDITIVE check (after JWT/API-key auth succeeded) ──
+            if (policy === TokenAuthenticationPolicy.ADDITIVE) {
+                if (!headerToken) {
+                    throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                        customMessageReference: ErrorCustomMessageReference.ADDITIVE_TOKEN_REQUIRED,
+                        context: { operationIdentifier: operation.operationIdentifier },
+                    });
+                }
+                const expectedTypes = tokenAuthConfig.types || [];
+                const consumableTokenObject = await this.consumableTokenService.validateToken(headerToken, expectedTypes.length > 0 ? expectedTypes : undefined);
+                if (consumableTokenObject.userId && executionContext.initiatorIds?.userId
+                    && consumableTokenObject.userId !== executionContext.initiatorIds.userId) {
+                    throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                        customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_CONTEXT_MISMATCH,
+                        context: { operationIdentifier: operation.operationIdentifier },
+                    });
+                }
+                executionContext.setConsumableTokenValue(headerToken);
+            }
+            return executionContext;
+        }
+        // ADDITIVE operations require JWT/API-key — anonymous sessions cannot satisfy them
+        if (policy === TokenAuthenticationPolicy.ADDITIVE) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.ADDITIVE_TOKEN_REQUIRED,
+                context: { operationIdentifier: operation.operationIdentifier },
+            });
+        }
+        // Step 3: x-anonymous-session header — existing anonymous session with signed JWT
+        const anonymousSessionToken = req.headers[WildoHeaderKeys.ANONYMOUS_SESSION];
+        if (anonymousSessionToken) {
+            return this.handleAnonymousSessionAuthentication(anonymousSessionToken, req, operation, initiatorInfo);
+        }
+        // Step 4: x-anonymous-session-init header — new session initialization (raw UUID)
+        const anonymousSessionInitId = req.headers[WildoHeaderKeys.ANONYMOUS_SESSION_INIT];
+        if (anonymousSessionInitId) {
+            return this.handleAnonymousSessionInit(anonymousSessionInitId, req, operation, initiatorInfo);
+        }
+        // Step 5: No authentication provided
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_NO_AUTHENTICATION_PROVIDED });
+    }
+    /**
+     * Create an ExecutionContext for manual controller requests (charts, billing, etc.).
+     *
+     * Manual controllers are NOT resource controllers — they don't have a
+     * ResourceConfiguration_Operation or URL initiatorInfo. This method provides a
+     * lightweight alternative to createExecutionContextFromRequest that:
+     *
+     * 1. Extracts the Authorization header (Bearer JWT or API key)
+     * 2. Verifies the token and fetches user from the database
+     * 3. Builds initiator roles from org memberships
+     * 4. Returns an ExecutionContext bound to APPLICATION.READ as a generic operation
+     *
+     * The returned context carries full identity (userId, roles, orgMemberships)
+     * which is sufficient for:
+     * - AggregationAuthorizationService (chart queries)
+     * - Role-based guards (billing endpoints)
+     * - Any service that needs initiatorIds / initiatorRoles
+     *
+     * @param req - Express Request object with Authorization header
+     * @returns ExecutionContext<any> with the caller's identity and roles
+     * @throws AUTHENTICATION error if no token, invalid token, or user not found/active
+     */
+    async createExecutionContextForManualController(req) {
+        this.logDebug('Creating execution context for manual controller', { url: req.url, method: req.method });
+        // 1. Extract authorization header
+        const authHeader = req.headers[WildoHeaderKeys.AUTHORIZATION];
+        if (!authHeader) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_NO_AUTHENTICATION_PROVIDED });
+        }
+        // 2. Get a generic operation for the context (APPLICATION.READ — lightweight, application-scoped)
+        const operationPath = this.resourcesRegistryService.getOperationPathDefault(CoreResourceType.APPLICATION, CoreResourceOperation.READ);
+        const operation = this.resourcesRegistryService.getOperationFromPath(operationPath);
+        const tempContext = this._getTempExecutionContext(operation);
+        // 3. Handle API key authentication
+        if (authHeader.startsWith('sk_org_') || authHeader.startsWith('sk_app_')) {
+            // API keys for manual controllers: only app-level keys make sense
+            // (org keys require ORGANIZATIONS-scoped operations which we don't have here)
+            if (authHeader.startsWith('sk_org_')) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.API_ORG_KEY_WRONG_RESOURCE,
+                    context: { message: 'Organization API keys are not supported for manual controller endpoints.' },
+                });
+            }
+            // App-level API key — validate and build context
+            const appApiKeyRepository = this.repositoriesRegistry.getRepository(CoreResourceType.APPLICATION_API_KEYS);
+            const appApiKey = await appApiKeyRepository.read(tempContext, { keyValue: authHeader });
+            if (!appApiKey || appApiKey.status !== ApiKeyStatus.ACTIVE) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_API_KEY_INVALID, context: { scope: 'application' } });
+            }
+            const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.APP_API_KEY, new Map(), { applicationApiKeyId: appApiKey._id }, [{ roles: appApiKey.roles || [], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION, relatedResourceId: appApiKey.applicationId }], []);
+            await this.populateApplicationIdIfNeeded(executionContext, true);
+            return executionContext;
+        }
+        // 4. Handle JWT Bearer token
+        const token = this.parseBearerToken(authHeader);
+        try {
+            const rawDecodedToken = await this.jwtService.verify(token);
+            const decodedToken = JwtClaim_App_Auth_Schema.parse(rawDecodedToken);
+            // Capture type before narrowing — after exhaustive if-chains, decodedToken becomes `never`
+            // but tokenType retains its original union type for the fallback error path.
+            const tokenType = decodedToken.type;
+            if (tokenType === ExecutionContext_ExecutionType.USER_REQUEST) {
+                const userJwtToken = decodedToken;
+                const iat = userJwtToken.iat;
+                if (iat) {
+                    const invalidBefore = await this.redisService.get(`${AUTH_REDIS_KEYS.TOKEN_INVALID_BEFORE}${userJwtToken.userId}`);
+                    if (invalidBefore && iat < invalidBefore) {
+                        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                            customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_JWT_TOKEN_FAILED,
+                            context: { reason: 'token_invalidated' },
+                        });
+                    }
+                }
+                const { initiatorRoles } = await this._fetchUserAndBuildRoles(userJwtToken.userId, tempContext);
+                const organizationId = this.resolveManualControllerOrganizationId(req, initiatorRoles);
+                const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.USER_REQUEST, new Map(), {
+                    userId: userJwtToken.userId,
+                    ...(organizationId ? { organizationId } : {}),
+                }, initiatorRoles, [], undefined, // requestUUID
+                0, // subCallDepth
+                undefined, // visitedResources
+                userJwtToken.activeUserType ?? null);
+                await this.populateApplicationIdIfNeeded(executionContext);
+                return executionContext;
+            }
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN, context: { tokenType } });
+        }
+        catch (error) {
+            if (isWildoBackendError(error)) {
+                throw error; // Re-throw engine errors
+            }
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_JWT_TOKEN_FAILED, context: { originalError: error instanceof Error ? error.message : 'Unknown error' } });
+        }
+    }
+    /**
+     * Manual endpoints like chart execution are not mounted on resource URLs, so
+     * they do not get organization scope from initiatorInfo / URL-param validation.
+     *
+     * Resolution policy:
+     * - If the request explicitly provides `organizationId`, validate it against
+     *   the caller's active organization memberships and use it.
+     * - Otherwise, if the caller belongs to exactly one active organization,
+     *   infer that org to preserve the common single-tenant case.
+     * - Otherwise, leave the org undefined and let downstream org-scoped
+     *   authorization fail closed instead of widening scope silently.
+     */
+    resolveManualControllerOrganizationId(req, initiatorRoles) {
+        const requestedOrganizationIds = [
+            ...new Set(this.getQueryParameterValues(req.query, 'organizationId').filter(Boolean)),
+        ];
+        if (requestedOrganizationIds.length > 1) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.API_CALL_INITIATOR_PARAMETER_INCONSISTENT,
+                context: {
+                    fieldIdentifier: 'organizationId',
+                    values: requestedOrganizationIds,
+                    sources: {
+                        urlValues: ['undefined'],
+                        queryValues: requestedOrganizationIds,
+                        bodyValues: ['undefined'],
+                        tokenValues: ['undefined'],
+                    },
+                },
+            });
+        }
+        const membershipOrganizationIds = [
+            ...new Set(initiatorRoles
+                .filter((roleInfo) => roleInfo.relatedPrimaryScope === ResourcePrimaryScope.ORGANIZATIONS && !!roleInfo.relatedResourceId)
+                .map((roleInfo) => roleInfo.relatedResourceId)),
+        ];
+        const requestedOrganizationId = requestedOrganizationIds[0];
+        if (requestedOrganizationId) {
+            if (!membershipOrganizationIds.includes(requestedOrganizationId)) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.AUTHORIZATION,
+                    context: {
+                        message: 'Manual controller organization scope is not allowed for the authenticated user.',
+                        organizationId: requestedOrganizationId,
+                    },
+                });
+            }
+            return requestedOrganizationId;
+        }
+        return membershipOrganizationIds.length === 1 ? membershipOrganizationIds[0] : undefined;
+    }
+    _getTempExecutionContext(operation) {
+        return new ExecutionContext(operation, ExecutionContext_ExecutionType.INTERNALLY_INITIATED_REQUEST, new Map(), null, [], []);
+    }
+    /**
+     * Build relationship contexts from initiator info parameters and extracted values.
+     *
+     * This extracts FK relationship information from URL parameters to enable:
+     * 1. Authorization checks that understand which FK path was used (e.g., assignedToUserId vs createdByUserId)
+     * 2. Repository filtering based on the FK relationship
+     *
+     * @param initiatorInfo The URL initiator info containing parameter definitions
+     * @param extractedValues The extracted parameter values from the request
+     * @returns Array of relationship contexts for the ExecutionContext
+     */
+    buildRelationshipContexts(initiatorInfo, extractedValues) {
+        const relationshipContexts = [];
+        if (!initiatorInfo.parameters) {
+            return relationshipContexts;
+        }
+        for (const param of initiatorInfo.parameters) {
+            const value = extractedValues[param.fieldIdentifier];
+            if (value) {
+                relationshipContexts.push({
+                    resourceType: param.resourceType,
+                    relationshipField: param.relationshipField,
+                    resourceId: value,
+                });
+            }
+        }
+        return relationshipContexts;
+    }
+    /**
+     * Extract all potential values from URL parameters (req.params)
+     * According to Express.js specification, URL params are always flat key-value pairs
+     * automatically URL-decoded from route parameters like /users/:userId
+     *
+     * Examples:
+     * - Route: /users/:userId → req.params = { userId: '123' }
+     * - Route: /users/:userId/posts/:postId → req.params = { userId: '123', postId: '456' }
+     */
+    getUrlParameterValues(params, fieldIdentifier) {
+        const values = [];
+        // Direct access to field (URL params are always flat, no nesting)
+        const directValue = params[fieldIdentifier];
+        if (this.isValidParameterValue(directValue)) {
+            values.push(this.safeStringify(directValue));
+        }
+        return values;
+    }
+    /**
+     * Extract all potential values from query parameters (req.query)
+     * Handles Express.js query serialization via the `qs` library:
+     *
+     * Examples of how Express/qs parses query strings:
+     * - ?name=John → { name: 'John' }
+     * - ?tags=red&tags=blue → { tags: ['red', 'blue'] } (repeated keys = array)
+     * - ?tags=red,blue → { tags: 'red,blue' } (comma-separated = single string)
+     * - ?user[name]=John&user[age]=25 → { user: { name: 'John', age: '25' } }
+     * - ?user[tags]=red&user[tags]=blue → { user: { tags: ['red', 'blue'] } }
+     * - ?items[0]=apple&items[1]=banana → { items: ['apple', 'banana'] }
+     */
+    getQueryParameterValues(query, fieldIdentifier) {
+        const values = [];
+        // Direct access to field
+        const directValue = query[fieldIdentifier];
+        if (this.isValidParameterValue(directValue)) {
+            if (Array.isArray(directValue)) {
+                // Handle arrays created by qs from repeated query params (?key=val1&key=val2)
+                values.push(...directValue.map(v => this.safeStringify(v)).filter(v => v));
+            }
+            else {
+                // Handle single values (including comma-separated strings)
+                values.push(this.safeStringify(directValue));
+            }
+        }
+        // Nested object access (e.g., user.id -> query.user?.id)
+        if (fieldIdentifier.includes('.')) {
+            const nestedValue = this.getNestedValue(query, fieldIdentifier);
+            if (this.isValidParameterValue(nestedValue)) {
+                if (Array.isArray(nestedValue)) {
+                    // Handle nested arrays like user[tags]=red&user[tags]=blue
+                    values.push(...nestedValue.map(v => this.safeStringify(v)).filter(v => v));
+                }
+                else {
+                    values.push(this.safeStringify(nestedValue));
+                }
+            }
+        }
+        return values;
+    }
+    /**
+     * Extract all potential values from body parameters (req.body)
+     * Handles deep object access and arrays according to body parser specifications
+     *
+     * Examples based on body parser type:
+     * - JSON: { "user": { "id": "123", "tags": ["red", "blue"] } }
+     * - URL-encoded: user[id]=123&user[tags]=red&user[tags]=blue (parsed to nested object)
+     * - Form-data: Can include files and nested structures
+     */
+    getBodyParameterValues(body, fieldIdentifier) {
+        const values = [];
+        if (!body || typeof body !== 'object') {
+            return values;
+        }
+        // Direct access to field
+        const directValue = body[fieldIdentifier];
+        if (this.isValidParameterValue(directValue)) {
+            if (Array.isArray(directValue)) {
+                values.push(...directValue.map(v => this.safeStringify(v)).filter(v => v));
+            }
+            else {
+                values.push(this.safeStringify(directValue));
+            }
+        }
+        // Nested object access (e.g., user.id -> body.user?.id)
+        if (fieldIdentifier.includes('.')) {
+            const nestedValue = this.getNestedValue(body, fieldIdentifier);
+            if (this.isValidParameterValue(nestedValue)) {
+                if (Array.isArray(nestedValue)) {
+                    values.push(...nestedValue.map(v => this.safeStringify(v)).filter(v => v));
+                }
+                else {
+                    values.push(this.safeStringify(nestedValue));
+                }
+            }
+        }
+        return values;
+    }
+    /**
+     * Extract all potential values from token context
+     * Handles deep object access if token context contains nested objects
+     *
+     * Token context is application-specific and can contain any structure
+     * depending on how the token was parsed and what data it contains.
+     *
+     * Examples:
+     * - JWT claims: { "userId": "123", "organizationId": "org456" }
+     * - Consumable token data: { "permissions": ["read", "write"], "scope": "user.profile" }
+     */
+    getTokenParameterValues(tokenContext, fieldIdentifier) {
+        const values = [];
+        if (!tokenContext || typeof tokenContext !== 'object') {
+            return values;
+        }
+        // Direct access to field
+        const directValue = tokenContext[fieldIdentifier];
+        if (this.isValidParameterValue(directValue)) {
+            if (Array.isArray(directValue)) {
+                values.push(...directValue.map(v => this.safeStringify(v)).filter(v => v));
+            }
+            else {
+                values.push(this.safeStringify(directValue));
+            }
+        }
+        // Nested object access (e.g., user.id -> tokenContext.user?.id)
+        if (fieldIdentifier.includes('.')) {
+            const nestedValue = this.getNestedValue(tokenContext, fieldIdentifier);
+            if (this.isValidParameterValue(nestedValue)) {
+                if (Array.isArray(nestedValue)) {
+                    values.push(...nestedValue.map(v => this.safeStringify(v)).filter(v => v));
+                }
+                else {
+                    values.push(this.safeStringify(nestedValue));
+                }
+            }
+        }
+        return values;
+    }
+    /**
+     * Get nested value from object using dot notation (e.g., 'user.profile.name')
+     */
+    getNestedValue(obj, path) {
+        if (!obj || typeof obj !== 'object') {
+            return undefined;
+        }
+        const keys = path.split('.');
+        let current = obj;
+        for (const key of keys) {
+            if (current === null || current === undefined || typeof current !== 'object') {
+                return undefined;
+            }
+            current = current[key];
+        }
+        return current;
+    }
+    /**
+     * Check if a parameter value is valid (not null, undefined, or empty string)
+     * According to Express.js specification, these values should be ignored
+     */
+    isValidParameterValue(value) {
+        return value !== undefined && value !== null && value !== '';
+    }
+    /**
+     * Safely convert a value to string, handling edge cases
+     * According to Express.js specification, all parameter values are strings or arrays of strings
+     */
+    safeStringify(value) {
+        if (value === null || value === undefined) {
+            return '';
+        }
+        if (typeof value === 'string') {
+            return value;
+        }
+        if (typeof value === 'number' || typeof value === 'boolean') {
+            return String(value);
+        }
+        // For objects, convert to string (though this should be rare in Express params)
+        return String(value);
+    }
+    validateParameterCoherence(req, initiatorInfo, tokenContext) {
+        this.logDebug('Validating parameter coherence', { parameters: initiatorInfo.parameters?.map(p => p.fieldIdentifier) || [] });
+        const initiatorCriticalParamsValue = {};
+        if (!initiatorInfo.parameters || initiatorInfo.parameters.length === 0) {
+            return initiatorCriticalParamsValue;
+        }
+        for (const paramInfo of initiatorInfo.parameters) {
+            const fieldIdentifier = paramInfo.fieldIdentifier;
+            // Extract ALL potential values from each source as arrays
+            const urlValues = this.getUrlParameterValues(req.params, fieldIdentifier);
+            const queryValues = this.getQueryParameterValues(req.query, fieldIdentifier);
+            const bodyValues = this.getBodyParameterValues(req.body, fieldIdentifier);
+            const tokenValues = this.getTokenParameterValues(tokenContext, fieldIdentifier);
+            const sources = {
+                urlValues: urlValues.length ? urlValues : ['undefined'],
+                queryValues: queryValues.length ? queryValues : ['undefined'],
+                bodyValues: bodyValues.length ? bodyValues : ['undefined'],
+                tokenValues: tokenValues.length ? tokenValues : ['undefined']
+            };
+            // Combine all non-empty values from all sources
+            const allValues = [...urlValues, ...queryValues, ...bodyValues, ...tokenValues]
+                .filter(v => v !== null && v !== undefined && v !== '');
+            // check if all mandatory parameters are present
+            if (allValues.length === 0) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, { customMessageReference: ErrorCustomMessageReference.API_CALL_INITIATOR_PARAMETER_MISSING,
+                    context: { fieldIdentifier, sources } });
+            }
+            // Check if all values are the same
+            const uniqueValues = [...new Set(allValues)];
+            if (uniqueValues.length > 1) { // Values are inconsistent across sources
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, { customMessageReference: ErrorCustomMessageReference.API_CALL_INITIATOR_PARAMETER_INCONSISTENT,
+                    context: { fieldIdentifier, values: uniqueValues, sources } });
+            }
+            // 🔒 SECURE: Validate parameter format for security-sensitive fields
+            const value = uniqueValues[0];
+            if (value) {
+                this.validateParameterFormat(fieldIdentifier, value, sources);
+            }
+            // Store the consistent value
+            if (value) {
+                initiatorCriticalParamsValue[fieldIdentifier] = value;
+            }
+        }
+        this.logDebug('Parameter coherence validation successful', { extractedParams: Object.keys(initiatorCriticalParamsValue) });
+        return initiatorCriticalParamsValue;
+    }
+    /**
+     * 🔒 SECURE: Validate parameter format for security-sensitive fields
+     */
+    validateParameterFormat(fieldIdentifier, value, sources) {
+        if (value === 'undefined' || value === null || value === undefined || value === '') {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, { customMessageReference: ErrorCustomMessageReference.API_CALL_INITIATOR_PARAMETER_MISSING,
+                context: { fieldIdentifier, value, sources } });
+        }
+        // Validate ID formats (should be alphanumeric, hyphens, underscores only)
+        if (fieldIdentifier.toLowerCase().endsWith('id')) {
+            if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, { customMessageReference: ErrorCustomMessageReference.API_CALL_INITIATOR_PARAMETER_UNSUPPORTED,
+                    context: { fieldIdentifier, value, sources, regexStringForIdFormat: '^[a-zA-Z0-9_-]+$' } });
+            }
+        }
+        if (value.length > 255) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, { customMessageReference: ErrorCustomMessageReference.API_CALL_INITIATOR_PARAMETER_UNSUPPORTED,
+                context: { fieldIdentifier, value, sources, maxLength: 255 } });
+        }
+    }
+    parseBearerToken(authHeader) {
+        const trimmed = authHeader.trim();
+        if (!trimmed.toLowerCase().startsWith('bearer ')) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN, context: { authHeader } });
+        }
+        const token = trimmed.substring(7).trim(); // Remove 'Bearer ' prefix
+        if (!token) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN, context: { authHeader } });
+        }
+        return token;
+    }
+    /**
+     * W7.3a: Handle x-anonymous-session header — verify existing session JWT,
+     * validate parameter coherence, and create ANONYMOUS_SESSION execution context.
+     */
+    async handleAnonymousSessionAuthentication(sessionToken, req, operation, initiatorInfo) {
+        this.logDebug('Processing anonymous session authentication', { operationId: operation.operationIdentifier });
+        if (!this.appConfigService.anonymousSessionsEnabled) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_NO_AUTHENTICATION_PROVIDED,
+                context: { message: 'Anonymous sessions are not enabled for this application' },
+            });
+        }
+        const operationRoles = operation.roles ?? [];
+        if (!operationRoles.includes(CORE_APP_ROLES.APP_ANONYMOUS)) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_NO_AUTHENTICATION_PROVIDED,
+                context: { message: 'This operation does not accept anonymous access', operationId: operation.operationIdentifier },
+            });
+        }
+        const { anonymousUserId } = this.getAnonymousSessionService().verifySessionToken(sessionToken);
+        const tokenContext = { anonymousUserId };
+        const initiatorCriticalParamsValue = this.validateParameterCoherence(req, initiatorInfo, tokenContext);
+        const relationshipContexts = this.buildRelationshipContexts(initiatorInfo, initiatorCriticalParamsValue);
+        // Pre-fetch applicationId — the EC constructor requires it for ANONYMOUS_SESSION
+        const applicationId = await this.getApplicationId();
+        const initiatorIds = {
+            anonymousUserId,
+            applicationId,
+            ...this.extractInitiatorIds(initiatorCriticalParamsValue),
+        };
+        const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.ANONYMOUS_SESSION, new Map(Object.entries(initiatorCriticalParamsValue)), initiatorIds, [{ roles: [CORE_APP_ROLES.APP_ANONYMOUS], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }], relationshipContexts);
+        return executionContext;
+    }
+    /**
+     * W7.3a: Handle x-anonymous-session-init header — validate UUID, check feature
+     * flag and operation roles, create ANONYMOUS_SESSION execution context with
+     * anonymousUserCreated flag for the controller to create the AnonymousUser record.
+     */
+    async handleAnonymousSessionInit(anonymousUserId, req, operation, initiatorInfo) {
+        this.logDebug('Processing anonymous session init', { anonymousUserId, operationId: operation.operationIdentifier });
+        this.validateParameterFormat('anonymousUserId', anonymousUserId);
+        if (!this.appConfigService.anonymousSessionsEnabled) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_NO_AUTHENTICATION_PROVIDED,
+                context: { message: 'Anonymous sessions are not enabled for this application' },
+            });
+        }
+        const operationRoles = operation.roles ?? [];
+        if (!operationRoles.includes(CORE_APP_ROLES.APP_ANONYMOUS)) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_NO_AUTHENTICATION_PROVIDED,
+                context: { message: 'This operation does not accept anonymous access', operationId: operation.operationIdentifier },
+            });
+        }
+        const tokenContext = { anonymousUserId };
+        const initiatorCriticalParamsValue = this.validateParameterCoherence(req, initiatorInfo, tokenContext);
+        const relationshipContexts = this.buildRelationshipContexts(initiatorInfo, initiatorCriticalParamsValue);
+        // Pre-fetch applicationId — the EC constructor requires it for ANONYMOUS_SESSION
+        const applicationId = await this.getApplicationId();
+        const initiatorIds = {
+            anonymousUserId,
+            applicationId,
+            ...this.extractInitiatorIds(initiatorCriticalParamsValue),
+        };
+        const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.ANONYMOUS_SESSION, new Map(Object.entries(initiatorCriticalParamsValue)), initiatorIds, [{ roles: [CORE_APP_ROLES.APP_ANONYMOUS], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION }], relationshipContexts);
+        executionContext.setAnonymousUserCreated(true);
+        return executionContext;
+    }
+    /**
+     * Extract initiator IDs from critical parameters
+     */
+    extractInitiatorIds(criticalParams) {
+        const initiatorIds = {};
+        // Map common field identifiers to initiator ID properties
+        if (criticalParams.organizationId) {
+            initiatorIds.organizationId = criticalParams.organizationId;
+        }
+        if (criticalParams.userId) {
+            initiatorIds.userId = criticalParams.userId;
+        }
+        if (criticalParams.applicationId) {
+            initiatorIds.applicationId = criticalParams.applicationId;
+        }
+        return initiatorIds;
+    }
+    /**
+     * Handle API key authentication (org and app keys)
+     */
+    async handleApiKeyAuthentication(apiKey, req, operation, initiatorInfo) {
+        this.logDebug('Processing API key authentication', { keyType: apiKey.startsWith('sk_org_') ? 'organization' : 'application' });
+        const initiatorCriticalParamsValue = this.validateParameterCoherence(req, initiatorInfo, {});
+        // Build relationship contexts from URL parameters
+        const relationshipContexts = this.buildRelationshipContexts(initiatorInfo, initiatorCriticalParamsValue);
+        return (apiKey.startsWith('sk_org_'))
+            ? await this.handleOrganizationApiKey(apiKey, initiatorCriticalParamsValue, operation, relationshipContexts)
+            : await this.handleApplicationApiKey(apiKey, initiatorCriticalParamsValue, operation, relationshipContexts);
+    }
+    /**
+     * Handle organization API key authentication with repository validation
+     */
+    async handleOrganizationApiKey(apiKey, initiatorCriticalParamsValue, operation, relationshipContexts) {
+        this.logDebug('Processing organization API key');
+        if (operation.resourcePrimaryScope !== ResourcePrimaryScope.ORGANIZATIONS) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.API_ORG_KEY_WRONG_RESOURCE,
+                context: { resourceIdentifier: operation.resourceIdentifier, primaryScope: operation.resourcePrimaryScope } });
+        }
+        if (!initiatorCriticalParamsValue.organizationId) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.API_ORG_KEY_WITHOUT_ORG_ID,
+                context: { providedParams: Object.keys(initiatorCriticalParamsValue) } });
+        }
+        try {
+            // Create a temporary execution context for repository access
+            const tempExecutionContext = this._getTempExecutionContext(operation);
+            const orgApiKeyRepository = this.repositoriesRegistry.getRepository(CoreResourceType.ORG_API_KEYS);
+            // Validate API key exists and is active
+            const orgApiKey = await orgApiKeyRepository.read(tempExecutionContext, {
+                keyValue: apiKey, // Search by key value
+                organizationId: initiatorCriticalParamsValue.organizationId
+            });
+            if (!orgApiKey || orgApiKey.status !== ApiKeyStatus.ACTIVE) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_API_KEY_INVALID,
+                    context: { scope: "organization", organizationId: initiatorCriticalParamsValue.organizationId, ...(orgApiKey?.status ? { apiKeyStatus: orgApiKey.status } : {}) } });
+            }
+            // Create execution context with API key info
+            const initiatorIds = {
+                organizationId: initiatorCriticalParamsValue.organizationId,
+                organizationApiKeyId: orgApiKey._id, // Use database ID, not raw key
+                ...this.extractInitiatorIds(initiatorCriticalParamsValue)
+            };
+            // Create initial execution context (roles will be validated by AuthorizationsBackendService)
+            const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.ORG_API_KEY, new Map(Object.entries(initiatorCriticalParamsValue)), initiatorIds, [{ roles: orgApiKey.roles || [], relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS, relatedResourceId: orgApiKey.organizationId }], // Use API key roles as initial roles
+            relationshipContexts);
+            return executionContext;
+        }
+        catch (error) {
+            if (isWildoBackendError(error)) {
+                throw error; // Re-throw our own errors (including WildoError_Backend)
+            }
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_API_KEY_FAILED,
+                context: {
+                    organizationId: initiatorCriticalParamsValue.organizationId,
+                    scope: "organization",
+                    originalError: error instanceof Error ? error.message : 'Unknown error'
+                } });
+        }
+    }
+    /**
+     * Handle application API key authentication with repository validation
+     */
+    async handleApplicationApiKey(apiKey, initiatorCriticalParamsValue, operation, relationshipContexts) {
+        this.logDebug('Processing application API key');
+        try {
+            // Create a temporary execution context for repository access
+            const tempExecutionContext = this._getTempExecutionContext(operation);
+            // Validate API key exists and is active
+            const appApiKeyRepository = this.repositoriesRegistry.getRepository(CoreResourceType.APPLICATION_API_KEYS);
+            const appApiKey = await appApiKeyRepository.read(tempExecutionContext, {
+                keyValue: apiKey, // Search by key value
+            });
+            if (!appApiKey || appApiKey.status !== ApiKeyStatus.ACTIVE) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_API_KEY_INVALID,
+                    context: { scope: "application", ...(appApiKey?.status ? { apiKeyStatus: appApiKey.status } : {}) } });
+            }
+            const initiatorIds = {
+                applicationApiKeyId: appApiKey._id, // Use database ID, not raw key
+                ...this.extractInitiatorIds(initiatorCriticalParamsValue)
+            };
+            const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.APP_API_KEY, new Map(Object.entries(initiatorCriticalParamsValue)), initiatorIds, [{ roles: appApiKey.roles || [], relatedPrimaryScope: ResourcePrimaryScope.APPLICATION, relatedResourceId: appApiKey.applicationId }], // Use API key roles as initial roles
+            relationshipContexts);
+            await this.populateApplicationIdIfNeeded(executionContext, true);
+            return executionContext;
+        }
+        catch (error) {
+            if (isWildoBackendError(error)) {
+                throw error;
+            }
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_API_KEY_FAILED,
+                context: {
+                    scope: "application",
+                    originalError: error instanceof Error ? error.message : 'Unknown error'
+                } });
+        }
+    }
+    /**
+     * Handle JWT bearer token authentication
+     */
+    async handleJwtAuthentication(token, req, operation, initiatorInfo) {
+        this.logDebug('Processing JWT authentication');
+        try {
+            const rawDecodedToken = await this.jwtService.verify(token);
+            const decodedToken = JwtClaim_App_Auth_Schema.parse(rawDecodedToken);
+            const tokenType = decodedToken.type;
+            const initiatorCriticalParamsValue = this.validateParameterCoherence(req, initiatorInfo, {});
+            // Build relationship contexts from URL parameters
+            const relationshipContexts = this.buildRelationshipContexts(initiatorInfo, initiatorCriticalParamsValue);
+            if (tokenType === ExecutionContext_ExecutionType.USER_REQUEST) {
+                const userJwtToken = decodedToken;
+                // F1 fix: Reject access tokens issued before a forced invalidation
+                // (e.g., after password reset or refresh token rotation detection).
+                // Without this check, stale access tokens would remain valid for resource
+                // requests until natural expiry, even after invalidateAllTokensForUser().
+                const iat = userJwtToken.iat;
+                if (iat) {
+                    const invalidBefore = await this.redisService.get(`${AUTH_REDIS_KEYS.TOKEN_INVALID_BEFORE}${userJwtToken.userId}`);
+                    if (invalidBefore && iat < invalidBefore) {
+                        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                            customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_JWT_TOKEN_FAILED,
+                            context: { reason: 'token_invalidated' },
+                        });
+                    }
+                }
+                return await this.handleUserJwtAuthentication(userJwtToken.userId, initiatorCriticalParamsValue, operation, relationshipContexts, userJwtToken.lastAuthenticatedAt, userJwtToken.activeUserType);
+            }
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN,
+                context: { tokenType } });
+        }
+        catch (error) {
+            // Handle JWT verification or validation errors
+            if (isWildoBackendError(error)) {
+                throw error;
+            }
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_JWT_TOKEN_FAILED,
+                context: { originalError: error instanceof Error ? error.message : 'Unknown error', token } });
+        }
+    }
+    // =====================================================
+    // SHARED AUTH HELPERS (used by both HTTP and WebSocket)
+    // =====================================================
+    /**
+     * Fetch user and build roles - SHARED between HTTP and WebSocket authentication.
+     * This is the single source of truth for user authentication logic.
+     *
+     * @param userId - User ID to authenticate
+     * @param tempContext - Temporary execution context for DB queries
+     * @returns User object and built roles array
+     */
+    async _fetchUserAndBuildRoles(userId, tempContext) {
+        // 1. Fetch and validate user
+        const userRepository = this.repositoriesRegistry.getRepository(CoreResourceType.USERS);
+        const user = await userRepository.read(tempContext, userId);
+        if (!user) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_NOT_FOUND,
+                context: { userId }
+            });
+        }
+        if (user.status !== UserStatus.ACTIVE) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_USER_NOT_ACTIVE,
+                context: { userId }
+            });
+        }
+        // 2. Fetch organization memberships
+        const orgMemberRepo = this.repositoriesRegistry.getRepository(CoreResourceType.ORGANIZATION_MEMBERS);
+        const membershipsList = await orgMemberRepo.list(tempContext, {
+            userId: userId,
+            status: OrganizationMemberStatus.ACTIVE
+        });
+        // Workaround: If organization members only have _id (due to projection issue),
+        // fetch them individually using READ operations to get all fields
+        const memberships = await Promise.all(membershipsList.map(async (member) => {
+            if (member && member.roles && member.organizationId) {
+                return member;
+            }
+            if (member && member._id) {
+                try {
+                    const fullMember = await orgMemberRepo.read(tempContext, member._id);
+                    return fullMember || member;
+                }
+                catch {
+                    return member;
+                }
+            }
+            return member;
+        }));
+        // 3. Build roles from memberships
+        const initiatorRoles = [];
+        for (const membership of memberships) {
+            if (membership && membership.organizationId) {
+                initiatorRoles.push({
+                    roles: membership.roles || [],
+                    relatedPrimaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+                    relatedResourceId: membership.organizationId
+                });
+            }
+        }
+        // 4. Add application-level roles if user has any
+        const applicationId = await this.getApplicationId();
+        if (user.appRoles && user.appRoles.length > 0) {
+            initiatorRoles.push({
+                roles: user.appRoles,
+                relatedPrimaryScope: ResourcePrimaryScope.APPLICATION,
+                relatedResourceId: applicationId
+            });
+        }
+        return { user, initiatorRoles, applicationId };
+    }
+    // =====================================================
+    // HTTP AUTHENTICATION METHODS
+    // =====================================================
+    /**
+     * Handle user JWT authentication with user and role validation.
+     * Uses _fetchUserAndBuildRoles() shared helper for DRY.
+     */
+    async handleUserJwtAuthentication(userId, initiatorCriticalParamsValue, operation, relationshipContexts, lastAuthenticatedAt, jwtActiveUserType) {
+        this.logDebug('Processing user JWT authentication', { userId: userId.substring(0, 8) + '...' });
+        // W3.6: Validate URL params don't contradict JWT-derived identity
+        if (initiatorCriticalParamsValue.userId && initiatorCriticalParamsValue.userId !== userId) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, undefined, {
+                context: { message: 'URL userId parameter does not match authenticated user' },
+            });
+        }
+        try {
+            const tempExecutionContext = this._getTempExecutionContext(operation);
+            // Use shared helper for user fetch and role building
+            const { initiatorRoles } = await this._fetchUserAndBuildRoles(userId, tempExecutionContext);
+            // W3.6: JWT-derived values MUST take precedence over URL params to prevent identity spoofing.
+            const initiatorIds = {
+                ...this.extractInitiatorIds(initiatorCriticalParamsValue),
+                userId,
+            };
+            const executionContext = new ExecutionContext(operation, ExecutionContext_ExecutionType.USER_REQUEST, new Map(Object.entries(initiatorCriticalParamsValue)), initiatorIds, initiatorRoles, relationshipContexts, undefined, // requestUUID — auto-generated
+            0, // subCallDepth — top-level
+            undefined, // visitedResources
+            jwtActiveUserType ?? null);
+            if (lastAuthenticatedAt !== undefined) {
+                executionContext.setLastAuthenticatedAt(lastAuthenticatedAt);
+            }
+            return executionContext;
+        }
+        catch (error) {
+            if (isWildoBackendError(error)) {
+                throw error;
+            }
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, { customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_JWT_TOKEN_FAILED,
+                context: { originalError: error instanceof Error ? error.message : 'Unknown error', userId } });
+        }
+    }
+    // =====================================================
+    // SOCKET AUTHENTICATION METHODS
+    // =====================================================
+    // These methods are factorized with HTTP authentication:
+    // - Same JWT verification (jwtService.verify)
+    // - Same token parsing (JwtClaim_App_Auth_Schema)
+    // - Same user/role extraction (reuses _fetchUserAndBuildRoles)
+    /**
+     * Authenticate a socket connection from JWT token.
+     *
+     * FACTORIZATION: Reuses same JWT verification and user/role extraction as HTTP.
+     *
+     * @param token - JWT token from socket handshake
+     * @returns SocketAuthResult with execution type, initiator IDs and roles
+     */
+    async authenticateSocketConnection(token) {
+        this.logDebug('Authenticating socket connection');
+        // SAME JWT verification as HTTP (jwtService.verify + schema parse)
+        const rawDecodedToken = await this.jwtService.verify(token);
+        const decodedToken = JwtClaim_App_Auth_Schema.parse(rawDecodedToken);
+        const tokenType = decodedToken.type;
+        if (tokenType === ExecutionContext_ExecutionType.USER_REQUEST) {
+            const userJwtToken = decodedToken;
+            const iat = userJwtToken.iat;
+            if (iat) {
+                const invalidBefore = await this.redisService.get(`${AUTH_REDIS_KEYS.TOKEN_INVALID_BEFORE}${userJwtToken.userId}`);
+                if (invalidBefore && iat < invalidBefore) {
+                    throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                        customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_JWT_TOKEN_FAILED,
+                        context: { reason: 'token_invalidated' },
+                    });
+                }
+            }
+            return await this._authenticateUserForSocket(userJwtToken.userId);
+        }
+        throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+            customMessageReference: ErrorCustomMessageReference.AUTHENTICATION_INVALID_TOKEN,
+            context: { tokenType }
+        });
+    }
+    /**
+     * Get auth result for public (unauthenticated) socket connections.
+     */
+    getPublicSocketAuth() {
+        return {
+            executionType: ExecutionContext_ExecutionType.PUBLIC_EXECUTION,
+            initiatorIds: null,
+            initiatorRoles: []
+        };
+    }
+    /**
+     * Build an ExecutionContext from socket auth info for resource authorization.
+     *
+     * FACTORIZATION: Creates an ExecutionContext with same structure as HTTP requests.
+     * Enables reuse of AuthorizationsBackendService.authorizeInController().
+     *
+     * @param auth - SocketAuthResult from authenticated socket
+     * @param operation - Operation config (already looked up from ResourcesRegistryService)
+     * @param contextResourceIdentifiers - Path context for authorization
+     */
+    async buildContextFromSocketAuth(auth, operation, contextResourceIdentifiers) {
+        this.logDebug('Building execution context from socket auth', {
+            executionType: auth.executionType,
+            resourceType: operation.resourceIdentifier,
+            operationIdentifier: operation.operationIdentifier,
+            contextKeys: Object.keys(contextResourceIdentifiers)
+        });
+        // Convert contextResourceIdentifiers to Map for ExecutionContext
+        // This is the SAME format used by HTTP request context extraction
+        const contextMap = new Map();
+        for (const [key, value] of Object.entries(contextResourceIdentifiers)) {
+            contextMap.set(key, value);
+        }
+        // Build execution context with socket auth info AND context identifiers
+        // SAME ExecutionContext structure as HTTP - enables reuse of:
+        // - AuthorizationsBackendService.authorizeInController()
+        // - All internal validation methods (validateOperationRoles, validateParentScopeAccess, etc.)
+        const executionContext = new ExecutionContext(operation, // Same: operation config
+        auth.executionType, // Same structure: USER_REQUEST, PUBLIC_EXECUTION
+        contextMap, // Same structure: context resource identifiers
+        auth.initiatorIds ?? {}, // Same structure: ExecutionContext_InitiatorIds
+        auth.initiatorRoles, // Same structure: ExecutionContext_RoleInfo[]
+        [] // relationshipContexts - not needed for socket authorization
+        );
+        if (auth.consumableTokenValue) {
+            executionContext.setConsumableTokenValue(auth.consumableTokenValue);
+        }
+        // Reuse existing helper to populate applicationId
+        await this.populateApplicationIdIfNeeded(executionContext, false);
+        return executionContext;
+    }
+    /**
+     * Authenticate user for socket.
+     * Uses _fetchUserAndBuildRoles() shared helper - same logic as HTTP auth.
+     */
+    async _authenticateUserForSocket(userId) {
+        this.logDebug('Authenticating user for socket', { userId: userId.substring(0, 8) + '...' });
+        // Get temp context for DB queries
+        const appReadOp = this.resourcesRegistryService.getOperationFromPath(this.resourcesRegistryService.getOperationPathDefault(CoreResourceType.APPLICATION, CoreResourceOperation.READ));
+        const tempContext = this._getTempExecutionContext(appReadOp);
+        // Use shared helper - same logic as HTTP auth
+        const { initiatorRoles, applicationId } = await this._fetchUserAndBuildRoles(userId, tempContext);
+        return {
+            executionType: ExecutionContext_ExecutionType.USER_REQUEST,
+            initiatorIds: { userId, applicationId },
+            initiatorRoles
+        };
+    }
+    /**
+     * Resolve the resource field identifier from the operation.
+     * This is the FK field name used when relating to this resource (e.g., 'todoId' for TODOS).
+     * Used to map token.relatedId to the correct parameter name for coherence validation.
+     */
+    resolveResourceFieldIdentifier(operation) {
+        return operation.resourceFieldIdentifier;
+    }
+};
+ExecutionContextCreatorBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.ExecutionContextHandlerService)),
+    __param(4, inject(SAAS_SERVICE_TYPES.JwtBackendService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.ResourceRegistryService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)),
+    __param(7, inject(SAAS_SERVICE_TYPES.ConsumableTokenService)),
+    __param(8, inject(SAAS_SERVICE_TYPES.RedisService)),
+    __param(9, inject(SAAS_SERVICE_TYPES.Container)),
+    __metadata("design:paramtypes", [LoggerService,
+        AppConfigurationService,
+        ErrorBuilderBackendService,
+        ExecutionContextHandlerBackendService,
+        JwtBackendService,
+        ResourcesRegistryBackendService,
+        RepositoriesRegistryHandlerBackendService,
+        ConsumableTokenBackendService,
+        RedisService,
+        Container])
+], ExecutionContextCreatorBackendService);
+export { ExecutionContextCreatorBackendService };
+//# sourceMappingURL=execution-context-creator.backend.service.js.map