Role permissions
Version 8 stores RolePermission.permission as text. The App's Prisma Permission enum
is optional and serves only as a catalog of App-owned IDs. Colon-separated business IDs
can also be provided as constants.
RbacPermissionCatalog loads .haneinfo/generated/permissions.json relative to
process.cwd() once at startup. Run the backend with its plugin build directory as the
working directory (normally backend/) and deploy this generated artifact with the App.
Only active desired entries are grantable; freshInstallPlan is never applied.
ENOENT logs the absolute missing path and exposes only App permissions. Invalid JSON,
an unsupported schema, duplicate IDs or I/O errors fail startup.
By default App permissions come from the consuming App's generated @prisma/client
Permission export, resolved from the working directory. For constants or a different
artifact location, export this provider from an App-owned global module:
{
provide: RBAC_PERMISSION_CATALOG_OPTIONS,
useValue: {
appPermissions: [...Object.values(Permission), 'equipment-loan:loan:return'],
permissionsPath: '/app/backend/.haneinfo/generated/permissions.json',
} satisfies PermissionCatalogOptions,
}
GET /roles/permission-catalog is read-only and uses the same interactive authentication
and ADMIN guard as role management. It returns { permissions: [{ id, displayName, source, pluginId? }] }. RolesService rejects unknown IDs on create, update and replace,
returning unknownPermissionIds. Existing IDs absent from the active catalog are retired:
replacement preserves their grants, and they cannot be newly granted to another role.
Pass this response as permissionCatalog to RolesTable. Use permissionGroups()
to prepare CreateRoleDialog choices. App labels still use Permission.* translations;
plugin labels use displayName. permissionLabels customizes the App heading and
retired marker (defaults: App 權限, 已停用). frontend-admin fetches the catalog itself.
Upgrade each App from 7.x
-
After release, install rbac 8.0.0 and the matching frontend-admin update in every workspace. Update optional m2m-api-key peers to a version accepting rbac 8.
-
Run
haneinfo buildto regenerate plugin artifacts and the composed schema. If the App usesbackend/prisma/schema/as its active schema, also copy the reviewednode_modules/@haneinfo/rbac/prisma/role.prismathere; build does not overwrite that folder. -
Add one App-owned migration before deploying the new backend:
ALTER TABLE role_permissions ALTER COLUMN permission TYPE text USING permission::text; -
Keep the old enum if it still supplies App catalog values. Do not drop its PostgreSQL type while any other column uses it. Existing grant values remain unchanged.
-
Regenerate Prisma Client, deploy the migration, then seed and run App integration tests. Deploy
permissions.jsonand use the same backend working directory at runtime. -
Grant a non-ADMIN designer
<kind>:definition:writeand:read(or READ_ALL). Publishing additionally requires<kind>:definition:publishand remains human-only.
Seed grants
Seeds bypass RolesService, so validate constants against the same catalog before writing:
import { RbacPermissionCatalog } from '@haneinfo/rbac';
const catalog = new RbacPermissionCatalog(); // run from backend/, after haneinfo build
const grants: string[] = [Permission.USERS_READ, 'timer:definition:write'];
catalog.assertGrantable(grants);
await prisma.rolePermission.createMany({
data: grants.map((permission) => ({ roleId, permission })),
skipDuplicates: true,
});
Do not type a mixed catalog as Permission[]. Existing seeds may continue to use
App enum constants, but should validate every grant and preserve retired grants rather
than deleting all role permissions during upgrades.
Instance access lists
Implemented against approved decision 202610-c8e3.
RbacPolicyPort.findRolesByNames(names, transaction?) is an optional batch lookup for existing role machine names and nullable display labels. It joins a supplied transaction and omits missing names. Existing rolesForUser/authorizationOfUser already supplies current role names; consumers pass those names into their own queries and never join RBAC tables. The state-machine manifest declares the new state-machine:instance:admin permission. Regenerate App permissions.json and grant it through RbacPermissionCatalog; a grantee's WRITE alone cannot manage access. API engine floor is 1.14.0.
Upgrade the affected mechanisms together after applying the App migration. The maintained model, HTTP routes, read-only list_instance_access MCP tool, errors and permission contract are documented in @haneinfo/state-machine/agent-guide.md. Its prisma/instance-access.sql migrates the existing reader table to USER/ROLE, READ/WRITE and ASSIGNED/DELEGATED/GRANTED rows while retaining timestamps. The maintainer selected (instanceId, principalType, principalId, source) uniqueness. Manual grants are limited to 100 by default; permanent READ entries survive manual removal. See the package repository validation/equipment-loan/instance-access/report.md for SQL, tests and App restoration evidence.
Authenticated role label lookup
GET /rbac/roles/lookup?q= uses InteractiveAuthGuard without administrative permissions. q is optional, trimmed and at most 200 characters. The response is an array of at most twenty { name, displayName } entries, ordered by machine name then id. LIKE metacharacters are literal. Permission content and membership are never included. Existing administrative /roles routes retain their guards. No new MCP tool or plugin-api contract is needed.
App-declared default roles
defaultRoleIds() no longer falls back to SYSTEM_USER_ROLE (USER) automatically. By default,
newly created users receive no roles ([]). Apps that want new users (via manual creation, JIT, or
CSV import with an empty roles cell) to receive default roles must configure rbac (configRef: "rbac"):
{
"defaultRoleNames": ["EDITOR"]
}
To preserve the previous behavior of assigning USER automatically, configure defaultRoleNames: ["USER"].
Duplicate role names and ADMIN (SYSTEM_ADMIN_ROLE) are rejected at startup. Missing declared
role names throw NotFoundException listing the missing names when defaultRoleIds() runs.
RbacPolicyService also implements RbacPolicyPort.resolveImportRoleIds(names, transaction?) for
CSV user import: machine names are trimmed and deduplicated, ADMIN is rejected with
system-admin, and missing roles are rejected with unknown.