feat: add composite coder:* API key scopes for better UX

Add high-level composite scopes that expand to multiple low-level
permissions:
- coder:workspaces.create - Template read/use + workspace CRUD
- coder:workspaces.operate - Workspace read/update
- coder:workspaces.delete - Workspace read/delete
- coder:workspaces.access - Workspace read/SSH/app connect
- coder:templates.build - Template read + file ops + provisioner jobs
- coder:templates.author - Full template management + insights
- coder:apikeys.manage_self - Self API key management

These composite scopes provide intuitive high-level permissions while
maintaining granular control through existing low-level scopes.
Database enum values are persisted to enable storing composite names
directly in tokens.

Author: ThomasK33

coderd/apidoc/docs.go

@@ -0,0 +1,3 @@
+-- No-op: keep enum values to avoid dependency churn.
+-- If strict removal is required, create a new enum type without these values,
+-- cast columns, drop the old type, and rename.

coderd/apidoc/swagger.json

@@ -0,0 +1,9 @@
+-- Add high-level composite coder:* API key scopes
+-- These values are persisted so that tokens can store coder:* names directly.
+ALTER TYPE api_key_scope ADD VALUE IF NOT EXISTS 'coder:workspaces.create';
+ALTER TYPE api_key_scope ADD VALUE IF NOT EXISTS 'coder:workspaces.operate';
+ALTER TYPE api_key_scope ADD VALUE IF NOT EXISTS 'coder:workspaces.delete';
+ALTER TYPE api_key_scope ADD VALUE IF NOT EXISTS 'coder:workspaces.access';
+ALTER TYPE api_key_scope ADD VALUE IF NOT EXISTS 'coder:templates.build';
+ALTER TYPE api_key_scope ADD VALUE IF NOT EXISTS 'coder:templates.author';
+ALTER TYPE api_key_scope ADD VALUE IF NOT EXISTS 'coder:apikeys.manage_self';

coderd/database/dump.sql

@@ -203,6 +203,29 @@ func (s APIKeyScopes) Expand() (rbac.Scope, error) {
 		}
 	}
 
+	// De-duplicate permissions across Site/Org/User
+	dedup := func(in []rbac.Permission) []rbac.Permission {
+		if len(in) == 0 {
+			return in
+		}
+		seen := make(map[string]struct{}, len(in))
+		out := make([]rbac.Permission, 0, len(in))
+		for _, p := range in {
+			key := p.ResourceType + "\x00" + string(p.Action) + "\x00" + strconv.FormatBool(p.Negate)
+			if _, ok := seen[key]; ok {
+				continue
+			}
+			seen[key] = struct{}{}
+			out = append(out, p)
+		}
+		return out
+	}
+	merged.Site = dedup(merged.Site)
+	for orgID, perms := range merged.Org {
+		merged.Org[orgID] = dedup(perms)
+	}
+	merged.User = dedup(merged.User)
+
 	if allowAll || len(allowSet) == 0 {
 		merged.AllowIDList = []rbac.AllowListElement{rbac.AllowListAll()}
 	} else {

coderd/database/migrations/000374_add_composite_api_key_scopes.down.sql

@@ -3,6 +3,7 @@ package rbac
 import (
 	"fmt"
 	"slices"
+	"sort"
 	"strings"
 
 	"github.com/google/uuid"
@@ -120,6 +121,56 @@ func BuiltinScopeNames() []ScopeName {
 	return names
 }
 
+// Composite coder:* scopes expand to multiple low-level resource:action permissions
+// at Site level. These names are persisted in the DB and expanded during
+// authorization.
+var compositePerms = map[ScopeName]map[string][]policy.Action{
+	"coder:workspaces.create": {
+		ResourceTemplate.Type:  {policy.ActionRead, policy.ActionUse},
+		ResourceWorkspace.Type: {policy.ActionCreate, policy.ActionUpdate, policy.ActionRead},
+	},
+	"coder:workspaces.operate": {
+		ResourceWorkspace.Type: {policy.ActionRead, policy.ActionUpdate},
+	},
+	"coder:workspaces.delete": {
+		ResourceWorkspace.Type: {policy.ActionRead, policy.ActionDelete},
+	},
+	"coder:workspaces.access": {
+		ResourceWorkspace.Type: {policy.ActionRead, policy.ActionSSH, policy.ActionApplicationConnect},
+	},
+	"coder:templates.build": {
+		ResourceTemplate.Type: {policy.ActionRead},
+		ResourceFile.Type:     {policy.ActionCreate, policy.ActionRead},
+		"provisioner_jobs":    {policy.ActionRead},
+	},
+	"coder:templates.author": {
+		ResourceTemplate.Type: {policy.ActionRead, policy.ActionCreate, policy.ActionUpdate, policy.ActionDelete, policy.ActionViewInsights},
+		ResourceFile.Type:     {policy.ActionCreate, policy.ActionRead},
+	},
+	"coder:apikeys.manage_self": {
+		ResourceApiKey.Type: {policy.ActionRead, policy.ActionCreate, policy.ActionUpdate, policy.ActionDelete},
+	},
+}
+
+// CompositeSitePermissions returns the site-level Permission list for a coder:* scope.
+func CompositeSitePermissions(name ScopeName) ([]Permission, bool) {
+	perms, ok := compositePerms[name]
+	if !ok {
+		return nil, false
+	}
+	return Permissions(perms), true
+}
+
+// CompositeScopeNames lists all high-level coder:* names in sorted order.
+func CompositeScopeNames() []string {
+	out := make([]string, 0, len(compositePerms))
+	for k := range compositePerms {
+		out = append(out, string(k))
+	}
+	sort.Strings(out)
+	return out
+}
+
 type ExpandableScope interface {
 	Expand() (Scope, error)
 	// Name is for logging and tracing purposes, we want to know the human
@@ -175,6 +226,19 @@ func ExpandScope(scope ScopeName) (Scope, error) {
 	if role, ok := builtinScopes[scope]; ok {
 		return role, nil
 	}
+	if site, ok := CompositeSitePermissions(scope); ok {
+		return Scope{
+			Role: Role{
+				Identifier:  RoleIdentifier{Name: fmt.Sprintf("Scope_%s", scope)},
+				DisplayName: string(scope),
+				Site:        site,
+				Org:         map[string][]Permission{},
+				User:        []Permission{},
+			},
+			// Composites are site-level; allow-list empty by default
+			AllowIDList: []AllowListElement{},
+		}, nil
+	}
 	if res, act, ok := parseLowLevelScope(scope); ok {
 		return expandLowLevel(res, act), nil
 	}

coderd/database/migrations/000374_add_composite_api_key_scopes.up.sql

@@ -52,6 +52,17 @@ var externalLowLevel = map[ScopeName]struct{}{
 	"user_secret:*":      {},
 }
 
+// Public composite coder:* scopes exposed to users.
+var externalComposite = map[ScopeName]struct{}{
+	"coder:workspaces.create":   {},
+	"coder:workspaces.operate":  {},
+	"coder:workspaces.delete":   {},
+	"coder:workspaces.access":   {},
+	"coder:templates.build":     {},
+	"coder:templates.author":    {},
+	"coder:apikeys.manage_self": {},
+}
+
 // IsExternalScope returns true if the scope is public, including the
 // `all` and `application_connect` special scopes and the curated
 // low-level resource:action scopes.
@@ -64,15 +75,18 @@ func IsExternalScope(name ScopeName) bool {
 	if _, ok := externalLowLevel[name]; ok {
 		return true
 	}
+	if _, ok := externalComposite[name]; ok {
+		return true
+	}
 
 	return false
 }
 
-// ExternalScopeNames returns a sorted list of all public scopes, which includes
-// the `all` and `application_connect` special scopes and the curated public
-// low-level names.
+// ExternalScopeNames returns a sorted list of all public scopes, which
+// includes the `all` and `application_connect` special scopes, curated
+// low-level resource:action names, and curated composite coder:* scopes.
 func ExternalScopeNames() []string {
-	names := make([]string, 0, len(externalLowLevel)+2)
+	names := make([]string, 0, len(externalLowLevel)+len(externalComposite)+2)
 	names = append(names, string(ScopeAll))
 	names = append(names, string(ScopeApplicationConnect))
 
@@ -83,6 +97,11 @@ func ExternalScopeNames() []string {
 		}
 	}
 
+	// curated composite names
+	for name := range externalComposite {
+		names = append(names, string(name))
+	}
+
 	sort.Slice(names, func(i, j int) bool { return strings.Compare(names[i], names[j]) < 0 })
 	return names
 }

coderd/database/modelmethods.go

@@ -2,6 +2,7 @@ package rbac
 
 import (
 	"sort"
+	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/require"
@@ -18,7 +19,7 @@ func TestExternalScopeNames(t *testing.T) {
 	sort.Strings(sorted)
 	require.Equal(t, sorted, names)
 
-	// Ensure each entry parses and expands to site-only
+	// Ensure each entry expands to site-only
 	for _, name := range names {
 		// Skip `all` and `application_connect` since they do not
 		// expand into a low level scope.
@@ -27,6 +28,17 @@ func TestExternalScopeNames(t *testing.T) {
 			continue
 		}
 
+		// Composite coder:* scopes expand to one or more site permissions.
+		if strings.HasPrefix(name, "coder:") {
+			s, err := ScopeName(name).Expand()
+			require.NoErrorf(t, err, "catalog entry should expand: %s", name)
+			require.NotEmpty(t, s.Site)
+			require.Empty(t, s.Org)
+			require.Empty(t, s.User)
+			continue
+		}
+
+		// Low-level scopes must parse to a single permission.
 		res, act, ok := parseLowLevelScope(ScopeName(name))
 		require.Truef(t, ok, "catalog entry should parse: %s", name)