# VPNCheap Xboard Server State and Security Improvement Plan

Date: 2026-07-31  
Mode: planning only  
Plan confidence: **95/100**. Make token invalidation, node/account freshness, and official-client access explicit server contracts rather than client guesses. This is an executive judgment score, separate from fingerprint priority.

Governing contract: [Feedback-to-Roadmap Decision Contract v1.0, 2026-07-31](https://vpncheap-feedback-brief-20260731.pages.dev/feedback-to-roadmap-decision-contract.md)

## Evidence and state

- **OBSERVED:** an old subscription URL appeared valid after reset; native clients repeatedly saw no nodes or stale renewal/account state.
- **MEASURED:** reset rotates UUID and token, middleware compares the current database token, and generated URLs use the new token. No live old/new token plus cache test closes the contradiction.
- **MEASURED:** current user agents are inconsistent and only influence response format. UA is not authorization.

`△△ ☐☐ | 0/2/2/0`

| State | IDs | Server obligation |
|---|---|---|
| `△` | VPN-11, VPN-12 | Rotation and several self-heals exist; production/interop matrix is missing. |
| `☐` | VPN-13, VPN-17 | Official-client capability and shared freshness envelope are not implemented. |

```text
BEFORE  token/cache/client each imply truth -> stale or contradictory UI
AFTER   server revision + atomic invalidation + signed capability -> one receipt
```

## Execution sequence

Order follows dependency and owner sequence, not numeric rank. Canonical fingerprint scores and program-value judgments are different decision ledgers and are not directly comparable.

Scores below are canonical registry references, not local rescores: items 1-4 -> VPN-11, VPN-12, VPN-17, and VPN-13 respectively.

### 1. Token-rotation invariant: 80/100, P1

Breakdown: `30 + 3 + 12 + 15 + 10 + 10`.

**PROPOSED:** first test old URL, new URL, web and API middleware, edge/app cache, concurrent request, and rollback on an approved non-production fixture. If current code passes, close with a production-safe read/probe receipt; if not, fix atomic invalidation at the earliest cache or middleware layer.

### 2. Native node-state contract: 81/100, P1

Breakdown: `24 + 15 + 12 + 15 + 5 + 10`.

**PROPOSED:** version the auth, subscription, and node response contract; return stable safe reasons for empty, auth-expired, subscription-invalid, endpoint-unavailable, and recovered states; run the released-client matrix across every native owner.

### 3. Account and subscription freshness envelope: 81/100, P1

Breakdown: `24 + 15 + 12 + 15 + 5 + 10`.

**PROPOSED:** provide authoritative server generation/revision and timestamps for account, entitlement, subscription, and node state; define conditional fetch, forced refresh, cache invalidation, account switch, and stale response rejection.

### 4. Official-client capability contract: 54/100, P3 evidence gate

Breakdown: `24 + 3 + 5 + 15 + 0 + 7`.

Proposed-only score is capped at 54. Inventory every shipped client identifier and update path, then design a versioned signed session/capability that survives rotation and offline recovery. UA-only gating scores **18/100** because it is spoofable and current identifiers conflict.

## Phases

- **0-30:** old/new-token interop test; freeze the P1/P2 state-reason and revision contracts; publish client migration matrix.
- **0-30, P3 evidence only:** inventory signed-capability dependencies and collect its evidence envelope; this is ordinary evidence collection, not P3 acceleration, and no exception is claimed.
- **31-60:** implement P1/P2 rotation, state, and revision contracts behind versioned compatibility; update clients in isolated branches; add cache/race/account-switch tests.
- **61-90:** after scheduled P0-P2 gates close, define and implement the signed-capability contract, then canary by client family; monitor invalid-token acceptance, empty-node reasons, stale revision rejection, forced-refresh success, signed-capability compatibility, and legacy compatibility.

### Phase gates

- **0-30:** evidence coverage reaches 100%.
- **31-60:** every scheduled P1/P2 acceptance is complete or explicitly approved `X`.
- **61-90:** two canary windows close without regression.
- Stop immediately on any listed guardrail.
- No P3 acceleration is claimed; signed-capability work starts in 61-90 only after P0-P2 gates close.

## Acceptance and stop conditions

- Old token fails and new token succeeds across every cache and route after reset.
- Top-up/renewal/node changes become visible without re-login and without an older response overwriting a newer generation.
- Unknown/legacy clients remain on an explicit bounded compatibility policy; no silent access widening.
- Stop on account crossover, token replay, cache inconsistency, unauthenticated data access, or client lockout without rollback.