feat(reconcile): add Permission and Role kinds, bootstrap only creates missing roles

cmd/export.go

@@ -31,11 +31,10 @@ func ExportCommand(cliConfig *Config) *cli.Command {
 		},
 		Args: cli.ExactArgs(1),
 		RunE: func(cmd *cli.Command, args []string) error {
-			adminClient, err := createAdminClient(cliConfig.Host)
+			registry, err := buildReconcileRegistry(cliConfig.Host, header)
 			if err != nil {
 				return err
 			}
-			registry := reconcileRegistry(adminClient, header)
 			kind, err := resolveKind(args[0], registry)
 			if err != nil {
 				return err

cmd/reconcile.go

@@ -22,9 +22,11 @@ func ReconcileCommand(cliConfig *Config) *cli.Command {
 		Long: heredoc.Doc(`
 			Make platform resources match a desired-state YAML file, through the admin API.
 
-			Supports the PlatformUser kind (platform admins and members) for now. The file
-			decides who has access: anyone listed is added, anyone not listed is removed.
-			Log in as a superuser (for example the bootstrap service account) with --header.
+			Kinds: PlatformUser (platform admins and members), Permission (custom
+			permissions), and Role (platform-level roles). Deleting a permission or a
+			role needs an explicit 'delete: true' on its entry; nothing is deleted by
+			omission. Log in as a superuser (for example the bootstrap service account)
+			with --header.
 
 			Use "frontier export <kind>" to print the current state in this file format.
 		`),
@@ -41,11 +43,11 @@ func ReconcileCommand(cliConfig *Config) *cli.Command {
 			if err != nil {
 				return fmt.Errorf("read desired-state file: %w", err)
 			}
-			adminClient, err := createAdminClient(cliConfig.Host)
+			registry, err := buildReconcileRegistry(cliConfig.Host, header)
 			if err != nil {
 				return err
 			}
-			reports, runErr := reconcile.Run(cmd.Context(), reconcileRegistry(adminClient, header), data, dryRun)
+			reports, runErr := reconcile.Run(cmd.Context(), registry, data, dryRun)
 			for _, rep := range reports {
 				printReconcileReport(cmd, rep)
 			}
@@ -60,11 +62,30 @@ func ReconcileCommand(cliConfig *Config) *cli.Command {
 	return cmd
 }
 
-// reconcileRegistry holds every reconcilable kind. New kinds register here.
-func reconcileRegistry(adminClient frontierv1beta1connect.AdminServiceClient, header string) map[string]reconcile.Reconciler {
+// reconcileAPI joins the two generated clients: reads live on FrontierService,
+// writes on AdminService. The embedded method sets combine to satisfy the
+// per-kind API interfaces.
+type reconcileAPI struct {
+	frontierv1beta1connect.AdminServiceClient
+	frontierv1beta1connect.FrontierServiceClient
+}
+
+// buildReconcileRegistry holds every reconcilable kind. New kinds register here.
+func buildReconcileRegistry(host, header string) (map[string]reconcile.Reconciler, error) {
+	adminClient, err := createAdminClient(host)
+	if err != nil {
+		return nil, err
+	}
+	frontierClient, err := createClient(host)
+	if err != nil {
+		return nil, err
+	}
+	api := reconcileAPI{AdminServiceClient: adminClient, FrontierServiceClient: frontierClient}
 	return map[string]reconcile.Reconciler{
 		reconcile.KindPlatformUser: reconcile.NewPlatformUserReconciler(adminClient, header),
-	}
+		reconcile.KindPermission:   reconcile.NewPermissionReconciler(api, header),
+		reconcile.KindRole:         reconcile.NewRoleReconciler(api, header),
+	}, nil
 }
 
 // printReconcileReport writes the report to stdout. cobra's cmd.Printf falls

cmd/serve.go

@@ -134,6 +134,10 @@ func StartServer(logger *slog.Logger, cfg *config.Frontier) error {
 	}()
 
 	// load resource config
+	if cfg.App.ResourcesConfigPath != "" {
+		logger.Warn("app.resources_config_path is deprecated and will be removed after a deprecation window; " +
+			"manage permissions and roles with 'frontier reconcile' instead")
+	}
 	resourceBlobFS, err := blob.NewStore(ctx, cfg.App.ResourcesConfigPath, cfg.App.ResourcesConfigPathSecret)
 	if err != nil {
 		return err

config/sample.config.yaml

@@ -61,6 +61,8 @@ app:
   host: "127.0.0.1"
   # WARNING: identity_proxy_header bypass all authorization checks and shouldn't be used in production
   identity_proxy_header: X-Frontier-Email
+  # DEPRECATED: will be removed after a deprecation window. Manage permissions
+  # and roles with 'frontier reconcile' instead (see docs/rfcs/0001-declarative-reconcile.md).
   # full path prefixed with scheme where resources config yaml files are kept
   # e.g.:
   # local storage file "file:///tmp/resources_config"

docs/content/docs/reconcile.mdx

@@ -47,6 +47,9 @@ Rules that apply to every document:
 - The whole file is parsed and checked before anything applies. A malformed later
   document stops the run before any change is made.
 - Documents apply in the order they appear in the file.
+- Some kinds depend on others. A role can grant a permission, so a `Permission` document
+  must come before a `Role` document in the same file. The wrong order is rejected before
+  anything applies.
 
 ## The PlatformUser kind
 
@@ -73,6 +76,75 @@ Two safety properties:
 
 Adding a user by an email that does not exist creates that user.
 
+## The Permission kind
+
+A permission is an identity: a `service/resource` namespace plus a verb. There is nothing
+else to manage on it, so it is either created or deleted.
+
+```yaml
+apiVersion: v1
+kind: Permission
+spec:
+  - namespace: compute/order
+    name: get
+  - namespace: compute/order
+    name: legacy
+    delete: true
+```
+
+- The namespace has two parts, `service/resource`. The name is alphanumeric.
+- Frontier's own permissions (the `app` namespaces) belong to the base schema. The
+  reconciler ignores them and rejects a file entry that names one.
+- A custom permission on the server that the file does not list fails the plan. Nothing
+  is deleted just because it is missing; deleting needs `delete: true` on the entry.
+- Creating a permission also updates the authorization schema, so a new permission is
+  ready to use in roles right away.
+
+## The Role kind
+
+`Role` manages platform-level roles. The role name is the identity and never changes. The
+managed fields are the title, the description, the permissions, and the scopes (the
+resource types a role can attach to).
+
+```yaml
+apiVersion: v1
+kind: Role
+spec:
+  - name: compute_order_manager      # custom role: must list its permissions
+    title: Order Manager
+    description: Manages compute orders
+    permissions:
+      - compute_order_get
+      - compute_order_update
+  - name: app_project_viewer         # predefined role: override only the fields you list
+    permissions:
+      - app_project_get
+      - resource_aoi_get
+  - name: old_role
+    delete: true
+```
+
+There are two kinds of roles, and they behave differently.
+
+**Custom roles** are yours to manage in full. A custom role must list at least one
+permission. Every custom role on the server must appear in the file, kept or marked
+`delete: true`; one that is missing fails the plan. A role that still has policy bindings
+cannot be deleted, and the apply fails with a clear error.
+
+**Predefined roles** are the ones Frontier ships, like `app_organization_owner` or
+`app_project_viewer`. They converge to their shipped definitions. A file entry overrides
+only the fields it lists; a field you leave out goes back to the default. A predefined
+role you do not list at all resets fully. The plan marks these resets, so a hand-made
+change to a predefined role shows up as an update back to the default. You cannot delete a
+predefined role; the server recreates it at boot.
+
+Because a predefined role resets to its default, removing its entry from the file is a
+real change. If an entry adds permissions to `app_project_viewer`, deleting that entry
+takes those permissions away on the next apply.
+
+Permission references accept any form the server knows: the slug (`compute_order_get`),
+`service/resource:verb`, or `service.resource.verb`.
+
 ## Running it
 
 Log in as a superuser. The bootstrap service user exists for exactly this; its client id
@@ -115,8 +187,8 @@ The kind argument is case-insensitive and accepts a plural, so `platformuser` an
 
 ## More kinds
 
-The design and the rules every kind follows live in
-[RFC 0001](https://github.com/raystack/frontier/blob/main/docs/rfcs/0001-declarative-reconcile.md).
-Custom permissions and platform-level roles are proposed there as the next kinds; this
-page grows with them. The flag reference for both commands is in the
+This page covers `PlatformUser`, `Permission`, and `Role`. The design and the rules every
+kind follows live in
+[RFC 0001](https://github.com/raystack/frontier/blob/main/docs/rfcs/0001-declarative-reconcile.md),
+which also lists the kinds proposed next. The flag reference for both commands is in the
 [CLI reference](./reference/cli.md).

docs/content/docs/reference/cli.mdx

@@ -33,7 +33,7 @@ List of supported environment variables
 
 Export the current state of a kind as a desired-state YAML file, printed to
 stdout. The output is the format `frontier reconcile` reads: reconciling it
-changes nothing. Supported kind: `PlatformUser`. See the
+changes nothing. Supported kinds: `PlatformUser`, `Permission`, `Role`. See the
 [Reconcile guide](../reconcile.md) for the file format and the flow.
 
 ```
@@ -246,9 +246,11 @@ View a project
 ## `frontier reconcile [flags]`
 
 Make platform resources match a desired-state YAML file, through the admin
-API. The file decides who has access: anyone listed is added, anyone not
-listed is removed. Supported kind: `PlatformUser`. Use `frontier export` to
-print the current state in this file format, and see the
+API. Supported kinds: `PlatformUser` (anyone listed is added, anyone not
+listed is removed), `Permission` (custom permissions), and `Role`
+(platform-level roles). Deleting a permission or a role needs an explicit
+`delete: true` on its entry; nothing is deleted by omission. Use
+`frontier export` to print the current state in this file format, and see the
 [Reconcile guide](../reconcile.md) for the full flow.
 
 ```

internal/api/v1beta1connect/role.go

@@ -27,6 +27,9 @@ func (h *ConnectHandler) CreateRole(ctx context.Context, request *connect.Reques
 	if request.Msg.GetBody() == nil {
 		return nil, connect.NewError(connect.CodeInvalidArgument, ErrBadRequest)
 	}
+	if len(request.Msg.GetBody().GetPermissions()) == 0 {
+		return nil, connect.NewError(connect.CodeInvalidArgument, ErrBadRequest)
+	}
 
 	var metaDataMap metadata.Metadata
 	if request.Msg.GetBody().GetMetadata() != nil {

internal/api/v1beta1connect/role_test.go

@@ -84,6 +84,17 @@ func TestHandler_CreateRole(t *testing.T) {
 			want:    nil,
 			wantErr: connect.NewError(connect.CodeInvalidArgument, ErrBadRequest),
 		},
+		{
+			name: "should return bad request error if permissions are empty",
+			request: connect.NewRequest(&frontierv1beta1.CreateRoleRequest{
+				Body: &frontierv1beta1.RoleRequestBody{
+					Name:        testRoleMap[instanceLevelRoleID].Name,
+					Permissions: nil,
+				},
+			}),
+			want:    nil,
+			wantErr: connect.NewError(connect.CodeInvalidArgument, ErrBadRequest),
+		},
 		{
 			name: "should create role on success",
 			setup: func(rs *mocks.RoleService, ms *mocks.MetaSchemaService) {

internal/bootstrap/service.go

@@ -35,7 +35,6 @@ type RoleService interface {
 	Get(ctx context.Context, id string) (role.Role, error)
 	List(ctx context.Context, f role.Filter) ([]role.Role, error)
 	Upsert(ctx context.Context, toCreate role.Role) (role.Role, error)
-	Update(ctx context.Context, toUpdate role.Role) (role.Role, error)
 }
 
 type RelationService interface {
@@ -288,20 +287,21 @@ func (s Service) MigrateRoles(ctx context.Context) error {
 	return nil
 }
 
-// migrateRole makes the stored role match its definition: create when missing,
-// reconcile when present. Roles are keyed by name, so renaming a definition
-// produces a new role rather than renaming the existing one.
+// migrateRole creates the role when it is missing and leaves it alone when it
+// exists. Operators manage existing roles (title, permissions) out of band via
+// the reconcile flow; updating them here would revert those changes on every
+// boot.
 func (s Service) migrateRole(ctx context.Context, orgID string, defRole schema.RoleDefinition) error {
-	existing, err := s.roleService.Get(ctx, defRole.Name)
+	_, err := s.roleService.Get(ctx, defRole.Name)
 	if errors.Is(err, role.ErrNotExist) {
 		return s.createRole(ctx, orgID, defRole)
 	}
 	if err != nil {
 		// A transient Get failure must not fall through to create: that would
-		// re-Upsert an existing role and skip the prune, the very drift this fixes.
+		// re-Upsert an existing role, reverting out-of-band changes.
 		return fmt.Errorf("get role %s: %w: %s", defRole.Name, schema.ErrMigration, err.Error())
 	}
-	return s.reconcileRole(ctx, existing, defRole)
+	return nil
 }
 
 func (s Service) createRole(ctx context.Context, orgID string, defRole schema.RoleDefinition) error {
@@ -322,50 +322,6 @@ func (s Service) createRole(ctx context.Context, orgID string, defRole schema.Ro
 	return nil
 }
 
-// reconcileRole writes the definition onto an existing role only when its
-// permission set differs. The write goes through role.Update (not a raw row
-// update) because that is what prunes the SpiceDB permission tuples a narrowed
-// definition no longer grants; the equality short-circuit keeps every boot from
-// rewriting unchanged roles and emitting a spurious RoleUpdated audit record.
-func (s Service) reconcileRole(ctx context.Context, existing role.Role, defRole schema.RoleDefinition) error {
-	if permissionsEqual(existing.Permissions, defRole.Permissions) {
-		return nil
-	}
-	existing.Title = defRole.Title
-	existing.Permissions = defRole.Permissions
-	existing.Scopes = defRole.Scopes
-	if existing.Metadata == nil {
-		existing.Metadata = map[string]any{}
-	}
-	existing.Metadata["description"] = defRole.Description
-	if _, err := s.roleService.Update(ctx, existing); err != nil {
-		return fmt.Errorf("can't reconcile role: %w: %s", schema.ErrMigration, err.Error())
-	}
-	return nil
-}
-
-// permissionsEqual reports whether two permission slug sets are equal, ignoring
-// order and duplicates.
-func permissionsEqual(a, b []string) bool {
-	setA := make(map[string]struct{}, len(a))
-	for _, p := range a {
-		setA[p] = struct{}{}
-	}
-	setB := make(map[string]struct{}, len(b))
-	for _, p := range b {
-		setB[p] = struct{}{}
-	}
-	if len(setA) != len(setB) {
-		return false
-	}
-	for p := range setB {
-		if _, ok := setA[p]; !ok {
-			return false
-		}
-	}
-	return true
-}
-
 // MigrateServiceUserOrgPolicies backfills the org policy for service users that
 // have only a SpiceDB member relation (legacy creation flow). Idempotent: on a
 // clean cluster the candidate query returns zero rows and this is a no-op.