protocol: add canonical Phase 3A contract sources

2026-07-21 23:42:13 +07:00
parent 75edd9941b
commit 2d69357052
16 changed files with 1052 additions and 0 deletions
@@ -0,0 +1,43 @@
+# 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.