# 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.