feat: add RBAC contracts, persistence, and bootstrap

.github/workflows/ci.yml

@@ -65,7 +65,9 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: "22"
+          # Minimum supported release: node:sqlite is available without an
+          # additional flag and --experimental-transform-types is present.
+          node-version: "22.13.0"
           cache: "npm"
 
       - name: Install dependencies
@@ -77,6 +79,12 @@ jobs:
       - name: Test complexity reporter
         run: npm run test:lint-complexity
 
+      - name: Test Owner bootstrap CLI
+        run: npm run test:rbac-bootstrap-owner
+
+      - name: Test user merge CLI
+        run: npm run test:user-merge-cli
+
       - name: Check Prettier formatting
         run: npm run format:check
 

package.json

@@ -14,12 +14,15 @@
     "format:check": "prettier --check .",
     "test": "npm run test --workspaces --if-present",
     "test:lint-complexity": "node --test scripts/lint-complexity-message.test.mjs",
+    "test:rbac-bootstrap-owner": "node --experimental-transform-types --test scripts/bootstrap-workspace-owner.test.ts",
+    "test:user-merge-cli": "node --experimental-transform-types --test scripts/merge-split-users.test.ts",
     "test:coverage": "npm run test:coverage --workspaces --if-present",
     "test:integration": "npm run test:integration --workspaces --if-present",
     "typecheck": "npm run build -w @open-inspect/shared && npm run typecheck --workspaces --if-present",
     "knip": "knip",
     "build": "npm run build -w @open-inspect/shared && npm run build --workspaces --if-present",
     "build:opencomputer-template": "npm run build-template -w @open-inspect/opencomputer-infra --",
+    "rbac:bootstrap-owner": "node --experimental-transform-types scripts/bootstrap-workspace-owner.ts",
     "prepare": "node -e \"if (process.env.CI) process.exit(0)\" && husky"
   },
   "devDependencies": {
@@ -39,7 +42,7 @@
     "wrangler": "^4.103.0"
   },
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.13.0"
   },
   "overrides": {
     "minimatch": "^10.2.5",

packages/control-plane/src/authorization/permission-sql.test.ts

@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { rolePermissionPredicate } from "./permission-sql";
+
+describe("rolePermissionPredicate", () => {
+  it("never grants ownership transfer through a custom role", () => {
+    const predicate = rolePermissionPredicate("workspace.transfer_ownership");
+
+    expect(predicate.sql).not.toContain("role_permissions");
+    expect(predicate.values).toEqual(["owner"]);
+  });
+});

packages/control-plane/src/authorization/permission-sql.ts

@@ -0,0 +1,29 @@
+import {
+  BUILT_IN_ROLE_KEYS,
+  isCustomRolePermission,
+  permissionsForBuiltInRole,
+  type PermissionId,
+} from "@open-inspect/shared/rbac";
+
+/** Builds a parameterized role predicate that enforces built-in and custom-role grant rules. */
+export function rolePermissionPredicate(permission: PermissionId): {
+  sql: string;
+  values: string[];
+} {
+  const builtInRoles = BUILT_IN_ROLE_KEYS.filter((role) =>
+    permissionsForBuiltInRole(role).includes(permission)
+  );
+  const customRolePermission = isCustomRolePermission(permission);
+  const customRoleSql = customRolePermission
+    ? `r.key IS NULL AND EXISTS (
+        SELECT 1 FROM role_permissions custom_permission
+        WHERE custom_permission.role_id = r.id
+          AND custom_permission.permission_id = ?
+      )`
+    : "0";
+  return {
+    sql: `(r.key IN (${builtInRoles.map(() => "?").join(", ")})
+      OR (${customRoleSql}))`,
+    values: [...builtInRoles, ...(customRolePermission ? [permission] : [])],
+  };
+}

packages/control-plane/src/authorization/service.ts

@@ -0,0 +1,169 @@
+import {
+  isRegisteredPermission,
+  isCustomRolePermission,
+  permissionsForBuiltInRole,
+  type BuiltInRoleKey,
+  type EffectiveAuthorization,
+  type PermissionId,
+  type RoleSummary,
+  type WorkspaceMember,
+} from "@open-inspect/shared/rbac";
+import {
+  AuthorizationStore,
+  type AuthorizationMutationOutcome,
+  type AuthorizationRoleRecord,
+} from "../db/authorization-store";
+import type { SqlDatabase } from "../db/sql-database";
+
+/** Represents an authorization denial that can be translated directly to an API response. */
+export class AuthorizationError extends Error {
+  /** Creates a denial with its HTTP status, stable error code, and optional missing grant. */
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    readonly permission?: PermissionId
+  ) {
+    super(code);
+    this.name = "AuthorizationError";
+  }
+}
+
+/** Signals that RBAC state changed or violated an invariant during a guarded mutation. */
+export class RbacConflictError extends Error {
+  /** Creates a conflict suitable for retry or refreshed administrative state. */
+  constructor(message: string) {
+    super(message);
+    this.name = "RbacConflictError";
+  }
+}
+
+/** Resolves effective grants and coordinates invariant-preserving workspace RBAC mutations. */
+export class AuthorizationService {
+  private readonly store: AuthorizationStore;
+
+  /** Creates a service backed by the workspace authorization database. */
+  constructor(db: SqlDatabase) {
+    this.store = new AuthorizationStore(db);
+  }
+
+  /** Resolves a user's assigned role and grants, withholding all grants while suspended. */
+  async getEffectiveAuthorization(userId: string): Promise<EffectiveAuthorization> {
+    const record = await this.store.getEffectiveAuthorization(userId);
+    if (!record?.role) throw new AuthorizationError(403, "assignment_required");
+
+    const permissions =
+      record.suspendedAt === null
+        ? await this.loadRolePermissions(record.role.id, record.role.key)
+        : [];
+
+    return {
+      userId: record.userId,
+      suspendedAt: record.suspendedAt,
+      role: record.role,
+      permissions,
+    };
+  }
+
+  /** Returns active authorization when the grant is present, or throws a structured denial. */
+  async requirePermission(
+    userId: string,
+    permission: PermissionId
+  ): Promise<EffectiveAuthorization> {
+    const authorization = await this.getEffectiveAuthorization(userId);
+    if (authorization.suspendedAt !== null) {
+      throw new AuthorizationError(403, "active_user_required");
+    }
+    if (!authorization.permissions.includes(permission)) {
+      throw new AuthorizationError(403, "permission_required", permission);
+    }
+    return authorization;
+  }
+
+  /** Lists roles with their effective permissions and current assignment counts. */
+  async listRoles(): Promise<RoleSummary[]> {
+    const roles = await this.store.listRoles();
+    return Promise.all(roles.map((role) => this.toRoleSummary(role)));
+  }
+
+  /** Returns a role's effective authorization summary, or null when it does not exist. */
+  async getRole(roleId: string): Promise<RoleSummary | null> {
+    const role = await this.store.getRole(roleId);
+    return role ? this.toRoleSummary(role) : null;
+  }
+
+  /** Lists assigned workspace members with suspension and role state. */
+  async listMembers(): Promise<WorkspaceMember[]> {
+    return this.store.listMembers();
+  }
+
+  /** Replaces a member's role under actor revalidation and ownership invariants. */
+  async replaceMemberRole(input: {
+    targetUserId: string;
+    roleId: string;
+    actorUserId: string;
+    requestId: string;
+  }): Promise<void> {
+    this.requireApplied(
+      await this.store.replaceMemberRole({
+        targetUserId: input.targetUserId,
+        roleId: input.roleId,
+        actorUserId: input.actorUserId,
+        requestId: input.requestId,
+        now: Date.now(),
+      }),
+      "Member role precondition conflict"
+    );
+  }
+
+  /** Suspends or reactivates a member while preserving an active workspace owner. */
+  async replaceMemberStatus(input: {
+    targetUserId: string;
+    suspended: boolean;
+    actorUserId: string;
+    requestId: string;
+  }): Promise<void> {
+    this.requireApplied(
+      await this.store.replaceMemberStatus({
+        targetUserId: input.targetUserId,
+        suspended: input.suspended,
+        actorUserId: input.actorUserId,
+        requestId: input.requestId,
+        now: Date.now(),
+      }),
+      "Member status precondition conflict"
+    );
+  }
+
+  private async loadRolePermissions(
+    roleId: string,
+    roleKey: BuiltInRoleKey | null
+  ): Promise<PermissionId[]> {
+    if (roleKey) return permissionsForBuiltInRole(roleKey);
+    return (await this.store.getCustomRolePermissions(roleId)).filter(
+      (permission): permission is PermissionId =>
+        isRegisteredPermission(permission) && isCustomRolePermission(permission)
+    );
+  }
+
+  private async toRoleSummary(role: AuthorizationRoleRecord): Promise<RoleSummary> {
+    return {
+      ...role,
+      permissions: await this.loadRolePermissions(role.id, role.key),
+    };
+  }
+
+  private requireApplied(outcome: AuthorizationMutationOutcome, conflictMessage: string): void {
+    if (outcome.status === "actor_authorization_changed") {
+      throw new RbacConflictError("Actor authorization changed");
+    }
+    if (outcome.status === "role_not_found") {
+      throw new AuthorizationError(404, "role_not_found");
+    }
+    if (outcome.status === "member_not_found") {
+      throw new AuthorizationError(404, "member_not_found");
+    }
+    if (outcome.status === "conflict") {
+      throw new RbacConflictError(conflictMessage);
+    }
+  }
+}

packages/control-plane/src/db/authorization-store.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from "vitest";
+import { AuthorizationStore } from "./authorization-store";
+import type { SqlDatabase, SqlResult, SqlStatement } from "./sql-database";
+
+function result(changes: number, rows: unknown[] = []): SqlResult {
+  return { results: rows, meta: { changes } };
+}
+
+function fakeDatabase(options: {
+  batchResults?: SqlResult[];
+  batchError?: Error;
+  allResults?: unknown[];
+}): SqlDatabase {
+  const statement: SqlStatement = {
+    bind: () => statement,
+    first: async <T>() => null as T | null,
+    run: async <T>() => result(0) as SqlResult<T>,
+    all: async <T>() => result(0, options.allResults) as SqlResult<T>,
+  };
+  return {
+    prepare: () => statement,
+    batch: async <T>() => {
+      if (options.batchError) throw options.batchError;
+      return (options.batchResults ?? []) as SqlResult<T>[];
+    },
+  };
+}
+
+const replaceMemberStatusInput: Parameters<AuthorizationStore["replaceMemberStatus"]>[0] = {
+  targetUserId: "target",
+  suspended: true,
+  actorUserId: "actor",
+  requestId: "request",
+  now: 100,
+};
+
+describe("AuthorizationStore", () => {
+  it("maps persistence role fields at the store boundary", async () => {
+    const store = new AuthorizationStore(
+      fakeDatabase({
+        allResults: [
+          {
+            id: "role_custom",
+            key: null,
+            name: "Custom",
+            description: null,
+            is_system: 0,
+            assignment_count: "4",
+          },
+        ],
+      })
+    );
+
+    await expect(store.listRoles()).resolves.toEqual([
+      {
+        id: "role_custom",
+        key: null,
+        name: "Custom",
+        description: null,
+        assignmentCount: 4,
+      },
+    ]);
+  });
+
+  it.each([
+    "applied",
+    "actor_authorization_changed",
+    "role_not_found",
+    "member_not_found",
+    "conflict",
+  ] as const)("returns the %s member status replacement batch outcome", async (status) => {
+    const store = new AuthorizationStore(
+      fakeDatabase({
+        batchResults: [result(0, [{ status }]), result(1), result(1), result(1)],
+      })
+    );
+
+    await expect(store.replaceMemberStatus(replaceMemberStatusInput)).resolves.toEqual({
+      status,
+    });
+  });
+
+  it("does not classify an unexpected database failure as a conflict", async () => {
+    const failure = new Error("database unavailable");
+    const store = new AuthorizationStore(fakeDatabase({ batchError: failure }));
+
+    await expect(store.replaceMemberStatus(replaceMemberStatusInput)).rejects.toBe(failure);
+  });
+});