What's new
The highlights of each minor release. Every package shares one version number, so 1.x of one package works with 1.x of all the others. Full details are in the changelog.
1.7
- MikroORM. MikroORM 7 runs on Kysely, so the Kysely adapter works on
orm.em.getKysely()with no extra package, and insideem.transactional()too. See MikroORM. - Sequelize. The new
@anievo-id/rbac-evolution-sequelizepackage stores roles and permissions through a Sequelize 6 instance:createRbac({ adapter: sequelizeAdapter(sequelize) }), orsequelizeAdapter(t)insidesequelize.transaction().rbacMigration()creates the tables from sequelize-cli or Umzug. See Sequelize.
1.6
- Solid. The new
@anievo-id/rbac-evolution-solidpackage brings<RbacProvider>,<Can>,<HasRole>anduseCan()accessors to Solid 1.8+ and 2.x, in the browser and in server rendering (SolidStart, TanStack Start Solid). See Solid. - TypeORM. The new
@anievo-id/rbac-evolution-typeormpackage stores roles and permissions through a TypeORM 0.3.20+ or 1.xDataSource:createRbac({ adapter: typeormAdapter(dataSource) }), ortypeormAdapter(manager)insidedataSource.transaction().rbacMigration()creates the tables as a regular TypeORM migration. See TypeORM.
1.5
- Astro. The new
@anievo-id/rbac-evolution-astropackage guards Astro 4 to 7 pages, endpoints and middleware:const denied = await rbacServer.requirePermission(Astro, 'edit articles')isundefinedwhen the check passes, or the 401 / 403Response(or a redirect) to return.getSnapshot(context)feeds<RbacProvider>in a client island. See Astro. - React Router. The new
@anievo-id/rbac-evolution-react-routerpackage guards the loaders and actions of React Router 7 and 8 (framework mode) and Remix 2:await rbacServer.requirePermission(args, 'edit articles')resolves to the subject or throws the usual 401 / 403Response, andgetSnapshot(args)feeds<RbacProvider>of the React package. See React Router. - Elysia. The new
@anievo-id/rbac-evolution-elysiapackage is an Elysia plugin:rbacPlugin()puts a typedrbacon the request context, andrequirePermission,requireRole,requireRoleOrPermission,canAnyandcanAllrun asbeforeHandlehooks on a route or a wholeapp.guard()group, with the same 401 / 403 bodies as the other integrations. Bun first, also on Node, Deno and Cloudflare Workers. See Elysia. - TanStack Start. The new
@anievo-id/rbac-evolution-tanstack-startpackage guards server functions, middleware and server routes:await rbacServer.requirePermission(getRequest(), 'edit articles')resolves to the subject or throws the usual 401 / 403Response, and a handler can return TanStack Router'sredirect()for pages. See TanStack Start. - Redis cache store. The new
@anievo-id/rbac-evolution-redispackage shares the cache between every process:createRbac({ adapter, cache: new RedisCache({ client: redis }) })with an ioredis or node-redis client.clear()is a singleINCR, and a lookup that overlaps a change elsewhere is never served after it. See Cache. subjectsWithoutRole()andsubjectsWithoutPermission(). The opposite ofsubjectsWithRole()/subjectsWithPermission()(spatie'sUser::withoutRole()/withoutPermission()): pass candidate ids inamong, get back the ones without any of the roles or permissions. See Querying subjects.
1.4
- tRPC.
@anievo-id/rbac-evolution-trpcguards tRPC v11 procedures:t.procedure.use(requirePermission('posts.edit')), with the same arguments as the other integrations, andctx.rbacis a typed, non-null subject after the guard. Denials areTRPCErrors (UNAUTHORIZED/FORBIDDEN), andrbacErrorFormattersends the usualreasonto the client. See tRPC. - SvelteKit. The new
@anievo-id/rbac-evolution-sveltekitpackage adds ahandlehook that puts the user'sSubjectRbaconevent.locals.rbac, the usual guards (requirePermission,requireRole, ...) forloadfunctions, form actions and+server.tsendpoints, with the same 401 / 403 bodies, and Svelte 5<Can>/<HasRole>components with a runes-based context fed by the root layout. See SvelteKit.
1.3: Prisma 7, Kysely 0.29 and Mongoose 9
Support for the current major versions of three ORMs. The older versions stay supported, and nothing changes on the rbac side: the same models, tables and options.
- Prisma 7. Pass your driver adapter to
new PrismaClient({ adapter })as Prisma 7 requires, and give the client toPrismaAdapteras before. Prisma 5.12 and 6 keep working. See Prisma 7. - Kysely 0.29.
rbacMigration()andrbacExpiryMigration()now returnRbacMigration, the same shape as Kysely'sMigration, so they work with theMigratorfromkysely/migration(0.29) and fromkysely(0.28). - Mongoose 9. Mongoose 8 keeps working. On 9, hooks you add to
rbacSchemas()must beasync. See Mongoose 9.
1.2
- Typed names per guard.
createRbac<{ guards: { web: {...}; api: {...} }; defaultGuard: 'web' }>()types the roles and permissions of each guard, and every name is checked in the guard you work in:rbac.for(key, { guard: 'api' }).can('api-keys.manage')is a type error whenapi-keys.manageis awebpermission.sync()checks each block against its own guard. Flat configs keep their meaning. See Typed names: names per guard. - Route guards narrow too.
createGuards<AppRbac, 'api'>(),createRbacDecorators<AppRbac, 'api'>(),createNextRbac({ rbac, guard: 'api' })andcreateRbacServer({ rbac, guard: 'api' })take the names of the request's guard, a route's{ guard }option those of that guard, andisRoleName()/isPermissionName()take{ guard }(withnames.guards). See Multiple guards. - Temporary access.
assignRole(),givePermissionTo()and the syncs take{ expiresAt }; from then on every check, query, snapshot and cache entry treats the link as gone, andrbac.pruneExpired()cleans up. It is opt-in per adapter ({ expiry: true }, plus one nullable column), so 1.1 databases keep working unchanged. See Temporary access.
1.1: lifecycle, typed requests and audit
No breaking changes: every addition is opt-in, and code written for 1.0 behaves the same.
- Removing access.
rbac.for(user).revokeAll()removes every role and direct permission (optionally in every guard and team),rbac.deleteTeam(teamId)removes a team's links and roles, andrbac.for(user).teams()lists the teams a subject has access in. See Teams. Custom adapters get three optional methods; see Custom adapter. - Typed requests.
req.rbac(Express, Fastify),c.var.rbac(Hono) andgetRbac<T>()(NestJS) can carry your typed names, andisRoleName(rbac, value)/isPermissionName(rbac, value)check user input against them. See Typed names. - Wildcards.
subjectsWithPermission(name, { expandWildcards: true })also finds subjects whose wildcard grant implies the name, andwildcardPrefixCheckwarns when a short name likeorders.refundsilently impliesorders.refund.large. See Wildcard permissions. beforehooks in the UI.snapshot({ checkBefore: [...] })sends the names abeforehook denies, and React, Vue and Next.js treat them as not allowed, super-admins included. See Super-admin.- Who made the change. Write calls take
{ actor }, the engine takesgetActor, and every event carriesactor. See Events.
1.0: the stable API
1.0 has no breaking changes from 0.9. What it adds is a promise: the public API of every package only changes in a breaking way in a new major version, every supported runtime, database and framework version is tested in CI, and security fixes have a supported version range. See versioning and, from older releases, the upgrade guide.
Since 0.8, closer to spatie/laravel-permission:
hasAnyDirectPermission(),hasAllDirectPermissions()andcheckPermissionTo()onrbac.for(user).findRoleById(),findPermissionById()androlesWithPermission()on the engine.rbac.for(user).withScope({ guard: 'api' }), and a per-routeguardoption on every integration, likerole:admin,api.<UnlessRole>in React, like@unlessrole.
0.8: typed names in every guard
With createRbac<AppTypes>(), a typo in a route guard, a Nest decorator, a Next.js or Nuxt server helper or the CLI seed is now a compile error. Pipe lists are checked part by part:
const { requirePermission } = createGuards<AppTypes>()
app.put('/articles/:id', requirePermission('articles.edit|articles.publish'), handler) // ok
app.delete('/articles/:id', requirePermission('articles.delte'), handler) // type errorGuards called with no names or with options before a name are type errors everywhere, typed names or not. See typed names and the upgrade guide.
0.7: hardening for 1.0
- Security: on MySQL and SQL Server, lookalike subject ids (
'admin ', and'ADMIN'with Prisma on MySQL) no longer share another subject's roles. Upgrade if you use string subject ids that users can choose. - Engine internals are private, and every option accepts an explicit
undefined(0.7.1). - New checks behind every release: type tests, package lint (publint, arethetypeswrong), property-based tests of the name parsers, a coverage floor, CodeQL and OpenSSF Scorecard. See the threat model.
0.6: one set of guard rules everywhere
Express, Fastify, Hono, NestJS and Nuxt used to carry their own copy of the code that reads guard names ('a|b', several arguments, { any }, { all }). They now share one implementation from core, so every integration answers the same way for the same names.
The building blocks are public, in case you write an integration of your own:
import { permissionRequirement, roleRequirement, satisfiesRequirement } from '@anievo-id/rbac-evolution'
const requirement = permissionRequirement(['articles.edit', 'articles.publish|articles.review'])
// [['articles.edit'], ['articles.publish', 'articles.review']]: edit AND (publish OR review)
if (await satisfiesRequirement(rbac.for(user), requirement)) {
// allowed
}roleRequirement(names, { all: true }) and roleOrPermissionRequirement(names) cover the other two guards.
Upgrading
A guard whose names are all blank now throws a TypeError when it is defined, in every integration, instead of answering 403 on every request. That covers requireRole(' | '), requireRoleOrPermission(' ') and requirePermission('', { any: true }). If names come from configuration, check them before building the guard.
Also in 0.6:
- Faster lookups on big tables.
subjectsWithRole()andsubjectsWithPermission()remove duplicates in the database:groupBywith Prisma, an aggregation with Mongoose (no more 16 MB limit). syncSubjects()under load. Two syncs of the same role at the same time no longer leave it without holders.
0.5: no flicker while permissions load
When the client fetches the snapshot after the page renders, content guarded by <Cannot> or a not branch used to flash for a moment. Tell the provider you are still loading, and the gates render nothing until the snapshot arrives:
const [snapshot, setSnapshot] = useState<RbacSnapshot | null>(null)
const [loading, setLoading] = useState(true)
useEffect(() => {
fetch('/api/me/permissions')
.then((r) => r.json())
.then(setSnapshot)
.finally(() => setLoading(false))
}, [])
return (
<RbacProvider snapshot={snapshot} loading={loading}>
<App />
</RbacProvider>
)export const rbac = createRbacPlugin({ loading: true })
// later, once the snapshot is fetched
rbac.setSnapshot(await fetch('/api/me/permissions').then((r) => r.json()))While loading, every check returns false, cannot() included, and <Can>, <Cannot>, <HasRole>, v-can and v-role show neither their content nor their fallback. See React and Vue.
0.4: spatie v8 parity
canAny / canAll guards
Named forms of the two common cases, like the route macros spatie added in v8.5. canAny passes with any of the permissions. canAll needs every argument, and a pipe inside one argument still means "any of these".
app.put('/articles/:id', canAny('articles.edit', 'articles.publish'), handler)
app.post('/articles/:id/release', canAll('articles.edit', 'articles.publish|articles.review'), handler)@CanAny('articles.edit', 'articles.publish')
@Put(':id')
update() {}export default defineEventHandler(async (event) => {
await rbacServer.canAll(event, 'articles.edit', 'articles.publish')
})They are also in Fastify and Hono. Next.js already had the boolean canAny() / canAll() helpers and takes { all: true } in its guards and middleware rules.
role(...).syncSubjects()
The spatie Role::syncModels() equivalent: make the given subjects of one type the only holders of a role. Other subject types keep it, and role.attached / role.detached events fire for each subject.
await rbac.role('editor').syncSubjects('user', [2, 7]) // only users 2 and 7 are editors nowSee Permissions via roles and Coming from Laravel.
