[lfals]

Resolves: #8086

📝 Summary

Finalizes the signer geolocation backend for #8086:

• Split into two independent policies: signer_device_geolocation and signer_ip_geolocation
• Final device contract names (deviceGeolocation*) and nested stored metadata under geolocation.{device,ip}
• Write-once policy snapshots (absent ⇒ disabled; no live-policy fallback)
• Local MaxMind City GeoIP via scoped LibreSign/3rdparty (geoip2/geoip2)
• Admin-only GET/POST /api/v1/admin/geoip
• IP lookup from Nextcloud IRequest::getRemoteAddress(), collected before the sync/async signing split; failures never block signing

Minimal frontend renames keep existing device flows green. Full GeoIP / Policy Workbench / audit UI remains #8087.

🧪 How to test

1. Configure a MaxMind City .mmdb path (e.g. tests/php/fixtures/geoip/GeoIP2-City-Test.mmdb).
2. As admin:
   • GET /ocs/v2.php/apps/libresign/api/v1/admin/geoip
   • POST /ocs/v2.php/apps/libresign/api/v1/admin/geoip with {"path":"..."}
     Confirm status and that no signer data is returned.
3. Enable:
   • signer_device_geolocation → required
   • signer_ip_geolocation → enabled
4. Create a signature request and confirm both policies are frozen in policy_snapshot.
5. Sign without deviceGeolocation → 422.
6. Sign with deviceGeolocation → 200; metadata includes geolocation.device and geolocation.ip (at least status + sourceIp).
7. Confirm later policy enable/disable does not change existing requests; only new requests pick up the new effective policy.
8. Confirm GeoIP failures / missing DB never block signing.
9. Focused checks (optional):
   • composer test:unit -- --filter GeoIp
   • composer test:unit -- --filter SignerIpGeolocation
   • Behat: tests/integration/features/sign/signer_geolocation.feature
   • Behat: tests/integration/features/policies/signer_geolocation_policy.feature

How to see this running using GitHub Codespaces

1. Open the Codespace

• Authenticate to GitHub
• Go to the branch: feat/geolocation-ip-based
• Click the Code button and select the Codespaces tab.
• Click "Create codespace on feat/geolocation-ip-based"

2. Wait for the environment to start

• Wait until you see:

  ✍️ LibreSign is up!

3. Access LibreSign in the browser

• Open the Ports tab and open port 80 via the globe icon.

4. Login credentials

• Username: admin
• Password: admin

🎨 UI / Front‑end changes

• Rename device geolocation fields to the final contract (deviceGeolocation, deviceGeolocationRequired, deviceGeolocationRequirement)
• Read nested geolocation.device in validation/sign helpers
• Update Policy Workbench key to signer_device_geolocation (IP policy UI deferred to Finalize signer geolocation frontend with IP-based location #8087)
• Vitest coverage updated for the renames
• Screenshots before/after — N/A (contract rename only; no GeoIP UI here)

🚧 Tasks

• Finalize signer geolocation frontend with IP-based location #8087 — Policy Workbench + audit/validation UI for IP geolocation

⚙️ API / Back‑end changes

• Independent policies + write-once snapshot freeze
• Nested geolocation.device / geolocation.ip; independent from collect_metadata
• GeoIP services (config, status, lookup, normalizer) + admin GeoIP API
• Lookup before sync/async split; non-blocking on failure
• Ship geoip2/geoip2 through scoped LibreSign/3rdparty
• OpenAPI + generated TypeScript types regenerated
• Unit + Behat coverage for device rename / GeoIP services / IP policy appliers
• REUSE: add LICENSES/Apache-2.0.txt for MaxMind test fixture attribution
• Capabilities — N/A
• Docs follow-up in LibreSign/documentation if needed

🚧 Tasks

• Merge feat: add geoip2/geoip2 for local MaxMind City lookups 3rdparty#101 (feat/geoip2-dependency) and retarget the submodule if the merged SHA differs from 2e04147
• Remaining Finalize signer geolocation backend with IP-based location #8086 test-matrix gaps (optional follow-up): IP freeze Behat, async non-relookup proof, admin GeoIP auth tests, Infection for isolated GeoIP classes

✅ Checklist

• Followed the contribution guide
• Backend contract matches Finalize signer geolocation backend with IP-based location #8086
• REUSE compliance for GeoIP fixtures

🤖 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

❌ Patch coverage is 88.88889% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/components/Request/IdentifySigner.vue	77.77%	0 Missing and 2 partials ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Files with missing lines	Coverage Δ
src/components/validation/EnvelopeValidation.vue	75.92% <100.00%> (+6.51%)	⬆️
src/components/validation/SignerDetails.vue	52.79% <100.00%> (+12.91%)	⬆️
src/helpers/signerGeolocation.ts	87.03% <100.00%> (ø)
src/services/signSubmit.ts	76.54% <ø> (ø)
src/store/files.js	75.97% <100.00%> (+1.11%)	⬆️
...ttings/PolicyWorkbench/settings/realDefinitions.ts	100.00% <ø> (ø)
...ench/settings/signer-geolocation/realDefinition.ts	73.33% <ø> (ø)
src/views/SignPDF/_partials/Sign.vue	59.93% <100.00%> (+8.14%)	⬆️
src/components/Request/IdentifySigner.vue	76.54% <77.77%> (-6.80%)	⬇️

... and 224 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.

[YvesCesar]

Many thanks for your contribution, @lfals :)

I added a few points for review.

A question:

About the 3rdparty submodule bump in this PR: it points to 2e04147, which is only reachable from the fork branch, right? LibreSign/3rdparty#101 was closed without being merged, so geoip2/geoip2 currently has no home in LibreSign/3rdparty. The commit itself is fine (the scoped package is there under composer/geoip2/geoip2/), it just needs to land on a LibreSign/3rdparty branch and the SHA retargeted before this can be merged.

[lfals]

@YvesCesar , 3rdparty submodule updated!

[lfals]

@vitormattos behat failing again, now we have logs. I'll take a look, but feel free to do too

[YvesCesar]

@lfals

I brought up a few more points. Could you take a look?

[YvesCesar]

Thanks, @lfals

@vitormattos this PR looks good to me.

[vitormattos]

Thanks, Luiz.

I reviewed the latest push. The migration now processes metadata in bounded batches, so the memory concern from the previous review is addressed. The current CI is also fully green, including the Playwright suite.

For the Playwright environment itself, we created separate follow-up work to align LibreSign with the current Nextcloud E2E/Playwright pattern and later consume the shared LibreCode workflow:

• #8727
• LibreCodeCoop/.github#73
• LibreCodeCoop/.github#74
• #8728

These are follow-up improvements to the test environment and are not blockers for this PR.

From my side, this is ready to approve.