@wildo-ai/saas-backend-lib 1.0.1

package/src/base-classes/services/controllers/validate-field-handler.backend.service.ts

@@ -0,0 +1,613 @@
+/**
+ * Validate Field Handler — General-Purpose Server-Side Field Validation Gateway
+ *
+ * Provides a single endpoint for all server-side field-level pre-validations.
+ * Each validation type is implemented as a FieldValidationStrategy. The handler
+ * dispatches to the matching strategy based on field decorators and resource config.
+ *
+ * Route: POST /api/v1/.../:resourceType/validate-field
+ *
+ * ## Architecture
+ *
+ * ```
+ *   Frontend (blur)  ──POST──>  validate-field endpoint
+ *                                    │
+ *                              parse & sanitize request
+ *                                    │
+ *                              resolve field schema
+ *                                    │
+ *                              authorize (CREATE rights)
+ *                                    │
+ *                              detect applicable strategies
+ *                                    │
+ *                    ┌───────────────┼───────────────┐
+ *                    ▼               ▼               ▼
+ *              [uniqueness]    [future: FK]    [future: external]
+ *                    │               │               │
+ *                    └───────────────┼───────────────┘
+ *                                    │
+ *                              return first failure (or valid)
+ * ```
+ *
+ * ## Strategy Registration
+ *
+ * Strategies are registered at module level in FIELD_VALIDATION_STRATEGIES.
+ * Each strategy declares:
+ * - `id`: unique identifier for logging/debugging
+ * - `appliesTo(fieldSchema)`: whether this field needs this validation
+ * - `validate(context)`: execute the validation, return result
+ *
+ * ## Security Model
+ *
+ * - Authorization: CREATE operation rights (collection-level) — if you can create, you can pre-validate
+ * - Value sanitization: only scalars allowed (prevents NoSQL injection)
+ * - Scope enforcement: organization/user scoping is mandatory when declared
+ * - Fail-open for UX: missing scope context returns valid (DB constraints catch at write time)
+ *
+ * ## Currently Implemented Strategies
+ *
+ * - `uniqueness`: checks `isUnique()` decorated fields against the collection
+ *
+ * ## Future Strategies (documented for roadmap)
+ *
+ * ### Foreign Key Existence (`fk-existence`) — DEFERRED
+ * Check that a foreign key value references an existing, accessible resource.
+ * Decorator: `isForeignKey()` (already exists on the schema, validation would be added).
+ * Deferred because: future field developments (autocomplete, resource pickers) will
+ * inherently avoid invalid FK values at the UI level. Server-side FK validation
+ * is a safety net, not a primary UX concern.
+ * Implementation notes when ready:
+ * - Read FK target from relationship configuration (not hardcoded)
+ * - Verify target resource exists via repositoriesRegistry
+ * - Respect user permissions (don't confirm existence of resources the user can't see)
+ * - Handle polymorphic FKs (discriminator-based target resolution)
+ *
+ * ### Quota / Cardinality Limits (`quota`) — DEFERRED
+ * Pre-check "can I create one more of this resource?" before the user fills the form.
+ * Tied to feature flags and billing tiers, which are not yet finalized.
+ * Implementation notes when ready:
+ * - Resource-level check, not field-level (applies to the CREATE action itself)
+ * - Could be triggered on form mount rather than on blur
+ * - Needs to integrate with the billing/subscription service
+ * - May return a quota-specific error type for distinct UI treatment (upgrade prompts)
+ *
+ * ### External API Validation (`external-api`) — DEFERRED
+ * Delegate validation to external services (email deliverability, phone format, VAT, etc.).
+ * Requires a pluggable connector architecture for different providers.
+ * Implementation notes when ready:
+ * - Decorator: `isExternallyValidated({ provider: 'email-deliverability' })` or similar
+ * - Strategy resolves provider from resource configuration or application config
+ * - External connectors engine (`external-connectors/`) would handle the actual API calls
+ * - Needs timeout handling, caching (same email checked twice shouldn't hit the API twice),
+ *   and graceful degradation when the external service is unavailable
+ * - Cost awareness: some APIs charge per call (e.g., Twilio, ZeroBounce)
+ *
+ * ### Custom Server Validators (`custom`) — DEFERRED
+ * Escape hatch for app-specific business rules that can't be expressed declaratively.
+ * Implementation notes when ready:
+ * - Decorator: `isServerValidated({ validator: 'my-custom-check' })` registered in resource config
+ * - Validator is a named function/class registered in the DI container
+ * - Receives the field value, execution context, and access to services
+ * - Must return ValidateFieldResponse (same contract as all strategies)
+ * - Risk: custom code quality varies — engine should impose timeout and error boundaries
+ */
+
+import { Request, Response, NextFunction, Router } from 'express';
+import { z } from 'zod';
+import type {
+  ResourceConfiguration,
+  ResourceConfiguration_Operation_ApiCall,
+  ResourceConfiguration_Operation_ApiCallWithCallback,
+  ResourceType,
+} from '@wildo-ai/saas-models';
+import {
+  CoreResourceOperation,
+  ResourceOperationVariantType,
+  ErrorType,
+  ErrorCustomMessageReference,
+  ValidateFieldRequest_Schema,
+  ValidateFieldResponse,
+} from '@wildo-ai/saas-models';
+import {
+  isUnique,
+  getUniqueParams,
+  getZodObjectShape,
+  isZodObject,
+} from '@wildo-ai/zod-decorators';
+
+import { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '~wildo-backend-lib/errors/services/error-builder.backend.service';
+import { AuthorizationsBackendService } from '~wildo-backend-lib/security/authorizations/services/authorizations.backend.service';
+import { ExecutionContextCreatorBackendService } from '~wildo-backend-lib/runtime/services/execution-context-creator.backend.service';
+import { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';
+import { RepositoriesRegistryHandlerBackendService } from '~wildo-backend-lib/base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';
+
+
+// =============================================================================
+// VALUE SANITIZATION
+// =============================================================================
+
+/**
+ * Sanitize a value for use in a database query filter.
+ * Rejects objects and arrays to prevent NoSQL injection via query operators
+ * (e.g., { "$regex": ".*" } or { "$gt": "" }).
+ *
+ * Only scalar values (string, number, boolean, null) are safe for equality checks.
+ */
+function sanitizeValueForFilter(value: unknown): { valid: true; sanitized: string | number | boolean | null } | { valid: false } {
+  if (value === null || value === undefined) {
+    return { valid: true, sanitized: null };
+  }
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return { valid: true, sanitized: value };
+  }
+  // Objects, arrays, functions, symbols — reject
+  return { valid: false };
+}
+
+/**
+ * Validate that an ID string has a recognized format (ObjectId or UUID).
+ * Used to sanitize excludeId before injecting into filters.
+ */
+function isValidResourceId(id: string): boolean {
+  return /^[a-fA-F0-9]{24}$/.test(id) ||
+    /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(id);
+}
+
+
+// =============================================================================
+// STRATEGY INTERFACE
+// =============================================================================
+
+/**
+ * Context passed to each validation strategy.
+ * Contains everything needed to perform the validation without leaking implementation details.
+ */
+export interface FieldValidationContext {
+  /** The field name being validated */
+  fieldName: string;
+  /** The sanitized scalar value */
+  value: string | number | boolean | null;
+  /** The field's Zod schema (with decorators) */
+  fieldSchema: z.ZodTypeAny;
+  /** Resource ID to exclude from checks (self-exclusion for UPDATE) */
+  excludeId?: string;
+  /** The resource type identifier */
+  resourceType: ResourceType;
+  /** The full resource configuration */
+  resourceConfiguration: ResourceConfiguration<any, any, any>;
+  /** The authenticated execution context (authorization already performed) */
+  executionContext: ExecutionContext<any>;
+  /** Framework services for database access */
+  repositoriesRegistry: RepositoriesRegistryHandlerBackendService;
+  /** Framework services for resource metadata */
+  resourcesRegistry: ResourcesRegistryBackendService;
+  /** Error builder for structured errors */
+  errorBuilder: ErrorBuilderBackendService;
+  /** Debug logger */
+  logDebug: (message: string, context?: Record<string, unknown>) => void;
+}
+
+/**
+ * A field validation strategy performs a single category of server-side pre-validation.
+ *
+ * Strategies are stateless — all request-specific data is passed via FieldValidationContext.
+ * They are instantiated once at module initialization time, not per-request.
+ *
+ * The validate-field handler runs all applicable strategies for a field in registration order
+ * and returns the first failure. If all strategies pass, the field is valid.
+ */
+export interface FieldValidationStrategy {
+  /** Unique identifier for this strategy (used in logging and debugging) */
+  readonly id: string;
+
+  /**
+   * Determine whether this strategy applies to a given field.
+   * Called once at route initialization time (not per-request) to detect
+   * which fields need the validate-field endpoint.
+   */
+  appliesTo(fieldSchema: z.ZodTypeAny, fieldName: string): boolean;
+
+  /**
+   * Check if the value can be skipped (e.g., null/empty for sparse unique fields).
+   * Called per-request BEFORE authorization to avoid unnecessary auth calls.
+   * Return true to skip this strategy (treat as valid), false to proceed.
+   */
+  shouldSkip?(context: FieldValidationContext): boolean;
+
+  /**
+   * Execute the validation. Returns a ValidateFieldResponse.
+   * Called per-request AFTER authorization has been verified.
+   *
+   * MUST NOT perform its own authorization — that's the handler's job.
+   * MUST NOT access the raw Request object — use FieldValidationContext.
+   */
+  validate(context: FieldValidationContext): Promise<ValidateFieldResponse>;
+}
+
+
+// =============================================================================
+// UNIQUENESS STRATEGY (IMPLEMENTED)
+// =============================================================================
+
+/**
+ * Validates that a field value is unique within the collection,
+ * respecting the `isUnique()` decorator's scope (global, organization, user)
+ * and sparse settings.
+ */
+const uniquenessStrategy: FieldValidationStrategy = {
+  id: 'uniqueness',
+
+  appliesTo(fieldSchema: z.ZodTypeAny): boolean {
+    return isUnique(fieldSchema);
+  },
+
+  shouldSkip(context: FieldValidationContext): boolean {
+    const uniqueParams = getUniqueParams(context.fieldSchema);
+    // Sparse: null/undefined/empty values are always valid (multiple nulls allowed)
+    return (context.value === null || context.value === undefined || context.value === '') &&
+      (uniqueParams?.sparse !== false);
+  },
+
+  async validate(context: FieldValidationContext): Promise<ValidateFieldResponse> {
+    const { fieldName, value, fieldSchema, excludeId, resourceType, executionContext, repositoriesRegistry, logDebug } = context;
+    const uniqueParams = getUniqueParams(fieldSchema);
+
+    // Build the filter with scope-aware filtering
+    const filter: Record<string, unknown> = { [fieldName]: value };
+
+    // Apply scope-based filtering.
+    // SECURITY: If scope requires organization/user context but the context is missing,
+    // we MUST NOT fall through to global scope. Instead, return valid (fail-open for UX)
+    // — the actual unique constraint at CREATE/UPDATE time will catch real conflicts.
+    const scope = uniqueParams?.scope ?? 'global';
+
+    if (scope === 'organization') {
+      const organizationId = executionContext.initiatorIds?.organizationId;
+      if (!organizationId) {
+        logDebug('Organization scope required but no organizationId in context, skipping check', { fieldName, resourceType });
+        return { valid: true };
+      }
+      filter.organizationId = organizationId;
+    } else if (scope === 'user') {
+      const userId = executionContext.initiatorIds?.userId;
+      if (!userId) {
+        logDebug('User scope required but no userId in context, skipping check', { fieldName, resourceType });
+        return { valid: true };
+      }
+      filter.createdByUserId = userId;
+    }
+    // 'global' scope: no additional filter (intentional — check entire collection)
+
+    // Exclude self for UPDATE operations (avoid false conflict with own value)
+    if (excludeId && isValidResourceId(excludeId)) {
+      filter._id = { $ne: excludeId };
+    }
+
+    // Execute uniqueness check via registry infrastructure query
+    const count = await repositoriesRegistry.countDocumentsForInfrastructure(
+      resourceType,
+      filter,
+      executionContext
+    );
+
+    logDebug('Uniqueness check result', { resourceType, fieldName, value, count, excludeId, scope });
+
+    if (count === 0) {
+      return { valid: true };
+    }
+
+    // Build error message, respecting custom errorMessage from decorator
+    const customMessage = uniqueParams?.errorMessage;
+    const fallbackMessage = customMessage
+      ? customMessage.replace('{fieldName}', fieldName)
+      : `This ${fieldName} is already taken`;
+
+    return {
+      valid: false,
+      error: {
+        fieldName,
+        message: fallbackMessage,
+        i18nKey: 'validation.unique.conflict',
+        i18nParams: {
+          fieldName,
+          value: String(value),
+        },
+      },
+    };
+  },
+};
+
+
+// =============================================================================
+// STRATEGY REGISTRY
+// =============================================================================
+
+/**
+ * All registered field validation strategies, in execution order.
+ * When multiple strategies apply to the same field, they are executed
+ * in this order and the first failure short-circuits.
+ *
+ * To add a new strategy:
+ * 1. Implement FieldValidationStrategy
+ * 2. Add it to this array
+ * 3. Update detectFieldsRequiringServerValidation() if the detection
+ *    is not already covered by the strategy's appliesTo()
+ */
+const FIELD_VALIDATION_STRATEGIES: FieldValidationStrategy[] = [
+  uniquenessStrategy,
+  // Future strategies will be added here:
+  // foreignKeyExistenceStrategy,
+  // externalApiStrategy,
+  // quotaStrategy,
+  // customServerValidatorStrategy,
+];
+
+
+// =============================================================================
+// FIELD DETECTION
+// =============================================================================
+
+/**
+ * Detect which fields in a resource schema require server-side pre-validation.
+ * Returns a map of field names to their applicable strategies.
+ *
+ * This is called at route initialization time to determine whether to register
+ * the validate-field endpoint for a given resource.
+ *
+ * Exported so the frontend can use a matching check (via decorator inspection)
+ * to know whether to enable the validate-field URL for a resource.
+ */
+export function detectFieldsRequiringServerValidation(
+  mainSchema: z.ZodTypeAny
+): Map<string, FieldValidationStrategy[]> {
+  const result = new Map<string, FieldValidationStrategy[]>();
+
+  if (!isZodObject(mainSchema)) return result;
+
+  const shape = getZodObjectShape(mainSchema);
+
+  for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+    const applicableStrategies = FIELD_VALIDATION_STRATEGIES.filter(
+      strategy => strategy.appliesTo(fieldSchema, fieldName)
+    );
+    if (applicableStrategies.length > 0) {
+      result.set(fieldName, applicableStrategies);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Quick boolean check: does a resource schema have any fields that require
+ * server-side pre-validation? Used for route gating and frontend URL computation.
+ */
+export function hasFieldsRequiringServerValidation(mainSchema: z.ZodTypeAny): boolean {
+  if (!isZodObject(mainSchema)) return false;
+
+  const shape = getZodObjectShape(mainSchema);
+
+  for (const [fieldName, fieldSchema] of Object.entries(shape)) {
+    for (const strategy of FIELD_VALIDATION_STRATEGIES) {
+      if (strategy.appliesTo(fieldSchema, fieldName)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+// =============================================================================
+// ROUTE INITIALIZATION
+// =============================================================================
+
+/**
+ * Initialize validate-field routes for a resource that has fields requiring
+ * server-side pre-validation.
+ *
+ * Called from ControllerResourceBackendService.initializeRoutes().
+ *
+ * Uses the CREATE operation's initiatorInfos to generate URL patterns,
+ * ensuring proper parent resource context in hierarchical resources.
+ *
+ * Authorization uses CREATE operation rights (collection-level).
+ */
+export function initializeValidateFieldRoutes(
+  router: Router,
+  resourceConfiguration: ResourceConfiguration<any, any, any>,
+  logger: LoggerService,
+  errorBuilder: ErrorBuilderBackendService,
+  authorizationsService: AuthorizationsBackendService,
+  executionContextCreator: ExecutionContextCreatorBackendService,
+  resourcesRegistry: ResourcesRegistryBackendService,
+  repositoriesRegistry: RepositoriesRegistryHandlerBackendService,
+  convertUrlPatternToExpressPath: (urlPattern: string) => string,
+  asyncHandler: (fn: Function) => (req: Request, res: Response, next: NextFunction) => void,
+): void {
+  const resourceType = resourceConfiguration.resourceIdentifier;
+  const logDebug = logger.debugByType(`ValidateField_${resourceType}`);
+  logger.setDebugTypeLogging(`ValidateField_${resourceType}`, false);
+
+  // Detect all fields that need server-side validation
+  const serverValidatedFields = detectFieldsRequiringServerValidation(resourceConfiguration.mainSchema);
+
+  if (serverValidatedFields.size === 0) {
+    logDebug('No fields require server-side validation, skipping validate-field routes', { resourceType });
+    return;
+  }
+
+  const fieldNames = Array.from(serverValidatedFields.keys());
+  const strategyIds = [...new Set(
+    Array.from(serverValidatedFields.values()).flatMap(strategies => strategies.map(s => s.id))
+  )];
+
+  logDebug('Fields requiring server-side validation detected', { resourceType, fieldNames, strategyIds });
+
+  // Get CREATE operation for authorization and URL patterns
+  const createOperation = resourceConfiguration.operations.find(
+    op => op.operationIdentifier === CoreResourceOperation.CREATE &&
+      [ResourceOperationVariantType.API_CALL, ResourceOperationVariantType.API_CALL_WITH_CALLBACK].includes(op.variantType)
+  ) as ResourceConfiguration_Operation_ApiCall<any, any, any> | ResourceConfiguration_Operation_ApiCallWithCallback<any, any, any> | undefined;
+
+  if (!createOperation) {
+    logDebug('CREATE operation not found, skipping validate-field routes', { resourceType });
+    return;
+  }
+
+  const createInitiatorInfos = createOperation.initiatorInfos || [];
+  if (createInitiatorInfos.length === 0) {
+    logDebug('CREATE operation has no initiatorInfos, skipping validate-field routes', { resourceType });
+    return;
+  }
+
+  // Get the schema shape for field lookups
+  const schemaShape = getZodObjectShape(resourceConfiguration.mainSchema);
+
+  // Register routes for each parent combination (same pattern as file upload routes)
+  const sortedInitiatorInfos = [...createInitiatorInfos].sort((a, b) => {
+    const aParams = a.parameters?.length || 0;
+    const bParams = b.parameters?.length || 0;
+    return bParams - aParams; // More specific first
+  });
+
+  for (const initiatorInfo of sortedInitiatorInfos) {
+    const basePath = convertUrlPatternToExpressPath(initiatorInfo.url);
+    const validatePath = `${basePath}/validate-field`;
+
+    router.post(
+      validatePath,
+      asyncHandler(async (req: Request, res: Response, next: NextFunction) => {
+        try {
+          // ─── 1. Parse and validate request body ───────────────────────
+          const parseResult = ValidateFieldRequest_Schema.safeParse(req.body);
+          if (!parseResult.success) {
+            throw errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+              customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+              context: { error: parseResult.error.message },
+            });
+          }
+
+          const { fieldName, value, excludeId } = parseResult.data;
+
+          // ─── 2. Sanitize value (prevent NoSQL injection) ─────────────
+          const sanitizeResult = sanitizeValueForFilter(value);
+          if (!sanitizeResult.valid) {
+            throw errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+              customMessageReference: ErrorCustomMessageReference.CONTROLLER_RESOURCE_VALIDATION_FAILED,
+              context: { fieldName, resourceType, reason: 'Value must be a scalar (string, number, or boolean)' },
+            });
+          }
+          const sanitizedValue = sanitizeResult.sanitized;
+
+          // ─── 3. Resolve field schema and applicable strategies ────────
+          const fieldSchema = schemaShape[fieldName];
+          if (!fieldSchema) {
+            throw errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+              customMessageReference: ErrorCustomMessageReference.VALIDATE_FIELD_NOT_FOUND,
+              context: { fieldName, resourceType },
+            });
+          }
+
+          // Find strategies that apply to this field
+          const applicableStrategies = FIELD_VALIDATION_STRATEGIES.filter(
+            strategy => strategy.appliesTo(fieldSchema, fieldName)
+          );
+
+          if (applicableStrategies.length === 0) {
+            // Field exists but no strategies apply — return valid (no-op)
+            res.json({ valid: true } satisfies ValidateFieldResponse);
+            return;
+          }
+
+          logDebug('Dispatching to strategies', {
+            fieldName,
+            strategies: applicableStrategies.map(s => s.id),
+          });
+
+          // ─── 4. Build validation context (shared across strategies) ──
+          // Note: authorization is deferred until after shouldSkip checks
+          // to avoid unnecessary auth calls for no-op cases.
+          const baseContext: Omit<FieldValidationContext, 'executionContext'> = {
+            fieldName,
+            value: sanitizedValue,
+            fieldSchema,
+            excludeId,
+            resourceType: resourceType as ResourceType,
+            resourceConfiguration,
+            repositoriesRegistry,
+            resourcesRegistry,
+            errorBuilder,
+            logDebug,
+          };
+
+          // ─── 5. Check if ALL strategies want to skip ─────────────────
+          const strategiesNeedingExecution = applicableStrategies.filter(
+            strategy => !strategy.shouldSkip?.(baseContext as FieldValidationContext)
+          );
+
+          if (strategiesNeedingExecution.length === 0) {
+            // All strategies skipped (e.g., null value on sparse unique field)
+            res.json({ valid: true } satisfies ValidateFieldResponse);
+            return;
+          }
+
+          // ─── 6. Authorize (CREATE operation rights) ──────────────────
+          const operationPath = resourcesRegistry.getOperationPathDefault(
+            resourceType as ResourceType,
+            CoreResourceOperation.CREATE
+          );
+          const executionContext = await executionContextCreator.createExecutionContextFromRequest(
+            req,
+            resourcesRegistry.getOperationFromPath(operationPath),
+            {
+              url: validatePath,
+              parameters: initiatorInfo.parameters || [],
+            }
+          );
+
+          // Attach executionContext to request for error handler access
+          (req as any).executionContext = executionContext;
+
+          await authorizationsService.authorizeInController(undefined, executionContext);
+
+          // ─── 7. Execute strategies (first failure short-circuits) ─────
+          const fullContext: FieldValidationContext = {
+            ...baseContext,
+            executionContext,
+          };
+
+          for (const strategy of strategiesNeedingExecution) {
+            const result = await strategy.validate(fullContext);
+
+            if (!result.valid) {
+              logDebug('Strategy returned failure', {
+                strategyId: strategy.id,
+                fieldName,
+                error: result.error?.message,
+              });
+              res.json(result);
+              return;
+            }
+          }
+
+          // ─── 8. All strategies passed ────────────────────────────────
+          res.json({ valid: true } satisfies ValidateFieldResponse);
+
+        } catch (error) {
+          next(error);
+        }
+      })
+    );
+
+    logDebug('validate-field route registered', {
+      resourceType,
+      path: validatePath,
+      serverValidatedFields: fieldNames,
+      strategies: strategyIds,
+      parentParams: initiatorInfo.parameters?.map(p => `${p.fieldIdentifier}:${p.resourceType}`).join(', ') || 'none',
+    });
+  }
+}

package/src/base-classes/services/repositories/__tests__/mock-repositories-registry-handler.service.ts

@@ -0,0 +1,31 @@
+import 'reflect-metadata';
+import { injectable } from 'inversify';
+import { vi } from 'vitest';
+
+@injectable()
+export class MockRepositoriesRegistryHandlerBackendService {
+  private readonly repositories = new Map<string, unknown>();
+
+  getRepository = vi.fn((resourceType: string) => {
+    return this.repositories.get(resourceType);
+  });
+
+  getRepositoryOrThrow = vi.fn((resourceType: string) => {
+    const repository = this.repositories.get(resourceType);
+    if (!repository) {
+      throw new Error(`No mock repository registered for resource type "${resourceType}"`);
+    }
+
+    return repository;
+  });
+
+  setRepository(resourceType: string, repository: unknown): void {
+    this.repositories.set(resourceType, repository);
+  }
+
+  reset(): void {
+    this.repositories.clear();
+    this.getRepository.mockClear();
+    this.getRepositoryOrThrow.mockClear();
+  }
+}

package/src/base-classes/services/repositories/__tests__/repository-resource.singleton-read.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+
+import { RepositoryResourceBackendService } from '../repository-resource.backend.service';
+
+describe('RepositoryResourceBackendService singleton read detection', () => {
+  it('allows parent-owned singleton reads to resolve through contextual scope alone', () => {
+    const repository = Object.create(RepositoryResourceBackendService.prototype) as any;
+
+    const canReadViaContextWithoutExplicitId = repository['canReadViaContextWithoutExplicitId'](
+      {
+        resourceFieldIdentifier: 'userGuidanceStateId',
+        initiatorInfos: [
+          {
+            parameters: [
+              { fieldIdentifier: 'userId', resourceType: 'users' },
+            ],
+          },
+        ],
+      },
+      {
+        getContextResourceIds: () => new Map([['userId', 'user-1']]),
+      },
+    );
+
+    expect(canReadViaContextWithoutExplicitId).toBe(true);
+  });
+
+  it('keeps regular entity reads bound to an explicit child resource id', () => {
+    const repository = Object.create(RepositoryResourceBackendService.prototype) as any;
+
+    const canReadViaContextWithoutExplicitId = repository['canReadViaContextWithoutExplicitId'](
+      {
+        resourceFieldIdentifier: 'todoId',
+        initiatorInfos: [
+          {
+            parameters: [
+              { fieldIdentifier: 'projectId', resourceType: 'projects' },
+              { fieldIdentifier: 'todoId', resourceType: 'todos' },
+            ],
+          },
+        ],
+      },
+      {
+        getContextResourceIds: () => new Map([['projectId', 'project-1']]),
+      },
+    );
+
+    expect(canReadViaContextWithoutExplicitId).toBe(false);
+  });
+});