Migrate to the permission model

This release replaces three overlapping access systems with one: permissions (resource:action), roles that bundle them, scopes for delegated credentials, and policies that refine a check against a record. There are no compatibility shims. A removed option or hook either fails the build or, for a hook listener, logs a warning in development and never runs.

What changed and why

• Before. defineAbility functions saw only the user. Route rules, admin.settings.roles and documents compared user.role with a fixed name. Behind rbac: true, "scopes" and "permissions" were the same string. Every module added its own <module>:authorize hook, with three different defaults when RBAC was off (one was "allow everything").
• Now. Code checks one thing: a registered permission, with authorize(event, permission, record?). A user holds several roles, which come from authorization.roles only. A token holds the permissions frozen into it when it was issued. One hook, authorization:before, is the host override. Everything fails closed.

Old to new

Server API and hooks

Configuration

Client

Behaviour changes that bite

These follow from "fail closed". Check each against your app before you deploy.

• No authorization installed. Only implicit permissions (self-service such as tickets:read, profile:write) and authorization:before apply. Route rules are still enforced. A staff route with no role provider and no before listener answers 403, where it may have answered 200 before.
• An unregistered permission is a 403. A route that checks a name nobody registered fails, also for admins and also when before allows. In development it logs an error too. A route rule or page meta naming an unknown permission fails the build.
• * never covers a sensitive permission. * and resource:* skip :pii permissions (events:pii, forms:pii). Grant them by name. grantTo on the permission puts them into admin for you.
• Plain users cannot mint * tokens. A user holds only what their roles grant, and a token cannot hold more than its user. A wildcard token needs a user whose roles cover it.
• users:list is now needed to list users. users:read opens one user; the directory and the sign-up numbers need users:list. The old users:read roles need both.
• events:refund is new and sessionOnly. Refunds are money. Roles that name events:manage need events:refund too; events:* covers it. An API token or OAuth token never refunds.
• forms:credentials is new and sessionOnly. Creating or removing form access tokens, passwords and secrets. Roles that name forms:manage need it too.
• subscriptions:manage is sessionOnly. Granting free memberships and sending payment links is cookie sessions only.
• A user's payment history in the admin needs payments:manage, not just a staff role.
• Token permissions are frozen. A token or OAuth access token carries the permissions it had when it was issued, intersected with its user's. Demoting a user does not shrink an old token's claim, but every check still goes through the user's current permissions, so a demoted user's token loses access at once. A token minted before the upgrade has no frozen set and holds nothing: mint it again.
• DB scopes cannot hold wildcards, sensitive or sessionOnly permissions. The admin refuses them. Config scopes are the same: a named scope that expands to a sensitive or session-only permission fails the build.
• An unknown scope at /oauth/authorize is invalid_scope. It used to be dropped. On refresh, scopes are still filtered silently.
• A role that is in the data but not in config is ignored and listed in a startup warning. Add it to authorization.roles or remove it.

Move the roles in your data

Existing users kept one role each in users.role. A one-time, automatic step copies it:

1. On the first request after the upgrade, @frigear-nu/authorization copies every users.role that is not user (and is not a default or auto role) into authorization_user_roles with source = 'migrated'.
2. It then writes a marker (users-role-migrated) into authorization_meta, so it never runs again. Removing a role later cannot bring it back, because nothing reads users.role as a fallback.
3. Single sign-on writes its own rows (source = 'sso') and never touches manual ones.
4. The users.role column is dropped in the next release.

Verify it. Both queries list users whose old role has no row, so they should return nothing:

SELECT u.id, u.email, u.role
FROM users u
LEFT JOIN authorization_user_roles r ON r.user_id = u.id AND r.role = u.role
WHERE u.role IS NOT NULL AND u.role <> 'user' AND r.user_id IS NULL;

SELECT u.id, u.email, u.role
FROM users u
LEFT JOIN authorization_user_roles r ON r.user_id = u.id AND r.role = u.role
WHERE u.role IS NOT NULL AND u.role <> 'user' AND r.user_id IS NULL;

A role that is a default or auto role in your config is legitimately missing from the result of the copy: list it by name in the query, or ignore it. To see what was copied and which names are unknown to your config:

SELECT role, source, COUNT(*) AS users
FROM authorization_user_roles
GROUP BY role, source
ORDER BY role;

Move an allowlist to authorization:roles

A host that made email allowlists administrators (NUXT_ACL_ADMINS, a *-policy.ts plugin, effectiveRole) now adds the role in the authorization:roles hook. The role is not stored, so removing an address removes the access at once.

export default defineNitroPlugin((nitro) => {
  const admins = new Set((process.env.NUXT_ACL_ADMINS ?? '').split(',').map(email => email.trim().toLowerCase()).filter(Boolean))
  nitro.hooks.hook('authorization:roles', (ctx) => {
    if (admins.has(ctx.user.email.toLowerCase()) && !ctx.roles.includes('admin')) {
      ctx.roles.push('admin') // identify the user from ctx.user, never from the session on ctx.event
    }
  })
})

Rules that deny (a coordinator may not edit an admin, an email change needs a staff check) become a policy, or an authorization:before listener that calls deny(). See Policies.

Checklist

authorization: {
  defaultRoles: ['user'],
  roles: {
    admin: { label: 'Admin', grant: ['*'] },
    manager: { label: 'Coordinator', grant: ['forms:*', 'users:read', 'users:list'], inherit: ['user'] },
    user: { label: 'User', grant: ['events:read'] },
  },
},

pnpm --filter @frigear-nu/<pkg> exec nuxt db generate --cwd "$PWD/packages/<pkg>/test/fixtures/<fixture>"

Next steps

• Access control – the vocabulary, the decision order and the fail-closed table.
• Protect a route – the two-step route in practice.
• Register permissions in a module – for module authors.