@auth-gate/rbac

RBAC as code for AuthGate — define resources, roles, and permissions in TypeScript and sync them with a single CLI command.

Installation

npm install @auth-gate/rbac

Quick Start

1. Generate a starter config

npx @auth-gate/rbac init

2. Define your RBAC config

// authgate.rbac.ts
import { defineRbac } from "@auth-gate/rbac";

export const rbac = defineRbac({
  resources: {
    documents: { actions: ["read", "write", "delete"] },
    billing: { actions: ["read", "manage"] },
  },
  roles: {
    admin: {
      name: "Admin",
      grants: {
        documents: { read: true, write: true, delete: true },
        billing: { read: true, manage: true },
      },
    },
    member: {
      name: "Member",
      isDefault: true,
      grants: {
        documents: { read: true, write: true },
      },
    },
    viewer: {
      name: "Viewer",
      grants: {
        documents: { read: true },
      },
    },
  },
});

3. Sync to AuthGate

export AUTHGATE_API_KEY=ag_...
export AUTHGATE_BASE_URL=https://www.authgate.dev

npx @auth-gate/rbac diff   # Preview changes
npx @auth-gate/rbac sync   # Apply changes

Type Safety

defineRbac() validates grants at compile time. Referencing an undeclared resource or action is a TypeScript error.

rbac.resources.documents.key           // "documents"
rbac.resources.documents.actions.read  // "documents:read"
rbac.roles.admin.key                   // "admin"
rbac.permissions.documents.write       // "documents:write"

CLI Commands

| Command | Description | |---------|-------------| | npx @auth-gate/rbac init | Generate a starter config file | | npx @auth-gate/rbac diff | Preview changes without applying | | npx @auth-gate/rbac sync | Apply changes to AuthGate | | npx @auth-gate/rbac pull | Pull server state into a local config |

Features

• Type-safe grants — compile-time validation of resources, actions, and roles
• Role inheritance — roles can inherit permissions from other roles via inherits
• Rename migrations — rename roles without losing assignments via renamedFrom
• Conditional grants — attach condition functions to grant values
• Default role — mark one role as isDefault: true for new org members
• Diff before sync — preview all changes before they're applied
• Coexists with dashboard — roles created in the dashboard are preserved

Runtime Role Management

import { createRoleManagement } from "@auth-gate/rbac";

const roles = createRoleManagement({
  apiKey: process.env.AUTHGATE_API_KEY!,
  baseUrl: process.env.AUTHGATE_BASE_URL!,
});

await roles.list();
await roles.create({ key: "editor", name: "Editor", permissions: ["documents:read", "documents:write"] });
await roles.update("editor", { name: "Content Editor" });
await roles.delete("editor");

License

MIT