@opensoha/contracts 0.1.11 → 0.1.12

package/compat/json-schema-ecosystem-0.1.0.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.11",
+  "version": "0.1.12",
   "schemas": {
     "plugins/plugin-manifest.schema.json": {
       "rootRequired": ["id", "name", "publisher", "type", "version"],

package/compat/openapi-loose-boundaries-0.1.0.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.11",
+  "version": "0.1.12",
   "generatedFrom": "openapi/soha-api.yaml",
   "entries": [
     {

package/fixtures/openapi/DockerHostAgentCredentialsEnvelope/invalid/missing-runtime-token.json

@@ -0,0 +1,9 @@
+{
+  "data": {
+    "hostId": "runtime-host-01",
+    "operationId": "host-sync-01",
+    "agentId": "docker-agent-01",
+    "agentBearerToken": "agent-secret-012345678901234567890",
+    "issuedAt": "2026-08-14T10:15:00Z"
+  }
+}

package/fixtures/openapi/DockerHostAgentCredentialsEnvelope/valid/credentials.json

@@ -0,0 +1,10 @@
+{
+  "data": {
+    "hostId": "runtime-host-01",
+    "operationId": "host-sync-01",
+    "agentId": "docker-agent-01",
+    "agentBearerToken": "agent-secret-012345678901234567890",
+    "runtimeBearerToken": "runtime-secret-012345678901234567",
+    "issuedAt": "2026-08-14T10:15:00Z"
+  }
+}

package/fixtures/openapi/DockerHostAgentEnrollmentRequest/invalid/short-token.json

@@ -0,0 +1,4 @@
+{
+  "agentId": "docker-agent-01",
+  "enrollmentToken": "too-short"
+}

package/fixtures/openapi/DockerHostAgentEnrollmentRequest/valid/enrollment.json

@@ -0,0 +1,4 @@
+{
+  "agentId": "docker-agent-01",
+  "enrollmentToken": "enrollment-secret-0123456789012345"
+}

package/gen/go/sohaapi/client.go

@@ -14,7 +14,7 @@ import (
 	"time"
 )
 
-const defaultUserAgent = "opensoha-contracts/0.1.11"
+const defaultUserAgent = "opensoha-contracts/0.1.12"
 
 type Client struct {
 	BaseURL    string
@@ -404,6 +404,15 @@ func (c *Client) ClaimDockerOperation(ctx context.Context, req DockerOperationCl
 	return out.Data, nil
 }
 
+func (c *Client) ExchangeDockerHostAgentEnrollment(ctx context.Context, operationID string, req DockerHostAgentEnrollmentRequest) (DockerHostAgentCredentials, error) {
+	var out DockerHostAgentCredentialsEnvelope
+	path := "/docker/agent-installations/" + url.PathEscape(strings.TrimSpace(operationID)) + "/enroll"
+	if err := c.doJSON(ctx, http.MethodPost, path, false, req, &out); err != nil {
+		return DockerHostAgentCredentials{}, err
+	}
+	return out.Data, nil
+}
+
 func (c *Client) GetDockerOperationRunnerStatus(ctx context.Context, operationID string) (DockerOperation, error) {
 	var out DockerOperationEnvelope
 	path := "/docker/operations/" + url.PathEscape(strings.TrimSpace(operationID)) + "/runner-status"

package/gen/go/sohaapi/client_test.go

@@ -143,6 +143,35 @@ func TestRunnerClaimClientsAcceptNoContent(t *testing.T) {
 	}
 }
 
+func TestExchangeDockerHostAgentEnrollmentIsPublicAndReturnsCredentials(t *testing.T) {
+	issuedAt := time.Now().UTC().Truncate(time.Second)
+	client := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
+		assertPublicRequest(t, r, http.MethodPost, "/api/v1/docker/agent-installations/operation-1/enroll")
+		request := decodeJSONRequestBody[DockerHostAgentEnrollmentRequest](t, r)
+		if request.AgentID != "host-1" || request.EnrollmentToken != "enrollment-secret-0123456789012345" {
+			t.Fatalf("enrollment request = %#v", request)
+		}
+		w.Header().Set("Cache-Control", "no-store")
+		w.WriteHeader(http.StatusCreated)
+		writeJSON(t, w, map[string]any{"data": map[string]any{
+			"hostId": "host-1", "operationId": "operation-1", "agentId": "host-1",
+			"agentBearerToken": "agent-secret-012345678901234567890",
+			"runtimeBearerToken": "runtime-secret-012345678901234567",
+			"issuedAt": issuedAt,
+		}})
+	})
+
+	credentials, err := client.ExchangeDockerHostAgentEnrollment(context.Background(), "operation-1", DockerHostAgentEnrollmentRequest{
+		AgentID: "host-1", EnrollmentToken: "enrollment-secret-0123456789012345",
+	})
+	if err != nil {
+		t.Fatalf("exchange enrollment: %v", err)
+	}
+	if credentials.HostID != "host-1" || credentials.OperationID != "operation-1" || credentials.RuntimeBearerToken == "" || credentials.AgentBearerToken == "" {
+		t.Fatalf("credentials = %#v", credentials)
+	}
+}
+
 func TestRedeemSecretLeaseSendsRunnerBindingHeaders(t *testing.T) {
 	client := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
 		assertCommonRequest(t, r, http.MethodPost, "/api/v1/runner/secret-leases/lease%2Fone/redeem")

package/gen/go/sohaapi/types.go

@@ -9758,6 +9758,32 @@ type DockerGitBuildInput struct {
 	RepositoryURL  string `json:"repositoryUrl"`
 }
 
+// DockerHostAgentCredentials defines model for DockerHostAgentCredentials.
+type DockerHostAgentCredentials struct {
+	// AgentBearerToken Credential for the Agent's local HTTP API, returned only by the successful enrollment response.
+	AgentBearerToken string    `json:"agentBearerToken"`
+	AgentID          string    `json:"agentId"`
+	HostID           string    `json:"hostId"`
+	IssuedAt         time.Time `json:"issuedAt"`
+	OperationID      string    `json:"operationId"`
+
+	// RuntimeBearerToken Revocable credential restricted to Docker operations for this host.
+	RuntimeBearerToken string `json:"runtimeBearerToken"`
+}
+
+// DockerHostAgentCredentialsEnvelope defines model for DockerHostAgentCredentialsEnvelope.
+type DockerHostAgentCredentialsEnvelope struct {
+	Data DockerHostAgentCredentials `json:"data"`
+}
+
+// DockerHostAgentEnrollmentRequest defines model for DockerHostAgentEnrollmentRequest.
+type DockerHostAgentEnrollmentRequest struct {
+	AgentID string `json:"agentId"`
+
+	// EnrollmentToken Short-lived one-time secret delivered only inside the installer.
+	EnrollmentToken string `json:"enrollmentToken"`
+}
+
 // DockerHostAgentInstallation defines model for DockerHostAgentInstallation.
 type DockerHostAgentInstallation struct {
 	Command     string    `json:"command"`
@@ -21526,6 +21552,9 @@ type TriggerManifestSourceWebhookJSONRequestBody = ManifestSyncWebhookInput
 // CreateDeliveryPlanJSONRequestBody defines body for CreateDeliveryPlan for application/json ContentType.
 type CreateDeliveryPlanJSONRequestBody = DeliveryPlanInput
 
+// ExchangeDockerHostAgentEnrollmentJSONRequestBody defines body for ExchangeDockerHostAgentEnrollment for application/json ContentType.
+type ExchangeDockerHostAgentEnrollmentJSONRequestBody = DockerHostAgentEnrollmentRequest
+
 // StartDockerContainerJSONRequestBody defines body for StartDockerContainer for application/json ContentType.
 type StartDockerContainerJSONRequestBody = DockerContainerStartInput
 

package/gen/ts/sohaapi/index.ts

@@ -2065,6 +2065,22 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/docker/agent-installations/{operationID}/enroll": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: operations["exchangeDockerHostAgentEnrollment"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/docker/hosts/quick-create/plan": {
         parameters: {
             query?: never;
@@ -15240,6 +15256,34 @@ export interface components {
         DockerHostAgentInstallationEnvelope: {
             data: components["schemas"]["DockerHostAgentInstallation"];
         };
+        DockerHostAgentEnrollmentRequest: {
+            agentId: string;
+            /**
+             * Format: password
+             * @description Short-lived one-time secret delivered only inside the installer.
+             */
+            enrollmentToken: string;
+        };
+        DockerHostAgentCredentials: {
+            hostId: string;
+            operationId: string;
+            agentId: string;
+            /**
+             * Format: password
+             * @description Credential for the Agent's local HTTP API, returned only by the successful enrollment response.
+             */
+            agentBearerToken: string;
+            /**
+             * Format: password
+             * @description Revocable credential restricted to Docker operations for this host.
+             */
+            runtimeBearerToken: string;
+            /** Format: date-time */
+            issuedAt: string;
+        };
+        DockerHostAgentCredentialsEnvelope: {
+            data: components["schemas"]["DockerHostAgentCredentials"];
+        };
         /** @enum {string} */
         ObservabilityProviderSignal: "logs" | "metrics" | "traces" | "profiles";
         /** @enum {string} */
@@ -19162,6 +19206,9 @@ export type AgentInstallation = components['schemas']['AgentInstallation'];
 export type AgentInstallationEnvelope = components['schemas']['AgentInstallationEnvelope'];
 export type DockerHostAgentInstallation = components['schemas']['DockerHostAgentInstallation'];
 export type DockerHostAgentInstallationEnvelope = components['schemas']['DockerHostAgentInstallationEnvelope'];
+export type DockerHostAgentEnrollmentRequest = components['schemas']['DockerHostAgentEnrollmentRequest'];
+export type DockerHostAgentCredentials = components['schemas']['DockerHostAgentCredentials'];
+export type DockerHostAgentCredentialsEnvelope = components['schemas']['DockerHostAgentCredentialsEnvelope'];
 export type ObservabilityProviderSignal = components['schemas']['ObservabilityProviderSignal'];
 export type ObservabilityProviderRuntimeMode = components['schemas']['ObservabilityProviderRuntimeMode'];
 export type ObservabilityProviderStatus = components['schemas']['ObservabilityProviderStatus'];
@@ -23776,6 +23823,38 @@ export interface operations {
             410: components["responses"]["Error"];
         };
     };
+    exchangeDockerHostAgentEnrollment: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                operationID: components["parameters"]["OperationID"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["DockerHostAgentEnrollmentRequest"];
+            };
+        };
+        responses: {
+            /** @description One-time host-bound Agent and control-plane credentials. The enrollment token is atomically consumed by a successful response. */
+            201: {
+                headers: {
+                    /** @description Prevents credential responses from being cached. */
+                    "Cache-Control"?: "no-store";
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DockerHostAgentCredentialsEnvelope"];
+                };
+            };
+            400: components["responses"]["Error"];
+            404: components["responses"]["Error"];
+            409: components["responses"]["Error"];
+            410: components["responses"]["Error"];
+        };
+    };
     planDockerHostQuickCreate: {
         parameters: {
             query?: never;

package/openapi/soha-api.json

@@ -10063,6 +10063,85 @@
         ],
         "type": "object"
       },
+      "DockerHostAgentCredentials": {
+        "additionalProperties": false,
+        "properties": {
+          "agentBearerToken": {
+            "description": "Credential for the Agent's local HTTP API, returned only by the successful enrollment response.",
+            "format": "password",
+            "maxLength": 512,
+            "minLength": 32,
+            "type": "string"
+          },
+          "agentId": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          },
+          "hostId": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "issuedAt": {
+            "format": "date-time",
+            "type": "string"
+          },
+          "operationId": {
+            "minLength": 1,
+            "type": "string"
+          },
+          "runtimeBearerToken": {
+            "description": "Revocable credential restricted to Docker operations for this host.",
+            "format": "password",
+            "maxLength": 512,
+            "minLength": 32,
+            "type": "string"
+          }
+        },
+        "required": [
+          "hostId",
+          "operationId",
+          "agentId",
+          "agentBearerToken",
+          "runtimeBearerToken",
+          "issuedAt"
+        ],
+        "type": "object"
+      },
+      "DockerHostAgentCredentialsEnvelope": {
+        "additionalProperties": false,
+        "properties": {
+          "data": {
+            "$ref": "#/components/schemas/DockerHostAgentCredentials"
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "type": "object"
+      },
+      "DockerHostAgentEnrollmentRequest": {
+        "additionalProperties": false,
+        "properties": {
+          "agentId": {
+            "maxLength": 200,
+            "minLength": 1,
+            "type": "string"
+          },
+          "enrollmentToken": {
+            "description": "Short-lived one-time secret delivered only inside the installer.",
+            "format": "password",
+            "maxLength": 512,
+            "minLength": 32,
+            "type": "string"
+          }
+        },
+        "required": [
+          "agentId",
+          "enrollmentToken"
+        ],
+        "type": "object"
+      },
       "DockerHostAgentInstallation": {
         "additionalProperties": false,
         "properties": {
@@ -41073,7 +41152,7 @@
         "type": "http"
       },
       "runtimeBearerAuth": {
-        "description": "Runtime execution runner token.",
+        "description": "Runtime execution runner token, including host-bound Docker Agent credentials.",
         "scheme": "bearer",
         "type": "http"
       },
@@ -41088,7 +41167,7 @@
   "info": {
     "description": "Public OpenSoha core API contract. This first contract focuses on stable cross-repository boundaries: auth, health, runner-facing control-plane callbacks, AI Gateway, and MCP capability discovery.\n",
     "title": "Soha API",
-    "version": "0.1.11"
+    "version": "0.1.12"
   },
   "openapi": "3.1.0",
   "paths": {
@@ -57072,6 +57151,63 @@
         "x-soha-implementation-status": "implemented"
       }
     },
+    "/docker/agent-installations/{operationID}/enroll": {
+      "post": {
+        "operationId": "exchangeDockerHostAgentEnrollment",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/OperationID"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/DockerHostAgentEnrollmentRequest"
+              }
+            }
+          },
+          "required": true
+        },
+        "responses": {
+          "201": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/DockerHostAgentCredentialsEnvelope"
+                }
+              }
+            },
+            "description": "One-time host-bound Agent and control-plane credentials. The enrollment token is atomically consumed by a successful response.",
+            "headers": {
+              "Cache-Control": {
+                "description": "Prevents credential responses from being cached.",
+                "schema": {
+                  "const": "no-store",
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/Error"
+          },
+          "404": {
+            "$ref": "#/components/responses/Error"
+          },
+          "409": {
+            "$ref": "#/components/responses/Error"
+          },
+          "410": {
+            "$ref": "#/components/responses/Error"
+          }
+        },
+        "security": [],
+        "tags": [
+          "Runner"
+        ]
+      }
+    },
     "/docker/containers/start": {
       "post": {
         "operationId": "startDockerContainer",

package/openapi/soha-api.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Soha API
-  version: 0.1.11
+  version: 0.1.12
   description: >
     Public OpenSoha core API contract. This first contract focuses on stable
     cross-repository boundaries: auth, health, runner-facing control-plane
@@ -3295,6 +3295,38 @@ paths:
           $ref: "#/components/responses/Error"
         "410":
           $ref: "#/components/responses/Error"
+  /docker/agent-installations/{operationID}/enroll:
+    post:
+      tags: [Runner]
+      operationId: exchangeDockerHostAgentEnrollment
+      security: []
+      parameters:
+        - $ref: "#/components/parameters/OperationID"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DockerHostAgentEnrollmentRequest"
+      responses:
+        "201":
+          description: One-time host-bound Agent and control-plane credentials. The enrollment token is atomically consumed by a successful response.
+          headers:
+            Cache-Control:
+              description: Prevents credential responses from being cached.
+              schema: { type: string, const: no-store }
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DockerHostAgentCredentialsEnvelope"
+        "400":
+          $ref: "#/components/responses/Error"
+        "404":
+          $ref: "#/components/responses/Error"
+        "409":
+          $ref: "#/components/responses/Error"
+        "410":
+          $ref: "#/components/responses/Error"
   /docker/hosts/quick-create/plan:
     post:
       tags: [Docker]
@@ -11944,7 +11976,7 @@ components:
     runtimeBearerAuth:
       type: http
       scheme: bearer
-      description: Runtime execution runner token.
+      description: Runtime execution runner token, including host-bound Docker Agent credentials.
     agentBearerAuth:
       type: http
       scheme: bearer
@@ -25915,6 +25947,58 @@ components:
         data:
           $ref: "#/components/schemas/DockerHostAgentInstallation"
       additionalProperties: false
+    DockerHostAgentEnrollmentRequest:
+      type: object
+      required: [agentId, enrollmentToken]
+      properties:
+        agentId:
+          type: string
+          minLength: 1
+          maxLength: 200
+        enrollmentToken:
+          type: string
+          minLength: 32
+          maxLength: 512
+          format: password
+          description: Short-lived one-time secret delivered only inside the installer.
+      additionalProperties: false
+    DockerHostAgentCredentials:
+      type: object
+      required: [hostId, operationId, agentId, agentBearerToken, runtimeBearerToken, issuedAt]
+      properties:
+        hostId:
+          type: string
+          minLength: 1
+        operationId:
+          type: string
+          minLength: 1
+        agentId:
+          type: string
+          minLength: 1
+          maxLength: 200
+        agentBearerToken:
+          type: string
+          minLength: 32
+          maxLength: 512
+          format: password
+          description: Credential for the Agent's local HTTP API, returned only by the successful enrollment response.
+        runtimeBearerToken:
+          type: string
+          minLength: 32
+          maxLength: 512
+          format: password
+          description: Revocable credential restricted to Docker operations for this host.
+        issuedAt:
+          type: string
+          format: date-time
+      additionalProperties: false
+    DockerHostAgentCredentialsEnvelope:
+      type: object
+      required: [data]
+      properties:
+        data:
+          $ref: "#/components/schemas/DockerHostAgentCredentials"
+      additionalProperties: false
     ObservabilityProviderSignal:
       type: string
       enum: [logs, metrics, traces, profiles]

package/openapi/spec_generated.go

@@ -5,9 +5,9 @@ package openapi
 import _ "embed"
 
 const (
-	Version    = "0.1.11"
-	YAMLSHA256 = "84fc6e95a10bbbf20bc8b2adbda86d824bf664d1ca16c879c37cf1005ed47557"
-	JSONSHA256 = "551abf1b2ab9a56f0b59de7d43d1d59c0145d88cf8a017e1c0a937441947fdff"
+	Version    = "0.1.12"
+	YAMLSHA256 = "b9dbd5597000f9124790f0df8e9e7616e76f7d7e12df03b72490c3403da4eda5"
+	JSONSHA256 = "6f34774013b3e6c9dd0e2c9b3e9d929a68f8f8b659a5909dad64a77821ef24dd"
 )
 
 //go:embed soha-api.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensoha/contracts",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "private": false,
   "description": "Shared OpenSoha API, agent, MCP, skill, event, and auth contracts.",
   "license": "Apache-2.0",