test(rbac): add module wiring, contract tests, and contributor guide

workspaces/rbac/.changeset/tall-lizards-pay.md

@@ -0,0 +1,28 @@
+---
+'@backstage-community/plugin-rbac-backend': patch
+'@backstage-community/plugin-rbac-common': patch
+'@backstage-community/plugin-rbac': patch
+---
+
+Add CI bump-trust coverage and contributor dev harness documentation for the RBAC plugin family.
+
+**`@backstage-community/plugin-rbac-backend`**
+
+- Add backend `dev/` harness config (`app-config.yaml`) that no longer depends on the workspace root `app-config.yaml`
+- Add `startTestBackend` smoke test for `GET /api/permission/roles`
+- Add policy contract test locking the documented `superUsers` direct-membership rule
+- Add manual backend-only test harness under `plugins/rbac-backend/manual-tests/` (Keycloak, CSV policies, login/permission scripts)
+- Add `CONTRIBUTING.md` with harness, test, and REST smoke guidance
+
+**`@backstage-community/plugin-rbac-common`**
+
+- Add minimal public API contract tests
+- Add `CONTRIBUTING.md`
+
+**`@backstage-community/plugin-rbac`**
+
+- Add `CONTRIBUTING.md` and link it from the plugin README
+
+**Workspace**
+
+- Remove non-functional root `yarn start` and `yarn start:alpha` scripts that paired separate plugin dev servers

workspaces/rbac/.gitignore

@@ -57,3 +57,4 @@ e2e-test-report*/
 
 # Local CSV Policy Files
 *.local.csv
+plugins/rbac-backend/manual-tests/userinfo.csv

workspaces/rbac/.vscode/launch.json

@@ -15,9 +15,9 @@
       "request": "launch",
       "name": "Debug backend",
       "program": "${workspaceRoot}/node_modules/.bin/backstage-cli",
-      "args": ["repo", "start"],
+      "args": ["package", "start", "--config", "app-config.yaml"],
       "console": "integratedTerminal",
-      "cwd": "${workspaceFolder}"
+      "cwd": "${workspaceFolder}/plugins/rbac-backend"
     },
   ]
 }

workspaces/rbac/README.md

@@ -1,18 +1,31 @@
-# [Backstage](https://backstage.io)
+# RBAC — Backstage community-plugins workspace
 
-This is your newly scaffolded Backstage App, Good Luck!
+Publishable packages live under `plugins/` (`rbac`, `rbac-backend`, `rbac-common`, `rbac-node`).
 
-To start the app, run:
+## Setup
 
 ```sh
 yarn install
-yarn start
 ```
 
-To generate knip reports for this app, run:
+## Development
+
+There is no `packages/app` in this workspace. Use per-plugin dev harnesses:
 
 ```sh
-yarn backstage-repo-tools knip-reports
+# Backend (policy, REST API)
+yarn workspace @backstage-community/plugin-rbac-backend start
+
+# Frontend UI (mocked APIs — default for UI work)
+yarn workspace @backstage-community/plugin-rbac start:mock
 ```
 
-> Notice: The guest user has admin permissions in this application for quick setup. For better control, specify more users and groups in app-config.local.yaml and define a separate admin/admins permission instead of using the guest user. Using the guest user as an admin is not recommended for permission management.
+See [plugins/rbac-backend/CONTRIBUTING.md](./plugins/rbac-backend/CONTRIBUTING.md) and [plugins/rbac/CONTRIBUTING.md](./plugins/rbac/CONTRIBUTING.md).
+
+## Other commands
+
+```sh
+yarn test
+yarn lint
+yarn backstage-repo-tools knip-reports
+```

workspaces/rbac/package.json

@@ -6,8 +6,6 @@
     "node": "22 || 24"
   },
   "scripts": {
-    "start": "backstage-cli repo start",
-    "start:alpha": "yarn workspaces foreach -A --include @backstage-community/plugin-rbac --include @backstage-community/plugin-rbac-backend --parallel -v -i run start:alpha",
     "tsc": "tsc",
     "tsc:full": "tsc --skipLibCheck true --incremental false",
     "build:all": "backstage-cli repo build --all",

workspaces/rbac/plugins/rbac-backend/CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing — RBAC backend plugin
+
+Developer guide for `@backstage-community/plugin-rbac-backend`. For operator install and configuration, see [README.md](./README.md).
+
+## Prerequisites
+
+- Node.js **22+** (see workspace `engines` in the workspace root `package.json`)
+- Yarn (community-plugins monorepo lockfile)
+
+## Development harness
+
+Start the backend plugin in isolation (auth, catalog, permission, and RBAC — no frontend):
+
+```bash
+# From workspaces/rbac
+yarn workspace @backstage-community/plugin-rbac-backend start
+```
+
+Sample non-secret config keys live in [`app-config.yaml`](./app-config.yaml) beside this package. Optional overrides: untracked `app-config.local.yaml` in the same directory.
+
+For OIDC-backed manual permission checks (Keycloak + superhero CSV policies):
+
+```bash
+yarn workspace @backstage-community/plugin-rbac-backend start:manual-tests
+```
+
+See [manual-tests/README.md](./manual-tests/README.md) for that flow.
+
+Only one backend `dev/` harness should listen on port **7007** at a time.
+
+### Recommended workflows
+
+| Goal                         | Command                                                                                                                           |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| Backend / REST / policy work | `yarn workspace @backstage-community/plugin-rbac-backend start`                                                                   |
+| UI work (mocked APIs)        | `yarn workspace @backstage-community/plugin-rbac start:mock`                                                                      |
+| Multi-user permission smoke  | `yarn workspace @backstage-community/plugin-rbac-backend start:manual-tests` + [manual-tests/README.md](./manual-tests/README.md) |
+
+### Full workspace evaluation
+
+There is no in-repo full Backstage app (`packages/app`, `packages/backend`). Day-to-day development uses plugin `dev/` harnesses plus automated tests. Legacy NFS-related CI in this workspace was evaluated and remains unchanged — backend `dev/` plus unit/integration tests cover module init and permission route registration.
+
+## Validation commands
+
+From `workspaces/rbac`:
+
+```bash
+yarn workspace @backstage-community/plugin-rbac-backend test
+yarn workspace @backstage-community/plugin-rbac-backend lint:check
+yarn tsc
+```
+
+## What automated tests cover
+
+CI exercises:
+
+- **`startTestBackend`** — RBAC module init and `GET /api/permission/roles` route registration (`src/plugin.test.ts`)
+- **Policy contracts** — Casbin/precedence and documented `superUsers` direct-membership rule (`src/policies/permission-policy.test.ts`)
+- **REST handlers** — role and policy CRUD with mocked dependencies (`src/service/policies-rest-api*.test.ts`)
+
+Shared types and permission constants are covered in [`@backstage-community/plugin-rbac-common`](../rbac-common/CONTRIBUTING.md).
+
+## Optional manual smoke checklist
+
+After changing route registration or bumping `@backstage/*` dependencies:
+
+1. Start the backend harness (`start` or `start:manual-tests`).
+2. Readiness:
+
+   ```bash
+   curl -sf http://localhost:7007/.backstage/health/v1/readiness
+   ```
+
+3. List roles (guest dev token):
+
+   ```bash
+   TOKEN=$(curl -s http://localhost:7007/api/auth/guest/refresh -X POST \
+     -H 'Content-Type: application/json' -d '{}' \
+     | python3 -c "import sys,json; print(json.load(sys.stdin)['backstageIdentity']['token'])")
+   curl -H "Authorization: Bearer ${TOKEN}" http://localhost:7007/api/permission/roles
+   ```
+
+REST endpoint reference: [docs/apis.md](./docs/apis.md).
+
+Multi-user, credential-backed, or production-like end-to-end testing belongs in a consumer Backstage deployment — not a newly scaffolded in-repo full app.
+
+## Related packages
+
+- [RBAC frontend plugin](../rbac/CONTRIBUTING.md)
+- [RBAC common library](../rbac-common/CONTRIBUTING.md)

workspaces/rbac/plugins/rbac-backend/README.md

@@ -6,6 +6,8 @@ The Backstage permission framework is a core component of the Backstage project,
 
 With the RBAC plugin, you'll have the means to efficiently administer permissions within your Backstage instance by assigning them to users and groups.
 
+For local development and CI commands, see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
 ## Prerequisites
 
 Before you dive into utilizing the RBAC plugin for Backstage, there are a few essential prerequisites to ensure a seamless experience. Please review the following requirements to make sure your environment is properly set up
@@ -348,6 +350,11 @@ The maxDepth must be greater than 0 to ensure that the graphs are built correctl
 
 More information about group hierarchy can be found in the doc: [Group hierarchy](./docs/group-hierarchy.md).
 
+## Related documentation
+
+- [Contributor guide](./CONTRIBUTING.md)
+- [REST API reference](./docs/apis.md)
+
 ### Optional RBAC provider module support
 
 We also include the ability to create and load in RBAC backend plugin modules that can be used to make connections to third part access management tools. For more information, consult the [RBAC Providers documentation](./docs/providers.md).

workspaces/rbac/plugins/rbac-backend/app-config.manual-tests.yaml

@@ -0,0 +1,55 @@
+# Overlay for backend-only manual RBAC tests (no frontend required).
+# Usage: yarn workspace @backstage-community/plugin-rbac-backend start:manual-tests
+#
+# Merges on top of app-config.yaml in this directory.
+# See manual-tests/README.md for Keycloak + OIDC login scripts.
+
+discovery:
+  endpoints:
+    - target:
+        internal: http://127.0.0.1:7007/api/{{pluginId}}
+      plugins: ['*']
+
+backend:
+  auth:
+    keys:
+      - secret: manual-tests-backend-secret
+
+auth:
+  session:
+    secret: manual-tests-session-secret
+  environment: development
+  providers:
+    guest: {}
+    oidc:
+      development:
+        metadataUrl: http://localhost:8080/realms/backstage
+        clientId: backstage
+        clientSecret: 5Mpv83xSyJkBVnP1Oi28u9RrbGAMRps3
+        prompt: auto
+        signIn:
+          resolvers:
+            - resolver: emailMatchingUserEntityProfileEmail
+
+catalog:
+  rules:
+    - allow: [Component, System, Group, User, Resource, Location, Template, API]
+  locations:
+    - type: file
+      target: manual-tests/rbac/all.yaml
+      rules:
+        - allow: [User, Group]
+
+permission:
+  enabled: true
+  rbac:
+    pluginsWithPermission:
+      - catalog
+      - permission
+      - scaffolder
+    policies-csv-file: manual-tests/rbac/rbac-policy.csv
+    admin:
+      users:
+        - name: user:default/admin
+      superUsers:
+        - name: user:default/super_user

workspaces/rbac/plugins/rbac-backend/app-config.yaml

@@ -0,0 +1,53 @@
+# Self-contained config for the RBAC backend dev harness.
+# Usage: yarn workspace @backstage-community/plugin-rbac-backend start
+#
+# Optional local overrides: app-config.local.yaml beside this file (gitignored).
+
+app:
+  baseUrl: http://localhost:3000
+
+organization:
+  name: RBAC Dev
+
+backend:
+  baseUrl: http://localhost:7007
+  listen:
+    port: 7007
+  cors:
+    origin: http://localhost:3000
+    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
+    credentials: true
+  database:
+    client: better-sqlite3
+    connection: ':memory:'
+
+auth:
+  environment: development
+  providers:
+    guest: {}
+
+catalog:
+  rules:
+    - allow: [Component, System, API, Resource, Location, Template, User, Group]
+  locations:
+    - type: file
+      target: ../../examples/entities.yaml
+    - type: file
+      target: ../../examples/template/template.yaml
+      rules:
+        - allow: [Template]
+    - type: file
+      target: ../../examples/org.yaml
+      rules:
+        - allow: [User, Group]
+
+permission:
+  enabled: true
+  rbac:
+    pluginsWithPermission:
+      - catalog
+      - permission
+      - scaffolder
+    admin:
+      users:
+        - name: user:development/guest

workspaces/rbac/plugins/rbac-backend/dev/index.ts

@@ -20,6 +20,7 @@ const backend = createBackend();
 
 backend.add(import('@backstage/plugin-auth-backend'));
 backend.add(import('@backstage/plugin-auth-backend-module-guest-provider'));
+backend.add(import('@backstage/plugin-auth-backend-module-oidc-provider'));
 
 backend.add(import('@backstage/plugin-catalog-backend'));
 backend.add(