@wildo-ai/saas-backend-lib 1.0.1

package/src/base-classes/services/controllers/__tests__/controller-resource-file-upload-routes.test.ts

@@ -0,0 +1,1335 @@
+import 'reflect-metadata';
+import express from 'express';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { PassThrough } from 'stream';
+import { describe, expect, it, vi } from 'vitest';
+import { z } from 'zod';
+
+import {
+  CoreResourceOperation,
+  FileStatus,
+  ResourceOperationVariantType,
+  ResourcePrimaryScope,
+  ResourcesConfigOperationsUrlsBuilderUtils,
+  type ResourceType,
+} from '@wildo-ai/saas-models';
+
+const { uploadSingleMiddlewareSpy, createMulterUploadConfigMock } = vi.hoisted(() => {
+  const uploadSingleMiddlewareSpy = vi.fn((req: express.Request, _res: express.Response, next: express.NextFunction) => {
+    (req as any).file = {
+      fieldname: 'file',
+      originalname: 'upload.txt',
+      mimetype: 'text/plain',
+      size: 5,
+      filename: 'upload.txt',
+      path: '/tmp/upload.txt',
+    };
+    next();
+  });
+
+  const createMulterUploadConfigMock = vi.fn(() => ({
+    single: () => uploadSingleMiddlewareSpy,
+  }));
+
+  return {
+    uploadSingleMiddlewareSpy,
+    createMulterUploadConfigMock,
+  };
+});
+
+const appConfigService = {
+  config: {
+    storage: {
+      maxFileSize: 5,
+    },
+  },
+};
+
+vi.mock('~wildo-backend-lib/files/utils/file-upload.utils', () => ({
+  createMulterUploadConfig: createMulterUploadConfigMock,
+}));
+
+async function expectMiddlewareFailure(
+  handle: (req: express.Request, res: express.Response, next: express.NextFunction) => unknown,
+  req: express.Request,
+  res: express.Response,
+): Promise<unknown> {
+  return await new Promise((resolve) => {
+    handle(req, res, (error?: unknown) => {
+      resolve(error);
+    });
+  });
+}
+
+import { ControllerResourceBackendService } from '../controller-resource.backend.service';
+import { ResourceFileUploadHandlerBackendService } from '~wildo-backend-lib/files/handlers/resource-file-upload-handler.backend.service';
+
+function resolveBackendUrlPattern(url: string, params: Record<string, string>): string {
+  return url.replace(/\{([^}]+)\}/g, (_match, token: string) => params[token] ?? `{${token}}`);
+}
+
+function toExpressPath(url: string): string {
+  return url.replace(/\{([^}]+)\}/g, ':$1');
+}
+
+async function runExpressMiddleware(
+  handle: (req: express.Request, res: express.Response, next: express.NextFunction) => unknown,
+  req: express.Request,
+  res: express.Response,
+): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const next: express.NextFunction = (error?: unknown) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve();
+    };
+
+    try {
+      handle(req, res, next);
+    } catch (error) {
+      if (!settled) {
+        settled = true;
+        reject(error);
+      }
+    }
+  });
+}
+
+describe('ControllerResourceBackendService file upload routes', () => {
+  it('wires upload route authorization through the dataMode-resolved variant context before handling the file', async () => {
+    uploadSingleMiddlewareSpy.mockClear();
+    createMulterUploadConfigMock.mockClear();
+    const resourceType = 'todos' as ResourceType;
+    const updateOperation = {
+      operationIdentifier: CoreResourceOperation.UPDATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/todos/{todoId}',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'todoId', resourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const createOperation = {
+      operationIdentifier: CoreResourceOperation.CREATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/todos',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const contextUpdateOperation = {
+      ...updateOperation,
+      isOperationDefault: false,
+      variantKey: 'context',
+    } as any;
+    const resourceConfiguration = {
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      operations: [createOperation, updateOperation, contextUpdateOperation],
+      mainSchema: z.object({}),
+      resourceRelationships: {
+        parentRelationships: [],
+        childRelationships: [],
+        selfRelationships: [],
+      },
+    } as any;
+
+    const baseExecutionContext = {
+      operation: updateOperation,
+      relationshipContexts: [],
+      getContextResourceId: vi.fn(),
+      withOperation: (operation: unknown) => ({
+        operation,
+        relationshipContexts: [],
+        getContextResourceId: vi.fn(),
+        withOperation: baseExecutionContext.withOperation,
+      }),
+    } as any;
+
+    const executionContextCreator = {
+      createExecutionContextFromRequest: vi.fn(async () => baseExecutionContext),
+    };
+    const fileUploadHandler = {
+      handleFileUpload: vi.fn(async (
+        _req: express.Request,
+        res: express.Response,
+        _calledResourceType: ResourceType,
+        _fieldName: string,
+        _resourceId: string | undefined,
+        _operationIdentifier: CoreResourceOperation,
+        calledExecutionContext: unknown,
+      ) => {
+        expect((calledExecutionContext as any).operation).toBe(contextUpdateOperation);
+        res.status(200).json({ success: true });
+      }),
+    };
+    const authorizationsService = {
+      authorizeInController: vi.fn(async () => undefined),
+    };
+
+    const controller = new ControllerResourceBackendService(
+      resourceType,
+      {
+        debugByType: vi.fn(() => vi.fn()),
+        setDebugTypeLogging: vi.fn(),
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      } as any,
+      {
+        buildError: vi.fn((type: string) => new Error(String(type))),
+      } as any,
+      {
+        expressErrorHandler: () => (_err: unknown, _req: express.Request, res: express.Response) => {
+          res.status(500).json({ success: false });
+        },
+      } as any,
+      {} as any,
+      authorizationsService as any,
+      {
+        getResourceConfiguration: vi.fn(() => resourceConfiguration),
+        getOperationFromPath: vi.fn((operationPath: Record<string, unknown>) => {
+          expect(operationPath).toMatchObject({
+            resourceIdentifier: resourceType,
+            operationIdentifier: CoreResourceOperation.UPDATE,
+            variantKey: 'context',
+          });
+          return contextUpdateOperation;
+        }),
+      } as any,
+      executionContextCreator as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {
+        hasFileFields: vi.fn(() => true),
+        detectFileFields: vi.fn(() => [{ fieldName: 'attachment' }]),
+      } as any,
+      fileUploadHandler as any,
+      {} as any,
+      {} as any,
+      appConfigService as any,
+    );
+
+    const uploadRoute = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({
+      operationRouteUrl: updateOperation.initiatorInfos[0].url,
+      operationParameters: updateOperation.initiatorInfos[0].parameters,
+      targetResourceType: resourceType,
+      targetResourceFieldIdentifier: 'todoId',
+      fieldName: 'attachment',
+      requiresTargetResourceId: true,
+      isFrontend: false,
+    });
+
+    const router = controller.getRouter() as any;
+    const routeLayer = router.stack.find((layer: any) => {
+      const candidatePath = layer.route?.path;
+      return typeof candidatePath === 'string'
+        && candidatePath.includes('/files/attachment')
+        && candidatePath.includes(':organizationId')
+        && candidatePath.includes(':todoId');
+    });
+    expect(routeLayer).toBeDefined();
+
+    const req = {
+      params: {
+        organizationId: 'org-1',
+        todoId: 'todo-1',
+      },
+      query: {
+        dataMode: 'context',
+      },
+      body: {},
+      method: 'POST',
+      path: resolveBackendUrlPattern(uploadRoute.url, {
+        organizationId: 'org-1',
+        todoId: 'todo-1',
+      }),
+    } as any;
+    const res = {
+      locals: {},
+      status: vi.fn().mockReturnThis(),
+      json: vi.fn(),
+    } as any;
+
+    await runExpressMiddleware(routeLayer.route.stack[0].handle, req, res);
+    expect(authorizationsService.authorizeInController).toHaveBeenCalledWith(
+      'todo-1',
+      expect.objectContaining({ operation: contextUpdateOperation }),
+    );
+    await runExpressMiddleware(routeLayer.route.stack[1].handle, req, res);
+    routeLayer.route.stack[2].handle(req, res, () => undefined);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(fileUploadHandler.handleFileUpload).toHaveBeenCalledTimes(1);
+    expect(res.locals.fileUploadExecutionContext.operation).toBe(contextUpdateOperation);
+  });
+
+  it('wires nested update upload routes through execution-context creation into the upload handler', async () => {
+    uploadSingleMiddlewareSpy.mockClear();
+    createMulterUploadConfigMock.mockClear();
+    const resourceType = 'todos' as ResourceType;
+    const updateOperation = {
+      operationIdentifier: CoreResourceOperation.UPDATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/projects/{projectId}/todos/{todoId}',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'projectId', resourceType: 'projects' as ResourceType },
+          { fieldIdentifier: 'todoId', resourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const createOperation = {
+      operationIdentifier: CoreResourceOperation.CREATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/projects/{projectId}/todos',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'projectId', resourceType: 'projects' as ResourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+
+    const resourceConfiguration = {
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      operations: [createOperation, updateOperation],
+      mainSchema: z.object({}),
+      resourceRelationships: {
+        parentRelationships: [],
+        childRelationships: [],
+        selfRelationships: [],
+      },
+    } as any;
+
+    const logger = {
+      debugByType: vi.fn(() => vi.fn()),
+      setDebugTypeLogging: vi.fn(),
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+
+    const errorBuilder = {
+      buildError: vi.fn((type: string, _executionContext: unknown, payload?: Record<string, unknown>) => {
+        const error = new Error(String(type));
+        Object.assign(error, payload);
+        return error;
+      }),
+    };
+
+    const executionContext = {
+      operation: updateOperation,
+      relationshipContexts: [{
+        resourceType: 'projects',
+        relationshipField: 'projectId',
+        resourceId: 'project-1',
+      }],
+      getContextResourceId: vi.fn(),
+    } as any;
+
+    const executionContextCreator = {
+      createExecutionContextFromRequest: vi.fn(async (req: express.Request) => {
+        expect(req.params).toMatchObject({
+          organizationId: 'org-1',
+          projectId: 'project-1',
+          todoId: 'todo-1',
+        });
+        return executionContext;
+      }),
+    };
+
+    const fileUploadHandler = {
+      handleFileUpload: vi.fn(async (
+        req: express.Request,
+        res: express.Response,
+        calledResourceType: ResourceType,
+        fieldName: string,
+        resourceId: string | undefined,
+        operationIdentifier: CoreResourceOperation,
+        calledExecutionContext: unknown,
+      ) => {
+        expect((req as any).file).toMatchObject({
+          originalname: 'upload.txt',
+          mimetype: 'text/plain',
+        });
+        expect(calledResourceType).toBe(resourceType);
+        expect(fieldName).toBe('attachment');
+        expect(resourceId).toBe('todo-1');
+        expect(operationIdentifier).toBe(CoreResourceOperation.UPDATE);
+        expect(calledExecutionContext).toBe(executionContext);
+        res.status(200).json({ success: true });
+      }),
+    };
+    const authorizationsService = {
+      authorizeInController: vi.fn(async () => undefined),
+    };
+
+    const controller = new ControllerResourceBackendService(
+      resourceType,
+      logger as any,
+      errorBuilder as any,
+      {
+        expressErrorHandler: () => (_err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+          res.status(500).json({ success: false });
+        },
+      } as any,
+      {} as any,
+      authorizationsService as any,
+      {
+        getResourceConfiguration: vi.fn(() => resourceConfiguration),
+      } as any,
+      executionContextCreator as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {
+        hasFileFields: vi.fn(() => true),
+        detectFileFields: vi.fn(() => [{ fieldName: 'attachment' }]),
+      } as any,
+      fileUploadHandler as any,
+      {} as any,
+      {} as any,
+      appConfigService as any,
+    );
+
+    expect(createMulterUploadConfigMock).toHaveBeenCalledWith(expect.objectContaining({
+      maxFileSize: 5,
+    }));
+
+    const uploadRoute = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({
+      operationRouteUrl: updateOperation.initiatorInfos[0].url,
+      operationParameters: updateOperation.initiatorInfos[0].parameters,
+      targetResourceType: resourceType,
+      targetResourceFieldIdentifier: 'todoId',
+      fieldName: 'attachment',
+      requiresTargetResourceId: true,
+      isFrontend: false,
+    });
+
+    const requestPath = resolveBackendUrlPattern(uploadRoute.url, {
+        organizationId: 'org-1',
+        projectId: 'project-1',
+        todoId: 'todo-1',
+      });
+    const router = controller.getRouter() as any;
+    const routeLayer = router.stack.find((layer: any) => {
+      const candidatePath = layer.route?.path;
+      return typeof candidatePath === 'string'
+        && candidatePath.includes('/files/attachment')
+        && candidatePath.includes(':projectId')
+        && candidatePath.includes(':todoId');
+    });
+
+    expect(routeLayer).toBeDefined();
+    expect(routeLayer.route.stack).toHaveLength(3);
+
+    const req = {
+      params: {
+        organizationId: 'org-1',
+        projectId: 'project-1',
+        todoId: 'todo-1',
+      },
+      body: {},
+      method: 'POST',
+      path: requestPath,
+    } as any;
+    const res = {
+      status: vi.fn().mockReturnThis(),
+      json: vi.fn(),
+    } as any;
+
+    await runExpressMiddleware(routeLayer.route.stack[0].handle, req, res);
+    expect(executionContextCreator.createExecutionContextFromRequest).toHaveBeenCalledTimes(1);
+    expect(authorizationsService.authorizeInController).toHaveBeenCalledWith('todo-1', executionContext);
+    await runExpressMiddleware(routeLayer.route.stack[1].handle, req, res);
+    expect(uploadSingleMiddlewareSpy).toHaveBeenCalledTimes(1);
+    const asyncErrors: unknown[] = [];
+    routeLayer.route.stack[2].handle(req, res, (error?: unknown) => {
+      if (error) {
+        asyncErrors.push(error);
+      }
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(asyncErrors).toEqual([]);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({ success: true });
+    expect(executionContextCreator.createExecutionContextFromRequest).toHaveBeenCalledWith(
+      expect.anything(),
+      updateOperation,
+      {
+        url: uploadRoute.url,
+        parameters: uploadRoute.parameters,
+      },
+    );
+    expect(fileUploadHandler.handleFileUpload).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects unauthorized upload requests before multer touches the request body', async () => {
+    uploadSingleMiddlewareSpy.mockClear();
+    const resourceType = 'todos' as ResourceType;
+    const authFailure = new Error('auth failed');
+    const updateOperation = {
+      operationIdentifier: CoreResourceOperation.UPDATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/todos/{todoId}',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'todoId', resourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const createOperation = {
+      operationIdentifier: CoreResourceOperation.CREATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/todos',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+
+    const authorizationsService = {
+      authorizeInController: vi.fn(async () => {
+        throw authFailure;
+      }),
+    };
+    const controller = new ControllerResourceBackendService(
+      resourceType,
+      {
+        debugByType: vi.fn(() => vi.fn()),
+        setDebugTypeLogging: vi.fn(),
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+      } as any,
+      {
+        buildError: vi.fn((type: string) => new Error(String(type))),
+      } as any,
+      {
+        expressErrorHandler: () => (_err: unknown, _req: express.Request, res: express.Response) => {
+          res.status(500).json({ success: false });
+        },
+      } as any,
+      {} as any,
+      authorizationsService as any,
+      {
+        getResourceConfiguration: vi.fn(() => ({
+          resourceIdentifier: resourceType,
+          resourceFieldIdentifier: 'todoId',
+          operations: [createOperation, updateOperation],
+          mainSchema: z.object({}),
+          resourceRelationships: {
+            parentRelationships: [],
+            childRelationships: [],
+            selfRelationships: [],
+          },
+        })),
+      } as any,
+      {
+        createExecutionContextFromRequest: vi.fn(async () => ({
+          requestId: 'req-1',
+          operation: updateOperation,
+          withOperation: (operation: unknown) => ({
+            requestId: 'req-1',
+            operation,
+          }),
+        })),
+      } as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {
+        hasFileFields: vi.fn(() => true),
+        detectFileFields: vi.fn(() => [{ fieldName: 'attachment' }]),
+      } as any,
+      {
+        handleFileUpload: vi.fn(),
+      } as any,
+      {} as any,
+      {} as any,
+      appConfigService as any,
+    );
+
+    const uploadRoute = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({
+      operationRouteUrl: updateOperation.initiatorInfos[0].url,
+      operationParameters: updateOperation.initiatorInfos[0].parameters,
+      targetResourceType: resourceType,
+      targetResourceFieldIdentifier: 'todoId',
+      fieldName: 'attachment',
+      requiresTargetResourceId: true,
+      isFrontend: false,
+    });
+
+    const router = controller.getRouter() as any;
+    const routeLayer = router.stack.find((layer: any) => {
+      const candidatePath = layer.route?.path;
+      return typeof candidatePath === 'string'
+        && candidatePath.includes('/organizations/:organizationId/todos/:todoId/files/attachment');
+    });
+    expect(routeLayer).toBeDefined();
+    expect(routeLayer.route.stack).toHaveLength(3);
+
+    const req = {
+      params: {
+        organizationId: 'org-1',
+        todoId: 'todo-1',
+      },
+      body: {},
+      method: 'POST',
+      path: resolveBackendUrlPattern(uploadRoute.url, {
+        organizationId: 'org-1',
+        todoId: 'todo-1',
+      }),
+    } as any;
+    const res = {
+      locals: {},
+      status: vi.fn().mockReturnThis(),
+      json: vi.fn(),
+    } as any;
+
+    const error = await expectMiddlewareFailure(routeLayer.route.stack[0].handle, req, res);
+
+    expect(error).toBe(authFailure);
+    expect(authorizationsService.authorizeInController).toHaveBeenCalledWith(
+      'todo-1',
+      expect.objectContaining({
+        requestId: 'req-1',
+        operation: updateOperation,
+      }),
+    );
+    expect(uploadSingleMiddlewareSpy).not.toHaveBeenCalled();
+  });
+
+  it('appends the target resource id for registered update upload routes whose operation path omits it', async () => {
+    const resourceType = 'todos' as ResourceType;
+    const updateOperation = {
+      operationIdentifier: CoreResourceOperation.UPDATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/projects/{projectId}/current-todo',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'projectId', resourceType: 'projects' as ResourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const createOperation = {
+      operationIdentifier: CoreResourceOperation.CREATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/projects/{projectId}/todos',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'projectId', resourceType: 'projects' as ResourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+
+    const resourceConfiguration = {
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      operations: [createOperation, updateOperation],
+      mainSchema: z.object({}),
+      resourceRelationships: {
+        parentRelationships: [],
+        childRelationships: [],
+        selfRelationships: [],
+      },
+    } as any;
+
+    const logger = {
+      debugByType: vi.fn(() => vi.fn()),
+      setDebugTypeLogging: vi.fn(),
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+
+    const errorBuilder = {
+      buildError: vi.fn((type: string, _executionContext: unknown, payload?: Record<string, unknown>) => {
+        const error = new Error(String(type));
+        Object.assign(error, payload);
+        return error;
+      }),
+    };
+
+    const executionContext = {
+      operation: updateOperation,
+      relationshipContexts: [{
+        resourceType: 'projects',
+        relationshipField: 'projectId',
+        resourceId: 'project-1',
+      }],
+      getContextResourceId: vi.fn(),
+    } as any;
+
+    const executionContextCreator = {
+      createExecutionContextFromRequest: vi.fn(async (req: express.Request) => {
+        expect(req.params).toMatchObject({
+          organizationId: 'org-1',
+          projectId: 'project-1',
+          todoId: 'todo-1',
+        });
+        return executionContext;
+      }),
+    };
+
+    const fileUploadHandler = {
+      handleFileUpload: vi.fn(async (
+        req: express.Request,
+        res: express.Response,
+        calledResourceType: ResourceType,
+        fieldName: string,
+        resourceId: string | undefined,
+        operationIdentifier: CoreResourceOperation,
+        calledExecutionContext: unknown,
+      ) => {
+        expect((req as any).file).toMatchObject({
+          originalname: 'upload.txt',
+          mimetype: 'text/plain',
+        });
+        expect(calledResourceType).toBe(resourceType);
+        expect(fieldName).toBe('attachment');
+        expect(resourceId).toBe('todo-1');
+        expect(operationIdentifier).toBe(CoreResourceOperation.UPDATE);
+        expect(calledExecutionContext).toBe(executionContext);
+        res.status(200).json({ success: true });
+      }),
+    };
+    const authorizationsService = {
+      authorizeInController: vi.fn(async () => undefined),
+    };
+
+    const controller = new ControllerResourceBackendService(
+      resourceType,
+      logger as any,
+      errorBuilder as any,
+      {
+        expressErrorHandler: () => (_err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+          res.status(500).json({ success: false });
+        },
+      } as any,
+      {} as any,
+      authorizationsService as any,
+      {
+        getResourceConfiguration: vi.fn(() => resourceConfiguration),
+      } as any,
+      executionContextCreator as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {} as any,
+      {
+        hasFileFields: vi.fn(() => true),
+        detectFileFields: vi.fn(() => [{ fieldName: 'attachment' }]),
+      } as any,
+      fileUploadHandler as any,
+      {} as any,
+      {} as any,
+      appConfigService as any,
+    );
+
+    const uploadRoute = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({
+      operationRouteUrl: updateOperation.initiatorInfos[0].url,
+      operationParameters: updateOperation.initiatorInfos[0].parameters,
+      targetResourceType: resourceType,
+      targetResourceFieldIdentifier: 'todoId',
+      fieldName: 'attachment',
+      requiresTargetResourceId: true,
+      isFrontend: false,
+    });
+
+    expect(uploadRoute.url).toBe(
+      '/api/v1/organizations/{organizationId}/projects/{projectId}/current-todo/{todoId}/files/attachment'
+    );
+    expect(uploadRoute.parameters).toEqual([
+      { fieldIdentifier: 'organizationId', resourceType: 'organizations' },
+      { fieldIdentifier: 'projectId', resourceType: 'projects' },
+      { fieldIdentifier: 'todoId', resourceType },
+    ]);
+
+    const requestPath = resolveBackendUrlPattern(uploadRoute.url, {
+      organizationId: 'org-1',
+      projectId: 'project-1',
+      todoId: 'todo-1',
+    });
+    const router = controller.getRouter() as any;
+    const routeLayer = router.stack.find((layer: any) => {
+      const candidatePath = layer.route?.path;
+      return typeof candidatePath === 'string'
+        && candidatePath.includes('/current-todo/:todoId/files/attachment')
+        && candidatePath.includes(':projectId');
+    });
+
+    expect(routeLayer).toBeDefined();
+    expect(routeLayer.route.stack).toHaveLength(3);
+
+    const req = {
+      params: {
+        organizationId: 'org-1',
+        projectId: 'project-1',
+        todoId: 'todo-1',
+      },
+      body: {},
+      method: 'POST',
+      path: requestPath,
+    } as any;
+    const res = {
+      locals: {},
+      status: vi.fn().mockReturnThis(),
+      json: vi.fn(),
+    } as any;
+
+    await runExpressMiddleware(routeLayer.route.stack[0].handle, req, res);
+    expect(authorizationsService.authorizeInController).toHaveBeenCalledWith('todo-1', executionContext);
+    await runExpressMiddleware(routeLayer.route.stack[1].handle, req, res);
+    const asyncErrors: unknown[] = [];
+    routeLayer.route.stack[2].handle(req, res, (error?: unknown) => {
+      if (error) {
+        asyncErrors.push(error);
+      }
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+
+    expect(asyncErrors).toEqual([]);
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({ success: true });
+    expect(executionContextCreator.createExecutionContextFromRequest).toHaveBeenCalledWith(
+      expect.anything(),
+      updateOperation,
+      {
+        url: uploadRoute.url,
+        parameters: uploadRoute.parameters,
+      },
+    );
+    expect(fileUploadHandler.handleFileUpload).toHaveBeenCalledTimes(1);
+  });
+
+  it('denies the registered nested upload route when the forwarded relationship context does not satisfy authorization', async () => {
+    uploadSingleMiddlewareSpy.mockClear();
+    const resourceType = 'todos' as ResourceType;
+    const todoId = '507f1f77bcf86cd799439011';
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'controller-upload-route-'));
+    const tempFilePath = path.join(tempDir, 'upload.txt');
+    fs.writeFileSync(tempFilePath, 'hello world');
+    const updateOperation = {
+      operationIdentifier: CoreResourceOperation.UPDATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/projects/{projectId}/todos/{todoId}',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'projectId', resourceType: 'projects' as ResourceType },
+          { fieldIdentifier: 'todoId', resourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const createOperation = {
+      operationIdentifier: CoreResourceOperation.CREATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/projects/{projectId}/todos',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'projectId', resourceType: 'projects' as ResourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const resourceConfiguration = {
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      operations: [createOperation, updateOperation],
+      mainSchema: z.object({}),
+      resourceRelationships: {
+        parentRelationships: [],
+        childRelationships: [],
+        selfRelationships: [],
+      },
+    } as any;
+    const logger = {
+      debugByType: vi.fn(() => vi.fn()),
+      setDebugTypeLogging: vi.fn(),
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+    const errorBuilder = {
+      buildError: vi.fn((type: string, _executionContext: unknown, payload?: { context?: { message?: string } }) => {
+        throw new Error(payload?.context?.message ?? String(type));
+      }),
+    };
+    const filesService = {
+      createFile: vi.fn(async () => ({
+        fileId: 'file-1',
+        storageKey: 'orgs/org-1/file-1',
+      })),
+      updateFileStatus: vi.fn(async (_fileId: string, status: FileStatus) => ({
+        fileId: 'file-1',
+        storageKey: 'orgs/org-1/file-1',
+        status,
+      })),
+      toMetadataResponse: vi.fn((file: { fileId: string; status: FileStatus }) => ({
+        fileId: file.fileId,
+        status: file.status,
+      })),
+      failFile: vi.fn(),
+    };
+    const authorizationsService = {
+      authorizeInController: vi.fn(async (_resourceId: string | undefined, executionContext: any) => {
+        const hasExpectedProject = executionContext.relationshipContexts?.some(
+          (context: { resourceType?: string; resourceId?: string }) =>
+            context.resourceType === 'projects' && context.resourceId === 'project-1',
+        );
+        if (!hasExpectedProject) {
+          throw new Error('nested project authorization denied');
+        }
+      }),
+    };
+    const uploadHandler = new ResourceFileUploadHandlerBackendService(
+      logger as any,
+      errorBuilder as any,
+      {
+        getResourceConfiguration: vi.fn(() => ({
+          resourcePrimaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+        })),
+      } as any,
+      {
+        resolve: vi.fn(async () => ({ maxSizeInBytes: 5_000_000 })),
+      } as any,
+      {
+        validateFile: vi.fn(async () => ({ success: true, errors: [] })),
+      } as any,
+      filesService as any,
+      {
+        uploadStream: vi.fn(async () => undefined),
+      } as any,
+      {
+        getInitiatorId: vi.fn((executionContext: { initiatorIds?: { userId?: string } }) => executionContext.initiatorIds?.userId),
+      } as any,
+      appConfigService as any,
+    );
+
+    const existsSpy = vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+    const streamSpy = vi.spyOn(fs, 'createReadStream').mockImplementation(() => new PassThrough() as any);
+
+    try {
+      const executionContextCreator = {
+        createExecutionContextFromRequest: vi.fn(async () => ({
+          operation: updateOperation,
+          initiatorIds: {
+            organizationId: 'org-1',
+            userId: 'user-1',
+          },
+          relationshipContexts: [],
+        })),
+      };
+
+      const controller = new ControllerResourceBackendService(
+        resourceType,
+        logger as any,
+        errorBuilder as any,
+        {
+          expressErrorHandler: () => (_err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+            res.status(500).json({ success: false });
+          },
+        } as any,
+        {} as any,
+        authorizationsService as any,
+        {
+          getResourceConfiguration: vi.fn(() => resourceConfiguration),
+        } as any,
+        executionContextCreator as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        {
+          hasFileFields: vi.fn(() => true),
+          detectFileFields: vi.fn(() => [{ fieldName: 'attachment' }]),
+        } as any,
+        uploadHandler as any,
+        {} as any,
+        {} as any,
+        appConfigService as any,
+      );
+
+      const uploadRoute = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({
+        operationRouteUrl: updateOperation.initiatorInfos[0].url,
+        operationParameters: updateOperation.initiatorInfos[0].parameters,
+        targetResourceType: resourceType,
+        targetResourceFieldIdentifier: 'todoId',
+        fieldName: 'attachment',
+        requiresTargetResourceId: true,
+        isFrontend: false,
+      });
+
+      const router = controller.getRouter() as any;
+      const routeLayer = router.stack.find((layer: any) => {
+        const candidatePath = layer.route?.path;
+        return typeof candidatePath === 'string'
+          && candidatePath.includes('/files/attachment')
+          && candidatePath.includes(':projectId')
+          && candidatePath.includes(':todoId');
+      });
+
+      expect(routeLayer).toBeDefined();
+
+      const req = {
+        params: {
+          organizationId: 'org-1',
+          projectId: 'project-1',
+          todoId,
+        },
+        body: {},
+        method: 'POST',
+        path: resolveBackendUrlPattern(uploadRoute.url, {
+          organizationId: 'org-1',
+          projectId: 'project-1',
+          todoId,
+        }),
+        file: {
+          fieldname: 'file',
+          originalname: 'upload.txt',
+          mimetype: 'text/plain',
+          size: 11,
+          filename: 'upload.txt',
+          path: tempFilePath,
+        },
+      } as any;
+      const res = {
+        locals: {},
+        status: vi.fn().mockReturnThis(),
+        json: vi.fn(),
+      } as any;
+
+      const error = await expectMiddlewareFailure(routeLayer.route.stack[0].handle, req, res);
+
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toBe('nested project authorization denied');
+      expect(authorizationsService.authorizeInController).toHaveBeenCalledWith(todoId, expect.objectContaining({
+        relationshipContexts: [],
+      }));
+      expect(filesService.createFile).not.toHaveBeenCalled();
+      expect(uploadSingleMiddlewareSpy).not.toHaveBeenCalled();
+      expect(res.status).not.toHaveBeenCalledWith(200);
+    } finally {
+      existsSpy.mockRestore();
+      streamSpy.mockRestore();
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('denies the appended-id upload route when the forwarded relationship context does not satisfy authorization', async () => {
+    uploadSingleMiddlewareSpy.mockClear();
+    const resourceType = 'todos' as ResourceType;
+    const todoId = '507f1f77bcf86cd799439012';
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'controller-upload-route-appended-'));
+    const tempFilePath = path.join(tempDir, 'upload.txt');
+    fs.writeFileSync(tempFilePath, 'hello world');
+    const updateOperation = {
+      operationIdentifier: CoreResourceOperation.UPDATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/projects/{projectId}/current-todo',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'projectId', resourceType: 'projects' as ResourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const createOperation = {
+      operationIdentifier: CoreResourceOperation.CREATE,
+      variantType: ResourceOperationVariantType.API_CALL,
+      isOperationDefault: true,
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      initiatorInfos: [{
+        url: '/api/v1/organizations/{organizationId}/projects/{projectId}/todos',
+        parameters: [
+          { fieldIdentifier: 'organizationId', resourceType: 'organizations' as ResourceType },
+          { fieldIdentifier: 'projectId', resourceType: 'projects' as ResourceType },
+        ],
+      }],
+      requestDto: z.object({}),
+      mainSchema: z.object({}),
+      roles: [],
+    } as any;
+    const resourceConfiguration = {
+      resourceIdentifier: resourceType,
+      resourceFieldIdentifier: 'todoId',
+      operations: [createOperation, updateOperation],
+      mainSchema: z.object({}),
+      resourceRelationships: {
+        parentRelationships: [],
+        childRelationships: [],
+        selfRelationships: [],
+      },
+    } as any;
+    const logger = {
+      debugByType: vi.fn(() => vi.fn()),
+      setDebugTypeLogging: vi.fn(),
+      debug: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+    };
+    const errorBuilder = {
+      buildError: vi.fn((type: string, _executionContext: unknown, payload?: { context?: { message?: string } }) => {
+        throw new Error(payload?.context?.message ?? String(type));
+      }),
+    };
+    const filesService = {
+      createFile: vi.fn(async () => ({
+        fileId: 'file-1',
+        storageKey: 'orgs/org-1/file-1',
+      })),
+      updateFileStatus: vi.fn(async (_fileId: string, status: FileStatus) => ({
+        fileId: 'file-1',
+        storageKey: 'orgs/org-1/file-1',
+        status,
+      })),
+      toMetadataResponse: vi.fn((file: { fileId: string; status: FileStatus }) => ({
+        fileId: file.fileId,
+        status: file.status,
+      })),
+      failFile: vi.fn(),
+    };
+    const authorizationsService = {
+      authorizeInController: vi.fn(async (_resourceId: string | undefined, executionContext: any) => {
+        const hasExpectedProject = executionContext.relationshipContexts?.some(
+          (context: { resourceType?: string; resourceId?: string }) =>
+            context.resourceType === 'projects' && context.resourceId === 'project-1',
+        );
+        if (!hasExpectedProject) {
+          throw new Error('nested project authorization denied');
+        }
+      }),
+    };
+    const uploadHandler = new ResourceFileUploadHandlerBackendService(
+      logger as any,
+      errorBuilder as any,
+      {
+        getResourceConfiguration: vi.fn(() => ({
+          resourcePrimaryScope: ResourcePrimaryScope.ORGANIZATIONS,
+        })),
+      } as any,
+      {
+        resolve: vi.fn(async () => ({ maxSizeInBytes: 5_000_000 })),
+      } as any,
+      {
+        validateFile: vi.fn(async () => ({ success: true, errors: [] })),
+      } as any,
+      filesService as any,
+      {
+        uploadStream: vi.fn(async () => undefined),
+      } as any,
+      {
+        getInitiatorId: vi.fn((executionContext: { initiatorIds?: { userId?: string } }) => executionContext.initiatorIds?.userId),
+      } as any,
+      appConfigService as any,
+    );
+
+    const existsSpy = vi.spyOn(fs, 'existsSync').mockReturnValue(true);
+    const streamSpy = vi.spyOn(fs, 'createReadStream').mockImplementation(() => new PassThrough() as any);
+
+    try {
+      const executionContextCreator = {
+        createExecutionContextFromRequest: vi.fn(async () => ({
+          operation: updateOperation,
+          initiatorIds: {
+            organizationId: 'org-1',
+            userId: 'user-1',
+          },
+          relationshipContexts: [],
+        })),
+      };
+
+      const controller = new ControllerResourceBackendService(
+        resourceType,
+        logger as any,
+        errorBuilder as any,
+        {
+          expressErrorHandler: () => (_err: unknown, _req: express.Request, res: express.Response, _next: express.NextFunction) => {
+            res.status(500).json({ success: false });
+          },
+        } as any,
+        {} as any,
+        authorizationsService as any,
+        {
+          getResourceConfiguration: vi.fn(() => resourceConfiguration),
+        } as any,
+        executionContextCreator as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        {} as any,
+        {
+          hasFileFields: vi.fn(() => true),
+          detectFileFields: vi.fn(() => [{ fieldName: 'attachment' }]),
+        } as any,
+        uploadHandler as any,
+        {} as any,
+        {} as any,
+        appConfigService as any,
+      );
+
+      const uploadRoute = ResourcesConfigOperationsUrlsBuilderUtils.buildFileUploadRouteForOperation({
+        operationRouteUrl: updateOperation.initiatorInfos[0].url,
+        operationParameters: updateOperation.initiatorInfos[0].parameters,
+        targetResourceType: resourceType,
+        targetResourceFieldIdentifier: 'todoId',
+        fieldName: 'attachment',
+        requiresTargetResourceId: true,
+        isFrontend: false,
+      });
+
+      const router = controller.getRouter() as any;
+      const routeLayer = router.stack.find((layer: any) => {
+        const candidatePath = layer.route?.path;
+        return typeof candidatePath === 'string'
+          && candidatePath.includes('/current-todo/:todoId/files/attachment')
+          && candidatePath.includes(':projectId');
+      });
+
+      expect(routeLayer).toBeDefined();
+
+      const req = {
+        params: {
+          organizationId: 'org-1',
+          projectId: 'project-1',
+          todoId,
+        },
+        body: {},
+        method: 'POST',
+        path: resolveBackendUrlPattern(uploadRoute.url, {
+          organizationId: 'org-1',
+          projectId: 'project-1',
+          todoId,
+        }),
+        file: {
+          fieldname: 'file',
+          originalname: 'upload.txt',
+          mimetype: 'text/plain',
+          size: 11,
+          filename: 'upload.txt',
+          path: tempFilePath,
+        },
+      } as any;
+      const res = {
+        locals: {},
+        status: vi.fn().mockReturnThis(),
+        json: vi.fn(),
+      } as any;
+
+      const error = await expectMiddlewareFailure(routeLayer.route.stack[0].handle, req, res);
+
+      expect(error).toBeInstanceOf(Error);
+      expect((error as Error).message).toBe('nested project authorization denied');
+      expect(authorizationsService.authorizeInController).toHaveBeenCalledWith(todoId, expect.objectContaining({
+        relationshipContexts: [],
+      }));
+      expect(filesService.createFile).not.toHaveBeenCalled();
+      expect(uploadSingleMiddlewareSpy).not.toHaveBeenCalled();
+      expect(res.status).not.toHaveBeenCalledWith(200);
+    } finally {
+      existsSpy.mockRestore();
+      streamSpy.mockRestore();
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+});