[vitormattos]

Objective

Align LibreSign's OpenAPI source contracts with the actual PHP, Nextcloud request dispatcher, and frontend behavior while preserving reusable component references. No change to the Nextcloud OpenAPI extractor, no Composer patch, no new SDK generation mechanism, and no multipart work in this PR.

Related: #9089, #9435, #9437. Independently reassesses the open #9453 and #9454 without requiring their merge. Preserves already merged #9494, #9452 and #9490.

Changes in this PR

Signing and saved signature requests

• Document signByFileId / signBySignerUuid.elements as typed lists of SigningElement (documentElementId and optional profileNodeId), matching the UI.
• Document saved-signature creation as a list of SavedSignatureElement and its update file as shared SavedSignatureFile, rather than maps with object-valued properties.
• Make deviceGeolocation an optional SignerDeviceGeolocation|null and retain runtime compatibility with the legacy empty-array sentinel. The signing validator and metadata requirements remain authoritative.

Signing-code requests and identification-document approval

• Fix optional PHP arguments for identifyMethod and signMethod so omitted values do not cause ArgumentCountError; identification methods are configured strings, not a hardcoded account|email enum.
• Remove the unnecessary 'true'|null enum from idDocApproval. Only the literal "true" selects the approval flow.
• Document that the frontend uses ?idDocApproval=true as a query string for signing and requesting a code. Nextcloud's merged request parameters also accept this flag through the JSON body of the code endpoint: preserve both inputs. Do not fabricate a JSON body flag on the general signing operation. Unit tests cover query and body sources.

Reusable policy contracts

• Reuse named RequestPolicy, RequestPolicyOverrides and PolicyActiveContext for both create and update request bodies; enforce the documented group context shape using the existing backend rules.
• Reuse PolicyValueMap across all four compound-policy write endpoints instead of four copies of array<string, mixed>. Its values reference the existing EffectivePolicyValue model, preserving consistent policy-value handling.

Account configuration values

• Expose the previously invisible value input directly in AccountController::setConfig, using a shared UserConfigValue alias for scalar values, arrays and objects. The Nextcloud dispatcher resolves named request parameters correctly.
• Explicitly normalize booleans to "1"/"0", numbers to strings, and arrays to JSON before IUserConfig::setValueString, retaining existing persisted formats. Null is rejected; existing preference-clear behavior uses the empty string. Unit tests cover strings, booleans, integers, decimals, empty arrays, nested JSON and null.

Evidence and regeneration

• Official unmodified extractor: composer openapi ran in the GitHub Actions environment and produced all six required artifacts (openapi*.json and matching src/types/openapi/*.ts, including administration scope). The outputs were committed from its own CI diff, not hand-edited.
• OpenAPI contracts: 45 tests, 858 assertions passed on the source revision (including account value and four policy-map references); the generator's expected diff check failed only because generated artifacts were not yet committed, now corrected in the separate signed generated-files commit.
• Psalm, PHP-CS-Fixer and DCO passed on the source revision. A fresh CI matrix is running on the generated-files commit; final CI completion and focused unit regressions are not yet claimed.
• Commits are incremental, cryptographically signed and DCO verified. No merge/backport performed.

Deliberate boundaries and remaining extractor/SDK limitations

1. The extractor maps nested mixed values inside array<string,mixed> and list<mixed> to object, although arbitrary JSON scalars can be valid there. A recursive alias was tested and reverted after the current PHPDoc parser and Psalm rejected it. The top-level source contracts are improved, but nested JSON remains an upstream extraction limitation. Do not replace it with a falsely restricted list of policy objects.
2. In OpenAPI 3.0.3, description and default siblings of $ref may be ignored. We intentionally preserve shared references instead of inlining duplicate schemas or changing PHP defaults just to placate a generator; proper reference metadata needs extractor/spec-compatible support. In particular, an empty PHP-array default on an object-valued map does not guarantee an SDK-friendly JSON-object default.
3. idDocApproval is accepted as a query flag by the Nextcloud middleware, but the current extractor cannot explicitly represent the indirectly read query parameter. The code endpoint's supported body input is retained. The frontend/query behavior is documented in the operation text.
4. Existing optional SignerDeviceGeolocation uses a nullable allOf/$ref wrapper; generators should omit it when absent, and older direct clients can still send [].
5. Multipart is out of scope (feat: Document uploaded files as multipart request bodies nextcloud/openapi-extractor#401 is tracked separately).
6. A successful OpenAPI generation is not a blanket Go for adopting generated typescript-axios SDKs; policy union fidelity and other limitations still require validation.

Reviewer focus

Verify that the generated JSON matches real callers, particularly code-request query/body handling, account-config persistence, compound-policy map references and authorization/validation boundaries. The final CI matrix must pass before merge consideration. No merge or backport is requested.

[github-actions]

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 (114c424)	#9505 (e2a3fb3)	+/-
Coverage	76.6%	76.7%	+0.0%
Test Execution Time	3m40s	3m42s	+2s

Details

  |                     | main (114c424) | #9505 (e2a3fb3) |  +/-  |
  |---------------------|----------------|-----------------|-------|
+ | Coverage            |          76.6% |           76.7% | +0.0% |
  |   Files             |            512 |             512 |     0 |
  |   Lines             |          28862 |           28867 |    +5 |
+ |   Covered           |          22129 |           22158 |   +29 |
- | Test Execution Time |          3m40s |           3m42s |   +2s |

Code coverage of files in pull request scope (56.8% → 59.4%, patch 91.6%)

Files	Coverage	+/-	Patch Coverage	Status
lib/Controller/AccountController.php	46.8%	+9.7%	85.7%	modified
lib/Controller/PolicyController.php	54.0%	0.0%	-	modified
lib/Controller/RequestSignatureController.php	90.5%	0.0%	-	modified
lib/Controller/SignFileController.php	85.5%	+4.0%	100.0%	modified
lib/Controller/SignatureElementsController.php	31.9%	0.0%	-	modified
lib/ResponseDefinitions.php	0.0%	0.0%	-	modified

---

Reported by octocov