Feat/signer geolocation backend 6960

[lfals]

Resolves: #6960

📝 Summary

Adds backend support for the signer_geolocation policy, allowing administrators to control whether signer device geolocation is disabled, optional, or required when signing documents.

The policy follows existing Policy Workbench patterns (collect_metadata, identification_documents) with three modes (disabled, optional, required) and optional requester override delegation. At request creation, the effective requirement is frozen per signer in metadata.geolocationRequirement. Sign endpoints accept a geolocation payload, validate it server-side, and persist coordinates independently of collect_metadata.

OpenAPI specs and generated TypeScript types were updated to document the new policy and sign/request parameters.

🧪 How to test

1. Set the system policy to require geolocation:

   curl -u admin:admin -H 'OCS-ApiRequest: true' -H 'Content-Type: application/json' \
     -X POST 'http://localhost/ocs/v2.php/apps/libresign/api/v1/policies/system/signer_geolocation' \
     -d '{"value":{"mode":"required","allowRequesterOverride":false}}'

2. Create a signature request with at least one signer.
3. List the file with details (GET /api/v1/file/list?details=1) and confirm the signer has metadata.geolocationRequirement: "required".
4. Attempt to sign without geolocation and confirm the API returns 422 with a geolocation-required error.
5. Sign again with a valid payload:

   {
     "method": "clickToSign",
     "geolocation": {
       "status": "collected",
       "latitude": -23.5505,
       "longitude": -46.6333,
       "accuracy": 25,
       "timestamp": 1700000000000
     }
   }

6. Confirm signing succeeds and the stored signer metadata includes geolocation coordinates.
7. Repeat with mode: "optional" and allowRequesterOverride: true, creating a request with geolocationRequired: true on selected signers, and verify only those signers are enforced.
8. Run focused automated checks:

   composer test:unit -- --filter SignerGeolocation
   vendor/bin/behat features/sign/signer_geolocation.feature -v
   vendor/bin/behat features/policies/signer_geolocation_policy.feature -v
   npx playwright test playwright/e2e/signer-geolocation-backend.spec.ts

⚙️ API / Back‑end changes

• Add signer_geolocation policy provider with modes disabled, optional, and required, plus allowRequesterOverride delegation
• Freeze per-signer geolocationRequirement on signature request creation via SignerGeolocationFilePolicyApplier
• Accept and validate geolocation on sign endpoints; reject missing/invalid submissions when required
• Persist geolocation coordinates in signer metadata independently of collect_metadata
• Expose geolocation-related fields in request/sign/list API responses
• Unit, API DB, Behat, and Playwright coverage added
• Capabilities updated (not applicable)
• Documentation updated (if applicable) - docs repository
• API documentation updated with composer openapi

✅ Checklist

• I have read and followed the contribution guide.
• Focused unit tests added for policy provider, applier, runtime services, and sign/request enforcement
• Behat scenarios cover required mode, requester override, and independence from collect_metadata
• OpenAPI and TypeScript types regenerated

🤖 AI (if applicable)

• The content of this PR was partially or fully generated using AI

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.
see 209 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[vitormattos]

It looks like we only persist the geolocation requirement to the last SignRequest created for the signer.

A signer can have multiple identifyMethods, and each iteration can create/update a SignRequest. Shouldn't we persist the effective requirement for every created sign request?

Otherwise, a sign request without geolocationRequirement will fall back to disabled during validation, which could bypass a required geolocation policy.

It would also be good to add a test with multiple identify methods for the same signer to validate if will work fine.

[vitormattos]

Could we avoid exposing the complete signer metadata here and only expose the geolocation metadata needed by this feature?

I think this should be based on the data stored in the SignRequest, not on the current policy. For example, a request may have required geolocation, the signer may already have signed and stored it, and the admin may disable the policy later. We should still return the historical data for that signer.

So, when present, I think we only need to expose geolocationRequirement and geolocation here. This also avoids unintentionally exposing unrelated current or future signer metadata with empty data through the file list API.

Could we also add a regression test covering this behavior to validate when this data is present and when not?