Configuration

config/authz.ts uses defineConfig plus the stores factory. Each store is a lazy thunk — the lucid store imports @adonisjs/lucid only when selected, so the peer dependency stays optional.

import { defineConfig, stores } from '@adonis-agora/authz'

export default defineConfig({
  default: 'lucid',
  stores: {
    memory: stores.memory(),
    lucid: stores.lucid({ /* connection, tables, autoCreateSchema */ }),
  },
})

StoresCopy Anchor Link

stores.lucid({
  connection: 'pg',        // defaults to the app's default connection
  autoCreateSchema: false, // recommended: use the published migration instead
  tables: {                // optional name overrides
    roles: 'authz_roles',
  },
  resolveClient: () => authzClient.getStore(), // optional; see "Joining a transaction"
  subjectIdType: 'integer',   // optional; see "Native key-type pivots" below
})

stores.lucid({
  subjectIdType: 'integer', // increments()   → INTEGER
  // subjectIdType: 'bigint', // bigIncrements() → BIGINT
})

-- Postgres (fails loudly on non-numeric rows — good)
ALTER TABLE authz_subject_role ALTER COLUMN subject_id TYPE INTEGER USING subject_id::integer;
ALTER TABLE authz_subject_permission ALTER COLUMN subject_id TYPE INTEGER USING subject_id::integer;
-- MySQL (strict mode errors on non-numeric rows — good)
ALTER TABLE authz_subject_role MODIFY subject_id INTEGER NOT NULL;
ALTER TABLE authz_subject_permission MODIFY subject_id INTEGER NOT NULL;
-- SQLite: rebuild (no ALTER COLUMN) —
CREATE TABLE authz_subject_role_new (subject_type VARCHAR(191) NOT NULL, subject_id INTEGER NOT NULL, role_id VARCHAR(191) NOT NULL, tenant_id VARCHAR(191) NOT NULL DEFAULT '', PRIMARY KEY (subject_type, subject_id, role_id, tenant_id));
INSERT INTO authz_subject_role_new SELECT subject_type, CAST(subject_id AS INTEGER), role_id, tenant_id FROM authz_subject_role;
DROP TABLE authz_subject_role;
ALTER TABLE authz_subject_role_new RENAME TO authz_subject_role;
-- (same for authz_subject_permission, then recreate the _subject_idx indexes)

import { AsyncLocalStorage } from 'node:async_hooks'
import type { StoreQueryClient } from '@adonis-agora/authz'

// The ambient seam: set the config's `resolveClient` to read this.
export const authzClient = new AsyncLocalStorage<StoreQueryClient>()

Super-admin hookCopy Anchor Link

Return true to allow, false to deny, or undefined to fall through to the normal RBAC resolution. It receives the resolved { type, id } reference.

defineConfig({
  // ...
  superAdmin: (user) => user.id === '1',
})

decisionProviderCopy Anchor Link

An external policy decision point (Cerbos, OPA, …) consulted right after the super-admin check: it can allow, deny or abstain on can(), batch canMany(), and plan query scopes. See External policy engines; a Cerbos adapter ships at @adonis-agora/authz/cerbos.

import { CerbosDecisionProvider } from '@adonis-agora/authz/cerbos'

defineConfig({
  // ...
  decisionProvider: new CerbosDecisionProvider({ client, principal, resource }),
})

superAdminRolesCopy Anchor Link

Global role names that short-circuit every check to allow — no rows seeded, no permissions listed:

defineConfig({
  superAdminRoles: ['platform:super'],
})

The superAdmin hook is consulted first and its false outranks the list; only the token's global roles are matched, not the whole effective union. See Roles → superAdminRoles for the full composition rules and when to prefer a roleGrants wildcard instead.

Mapping a user to a referenceCopy Anchor Link

By default user.id (and optional user.type) is used. Override to fit your model:

defineConfig({
  resolveSubjectRef: (user) => ({ type: 'account', id: user.uid }),
})

Tenant resolverCopy Anchor Link

Return a tenant id string (or { tenantId }) for the current request; omit it for single-tenant apps.

import { HttpContext } from '@adonisjs/core/http'

defineConfig({
  tenant: () => HttpContext.getOrFail().request.header('x-tenant'),
})

Effective roles: resolveRoles & roleGrantsCopy Anchor Link

A user's effective roles are the union of three sources — and two config seams let you feed them without seeding the authz store:

effective roles  =  context/global roles (token claim, via authkit)
                  ∪  app roles      (the `resolveRoles` seam)
                  ∪  store roles    (assigned via store.assignRole)

Every decision — can, hasRole, hasAnyRole, the route middleware, a query scope and the frontend share — resolves against this same union, so they never disagree.

resolveRoles — app rolesCopy Anchor Link

Roles that live in your domain (typically a user_roles-style table), not in the token and not in the authz store. Return them and they enter the union and get mapped by roleGrants, exactly like global roles. Optional — omit it and only the token and store decide.

defineConfig({
  resolveRoles: async (user, scope) => {
    const rows = await SubjectRole.query()
      .where('subject_id', user.id)
      .if(scope, (q) => q.where('tenant_id', scope!.tenantId))
    return rows.map((r) => r.role)
  },
})

The callback receives the resolved { type, id } reference and the active TenantScope, so app roles can themselves be tenant-scoped.

resolveRoleMembers & resolveGlobalRoleMembers — the reverse seamsCopy Anchor Link

resolveRoles answers "which roles does this user hold?". Two more keys answer the opposite question — "who holds this role?" — for subjectsWithRole:

defineConfig({
  // reverse of `resolveRoles`: your domain tables.
  resolveRoleMembers: async (role, scope) => {
    const rows = await SubjectRole.query()
      .where('role', role)
      .if(scope?.tenantId, (query) => query.where('tenant_id', scope!.tenantId!))
    return rows.map((row) => row.subjectId)
  },

  // reverse of the token's global-role claim: your identity store.
  resolveGlobalRoleMembers: async (role) => {
    const accounts = await Account.query().whereJsonSuperset('global_roles', [role])
    return accounts.map((account) => ({ type: 'user', id: account.id }))
  },
})

Each returns bare ids or { type, id } references. Both are optional — and an unconfigured one contributes nothing rather than failing, so a subjectsWithRole call simply returns a shorter list. Wire the reverse seam for every source you wired forwards; Roles covers the pairing and the failure mode.

roleGrants — role → permissions, no seedCopy Anchor Link

A role → permissions/wildcards map applied to the user's effective roles at check time, without seeding the store. Union it into permission checks to grant a role its abilities purely from config:

defineConfig({
  roleGrants: {
    editor: ['posts.*', 'comments.moderate'],
    auditor: ['audit.*'],
  },
})

Now a user with the editor role (from any of the three sources) passes can('posts.edit') even though nothing was written to authz_role_permission.

Standalone schema helpersCopy Anchor Link

With autoCreateSchema: false (recommended for production) the store no longer creates its tables — you own the schema through a Lucid migration. The package exports the exact same DDL the store would otherwise run, so the two paths never drift:

import { BaseSchema } from '@adonisjs/lucid/schema'
import { createAuthzTables, dropAuthzTables } from '@adonis-agora/authz'

export default class extends BaseSchema {
  async up() {
    this.defer((db) => createAuthzTables(db))
  }

  async down() {
    this.defer((db) => dropAuthzTables(db))
  }
}

• createAuthzTables(db, { tables? }) — idempotent (CREATE TABLE IF NOT EXISTS), dialect-aware (Postgres / MySQL / SQLite). Safe to call from a migration up(). MySQL 8 has no CREATE INDEX IF NOT EXISTS (a MariaDB-only extension), so there the index DDL drops the clause and swallows the duplicate-key error — same idempotency, no version-sniffing. Verified against a real MySQL 8.
• It also upgrades a pivot created by an earlier version: the source column of role sources is added non-destructively. Widening that table's primary key is a manual, one-off step (SQL in the linked section).
• dropAuthzTables(db, { tables? }) — idempotent (DROP TABLE IF EXISTS), child-first, for the migration down().
• AUTHZ_TABLES — the default table names (authz_roles, authz_permissions, authz_role_permission, authz_subject_role, authz_subject_permission).

Pass matching tables overrides to both the store config and these helpers so they agree:

import { AUTHZ_TABLES } from '@adonis-agora/authz'

const tables = { ...AUTHZ_TABLES, roles: 'rbac_roles' }

// config/authz.ts → stores.lucid({ autoCreateSchema: false, tables })
// migration       → createAuthzTables(db, { tables })

Sync catalogCopy Anchor Link

Declare roles → permissions to seed with node ace authz:sync:

defineConfig({
  catalog: {
    permissions: ['system.manage'],
    roles: {
      editor: ['posts.*'],
      viewer: ['posts.view', 'comments.view'],
    },
  },
})