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,120 @@
+# 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)
+- **Docker** — only for multi-user permission testing with Keycloak (port **8080**)
+
+## Development harness
+
+The plugin has two dev harness modes — single-user with guest auth and multi-user with Keycloak OIDC. Both run without a frontend.
+
+| 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  | `start:keycloak` + `start:multi-user`                           |
+
+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. Only one backend `dev/` harness should listen on port **7007** at a time.
+
+### Single-user testing (guest auth, no Keycloak)
+
+```bash
+yarn workspace @backstage-community/plugin-rbac-backend start
+```
+
+The guest user (`user:development/guest`) is configured as the RBAC admin in [`app-config.yaml`](./app-config.yaml). Get a token and test permissions:
+
+```bash
+TOKEN=$(curl -s http://localhost:7007/api/auth/guest/refresh -X POST \
+  -H 'Content-Type: application/json' -d '{}' \
+  | node -e "let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>console.log(JSON.parse(d).backstageIdentity.token))")
+
+curl -s -H "Authorization: Bearer $TOKEN" \
+  http://localhost:7007/api/permission/authorize \
+  -X POST -H 'Content-Type: application/json' \
+  -d '{"items":[{"id":"1","resourceRef":"component:default/x","permission":{"name":"catalog.entity.read","type":"resource","resourceType":"catalog-entity","attributes":{"action":"read"}}}]}'
+```
+
+The guest admin user gets **ALLOW** for `catalog.entity.read`. To verify **DENY** behavior, remove `user:development/guest` from `permission.rbac.admin.users` in `app-config.yaml` and restart.
+
+List roles:
+
+```bash
+curl -s -H "Authorization: Bearer $TOKEN" http://localhost:7007/api/permission/roles
+```
+
+### Multi-user testing (Keycloak + OIDC)
+
+For testing RBAC policies across multiple users and group hierarchies, the workspace includes 42 superhero test users with pre-configured Casbin CSV policies covering basic RBAC test cases: direct user roles, group-based roles, hierarchical groups, bidirectional group links, and admin/superUser configuration. Test data is in [`__fixtures__/rbac/`](./__fixtures__/rbac/).
+
+Start Keycloak with realm import (terminal 1):
+
+```bash
+yarn workspace @backstage-community/plugin-rbac-backend start:keycloak
+```
+
+Keycloak admin: http://localhost:8080/admin (`admin` / `admin`).
+Realm `backstage` is auto-imported from [`__fixtures__/keycloak/backstage-realm.json`](./__fixtures__/keycloak/backstage-realm.json). All test users use password `test`.
+
+Start the backend with OIDC overlay (terminal 2, after Keycloak is healthy):
+
+```bash
+yarn workspace @backstage-community/plugin-rbac-backend start:multi-user
+```
+
+This loads `app-config.yaml` + [`app-config.multi-user.yaml`](./app-config.multi-user.yaml) (OIDC provider, catalog entities from `__fixtures__/rbac/`, CSV policies, admin/superUser config).
+
+Get a token and check a user's `catalog.entity.read` permission:
+
+```bash
+TOKEN=$(npx @oandriie/backstage-login-helper@^0.3.0 --user ant_man --password test)
+
+curl -s -H "Authorization: Bearer $TOKEN" \
+  http://localhost:7007/api/permission/authorize \
+  -X POST -H 'Content-Type: application/json' \
+  -d '{"items":[{"id":"1","resourceRef":"component:default/artist-lookup","permission":{"name":"catalog.entity.read","type":"resource","resourceType":"catalog-entity","attributes":{"action":"read"}}}]}'
+```
+
+Expected: `ant_man` → ALLOW, `hulk` → DENY.
+
+The login helper ([`@oandriie/backstage-login-helper`](https://github.com/AndrienkoAleksandr/backstage-login-helper)) runs via `npx` — no install needed. It performs the OIDC redirect flow against `/api/auth/oidc/start` using only Node.js built-ins.
+
+### Troubleshooting
+
+| Symptom                           | Likely cause                      | Fix                                                      |
+| --------------------------------- | --------------------------------- | -------------------------------------------------------- |
+| `ECONNREFUSED` on port 8080       | Keycloak not running              | Run `start:keycloak` first                               |
+| `500` on OIDC login               | Keycloak not ready at startup     | Restart the backend after Keycloak is healthy            |
+| `No Keycloak login form found`    | Backend not running or wrong port | Confirm `Listening on :7007` in backend logs             |
+| `Invalid parameter: redirect_uri` | Stale Keycloak container          | Stop/remove the container and run `start:keycloak` again |
+
+## 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).
+
+REST endpoint reference: [docs/apis.md](./docs/apis.md).
+
+## 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
@@ -370,6 +372,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).