44 lines
3.3 KiB
Markdown
44 lines
3.3 KiB
Markdown
# Phase 3A interface inventory
|
|
|
|
This inventory records the wire boundary consumed by the closed Connection Server.
|
|
The Protocol repository owns only schemas, registries, fixtures, and generated bindings;
|
|
the Server remains the authority for authentication, authorization, persistence, and
|
|
provider selection.
|
|
|
|
## Existing Server routes adapted by generated contracts
|
|
|
|
| Route | Channel/guard | Contract boundary | Phase 2 behavior |
|
|
|---|---|---|---|
|
|
| `POST /api/v1/auth/refresh` | native credential body; rate limited | `RefreshRequest` -> `NativeCredential` | opaque refresh rotation and replay-family revocation remain PostgreSQL-owned |
|
|
| `POST /api/v1/auth/devices` | authenticated browser session + CSRF | `DeviceRegistrationRequest` -> `DeviceChallenge` | device challenge remains one-use and hash-backed |
|
|
| `POST /api/v1/auth/devices/:id/prove` | authenticated browser session + CSRF | `DeviceProofRequest` -> `NativeCredential` | canonical Ed25519 proof and native session issuance remain Server-owned |
|
|
| `DELETE /api/v1/auth/devices/:id` | authenticated browser session + CSRF | no body | principal-scoped device revocation remains Server-owned |
|
|
| `GET /api/v1/resources` | authenticated browser/native session | `ResourceList` | assigned desktop and entitled pool projections omit machine/provider data |
|
|
| `POST /api/v1/broker/sessions` | authenticated session + CSRF | `SessionRequest` -> `BrokerSession` | existing assignment, idempotency, queue, and PostgreSQL state machine remain authoritative |
|
|
| `GET /api/v1/broker/sessions/:id` | authenticated session | `BrokerSession` | owner-scoped lookup is preserved |
|
|
| `POST /api/v1/broker/sessions/:id/allocate` | authenticated session + CSRF | `ConnectionManifest` | gateway-only grant boundary; no provider/direct-host fields |
|
|
| `POST /api/v1/broker/sessions/:id/reconnect` | authenticated session + CSRF | `ReconnectRequest` -> `ConnectionManifest` | device proof, expected version, grant rotation, and monotonic reconnect sequence remain authoritative |
|
|
| `POST /api/v1/broker/sessions/:id/cancel` | authenticated session + CSRF | no body | existing compensation path remains authoritative |
|
|
|
|
## Contract rules
|
|
|
|
- Unknown fields are rejected for signed/security-sensitive requests and generated
|
|
decoders are strict.
|
|
- Responses are explicit projections; domain, sqlc, provider, VM, and credential
|
|
structures are never serialized directly.
|
|
- Resource projections contain only opaque assignment/pool identifiers and safe state;
|
|
machine identifiers and provider endpoints are not wire fields.
|
|
- A manifest contains only the versioned gateway/tunnel/profile/grant allow-list. The
|
|
opaque grant is stored as a hash in the Server database and is single-use.
|
|
- Events and QUIC/tunnel sources are defined here before any production media or gateway
|
|
implementation; the Phase 3A claim stops at control contracts and conformance.
|
|
|
|
## Compatibility notes
|
|
|
|
The existing routes and authentication channels remain unchanged. Phase 3A adds the
|
|
`page` member to the resource response and replaces the legacy flat manifest projection
|
|
with the versioned gateway-only manifest. Both changes are intentional contract changes:
|
|
the former is additive, and the latter is required to make provider/direct-host fields
|
|
unrepresentable. The Server integration tests retain the old safe resource members and
|
|
assert the new allow-list explicitly.
|