Repository navigation
feat(id-docs): add occ command to recover identification documents orphaned in appdata - #9535
Open
maia-andre wants to merge 2 commits into
Open
maia-andre wants to merge 2 commits into
maia-andre wants to merge 2 commits into
Conversation
Before LibreSign#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 <andrefnkmm@gmail.com>
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 <andrefnkmm@gmail.com>
This was referenced Nov 18, 2026
Open
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves: #9168
📝 Summary
Adds
occ libresign:id-docs:recover, which finds identification documents of external signers that were written to theunauthenticatedappdata folder before #8368 and copies them into the storage of their owner, so they open again in Documents Validation.Your answer on the questions in my claim comment hadn't arrived, so I went with the defaults proposed there. Each one is easy to change in review:
libresign:id-docs:recover.signed_node_idare reported asambiguousand skipped.FolderService::getUnauthenticatedFolder(), so a backport needs adaptation. Happy to do it if you want it.How it decides
Only
id_docsrows with a nulluser_id(the external-signer path) are checked. Each one is reported with a reason:affectedunauthenticatedappdata, owner exists and matches the owner of the signed document, node referenced by exactly one file recordalready_correctambiguousunrecoverableWhat
--executedoes for an affected row<date>_recovered-id-doc-<fileId>_<uid>in the owner's LibreSign folder, using the samegetFolderForFile()resolution as the fixed upload path. It stops if that folder is not inside the owner's files (see below).libresign_file.node_idin a transaction, usinggetByIdForUpdate(), only ifnode_idis unchanged and there is still no signed copy.File IDs, UUIDs,
id_docsand sign request rows are not touched. Any failure removes the new folder and leaves the record as it was, so the next run sees the row asaffectedagain. If that cleanup fails, the leftover node ID is printed. The output contains record and node IDs only: no file names, contents or signer data. Exceptions go to the server log.Found while testing manually
In a CLI process, if a user whose home was never initialized is looked up by node ID first, a later write to that home throws
NotFoundException, andFolderService::getContainerFolder()falls back to appdata. The copy would then become a new orphan. The command now checks that the target folder is inside the owner's files before copying, and reportsowner storage not availableotherwise. I leftFolderServiceitself alone. In practice an owner who requested a signature already has a home, and the docs tell the admin to have the owner log in once.Reading order
lib/Service/IdDocsRecoveryService.phpfirst, thenlib/Command/IdDocs/Recover.php. Composition: about 360 lines of code (service 201, command 73, mapper andFolderServicehelpers 86) and 529 lines of tests. Two commits: service, then command.Admin documentation: LibreSign/documentation#176.
🧪 How to test
On a disposable instance with synthetic data:
Then open the document in Documents Validation.
Output from my run (isolated sqlite instance, synthetic rows: one owner with an initialized home, one without):
After that,
AccountFileService::getPdfByUuid()(the Documents Validation path) returned the original content for both documents.Validation evidence
All runs were in the devcontainer, against an isolated sqlite instance (
NEXTCLOUD_CONFIG_DIR).tests/php/Unit/Service/IdDocsRecoveryServiceTest.phpandtests/php/Unit/Command/IdDocs/RecoverTest.php: 22 tests, OK. They cover each skip reason, dry-run without copying, recovery, content mismatch, unreadable copy, record changed or signed concurrently, appdata fallback, rollback with failed cleanup, and command output and exit codes.tests/php/Integration/Service/IdDocsRecoveryServiceTest.php: 2 tests, OK, with real storage and database:--executemakesgetPdfByUuid()return the content (it throws before recovery), keeps the original in appdata, keeps the UUID, owner andid_docs/sign request link, doesn't expose the node to another user, and is idempotent on re-run.api,integrationsuite: 517 tests, OK (1 warning fromDnsPinMiddleware, network). An earlier run showed the new test failing only inside the full suite, because of stale appdata nodes left by earlier classes. It now extendsAppDataTestCase, like the other appdata tests.composer test:unit: 5014 tests. The only error isTsaValidationServiceTestreaching freetsa.org (no network here).composer cs:check: clean.composer psalm: no issues in the changed files. The 2 errors reported are inlib/Service/Install/SignSetupService.php, which this PR doesn't touch, so I expect they come from my local vendor-bin.Not verified: MySQL/PostgreSQL. The integration run used sqlite, where
getByIdForUpdate()does not addFOR UPDATE.⚙️ API / Back-end changes
libresign:id-docs:recover(no HTTP API change, no OpenAPI change)✅ Checklist
🤖 AI (if applicable)