From a47cbc429c9c3961d7ef345721e6ebb30e58366c Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:44:18 +0000 Subject: [PATCH 1/4] fix(api): reject ambiguous file input combinations (#9435) Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- lib/Controller/FileController.php | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/lib/Controller/FileController.php b/lib/Controller/FileController.php index 5e4228745c..503d4ca5aa 100644 --- a/lib/Controller/FileController.php +++ b/lib/Controller/FileController.php @@ -571,7 +571,9 @@ private function getMimeFallbackResponse(string $mimeType): ?\OCP\AppFramework\H * Send a file * * Send a new file to Nextcloud and return the fileId used to create a signature request. - * Files must be uploaded as multipart/form-data with field name 'file[]' or 'files[]'. + * File references can be sent as JSON using 'file' (single) or 'files' (list). + * Binary files use multipart/form-data: 'file' for one file, 'files[]' for several; + * the legacy 'file[]' field is also accepted. Do not combine these input forms. * Multipart clients can send optional expectedFilesCount to reject incomplete batches. * * **Note on multiple file uploads:** @@ -602,9 +604,10 @@ public function save( try { $this->signingRequestValidator->canRequestSign($this->userSession->getUser()); - $uploadedFiles = $this->request->getUploadedFile('files') ?: $this->request->getUploadedFile('file'); - $normalizedFiles = $this->prepareFilesForSaving($file, $files, $settings, $uploadedFiles); - if ($uploadedFiles) { + $singleUploadedFile = $this->request->getUploadedFile('file'); + $multipleUploadedFiles = $this->request->getUploadedFile('files'); + $normalizedFiles = $this->prepareFilesForSaving($file, $files, $settings, $singleUploadedFile, $multipleUploadedFiles); + if ($singleUploadedFile || $multipleUploadedFiles) { $this->assertExpectedUploadedFileCount(count($normalizedFiles)); } @@ -757,7 +760,15 @@ private function prepareFileForSaving(array $fileData, string $name, array $sett /** * @return list Normalized files array */ - private function prepareFilesForSaving(array $file, array $files, array $settings, ?array $uploadedFiles): array { + private function prepareFilesForSaving(array $file, array $files, array $settings, ?array $singleUploadedFile, ?array $multipleUploadedFiles): array { + if (($file && $files) + || ($singleUploadedFile && $multipleUploadedFiles) + || (($file || $files) && ($singleUploadedFile || $multipleUploadedFiles))) { + // TRANSLATORS Error shown when a file upload mixes mutually exclusive input formats. + throw new LibresignException($this->l10n->t('Use only one file input format per request')); + } + + $uploadedFiles = $multipleUploadedFiles ?: $singleUploadedFile; if ($uploadedFiles) { return $this->processUploadedFiles($uploadedFiles); } From a0bf9e256b414ae61b8aae2e91e2c7ece35b751e Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:45:02 +0000 Subject: [PATCH 2/4] test(api): cover mutually exclusive file input formats (#9435) Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .../FileControllerInputSourceTest.php | 144 ++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 tests/php/Unit/Controller/FileControllerInputSourceTest.php diff --git a/tests/php/Unit/Controller/FileControllerInputSourceTest.php b/tests/php/Unit/Controller/FileControllerInputSourceTest.php new file mode 100644 index 0000000000..d5a65ea478 --- /dev/null +++ b/tests/php/Unit/Controller/FileControllerInputSourceTest.php @@ -0,0 +1,144 @@ + $name, + 'tmp_name' => '/tmp/upload-placeholder', + 'type' => 'application/pdf', + 'size' => 3, + 'error' => UPLOAD_ERR_OK, + ]; + } + + private static function batch(): array { + return [ + 'name' => ['first.pdf', 'second.pdf'], + 'tmp_name' => ['/tmp/first', '/tmp/second'], + 'type' => ['application/pdf', 'application/pdf'], + 'size' => [3, 4], + 'error' => [UPLOAD_ERR_OK, UPLOAD_ERR_OK], + ]; + } + + public static function acceptedInputs(): array { + return [ + 'JSON single reference' => [['nodeId' => 1], [], null, null, [['nodeId' => 1]]], + 'JSON reference list' => [[], [['nodeId' => 1], ['nodeId' => 2]], null, null, [['nodeId' => 1], ['nodeId' => 2]]], + 'single multipart file' => [[], [], self::upload('one.pdf'), null, [ + ['uploadedFile' => self::upload('one.pdf'), 'name' => 'one'], + ]], + 'multipart list under files' => [[], [], null, self::batch(), [ + ['uploadedFile' => self::uploadFromBatch(0), 'name' => 'first'], + ['uploadedFile' => self::uploadFromBatch(1), 'name' => 'second'], + ]], + 'legacy multipart list under file' => [[], [], self::batch(), null, [ + ['uploadedFile' => self::uploadFromBatch(0), 'name' => 'first'], + ['uploadedFile' => self::uploadFromBatch(1), 'name' => 'second'], + ]], + ]; + } + + private static function uploadFromBatch(int $index): array { + $batch = self::batch(); + return array_map(static fn (array $column): mixed => $column[$index], $batch); + } + + public static function conflictingInputs(): array { + return [ + 'both JSON forms' => [['nodeId' => 1], [['nodeId' => 2]], null, null], + 'both multipart fields' => [[], [], self::upload('one.pdf'), self::batch()], + 'JSON file plus multipart file' => [['nodeId' => 1], [], self::upload('one.pdf'), null], + 'JSON files plus multipart files' => [[], [['nodeId' => 1]], null, self::batch()], + ]; + } + + private function controller(): FileController { + $reflection = new ReflectionClass(FileController::class); + /** @var FileController $controller */ + $controller = $reflection->newInstanceWithoutConstructor(); + + $l10n = $this->createMock(IL10N::class); + $l10n->method('t')->willReturnCallback(static fn (string $message): string => $message); + $reflection->getProperty('l10n')->setValue($controller, $l10n); + + $fileService = $this->createMock(FileService::class); + $reflection->getProperty('fileService')->setValue($controller, $fileService); + + $validator = $this->createMock(FileInputValidator::class); + $validator->method('normalizeNodeId')->willReturnCallback(static fn (array $file): array => $file); + $reflection->getProperty('fileInputValidator')->setValue($controller, $validator); + return $controller; + } + + #[DataProvider('acceptedInputs')] + public function testAcceptsOneFileInputSource(array $file, array $files, ?array $singleUpload, ?array $batchUpload, array $expected): void { + $controller = $this->controller(); + $result = (new ReflectionMethod(FileController::class, 'prepareFilesForSaving')) + ->invoke($controller, $file, $files, [], $singleUpload, $batchUpload); + self::assertSame($expected, $result); + } + + #[DataProvider('conflictingInputs')] + public function testRejectsAmbiguousFileInputs(array $file, array $files, ?array $singleUpload, ?array $batchUpload): void { + $controller = $this->controller(); + $this->expectException(LibresignException::class); + $this->expectExceptionMessage('Use only one file input format per request'); + (new ReflectionMethod(FileController::class, 'prepareFilesForSaving')) + ->invoke($controller, $file, $files, [], $singleUpload, $batchUpload); + } + + public function testConflictingMultipartInputReturns422WithoutSaving(): void { + $controller = $this->controller(); + $reflection = new ReflectionClass(FileController::class); + + $request = $this->createMock(IRequest::class); + $request->method('getUploadedFile')->willReturnMap([ + ['file', self::upload('one.pdf')], + ['files', self::batch()], + ]); + $reflection->getProperty('request')->setValue($controller, $request); + + $user = $this->createMock(IUser::class); + $userSession = $this->createMock(IUserSession::class); + $userSession->method('getUser')->willReturn($user); + $reflection->getProperty('userSession')->setValue($controller, $userSession); + + $signingValidator = $this->createMock(SigningRequestValidator::class); + $signingValidator->expects($this->once())->method('canRequestSign')->with($user); + $reflection->getProperty('signingRequestValidator')->setValue($controller, $signingValidator); + + $requestSignatureService = $this->createMock(RequestSignatureService::class); + $requestSignatureService->expects($this->never())->method('saveFiles'); + $reflection->getProperty('requestSignatureService')->setValue($controller, $requestSignatureService); + + $response = $controller->save(); + self::assertSame(Http::STATUS_UNPROCESSABLE_ENTITY, $response->getStatus()); + self::assertSame('Use only one file input format per request', $response->getData()['message']); + } +} From c21cbaa392eacf0ef59a97e82346c7694a61cf22 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:48:12 +0000 Subject: [PATCH 3/4] chore(openapi): regenerate file-save descriptions (#9435) Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- openapi-full.json | 2 +- openapi.json | 2 +- src/types/openapi/openapi-full.ts | 2 +- src/types/openapi/openapi.ts | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/openapi-full.json b/openapi-full.json index 35b5e8b95a..322fd4425f 100644 --- a/openapi-full.json +++ b/openapi-full.json @@ -6613,7 +6613,7 @@ "post": { "operationId": "file-save", "summary": "Send a file", - "description": "Send a new file to Nextcloud and return the fileId used to create a signature request. Files must be uploaded as multipart/form-data with field name 'file[]' or 'files[]'. Multipart clients can send optional expectedFilesCount to reject incomplete batches.\n**Note on multiple file uploads:** PHP has a limit on the number of files that can be uploaded in a single request (max_file_uploads directive, default 20). When uploading many files (more than 20), consider uploading them sequentially in multiple requests or use individual file uploads like the Files app does.", + "description": "Send a new file to Nextcloud and return the fileId used to create a signature request. File references can be sent as JSON using 'file' (single) or 'files' (list). Binary files use multipart/form-data: 'file' for one file, 'files[]' for several; the legacy 'file[]' field is also accepted. Do not combine these input forms. Multipart clients can send optional expectedFilesCount to reject incomplete batches.\n**Note on multiple file uploads:** PHP has a limit on the number of files that can be uploaded in a single request (max_file_uploads directive, default 20). When uploading many files (more than 20), consider uploading them sequentially in multiple requests or use individual file uploads like the Files app does.", "tags": [ "documents" ], diff --git a/openapi.json b/openapi.json index 40fcf6249c..b0fe478181 100644 --- a/openapi.json +++ b/openapi.json @@ -6071,7 +6071,7 @@ "post": { "operationId": "file-save", "summary": "Send a file", - "description": "Send a new file to Nextcloud and return the fileId used to create a signature request. Files must be uploaded as multipart/form-data with field name 'file[]' or 'files[]'. Multipart clients can send optional expectedFilesCount to reject incomplete batches.\n**Note on multiple file uploads:** PHP has a limit on the number of files that can be uploaded in a single request (max_file_uploads directive, default 20). When uploading many files (more than 20), consider uploading them sequentially in multiple requests or use individual file uploads like the Files app does.", + "description": "Send a new file to Nextcloud and return the fileId used to create a signature request. File references can be sent as JSON using 'file' (single) or 'files' (list). Binary files use multipart/form-data: 'file' for one file, 'files[]' for several; the legacy 'file[]' field is also accepted. Do not combine these input forms. Multipart clients can send optional expectedFilesCount to reject incomplete batches.\n**Note on multiple file uploads:** PHP has a limit on the number of files that can be uploaded in a single request (max_file_uploads directive, default 20). When uploading many files (more than 20), consider uploading them sequentially in multiple requests or use individual file uploads like the Files app does.", "tags": [ "documents" ], diff --git a/src/types/openapi/openapi-full.ts b/src/types/openapi/openapi-full.ts index b4d5ac4b72..9217014bfe 100644 --- a/src/types/openapi/openapi-full.ts +++ b/src/types/openapi/openapi-full.ts @@ -308,7 +308,7 @@ export type paths = { put?: never; /** * Send a file - * @description Send a new file to Nextcloud and return the fileId used to create a signature request. Files must be uploaded as multipart/form-data with field name 'file[]' or 'files[]'. Multipart clients can send optional expectedFilesCount to reject incomplete batches. + * @description Send a new file to Nextcloud and return the fileId used to create a signature request. File references can be sent as JSON using 'file' (single) or 'files' (list). Binary files use multipart/form-data: 'file' for one file, 'files[]' for several; the legacy 'file[]' field is also accepted. Do not combine these input forms. Multipart clients can send optional expectedFilesCount to reject incomplete batches. * **Note on multiple file uploads:** PHP has a limit on the number of files that can be uploaded in a single request (max_file_uploads directive, default 20). When uploading many files (more than 20), consider uploading them sequentially in multiple requests or use individual file uploads like the Files app does. */ post: operations["file-save"]; diff --git a/src/types/openapi/openapi.ts b/src/types/openapi/openapi.ts index a1815b1662..8595d7c47d 100644 --- a/src/types/openapi/openapi.ts +++ b/src/types/openapi/openapi.ts @@ -308,7 +308,7 @@ export type paths = { put?: never; /** * Send a file - * @description Send a new file to Nextcloud and return the fileId used to create a signature request. Files must be uploaded as multipart/form-data with field name 'file[]' or 'files[]'. Multipart clients can send optional expectedFilesCount to reject incomplete batches. + * @description Send a new file to Nextcloud and return the fileId used to create a signature request. File references can be sent as JSON using 'file' (single) or 'files' (list). Binary files use multipart/form-data: 'file' for one file, 'files[]' for several; the legacy 'file[]' field is also accepted. Do not combine these input forms. Multipart clients can send optional expectedFilesCount to reject incomplete batches. * **Note on multiple file uploads:** PHP has a limit on the number of files that can be uploaded in a single request (max_file_uploads directive, default 20). When uploading many files (more than 20), consider uploading them sequentially in multiple requests or use individual file uploads like the Files app does. */ post: operations["file-save"]; From 1e037b729c847ce4c20402a1951e21ffda4e6459 Mon Sep 17 00:00:00 2001 From: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> Date: Sat, 14 Nov 2026 17:51:32 +0000 Subject: [PATCH 4/4] test(api): compare multipart metadata independently of key insertion order (#9435) Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com> --- .../Unit/Controller/FileControllerInputSourceTest.php | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/tests/php/Unit/Controller/FileControllerInputSourceTest.php b/tests/php/Unit/Controller/FileControllerInputSourceTest.php index d5a65ea478..b18d9da4fc 100644 --- a/tests/php/Unit/Controller/FileControllerInputSourceTest.php +++ b/tests/php/Unit/Controller/FileControllerInputSourceTest.php @@ -101,7 +101,14 @@ public function testAcceptsOneFileInputSource(array $file, array $files, ?array $controller = $this->controller(); $result = (new ReflectionMethod(FileController::class, 'prepareFilesForSaving')) ->invoke($controller, $file, $files, [], $singleUpload, $batchUpload); - self::assertSame($expected, $result); + // PHP file entries are associative maps: key insertion order is not contractual. + $sortUploadKeys = static function (array $entry): array { + if (isset($entry['uploadedFile'])) { + ksort($entry['uploadedFile']); + } + return $entry; + }; + self::assertSame(array_map($sortUploadKeys, $expected), array_map($sortUploadKeys, $result)); } #[DataProvider('conflictingInputs')]