feat: version the private IAM protocol between gateway and standalone service

The S3 gateway and the standalone IAM service exchange authorization decisions over the private endpoints, where a version skew is silently unsafe in both directions: an older service drops a request field it does not know (a `Condition` block, say) and evaluates fail-open, while an older gateway ignores a response field it does not know and misses a deny the service intended. Neither side could previously detect either case. Both peers now declare a protocol version on every exchange via the `X-Vgw-Private-Protocol` header — the gateway on each request, the service on each response, error responses included — and each refuses a peer it cannot serve safely. The service rejects a gateway below `MinClientProtocol` with a `ProtocolMismatch` code; the gateway rejects a service older than the `ProtocolVersion` it speaks, and rejects a response carrying no version at all, since no build of this protocol omits the header and something else answering on that address should not be interpreted as an IAM decision. `ParseProtocolVersion` is shared by both sides and deliberately strict: an unreadable value is a mismatch, never an assumed default. A new root-signed `/private/version` endpoint reports the protocol version, the minimum client the service will serve, and the build tag (`WithPrivateServerVersion`). It is exempt from the service's own client-version check so it can still answer a gateway the service refuses — which is how that gateway learns why. Being authenticated like every other private endpoint, it also lets the gateway's startup probe verify its own credential and its mTLS transport in the same round trip. The gateway probes it once in `NewIAMServiceStandalone` rather than discovering a skew as an opaque per-request 500. An incompatible service is fatal after a 30s window, since a gateway that cannot authorize a single request is more useful refusing to start with the reason in its log; an unreachable one is only a warning, because the two processes legitimately start in parallel and every request checks the version regardless. Only conditions that can resolve on their own are retried — a rejected credential is reported immediately.
2026-09-24 00:44:23 +00:00 · 2026-08-25 01:41:12 +04:00
parent 2147a0c304
commit a4d4519ffe
15 changed files with 850 additions and 38 deletions
@@ -220,6 +220,7 @@ func New(o *Opts) (IAMService, error) {

 	switch {
 	case o.StandaloneIAMEndpoint != "":
+		fmt.Printf("initializing standalone IAM with %q\n", o.StandaloneIAMEndpoint)
 		svc, err = NewIAMServiceStandalone(o.RootAccount, IAMServiceStandaloneConfig{
 			Endpoint:         o.StandaloneIAMEndpoint,
 			Access:           o.StandaloneIAMAccess,
@@ -231,7 +232,6 @@ func New(o *Opts) (IAMService, error) {
 			DefaultGroupID:   o.StandaloneDefaultGroupID,
 			DefaultProjectID: o.StandaloneDefaultProjectID,
 		})
-		fmt.Printf("initializing standalone IAM with %q\n", o.StandaloneIAMEndpoint)
 		if err != nil {
 			return nil, err
 		}
@@ -18,10 +18,14 @@ import (
 	"context"
 	"crypto/tls"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"io"
+	"log"
 	"net"
 	"net/http"
+	"net/url"
+	"strconv"
 	"time"

 	"github.com/versity/versitygw/iamapi/private"
@@ -39,6 +43,34 @@ const (
 	standaloneRequestTimeout = 10 * time.Second
 )

+// standaloneProbeWindow bounds how long NewIAMServiceStandalone waits for the
+// IAM service to answer compatibly before it gives up, and
+// standaloneProbeInterval how often it retries within that window. Both
+// failures are retried, for different reasons: an unreachable service is the
+// ordinary case of the two processes starting in parallel, and an
+// incompatible one is what a gateway sees while the IAM service it is paired
+// with is still rolling. Failing immediately on either would turn a routine
+// deployment into a crash loop whose backoff long outlives the condition.
+//
+// Variables rather than constants so tests can shorten the window; nothing
+// else writes them.
+var (
+	standaloneProbeWindow   = 30 * time.Second
+	standaloneProbeInterval = 2 * time.Second
+)
+
+// protocolMismatchError reports that whatever answered the private endpoints
+// is not a standalone IAM service this gateway can use. It is a distinct type
+// so the startup probe can tell an incompatible peer, which is fatal, from an
+// unreachable one, which is not.
+type protocolMismatchError struct {
+	detail string
+}
+
+func (e *protocolMismatchError) Error() string {
+	return "iam standalone: " + e.detail
+}
+
 // IAMServiceStandaloneConfig configures IAMServiceStandalone.
 type IAMServiceStandaloneConfig struct {
 	// Endpoint is either a "host:port" TCP address (mTLS required -
@@ -46,8 +78,8 @@ type IAMServiceStandaloneConfig struct {
 	// the standalone IAM service's own --private-ports address shape.
 	Endpoint string
 	// Access/Secret are this client's own SigV4 identity — the credential
-	// it signs its private requests with. Defaults both to the
-	// gateway's root account when unset.
+	// it signs its private requests with. Both must be set together, or
+	// both left empty to sign with the gateway's root account.
 	Access string
 	Secret string
 	// ClientCert/ClientCertKey/ServerCA configure outbound mTLS. Required
@@ -96,13 +128,13 @@ func NewIAMServiceStandalone(rootAcc Account, cfg IAMServiceStandaloneConfig) (*
 		return nil, fmt.Errorf("iam standalone: endpoint is required")
 	}

-	access := cfg.Access
-	if access == "" {
-		access = rootAcc.Access
+	if (cfg.Access == "") != (cfg.Secret == "") {
+		return nil, fmt.Errorf("iam standalone: access and secret must both be set, or both left empty to sign with the root account")
 	}
-	secret := cfg.Secret
-	if secret == "" {
-		secret = rootAcc.Secret
+
+	access, secret := cfg.Access, cfg.Secret
+	if access == "" {
+		access, secret = rootAcc.Access, rootAcc.Secret
 	}

 	client, baseURL, err := newStandaloneHTTPClient(cfg)
@@ -110,14 +142,93 @@ func NewIAMServiceStandalone(rootAcc Account, cfg IAMServiceStandaloneConfig) (*
 		return nil, err
 	}

-	return &IAMServiceStandalone{
+	svc := &IAMServiceStandalone{
 		client:  client,
 		baseURL: baseURL,
 		access:  access,
 		secret:  secret,
 		rootAcc: rootAcc,
 		cfg:     cfg,
-	}, nil
+	}
+
+	if err := svc.probeProtocol(); err != nil {
+		return nil, err
+	}
+
+	return svc, nil
+}
+
+// probeProtocol verifies at startup what every request verifies anyway, so a
+// version skew is diagnosed once, here, instead of once per S3 request as an
+// opaque 500. Because it is a signed request to a root-authenticated
+// endpoint, reaching a compatible answer also proves the transport, the mTLS
+// material, and this gateway's own IAM credential.
+//
+// An incompatible service is fatal: a gateway that cannot authorize a single
+// request is more useful refusing to start, with the reason in its log, than
+// running and serving errors. An unreachable one is only a warning — the two
+// processes legitimately start in parallel, and every request checks the
+// version regardless.
+func (s *IAMServiceStandalone) probeProtocol() error {
+	deadline := time.Now().Add(standaloneProbeWindow)
+
+	for {
+		var resp private.VersionResponse
+		// The endpoint takes no arguments; an empty object is the request.
+		err := s.doPrivateRequest(private.VersionPath, struct{}{}, &resp)
+
+		// The version endpoint answers even a gateway the service will not
+		// serve — that is the whole point of exempting it from the service's
+		// own check — so the probe has to draw that conclusion itself from
+		// the minimum the service reports. Without this the one direction a
+		// gateway cannot detect from a response header would pass startup and
+		// fail on every request afterwards.
+		if err == nil && private.ProtocolVersion < resp.MinClient {
+			err = &protocolMismatchError{fmt.Sprintf(
+				"IAM service at %q serves private protocol %d and newer, this gateway speaks %d: upgrade the gateway",
+				s.cfg.Endpoint, resp.MinClient, private.ProtocolVersion)}
+		}
+
+		if err == nil {
+			serverVersion := resp.ServerVersion
+			if serverVersion == "" {
+				serverVersion = "unknown"
+			}
+			fmt.Printf("standalone IAM service %q: version %s, private protocol %d\n",
+				s.cfg.Endpoint, serverVersion, resp.Protocol)
+			return nil
+		}
+
+		if probeRetryable(err) && time.Now().Before(deadline) {
+			time.Sleep(standaloneProbeInterval)
+			continue
+		}
+
+		var mismatch *protocolMismatchError
+		if errors.As(err, &mismatch) {
+			return fmt.Errorf("%w (still incompatible after %v, so this is a version skew rather than a rollout in progress)",
+				err, standaloneProbeWindow)
+		}
+
+		log.Printf("WARNING: iam standalone: could not verify the IAM service at %q: %v; "+
+			"the private protocol version is still checked on every request",
+			s.cfg.Endpoint, err)
+		return nil
+	}
+}
+
+// probeRetryable reports whether a failed probe could resolve on its own.
+// Only two can: the service not being up yet, and it being mid-rollout at an
+// incompatible version. Anything it answered definitively — a rejected
+// gateway credential above all — will answer the same way in thirty seconds,
+// so retrying only delays the warning that says so.
+func probeRetryable(err error) bool {
+	var mismatch *protocolMismatchError
+	if errors.As(err, &mismatch) {
+		return true
+	}
+	var transport *url.Error
+	return errors.As(err, &transport)
 }

 func newStandaloneHTTPClient(cfg IAMServiceStandaloneConfig) (*http.Client, string, error) {
@@ -180,6 +291,11 @@ func (s *IAMServiceStandalone) doPrivateRequest(path string, reqBody, respBody a
 		return fmt.Errorf("iam standalone: build request: %w", err)
 	}
 	req.Header.Set("Content-Type", "application/json")
+	// Set before signing, so it is covered by the signature: SigningInput
+	// FromRequest leaves SignedHeaders nil, and sigv4auth's default policy
+	// excludes only Authorization, User-Agent, X-Amzn-Trace-Id, Expect and
+	// Transfer-Encoding.
+	req.Header.Set(private.ProtocolHeader, strconv.Itoa(private.ProtocolVersion))

 	payloadHash := sigv4auth.PayloadSHA256Hex(bodyBytes)
 	req.Header.Set("X-Amz-Content-Sha256", payloadHash)
@@ -203,6 +319,12 @@ func (s *IAMServiceStandalone) doPrivateRequest(path string, reqBody, respBody a
 	}
 	defer resp.Body.Close()

+	// Checked before the status and before the body: a peer whose protocol
+	// this gateway cannot read is not one whose response it should interpret.
+	if err := s.checkServerProtocol(path, resp); err != nil {
+		return err
+	}
+
 	respBytes, err := io.ReadAll(resp.Body)
 	if err != nil {
 		return fmt.Errorf("iam standalone: read response from %s: %w", path, err)
@@ -240,11 +362,47 @@ func standaloneResponseError(path string, status int, body []byte) error {
 		return ErrNoSuchUser
 	case private.CodeInvalidToken:
 		return ErrInvalidSessionToken
+	case private.CodeProtocolMismatch:
+		// The other direction of the same check: this gateway is too old for
+		// the IAM service to serve safely, which only that service can know.
+		return &protocolMismatchError{fmt.Sprintf(
+			"IAM service refused this gateway's private protocol version %d at %s: %s",
+			private.ProtocolVersion, path, errBody.Error)}
 	}

 	return fmt.Errorf("iam standalone: %s returned %d: %s", path, status, string(body))
 }

+// checkServerProtocol verifies the private protocol version the IAM service
+// declared on a response.
+//
+// A missing version fails just as hard as an incompatible one. No build of
+// this protocol omits the header, so a response without one did not come from
+// a compatible IAM service — it came from something else answering on that
+// address, such as a proxy returning its own error page. The message says
+// what was observed rather than naming a cause, since both look identical from here.
+func (s *IAMServiceStandalone) checkServerProtocol(path string, resp *http.Response) error {
+	value := resp.Header.Get(private.ProtocolHeader)
+	if value == "" {
+		return &protocolMismatchError{fmt.Sprintf(
+			"no %s header on the %d response from %s at %q: not a versioned IAM service",
+			private.ProtocolHeader, resp.StatusCode, path, s.cfg.Endpoint)}
+	}
+
+	server, err := private.ParseProtocolVersion(value)
+	if err != nil {
+		return &protocolMismatchError{fmt.Sprintf("response from %s at %q: %v", path, s.cfg.Endpoint, err)}
+	}
+
+	if server < private.ProtocolVersion {
+		return &protocolMismatchError{fmt.Sprintf(
+			"IAM service at %q speaks private protocol %d, this gateway requires %d or newer: upgrade the IAM service before the gateway",
+			s.cfg.Endpoint, server, private.ProtocolVersion)}
+	}
+
+	return nil
+}
+
 // DeriveSigningKey implements SigningKeyProvider. Root is special-cased
 // locally: its secret is already known to this process either way, so
 // there's no reason to round-trip it through the IAM service.
@@ -16,9 +16,12 @@ package auth
 import (
 	"context"
 	"errors"
+	"fmt"
 	"net"
+	"net/http"
 	"os"
 	"path/filepath"
+	"strconv"
 	"testing"
 	"time"

@@ -354,3 +357,265 @@ func TestNewIAMServiceStandaloneRespectsExplicitCredentials(t *testing.T) {
 		t.Errorf("secret = %q, want %q", client.secret, "CUSTOMSECRET")
 	}
 }
+
+// TestNewIAMServiceStandalonePartialCredentialsRejected covers a half
+// configured signing identity: pairing one supplied key with the other half
+// of the root credential would silently sign with a mismatched identity, so
+// it must fail at construction instead.
+func TestNewIAMServiceStandalonePartialCredentialsRejected(t *testing.T) {
+	rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+	_, sock := standaloneTestServer(t)
+
+	for _, tc := range []struct {
+		name   string
+		access string
+		secret string
+	}{
+		{name: "access only", access: "AKIDCUSTOM"},
+		{name: "secret only", secret: "CUSTOMSECRET"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			_, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{
+				Endpoint: sock,
+				Access:   tc.access,
+				Secret:   tc.secret,
+			})
+			if err == nil {
+				t.Fatal("expected an error when only one of access/secret is configured")
+			}
+		})
+	}
+}
+
+// TestIAMServiceStandaloneRejectsIncompatibleService covers every response a
+// peer can give that this gateway must not interpret: no protocol header at
+// all (a pre-versioning build, or something else answering on the address),
+// one it cannot read, and one older than the protocol this gateway speaks.
+// None of them may yield a working client.
+func TestIAMServiceStandaloneRejectsIncompatibleService(t *testing.T) {
+	shortenProbeWindow(t)
+
+	for _, tc := range []struct {
+		name     string
+		protocol string
+	}{
+		{"no header", ""},
+		{"unreadable", "one"},
+		{"older service", strconv.Itoa(private.ProtocolVersion - 1)},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			sock := serveFakePrivate(t, tc.protocol, http.StatusOK, `{"protocol":0}`)
+
+			rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+			_, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{Endpoint: sock})
+			if err == nil {
+				t.Fatal("expected the gateway to refuse to start against an incompatible IAM service")
+			}
+			var mismatch *protocolMismatchError
+			if !errors.As(err, &mismatch) {
+				t.Fatalf("error = %v, want a protocolMismatchError", err)
+			}
+		})
+	}
+}
+
+// TestIAMServiceStandaloneAcceptsNewerService confirms the rule is
+// "not older", not "equal": an IAM service upgraded ahead of its gateways is
+// the supported deployment order, so it must keep serving them.
+func TestIAMServiceStandaloneAcceptsNewerService(t *testing.T) {
+	shortenProbeWindow(t)
+
+	newer := strconv.Itoa(private.ProtocolVersion + 1)
+	sock := serveFakePrivate(t, newer, http.StatusOK,
+		`{"protocol":`+newer+`,"minClient":1,"serverVersion":"v9.9.9"}`)
+
+	rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+	client, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{Endpoint: sock})
+	if err != nil {
+		t.Fatalf("NewIAMServiceStandalone against a newer IAM service: %v", err)
+	}
+	defer client.Shutdown()
+}
+
+// TestIAMServiceStandaloneRefusedByNewerService is the other direction of the
+// same check: an IAM service that has raised its minimum turns this gateway
+// away, and the gateway must recognise that as a version problem rather than
+// as a generic server error.
+func TestIAMServiceStandaloneRefusedByNewerService(t *testing.T) {
+	shortenProbeWindow(t)
+
+	sock := serveFakePrivate(t, strconv.Itoa(private.ProtocolVersion+1), http.StatusBadRequest,
+		`{"error":"gateway speaks private protocol 1, this IAM service requires 2 or newer","code":"`+private.CodeProtocolMismatch+`"}`)
+
+	rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+	_, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{Endpoint: sock})
+	if err == nil {
+		t.Fatal("expected the gateway to refuse to start when the IAM service refuses it")
+	}
+	var mismatch *protocolMismatchError
+	if !errors.As(err, &mismatch) {
+		t.Fatalf("error = %v, want a protocolMismatchError", err)
+	}
+}
+
+// TestIAMServiceStandaloneRefusedByServiceMinimum covers the one direction a
+// response header cannot express. The version endpoint is exempt from the
+// service's own client-version check, so it answers 200 even to a gateway the
+// service will not serve; the gateway has to reach that conclusion from the
+// minimum the endpoint reports, or it would start cleanly and then fail every
+// real request.
+func TestIAMServiceStandaloneRefusedByServiceMinimum(t *testing.T) {
+	shortenProbeWindow(t)
+
+	current := strconv.Itoa(private.ProtocolVersion)
+	sock := serveFakePrivate(t, current, http.StatusOK,
+		`{"protocol":`+current+`,"minClient":`+strconv.Itoa(private.ProtocolVersion+1)+`}`)
+
+	rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+	_, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{Endpoint: sock})
+	if err == nil {
+		t.Fatal("expected the gateway to refuse to start below the IAM service's minimum")
+	}
+	var mismatch *protocolMismatchError
+	if !errors.As(err, &mismatch) {
+		t.Fatalf("error = %v, want a protocolMismatchError", err)
+	}
+}
+
+// TestIAMServiceStandaloneUnreachableIsNotFatal confirms an unreachable IAM
+// service only warns. The two processes legitimately start in parallel, and
+// every request checks the version anyway, so refusing to start here would
+// invent an ordering dependency without buying any safety.
+func TestIAMServiceStandaloneUnreachableIsNotFatal(t *testing.T) {
+	shortenProbeWindow(t)
+
+	sockDir, err := os.MkdirTemp("", "vgw-priv")
+	if err != nil {
+		t.Fatalf("MkdirTemp: %v", err)
+	}
+	t.Cleanup(func() { os.RemoveAll(sockDir) })
+
+	rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+	client, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{
+		Endpoint: filepath.Join(sockDir, "nothing-here.sock"),
+	})
+	if err != nil {
+		t.Fatalf("an unreachable IAM service must not be fatal, got: %v", err)
+	}
+	defer client.Shutdown()
+}
+
+// TestIAMServiceStandaloneDoesNotRetryDefinitiveRejection confirms the probe's
+// retry window applies only to failures that can resolve on their own. A
+// rejected gateway credential is answered by a service that is up and
+// compatible, so it must warn at once rather than hold startup for the full
+// window. Deliberately run against the real, unshortened window.
+func TestIAMServiceStandaloneDoesNotRetryDefinitiveRejection(t *testing.T) {
+	sock := serveFakePrivate(t, strconv.Itoa(private.ProtocolVersion), http.StatusForbidden,
+		`{"error":"The security token included in the request is invalid","code":"InvalidClientTokenId"}`)
+
+	rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+
+	start := time.Now()
+	client, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{Endpoint: sock})
+	if err != nil {
+		t.Fatalf("a rejected credential must warn, not fail startup: %v", err)
+	}
+	defer client.Shutdown()
+
+	if elapsed := time.Since(start); elapsed > standaloneProbeInterval {
+		t.Errorf("probe took %v; a definitive rejection must not be retried", elapsed)
+	}
+}
+
+// TestIAMServiceStandaloneSendsProtocolHeader confirms the gateway advertises
+// its own version, and that it does so inside the signature: the real server
+// verifies the signature over that header, so an unsigned or absent one would
+// fail before reaching a handler.
+func TestIAMServiceStandaloneSendsProtocolHeader(t *testing.T) {
+	store, sock := standaloneTestServer(t)
+	createStandaloneTestUser(t, store, "alice", "AKIAALICE", "alicesecret", "")
+
+	rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+	client, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{Endpoint: sock})
+	if err != nil {
+		t.Fatalf("NewIAMServiceStandalone: %v", err)
+	}
+	defer client.Shutdown()
+
+	if _, err := client.GetUserAccount("AKIAALICE"); err != nil {
+		t.Fatalf("GetUserAccount: %v", err)
+	}
+}
+
+// TestIAMServiceStandaloneShapeChecksSurviveMatchingProtocol confirms the
+// version header did not replace the response-shape checks. A peer can declare
+// a compatible version and still send a matrix that disagrees — a forgotten
+// bump, a locally patched build — and that must still fail closed.
+func TestIAMServiceStandaloneShapeChecksSurviveMatchingProtocol(t *testing.T) {
+	shortenProbeWindow(t)
+
+	// Compatible on the wire version, but one action decision short of the two
+	// actions asked for below.
+	current := strconv.Itoa(private.ProtocolVersion)
+	sock := serveFakePrivate(t, current, http.StatusOK,
+		`{"protocol":`+current+`,"decisions":[["allow"]]}`)
+
+	rootAcc := Account{Access: standaloneTestRootAccess, Secret: standaloneTestRootSecret}
+	client, err := NewIAMServiceStandalone(rootAcc, IAMServiceStandaloneConfig{Endpoint: sock})
+	if err != nil {
+		t.Fatalf("NewIAMServiceStandalone: %v", err)
+	}
+	defer client.Shutdown()
+
+	_, err = client.EvaluatePolicy("AKIAALICE", "", []Action{GetObjectAction, PutObjectAction}, []string{"arn:aws:s3:::b/o"}, nil)
+	if err == nil {
+		t.Fatal("expected a short decision row to fail closed even at a matching protocol version")
+	}
+}
+
+// shortenProbeWindow collapses the startup probe's retry window for tests that
+// deliberately point the client at an incompatible or absent service, which
+// would otherwise sit through the full production window.
+func shortenProbeWindow(t *testing.T) {
+	t.Helper()
+
+	window, interval := standaloneProbeWindow, standaloneProbeInterval
+	standaloneProbeWindow, standaloneProbeInterval = 0, time.Millisecond
+	t.Cleanup(func() { standaloneProbeWindow, standaloneProbeInterval = window, interval })
+}
+
+// serveFakePrivate serves a stand-in for the standalone IAM service on a unix
+// socket, answering every request with the given protocol header (omitted when
+// empty), status, and body. It exists because the cases worth testing — a
+// build older or newer than this one, or one predating versioning altogether —
+// cannot be produced by the real server, which only ever speaks its own
+// version.
+func serveFakePrivate(t *testing.T, protocol string, status int, body string) string {
+	t.Helper()
+
+	sockDir, err := os.MkdirTemp("", "vgw-priv")
+	if err != nil {
+		t.Fatalf("MkdirTemp: %v", err)
+	}
+	t.Cleanup(func() { os.RemoveAll(sockDir) })
+	sockPath := filepath.Join(sockDir, "p.sock")
+
+	ln, err := net.Listen("unix", sockPath)
+	if err != nil {
+		t.Fatalf("listen: %v", err)
+	}
+
+	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		if protocol != "" {
+			w.Header().Set(private.ProtocolHeader, protocol)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.WriteHeader(status)
+		fmt.Fprint(w, body)
+	})}
+	go srv.Serve(ln)
+	t.Cleanup(func() { srv.Close() })
+
+	return sockPath
+}