feat: per-ref policies on REST endpoints across all SDKs

packages/code-storage-go/client.go

@@ -470,6 +470,9 @@ func (c *Client) generateJWT(repoID string, options RemoteURLOptions) (string, e
 		"iat":    issuedAt.Unix(),
 		"exp":    issuedAt.Add(ttl).Unix(),
 	}
+	if len(options.Refs) > 0 {
+		claims["refs"] = encodeRefsClaim(options.Refs)
+	}
 	if len(options.Ops) > 0 {
 		claims["ops"] = options.Ops
 	}

packages/code-storage-go/commit.go

@@ -183,7 +183,7 @@ func (b *CommitBuilder) Send(ctx context.Context) (CommitResult, error) {
 	}
 
 	ttl := resolveCommitTTL(b.options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := b.client.generateJWT(b.repoID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := b.client.generateJWT(b.repoID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: b.options.Refs})
 	if err != nil {
 		return CommitResult{}, err
 	}

packages/code-storage-go/diff_commit.go

@@ -67,7 +67,7 @@ func (d *diffCommitExecutor) send(ctx context.Context, repoID string) (CommitRes
 	}
 
 	ttl := resolveCommitTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := d.client.generateJWT(repoID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := d.client.generateJWT(repoID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return CommitResult{}, err
 	}

packages/code-storage-go/jwt_claims.go

@@ -0,0 +1,14 @@
+package storage
+
+// encodeRefsClaim builds the JWT `refs` claim as an array of [pattern, ops] tuples.
+func encodeRefsClaim(refs RefPolicies) []any {
+	out := make([]any, len(refs))
+	for i, rule := range refs {
+		opList := []string(rule.Ops)
+		if opList == nil {
+			opList = []string{}
+		}
+		out[i] = []any{rule.Pattern, opList}
+	}
+	return out
+}

packages/code-storage-go/jwt_claims_test.go

@@ -0,0 +1,36 @@
+package storage
+
+import "testing"
+
+func TestEncodeRefsClaim(t *testing.T) {
+	encoded := encodeRefsClaim(RefPolicies{
+		{Pattern: "refs/heads/main", Ops: Ops{OpNoPush}},
+		{Pattern: "refs/heads/release/*", Ops: nil},
+		{Pattern: "*", Ops: Ops{OpNoForcePush}},
+	})
+
+	if len(encoded) != 3 {
+		t.Fatalf("expected 3 rules, got %d", len(encoded))
+	}
+
+	mainRule, ok := encoded[0].([]any)
+	if !ok {
+		t.Fatalf("unexpected rule type: %T", encoded[0])
+	}
+	if mainRule[0] != "refs/heads/main" {
+		t.Fatalf("unexpected pattern: %v", mainRule[0])
+	}
+	mainOps, ok := mainRule[1].([]string)
+	if !ok || len(mainOps) != 1 || mainOps[0] != OpNoPush {
+		t.Fatalf("unexpected ops: %v", mainRule[1])
+	}
+
+	releaseRule, ok := encoded[1].([]any)
+	if !ok {
+		t.Fatalf("unexpected rule type: %T", encoded[1])
+	}
+	releaseOps, ok := releaseRule[1].([]string)
+	if !ok || len(releaseOps) != 0 {
+		t.Fatalf("expected empty ops slice, got %v", releaseRule[1])
+	}
+}

packages/code-storage-go/repo.go

@@ -536,12 +536,12 @@ func (r *Repo) GetNote(ctx context.Context, options GetNoteOptions) (GetNoteResu
 
 // CreateNote adds a git note.
 func (r *Repo) CreateNote(ctx context.Context, options CreateNoteOptions) (NoteWriteResult, error) {
-	return r.writeNote(ctx, options.InvocationOptions, "add", options.SHA, options.Note, options.ExpectedRefSHA, options.Author)
+	return r.writeNote(ctx, options.InvocationOptions, "add", options.SHA, options.Note, options.ExpectedRefSHA, options.Author, options.Refs)
 }
 
 // AppendNote appends to a git note.
 func (r *Repo) AppendNote(ctx context.Context, options AppendNoteOptions) (NoteWriteResult, error) {
-	return r.writeNote(ctx, options.InvocationOptions, "append", options.SHA, options.Note, options.ExpectedRefSHA, options.Author)
+	return r.writeNote(ctx, options.InvocationOptions, "append", options.SHA, options.Note, options.ExpectedRefSHA, options.Author, options.Refs)
 }
 
 // DeleteNote deletes a git note.
@@ -552,7 +552,7 @@ func (r *Repo) DeleteNote(ctx context.Context, options DeleteNoteOptions) (NoteW
 	}
 
 	ttl := resolveInvocationTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return NoteWriteResult{}, err
 	}
@@ -592,7 +592,7 @@ func (r *Repo) DeleteNote(ctx context.Context, options DeleteNoteOptions) (NoteW
 	return result, nil
 }
 
-func (r *Repo) writeNote(ctx context.Context, invocation InvocationOptions, action string, sha string, note string, expectedRefSHA string, author *NoteAuthor) (NoteWriteResult, error) {
+func (r *Repo) writeNote(ctx context.Context, invocation InvocationOptions, action string, sha string, note string, expectedRefSHA string, author *NoteAuthor, refs RefPolicies) (NoteWriteResult, error) {
 	sha = strings.TrimSpace(sha)
 	if sha == "" {
 		return NoteWriteResult{}, errors.New("note sha is required")
@@ -604,7 +604,7 @@ func (r *Repo) writeNote(ctx context.Context, invocation InvocationOptions, acti
 	}
 
 	ttl := resolveInvocationTTL(invocation, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: refs})
 	if err != nil {
 		return NoteWriteResult{}, err
 	}
@@ -862,7 +862,7 @@ func (r *Repo) Grep(ctx context.Context, options GrepOptions) (GrepResult, error
 // PullUpstream triggers a pull-upstream operation.
 func (r *Repo) PullUpstream(ctx context.Context, options PullUpstreamOptions) error {
 	ttl := resolveInvocationTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return err
 	}
@@ -897,7 +897,7 @@ func (r *Repo) CreateBranch(ctx context.Context, options CreateBranchOptions) (C
 	}
 
 	ttl := resolveInvocationTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return CreateBranchResult{}, err
 	}
@@ -944,7 +944,7 @@ func (r *Repo) DeleteBranch(ctx context.Context, options DeleteBranchOptions) (D
 	}
 
 	ttl := resolveInvocationTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return DeleteBranchResult{}, err
 	}
@@ -1020,7 +1020,7 @@ func (r *Repo) Merge(ctx context.Context, options MergeOptions) (MergeResult, er
 	}
 
 	ttl := resolveInvocationTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return MergeResult{}, err
 	}
@@ -1081,7 +1081,7 @@ func (r *Repo) CreateTag(ctx context.Context, options CreateTagOptions) (CreateT
 	}
 
 	ttl := resolveInvocationTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return CreateTagResult{}, err
 	}
@@ -1116,7 +1116,7 @@ func (r *Repo) DeleteTag(ctx context.Context, options DeleteTagOptions) (DeleteT
 	}
 
 	ttl := resolveInvocationTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitRead, PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitRead, PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return DeleteTagResult{}, err
 	}
@@ -1159,7 +1159,7 @@ func (r *Repo) RestoreCommit(ctx context.Context, options RestoreCommitOptions)
 	}
 
 	ttl := resolveCommitTTL(options.InvocationOptions, defaultTokenTTL)
-	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl})
+	jwtToken, err := r.client.generateJWT(r.ID, RemoteURLOptions{Permissions: []Permission{PermissionGitWrite}, TTL: ttl, Refs: options.Refs})
 	if err != nil {
 		return RestoreCommitResult{}, err
 	}

packages/code-storage-go/repo_test.go

@@ -104,6 +104,56 @@ func TestRemoteURLOps(t *testing.T) {
 	})
 }
 
+func TestRemoteURLRefs(t *testing.T) {
+	client, err := NewClient(Options{Name: "acme", Key: testKey, StorageBaseURL: "acme.code.storage"})
+	if err != nil {
+		t.Fatalf("client error: %v", err)
+	}
+	repo := &Repo{ID: "repo-1", DefaultBranch: "main", client: client}
+
+	t.Run("includes refs in JWT when provided", func(t *testing.T) {
+		remote, err := repo.RemoteURL(nil, RemoteURLOptions{
+			Refs: RefPolicies{
+				{Pattern: "refs/heads/main", Ops: Ops{OpNoPush}},
+				{Pattern: "*", Ops: Ops{OpNoForcePush}},
+			},
+		})
+		if err != nil {
+			t.Fatalf("remote url error: %v", err)
+		}
+		claims := parseJWTFromURL(t, remote)
+		refs, ok := claims["refs"].([]interface{})
+		if !ok {
+			t.Fatalf("expected refs claim to be a list, got %T", claims["refs"])
+		}
+		if len(refs) != 2 {
+			t.Fatalf("expected 2 ref rules, got %d", len(refs))
+		}
+		mainRule, ok := refs[0].([]interface{})
+		if !ok || len(mainRule) != 2 {
+			t.Fatalf("unexpected main rule shape: %v", refs[0])
+		}
+		if mainRule[0] != "refs/heads/main" {
+			t.Fatalf("unexpected pattern: %v", mainRule[0])
+		}
+		mainOps, ok := mainRule[1].([]interface{})
+		if !ok || len(mainOps) != 1 || mainOps[0] != "no-push" {
+			t.Fatalf("unexpected main ops: %v", mainRule[1])
+		}
+	})
+
+	t.Run("omits refs from JWT when not provided", func(t *testing.T) {
+		remote, err := repo.RemoteURL(nil, RemoteURLOptions{})
+		if err != nil {
+			t.Fatalf("remote url error: %v", err)
+		}
+		claims := parseJWTFromURL(t, remote)
+		if _, ok := claims["refs"]; ok {
+			t.Fatalf("expected no refs claim")
+		}
+	})
+}
+
 func TestListFilesEphemeral(t *testing.T) {
 	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if r.URL.Path != "/api/v1/repos/files" {

packages/code-storage-go/types.go

@@ -35,16 +35,28 @@ type Op = string
 
 const (
 	OpNoForcePush Op = "no-force-push"
+	OpNoPush      Op = "no-push"
 )
 
 // Ops is a list of policy operations.
 type Ops []Op
 
+// RefPolicy is a single ordered ref-matching policy rule (first match wins).
+type RefPolicy struct {
+	Pattern string
+	Ops     Ops
+}
+
+// RefPolicies is an ordered list of per-ref policy rules for the JWT `refs` claim.
+type RefPolicies []RefPolicy
+
 // RemoteURLOptions configure token generation for remote URLs.
 type RemoteURLOptions struct {
 	Permissions []Permission
 	TTL         time.Duration
 	Ops         Ops
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // InvocationOptions holds common request options.
@@ -232,6 +244,8 @@ type ArchiveOptions struct {
 type PullUpstreamOptions struct {
 	InvocationOptions
 	Ref string
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // ListFilesOptions configures list files.
@@ -309,6 +323,8 @@ type CreateBranchOptions struct {
 	TargetBranch      string
 	BaseIsEphemeral   bool
 	TargetIsEphemeral bool
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // CreateBranchResult describes branch creation result.
@@ -324,6 +340,8 @@ type DeleteBranchOptions struct {
 	InvocationOptions
 	Name      string
 	Ephemeral *bool
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // DeleteBranchResult describes branch deletion result.
@@ -357,6 +375,8 @@ type MergeOptions struct {
 	AllowUnrelatedHistories bool
 	// Squash is incompatible with MergeStrategyFFOnly.
 	Squash bool
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // MergeResultStatus describes a merge operation outcome.
@@ -422,6 +442,8 @@ type CreateTagOptions struct {
 	InvocationOptions
 	Name   string
 	Target string
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // CreateTagResult describes tag creation result.
@@ -435,6 +457,8 @@ type CreateTagResult struct {
 type DeleteTagOptions struct {
 	InvocationOptions
 	Name string
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // DeleteTagResult describes tag deletion result.
@@ -544,6 +568,8 @@ type CreateNoteOptions struct {
 	Note           string
 	ExpectedRefSHA string
 	Author         *NoteAuthor
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // AppendNoteOptions configures note append.
@@ -553,6 +579,8 @@ type AppendNoteOptions struct {
 	Note           string
 	ExpectedRefSHA string
 	Author         *NoteAuthor
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // DeleteNoteOptions configures note delete.
@@ -561,6 +589,8 @@ type DeleteNoteOptions struct {
 	SHA            string
 	ExpectedRefSHA string
 	Author         *NoteAuthor
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // NoteWriteResult describes note write response.
@@ -799,6 +829,8 @@ type CommitOptions struct {
 	EphemeralBase   bool
 	Author          CommitSignature
 	Committer       *CommitSignature
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // CommitFromDiffOptions configures diff commit.
@@ -813,6 +845,8 @@ type CommitFromDiffOptions struct {
 	EphemeralBase   bool
 	Author          CommitSignature
 	Committer       *CommitSignature
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // RestoreCommitOptions configures restore commit.
@@ -824,6 +858,8 @@ type RestoreCommitOptions struct {
 	ExpectedHeadSHA string
 	Author          CommitSignature
 	Committer       *CommitSignature
+	// Refs is evaluated in declaration order; the first matching rule wins.
+	Refs RefPolicies
 }
 
 // RestoreCommitResult describes restore commit.

packages/code-storage-go/version.go

@@ -2,7 +2,7 @@ package storage
 
 const (
 	PackageName    = "code-storage-go-sdk"
-	PackageVersion = "0.8.0"
+	PackageVersion = "0.9.0"
 )
 
 func userAgent() string {