Declare required native installation credentials

Author: SaladDay

contracts/agents-api/runtime.openapi.yaml

@@ -4,6 +4,8 @@ definitions:
     properties:
       executor_token:
         type: string
+    required:
+      - executor_token
     type: object
   deployment.Enrollment:
     properties:
@@ -483,6 +485,12 @@ paths:
   /api/v1/agent-daemon/installation:
     post:
       description: Accepts a short-lived Environment installation Bearer authorization, not a Project or Core key. Returns frozen connection constraints; it does not claim or rotate credentials.
+      parameters:
+        - description: Bearer installation grant
+          in: header
+          name: Authorization
+          required: true
+          type: string
       produces:
         - application/json
       responses:
@@ -511,6 +519,11 @@ paths:
         - application/json
       description: A valid installation Bearer authorization can claim one connect-only key. The client persists its generated secret before submitting it. Retries must present that same secret; a different, rotated or revoked credential is never replaced.
       parameters:
+        - description: Bearer installation grant
+          in: header
+          name: Authorization
+          required: true
+          type: string
         - description: Locally persisted executor secret
           in: body
           name: body

services/core/internal/api/contract_routes_test.go

@@ -129,3 +129,39 @@ func TestContractsPublishExactlyTheRegisteredCoreAndMachineRoutes(t *testing.T)
 		}
 	}
 }
+
+func TestInstallationContractRequiresGrantAndExecutorToken(t *testing.T) {
+	raw, err := os.ReadFile("../../../../contracts/agents-api/runtime.openapi.yaml")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var contract struct {
+		Paths map[string]map[string]struct {
+			Parameters []struct {
+				Name     string `yaml:"name"`
+				In       string `yaml:"in"`
+				Required bool   `yaml:"required"`
+			}
+		} `yaml:"paths"`
+		Definitions map[string]struct {
+			Required []string `yaml:"required"`
+		} `yaml:"definitions"`
+	}
+	if err := yaml.Unmarshal(raw, &contract); err != nil {
+		t.Fatal(err)
+	}
+	for _, path := range []string{"/api/v1/agent-daemon/installation", "/api/v1/agent-daemon/installation/claim"} {
+		present := false
+		for _, parameter := range contract.Paths[path]["post"].Parameters {
+			if parameter.In == "header" && parameter.Name == "Authorization" && parameter.Required {
+				present = true
+			}
+		}
+		if !present {
+			t.Errorf("%s does not require its installation grant", path)
+		}
+	}
+	if !slices.Contains(contract.Definitions["api.NativeInstallationClaim"].Required, "executor_token") {
+		t.Fatal("claim schema does not require the executor secret")
+	}
+}

services/core/internal/api/environment_installation.go

@@ -84,6 +84,7 @@ func (h *Handler) installationAuthorization(w http.ResponseWriter, r *http.Reque
 // @Description Accepts a short-lived Environment installation Bearer authorization, not a Project or Core key. Returns frozen connection constraints; it does not claim or rotate credentials.
 // @Tags Native Installation
 // @Produce json
+// @Param Authorization header string true "Bearer installation grant"
 // @Success 200 {object} v1.NativeInstallationContext
 // @Failure 401,404,503 {object} v1.ErrorResponse
 // @Router /api/v1/agent-daemon/installation [post]
@@ -111,13 +112,14 @@ func (h *Handler) prepareNativeInstallation(w http.ResponseWriter, r *http.Reque
 }
 
 type NativeInstallationClaim struct {
-	ExecutorToken string `json:"executor_token"`
+	ExecutorToken string `json:"executor_token" binding:"required"`
 }
 
 // @Summary Claim an Environment's installation credential
 // @Description A valid installation Bearer authorization can claim one connect-only key. The client persists its generated secret before submitting it. Retries must present that same secret; a different, rotated or revoked credential is never replaced.
 // @Tags Native Installation
 // @Accept json
+// @Param Authorization header string true "Bearer installation grant"
 // @Param body body api.NativeInstallationClaim true "Locally persisted executor secret"
 // @Success 204
 // @Failure 400,401,409,503 {object} v1.ErrorResponse

services/core/tests/integration/environment_installation_test.go

@@ -4,11 +4,15 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"errors"
+	"net/http"
+	"net/http/httptest"
 	"strings"
 	"sync"
 	"testing"
 	"time"
 
+	"github.com/MiniMax-AI/OpenAgentCore/services/core/internal/api"
+	"github.com/MiniMax-AI/OpenAgentCore/services/core/internal/nativeinstaller"
 	"github.com/MiniMax-AI/OpenAgentCore/services/core/internal/sessions"
 	"github.com/google/uuid"
 )
@@ -32,6 +36,28 @@ func TestEnvironmentInstallationClaimLifetimeAndRetries(t *testing.T) {
 	if err != nil || expires <= time.Now().Unix() || expires > time.Now().Add(31*time.Minute).Unix() {
 		t.Fatal("authorization", err)
 	}
+	handler, err := publicHandler(t, s, fixtureKeyResolver{}, "codex", func(d *api.Dependencies) {
+		d.Execution.NativeInstaller = &api.NativeInstaller{Version: "build", Base: "https://core.example/api/v1/agent-daemon/install/", Catalog: &nativeinstaller.Catalog{Version: "build"}}
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	claimHTTP := func(path, grant, body string, status int) {
+		t.Helper()
+		request := httptest.NewRequest(http.MethodPost, "/api/v1/agent-daemon/"+path, strings.NewReader(body))
+		if grant != "" {
+			request.Header.Set("Authorization", "Bearer "+grant)
+		}
+		request.Header.Set("Content-Type", "application/json")
+		response := httptest.NewRecorder()
+		handler.ServeHTTP(response, request)
+		if response.Code != status {
+			t.Fatalf("%s returned %d, want %d: %s", path, response.Code, status, response.Body)
+		}
+	}
+	claimHTTP("installation", "", "", http.StatusUnauthorized)
+	claimHTTP("installation/claim", "", "{}", http.StatusUnauthorized)
+	claimHTTP("installation/claim", token, "{}", http.StatusBadRequest)
 	for _, pair := range [][2]string{{token + "x", "build"}, {token, "other-build"}, {"", "build"}} {
 		if _, err := installations.ValidateEnvironmentInstallation(ctx, pair[0], pair[1]); !errors.Is(err, sessions.ErrInstallationAuthorization) {
 			t.Fatal("accepted invalid authorization", err)
@@ -78,6 +104,11 @@ func TestEnvironmentInstallationClaimLifetimeAndRetries(t *testing.T) {
 	if err := installations.ClaimEnvironmentInstallation(ctx, token, "build", secrets[winner]); err != nil {
 		t.Fatal("lost-response retry", err)
 	}
+	claimBody, err := json.Marshal(api.NativeInstallationClaim{ExecutorToken: secrets[winner]})
+	if err != nil {
+		t.Fatal(err)
+	}
+	claimHTTP("installation/claim", token, string(claimBody), http.StatusNoContent)
 	if _, err := sessionAdapter(s).AuthenticateEnvironmentExecutor(ctx, environment.ID, executorDigest(secrets[winner])); err != nil {
 		t.Fatal(err)
 	}