fix: keep VPN usage as audit metadata

[Seranged]

Summary

VPN usage is audit metadata. A positive VPN flag or an unavailable VPN measurement must not disconnect an otherwise eligible wallet; wallet access depends on the address-screening verdict.

Changes

• Continue address screening for every VPN result and forward the evidence for recording.
• Represent failed, missing, invalid, or unsupported client VPN measurements as null; preserve measured true and false values.
• Keep country restrictions, screening failure handling, and stale-request protection enforced.
• Update the architecture documentation and regression coverage for both eligible and restricted addresses.

Test plan

• npm run lint (0 errors; 6 existing warnings)
• npm run typecheck
• npm run build
• npm run test:run (221 files; 2,164 tests passed)
• Regression coverage for positive/negative/unknown VPN evidence, probe timeouts and network/HTTP failures, audit payloads, and restricted-wallet disconnection

No environment changes are required. Live wallet browser validation has not been performed for this change.

Summary by CodeRabbit

• Behavior Changes

  • Address access is now determined solely by screening results; VPN detection no longer independently blocks connected addresses.
  • VPN usage is recorded as audit metadata, including an indeterminate state when detection is unavailable.
  • VPN detection now distinguishes between detected, not detected, and unknown results, with improved handling of failed or unsupported checks.

• Documentation

  • Updated wallet-screening documentation to describe the revised VPN detection and screening behavior.

[railway-app]

🚅 Deployed to the euler-lite-pr-861 environment in euler-lite(dev,PR previews)

Service	Status	Web	Updated
dev-build	✅ Success (View Logs)	Web	Sep 10, 2026 at 12:22 pm UTC

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: euler-xyz/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Essentials

Run ID: 99e37c58-2d03-4186-957a-5e1b017c8734

📥 Commits

Reviewing files that changed from the base of the PR and between 2ee0fa6 and 40834da.

📒 Files selected for processing (7)

• composables/useAddressScreen.ts
• docs/architecture.md
• services/screening.ts
• services/vpn.ts
• tests/composables/useAddressScreen.test.ts
• tests/services/screening.test.ts
• tests/services/vpn.test.ts

Included review availability: 4 reviews are currently available. Your included PR review attempts over the past 7 days set your current allowance at 5 reviews per hour.

---

📝 Walkthrough

Walkthrough

VPN detection now returns true, false, or null as audit metadata. Address access is controlled only by the remote screening verdict. Tests cover forwarding, unavailable evidence, and screening behavior.

Changes

VPN-aware address screening

Layer / File(s)	Summary
Nullable VPN evidence and screening contract services/vpn.ts, services/screening.ts	VPN detection normalizes response headers and returns null for unavailable or invalid evidence. screenAddress accepts and forwards nullable VPN metadata.
Screening-controlled address access composables/useAddressScreen.ts, docs/architecture.md	Address screening no longer blocks independently on a local VPN verdict. Access follows the screening result, and the documentation describes nullable VPN audit metadata.
Tri-state screening validation tests/services/vpn.test.ts, tests/services/screening.test.ts, tests/composables/useAddressScreen.test.ts	Tests cover VPN verdict normalization, failed probes, nullable request forwarding, and allowed or restricted address behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant WalletScreen
  participant VPNDetection
  participant AddressScreening
  WalletScreen->>VPNDetection: Detect VPN usage
  VPNDetection-->>WalletScreen: Return true, false, or null
  WalletScreen->>AddressScreening: Send address and vpnIsUsed
  AddressScreening-->>WalletScreen: Return screening verdict
  WalletScreen->>WalletScreen: Allow or block from screening verdict

Loading

Suggested reviewers: kasperpawlowski

Merge Risk: ⚪ Minimal · up to 40834

VPN results remain audit metadata while screening continues to control wallet access. The tested change is mergeable with no actionable current-head risk identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 6 files. (1 skipped: 1…	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: VPN usage remains audit metadata instead of controlling wallet access.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 3 functions across 6 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/vpn-telemetry-only

Warning

Some tools did not complete. Review the errors below.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

composables/useAddressScreen.ts

ESLint skipped: missing config or dependency (missing-dependency). The ESLint configuration references a package that is not available in the sandbox.

services/screening.ts

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

services/vpn.ts

ESLint skipped: the matched ESLint configuration already failed (missing-dependency).

• 3 others

---

_{Comment @coderabbitai help to get the list of available commands.}

[LeonardEulerXYZ]

Review — approved

Reviewed exact head 40834da9f0fbc8904962466df1c69d94ce587f5a against development. No blocking findings.

Scope and walkthrough

• Reviewed all seven changed files: the address-screening composable, both client services, their three test files, and architecture documentation.
• VPN detection now distinguishes measured true/false from unavailable evidence, and no longer independently disconnects eligible addresses. All three values continue into address screening.
• Checked the adjacent server proxy, trusted-edge evidence precedence, country restriction middleware, and stale-generation guards. Address-screening failures remain fail-closed; client false/null cannot erase positive trusted-edge evidence.
• Cross-repo check: current Data v3 route accepts nullable VPN input, its screening service records it on audit paths rather than using it as the eligibility verdict, and its operations documentation describes the same contract. No consumer package/schema update is needed for this change.
• Whole-diff security pass: no dependency, credential, deployment configuration, or network-destination changes.

Validation

• npx vitest run tests/composables/useAddressScreen.test.ts tests/services/vpn.test.ts tests/services/screening.test.ts tests/server/screen-address.test.ts tests/server/edge.test.ts tests/server/geo-gate.test.ts — 6 files, 86 tests passed.
• npm run test:run — 221 files, 2,164 tests passed.
• npm run typecheck — passed.
• npm run lint — 0 errors, 6 warnings in unchanged files.
• npm run build — passed.

The concrete screening fixture is the existing mocked address 0x0000000000000000000000000000000000000001, exercised with clean/restricted verdicts and true/false/null VPN evidence. This is source and automated-test validation, not a live provider call or wallet-browser smoke. Technical approval does not establish production deployment or replace any required policy-owner sign-off.