From ebceafbbf4d5ef1c63ca566cb7ef0cf019aacfe1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Maia?= Date: Tue, 17 Nov 2026 22:03:01 -0300 Subject: [PATCH 1/2] feat(id-docs): recover documents orphaned in unauthenticated appdata MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Before #8368, identification documents uploaded by external signers were written to the unauthenticated appdata folder while their file record pointed to the owner of the signed document, so they never opened in Documents Validation. IdDocsRecoveryService classifies every id_docs row without a user as affected, already correct, ambiguous or unrecoverable, with a reason. Only rows whose owner matches the owner of the signed document, whose node is not shared by another record and that have no signed copy are recovered. Recovery copies the file into a new folder of the owner, compares the SHA-256 of both, checks that the owner can read the copy and then updates node_id under a row lock, only if the record did not change. The original stays in appdata. A failed step removes the new folder and leaves the record untouched, so a later run starts over. Signed-off-by: André Maia --- lib/Db/FileMapper.php | 19 ++ lib/Db/IdDocsMapper.php | 44 +++ lib/Service/FolderService.php | 23 ++ lib/Service/IdDocsRecoveryService.php | 201 ++++++++++++ .../Service/IdDocsRecoveryServiceTest.php | 167 ++++++++++ .../Service/IdDocsRecoveryServiceTest.php | 298 ++++++++++++++++++ 6 files changed, 752 insertions(+) create mode 100644 lib/Service/IdDocsRecoveryService.php create mode 100644 tests/php/Integration/Service/IdDocsRecoveryServiceTest.php create mode 100644 tests/php/Unit/Service/IdDocsRecoveryServiceTest.php diff --git a/lib/Db/FileMapper.php b/lib/Db/FileMapper.php index c317b06f58..fa653e6ddc 100644 --- a/lib/Db/FileMapper.php +++ b/lib/Db/FileMapper.php @@ -238,6 +238,25 @@ public function getByNodeId(int $nodeId): File { return $file; } + /** + * Count the records that reference a node, bypassing the entity cache. + */ + public function countByNodeId(int $nodeId): int { + $qb = $this->db->getQueryBuilder(); + $qb->select($qb->func()->count('*', 'total')) + ->from($this->getTableName()) + ->where( + $qb->expr()->orX( + $qb->expr()->eq('node_id', $qb->createNamedParameter($nodeId, IQueryBuilder::PARAM_INT)), + $qb->expr()->eq('signed_node_id', $qb->createNamedParameter($nodeId, IQueryBuilder::PARAM_INT)) + ) + ); + $result = $qb->executeQuery(); + $total = (int)$result->fetchOne(); + $result->closeCursor(); + return $total; + } + public function nodeIdExists(int $nodeId): bool { $qb = $this->db->getQueryBuilder(); diff --git a/lib/Db/IdDocsMapper.php b/lib/Db/IdDocsMapper.php index 21c6dc45ff..848879c38c 100644 --- a/lib/Db/IdDocsMapper.php +++ b/lib/Db/IdDocsMapper.php @@ -97,6 +97,50 @@ public function getBySignRequestIdAndNodeId(int $signRequestId, int $nodeId): Id return $this->findEntity($qb); } + /** + * Identification documents uploaded by signers without an account, with + * the references needed to locate their node and its expected owner. + * + * @return list + */ + public function getExternalSignerDocuments(): array { + $qb = $this->db->getQueryBuilder(); + $qb->select('id.id', 'id.file_id', 'id.sign_request_id') + ->selectAlias('f.id', 'file_row_id') + ->selectAlias('f.node_id', 'node_id') + ->selectAlias('f.signed_node_id', 'signed_node_id') + ->selectAlias('f.user_id', 'owner') + ->selectAlias('sr.id', 'sign_request_row_id') + ->selectAlias('sr.file_id', 'signed_document_id') + ->selectAlias('sf.id', 'signed_document_row_id') + ->selectAlias('sf.user_id', 'signed_document_owner') + ->from($this->getTableName(), 'id') + ->leftJoin('id', 'libresign_file', 'f', 'f.id = id.file_id') + ->leftJoin('id', 'libresign_sign_request', 'sr', 'sr.id = id.sign_request_id') + ->leftJoin('sr', 'libresign_file', 'sf', 'sf.id = sr.file_id') + ->where($qb->expr()->isNull('id.user_id')) + ->orderBy('id.id'); + + $rows = []; + $result = $qb->executeQuery(); + while ($row = $result->fetch()) { + $rows[] = [ + 'id_doc_id' => (int)$row['id'], + 'file_id' => (int)$row['file_id'], + 'sign_request_id' => $row['sign_request_row_id'] === null ? null : (int)$row['sign_request_row_id'], + 'file_exists' => $row['file_row_id'] !== null, + 'node_id' => $row['node_id'] === null ? null : (int)$row['node_id'], + 'signed_node_id' => $row['signed_node_id'] === null ? null : (int)$row['signed_node_id'], + 'owner' => $row['owner'] === null || $row['owner'] === '' ? null : (string)$row['owner'], + 'signed_document_id' => $row['signed_document_id'] === null ? null : (int)$row['signed_document_id'], + 'signed_document_owner' => $row['signed_document_owner'] === null || $row['signed_document_owner'] === '' ? null : (string)$row['signed_document_owner'], + 'signed_document_exists' => $row['signed_document_row_id'] !== null, + ]; + } + $result->closeCursor(); + return $rows; + } + public function getByFileId(int $fileId): IdDocs { $qb = $this->db->getQueryBuilder(); $qb->select('*') diff --git a/lib/Service/FolderService.php b/lib/Service/FolderService.php index b6020c6041..98c5b44cc3 100644 --- a/lib/Service/FolderService.php +++ b/lib/Service/FolderService.php @@ -113,6 +113,17 @@ public function getUnauthenticatedFolder(): Folder { return $service->getFolder(); } + /** + * Look up a node in the unauthenticated container without creating it. + * + * @throws NotFoundException + */ + public function getUnauthenticatedFileByNodeId(int $nodeId): File { + $service = clone $this; + $service->setUserId(null); + return $service->getFileByNodeId($nodeId); + } + /** * @throws NotFoundException */ @@ -224,6 +235,18 @@ public function getFolderForFile(array $data, $identifier): Folder { return $userFolder->newFolder($folderName); } + /** + * Resolve the folder for a new file of the given user, independently of + * the user currently bound to this service. + * + * @throws LibresignException + */ + public function getFolderForUserFile(IUser $user, array $data): Folder { + $service = clone $this; + $service->setUserId($user->getUID()); + return $service->getFolderForFile($data, $user); + } + /** * @param array{settings: array, name: string} $data * @param IUser $owner diff --git a/lib/Service/IdDocsRecoveryService.php b/lib/Service/IdDocsRecoveryService.php new file mode 100644 index 0000000000..6ca9116637 --- /dev/null +++ b/lib/Service/IdDocsRecoveryService.php @@ -0,0 +1,201 @@ + + */ + public function run(bool $execute): array { + $results = []; + foreach ($this->idDocsMapper->getExternalSignerDocuments() as $row) { + [$result, $owner, $source] = $this->classify($row); + if ($execute && $result['status'] === self::STATUS_AFFECTED && $owner instanceof IUser && $source instanceof File) { + $result = $this->recover($result, $owner, $source); + } + $results[] = $result; + } + return $results; + } + + /** + * @param array{id_doc_id: int, file_id: int, sign_request_id: ?int, file_exists: bool, node_id: ?int, signed_node_id: ?int, owner: ?string, signed_document_id: ?int, signed_document_owner: ?string, signed_document_exists: bool} $row + * @return array{0: RecoveryResult, 1: ?IUser, 2: ?File} + */ + private function classify(array $row): array { + $result = [ + 'idDocId' => $row['id_doc_id'], + 'fileId' => $row['file_id'], + 'nodeId' => $row['node_id'], + ]; + $skip = static fn (string $status, string $reason): array => [$result + ['status' => $status, 'reason' => $reason], null, null]; + + if (!$row['file_exists'] || $row['node_id'] === null) { + return $skip(self::STATUS_UNRECOVERABLE, 'file record missing'); + } + if ($row['signed_node_id'] !== null) { + return $skip(self::STATUS_AMBIGUOUS, 'document has a signed copy'); + } + if ($row['owner'] === null) { + return $skip(self::STATUS_UNRECOVERABLE, 'owner missing'); + } + $owner = $this->userManager->get($row['owner']); + if (!$owner instanceof IUser) { + return $skip(self::STATUS_UNRECOVERABLE, 'owner account missing'); + } + if ($row['sign_request_id'] === null) { + return $skip(self::STATUS_UNRECOVERABLE, 'sign request missing'); + } + if (!$row['signed_document_exists']) { + return $skip(self::STATUS_UNRECOVERABLE, 'signed document missing'); + } + if ($row['signed_document_owner'] !== $row['owner']) { + return $skip(self::STATUS_AMBIGUOUS, 'owner differs from signed document owner'); + } + if ($this->folderService->getReadableNodeById($owner->getUID(), $row['node_id']) instanceof File) { + return $skip(self::STATUS_ALREADY_CORRECT, 'readable in owner storage'); + } + if ($this->fileMapper->countByNodeId($row['node_id']) !== 1) { + return $skip(self::STATUS_AMBIGUOUS, 'node referenced by several file records'); + } + try { + $source = $this->folderService->getUnauthenticatedFileByNodeId($row['node_id']); + } catch (NotFoundException) { + return $skip(self::STATUS_UNRECOVERABLE, 'source file missing'); + } + return [$result + ['status' => self::STATUS_AFFECTED, 'reason' => 'stored in unauthenticated appdata'], $owner, $source]; + } + + /** + * Copy the source into a new folder of the owner, verify it and only then + * point the file record to the copy. The original is never removed. + * + * @param RecoveryResult $result + * @return RecoveryResult + */ + private function recover(array $result, IUser $owner, File $source): array { + $folder = null; + try { + $folder = $this->folderService->getFolderForUserFile($owner, ['name' => 'recovered-id-doc-' . $result['fileId']]); + // FolderService falls back to app data when the owner's files cannot + // be written, which would only create another orphan. + $ownerRoot = $this->folderService->getUserFolder($owner->getUID())->getPath(); + if (!str_starts_with($folder->getPath(), $ownerRoot . '/')) { + return $this->fail($result, 'owner storage not available', $folder); + } + $stream = $source->fopen('r'); + if ($stream === false) { + return $this->fail($result, 'source file not readable', $folder); + } + try { + $copy = $folder->newFile($source->getName(), $stream); + } finally { + if (is_resource($stream)) { + fclose($stream); + } + } + if ($copy->hash('sha256') !== $source->hash('sha256')) { + return $this->fail($result, 'content verification failed', $folder); + } + $newNodeId = $copy->getId(); + if (!$this->folderService->getReadableNodeById($owner->getUID(), $newNodeId) instanceof File) { + return $this->fail($result, 'copy not readable in owner storage', $folder); + } + $oldNodeId = (int)$result['nodeId']; + $updated = $this->atomic(function () use ($result, $oldNodeId, $newNodeId): bool { + $file = $this->fileMapper->getByIdForUpdate($result['fileId']); + if ($file->getNodeId() !== $oldNodeId || $file->getSignedNodeId() !== null) { + return false; + } + $file->setNodeId($newNodeId); + $this->fileMapper->update($file); + return true; + }, $this->db); + if (!$updated) { + return $this->fail($result, 'file record changed during recovery', $folder); + } + return array_merge($result, [ + 'status' => self::STATUS_RECOVERED, + 'reason' => 'copied to owner storage, original kept', + 'newNodeId' => $newNodeId, + ]); + } catch (\Throwable $e) { + $this->logger->error('Failed to recover identification document', [ + 'idDocId' => $result['idDocId'], + 'fileId' => $result['fileId'], + 'exception' => $e, + ]); + return $this->fail($result, 'unexpected error, see the server log', $folder); + } + } + + /** + * Report a failure and remove the folder created for the copy, so a retry + * starts from the same state. + * + * @param RecoveryResult $result + * @return RecoveryResult + */ + private function fail(array $result, string $reason, ?Folder $folder): array { + $result = array_merge($result, ['status' => self::STATUS_FAILED, 'reason' => $reason]); + if ($folder === null) { + return $result; + } + try { + $folder->delete(); + } catch (\Throwable $e) { + $this->logger->warning('Could not remove the copy of an identification document after a failed recovery', [ + 'idDocId' => $result['idDocId'], + 'exception' => $e, + ]); + $result['leftoverNodeId'] = $folder->getId(); + } + return $result; + } +} diff --git a/tests/php/Integration/Service/IdDocsRecoveryServiceTest.php b/tests/php/Integration/Service/IdDocsRecoveryServiceTest.php new file mode 100644 index 0000000000..4189d93804 --- /dev/null +++ b/tests/php/Integration/Service/IdDocsRecoveryServiceTest.php @@ -0,0 +1,167 @@ +fileMapper = Server::get(FileMapper::class); + $this->idDocsMapper = Server::get(IdDocsMapper::class); + $this->signRequestMapper = Server::get(SignRequestMapper::class); + $this->folderService = Server::get(FolderService::class); + $this->rootFolder = Server::get(IRootFolder::class); + + $suffix = bin2hex(random_bytes(6)); + $this->owner = $this->createAccount('id-docs-owner-' . $suffix, 'test-password'); + $this->otherUser = $this->createAccount('id-docs-other-' . $suffix, 'test-password'); + // Same place the upload wrote to before #8368: a folder under unauthenticated appdata. + $this->legacyFolder = $this->folderService->getUnauthenticatedFolder()->newFolder('id-docs-recovery-test-' . $suffix); + + $signedDocument = $this->insertFile(1, $this->owner->getUID()); + $signRequest = new SignRequest(); + $signRequest->setFileId($signedDocument->getId()); + $signRequest->setDisplayName('External signer'); + $signRequest->setUuid(UUIDUtil::getUUID()); + $signRequest->setCreatedAt(new \DateTime('now', new \DateTimeZone('UTC'))); + $this->signRequestId = $this->signRequestMapper->insert($signRequest)->getId(); + } + + public function tearDown(): void { + try { + if (isset($this->legacyFolder)) { + $this->legacyFolder->delete(); + } + } finally { + parent::tearDown(); + } + } + + private function insertFile(int $nodeId, ?string $owner): FileEntity { + $file = new FileEntity(); + $file->setNodeId($nodeId); + $file->setUserId($owner); + $file->setUuid(UUIDUtil::getUUID()); + $file->setCreatedAt(new \DateTime('now', new \DateTimeZone('UTC'))); + $file->setName('IDENTIFICATION'); + $file->setStatus(FileStatus::ABLE_TO_SIGN->value); + return $this->fileMapper->insert($file); + } + + private function insertIdDoc(int $nodeId, ?string $owner = null, ?int $signRequestId = null): FileEntity { + $file = $this->insertFile($nodeId, $owner ?? $this->owner->getUID()); + $this->idDocsMapper->save($file->getId(), $signRequestId ?? $this->signRequestId, null, 'IDENTIFICATION'); + return $file; + } + + private function legacyNode(string $name = 'IDENTIFICATION.pdf'): int { + return $this->legacyFolder->newFile($name, self::CONTENT)->getId(); + } + + private function recoveredFolders(): array { + $service = clone $this->folderService; + $service->setUserId($this->owner->getUID()); + return array_values(array_filter( + $service->getFolder()->getDirectoryListing(), + static fn ($node): bool => str_contains($node->getName(), 'recovered-id-doc-'), + )); + } + + /** @return array */ + private function runRecovery(bool $execute): array { + $results = []; + foreach (Server::get(IdDocsRecoveryService::class)->run($execute) as $result) { + $results[$result['fileId']] = $result; + } + return $results; + } + + public function testDryRunClassifiesDocumentsWithoutChangingFilesOrRecords(): void { + $orphan = $this->insertIdDoc($this->legacyNode()); + $correctNode = $this->rootFolder->getUserFolder($this->owner->getUID())->newFile('already-correct.pdf', self::CONTENT); + $correct = $this->insertIdDoc($correctNode->getId()); + $missingSource = $this->insertIdDoc(2147483000); + $missingOwner = $this->insertIdDoc($this->legacyNode('missing-owner.pdf'), 'deleted-account'); + $brokenSignRequest = $this->insertIdDoc($this->legacyNode('broken.pdf'), null, 2147483001); + + $results = $this->runRecovery(false); + + $this->assertSame(IdDocsRecoveryService::STATUS_AFFECTED, $results[$orphan->getId()]['status']); + $this->assertSame(IdDocsRecoveryService::STATUS_ALREADY_CORRECT, $results[$correct->getId()]['status']); + $this->assertSame(['unrecoverable', 'source file missing'], [$results[$missingSource->getId()]['status'], $results[$missingSource->getId()]['reason']]); + $this->assertSame(['unrecoverable', 'owner account missing'], [$results[$missingOwner->getId()]['status'], $results[$missingOwner->getId()]['reason']]); + $this->assertSame(['unrecoverable', 'sign request missing'], [$results[$brokenSignRequest->getId()]['status'], $results[$brokenSignRequest->getId()]['reason']]); + $this->assertSame($orphan->getNodeId(), $this->fileMapper->getByIdForUpdate($orphan->getId())->getNodeId()); + $this->assertSame([], $this->recoveredFolders()); + } + + public function testExecuteMakesTheDocumentReadableOnlyByItsOwnerAndIsIdempotent(): void { + $legacyNodeId = $this->legacyNode(); + $orphan = $this->insertIdDoc($legacyNodeId); + $correctNode = $this->rootFolder->getUserFolder($this->owner->getUID())->newFile('already-correct.pdf', self::CONTENT); + $correct = $this->insertIdDoc($correctNode->getId()); + $accountFileService = Server::get(AccountFileService::class); + try { + $accountFileService->getPdfByUuid($orphan->getUuid()); + $this->fail('The orphaned document should not be readable before recovery.'); + } catch (\OCP\AppFramework\Db\DoesNotExistException) { + } + + $results = $this->runRecovery(true); + + $this->assertSame(IdDocsRecoveryService::STATUS_RECOVERED, $results[$orphan->getId()]['status']); + $this->assertSame(IdDocsRecoveryService::STATUS_ALREADY_CORRECT, $results[$correct->getId()]['status']); + $newNodeId = $results[$orphan->getId()]['newNodeId']; + $record = $this->fileMapper->getByIdForUpdate($orphan->getId()); + $this->assertSame($newNodeId, $record->getNodeId()); + $this->assertSame($orphan->getUuid(), $record->getUuid()); + $this->assertSame($this->owner->getUID(), $record->getUserId()); + $this->assertSame($this->signRequestId, $this->idDocsMapper->getByFileId($orphan->getId())->getSignRequestId()); + $this->assertSame($correctNode->getId(), $this->fileMapper->getByIdForUpdate($correct->getId())->getNodeId()); + $this->assertSame(self::CONTENT, $accountFileService->getPdfByUuid($orphan->getUuid())->getContent()); + $this->assertSame(self::CONTENT, $this->folderService->getUnauthenticatedFileByNodeId($legacyNodeId)->getContent()); + $this->assertSame([], $this->rootFolder->getUserFolder($this->otherUser->getUID())->getById($newNodeId)); + + $rerun = $this->runRecovery(true); + + $this->assertSame(IdDocsRecoveryService::STATUS_ALREADY_CORRECT, $rerun[$orphan->getId()]['status']); + $this->assertSame($newNodeId, $this->fileMapper->getByIdForUpdate($orphan->getId())->getNodeId()); + $this->assertCount(1, $this->recoveredFolders()); + } +} diff --git a/tests/php/Unit/Service/IdDocsRecoveryServiceTest.php b/tests/php/Unit/Service/IdDocsRecoveryServiceTest.php new file mode 100644 index 0000000000..2a54dc3dca --- /dev/null +++ b/tests/php/Unit/Service/IdDocsRecoveryServiceTest.php @@ -0,0 +1,298 @@ +idDocsMapper = $this->createMock(IdDocsMapper::class); + $this->fileMapper = $this->createMock(FileMapper::class); + $this->folderService = $this->createMock(FolderService::class); + $this->userManager = $this->createMock(IUserManager::class); + $this->db = $this->createMock(IDBConnection::class); + } + + private function service(): IdDocsRecoveryService { + return new IdDocsRecoveryService( + $this->idDocsMapper, + $this->fileMapper, + $this->folderService, + $this->userManager, + $this->db, + $this->createMock(LoggerInterface::class), + ); + } + + private static function row(array $overrides = []): array { + return array_merge([ + 'id_doc_id' => 1, + 'file_id' => 10, + 'sign_request_id' => 20, + 'file_exists' => true, + 'node_id' => 100, + 'signed_node_id' => null, + 'owner' => 'owner', + 'signed_document_id' => 30, + 'signed_document_owner' => 'owner', + 'signed_document_exists' => true, + ], $overrides); + } + + private function owner(): IUser&MockObject { + $owner = $this->createMock(IUser::class); + $owner->method('getUID')->willReturn('owner'); + $this->userManager->method('get')->willReturnCallback(fn (string $uid) => $uid === 'owner' ? $owner : null); + $userFolder = $this->createMock(IUserFolder::class); + $userFolder->method('getPath')->willReturn('/owner/files'); + $this->folderService->method('getUserFolder')->with('owner')->willReturn($userFolder); + return $owner; + } + + private function targetFolder(string $path = '/owner/files/LibreSign/recovered-id-doc-10'): Folder&MockObject { + $folder = $this->createMock(Folder::class); + $folder->method('getPath')->willReturn($path); + return $folder; + } + + private function source(string $hash = 'abc'): File&MockObject { + $source = $this->createMock(File::class); + $source->method('getName')->willReturn('IDENTIFICATION.pdf'); + $source->method('fopen')->willReturnCallback(static fn () => fopen('php://memory', 'r')); + $source->method('hash')->with('sha256')->willReturn($hash); + return $source; + } + + private function copy(int $id, string $hash = 'abc'): File&MockObject { + $copy = $this->createMock(File::class); + $copy->method('getId')->willReturn($id); + $copy->method('hash')->with('sha256')->willReturn($hash); + return $copy; + } + + /** Make the mocked connection run the transactional callback. */ + private function lockedFile(int $nodeId, ?int $signedNodeId = null): FileEntity { + $file = new FileEntity(); + $file->setId(10); + $file->setNodeId($nodeId); + $file->setSignedNodeId($signedNodeId); + $this->fileMapper->method('getByIdForUpdate')->with(10)->willReturn($file); + return $file; + } + + public static function provideSkippedRows(): array { + return [ + 'missing file record' => [['file_exists' => false, 'node_id' => null], IdDocsRecoveryService::STATUS_UNRECOVERABLE, 'file record missing'], + 'signed copy present' => [['signed_node_id' => 101], IdDocsRecoveryService::STATUS_AMBIGUOUS, 'document has a signed copy'], + 'owner not stored' => [['owner' => null], IdDocsRecoveryService::STATUS_UNRECOVERABLE, 'owner missing'], + 'owner account deleted' => [['owner' => 'deleted', 'signed_document_owner' => 'deleted'], IdDocsRecoveryService::STATUS_UNRECOVERABLE, 'owner account missing'], + 'sign request deleted' => [['sign_request_id' => null], IdDocsRecoveryService::STATUS_UNRECOVERABLE, 'sign request missing'], + 'signed document deleted' => [['signed_document_exists' => false, 'signed_document_owner' => null], IdDocsRecoveryService::STATUS_UNRECOVERABLE, 'signed document missing'], + 'owner mismatch' => [['signed_document_owner' => 'someone-else'], IdDocsRecoveryService::STATUS_AMBIGUOUS, 'owner differs from signed document owner'], + ]; + } + + #[DataProvider('provideSkippedRows')] + public function testSkipsRowsWithoutReliableReferences(array $overrides, string $status, string $reason): void { + $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row($overrides)]); + $this->folderService->expects($this->never())->method('getUnauthenticatedFileByNodeId'); + $this->folderService->expects($this->never())->method('getFolderForUserFile'); + $this->fileMapper->expects($this->never())->method('update'); + + $result = $this->service()->run(true)[0]; + + $this->assertSame($status, $result['status']); + $this->assertSame($reason, $result['reason']); + } + + public function testReportsDocumentReadableByOwnerAsAlreadyCorrect(): void { + $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row()]); + $this->folderService->method('getReadableNodeById')->with('owner', 100)->willReturn($this->createMock(File::class)); + $this->folderService->expects($this->never())->method('getFolderForUserFile'); + $this->fileMapper->expects($this->never())->method('update'); + + $result = $this->service()->run(true)[0]; + + $this->assertSame(IdDocsRecoveryService::STATUS_ALREADY_CORRECT, $result['status']); + } + + public function testSkipsNodeSharedBySeveralFileRecords(): void { + $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row()]); + $this->fileMapper->method('countByNodeId')->with(100)->willReturn(2); + $this->folderService->expects($this->never())->method('getUnauthenticatedFileByNodeId'); + + $result = $this->service()->run(true)[0]; + + $this->assertSame(IdDocsRecoveryService::STATUS_AMBIGUOUS, $result['status']); + $this->assertSame('node referenced by several file records', $result['reason']); + } + + public function testReportsMissingSourceAsUnrecoverable(): void { + $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row()]); + $this->fileMapper->method('countByNodeId')->willReturn(1); + $this->folderService->method('getUnauthenticatedFileByNodeId')->willThrowException(new NotFoundException()); + + $result = $this->service()->run(true)[0]; + + $this->assertSame(IdDocsRecoveryService::STATUS_UNRECOVERABLE, $result['status']); + $this->assertSame('source file missing', $result['reason']); + } + + public function testDryRunReportsAffectedDocumentWithoutCopying(): void { + $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row()]); + $this->fileMapper->method('countByNodeId')->willReturn(1); + $source = $this->source(); + $source->expects($this->never())->method('fopen'); + $this->folderService->method('getUnauthenticatedFileByNodeId')->with(100)->willReturn($source); + $this->folderService->expects($this->never())->method('getFolderForUserFile'); + $this->fileMapper->expects($this->never())->method('update'); + + $result = $this->service()->run(false)[0]; + + $this->assertSame(IdDocsRecoveryService::STATUS_AFFECTED, $result['status']); + $this->assertArrayNotHasKey('newNodeId', $result); + } + + public function testExecuteCopiesIntoOwnerFolderAndPointsTheRecordToTheCopy(): void { + $owner = $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row()]); + $this->fileMapper->method('countByNodeId')->willReturn(1); + $source = $this->source(); + $source->expects($this->never())->method('delete'); + $source->expects($this->never())->method('move'); + $this->folderService->method('getUnauthenticatedFileByNodeId')->willReturn($source); + $copy = $this->copy(200); + $folder = $this->targetFolder(); + $folder->expects($this->once())->method('newFile') + ->with('IDENTIFICATION.pdf', $this->isType('resource')) + ->willReturn($copy); + $folder->expects($this->never())->method('delete'); + $this->folderService->expects($this->once())->method('getFolderForUserFile') + ->with($owner, ['name' => 'recovered-id-doc-10']) + ->willReturn($folder); + $this->folderService->method('getReadableNodeById')->willReturnMap([ + ['owner', 100, null], + ['owner', 200, $copy], + ]); + $file = $this->lockedFile(100); + $this->fileMapper->expects($this->once())->method('update')->with($file); + + $result = $this->service()->run(true)[0]; + + $this->assertSame(IdDocsRecoveryService::STATUS_RECOVERED, $result['status']); + $this->assertSame(200, $result['newNodeId']); + $this->assertSame(200, $file->getNodeId()); + } + + public static function provideFailedRecoveries(): array { + return [ + 'content differs' => ['different', true, 100, null, 'content verification failed'], + 'copy not readable by owner' => ['abc', false, 100, null, 'copy not readable in owner storage'], + 'record changed concurrently' => ['abc', true, 999, null, 'file record changed during recovery'], + 'record signed concurrently' => ['abc', true, 100, 555, 'file record changed during recovery'], + ]; + } + + #[DataProvider('provideFailedRecoveries')] + public function testFailedRecoveryRemovesTheCopyAndKeepsTheRecord(string $copyHash, bool $copyReadable, int $lockedNodeId, ?int $lockedSignedNodeId, string $reason): void { + $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row()]); + $this->fileMapper->method('countByNodeId')->willReturn(1); + $this->folderService->method('getUnauthenticatedFileByNodeId')->willReturn($this->source()); + $copy = $this->copy(200, $copyHash); + $folder = $this->targetFolder(); + $folder->method('newFile')->willReturn($copy); + $folder->expects($this->once())->method('delete'); + $this->folderService->method('getFolderForUserFile')->willReturn($folder); + $this->folderService->method('getReadableNodeById')->willReturnMap([ + ['owner', 100, null], + ['owner', 200, $copyReadable ? $copy : null], + ]); + $this->lockedFile($lockedNodeId, $lockedSignedNodeId); + $this->fileMapper->expects($this->never())->method('update'); + + $result = $this->service()->run(true)[0]; + + $this->assertSame(IdDocsRecoveryService::STATUS_FAILED, $result['status']); + $this->assertSame($reason, $result['reason']); + $this->assertArrayNotHasKey('leftoverNodeId', $result); + } + + public function testDoesNotCopyWhenOwnerStorageFallsBackToAppData(): void { + $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row()]); + $this->fileMapper->method('countByNodeId')->willReturn(1); + $source = $this->source(); + $source->expects($this->never())->method('fopen'); + $this->folderService->method('getUnauthenticatedFileByNodeId')->willReturn($source); + $folder = $this->targetFolder('/appdata_x/libresign/LibreSign/recovered-id-doc-10'); + $folder->expects($this->never())->method('newFile'); + $folder->expects($this->once())->method('delete'); + $this->folderService->method('getFolderForUserFile')->willReturn($folder); + $this->fileMapper->expects($this->never())->method('update'); + + $result = $this->service()->run(true)[0]; + + $this->assertSame(IdDocsRecoveryService::STATUS_FAILED, $result['status']); + $this->assertSame('owner storage not available', $result['reason']); + } + + public function testUnexpectedErrorRollsBackAndReportsLeftoverWhenCleanupFails(): void { + $this->owner(); + $this->idDocsMapper->method('getExternalSignerDocuments')->willReturn([self::row()]); + $this->fileMapper->method('countByNodeId')->willReturn(1); + $this->folderService->method('getUnauthenticatedFileByNodeId')->willReturn($this->source()); + $copy = $this->copy(200); + $folder = $this->targetFolder(); + $folder->method('getId')->willReturn(300); + $folder->method('newFile')->willReturn($copy); + $folder->method('delete')->willThrowException(new \RuntimeException('storage unavailable')); + $this->folderService->method('getFolderForUserFile')->willReturn($folder); + $this->folderService->method('getReadableNodeById')->willReturnMap([ + ['owner', 100, null], + ['owner', 200, $copy], + ]); + $this->lockedFile(100); + $this->fileMapper->method('update')->willThrowException(new \RuntimeException('database unavailable')); + $this->db->expects($this->once())->method('rollBack'); + $this->db->expects($this->never())->method('commit'); + + $result = $this->service()->run(true)[0]; + + $this->assertSame(IdDocsRecoveryService::STATUS_FAILED, $result['status']); + $this->assertSame('unexpected error, see the server log', $result['reason']); + $this->assertSame(300, $result['leftoverNodeId']); + } +} From 03697b828938f8e24763c032d5302c34cc966dac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Maia?= Date: Tue, 17 Nov 2026 22:03:02 -0300 Subject: [PATCH 2/2] feat(command): add libresign:id-docs:recover MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expose the recovery as an occ command. It runs as a dry-run by default and only changes data with --execute. The table lists record and node IDs only, without file names or signer data, and the command exits with a failure code when a recovery fails. Signed-off-by: André Maia --- appinfo/info.xml | 1 + lib/Command/IdDocs/Recover.php | 73 +++++++++++++++++++ tests/php/Unit/Command/IdDocs/RecoverTest.php | 64 ++++++++++++++++ 3 files changed, 138 insertions(+) create mode 100644 lib/Command/IdDocs/Recover.php create mode 100644 tests/php/Unit/Command/IdDocs/RecoverTest.php diff --git a/appinfo/info.xml b/appinfo/info.xml index 9dc66f3f99..d8e7a9a7c6 100644 --- a/appinfo/info.xml +++ b/appinfo/info.xml @@ -76,6 +76,7 @@ https://libresign.coop OCA\Libresign\Command\Crl\Stats OCA\Libresign\Command\Crl\Cleanup OCA\Libresign\Command\Crl\Revoke + OCA\Libresign\Command\IdDocs\Recover OCA\Libresign\Command\SignatureElements\Cleanup OCA\Libresign\Command\Developer\Reset OCA\Libresign\Command\Developer\SignSetup diff --git a/lib/Command/IdDocs/Recover.php b/lib/Command/IdDocs/Recover.php new file mode 100644 index 0000000000..fc8d83f6ee --- /dev/null +++ b/lib/Command/IdDocs/Recover.php @@ -0,0 +1,73 @@ +setName('libresign:id-docs:recover') + ->setDescription('Find identification documents of external signers stored in the unauthenticated appdata folder and copy them to the owner storage') + ->setHelp( + "Runs as a dry-run by default and only reports what would change.\n" + . "With --execute, each affected document is copied into a new folder of the owner,\n" + . "its content is compared with the original, and only then is the file record\n" + . 'updated to the copy. The original stays in appdata and must be removed manually.' + ) + ->addOption('execute', null, InputOption::VALUE_NONE, 'Copy the affected documents and update their file records'); + } + + #[\Override] + protected function execute(InputInterface $input, OutputInterface $output): int { + $execute = (bool)$input->getOption('execute'); + $results = $this->recoveryService->run($execute); + + if ($results !== []) { + $table = new Table($output); + $table->setHeaders(['ID doc', 'File', 'Node', 'Status', 'Reason', 'New node']); + foreach ($results as $result) { + $table->addRow([ + $result['idDocId'], + $result['fileId'], + $result['nodeId'] ?? '', + $result['status'], + $result['reason'], + $result['newNodeId'] ?? $result['leftoverNodeId'] ?? '', + ]); + } + $table->render(); + } + + $totals = array_count_values(array_column($results, 'status')); + ksort($totals); + $summary = []; + foreach ($totals as $status => $total) { + $summary[] = $status . ': ' . $total; + } + $output->writeln('Checked ' . count($results) . ' identification documents' . ($summary === [] ? '.' : ' (' . implode(', ', $summary) . ').')); + if (!$execute && isset($totals[IdDocsRecoveryService::STATUS_AFFECTED])) { + $output->writeln('Dry-run: nothing was changed. Run again with --execute to recover the affected documents.'); + } + + return isset($totals[IdDocsRecoveryService::STATUS_FAILED]) ? self::FAILURE : self::SUCCESS; + } +} diff --git a/tests/php/Unit/Command/IdDocs/RecoverTest.php b/tests/php/Unit/Command/IdDocs/RecoverTest.php new file mode 100644 index 0000000000..8b13919dee --- /dev/null +++ b/tests/php/Unit/Command/IdDocs/RecoverTest.php @@ -0,0 +1,64 @@ +createMock(IdDocsRecoveryService::class); + $service->expects($this->once())->method('run')->with($execute)->willReturn($results); + $tester = new CommandTester(new Recover($service)); + $tester->execute($input); + return $tester; + } + + public function testRunsAsDryRunByDefault(): void { + $tester = $this->runCommand([ + ['idDocId' => 1, 'fileId' => 10, 'nodeId' => 100, 'status' => 'affected', 'reason' => 'stored in unauthenticated appdata'], + ['idDocId' => 2, 'fileId' => 11, 'nodeId' => 101, 'status' => 'already_correct', 'reason' => 'readable in owner storage'], + ], false); + + $this->assertSame(Command::SUCCESS, $tester->getStatusCode()); + $display = $tester->getDisplay(); + $this->assertStringContainsString('Checked 2 identification documents (affected: 1, already_correct: 1).', $display); + $this->assertStringContainsString('Dry-run: nothing was changed.', $display); + } + + public function testExecuteOptionRecoversAndShowsTheNewNode(): void { + $tester = $this->runCommand([ + ['idDocId' => 1, 'fileId' => 10, 'nodeId' => 100, 'status' => 'recovered', 'reason' => 'copied to owner storage, original kept', 'newNodeId' => 200], + ], true, ['--execute' => true]); + + $this->assertSame(Command::SUCCESS, $tester->getStatusCode()); + $display = $tester->getDisplay(); + $this->assertMatchesRegularExpression('/\|\s*1\s*\|\s*10\s*\|\s*100\s*\|\s*recovered\s*\|.*\|\s*200\s*\|/', $display); + $this->assertStringNotContainsString('Dry-run', $display); + } + + public function testFailureReturnsFailureCodeAndShowsLeftover(): void { + $tester = $this->runCommand([ + ['idDocId' => 1, 'fileId' => 10, 'nodeId' => 100, 'status' => 'failed', 'reason' => 'unexpected error, see the server log', 'leftoverNodeId' => 300], + ], true, ['--execute' => true]); + + $this->assertSame(Command::FAILURE, $tester->getStatusCode()); + $this->assertMatchesRegularExpression('/failed\s*\|.*\|\s*300\s*\|/', $tester->getDisplay()); + } + + public function testReportsWhenThereIsNothingToCheck(): void { + $tester = $this->runCommand([], false); + + $this->assertSame(Command::SUCCESS, $tester->getStatusCode()); + $this->assertSame('Checked 0 identification documents.' . PHP_EOL, $tester->getDisplay()); + } +}