Skip to content

fix(openapi): document optional sign request UUID headers - #9466

Merged
vitormattos merged 7 commits into
mainfrom
fix/document-sign-request-headers
Nov 14, 2026
Merged

vitormattos merged 7 commits into
mainfrom
fix/document-sign-request-headers

Conversation

@vitormattos

@vitormattos vitormattos commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Document the existing libresign-sign-request-uuid header for all middleware-consumer OCS operations that lack a {uuid} route parameter: six previously missing operations in SignatureElementsController and IdDocsController, plus SignFileController::requestCodeByFileId.
  • Regenerate openapi.json, openapi-full.json, and their TypeScript types. The default and full specs now document the header on 10 operations; the administration spec remains unchanged.
  • Replace the fixed OpenAPI operation list with a contract regression that discovers UUID-consuming middleware attributes and controller routes, without copying #[RequestHeader] declarations into the expected results.
  • Correct ModalVerificationCode.requestCode() to use the current signer's/approver's resolved UUID and signStore.buildRequestCodeUrl(), even when a fileId is present. The old file_id/{fileId}/code call supplied no UUID, but #[RequireSigner] needs it before the controller runs. Preserve the idDocApproval=true context and avoid making any request when no valid UUID context can be resolved.
  • Add focused frontend regression cases for a normal signer, an identification-document approver, an approver who is also a signer, and a fileId without usable UUID. Preserve the existing check that a typed email address is not sent as a verification-code destination.

Review findings and contract decisions

  • Missing header on sign_file-request-code-by-file-id: confirmed and corrected. The controller now documents the header; the application UI no longer takes that route without a UUID.
  • Optional header on signature_elements-use-saved-signature-elements: intentional. The external signer's UUID is required for authorization, but the header itself is not the only accepted source: InjectionMiddleware::getUuidFromRequest() uses IRequest::getParam('uuid', $request->getHeader(...)), and Nextcloud merges route, GET and POST parameters. Keeping required: false on the header avoids rejecting/documenting incorrectly an otherwise valid request with a uuid request parameter. A request missing both sources is rejected; authenticated users do not become eligible to reuse external email signatures.

Verification

  • The OpenAPI suite passed locally on the earlier contract revision: 24 tests, 659 assertions. composer openapi, TypeScript generation, npm run ts:check, PHP syntax and PHP-CS-Fixer were also checked on the earlier revision.
  • Latest frontend routing and test changes are in signed commits 66863d3 and f8baf71. GitHub CI for the current HEAD is the authority for their execution; do not treat prior runs as current results.
  • All new commits created during the review have cryptographically verified signatures and matching DCO trailers.

Boundaries / outstanding verification

  • No change to backend authentication, authorization, routing attributes, signer validation, or multipart behavior. The existing wire header name is preserved.
  • Retain the previously identified need for focused guest/authenticated authorization verification in an isolated Nextcloud runtime. Review the current-head CI and frontend regression results before merging.
  • The Nextcloud OpenAPI extractor warns about the custom header lacking an x- prefix; renaming it would break existing clients and is outside this change.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Code Metrics Report

Note: Metrics describe the revision analyzed by the successful PHPUnit run. Newer commits with pending, canceled or failed checks may not yet be represented in this report.

main (2c798a0) #9466 (9a5b13e) +/-
Coverage 76.4% 76.4% 0.0%
Test Execution Time 3m41s 3m14s -27s
Details
  |                     | main (2c798a0) | #9466 (9a5b13e) | +/-  |
  |---------------------|----------------|-----------------|------|
  | Coverage            |          76.4% |           76.4% | 0.0% |
  |   Files             |            512 |             512 |    0 |
  |   Lines             |          28845 |           28845 |    0 |
  |   Covered           |          22063 |           22063 |    0 |
+ | Test Execution Time |          3m41s |           3m14s | -27s |

Code coverage of files in pull request scope (55.4% → 55.4%)

Files Coverage +/- Status
lib/Controller/IdDocsController.php 40.0% 0.0% modified
lib/Controller/SignFileController.php 81.5% 0.0% modified
lib/Controller/SignatureElementsController.php 31.9% 0.0% modified

Reported by octocov

@vitormattos

Copy link
Copy Markdown
Member Author

/backport to stable35

@backportbot-libresign backportbot-libresign Bot added the backport-request Request to backport a change to supported stable branches label Nov 13, 2026
@vitormattos

Copy link
Copy Markdown
Member Author

/backport to stable34

@vitormattos

Copy link
Copy Markdown
Member Author

/backport to stable33

@vitormattos
vitormattos marked this pull request as ready for review November 13, 2026 17:27
@vitormattos
vitormattos requested a review from a team as a code owner November 13, 2026 17:27

@lfals lfals left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The six public operations that already accept libresign-sign-request-uuid and skip it for a logged-in caller now declare that header as optional. Generated OpenAPI and TypeScript types match those attributes.

One regression: OpenApiRequestHeadersTest requires sign_file-request-code-by-file-id to stay undocumented, so a client that follows the spec is rejected with Invalid UUID before requestCodeByFileId runs.

Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
Signed-off-by: Vitor Mattos <1079143+vitormattos@users.noreply.github.com>
@vitormattos
vitormattos requested a review from lfals November 14, 2026 13:24
@vitormattos
vitormattos merged commit aa72946 into main Nov 14, 2026
80 checks passed
@vitormattos
vitormattos deleted the fix/document-sign-request-headers branch November 14, 2026 17:24
@backportbot-libresign backportbot-libresign Bot removed the backport-request Request to backport a change to supported stable branches label Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants