Hono
@anievo-id/rbac-evolution-hono adds RBAC Evolution to Hono apps: one middleware that resolves the current user's access, and route guards — requirePermission, requireRole and requireRoleOrPermission — that mirror spatie/laravel-permission's permission, role and role_or_permission middleware.
It uses no Node-only APIs, so it runs wherever Hono runs: Node, Bun, Deno, Cloudflare Workers, Vercel/Netlify edge functions and other Web-standard runtimes. Guards behave exactly like the Express ones and return the same response bodies.
Installation
npm i @anievo-id/rbac-evolution @anievo-id/rbac-evolution-honopnpm add @anievo-id/rbac-evolution @anievo-id/rbac-evolution-honoyarn add @anievo-id/rbac-evolution @anievo-id/rbac-evolution-honohono (4 or newer) is a peer dependency.
Storage on the edge
On Workers and other edge runtimes, pick an adapter whose database driver works there (for example Drizzle or Prisma with an HTTP/edge driver). The MemoryAdapter is fine for tests and demos.
Setup
Authentication is up to you (hono/jwt, a session middleware, …). Register it first, then add rbacMiddleware and tell it how to find the subject on the request.
import { Hono } from 'hono'
import { createRbac, MemoryAdapter } from '@anievo-id/rbac-evolution'
import { type RbacVariables, rbacMiddleware, requirePermission } from '@anievo-id/rbac-evolution-hono'
type User = { id: string }
type AppEnv = { Variables: RbacVariables & { user: User | undefined } }
const rbac = createRbac({ adapter: new MemoryAdapter() })
const app = new Hono<AppEnv>()
app.use(yourAuthMiddleware) // sets c.var.user
app.use(
rbacMiddleware<AppEnv>({
rbac,
// Return null or undefined for guests.
getSubject: (c) => (c.var.user ? { type: 'user', id: c.var.user.id } : null),
}),
)
app.get('/articles', requirePermission('articles.view'), (c) => c.json([]))
export default appIf you do not need your own variables, new Hono<RbacEnv>() is enough.
rbacMiddleware options
| Option | Type | Description |
|---|---|---|
rbac | Rbac | Your createRbac(...) instance. Required. |
getSubject | (c) => Subject | null | undefined | Promise<…> | Resolves the current subject. Required. |
guard | string | Guard name. Defaults to the engine's defaultGuard. |
team | (c) => TeamId | undefined | Promise<…> | Current team. Only for engines created with teams: true. |
Pass your app's env as the type argument (rbacMiddleware<AppEnv>(...)) so c is typed inside getSubject and team. With a typed engine, pass its names too (rbacMiddleware<AppEnv, AppRbac>(...)), see Typed c.var.rbac.
c.var.rbac
After the middleware runs, c.var.rbac (or c.get('rbac')) is:
- a
SubjectRbacfor the current subject (the same objectrbac.for(subject, { guard, team })returns), or nullfor guests.
It is typed through the RbacVariables / RbacEnv types, with your names when you give them the engine (see Typed c.var.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 (c) => c.json(c.var.rbac ? await c.var.rbac.snapshot() : null))
app.post('/articles/:id/publish', async (c) => {
if (!(await c.var.rbac?.can('articles.publish'))) {
return c.json({ error: 'FORBIDDEN' }, 403)
}
// ...publish
return c.json({ ok: true })
})Route guards
Guards are regular Hono middleware, so they work per route or for a whole path:
app.get('/admin/stats', requireRole('admin'), handler)
app.use('/admin/*', requireRole('admin'))requirePermission
app.put('/articles/:id', requirePermission('articles.edit'), handler)
// any of them — pipe syntax, like spatie's permission:a|b
app.put('/articles/:id', requirePermission('articles.edit|articles.delete'), handler)
// all of them — one argument per requirement
app.put('/articles/:id', requirePermission('articles.edit', 'articles.publish'), handler)
// any of them — with { any: true }
app.put('/articles/:id', 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', canAny('articles.edit', 'articles.publish'), handler)
app.put('/articles/:id', canAll('articles.edit', 'articles.publish|articles.delete'), handler)canAny(...) is requirePermission(..., { any: true }), and canAll(...) is requirePermission(...).
requireRole
app.get('/admin', requireRole('admin'), handler)
app.get('/staff', requireRole('admin|editor'), handler) // any of
app.get('/staff', requireRole('admin', 'editor'), handler) // any of
app.get('/review', 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', 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 (c.var.rbac === null) | 401 { "error": "UNAUTHENTICATED", "message": "User is not logged in." } |
| Missing role/permission | 403 { "error": "FORBIDDEN", "reason": "permission" | "role" | "role_or_permission", "message": "…" } |
rbacMiddleware not registered | throws RbacMiddlewareMissingError (code: 'RBAC_MIDDLEWARE_MISSING'), handled by app.onError |
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 (c, context), where context is { kind, requirements }, and return the Response to send — or throw, for example an HTTPException that your app.onError turns into a page.
requirePermission('articles.edit', {
onUnauthenticated: (c) => c.redirect('/login'),
onForbidden: (c, { kind }) => c.html(`<h1>Forbidden (${kind})</h1>`, 403),
})createGuards
To change the defaults for every guard, build your own set with createGuards():
// src/rbac-guards.ts
import { HTTPException } from 'hono/http-exception'
import { createGuards } from '@anievo-id/rbac-evolution-hono'
export const { requirePermission, requireRole, requireRoleOrPermission } = createGuards({
onUnauthenticated: (c) => c.redirect(`/login?next=${encodeURIComponent(c.req.path)}`),
onForbidden: () => {
throw new HTTPException(403, { message: 'Forbidden' })
},
})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-hono'
import type { AppRbac } from './rbac' // the type you pass to createRbac<AppRbac>()
export const { requirePermission, requireRole } = createGuards<AppRbac>()
app.put('/articles/:id', requirePermission('edit articles|publish articles'), updateArticle)
app.delete('/articles/:id', requirePermission('delete artcles'), deleteArticle) // type errorcreateGuards<typeof rbac>() works too. createGuards() also takes the shared options shown above, and their c.var.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 c.var.rbac
Hono types c from the app's env, so the names can flow all the way: give RbacVariables (or RbacEnv) the engine, and c.var.rbac checks names like the engine does.
import { Hono } from 'hono'
import { createRbac } from '@anievo-id/rbac-evolution'
import { createGuards, rbacMiddleware, type RbacVariables } from '@anievo-id/rbac-evolution-hono'
import type { AppRbac } from './rbac'
const rbac = createRbac<AppRbac>({ adapter })
const { requirePermission } = createGuards<typeof rbac>()
type AppEnv = { Variables: RbacVariables<typeof rbac> & { user: { id: string } | undefined } }
const app = new Hono<AppEnv>()
app.use(
rbacMiddleware<AppEnv, AppRbac>({
rbac,
getSubject: (c) => (c.var.user ? { type: 'user', id: c.var.user.id } : null),
}),
)
app.post('/articles/:id/publish', requirePermission('edit articles'), async (c) => {
if (!(await c.var.rbac?.can('publish articles'))) return c.json({ error: 'FORBIDDEN' }, 403)
await c.var.rbac?.can('publish artcles') // type error
return c.json({ ok: true })
})RbacVariables<T> and RbacEnv<T> take the names type or typeof rbac. Without your own env, new Hono<RbacEnv<typeof rbac>>() is enough, and a chained new Hono().use(rbacMiddleware({ rbac, ... })) infers the names from rbac. With an explicit env, TypeScript does not infer the second type argument, so pass both: rbacMiddleware<AppEnv, AppRbac>(...).
Use the guards of createGuards<T>() on typed routes. The guards exported by the package add an untyped c.var.rbac to the route, and the two types merge into one that accepts any name again.
Teams
When the engine is created with teams: true, resolve the current team per request:
const rbac = createRbac({ adapter, teams: true })
app.use(
rbacMiddleware<AppEnv>({
rbac,
getSubject: (c) => (c.var.user ? { type: 'user', id: c.var.user.id } : null),
team: (c) => c.req.header('x-team-id'),
}),
)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. Mount a sub-app with its own middleware:
const api = new Hono<RbacEnv>()
api.use(
rbacMiddleware({
rbac,
guard: 'api',
getSubject: (c) => {
const clientId = c.req.header('x-client-id')
return clientId ? { type: 'client', id: clientId } : null
},
}),
)
api.get('/reports', requirePermission('reports.view'), handler)
app.route('/api', api)Another guard per route
Every guard also takes a guard option: the check runs in that guard (c.var.rbac.withScope({ guard })) instead of the middleware's, like spatie's role:admin,api / permission:edit articles,api. c.var.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', requireRole('admin', { guard: 'api' }), handler) // role:admin,api
app.get('/api/articles', requirePermission('articles.edit', { guard: 'api' }), handler) // permission:articles.edit,api
app.get('/api/reports', canAny('reports.view', 'reports.export', { guard: 'api' }), handler)Names per guard
With typed names per guard, rbacMiddleware({ rbac, guard: 'api' }) types c.var.rbac with the names of api, and createGuards<AppRbac, 'api'>() checks the names of the routes behind it. A route's { guard } option takes the names of that guard:
import { createRbac } from '@anievo-id/rbac-evolution'
import { createGuards, rbacMiddleware } from '@anievo-id/rbac-evolution-hono'
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 engine = createRbac<AppRbac>({ adapter })
const { requirePermission: requireScope } = createGuards<AppRbac, 'api'>()
const api = new Hono()
.use(
rbacMiddleware({
rbac: engine,
guard: 'api', // c.var.rbac: the `api` names
getSubject: (c) => {
const id = c.req.header('x-api-key')
return id ? { type: 'api_key', id } : null
},
}),
)
.get('/orders', requireScope('orders.read'), async (c) => c.json({ write: await c.var.rbac?.can('orders.write') }))
requireScope('api-keys.manage') // type error: a `web` permission
requireScope('api-keys.manage', { guard: 'web' }) // ok: checked in `web`The second type argument of createGuards() is a type only: at runtime the middleware's guard decides, as before. A guard that is a string variable accepts the names of every guard. RbacEnv<typeof engine, 'api'> types a new Hono<...>() app in that guard.
See Multiple guards.
Full API: reference
