82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# 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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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
|
|
|
|
```mermaid
|
|
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>`.
|