@automattic/vip 4.1.3 → 4.1.5

package/internal/gql/rechallenge.go

@@ -10,6 +10,7 @@ import (
 
 	json "encoding/json/v2"
 
+	"github.com/Automattic/vip/internal/debuglog"
 	"github.com/Automattic/vip/internal/rechallenge"
 )
 
@@ -20,8 +21,8 @@ type RechallengeConfig struct {
 	TokenCache *rechallenge.TokenCache
 	Runner     *rechallenge.Runner
 	// Context, if non-nil, supplies the context used for Parker calls.
-	// Defaults to context.Background(); production should pass the cobra
-	// command's ctx so SIGINT cancels the flow.
+	// Defaults to the request context, preserving command diagnostics and
+	// cancellation through the flow.
 	Context func() context.Context
 	// Interactive, when non-nil, replaces the default
 	// rechallenge.IsInteractiveContext(nil) fallback for the Runner's
@@ -65,13 +66,13 @@ type rechallengeDoer struct {
 	cfg  RechallengeConfig
 }
 
-func (r *rechallengeDoer) ctx() context.Context {
+func (r *rechallengeDoer) ctx(fallback context.Context) context.Context {
 	if r.cfg.Context != nil {
 		if c := r.cfg.Context(); c != nil {
 			return c
 		}
 	}
-	return context.Background()
+	return fallback
 }
 
 func (r *rechallengeDoer) Do(req *http.Request) (*http.Response, error) {
@@ -98,6 +99,8 @@ func (r *rechallengeDoer) Do(req *http.Request) (*http.Response, error) {
 	if r.cfg.TokenCache != nil {
 		if tok, err := r.cfg.TokenCache.Get(scope); err == nil && tok != nil {
 			attachElevatedHeader(req, *tok)
+		} else if err != nil {
+			debuglog.Printf(req.Context(), "@automattic/vip:rechallenge:link", "preflight error: unable to load elevated token")
 		}
 	}
 
@@ -128,13 +131,14 @@ func (r *rechallengeDoer) Do(req *http.Request) (*http.Response, error) {
 	if r.cfg.Wait != nil {
 		wait = r.cfg.Wait()
 	}
-	tok, runErr := r.cfg.Runner.Run(r.ctx(), rechallenge.RunInput{
+	tok, runErr := r.cfg.Runner.Run(r.ctx(req.Context()), rechallenge.RunInput{
 		RequestedOperation: scope,
 		Extension:          *ext,
 		Interactive:        interactive,
 		Wait:               wait,
 	})
 	if runErr != nil || tok == nil {
+		debuglog.Printf(req.Context(), "@automattic/vip:rechallenge:link", "rechallenge flow failed for %s", scope)
 		r.reportStepUpFailure(scope, runErr)
 		// Surface the ORIGINAL error response upstream.
 		return resp, nil

package/internal/gql/retry.go

@@ -7,6 +7,8 @@ import (
 	"net/http"
 	"syscall"
 	"time"
+
+	"github.com/Automattic/vip/internal/debuglog"
 )
 
 type RetryConfig struct {
@@ -49,7 +51,12 @@ func (r *retryDoer) Do(req *http.Request) (*http.Response, error) {
 		req.Body = io.NopCloser(bytes.NewReader(body))
 		req.ContentLength = int64(len(body))
 	}
-	retryable := isRetryableOperation(body)
+	operation, parseErr := ParseOperationFromBody(body)
+	retryable := parseErr == nil && operation != nil && !operation.IsMutation
+	operationName := ""
+	if operation != nil {
+		operationName = operation.OperationName
+	}
 	var resp *http.Response
 	var lastErr error
 	for attempt := 1; attempt <= r.cfg.MaxAttempts; attempt++ {
@@ -58,7 +65,19 @@ func (r *retryDoer) Do(req *http.Request) (*http.Response, error) {
 			req.ContentLength = int64(len(body))
 		}
 		resp, lastErr = r.next.Do(req)
-		if !shouldRetry(resp, lastErr, retryable, attempt, r.cfg.MaxAttempts) {
+		retry := shouldRetry(resp, lastErr, retryable, attempt, r.cfg.MaxAttempts)
+		if lastErr != nil || (resp != nil && resp.StatusCode >= 400) {
+			status := 0
+			if resp != nil {
+				status = resp.StatusCode
+			}
+			action := "Request failed."
+			if retry {
+				action += " Retrying request."
+			}
+			debuglog.Printf(req.Context(), "@automattic/vip:http:graphql", "%s Operation: %s. Attempt: %d. Status code: %d.", action, operationName, attempt, status)
+		}
+		if !retry {
 			return resp, lastErr
 		}
 		if resp != nil {

package/internal/gql/transport.go

@@ -6,6 +6,8 @@ import (
 	"net/http"
 	"net/url"
 	"strings"
+
+	"github.com/Automattic/vip/internal/debuglog"
 )
 
 type transport struct {
@@ -31,6 +33,13 @@ func (t *transport) Do(req *http.Request) (*http.Response, error) {
 	if req.Header.Get("Content-Type") == "" {
 		req.Header.Set("Content-Type", "application/json")
 	}
+	// Mirror Node's HTTP diagnostic without exposing URL credentials or
+	// arbitrary query parameters (which can contain signed download tokens).
+	safeURL := *req.URL
+	safeURL.User = nil
+	safeURL.RawQuery = ""
+	safeURL.Fragment = ""
+	debuglog.Printf(req.Context(), "@automattic/vip:http", "running fetch %s", safeURL.String())
 	return t.cfg.HTTPClient.Do(req)
 }
 

package/internal/httpproxy/debug_test.go

@@ -0,0 +1,32 @@
+package httpproxy
+
+import (
+	"bytes"
+	"context"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/Automattic/vip/internal/debuglog"
+)
+
+func TestProxyDiagnosticOmitsCredentials(t *testing.T) {
+	clearProxyEnv(t)
+	t.Setenv("VIP_PROXY", "socks5://user:proxy-secret@localhost:1080")
+	var out bytes.Buffer
+	ctx := debuglog.WithLogger(context.Background(), "vip:proxy-dispatcher", &out)
+	req, _ := http.NewRequestWithContext(ctx, "GET", "https://example.test/graphql?token=request-secret", nil)
+	u, err := ProxyURL(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if u == nil || u.User == nil {
+		t.Fatal("proxy authentication lost")
+	}
+	if !strings.Contains(out.String(), "socks5://localhost:1080") {
+		t.Fatalf("missing proxy diagnostic: %q", out.String())
+	}
+	if strings.Contains(out.String(), "secret") || strings.Contains(out.String(), "user") {
+		t.Fatalf("credentials exposed: %q", out.String())
+	}
+}

package/internal/httpproxy/httpproxy.go

@@ -21,6 +21,8 @@ import (
 	"strconv"
 	"strings"
 	"time"
+
+	"github.com/Automattic/vip/internal/debuglog"
 )
 
 // ProxyURL is the port of createProxyAgent (proxy-agent.ts:20-46). It is shaped
@@ -41,10 +43,15 @@ import (
 // Errors are returned rather than swallowed. A proxy the user configured but
 // that we cannot honour must fail the request; silently connecting direct is
 // how the SOCKS half of this bug went unnoticed.
-func ProxyURL(req *http.Request) (*url.URL, error) {
+func ProxyURL(req *http.Request) (selected *url.URL, err error) {
 	if req == nil || req.URL == nil {
 		return nil, nil
 	}
+	defer func() {
+		if selected != nil && err == nil {
+			debuglog.Printf(req.Context(), "vip:proxy-dispatcher", "Enabling fetch dispatcher proxy support using config: %s://%s", selected.Scheme, selected.Host)
+		}
+	}()
 	target := req.URL
 
 	// 1. VIP Socks Proxy takes precedence and is fully backward compatible.

package/internal/installer/version.go

@@ -0,0 +1,41 @@
+// Package installer defines the version contract shared by native packages.
+package installer
+
+import (
+	"fmt"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+var versionPattern = regexp.MustCompile(`^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-(?:(alpha|beta|rc)\.(0|[1-9][0-9]*)|dev\.[0-9A-Za-z]+))?$`)
+
+// NumericVersion preserves release ordering in MSI's three numeric fields.
+// Each patch reserves 1000 values: dev=0, alpha=100..299, beta=300..499,
+// rc=500..699, stable=999. Bounds are checked rather than silently truncating
+// a version, which could otherwise make a newer release look like a downgrade.
+func NumericVersion(version string) (string, error) {
+	m := versionPattern.FindStringSubmatch(version)
+	if m == nil {
+		return "", fmt.Errorf("invalid installer version %q", version)
+	}
+	values := make([]int, 3)
+	for i, max := range []int{255, 255, 64} {
+		n, err := strconv.Atoi(m[i+1])
+		if err != nil || n > max {
+			return "", fmt.Errorf("installer version %q exceeds numeric field %d limit %d", version, i+1, max)
+		}
+		values[i] = n
+	}
+	stage := 999
+	if m[4] != "" {
+		n, err := strconv.Atoi(m[5])
+		if err != nil || n > 199 {
+			return "", fmt.Errorf("installer prerelease number must be between 0 and 199")
+		}
+		stage = map[string]int{"alpha": 100, "beta": 300, "rc": 500}[m[4]] + n
+	} else if strings.Contains(version, "-dev.") {
+		stage = 0
+	}
+	return fmt.Sprintf("%d.%d.%d", values[0], values[1], values[2]*1000+stage), nil
+}

package/internal/installer/version_test.go

@@ -0,0 +1,33 @@
+package installer
+
+import "testing"
+
+func TestNumericVersion(t *testing.T) {
+	for _, tt := range []struct{ input, want string }{
+		{"5.0.0-dev.abc1234", "5.0.0"},
+		{"5.0.0-alpha.0", "5.0.100"},
+		{"5.0.0-alpha.199", "5.0.299"},
+		{"5.0.0-beta.0", "5.0.300"},
+		{"5.0.0-beta.199", "5.0.499"},
+		{"5.0.0-rc.0", "5.0.500"},
+		{"5.0.0-rc.199", "5.0.699"},
+		{"5.0.0", "5.0.999"},
+		{"5.0.1-alpha.0", "5.0.1100"},
+		{"5.12.3-alpha.10", "5.12.3110"},
+		{"255.255.64", "255.255.64999"},
+	} {
+		t.Run(tt.input, func(t *testing.T) {
+			got, err := NumericVersion(tt.input)
+			if err != nil || got != tt.want {
+				t.Fatalf("got %q, %v; want %q", got, err, tt.want)
+			}
+		})
+	}
+	for _, input := range []string{"", "v5.0.0", "5.0", "5.0.0-beta1", "5.0.0-beta.200", "5.0.0-alpha.01", "5.0.0-rc.-1", "256.0.0", "5.256.0", "5.0.65", "05.0.0", "5.0.0-unknown.1", "5.0.0-dev.", "5.0.0+meta", "9999999999999999999999.0.0"} {
+		t.Run(input, func(t *testing.T) {
+			if got, err := NumericVersion(input); err == nil {
+				t.Fatalf("accepted %q as %q", input, got)
+			}
+		})
+	}
+}

package/internal/parity/edge_workers_debug_test.go

@@ -0,0 +1,87 @@
+//go:build parity
+
+package parity
+
+import (
+	json "encoding/json/v2"
+	"reflect"
+	"regexp"
+	"strings"
+	"testing"
+)
+
+// This catches debug flags being parsed but never connected to the transport,
+// namespace filters being ignored, and diagnostics contaminating JSON stdout.
+func TestEdgeWorkersListDebugParity(t *testing.T) {
+	rig, skip := differentialAvailable(t)
+	if skip != "" {
+		t.Skip(LoudSkip("Edge Workers debug real Node-vs-Go comparisons", skip))
+	}
+	for _, tc := range []struct {
+		name     string
+		flags    []string
+		env      string
+		wantHTTP bool
+	}{
+		{name: "disabled"},
+		{name: "short", flags: []string{"-d"}, wantHTTP: true},
+		{name: "long", flags: []string{"--debug"}, wantHTTP: true},
+		{name: "matching", flags: []string{"--debug=@automattic/vip:http"}, wantHTTP: true},
+		{name: "matching-separated", flags: []string{"--debug", "@automattic/vip:http"}, wantHTTP: true},
+		{name: "nonmatching-separated", flags: []string{"-d", "unrelated:namespace"}},
+		{name: "wildcard-exclusion", flags: []string{"--debug=*,-@automattic/vip:http"}},
+		{name: "nonmatching", flags: []string{"--debug=unrelated:namespace"}},
+		{name: "environment", env: "@automattic/vip:http", wantHTTP: true},
+		{name: "flag-overrides-environment", env: "@automattic/vip:http", flags: []string{"--debug=unrelated:namespace"}},
+		{name: "empty-flag-keeps-environment", env: "@automattic/vip:http", flags: []string{"--debug="}, wantHTTP: true},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var outputs [2]any
+			for side, bin := range []string{rig.nodeBin, rig.goBin} {
+				api := newEdgeFixtureAPI("inactive")
+				// A list response has no reason to reveal stored source in diagnostics.
+				api.workers[0]["source"] = "debug-parity-private-source"
+				rig.serve(t, api)
+				env := rig.scenarioEnv(&Scenario{Env: map[string]string{"DEBUG": tc.env}})
+				args := append([]string{"edge-workers", "list", "--app=42", "--env=develop", "--format=json"}, tc.flags...)
+				result, err := Run(RunSpec{Binary: bin, Dir: t.TempDir(), Argv: args, Env: FixtureEnv(env)})
+				if err != nil {
+					t.Fatal(err)
+				}
+				if result.ExitCode != 0 {
+					t.Fatalf("side %d exited %d: %s", side, result.ExitCode, result.Stderr)
+				}
+				// Approved runtime banner difference, CUTOVER-BREAKING-CHANGES 1.10.
+				stdout := regexp.MustCompile(`(?m)^Debug:  VIP-CLI v[^,\n]+, Node v[^,\n]+, [^,\n]+, Runtime node-script\n`).ReplaceAllString(result.Stdout, "")
+				if err := json.Unmarshal([]byte(stdout), &outputs[side]); err != nil {
+					t.Fatalf("side %d stdout is not JSON: %v\n%s", side, err, stdout)
+				}
+				count := 0
+				for _, line := range strings.Split(result.Stderr, "\n") {
+					if strings.Contains(line, "@automattic/vip:http running fetch "+rig.srv.URL+"/graphql") {
+						count++
+					}
+				}
+				wantCount := 0
+				if tc.wantHTTP {
+					wantCount = 2 // app resolution, then EdgeWorkers
+				}
+				if count != wantCount {
+					t.Errorf("side %d HTTP diagnostics = %d, want %d; stderr:\n%s", side, count, wantCount, result.Stderr)
+				}
+				for _, secret := range []string{rig.token, "debug-parity-private-source", "Bearer ", `"variables":`, `"edgeWorkers":`} {
+					if strings.Contains(result.Stderr, secret) {
+						t.Errorf("side %d diagnostics exposed credential or payload data", side)
+					}
+				}
+				ops, observations := api.snapshot()
+				if len(ops) != 0 || len(observations) != 1 || observations[0].Operation != "EdgeWorkers" || observations[0].Source {
+					t.Errorf("side %d did not perform exactly one source-free list: operations=%v requests=%v", side, ops, observations)
+				}
+			}
+			if !reflect.DeepEqual(outputs[0], outputs[1]) {
+				t.Errorf("JSON output differs: Node=%v Go=%v", outputs[0], outputs[1])
+			}
+		})
+	}
+}

package/internal/parity/pendo_test.go

@@ -0,0 +1,122 @@
+//go:build parity
+
+package parity
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"time"
+
+	json "encoding/json/v2"
+	"github.com/Automattic/vip/internal/debuglog"
+	"github.com/Automattic/vip/internal/telemetry"
+)
+
+// Compare the real clients and HTTP stacks against an authenticated local
+// endpoint. Only credential lookup is injected; no real analytics or user
+// keychain is touched. The ordinary CLI parity harness disables telemetry.
+func TestPendoClientParity(t *testing.T) {
+	node := ResolveNodeVipBin(os.Getenv("NODE_VIP_BIN"), DefaultNodeVipBinProbe())
+	if !node.Ready {
+		t.Skip(LoudSkip("Pendo real Node-vs-Go client comparison", node.Reason))
+	}
+	dist := filepath.Dir(filepath.Dir(node.Path))
+	for _, tc := range []struct {
+		name   string
+		status int
+		token  string
+	}{
+		{"accepted", 200, "credential-sentinel"},
+		{"unauthorized", 401, "credential-sentinel"},
+		{"server-error", 500, "credential-sentinel"},
+		{"no-token", 200, ""},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			var observations [2][]map[string]any
+			for side := range 2 {
+				srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+					body, _ := io.ReadAll(r.Body)
+					var payload map[string]any
+					if err := json.Unmarshal(body, &payload); err != nil {
+						t.Error(err)
+					}
+					if payload["timestamp"] == nil {
+						t.Error("missing timestamp")
+					}
+					delete(payload, "timestamp")
+					observations[side] = append(observations[side], map[string]any{"path": r.URL.Path, "method": r.Method, "auth": r.Header.Get("Authorization"), "payload": payload})
+					status := tc.status
+					if r.Header.Get("Authorization") != "Bearer credential-sentinel" {
+						status = http.StatusUnauthorized
+					}
+					w.WriteHeader(status)
+					_, _ = w.Write([]byte("response-sentinel"))
+				}))
+				var diagnostics bytes.Buffer
+				if side == 0 {
+					const script = `
+const path = require('path');
+const dist = process.argv[1];
+const Token = require(path.join(dist, 'lib/token.js')).default;
+Token.get = async () => ({ raw: process.env.PENDO_FIXTURE_TOKEN });
+const Pendo = require(path.join(dist, 'lib/analytics/clients/pendo.js')).default;
+const c = new Pendo({ userId: 'visitor-sentinel', eventPrefix: 'vip_cli_', env: { userAgent: 'fixture' } });
+c.trackEvent('test', { org_slug: 'org-sentinel', org_sfid: 'account-sentinel' }).then(result => {
+  process.stdout.write(result === false ? 'failed' : 'accepted');
+}).catch(() => { process.exitCode = 1; });
+`
+					ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+					cmd := exec.CommandContext(ctx, "node", "-e", script, dist)
+					cmd.Env = FixtureEnv(map[string]string{"API_HOST": srv.URL, "PENDO_FIXTURE_TOKEN": tc.token, "DEBUG": "@automattic/vip:analytics:clients:pendo"})
+					cmd.Stderr = &diagnostics
+					out, err := cmd.Output()
+					cancel()
+					if err != nil {
+						srv.Close()
+						t.Fatalf("Node: %v\n%s", err, &diagnostics)
+					}
+					want := "failed"
+					if tc.token != "" && tc.status == 200 {
+						want = "accepted"
+					}
+					if string(out) != want {
+						t.Errorf("Node delivery result=%s, want %s", out, want)
+					}
+				} else {
+					c := &telemetry.PendoClient{Endpoint: srv.URL + "/pendo", HTTP: srv.Client(), UserID: "visitor-sentinel", UserAgent: "fixture", EventPrefix: "vip_cli_", GetToken: func() (string, error) { return tc.token, nil }, Context: debuglog.WithLogger(context.Background(), "@automattic/vip:analytics:clients:pendo", &diagnostics)}
+					err := c.TrackEvent("test", map[string]any{"org_slug": "org-sentinel", "org_sfid": "account-sentinel"})
+					if (err != nil) != (tc.token != "" && tc.status != 200) {
+						t.Errorf("Go delivery error=%v for HTTP %d", err, tc.status)
+					}
+				}
+				srv.Close()
+				wantRequests := 1
+				if tc.token == "" {
+					wantRequests = 0
+				}
+				if len(observations[side]) != wantRequests {
+					t.Errorf("side %d requests=%d, want %d", side, len(observations[side]), wantRequests)
+				}
+				if tc.token != "" && !strings.Contains(diagnostics.String(), fmt.Sprint(tc.status)) {
+					t.Errorf("side %d missing HTTP status: %s", side, &diagnostics)
+				}
+				if strings.Contains(diagnostics.String(), "sentinel") {
+					t.Errorf("side %d exposed private data: %s", side, &diagnostics)
+				}
+			}
+			if !reflect.DeepEqual(observations[0], observations[1]) {
+				t.Errorf("request mismatch: Node=%v Go=%v", observations[0], observations[1])
+			}
+		})
+	}
+}

package/internal/rechallenge/flow.go

@@ -6,6 +6,8 @@ import (
 	"io"
 	"os"
 	"time"
+
+	"github.com/Automattic/vip/internal/debuglog"
 )
 
 // Tracker is the minimal telemetry interface the runner needs.
@@ -121,6 +123,7 @@ func (r *Runner) Run(ctx context.Context, in RunInput) (*ElevatedToken, error) {
 		return nil, NewInteractionRequiredError(scope)
 	}
 
+	debuglog.Printf(ctx, "@automattic/vip:rechallenge:client", "createSession scope=%s", scope)
 	session, err := r.Client.CreateSession(CreateSessionInput{
 		Path:               in.Extension.CreateSessionPath,
 		RequestedOperation: scope,
@@ -182,6 +185,11 @@ func (r *Runner) Run(ctx context.Context, in RunInput) (*ElevatedToken, error) {
 		}
 
 		if !ss.Status.IsTerminal() {
+			status := "unknown"
+			if ss.Status == StatusPending {
+				status = "pending"
+			}
+			debuglog.Printf(ctx, "@automattic/vip:rechallenge:flow", "still %s; polling again", status)
 			continue
 		}
 

package/internal/rechallenge/flow_test.go

@@ -11,6 +11,8 @@ import (
 	"sync/atomic"
 	"testing"
 	"time"
+
+	"github.com/Automattic/vip/internal/debuglog"
 )
 
 type fakeTracker struct {
@@ -77,7 +79,9 @@ func TestFlowHappyPathVerified(t *testing.T) {
 		Sleep:      func(_ context.Context, _ time.Duration) error { return nil },
 	}
 
-	tok, err := r.Run(context.Background(), RunInput{
+	var diagnostics bytes.Buffer
+	debugCtx := debuglog.WithLogger(context.Background(), "@automattic/vip:rechallenge:*", &diagnostics)
+	tok, err := r.Run(debugCtx, RunInput{
 		RequestedOperation: "doThing",
 		Interactive:        true,
 		Extension: Extension{
@@ -94,6 +98,16 @@ func TestFlowHappyPathVerified(t *testing.T) {
 	if tok.Token != "opaque" {
 		t.Errorf("token = %q", tok.Token)
 	}
+	for _, want := range []string{"createSession scope=doThing", "still pending; polling again"} {
+		if !strings.Contains(diagnostics.String(), want) {
+			t.Errorf("missing %q in diagnostics: %q", want, diagnostics.String())
+		}
+	}
+	for _, secret := range []string{"opaque", "https://example/v/c1"} {
+		if strings.Contains(diagnostics.String(), secret) {
+			t.Fatal("rechallenge diagnostic leaked credentials")
+		}
+	}
 	if atomic.LoadInt32(&openCalled) != 1 {
 		t.Errorf("OpenURL called %d times, want 1", openCalled)
 	}

package/internal/releasepromotion/buildkite.go

@@ -97,8 +97,19 @@ func (c *BuildkiteClient) DownloadArtifacts(ctx context.Context, build Build, ro
 		return fmt.Errorf("create artifact directory: %w", err)
 	}
 
+	existing, err := os.ReadDir(root)
+	if err != nil {
+		return fmt.Errorf("read artifact directory: %w", err)
+	}
+	if len(existing) != 0 {
+		return fmt.Errorf("artifact directory must be empty; refusing to mix artifacts from different builds")
+	}
+
 	for _, artifactPath := range expectedArtifactPaths {
-		artifact := manifest[artifactPath]
+		artifact, ok := manifest[artifactPath]
+		if !ok {
+			continue
+		}
 		if artifact.DownloadURL == "" {
 			return fmt.Errorf("artifact %q has no download URL", artifactPath)
 		}

package/internal/releasepromotion/buildkite_test.go

@@ -251,3 +251,34 @@ func writeJSON(t *testing.T, w http.ResponseWriter, value any) {
 		t.Fatal(err)
 	}
 }
+
+func TestDownloadArtifactsRejectsStaleOptionalInstallers(t *testing.T) {
+	server := newBuildkiteServer(t, func(w http.ResponseWriter, r *http.Request) {
+		if !strings.HasSuffix(r.URL.Path, "/artifacts") {
+			t.Errorf("unexpected download into nonempty directory: %s", r.URL)
+			w.WriteHeader(500)
+			return
+		}
+		var artifacts []Artifact
+		for _, p := range ExpectedArtifactPaths() {
+			if strings.Contains(p, ".tar.gz") {
+				artifacts = append(artifacts, Artifact{Path: p, State: "finished", DownloadURL: "https://example.invalid/download"})
+			}
+		}
+		writeJSON(t, w, artifacts)
+	})
+	defer server.Close()
+	root := t.TempDir()
+	stale := filepath.Join(root, "vip-next-darwin-amd64.pkg")
+	if err := os.WriteFile(stale, []byte("previous build"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	err := testBuildkiteClient(server.URL).DownloadArtifacts(context.Background(), Build{Number: 28}, root)
+	if err == nil || !strings.Contains(err.Error(), "must be empty") {
+		t.Fatalf("accepted stale artifact: %v", err)
+	}
+	got, err := os.ReadFile(stale)
+	if err != nil || string(got) != "previous build" {
+		t.Fatalf("changed existing artifact: %q %v", got, err)
+	}
+}

package/internal/releasepromotion/contract.go

@@ -2,7 +2,9 @@ package releasepromotion
 
 import (
 	"fmt"
+	"os"
 	"path"
+	"path/filepath"
 	"regexp"
 	"sort"
 	"strings"
@@ -18,6 +20,12 @@ const (
 var prereleaseVersionPattern = regexp.MustCompile(`^5\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)-(alpha|beta|rc)\.(0|[1-9][0-9]*)$`)
 
 var expectedArtifactPaths = []string{
+	"dist/vip-next-darwin-amd64.pkg",
+	"dist/vip-next-darwin-amd64.pkg.sha256",
+	"dist/vip-next-darwin-arm64.pkg",
+	"dist/vip-next-darwin-arm64.pkg.sha256",
+	"dist/vip-next-windows-amd64.msi",
+	"dist/vip-next-windows-amd64.msi.sha256",
 	"dist/vip-next-darwin-amd64.tar.gz",
 	"dist/vip-next-darwin-amd64.tar.gz.sha256",
 	"dist/vip-next-darwin-arm64.tar.gz",
@@ -88,7 +96,16 @@ func ValidateArtifactManifest(artifacts []Artifact) (map[string]Artifact, error)
 	var missing []string
 	for _, artifactPath := range expectedArtifactPaths {
 		if _, ok := manifest[artifactPath]; !ok {
-			missing = append(missing, artifactPath)
+			// Portable binaries are mandatory. Installers are optional, but a
+			// package and its checksum must always be present together.
+			companion := strings.TrimSuffix(artifactPath, ".sha256")
+			if companion == artifactPath {
+				companion += ".sha256"
+			}
+			_, paired := manifest[companion]
+			if strings.Contains(artifactPath, ".tar.gz") || paired {
+				missing = append(missing, artifactPath)
+			}
 		}
 	}
 
@@ -115,3 +132,34 @@ func ValidateArtifactManifest(artifacts []Artifact) (map[string]Artifact, error)
 
 	return manifest, nil
 }
+
+// localArtifactPaths applies the same contract to downloads before upload. It
+// also rejects unknown files and non-regular entries instead of publishing them.
+func localArtifactPaths(root string) ([]string, error) {
+	entries, err := os.ReadDir(root)
+	if err != nil {
+		return nil, err
+	}
+	var artifacts []Artifact
+	for _, entry := range entries {
+		info, err := entry.Info()
+		if err != nil {
+			return nil, err
+		}
+		if !info.Mode().IsRegular() {
+			return nil, fmt.Errorf("replacement asset %q is not a regular file", entry.Name())
+		}
+		artifacts = append(artifacts, Artifact{Path: "dist/" + entry.Name(), State: "finished"})
+	}
+	manifest, err := ValidateArtifactManifest(artifacts)
+	if err != nil {
+		return nil, err
+	}
+	paths := make([]string, 0, len(manifest))
+	for _, p := range expectedArtifactPaths {
+		if _, ok := manifest[p]; ok {
+			paths = append(paths, filepath.Base(p))
+		}
+	}
+	return paths, nil
+}