Fastify
@anievo-id/rbac-evolution-fastify adds RBAC Evolution to Fastify apps: a plugin that resolves the current user's access into request.rbac, and preHandler guards — requirePermission, requireRole and requireRoleOrPermission — that mirror spatie/laravel-permission's permission, role and role_or_permission middleware. Guards behave exactly like the Express ones and return the same response bodies.
It requires Fastify 5.
Installation
npm i @anievo-id/rbac-evolution @anievo-id/rbac-evolution-fastifypnpm add @anievo-id/rbac-evolution @anievo-id/rbac-evolution-fastifyyarn add @anievo-id/rbac-evolution @anievo-id/rbac-evolution-fastifyfastify (5 or newer) is a peer dependency.
Setup
Authentication is up to you (@fastify/jwt, @fastify/session, …). Register it first, then register rbacPlugin and tell it how to find the subject on the request.
import Fastify from 'fastify'
import { createRbac, MemoryAdapter } from '@anievo-id/rbac-evolution'
import { rbacPlugin, requirePermission } from '@anievo-id/rbac-evolution-fastify'
const rbac = createRbac({ adapter: new MemoryAdapter() })
const app = Fastify()
await app.register(yourAuthPlugin) // sets request.user
await app.register(rbacPlugin, {
rbac,
// Return null or undefined for guests.
getSubject: (request) => (request.user ? { type: 'user', id: request.user.id } : null),
})
app.get('/articles', { preHandler: requirePermission('articles.view') }, async () => [])
await app.listen({ port: 3000 })The plugin is wrapped with fastify-plugin, so its hook applies to the context you register it in — register it on the root instance for the whole app, or inside an encapsulated plugin to scope it (see Guards for an API).
rbacPlugin options
| Option | Type | Description |
|---|---|---|
rbac | Rbac | Your createRbac(...) instance. Required. |
getSubject | (request) => Subject | null | undefined | Promise<…> | Resolves the current subject. Required. |
guard | string | Guard name. Defaults to the engine's defaultGuard. |
team | (request) => TeamId | undefined | Promise<…> | Current team. Only for engines created with teams: true. |
hook | 'onRequest' | 'preValidation' | 'preHandler' | Hook in which the subject is resolved. Defaults to 'preHandler'. |
The default preHandler hook runs after authentication done in onRequest / preValidation hooks (including route-level ones such as onRequest: [app.authenticate]) and before the route's own preHandler guards. Choose an earlier hook if you need request.rbac sooner, as long as your authentication has already run by then.
request.rbac
After the hook runs, request.rbac is:
- a
SubjectRbacfor the current subject (the same objectrbac.for(subject, { guard, team })returns), or nullfor guests.
It is typed through FastifyRequest module augmentation, so no casts are needed. With a typed engine, register it once to give request.rbac your names (see Typed request.rbac). Use it for checks inside handlers and to send a snapshot to the browser:
// Feed the React / Vue packages
app.get('/api/me/permissions', async (request) => (request.rbac ? request.rbac.snapshot() : null))
app.post('/articles/:id/publish', async (request, reply) => {
if (!(await request.rbac?.can('articles.publish'))) {
return reply.code(403).send({ error: 'FORBIDDEN' })
}
// ...publish
return { ok: true }
})Route guards
Guards are preHandler hooks. Use them in route options, as an array, or for a whole encapsulated scope:
app.get('/admin/stats', { preHandler: requireRole('admin') }, handler)
app.post('/articles', { preHandler: [requireRole('writer'), requirePermission('articles.create')] }, handler)
app.register(
async (admin) => {
admin.addHook('preHandler', requireRole('admin'))
admin.get('/users', handler)
},
{ prefix: '/admin' },
)requirePermission
app.put('/articles/:id', { preHandler: requirePermission('articles.edit') }, handler)
// any of them — pipe syntax, like spatie's permission:a|b
app.put('/articles/:id', { preHandler: requirePermission('articles.edit|articles.delete') }, handler)
// all of them — one argument per requirement
app.put('/articles/:id', { preHandler: requirePermission('articles.edit', 'articles.publish') }, handler)
// any of them — with { any: true }
app.put('/articles/:id', { preHandler: requirePermission('articles.edit', 'articles.publish', { any: true }) }, handler)Permission checks use can(), so the engine's before hook and superAdminRoles apply. Unknown permissions simply fail the check; they never throw.
canAny / canAll
Named forms of the two common cases, like spatie v8.5's route macros. canAny passes with any of the permissions. canAll needs every argument; a pipe inside one argument still means "any of these".
app.put('/articles/:id', { preHandler: canAny('articles.edit', 'articles.publish') }, handler)
app.put('/articles/:id', { preHandler: canAll('articles.edit', 'articles.publish|articles.delete') }, handler)canAny(...) is requirePermission(..., { any: true }), and canAll(...) is requirePermission(...).
requireRole
app.get('/admin', { preHandler: requireRole('admin') }, handler)
app.get('/staff', { preHandler: requireRole('admin|editor') }, handler) // any of
app.get('/staff', { preHandler: requireRole('admin', 'editor') }, handler) // any of
app.get('/review', { preHandler: requireRole('writer', 'editor', { all: true }) }, handler) // all ofrequireRoleOrPermission
Passes when the user has any of the names, either as a role or as a permission:
app.get('/dashboard', { preHandler: requireRoleOrPermission('admin|dashboard.view') }, handler)Combining names
| Guard | 'a|b' | 'a', 'b' (separate args) | Option |
|---|---|---|---|
requirePermission | any | all | { any: true } → any of everything |
requireRole | any | any | { all: true } → all of everything |
requireRoleOrPermission | any | any | — |
Arrays are accepted wherever a name is; each array item counts like a separate argument, so requirePermission(['a', 'b']) requires both. Guards created with no names throw a TypeError at startup.
Responses
| Situation | Default response |
|---|---|
Guest (request.rbac === null) | 401 { "error": "UNAUTHENTICATED", "message": "User is not logged in." } |
| Missing role/permission | 403 { "error": "FORBIDDEN", "reason": "permission" | "role" | "role_or_permission", "message": "…" } |
rbacPlugin not registered for route | throws RbacMiddlewareMissingError (code: 'RBAC_MIDDLEWARE_MISSING', statusCode: 500) |
The 403 body describes the kind of check but not the names that were required. To include them (for example during development), pass exposeRequirements: true; the body then gets a required field with the groups of names.
WARNING
Exposing the required permissions tells callers exactly what to look for. Keep exposeRequirements off in production. See Security.
Custom handlers
Every guard accepts onUnauthenticated and onForbidden in its options object. Both receive (request, reply, context), where context is { kind, requirements }. A handler must either send a reply or throw (the error goes to your error handler).
requirePermission('articles.edit', {
onUnauthenticated: (request, reply) => reply.redirect('/login'),
onForbidden: (request, reply, { kind }) => reply.code(403).send({ message: `Forbidden (${kind})` }),
})createGuards
To change the defaults for every guard, build your own set with createGuards():
// src/rbac-guards.ts
import { createGuards } from '@anievo-id/rbac-evolution-fastify'
export const { requirePermission, requireRole, requireRoleOrPermission } = createGuards({
onUnauthenticated: (request, reply) => reply.redirect(`/login?next=${encodeURIComponent(request.url)}`),
onForbidden: () => {
throw Object.assign(new Error('Forbidden'), { statusCode: 403 })
},
})Options passed to an individual guard still override the shared defaults. createGuards() accepts onUnauthenticated, onForbidden and exposeRequirements.
Typed names
If you pass a type to createRbac<AppRbac>(), pass the same type to createGuards(). Then a typo in a guard is a compile error. Every name is checked, including each part of a 'a|b' list and each array item.
import { createGuards } from '@anievo-id/rbac-evolution-fastify'
import type { AppRbac } from './rbac' // the type you pass to createRbac<AppRbac>()
export const { requirePermission, requireRole } = createGuards<AppRbac>()
app.put('/articles/:id', { preHandler: requirePermission('edit articles|publish articles') }, updateArticle)
app.delete('/articles/:id', { preHandler: requirePermission('delete artcles') }, deleteArticle) // type errorcreateGuards<typeof rbac>() works too. createGuards() also takes the shared options shown above, and their request.rbac has the same names.
A guard without names, or with options before a name, is a type error too. The guards exported by the package still accept any string. See Typed names.
Typed request.rbac
request.rbac comes from a FastifyRequest augmentation, which is global, so the engine you pass to rbacPlugin can't reach it by itself: without more, request.rbac accepts any name. Register your engine once, next to createRbac():
// src/rbac-register.ts (any file the compiler includes)
import type { rbac } from './rbac'
declare module '@anievo-id/rbac-evolution-fastify' {
interface RbacRegister {
rbac: typeof rbac // or the names type: AppRbac
}
}Now request.rbac has your names in every handler, the onForbidden / onUnauthenticated handlers included, so request.rbac?.can('edit artcles') is a compile error everywhere.
A registration is global: one names type for the whole app. When two plugins use different engines, or you'd rather not declare a module, type the request of a handler with RbacRequest instead:
import type { RbacRequest } from '@anievo-id/rbac-evolution-fastify'
import type { AppRbac } from './rbac'
app.post('/articles/:id/publish', async (request: RbacRequest<AppRbac>, reply) => {
if (!(await request.rbac?.can('publish articles'))) {
return reply.code(403).send({ error: 'FORBIDDEN' })
}
await request.rbac?.can('publish artcles') // type error
return { ok: true }
})RbacRequest<T> takes the names type or typeof rbac. Its second argument is the request type to start from, for a typed route: RbacRequest<AppRbac, FastifyRequest<{ Params: { id: string } }>>.
RbacRegister | RbacRequest<T> | |
|---|---|---|
| Where | once per app | on each handler |
| Engines | one names type for every request | one per handler |
| Route generics | inferred by Fastify as usual | pass the request type yourself |
Teams
When the engine is created with teams: true, resolve the current team per request:
const rbac = createRbac({ adapter, teams: true })
await app.register(rbacPlugin, {
rbac,
getSubject: (request) => (request.user ? { type: 'user', id: request.user.id } : null),
team: (request) => request.headers['x-team-id'] as string | undefined,
})WARNING
The team id usually comes from user input (a header, a URL segment, the session). Make sure the user actually belongs to that team — RBAC Evolution only checks roles and permissions within the team you give it. See Teams.
Guards for an API
guard selects which guard's roles and permissions are loaded. Register the plugin inside an encapsulated scope to use a different guard for part of the app:
await app.register(
async (api) => {
await api.register(rbacPlugin, {
rbac,
guard: 'api',
getSubject: (request) => (request.apiClient ? { type: 'client', id: request.apiClient.id } : null),
})
api.get('/reports', { preHandler: requirePermission('reports.view') }, handler)
},
{ prefix: '/api' },
)Another guard per route
Every guard also takes a guard option: the check runs in that guard (request.rbac.withScope({ guard })) instead of the plugin's, like spatie's role:admin,api / permission:edit articles,api. request.rbac itself is unchanged, and a guest still gets 401. guard is per route only: it is not a createGuards() default.
app.get('/api/admin', { preHandler: requireRole('admin', { guard: 'api' }) }, handler) // role:admin,api
app.get('/api/articles', { preHandler: requirePermission('articles.edit', { guard: 'api' }) }, handler)
app.get('/api/reports', { preHandler: canAny('reports.view', 'reports.export', { guard: 'api' }) }, handler)Names per guard
With typed names per guard, tell createGuards() the guard of the requests it guards, the one the plugin was given. The names of each guard then follow it, and a route's { guard } option takes the names of that guard:
import { createGuards } from '@anievo-id/rbac-evolution-fastify'
type AppRbac = {
guards: {
web: { roles: 'admin' | 'editor'; permissions: 'articles.edit' | 'api-keys.manage' }
api: { roles: 'read-only' | 'full-access'; permissions: 'orders.read' | 'orders.write' }
}
defaultGuard: 'web'
}
const web = createGuards<AppRbac>() // routes of a plugin without `guard`: the default guard
const api = createGuards<AppRbac, 'api'>() // routes of the plugin registered with `guard: 'api'`
app.get('/settings/keys', { preHandler: web.requirePermission('api-keys.manage') }, handler)
app.get('/api/orders', { preHandler: api.requirePermission('orders.read') }, handler)
app.get('/api/keys', { preHandler: api.requirePermission('api-keys.manage') }, handler) // type error: a `web` permission
app.get('/admin/orders', { preHandler: web.requirePermission('orders.read', { guard: 'api' }) }, handler)The second type argument is a type only: at runtime the plugin's guard decides, as before. A guard that is a string variable accepts the names of every guard. Type a handler of the api scope as RbacRequest<typeof rbac, FastifyRequest, 'api'>. RbacRegister types the global request.rbac with the default guard's names.
See Multiple guards.
Full API: reference
