Expose single-server default bucket signing in Go SDK

Author: terion-labs

packages/go/edgesign/edgesign.go

@@ -29,8 +29,9 @@ var (
 
 // SignInput describes one public edge object URL to sign.
 //
-// DefaultBucketPath only applies in multi-server mode. When set, SignURL emits
-// /{server}/{key} while signing the canonical claims with the real Bucket.
+// DefaultBucketPath applies in single-server and multi-server modes. When set,
+// SignURL emits /{key} in single-server mode or /{server}/{key} in
+// multi-server mode while signing the canonical claims with the real Bucket.
 type SignInput struct {
 	Method                     string
 	BaseURL                    string
@@ -63,9 +64,10 @@ type Claims struct {
 // set, the URL must include the same signed range claim. When it is empty, a
 // signed range claim remains valid and is returned in Claims.Range.
 //
-// DefaultBucket only applies in multi-server mode. When set, VerifyURL also
-// accepts /{server}/{key} paths and verifies the signature against DefaultBucket
-// as the real signed bucket claim.
+// DefaultBucket applies in single-server and multi-server modes. When set,
+// VerifyURL also accepts /{key} in single-server mode or /{server}/{key} in
+// multi-server mode and verifies the signature against DefaultBucket as the real
+// signed bucket claim.
 type VerifyInput struct {
 	Method        string
 	URL           string
@@ -77,7 +79,8 @@ type VerifyInput struct {
 }
 
 // SignURL returns BaseURL/{bucket}/{key}?expires=...&sig=... using the edge
-// gateway HMAC canonical form. When Server is set, it returns
+// gateway HMAC canonical form unless DefaultBucketPath requests the short
+// /{key} form. When Server is set, it returns
 // BaseURL/{server}/{bucket}/{key}?expires=...&sig=... using multi-server mode
 // unless DefaultBucketPath requests the short /{server}/{key} form.
 func SignURL(input SignInput) (string, error) {
@@ -94,6 +97,9 @@ func SignURL(input SignInput) (string, error) {
 		Secret:                     input.Secret,
 	}
 	if input.Server == "" {
+		if input.DefaultBucketPath {
+			return signing.SignURLForModeWithOptions(signingInput, publicpath.ModeSingle, signing.SignOptions{DefaultBucketPath: true})
+		}
 		return signing.SignURL(signingInput)
 	}
 	raw, err := signing.SignURLForMode(signingInput, publicpath.ModeMulti)
@@ -136,6 +142,13 @@ func VerifyURL(input VerifyInput) (Claims, error) {
 func validateURL(input VerifyInput) (signing.Claims, error) {
 	cfg := signing.ValidationConfig{Secret: input.Secret}
 	if input.Server == "" {
+		if input.DefaultBucket != "" {
+			return signing.ValidateURLForModeWithOptions(input.Method, input.URL, cfg, input.Now, publicpath.ModeSingle, signing.ValidationOptions{
+				DefaultBucket: func(server string) (string, bool) {
+					return input.DefaultBucket, server == ""
+				},
+			})
+		}
 		return signing.ValidateURL(input.Method, input.URL, cfg, input.Now)
 	}
 	claims, err := signing.ValidateURLForMode(input.Method, input.URL, cfg, input.Now, publicpath.ModeMulti)

packages/go/edgesign/edgesign_test.go

@@ -211,6 +211,106 @@ func TestNoServerUsesLegacySingleServerBehavior(t *testing.T) {
 	}
 }
 
+func TestSingleServerDefaultBucketPathSignAndVerify(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	expires := now.Add(time.Minute)
+	raw, err := SignURL(SignInput{
+		Method:            "GET",
+		BaseURL:           "https://files.example.com",
+		Bucket:            "demo",
+		Key:               "file.txt",
+		Secret:            "top-secret",
+		Expires:           expires,
+		DefaultBucketPath: true,
+	})
+	if err != nil {
+		t.Fatalf("SignURL() error = %v", err)
+	}
+	u, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("parse signed URL: %v", err)
+	}
+	if got, want := u.EscapedPath(), "/file.txt"; got != want {
+		t.Fatalf("path = %q, want %q", got, want)
+	}
+
+	claims, err := VerifyURL(VerifyInput{Method: "GET", URL: raw, Secret: "top-secret", Now: now, DefaultBucket: "demo"})
+	if err != nil {
+		t.Fatalf("VerifyURL() error = %v", err)
+	}
+	if claims.Server != "" || claims.Bucket != "demo" || claims.Key != "file.txt" {
+		t.Fatalf("claims = %#v", claims)
+	}
+	wantCanonical := "GET\ndemo\nfile.txt\n" + formatUnixSeconds(expires) + "\n\n\n"
+	if got := CanonicalString(claims); got != wantCanonical {
+		t.Fatalf("CanonicalString() = %q, want %q", got, wantCanonical)
+	}
+}
+
+func TestSingleServerDefaultBucketPathRequiresDefaultBucket(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	raw, err := SignURL(SignInput{
+		Method:            "GET",
+		BaseURL:           "https://files.example.com",
+		Bucket:            "demo",
+		Key:               "file.txt",
+		Secret:            "top-secret",
+		Expires:           now.Add(time.Minute),
+		DefaultBucketPath: true,
+	})
+	if err != nil {
+		t.Fatalf("SignURL() error = %v", err)
+	}
+	u, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("parse signed URL: %v", err)
+	}
+	if got, want := u.EscapedPath(), "/file.txt"; got != want {
+		t.Fatalf("path = %q, want %q", got, want)
+	}
+
+	_, err = VerifyURL(VerifyInput{Method: "GET", URL: raw, Secret: "top-secret", Now: now})
+	if err == nil {
+		t.Fatal("VerifyURL() without DefaultBucket succeeded, want error")
+	}
+}
+
+func TestSingleServerDefaultBucketPathShortFormWins(t *testing.T) {
+	now := time.Date(2026, 6, 8, 12, 0, 0, 0, time.UTC)
+	expires := now.Add(time.Minute)
+	raw, err := SignURL(SignInput{
+		Method:            "GET",
+		BaseURL:           "https://files.example.com",
+		Bucket:            "demo",
+		Key:               "demo/file.txt",
+		Secret:            "top-secret",
+		Expires:           expires,
+		DefaultBucketPath: true,
+	})
+	if err != nil {
+		t.Fatalf("SignURL() error = %v", err)
+	}
+	u, err := url.Parse(raw)
+	if err != nil {
+		t.Fatalf("parse signed URL: %v", err)
+	}
+	if got, want := u.EscapedPath(), "/demo/file.txt"; got != want {
+		t.Fatalf("path = %q, want %q", got, want)
+	}
+
+	claims, err := VerifyURL(VerifyInput{Method: "GET", URL: raw, Secret: "top-secret", Now: now, DefaultBucket: "demo"})
+	if err != nil {
+		t.Fatalf("VerifyURL() error = %v", err)
+	}
+	if claims.Server != "" || claims.Bucket != "demo" || claims.Key != "demo/file.txt" {
+		t.Fatalf("claims = %#v", claims)
+	}
+	wantCanonical := "GET\ndemo\ndemo/file.txt\n" + formatUnixSeconds(expires) + "\n\n\n"
+	if got := CanonicalString(claims); got != wantCanonical {
+		t.Fatalf("CanonicalString() = %q, want %q", got, wantCanonical)
+	}
+}
+
 func loadVectors(t *testing.T) []vector {
 	t.Helper()
 	data, err := os.ReadFile("../../testdata/edge-signing-vectors.json")