28871954782

Committed 07 Jul 2026 01:58PM UTC coverage: 67.471%. First build

Build # 28871954782

Build Type

Pull #7596

github

Committed by

web-flow

Commit Message

Merge 8c9f94390 into 691b079ec

Pull Request Pull Request #7596: feat: integrate pdf-signature-validator for native validation

Coverage Stats

163 of 232 new or added lines in 3 files covered. (70.26%)

16071 of 23819 relevant lines covered (67.47%)

10.95 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

21.45

/lib/Controller/FileController.php

<?php

declare(strict_types=1);
/**
 * SPDX-FileCopyrightText: 2020-2024 LibreCode coop and contributors
 * SPDX-License-Identifier: AGPL-3.0-or-later
 */

namespace OCA\Libresign\Controller;

use InvalidArgumentException;
use OCA\Files_Sharing\SharedStorage;
use OCA\Libresign\AppInfo\Application;
use OCA\Libresign\Db\FileMapper;
use OCA\Libresign\Db\SignRequestMapper;
use OCA\Libresign\Enum\FileStatus;
use OCA\Libresign\Exception\LibresignException;
use OCA\Libresign\Helper\JSActions;
use OCA\Libresign\Helper\ValidateHelper;
use OCA\Libresign\Middleware\Attribute\PrivateValidation;
use OCA\Libresign\Middleware\Attribute\RequireFileAccess;
use OCA\Libresign\Middleware\Attribute\RequireManager;
use OCA\Libresign\Service\AccountService;
use OCA\Libresign\Service\File\FileListService;
use OCA\Libresign\Service\File\SettingsLoader;
use OCA\Libresign\Service\FileService;
use OCA\Libresign\Service\Policy\ValidationEffectivePolicyService;
use OCA\Libresign\Service\RequestSignatureService;
use OCA\Libresign\Service\SessionService;
use OCP\AppFramework\Db\DoesNotExistException;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\Attribute\ApiRoute;
use OCP\AppFramework\Http\Attribute\NoAdminRequired;
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
use OCP\AppFramework\Http\Attribute\PublicPage;
use OCP\AppFramework\Http\DataResponse;
use OCP\AppFramework\Http\FileDisplayResponse;
use OCP\AppFramework\Http\RedirectResponse;
use OCP\Files\File;
use OCP\Files\Node;
use OCP\Files\NotFoundException;
use OCP\IL10N;
use OCP\IPreview;
use OCP\IRequest;
use OCP\IURLGenerator;
use OCP\IUserSession;
use OCP\Preview\IMimeIconProvider;
use Psr\Log\LoggerInterface;

/**
 * @psalm-import-type LibresignFile from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignDetailedFile from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignDetailedFileResponse from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignActionErrorResponse from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignFileListResponse from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignMessageResponse from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignFileSummary from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignFolderSettings from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignNewFile from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignPagination from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignSettings from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignValidatedFile from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignValidatedFileResponse from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignEffectivePolicyState from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignValidateMetadata from \OCA\Libresign\ResponseDefinitions
 * @psalm-import-type LibresignVisibleElement from \OCA\Libresign\ResponseDefinitions
 */
class FileController extends AEnvironmentAwareController {
        public function __construct(
                IRequest $request,
                private IL10N $l10n,
                private LoggerInterface $logger,
                private IUserSession $userSession,
                private SessionService $sessionService,
                private SignRequestMapper $signRequestMapper,
                private FileMapper $fileMapper,
                private RequestSignatureService $requestSignatureService,
                private AccountService $accountService,
                private ValidationEffectivePolicyService $validationEffectivePolicyService,
                private IPreview $preview,
                private IMimeIconProvider $mimeIconProvider,
                private FileService $fileService,
                private FileListService $fileListService,
                private ValidateHelper $validateHelper,
                private SettingsLoader $settingsLoader,
                private IURLGenerator $urlGenerator,
        ) {
                parent::__construct(Application::APP_ID, $request);
        }

        /**
         * Validate a file using Uuid
         *
         * Validate a file returning file data.
         * The response always includes `filesCount` and `files`.
         * For `nodeType=file`, `filesCount=1` and `files` contains the current file.
         * For `nodeType=envelope`, `files` contains envelope child files.
         *
         * @param string $uuid The UUID of the LibreSign file
         * @param bool $showVisibleElements Whether to include visible elements in the response
         * @param bool $showMessages Whether to include validation messages in the response
         * @param bool $showValidateFile Whether to include the file payload in the response
         * @return DataResponse<Http::STATUS_OK, LibresignValidatedFileResponse, array{}>|DataResponse<Http::STATUS_NOT_FOUND, LibresignActionErrorResponse, array{}>
         *
         * 200: OK
         * 404: Request failed
         * 422: Request failed
         */
        #[PrivateValidation(allowValidSignRequestUuid: true)]
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[PublicPage]
        #[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/file/validate/uuid/{uuid}', requirements: ['apiVersion' => '(v1)'])]
        public function validateUuid(
                string $uuid,
                bool $showVisibleElements = true,
                bool $showMessages = true,
                bool $showValidateFile = true,
        ): DataResponse {
                return $this->validate('Uuid', $uuid, $showVisibleElements, $showMessages, $showValidateFile);
        }

        /**
         * Validate a file using FileId
         *
         * Validate a file returning file data.
         * The response always includes `filesCount` and `files`.
         * For `nodeType=file`, `filesCount=1` and `files` contains the current file.
         * For `nodeType=envelope`, `files` contains envelope child files.
         *
         * @param int $fileId The identifier value of the LibreSign file
         * @param bool $showVisibleElements Whether to include visible elements in the response
         * @param bool $showMessages Whether to include validation messages in the response
         * @param bool $showValidateFile Whether to include the file payload in the response
         * @return DataResponse<Http::STATUS_OK, LibresignValidatedFileResponse, array{}>|DataResponse<Http::STATUS_NOT_FOUND, LibresignActionErrorResponse, array{}>
         *
         * 200: OK
         * 404: Request failed
         * 422: Request failed
         */
        #[PrivateValidation]
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[PublicPage]
        #[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/file/validate/file_id/{fileId}', requirements: ['apiVersion' => '(v1)'])]
        public function validateFileId(
                int $fileId,
                bool $showVisibleElements = true,
                bool $showMessages = true,
                bool $showValidateFile = true,
        ): DataResponse {
                return $this->validate('FileId', $fileId, $showVisibleElements, $showMessages, $showValidateFile);
        }

        /**
         * Validate a binary file
         *
         * Validate a binary file returning file data.
         * Use field 'file' for the file upload.
         * The response always includes `filesCount` and `files`.
         * For `nodeType=file`, `filesCount=1` and `files` contains the current file.
         * For `nodeType=envelope`, `files` contains envelope child files.
         *
         * @return DataResponse<Http::STATUS_OK, LibresignValidatedFileResponse, array{}>|DataResponse<Http::STATUS_NOT_FOUND|Http::STATUS_BAD_REQUEST, LibresignActionErrorResponse, array{}>
         *
         * 200: OK
         * 404: Request failed
         * 400: Request failed
         */
        #[PrivateValidation]
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[PublicPage]
        #[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/file/validate/', requirements: ['apiVersion' => '(v1)'])]
        public function validateBinary(): DataResponse {
                try {
                        $file = $this->request->getUploadedFile('file');
                        /** @var LibresignValidatedFile $validatedFile */
                        $validatedFile = $this->fileService
                                ->setMe($this->userSession->getUser())
                                ->setFileFromRequest($file)
                                ->setHost($this->request->getServerHost())
                                ->showVisibleElements()
                                ->showSigners()
                                ->showSettings()
                                ->showMessages()
                                ->showValidateFile()
                                ->toArray();

                        /** @var LibresignValidatedFileResponse $response */
                        $response = $this->validationEffectivePolicyService->appendEffectivePolicies($validatedFile);

                        return new DataResponse($response, Http::STATUS_OK);
                } catch (InvalidArgumentException $e) {
                        $message = $e->getMessage();
                        /** @var LibresignActionErrorResponse $response */
                        $response = [
                                'action' => JSActions::ACTION_DO_NOTHING,
                                'errors' => [['message' => $message]]
                        ];

                        return new DataResponse($response, Http::STATUS_NOT_FOUND);
                } catch (\Exception $e) {
                        $this->logger->error('Failed to post file to validate', [
                                'exception' => $e,
                        ]);

                        /** @var LibresignActionErrorResponse $response */
                        $response = [
                                'action' => JSActions::ACTION_DO_NOTHING,
                                'errors' => [['message' => $this->l10n->t('Internal error. Contact admin.')]],
                        ];

                        return new DataResponse($response, Http::STATUS_BAD_REQUEST);
                }
        }

        /**
         * Validate a file
         *
         * @param string|null $type The type of identifier could be Uuid or FileId
         * @param string|int $identifier The identifier value, could be string or integer, if UUID will be a string, if FileId will be an integer
         * @return DataResponse<Http::STATUS_OK, LibresignValidatedFileResponse, array{}>|DataResponse<Http::STATUS_NOT_FOUND, LibresignActionErrorResponse, array{}>
         */
        private function validate(
                ?string $type = null,
                $identifier = null,
                bool $showVisibleElements = true,
                bool $showMessages = true,
                bool $showValidateFile = true,
        ): DataResponse {
                try {
                        $signRequest = null;
                        if ($type === 'Uuid' && !empty($identifier)) {
                                try {
                                        $this->fileService->setFileByUuid((string)$identifier);
                                } catch (LibresignException) {
                                        $this->fileService->setFileBySignerUuid((string)$identifier);
                                        $signRequest = $this->signRequestMapper->getBySignerUuidAndUserId((string)$identifier);
                                }
                        } elseif ($type === 'SignerUuid' && !empty($identifier)) {
                                $this->fileService->setFileBySignerUuid((string)$identifier);
                                $signRequest = $this->signRequestMapper->getBySignerUuidAndUserId((string)$identifier);
                        } elseif ($type === 'FileId' && !empty($identifier)) {
                                $this->fileService->setFileById((int)$identifier);
                        } elseif ($this->request->getParam('fileId')) {
                                $this->fileService->setFileById((int)$this->request->getParam('fileId'));
                        } elseif ($this->request->getParam('uuid')) {
                                try {
                                        $this->fileService->setFileByUuid((string)$this->request->getParam('uuid'));
                                } catch (LibresignException) {
                                        $this->fileService->setFileBySignerUuid((string)$this->request->getParam('uuid'));
                                        $signRequest = $this->signRequestMapper->getBySignerUuidAndUserId((string)$this->request->getParam('uuid'));
                                }
                        }

                        if ($signRequest) {
                                $this->fileService->setSignRequest($signRequest);
                        }

                        /** @var LibresignValidatedFile $validatedFile */
                        $validatedFile = $this->fileService
                                ->setMe($this->userSession->getUser())
                                ->setIdentifyMethodId($this->sessionService->getIdentifyMethodId())
                                ->setHost($this->request->getServerHost())
                                ->showVisibleElements($showVisibleElements)
                                ->showSigners()
                                ->showSettings()
                                ->showMessages($showMessages)
                                ->showValidateFile($showValidateFile)
                                ->toArray();

                        /** @var LibresignValidatedFileResponse $response */
                        $response = $this->validationEffectivePolicyService->appendEffectivePolicies($validatedFile);

                        return new DataResponse($response, Http::STATUS_OK);
                } catch (LibresignException $e) {
                        $message = $e->getMessage();
                        /** @var LibresignActionErrorResponse $response */
                        $response = [
                                'action' => JSActions::ACTION_DO_NOTHING,
                                'errors' => [['message' => $message]]
                        ];

                        return new DataResponse($response, Http::STATUS_NOT_FOUND);
                } catch (\Throwable $th) {
                        $this->logger->error($th->getMessage(), ['exception' => $th]);
                        $message = $this->l10n->t('Internal error. Contact admin.');
                        /** @var LibresignActionErrorResponse $response */
                        $response = [
                                'action' => JSActions::ACTION_DO_NOTHING,
                                'errors' => [['message' => $message]]
                        ];

                        return new DataResponse($response, Http::STATUS_NOT_FOUND);
                }
        }

        /**
         * List identification documents that need to be approved
         *
         * @param string|null $signer_uuid Signer UUID
         * @param list<int>|null $fileIds The list of fileIds (database file IDs). It's the ids of LibreSign files
         * @param list<int>|null $nodeIds The list of nodeIds. It's the ids of files at Nextcloud
         * @param list<int>|null $status Status could be none or many of 0 = draft, 1 = able to sign, 2 = partial signed, 3 = signed, 4 = deleted.
         * @param int|null $page the number of page to return
         * @param int|null $length Total of elements to return
         * @param int|null $start Start date of signature request (UNIX timestamp)
         * @param int|null $end End date of signature request (UNIX timestamp)
         * @param string|null $sortBy Name of the column to sort by
         * @param string|null $sortDirection Ascending or descending order
         * @param int|null $parentFileId Filter files by parent envelope file ID
         * @param bool $details Whether to return the detailed payload instead of the lightweight summary payload
         * @return DataResponse<Http::STATUS_OK, LibresignFileListResponse, array{}>
         *
         * 200: OK
         */
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/file/list', requirements: ['apiVersion' => '(v1)'])]
        public function list(
                ?int $page = null,
                ?int $length = null,
                ?string $signer_uuid = null,
                ?array $fileIds = null,
                ?array $nodeIds = null,
                ?array $status = null,
                ?int $start = null,
                ?int $end = null,
                ?string $sortBy = null,
                ?string $sortDirection = null,
                ?int $parentFileId = null,
                bool $details = false,
        ): DataResponse {
                $filter = array_filter([
                        'signer_uuid' => $signer_uuid,
                        'fileIds' => $fileIds,
                        'nodeIds' => $nodeIds,
                        'status' => $status,
                        'start' => $start,
                        'end' => $end,
                        'parentFileId' => $parentFileId,
                ], static fn ($var) => $var !== null);
                $sort = [
                        'sortBy' => $sortBy,
                        'sortDirection' => $sortDirection,
                ];

                $user = $this->userSession->getUser();
                $return = $this->fileListService->listAssociatedFilesOfSignFlow($user, $page, $length, $filter, $sort, $details);

                if ($user) {
                        $return['settings'] = $this->settingsLoader->getUserIdentificationSettings($user);
                }

                return new DataResponse($return, Http::STATUS_OK);
        }

        /**
         * Return the thumbnail of a LibreSign file
         *
         * @param integer $nodeId The nodeId of document
         * @param integer $x Width of generated file
         * @param integer $y Height of generated file
         * @param boolean $a Crop, boolean value, default false
         * @param boolean $forceIcon Force to generate a new thumbnail
         * @param string $mode To force a given mimetype for the file
         * @param boolean $mimeFallback If we have no preview enabled, we can redirect to the mime icon if any
         * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>|RedirectResponse<Http::STATUS_SEE_OTHER, array{}>
         *
         * 200: OK
         * 303: Redirect
         * 400: Bad request
         * 403: Forbidden
         * 404: Not found
         */
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[RequireFileAccess('nodeId')]
        #[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/file/thumbnail/{nodeId}', requirements: ['apiVersion' => '(v1)'])]
        public function getThumbnail(
                int $nodeId = -1,
                int $x = 32,
                int $y = 32,
                bool $a = false,
                bool $forceIcon = true,
                string $mode = 'fill',
                bool $mimeFallback = false,
        ) {
                if ($nodeId === -1 || $x === 0 || $y === 0) {
                        return new DataResponse([], Http::STATUS_BAD_REQUEST);
                }

                try {
                        $libreSignFile = $this->fileMapper->getByNodeId($nodeId);

                        if ($libreSignFile->getNodeType() === 'envelope') {
                                if ($mimeFallback) {
                                        $url = $this->mimeIconProvider->getMimeIconUrl('folder');
                                        if ($url) {
                                                return new RedirectResponse($url);
                                        }
                                }
                                return new DataResponse([], Http::STATUS_NOT_FOUND);
                        }

                        $node = $this->accountService->getPdfByUuid($libreSignFile->getUuid());
                } catch (DoesNotExistException) {
                        return new DataResponse([], Http::STATUS_NOT_FOUND);
                }

                return $this->fetchPreview($node, $x, $y, $a, $forceIcon, $mode, $mimeFallback);
        }

        /**
         * Return the thumbnail of a LibreSign file by fileId
         *
         * @param integer $fileId The LibreSign fileId (database id)
         * @param integer $x Width of generated file
         * @param integer $y Height of generated file
         * @param boolean $a Crop, boolean value, default false
         * @param boolean $forceIcon Force to generate a new thumbnail
         * @param string $mode To force a given mimetype for the file
         * @param boolean $mimeFallback If we have no preview enabled, we can redirect to the mime icon if any
         * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>|RedirectResponse<Http::STATUS_SEE_OTHER, array{}>
         *
         * 200: OK
         * 303: Redirect
         * 400: Bad request
         * 403: Forbidden
         * 404: Not found
         */
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[RequireFileAccess('fileId')]
        #[ApiRoute(verb: 'GET', url: '/api/{apiVersion}/file/thumbnail/file_id/{fileId}', requirements: ['apiVersion' => '(v1)'])]
        public function getThumbnailByFileId(
                int $fileId = -1,
                int $x = 32,
                int $y = 32,
                bool $a = false,
                bool $forceIcon = true,
                string $mode = 'fill',
                bool $mimeFallback = false,
        ) {
                if ($fileId === -1 || $x === 0 || $y === 0) {
                        return new DataResponse([], Http::STATUS_BAD_REQUEST);
                }

                try {
                        $libreSignFile = $this->fileMapper->getById($fileId);

                        if ($libreSignFile->getNodeType() === 'envelope') {
                                if ($mimeFallback) {
                                        $url = $this->mimeIconProvider->getMimeIconUrl('folder');
                                        if ($url) {
                                                return new RedirectResponse($url);
                                        }
                                }
                                return new DataResponse([], Http::STATUS_NOT_FOUND);
                        }

                        $node = $this->accountService->getPdfByUuid($libreSignFile->getUuid());
                } catch (DoesNotExistException) {
                        return new DataResponse([], Http::STATUS_NOT_FOUND);
                }

                return $this->fetchPreview($node, $x, $y, $a, $forceIcon, $mode, $mimeFallback);
        }

        /**
         * @return FileDisplayResponse<Http::STATUS_OK, array{Content-Type: string}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_FORBIDDEN|Http::STATUS_NOT_FOUND, array<empty>, array{}>|RedirectResponse<Http::STATUS_SEE_OTHER, array{}>
         */
        private function fetchPreview(
                Node $node,
                int $x,
                int $y,
                bool $a,
                bool $forceIcon,
                string $mode,
                bool $mimeFallback = false,
        ): Http\Response {
                if (!($node instanceof File) || (!$forceIcon && !$this->preview->isAvailable($node))) {
                        return new DataResponse([], Http::STATUS_NOT_FOUND);
                }
                if (!$node->isReadable()) {
                        return new DataResponse([], Http::STATUS_FORBIDDEN);
                }

                // Avoid expensive external preview generators for PDFs when a mime fallback is explicitly requested.
                if ($mimeFallback && $node->getMimeType() === 'application/pdf') {
                        $mimeFallbackResponse = $this->getMimeFallbackResponse($node->getMimeType());
                        if ($mimeFallbackResponse !== null) {
                                /** @var Http\RedirectResponse<Http::STATUS_SEE_OTHER, array{}> $mimeFallbackResponse */
                                return $mimeFallbackResponse;
                        }
                }

                $storage = $node->getStorage();
                if ($storage->instanceOfStorage(SharedStorage::class)) {
                        /** @var SharedStorage $storage */
                        $share = $storage->getShare();
                        $attributes = $share->getAttributes();
                        if ($attributes !== null && $attributes->getAttribute('permissions', 'download') === false) {
                                return new DataResponse([], Http::STATUS_FORBIDDEN);
                        }
                }

                try {
                        $f = $this->preview->getPreview($node, $x, $y, !$a, $mode);
                        $response = new FileDisplayResponse($f, Http::STATUS_OK, [
                                'Content-Type' => $f->getMimeType(),
                        ]);
                        $response->cacheFor(3600 * 24, false, true);
                        return $response;
                } catch (NotFoundException) {
                        $mimeFallbackResponse = $mimeFallback ? $this->getMimeFallbackResponse($node->getMimeType()) : null;
                        if ($mimeFallbackResponse !== null) {
                                /** @var Http\RedirectResponse<Http::STATUS_SEE_OTHER, array{}> $mimeFallbackResponse */
                                return $mimeFallbackResponse;
                        }

                        return new DataResponse([], Http::STATUS_NOT_FOUND);
                } catch (\InvalidArgumentException) {
                        return new DataResponse([], Http::STATUS_BAD_REQUEST);
                } catch (\Throwable $e) {
                        $this->logger->warning('Failed to generate LibreSign thumbnail preview', [
                                'nodeId' => $node->getId(),
                                'mimeType' => $node->getMimeType(),
                                'exception' => $e,
                        ]);

                        $mimeFallbackResponse = $mimeFallback ? $this->getMimeFallbackResponse($node->getMimeType()) : null;
                        if ($mimeFallbackResponse !== null) {
                                /** @var Http\RedirectResponse<Http::STATUS_SEE_OTHER, array{}> $mimeFallbackResponse */
                                return $mimeFallbackResponse;
                        }

                        return new DataResponse([], Http::STATUS_NOT_FOUND);
                }
        }

        private function getMimeFallbackResponse(string $mimeType): ?\OCP\AppFramework\Http\RedirectResponse {
                $url = $this->mimeIconProvider->getMimeIconUrl($mimeType);
                if ($url) {
                        /** @var \OCP\AppFramework\Http\RedirectResponse<Http::STATUS_SEE_OTHER, array{}> $response */
                        $response = new RedirectResponse($url, Http::STATUS_SEE_OTHER);
                        return $response;
                }

                return null;
        }

        /**
         * 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[]'.
         *
         * **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.
         *
         * @param LibresignNewFile $file File to save
         * @param string $name The name of file to sign
         * @param LibresignFolderSettings $settings Settings to define how and where the file should be stored
         * @param list<LibresignNewFile> $files Multiple files to create an envelope (optional, use either file or files)
         * @return DataResponse<Http::STATUS_OK, LibresignDetailedFileResponse, array{}>|DataResponse<Http::STATUS_UNPROCESSABLE_ENTITY, LibresignMessageResponse, array{}>
         *
         * 200: OK
         * 422: Failed to save data
         */
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[RequireManager]
        #[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/file', requirements: ['apiVersion' => '(v1)'])]
        public function save(
                array $file = [],
                string $name = '',
                array $settings = [],
                array $files = [],
        ): DataResponse {
                try {
                        $this->validateHelper->canRequestSign($this->userSession->getUser());

                        $normalizedFiles = $this->prepareFilesForSaving($file, $files, $settings);

                        return $this->saveFiles($normalizedFiles, $name, $settings);
                } catch (LibresignException $e) {
                        return new DataResponse(
                                [
                                        'message' => $e->getMessage(),
                                ],
                                Http::STATUS_UNPROCESSABLE_ENTITY,
                        );
                }
        }

        /**
         * Add file to envelope
         *
         * Add one or more files to an existing envelope that is in DRAFT status.
         * Files must be uploaded as multipart/form-data with field name 'files[]'.
         *
         * @param string $uuid The UUID of the envelope
         * @return DataResponse<Http::STATUS_OK, LibresignDetailedFileResponse, array{}>|DataResponse<Http::STATUS_BAD_REQUEST|Http::STATUS_NOT_FOUND|Http::STATUS_UNPROCESSABLE_ENTITY, LibresignMessageResponse, array{}>
         *
         * 200: Files added successfully
         * 400: Invalid request
         * 404: Envelope not found
         * 422: Cannot add files (envelope not in DRAFT status or validation failed)
         */
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[RequireManager]
        #[ApiRoute(verb: 'POST', url: '/api/{apiVersion}/file/{uuid}/add-file', requirements: ['apiVersion' => '(v1)'])]
        public function addFileToEnvelope(string $uuid): DataResponse {
                try {
                        $this->validateHelper->canRequestSign($this->userSession->getUser());

                        $envelope = $this->fileMapper->getByUuid($uuid);

                        if ($envelope->getNodeType() !== 'envelope') {
                                throw new LibresignException($this->l10n->t('This is not an envelope'));
                        }

                        if ($envelope->getStatus() !== FileStatus::DRAFT->value) {
                                throw new LibresignException($this->l10n->t('Cannot add files to an envelope that is not in draft status'));
                        }

                        $settings = $envelope->getMetadata()['settings'] ?? [];

                        $uploadedFiles = $this->request->getUploadedFile('files');
                        if (!$uploadedFiles) {
                                throw new LibresignException($this->l10n->t('No files uploaded'));
                        }

                        $normalizedFiles = $this->processUploadedFiles($uploadedFiles);

                        $addedFiles = [];
                        foreach ($normalizedFiles as $fileData) {
                                $prepared = $this->prepareFileForSaving($fileData, '', $settings);

                                $childFile = $this->requestSignatureService->save([
                                        'file' => ['fileNode' => $prepared['node']],
                                        'name' => $prepared['name'],
                                        'userManager' => $this->userSession->getUser(),
                                        'status' => FileStatus::DRAFT->value,
                                        'parentFileId' => $envelope->getId(),
                                ]);

                                $addedFiles[] = $childFile;
                        }

                        $this->fileService->updateEnvelopeFilesCount($envelope, count($addedFiles));

                        $envelope = $this->fileMapper->getById($envelope->getId());
                        $response = $this->fileListService->formatFileWithChildren($envelope, $addedFiles, $this->userSession->getUser());
                        return new DataResponse($response, Http::STATUS_OK);
                } catch (DoesNotExistException) {
                        return new DataResponse(
                                ['message' => $this->l10n->t('Envelope not found')],
                                Http::STATUS_NOT_FOUND,
                        );
                } catch (LibresignException $e) {
                        return new DataResponse(
                                ['message' => $e->getMessage()],
                                Http::STATUS_UNPROCESSABLE_ENTITY,
                        );
                } catch (\Exception $e) {
                        $this->logger->error('Failed to add file to envelope', [
                                'exception' => $e,
                        ]);
                        return new DataResponse(
                                ['message' => $this->l10n->t('Failed to add file to envelope')],
                                Http::STATUS_BAD_REQUEST,
                        );
                }
        }

        /**
         * @return array{node: Node, name: string}
         */
        private function prepareFileForSaving(array $fileData, string $name, array $settings): array {
                if (empty($name)) {
                        $name = $this->extractFileName($fileData);
                }
                if (empty($name)) {
                        throw new LibresignException($this->l10n->t('File name is required'));
                }

                if (isset($fileData['fileNode']) && $fileData['fileNode'] instanceof Node) {
                        $node = $fileData['fileNode'];
                        $name = $fileData['name'] ?? $name;
                } elseif (isset($fileData['uploadedFile'])) {
                        $this->fileService->validateUploadedFile($fileData['uploadedFile']);

                        $node = $this->fileService->getNodeFromData([
                                'userManager' => $this->userSession->getUser(),
                                'name' => $name,
                                'uploadedFile' => $fileData['uploadedFile'],
                                'settings' => $settings
                        ]);
                } else {
                        $this->validateHelper->validateNewFile([
                                'file' => $fileData,
                                'userManager' => $this->userSession->getUser(),
                        ]);

                        $node = $this->fileService->getNodeFromData([
                                'userManager' => $this->userSession->getUser(),
                                'name' => $name,
                                'file' => $fileData,
                                'settings' => $settings
                        ]);
                }

                return [
                        'node' => $node,
                        'name' => $name,
                ];
        }

        /**
         * @return list<array{fileNode?: Node, name?: string, uploadedFile?: array}> Normalized files array
         */
        private function prepareFilesForSaving(array $file, array $files, array $settings): array {
                $uploadedFiles = $this->request->getUploadedFile('files') ?: $this->request->getUploadedFile('file');

                if ($uploadedFiles) {
                        return $this->processUploadedFiles($uploadedFiles);
                }

                if (!empty($files)) {
                        /** @var list<array{fileNode?: Node, name?: string}> $files */
                        return $files;
                }

                if (!empty($file)) {
                        return [$file];
                }

                throw new LibresignException($this->l10n->t('File or files parameter is required'));
        }

        /**
         * @return list<array{uploadedFile: array, name: string}>
         */
        private function processUploadedFiles(array $uploadedFiles): array {
                $filesArray = [];

                if (isset($uploadedFiles['tmp_name'])) {
                        if (is_array($uploadedFiles['tmp_name'])) {
                                $count = count($uploadedFiles['tmp_name']);
                                for ($i = 0; $i < $count; $i++) {
                                        $uploadedFile = [
                                                'tmp_name' => $uploadedFiles['tmp_name'][$i],
                                                'name' => $uploadedFiles['name'][$i],
                                                'type' => $uploadedFiles['type'][$i],
                                                'size' => $uploadedFiles['size'][$i],
                                                'error' => $uploadedFiles['error'][$i],
                                        ];
                                        $this->fileService->validateUploadedFile($uploadedFile);
                                        $filesArray[] = [
                                                'uploadedFile' => $uploadedFile,
                                                'name' => pathinfo((string)$uploadedFile['name'], PATHINFO_FILENAME),
                                        ];
                                }
                        } else {
                                $this->fileService->validateUploadedFile($uploadedFiles);
                                $filesArray[] = [
                                        'uploadedFile' => $uploadedFiles,
                                        'name' => pathinfo((string)$uploadedFiles['name'], PATHINFO_FILENAME),
                                ];
                        }
                }

                if (empty($filesArray)) {
                        throw new LibresignException($this->l10n->t('No files uploaded'));
                }

                return $filesArray;
        }

        /**
         * @return DataResponse<Http::STATUS_OK, LibresignDetailedFileResponse, array{}>
         */
        private function saveFiles(array $files, string $name, array $settings): DataResponse {
                if (empty($files)) {
                        throw new LibresignException($this->l10n->t('File or files parameter is required'));
                }

                $result = $this->requestSignatureService->saveFiles([
                        'files' => $files,
                        'name' => $name,
                        'userManager' => $this->userSession->getUser(),
                        'settings' => $settings,
                ]);

                $response = $this->fileListService->formatFileWithChildren($result['file'], $result['children'], $this->userSession->getUser());
                return new DataResponse($response, Http::STATUS_OK);
        }

        private function extractFileName(array $fileData): string {
                if (!empty($fileData['name'])) {
                        return $fileData['name'];
                }
                if (!empty($fileData['url'])) {
                        return rawurldecode(pathinfo((string)$fileData['url'], PATHINFO_FILENAME));
                }
                return '';
        }

        /**
         * Delete File
         *
         * This will delete the file and all data
         *
         * @param integer $fileId LibreSign file ID
         * @param boolean $deleteFile Whether to delete the physical file from Nextcloud (default: true)
         * @return DataResponse<Http::STATUS_OK, LibresignMessageResponse, array{}>|DataResponse<Http::STATUS_UNAUTHORIZED, LibresignMessageResponse, array{}>|DataResponse<Http::STATUS_UNPROCESSABLE_ENTITY, LibresignActionErrorResponse, array{}>
         *
         * 200: OK
         * 401: Failed
         * 422: Failed
         */
        #[NoAdminRequired]
        #[NoCSRFRequired]
        #[RequireManager]
        #[ApiRoute(verb: 'DELETE', url: '/api/{apiVersion}/file/file_id/{fileId}', requirements: ['apiVersion' => '(v1)'])]
        public function deleteFile(int $fileId, bool $deleteFile = true): DataResponse {
                try {
                        $data = [
                                'userManager' => $this->userSession->getUser(),
                                'file' => [
                                        'fileId' => $fileId
                                ]
                        ];
                        $this->validateHelper->validateExistingFile($data);
                        $this->fileService->delete($fileId, $deleteFile);
                } catch (\Throwable $th) {
                        return new DataResponse(
                                [
                                        'message' => $th->getMessage(),
                                ],
                                Http::STATUS_UNAUTHORIZED
                        );
                }
                return new DataResponse(
                        [
                                'message' => $this->l10n->t('Success')
                        ],
                        Http::STATUS_OK
                );
        }
}

LibreSign / libresign / 28871954782

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous