feat(protocol): define native session credentials

openapi/control-v1.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 info:
   title: VerseVDI control contract
   version: 1.0.0
-  description: Bounded Phase 3A control-plane wire contract; no provider or media endpoints.
+  description: Bounded control-plane wire contract. The current SessionRequest shape is control wire version 2; no provider or media endpoints.
 servers:
   - url: /
 tags:
@@ -23,18 +23,11 @@ paths:
               $ref: ../schemas/control-v1.schema.json#/$defs/LoginRequest
       responses:
         '200':
-          description: Browser session established through secure cookies.
+          description: Browser session established through secure cookies; native identity is structurally forbidden.
           content:
             application/json:
               schema:
-                type: object
-                additionalProperties: false
-                required: [username, provider, roles, role]
-                properties:
-                  username: {type: string, minLength: 1, maxLength: 256}
-                  provider: {type: string, minLength: 1, maxLength: 64}
-                  roles: {type: array, maxItems: 16, items: {type: string, maxLength: 64}}
-                  role: {type: string, enum: [user, admin]}
+                $ref: ../schemas/control-v1.schema.json#/$defs/BrowserAuthenticatedSession
         '400': {$ref: '#/components/responses/InvalidRequest'}
         '401': {$ref: '#/components/responses/Unauthorized'}
         '503': {$ref: '#/components/responses/Unavailable'}
@@ -66,18 +59,32 @@ paths:
         - nativeBearer: []
       responses:
         '200':
-          description: Authenticated subject summary.
+          description: Route-context-specific authenticated subject summary. Browser responses forbid native identity; native bearer responses require it.
           content:
             application/json:
               schema:
-                type: object
-                additionalProperties: false
-                required: [username, provider, roles, role]
-                properties:
-                  username: {type: string, minLength: 1, maxLength: 256}
-                  provider: {type: string, minLength: 1, maxLength: 64}
-                  roles: {type: array, maxItems: 16, items: {type: string, maxLength: 64}}
-                  role: {type: string, enum: [user, admin]}
+                oneOf:
+                  - $ref: ../schemas/control-v1.schema.json#/$defs/BrowserAuthenticatedSession
+                  - $ref: ../schemas/control-v1.schema.json#/$defs/NativeAuthenticatedSession
+        '401': {$ref: '#/components/responses/Unauthorized'}
+  /api/v1/auth/tunnel-credentials:
+    post:
+      tags: [authentication]
+      operationId: issueNativeTunnelCredential
+      security:
+        - nativeBearer: []
+      responses:
+        '200':
+          description: Short-lived native tunnel credential. The response must not be stored.
+          headers:
+            Cache-Control:
+              description: Prevent storage of the credential response.
+              required: true
+              schema: {type: string, const: no-store}
+          content:
+            application/json:
+              schema:
+                $ref: ../schemas/control-v1.schema.json#/$defs/NativeTunnelCredential
         '401': {$ref: '#/components/responses/Unauthorized'}
   /api/v1/auth/reauth:
     post:
@@ -189,6 +196,7 @@ paths:
     post:
       tags: [broker]
       operationId: requestBrokerSession
+      description: Control wire version 2 endpoint. Legacy version-1 SessionRequest payloads containing client-supplied policy_snapshot are rejected.
       security:
         - browserSession: []
         - nativeBearer: []