@stackra/rbac

Role-Based Access Control admin UI + headless services for Stackra. Sits on top of @stackra/auth and @stackra/authorization per ADR-0037.

Phase 3 of the frontend auth split — the admin surface every tenant admin uses to manage roles + permissions + role assignments. Consumes the Laravel stackra/rbac backend package via @stackra/http.

Install

pnpm add @stackra/rbac @stackra/authorization @stackra/container \
         @stackra/contracts @stackra/http @stackra/support \
         reflect-metadata zod
# Optional peers — install per subpath you consume:
pnpm add @stackra/decorators @stackra/i18n @stackra/routing \
         @stackra/testing @stackra/ui react

Quick start

import "reflect-metadata";

import { AuthModule } from "@stackra/auth";
import { AuthorizationModule } from "@stackra/authorization";
import { Module } from "@stackra/container";
import { HttpModule } from "@stackra/http";
import { RbacModule } from "@stackra/rbac";

@Module({
  imports: [
    HttpModule.forRoot({
      default: "api",
      connections: { api: { baseURL: "/api/v1" } },
    }),
    AuthorizationModule.forRoot(),
    AuthModule.forRoot({ appName: "Acme" }),
    RbacModule.forRoot({ api: { baseURL: "/api/v1/rbac" } }),
  ],
})
export class AppModule {}

Mount the admin routes:

import { buildRbacRoutes } from "@stackra/rbac/react";

export const routes = [
  ...buildRbacRoutes(),
  // ...your app routes
];

Or use a specific page directly:

import { RolesListPage } from "@stackra/rbac/react";

function AdminRolesRoute() {
  return <RolesListPage />;
}

Public API

. — module, services, schemas, constants, utilities

• RbacModule.forRoot(options) / .forRootAsync(options) — DI module. Registers HttpModule.forFeature({ name: 'rbac', baseURL: ... }) and binds RolesService + PermissionsService.
• RolesService — list, get, create, update, delete, assign permissions to role, revoke permission, assign role to user, revoke role from user.
• PermissionsService — list, group by domain.
• Zod schemas: createRoleSchema, updateRoleSchema, assignRoleSchema, assignPermissionsSchema.
• Constants: DEFAULT_RBAC_CONFIG, RBAC_ROUTE_PATHS.
• Utilities: applyRoutePrefix, buildListQuery, groupPermissions, mergeConfig, IRbacConfig.
• Interfaces: IRole, IPermission, IPermissionGroup, IRoleDefinition, ITranslatableLabel, ICreateRolePayload, IUpdateRolePayload, IAssignRolePayload, IAssignPermissionsPayload, IListParams, IPaginatedResponse, IPaginationMeta, IUseRolesResult, IUseRoleResult, IUsePermissionsResult, IUseMutationResult, IRbacModuleOptions, IRbacModuleAsyncOptions, IRbacRoutePaths.
• Types: RoleId, PermissionKey, PermissionAction.
• DI tokens (RBAC_CONFIG, ROLES_SERVICE, PERMISSIONS_SERVICE) live in @stackra/contracts per the 2026-07-25 contracts-decorators promotion sweep — import from there.

./react — hooks, pages, routes, provider, module

Hooks:

• useRoles() — paginated role list.
• useRole(id) — one role by id.
• usePermissions() — permission catalogue grouped by domain.
• useRbacConfig() — read the resolved runtime config.
• useCreateRole(), useUpdateRole(), useDeleteRole() — role CRUD.
• useAssignRole(), useRevokeRole() — user ↔ role assignment.
• useAssignPermissions(), useRevokePermission() — role ↔ permission assignment.

Pages:

• <RolesListPage> — paginated table of roles + toolbar (IRolesListPageProps for path overrides).
• <RoleDetailPage> — one-role detail with permissions matrix (IRoleDetailPageProps).
• <PermissionsCatalogPage> — every permission grouped by domain.

Routes:

• buildRbacRoutes(overrides?) — factory returning the three route records. rolesListRoute + roleDetailRoute + permissionsCatalogRoute are also exported directly for consumers that want to compose paths manually. Every route declares access: { permissions: ['admin.roles'] } so PermissionGuard denies traffic without the capability.

Provider + module:

• <RbacProvider> — wired automatically by WebRbacModule.forRoot(...); RbacContext is exported for advanced composition.
• WebRbacModule.forRoot(options?) — react-subpath web module. Composes RbacModule.forRoot(options) and registers the three routes on RoutingModule.forFeature(...).

./testing

Placeholder — the initial 0.1.0 release ships the core services + React hooks; test fakes (MockRolesService, MockPermissionsService, renderWithRbac) are deferred to a follow-up minor bump. Consumers can drive the services via their own vitest mocks against ROLES_SERVICE / PERMISSIONS_SERVICE (both from @stackra/contracts) in the meantime.

Backend contract

Consumes the Laravel stackra/rbac backend package (packages/backend/access/rbac/) via the following endpoints (the actual base URL is caller-configured through RbacModule.forRoot({ api: { baseURL } })):

• GET /roles — list roles (paginated).
• POST /roles — create role.
• GET /roles/{id} — get role.
• PATCH /roles/{id} — update role.
• DELETE /roles/{id} — delete role.
• GET /permissions — list permissions (paginated).
• POST /roles/{id}/permissions — assign permissions to role.
• DELETE /roles/{id}/permissions/{perm} — revoke permission.
• POST /users/{id}/roles — assign role to user.
• DELETE /users/{id}/roles/{role} — revoke role from user.

Related

• ADR-0037 — the 3-package split that motivates this admin package.
• .kiro/steering/ui-components.md — the HeroUI + @stackra/ui mandate every component obeys.
• Sibling packages: @stackra/authorization (Phase 1), @stackra/auth (Phase 2), @stackra/invitations (Phase 4a), @stackra/delegation (Phase 4b), @stackra/grants (Phase 4c), @stackra/access-requests (Phase 4d).

License

MIT © Figentra L.L.C.