Authorization

Authorization decides what a signed-in user may do. Modules and your app register permissions such as events:update. You bundle them into roles (admin, coordinator, member), give users roles, and write a policy where a rule depends on the record, for example "only the author may edit a post". Then you check the one permission on the server, in route rules and in the interface.

Install it when your app has more than "signed in" and "admin". Who the user is comes from Auth, which also owns the engine that decides. This module adds the roles, where they are stored, the admin pages for them, and what the browser may show. The vocabulary and the order of a check are in Access control.

The package is @frigear-nu/authorization. It works in both modes of Auth. In client mode the same composables only decide what the app shows.

What you get

• Roles from config (authorization.roles) merged with the roles modules ship, with inheritance, requirements and automatic roles. See Roles and requirements.
• Role assignment: a user holds several roles, stored in authorization_user_roles, with a hard-coded escalation rule.
• Policies: definePolicy on the server and defineSharedPolicy for the server and the client. See Policies.
• The client: useAuthorization(), <Can> and <Cannot>, route rules and definePageMeta({ authorize }), and filtered menus, tabs and widgets. See Client.
• Roles admin (needs Admin): read-only role pages and a "Roles and permissions" tab on the admin user page. See Admin.

Quick setup

pnpm add @frigear-nu/authorization @nuxthub/core

import { defineRoles } from '@frigear-nu/auth/access'

export default defineNuxtConfig({
  modules: ['@nuxthub/core', '@frigear-nu/users', '@frigear-nu/authorization'],
  routeRules: {
    '/admin/**': { permission: 'admin:access' },
    '/api/admin/**': { permission: 'admin:access' },
  },
  authorization: {
    defaultRoles: ['user'], // every signed-in user holds these
    roles: defineRoles({
      admin: { label: 'Admin', grant: ['*'] },
      user: { label: 'User', grant: ['events:read'] },
    }),
    redirectTo: '/login', // unauthenticated page visits; client mode defaults to the login path
  },
})

pnpm db:generate

import { intIdParams } from '@frigear-nu/module-kit/server'

export default defineEventHandler(async (event) => {
  await authorize(event, 'posts:update') // 401 or 403 before anything is loaded
  const { id } = await getValidatedRouterParams(event, intIdParams().parse)
  const post = await findPost(id) // 404 only now
  await authorize(event, 'posts:update', post) // policies see the record
})

<Can permission="posts:update" :record="post">
  <button>Edit</button>
</Can>

Options

Options go under the authorization key.

redirectTo. The requested page goes along in ?redirect=, checked by the shared redirect rule. In server mode without the option, or with false, a 401 error is shown instead.

roles and defaultRoles. A role's definition is { label?, labelKey?, description?, descriptionKey?, grant?, inherit?, requirements?, auto?, assignable?, replace? }. All of it is explained on the next page. The formatted example below is a complete host configuration:

export default defineNuxtConfig({
  authorization: {
    defaultRoles: ['user'],
    roles: {
      admin: {
        label: 'Admin',
        labelKey: 'authorization.roles.admin',
        grant: ['*'], // '*' never covers sensitive (:pii) permissions: grant those by name
      },
      manager: {
        label: 'Coordinator',
        labelKey: 'authorization.roles.manager',
        grant: ['forms:*', 'users:read', 'users:list'],
        inherit: ['eventmanager', 'crew'],
      },
      eventmanager: {
        label: 'Event Manager',
        grant: ['events:*'],
        inherit: ['user'],
      },
      crew: {
        label: 'Crew',
        grant: ['events:read'],
        inherit: ['user'],
      },
      member: {
        label: 'Member',
        grant: ['member-area:view'],
        requirements: { subscription: '*' }, // counts only while every requirement holds
        auto: true, // held by everyone meeting the requirements; not assignable
        inherit: ['user'],
      },
      user: {
        label: 'User',
        grant: ['events:read'],
      },
    },
  },
  oauthServer: {
    scopes: [
      // a named scope is a group of permissions (never sensitive or sessionOnly ones)
      { name: 'tickets', label: 'Your tickets', permissions: ['tickets:read', 'tickets:write'] },
    ],
    settings: {
      roleScopes: { // the most each role may grant to a client
        admin: ['*'],
        user: ['openid', 'profile', 'profile:read', 'profile:write', 'tickets:read', 'tickets:write'],
      },
    },
  },
})

Every grant has to name a registered permission, and every role in inherit has to exist: the build stops otherwise.

Hooks

Your app answers these Nitro hooks from a server plugin (server/plugins/*.ts).

The before hook explains authorization:before. authorization:roles is on Roles and requirements.

Routes

Routes the module registers, and who may call them. Paths come from authorizationApi in @frigear-nu/authorization/api. The caller's own access, GET /api/auth/me/access, belongs to Auth.

Permissions

The sensitive permissions of other modules (events:pii, forms:pii) are sensitive (MCP only): they gate personal data in MCP tool output, while the admin HTTP API is gated by events:manage and forms:manage. Grant them by name.

Database

Tables the module adds. Generate and commit a migration after installing. Both exist for SQLite and PostgreSQL.

The users.role column is still added to the users table, for the one-off migration only. Nothing reads it as a live role, and a later release drops it. See the role migration.

Next steps

• Roles and requirements – how roles are built and assigned.
• Policies – refine a permission for one record.
• Client – useAuthorization(), <Can> and route rules.
• Admin – the roles pages and the user roles tab.
• Protect a route – the two-step route in context.
• Authentication – make the first user an admin.