xworkmate-app/docs/testing/bridge-sync-contract-chain.md

Bridge Sync Contract Chain

Scope

This note documents the account-driven bridge sync chain after the naming unification to:

• BRIDGE_SERVER_URL
• BRIDGE_AUTH_TOKEN

It focuses on the runtime data path:

• accounts.svc.plus
• xworkmate-app
• xworkmate-bridge

and the two key client-side parsing assertions:

• BRIDGE_SERVER_URL is written into account sync state
• BRIDGE_AUTH_TOKEN is written into secure storage

Sync Chain

flowchart LR
    A["accounts.svc.plus\nprotected login / MFA / sync / bootstrap response"] -->|returns| B["xworkmate-app\nparse BRIDGE_SERVER_URL\nparse BRIDGE_AUTH_TOKEN"]
    B -->|write| C["AccountSyncState.syncedDefaults.bridgeServerUrl"]
    B -->|write secure only| D["Secure Storage\nbridge.auth_token"]
    C -->|drive runtime metadata| E["cloudSynced.remoteServerSummary.endpoint"]
    D -->|Authorization: Bearer <token>| F["xworkmate-app runtime requests"]
    F --> G["xworkmate-bridge"]

Field Ownership

flowchart TD
    A["accounts.svc.plus"] --> A1["BRIDGE_SERVER_URL\nplain response field"]
    A --> A2["BRIDGE_AUTH_TOKEN\nprotected response field only"]

    B["xworkmate-app"] --> B1["sync state\nstores BRIDGE_SERVER_URL-derived bridgeServerUrl"]
    B --> B2["secure storage\nstores BRIDGE_AUTH_TOKEN as bridge.auth_token"]
    B --> B3["normal settings/profile\nmust not persist BRIDGE_AUTH_TOKEN"]

    C["xworkmate-bridge"] --> C1["consume bootstrap response"]
    C1 --> C2["uses BRIDGE_SERVER_URL"]
    C1 --> C3["uses BRIDGE_AUTH_TOKEN"]

Parsing And Persistence Checks

sequenceDiagram
    participant Accounts as accounts.svc.plus
    participant App as xworkmate-app
    participant SyncState as Account Sync State
    participant SecureStore as Secure Storage
    participant Bridge as xworkmate-bridge

    Accounts->>App: protected response\nBRIDGE_SERVER_URL\nBRIDGE_AUTH_TOKEN
    App->>SyncState: save bridgeServerUrl from BRIDGE_SERVER_URL
    App->>SecureStore: save bridge.auth_token from BRIDGE_AUTH_TOKEN
    App->>Bridge: connect with Authorization: Bearer <token>

Test Coverage Targets

flowchart TD
    T["Account sync parsing tests"] --> T1["assert BRIDGE_SERVER_URL -> AccountSyncState.syncedDefaults.bridgeServerUrl"]
    T --> T2["assert BRIDGE_SERVER_URL -> cloudSynced.remoteServerSummary.endpoint"]
    T --> T3["assert BRIDGE_AUTH_TOKEN -> secure storage target bridge.auth_token"]
    T --> T4["assert BRIDGE_AUTH_TOKEN never enters normal settings/profile persistence"]
    T --> T5["assert offline path can still read token from secure storage"]

Expected Invariants

• BRIDGE_SERVER_URL is the only bridge endpoint field used by the sync contract.
• BRIDGE_AUTH_TOKEN is the only bridge token field used by the sync contract.
• BRIDGE_AUTH_TOKEN must never be written into normal settings snapshot, profile JSON, or UI-visible text.
• Client requests must assemble the header as Authorization: Bearer <token>.