Convex Authz

@djpanda/convex-authz

A comprehensive, production-ready authorization component for Convex featuring RBAC, ABAC, and ReBAC with O(1) indexed lookups, inspired by Google Zanzibar.

Features

Terminology

Installation

npm install @djpanda/convex-authz

Quick Start

1. Register the Component

// convex/convex.config.ts
import { defineApp } from "convex/server";
import authz from "@djpanda/convex-authz/convex.config";

const app = defineApp();
app.use(authz);

export default app;

2. Define Your Permissions and Roles

// convex/authz.ts
import { Authz, definePermissions, defineRoles } from "@djpanda/convex-authz";
import { components } from "./_generated/api";

// Step 1: Define permissions
const permissions = definePermissions({
  documents: {
    create: true,
    read: true,
    update: true,
    delete: true,
  },
  settings: {
    view: true,
    manage: true,
  },
});

// Step 2: Define roles
const roles = defineRoles(permissions, {
  admin: {
    documents: ["create", "read", "update", "delete"],
    settings: ["view", "manage"],
  },
  editor: {
    documents: ["create", "read", "update"],
    settings: ["view"],
  },
  viewer: {
    documents: ["read"],
  },
});

// Step 3: Create the authz client
export const authz = new Authz(components.authz, { permissions, roles, tenantId: "my-app" });

Role inheritance and composition

Roles can be defined in terms of other roles to avoid repeating permission lists:

• **inherits** – one parent role; effective permissions = parent’s permissions ∪ this role’s direct permissions.
• **includes** – multiple roles; effective permissions = union of all included roles’ permissions ∪ this role’s direct permissions.

Example with inheritance (admin > editor > viewer):

const roles = defineRoles(permissions, {
  viewer: { documents: ["read"] },
  editor: { inherits: "viewer", documents: ["create", "update"] },
  admin: { inherits: "editor", documents: ["delete"], settings: ["manage"] },
});

Example with composition (combine roles):

const roles = defineRoles(permissions, {
  editor: { documents: ["create", "read", "update"] },
  billing_admin: { billing: ["view", "manage"] },
  billing_manager: { includes: ["editor", "billing_admin"], settings: ["view"] },
});

Note: inherits and includes are reserved keys in role definitions; do not use them as permission resource names.

3. Use in Your Functions

// convex/documents.ts
import { mutation, query } from "./_generated/server";
import { v } from "convex/values";
import { authz } from "./authz";
import { getAuthUserId } from "@convex-dev/auth/server";

export const updateDocument = mutation({
  args: { docId: v.id("documents"), content: v.string() },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    
    // Check permission (throws if denied)
    await authz.require(ctx, userId, "documents:update");
    
    // Or with scope
    await authz.require(ctx, userId, "documents:update", {
      type: "document",
      id: args.docId,
    });
    
    // Proceed with update...
  },
});

Unified Authz v2

v2 consolidates everything into a single Authz class. If you previously used IndexedAuthz, just rename it — the constructor signature is identical.

What changed

• One class: Authz replaces both the original Authz and IndexedAuthz. O(1) reads via pre-computed effective tables are now the default.
• ReBAC on Authz: hasRelation, addRelation, and removeRelation are available directly on every Authz instance.
• ABAC policy types: Policies accept a type field ("static" or "deferred"). In the current implementation, both types are evaluated at read-time when can() is called — Convex mutations cannot call queries, so write-time evaluation is not possible. The type field is reserved for future optimization but currently has no behavioral difference.
• **canWithContext()**: Check deferred ABAC policies that need runtime context (e.g. IP address, time of day).
• **recomputeUser()**: Rebuild a user's effective-permissions table on demand — useful after a schema change or post-deploy migration.
• **withTenant()**: Get a scoped copy of the client bound to a different tenant for cross-tenant admin operations.

ReBAC example

// Add a relationship
await authz.addRelation(ctx, { type: "user", id: userId }, "member", { type: "team", id: teamId });

// Check a relationship
const isMember = await authz.hasRelation(ctx, { type: "user", id: userId }, "member", { type: "team", id: teamId });

// Remove a relationship
await authz.removeRelation(ctx, { type: "user", id: userId }, "member", { type: "team", id: teamId });

ReBAC → Permission Bridge

Use defineRelationPermissions to automatically grant permissions when relationships are created:

import { defineRelationPermissions } from "@djpanda/convex-authz";

const authz = new Authz(components.authz, {
  permissions, roles, tenantId: "my-app",
  relationPermissions: defineRelationPermissions({
    "document:viewer": ["documents:read"],
    "document:editor": ["documents:read", "documents:update"],
    "document:owner": ["documents:read", "documents:update", "documents:delete"],
  }),
});

// Adding a relation automatically grants scoped permissions
await authz.addRelation(ctx, { type: "user", id: userId }, "editor", { type: "document", id: docId });

// can() now checks relation-derived permissions — no separate hasRelation() needed
const canUpdate = await authz.can(ctx, userId, "documents:update", { type: "document", id: docId }); // true

// Removing the relation revokes the permissions
await authz.removeRelation(ctx, { type: "user", id: userId }, "editor", { type: "document", id: docId });

ABAC example

// Policies are always evaluated at read-time when can() is called.
// The optional type field ("static" | "deferred") is reserved for future use
// and currently has no behavioral effect.
const policies = definePolicies({
  "documents:read": {
    condition: (ctx) => ctx.getAttribute("verified") === true,
    message: "Only verified users can read documents",
  },
  "billing:export": {
    condition: (ctx) => {
      const hour = new Date().getUTCHours();
      return hour >= 9 && hour <= 17;
    },
    message: "Billing exports only during business hours",
  },
});

// Use canWithContext() when request context is available
const allowed = await authz.canWithContext(ctx, userId, "documents:read", undefined, {
  ipAllowlisted: true,
});

Post-deploy rebuild

// Rebuild a single user's effective permissions after upgrading
await authz.recomputeUser(ctx, userId);

Cross-tenant operations

const otherTenantAuthz = authz.withTenant("other-tenant-id");
const allowed = await otherTenantAuthz.can(ctx, userId, "documents:read");

Migration guide: IndexedAuthz → Authz

Note: IndexedAuthz is no longer exported in v2. The import below will fail — just replace it with Authz.

// Before (v1) — this import no longer works in v2
// import { IndexedAuthz } from "@djpanda/convex-authz";
// const authz = new IndexedAuthz(components.authz, { permissions, roles, tenantId: "my-app" });

// After (v2) — same constructor, just rename the class
import { Authz } from "@djpanda/convex-authz";
const authz = new Authz(components.authz, { permissions, roles, tenantId: "my-app" });

After upgrading, run recomputeUser() for each existing user to backfill the effective-permissions table:

// one-time migration mutation
export const backfillEffectivePermissions = mutation({
  args: {},
  handler: async (ctx) => {
    const users = await ctx.db.query("users").collect();
    for (const user of users) {
      await authz.recomputeUser(ctx, String(user._id));
    }
  },
});

React integration

The package provides React hooks and a PermissionGate component so your UI can check permissions and roles reactively. Your app must expose Convex queries that wrap the Authz component (e.g. checkPermission, getUserRoles). The hooks call those queries via Convex’s useQuery, so permission and role changes stay up to date without polling.

1. Expose Convex queries

Define queries that delegate to your authz client, for example:

// convex/app.ts (or similar)
import { query } from "./_generated/server";
import { v } from "convex/values";
import { authz } from "./authz";

export const checkPermission = query({
  args: {
    userId: v.string(),
    permission: v.string(),
    scope: v.optional(v.object({ type: v.string(), id: v.string() })),
  },
  handler: async (ctx, args) => {
    return authz.can(ctx, args.userId, args.permission, args.scope);
  },
});

export const getUserRoles = query({
  args: {
    userId: v.string(),
    scope: v.optional(v.object({ type: v.string(), id: v.string() })),
  },
  handler: async (ctx, args) => {
    return authz.getUserRoles(ctx, args.userId, args.scope);
  },
});

2. Wrap your app with AuthzProvider

Pass your Convex query refs (and optionally a default user id) to the provider:

import { AuthzProvider } from "@djpanda/convex-authz/react";
import { api } from "./convex/_generated/api";

<AuthzProvider
  queryRefs={{
    checkPermission: api.app.checkPermission,
    getUserRoles: api.app.getUserRoles,
  }}
  defaultUserId={currentUserId}  // optional; hooks can pass userId in options
>
  <App />
</AuthzProvider>

3. Use hooks and PermissionGate

• useCanUser(permission, options?) — Returns { allowed, isLoading, error }. Options: { userId?, scope? }. Uses defaultUserId from the provider when userId is omitted.
• useUserRoles(options?) — Returns { roles, isLoading, error }. Options: { userId?, scope? }.
• useRequirePermission(permission, options?) — Throws when the user is not allowed (use an error boundary to show a denied state).
• PermissionGate — Renders children when allowed, fallback when denied, and loadingFallback (optional) while loading.

import {
  useCanUser,
  useUserRoles,
  useRequirePermission,
  PermissionGate,
} from "@djpanda/convex-authz/react";

function DocumentList() {
  const { allowed, isLoading } = useCanUser("documents:read");

  if (isLoading) return <Spinner />;
  if (!allowed) return <p>You cannot view documents.</p>;
  return <div>{/* list */}</div>;
}

function AdminPanel() {
  useRequirePermission("settings:manage"); // throws if denied; wrap in error boundary
  return <div>Admin content</div>;
}

function EditButton({ docId }: { docId: string }) {
  return (
    <PermissionGate
      permission="documents:update"
      scope={{ type: "document", id: docId }}
      fallback={<span>No access</span>}
      loadingFallback={<span>Checking…</span>}
    >
      <button>Edit</button>
    </PermissionGate>
  );
}

Convex’s reactivity ensures that when permissions or roles change on the backend, the hooks and PermissionGate re-run and the UI updates automatically.

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           @djpanda/convex-authz                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────────────┐   │
│  │      RBAC        │  │      ABAC        │  │         ReBAC            │   │
│  │  Role-Based      │  │  Attribute-Based │  │  Relationship-Based      │   │
│  │  Access Control  │  │  Access Control  │  │  Access Control          │   │
│  │                  │  │                  │  │                          │   │
│  │  • Roles         │  │  • User attrs    │  │  • Tuples (S, R, O)      │   │
│  │  • Permissions   │  │  • Policies      │  │  • Graph traversal       │   │
│  │  • Scopes        │  │  • Conditions    │  │  • Inheritance           │   │
│  └──────────────────┘  └──────────────────┘  └──────────────────────────┘   │
│           │                    │                         │                  │
│           ▼                    ▼                         ▼                  │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    O(1) Indexed Permission Cache                     │   │
│  │                                                                      │   │
│  │   effectivePermissions  │  effectiveRoles  │  effectiveRelationships │   │
│  │   [user, perm, scope]   │  [user, role]    │  [subject, rel, object] │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

RBAC (Role-Based Access Control)

Assigning Roles

// Global role
await authz.assignRole(ctx, userId, "admin");

// Scoped role (e.g., admin of a specific team)
await authz.assignRole(ctx, userId, "admin", {
  type: "team",
  id: "team_123",
});

// With expiration (24 hours)
await authz.assignRole(ctx, userId, "admin", undefined, Date.now() + 86400000);

Revoking Roles

await authz.revokeRole(ctx, userId, "admin");

// Scoped
await authz.revokeRole(ctx, userId, "admin", { type: "team", id: "team_123" });

Checking Permissions

// Boolean check
const canEdit = await authz.can(ctx, userId, "documents:update");

// Throws if denied
await authz.require(ctx, userId, "documents:update");

// With scope
const canEditTeamDocs = await authz.can(ctx, userId, "documents:update", {
  type: "team",
  id: "team_123",
});

Checking Roles

const isAdmin = await authz.hasRole(ctx, userId, "admin");

// Scoped
const isTeamAdmin = await authz.hasRole(ctx, userId, "admin", {
  type: "team",
  id: "team_123",
});

Wildcard and pattern-matching permissions

Permission checks and overrides support wildcard patterns so you can grant or deny whole families of permissions in one go.

Pattern format: resource:action. Either resource or action (or both) may be *:

Checking: When you call can(ctx, userId, "documents:read") or require(ctx, userId, "documents:read"), the backend treats any stored role or override that matches that permission as granting it. So if the user has a role with documents:* or an override *:read, they are allowed for documents:read.

Allocation: You can pass a pattern into grantPermission and denyPermission:

// Grant all document actions
await authz.grantPermission(ctx, userId, "documents:*", undefined, "Full document access");

// Deny read on any resource
await authz.denyPermission(ctx, userId, "*:read", undefined, "Read access revoked");

Role definitions: When the component evaluates permissions, it matches the requested permission against each role’s permission list using the same pattern rules. So if a role’s permissions include "documents:*" (in the flattened role–permission map), then can(ctx, userId, "documents:read") is allowed. With defineRoles you typically list concrete actions per resource (e.g. documents: ["read", "update"]); to use patterns in roles you would supply a role-permission map that includes pattern strings for that role.

Client-side helper: To test whether a pattern matches a permission without calling the backend, use the exported helper:

import { matchesPermissionPattern } from "@djpanda/convex-authz";

matchesPermissionPattern("documents:read", "documents:*"); // true
matchesPermissionPattern("documents:read", "*:read");      // true
matchesPermissionPattern("settings:read", "documents:*"); // false

The same wildcard behavior applies to all permission checks.

Getting User Roles

const roles = await authz.getUserRoles(ctx, userId);
// Returns: [{ role: "admin", scopeKey: "global" }, { role: "editor", scopeKey: "team:123", scope: { type: "team", id: "123" } }]

Bulk operations and offboarding

For large-scale or enterprise workflows, the API supports bulk permission checks (up to 100 permissions) and role updates (up to 20 roles) in a single call.

Bulk permission check (canAny)

Check whether the user has any of the given permissions in one round-trip:

const allowed = await authz.canAny(ctx, userId, [
  "documents:read",
  "documents:update",
  "documents:delete",
], scope);
// true if the user has at least one of these permissions

Bulk role assign and revoke

Assign or revoke multiple roles for one user in a single transaction:

// Assign multiple roles at once (max 20 per call)
const { assigned, assignmentIds } = await authz.assignRoles(ctx, userId, [
  { role: "admin" },
  { role: "editor", scope: { type: "team", id: "team_1" } },
  { role: "viewer", scope: { type: "org", id: "org_1" }, expiresAt: Date.now() + 86400000 },
], actorId);

// Revoke multiple roles at once (max 20 per call)
const { revoked } = await authz.revokeRoles(ctx, userId, [
  { role: "editor", scope: { type: "team", id: "team_1" } },
  { role: "viewer" },
], actorId);

Revoke all roles

Revoke every role for a user (optionally only in a given scope):

const count = await authz.revokeAllRoles(ctx, userId);
const countScoped = await authz.revokeAllRoles(ctx, userId, { type: "team", id: "team_1" }, actorId);

Full user offboarding

Remove all roles, permission overrides, attributes, and optionally ReBAC relationships for a user in one call (optionally scoped). Also clears indexed effectiveRoles, effectivePermissions, and effectiveRelationships when present:

const result = await authz.offboardUser(ctx, userId, {
  scope: { type: "org", id: "org_1" },  // optional: only remove data in this scope
  actorId: "system",
  removeAttributes: true,   // default true
  removeOverrides: true,    // default true
  removeRelationships: true, // default true when no scope (full offboard)
});
// result: { rolesRevoked, overridesRemoved, attributesRemoved, relationshipsRemoved, effectiveRolesRemoved, effectivePermissionsRemoved, effectiveRelationshipsRemoved }

When scope is omitted, the call performs a full deprovision: all roles, overrides, attributes, and all ReBAC relationships where the user is the subject are removed. When scope is provided, only data in that scope is removed and relationships are left unchanged.

User deprovisioning (full wipe)

For security incident response, enterprise offboarding, or single-button deactivation, use deprovisionUser to atomically wipe all roles, attributes, relationships, and permission overrides for a user (no scope, no options):

const result = await authz.deprovisionUser(ctx, userId, {
  actorId: "security-team",
  enableAudit: true,
});
// result: { rolesRevoked, overridesRemoved, attributesRemoved, relationshipsRemoved, effectiveRolesRemoved, effectivePermissionsRemoved, effectiveRelationshipsRemoved }

Bulk arrays are limited per call: permissions in canAny up to 100 items, roles in assignRoles / revokeRoles up to 20 items. The client and component validate and throw a clear error if exceeded.

ABAC (Attribute-Based Access Control)

Setting User Attributes

await authz.setAttribute(ctx, userId, "department", "engineering");
await authz.setAttribute(ctx, userId, "clearanceLevel", 5);
await authz.setAttribute(ctx, userId, "location", { country: "US", state: "CA" });

Getting Attributes

const attributes = await authz.getUserAttributes(ctx, userId);
// Returns: [{ key: "department", value: "engineering" }, { key: "clearanceLevel", value: 5 }]

Defining Policies

The condition function may return either a boolean or a Promise<boolean>, so you can use async logic (e.g. querying the database or calling external APIs).

import { definePolicies, evaluatePolicyCondition } from "@djpanda/convex-authz";

const policies = definePolicies({
  "documents:update": {
    // User can update if they own the document (sync)
    condition: (ctx) => ctx.resource?.ownerId === ctx.subject.userId,
    message: "Only document owners can update",
  },
  "reports:view": {
    // Only engineering department with clearance >= 3 (sync)
    condition: (ctx) => 
      ctx.subject.attributes.department === "engineering" &&
      (ctx.subject.attributes.clearanceLevel as number) >= 3,
    message: "Requires engineering department with clearance level 3+",
  },
  "documents:delete": {
    // Async: e.g. check external service or fetch extra data
    condition: async (ctx) => {
      const doc = await getDocument(ctx.resource?.id);
      return doc != null && doc.ownerId === ctx.subject.userId;
    },
    message: "Only document owners can delete",
  },
});

const authz = new Authz(components.authz, { permissions, roles, policies, tenantId: "my-app" });

When you evaluate a policy (e.g. after RBAC allows), always await the condition so both sync and async policies work. Use evaluatePolicyCondition to normalize to a Promise:

const policy = policies["documents:update"];
if (policy) {
  const allowed = await evaluatePolicyCondition(policy.condition, policyCtx);
  if (!allowed) throw new Error(policy.message ?? "Permission denied");
}

Policy Context

Policies receive a context object with:

interface PolicyContext {
  subject: {
    userId: string;
    roles: string[];
    attributes: Record<string, unknown>;
  };
  resource?: {
    type: string;
    id: string;
    [key: string]: unknown; // Resource data
  };
  action: string; // The permission being checked
  environment?: {
    timestamp: number;
    ip?: string;
  };
  hasRole: (role: string) => boolean;
  hasAttribute: (key: string) => boolean;
  getAttribute: <T = unknown>(key: string, defaultValue?: T) => T | undefined;
}

API note: Existing sync conditions remain valid. There is no breaking change; only the return type is widened to allow Promise<boolean> for async policies.

ReBAC (Relationship-Based Access Control)

ReBAC enables access control based on relationships between entities, perfect for hierarchical systems like CRMs, document sharing, and organizational structures.

Relationship Model

Relationships are stored as tuples: (subject, relation, object)

user:alice  ──member──►  team:sales
team:sales  ──owner──►   account:acme
account:acme ──parent──► deal:big_deal

Adding Relationships

// Use the Authz client — NOT direct component calls
// User is member of team
await authz.addRelation(ctx, { type: "user", id: "alice" }, "member", { type: "team", id: "sales" });

// Team owns account
await authz.addRelation(ctx, { type: "team", id: "sales" }, "owner", { type: "account", id: "acme" });

Checking Direct Relationships

// Use the Authz client — NOT direct component calls
const isMember = await authz.hasRelation(ctx, { type: "user", id: "alice" }, "member", { type: "team", id: "sales" });
// Returns: true

// To remove a relationship
await authz.removeRelation(ctx, { type: "user", id: "alice" }, "member", { type: "team", id: "sales" });

Relationship Traversal (Inherited Access)

The real power of ReBAC is checking access through relationship chains:

// Define how permissions flow through relationships
const traversalRules = {
  // A deal viewer is anyone who can view the parent account
  "deal:viewer": [
    { through: "account", via: "parent", inherit: "viewer" }
  ],
  // An account viewer is any member of the owning team
  "account:viewer": [
    { through: "team", via: "owner", inherit: "member" }
  ],
};

// Graph traversal is available via the component query directly
// Check: Can alice view big_deal?
const result = await ctx.runQuery(components.authz.rebac.checkRelationWithTraversal, {
  subjectType: "user",
  subjectId: "alice",
  relation: "viewer",
  objectType: "deal",
  objectId: "big_deal",
  traversalRules,
  maxDepth: 5,
});

// Returns:
// {
//   allowed: true,
//   path: [
//     "account:acme -[parent]-> deal:big_deal",
//     "team:sales -[owner]-> account:acme",
//     "user:alice -[member]-> team:sales"
//   ],
//   reason: "Access via relationship chain"
// }

Traversal uses a maxDepth limit (default 5) and tracks visited (objectType, objectId, relation) nodes so that circular relationships do not cause infinite loops.

CRM Example

// Setup CRM hierarchy using the Authz client
const setupCRM = async (ctx) => {
  // Sales rep Alice is on sales team
  await authz.addRelation(ctx, { type: "user", id: "alice" }, "member", { type: "team", id: "sales" });

  // Sales team owns Acme Corp account
  await authz.addRelation(ctx, { type: "team", id: "sales" }, "owner", { type: "account", id: "acme_corp" });

  // Acme Corp has a big deal
  await authz.addRelation(ctx, { type: "account", id: "acme_corp" }, "parent", { type: "deal", id: "big_deal" });

  // Now Alice can access the deal through the relationship chain!
};

O(1) Indexed Lookups

For high-performance production use, the indexed system pre-computes permissions for instant lookups.

Using the Indexed API

import { Authz } from "@djpanda/convex-authz";
import { components } from "./_generated/api";

const authz = new Authz(components.authz, { permissions, roles, tenantId: "my-app" });

// O(1) permission check - single index lookup
const canEdit = await authz.can(ctx, userId, "documents:update");

// O(1) role check
const isAdmin = await authz.hasRole(ctx, userId, "admin");

// O(1) relationship check
const isMember = await authz.hasRelation(ctx, { type: "user", id: userId }, "member", { type: "team", id: "sales" });

How It Works

Traditional (O(n)):                    Indexed (O(1)):
┌──────┐                               ┌──────┐
│ User │                               │ User │
└──┬───┘                               └──┬───┘
   │                                      │
   ▼                                      ▼
┌──────────┐                           ┌─────────────────────────────┐
│ Get Roles│ ◄── Query                 │ Index Lookup:               │
└──┬───────┘                           │ effectivePermissions        │
   │                                   │ [userId, permission, scope] │
   ▼                                   └─────────────────────────────┘
┌───────────────┐                                  │
│ Expand Perms  │ ◄── Loop                         ▼
└──┬────────────┘                              true/false
   │
   ▼
┌──────────────┐
│ Check Each   │ ◄── Loop
│ Permission   │
└──┬───────────┘
   │
   ▼
true/false

Trade-offs

Use Indexed for production workloads with many permission checks.

Audit Logging

All authorization changes are logged for compliance and debugging.

Automatic Logging

The following actions are automatically logged:

• role_assigned - When a role is assigned
• role_revoked - When a role is revoked
• permission_granted - When a direct permission is granted
• permission_denied - When a permission is explicitly denied
• attribute_set - When a user attribute is set
• attribute_removed - When a user attribute is removed
• permission_check - (Optional) When permissions are checked

Querying the Audit Log

Without pagination options, getAuditLog returns a simple array (optional limit, default 100):

// Get all logs for a user
const logs = await authz.getAuditLog(ctx, {
  userId: "user_123",
  limit: 50,
});

// Get logs by action type
const roleChanges = await authz.getAuditLog(ctx, {
  action: "role_assigned",
  limit: 100,
});

For scalable browsing, use cursor-based pagination by passing numItems (and optionally cursor for the next page). The return value is then { page, isDone, continueCursor }:

// First page
const result = await authz.getAuditLog(ctx, { numItems: 50 });
if (!Array.isArray(result)) {
  console.log(result.page);
  if (!result.isDone) {
    // Next page
    const next = await authz.getAuditLog(ctx, {
      numItems: 50,
      cursor: result.continueCursor,
    });
  }
}

Log Entry Structure

{
  _id: "...",
  timestamp: 1704672000000,
  actorId: "admin_user",  // Who made the change
  action: "role_assigned",
  userId: "target_user",  // Who was affected
  details: {
    role: "editor",
    scope: { type: "team", id: "team_123" },
  },
}

Permission Overrides

Grant or deny specific permissions that override role-based assignments.

Granting Permissions

// Grant a permission directly (bypasses role checks)
await authz.grantPermission(ctx, userId, "documents:delete", undefined, "Temporary access for migration");

// With scope
await authz.grantPermission(ctx, userId, "documents:delete", { type: "team", id: "team_123" });

// With expiration
await authz.grantPermission(ctx, userId, "documents:delete", undefined, "Temporary", Date.now() + 3600000);

Denying Permissions

// Deny a permission (even if user has it via role)
await authz.denyPermission(ctx, userId, "documents:delete", undefined, "Access restricted");

Schema Reference

Tables

Indexes

All tables have optimized indexes for common query patterns:

// roleAssignments
.index("by_user", ["userId"])
.index("by_role", ["role"])
.index("by_user_and_role", ["userId", "role"])

// effectivePermissions (O(1) lookup)
.index("by_user_permission_scope", ["userId", "permission", "scopeKey"])

// relationships
.index("by_subject_relation_object", ["subjectType", "subjectId", "relation", "objectType", "objectId"])

API Reference

Authz Client

class Authz<P, R, Policy> {
  // Permission checks
  can(ctx, userId, permission, scope?): Promise<boolean>
  canAny(ctx, userId, permissions: string[], scope?): Promise<boolean>   // bulk: any of N permissions (max 100)
  require(ctx, userId, permission, scope?): Promise<void>
  
  // Role management
  hasRole(ctx, userId, role, scope?): Promise<boolean>
  assignRole(ctx, userId, role, scope?, expiresAt?, actorId?): Promise<string>
  assignRoles(ctx, userId, roles: RoleAssignItem[], actorId?): Promise<{ assigned: number; assignmentIds: string[] }>  // bulk, max 20
  revokeRole(ctx, userId, role, scope?, actorId?): Promise<boolean>
  revokeRoles(ctx, userId, roles: RoleScopeItem[], actorId?): Promise<{ revoked: number }>  // bulk, max 20
  revokeAllRoles(ctx, userId, scope?, actorId?): Promise<number>
  getUserRoles(ctx, userId, scope?): Promise<Role[]>
  getUserPermissions(ctx, userId, scope?): Promise<PermissionResult>

  // Offboarding
  offboardUser(ctx, userId, options?: { scope?, actorId?, removeAttributes?, removeOverrides?, removeRelationships? }): Promise<OffboardResult>
  deprovisionUser(ctx, userId, options?: { actorId?, enableAudit? }): Promise<OffboardResult>  // full wipe: roles, overrides, attributes, relationships
  
  // Attribute management
  setAttribute(ctx, userId, key, value, actorId?): Promise<string>
  removeAttribute(ctx, userId, key, actorId?): Promise<boolean>
  getUserAttributes(ctx, userId): Promise<Attribute[]>
  
  // Permission overrides
  grantPermission(ctx, userId, permission, scope?, reason?, expiresAt?, actorId?): Promise<string>
  denyPermission(ctx, userId, permission, scope?, reason?, expiresAt?, actorId?): Promise<string>
  
  // Audit
  getAuditLog(ctx, options?): Promise<AuditEntry[] | { page: AuditEntry[]; isDone: boolean; continueCursor: string }>
}

Argument validation

All public methods on Authz validate their arguments before calling the component. Invalid inputs throw an Error with a clear message so you can fail fast and fix call sites.

Optional parameters are only validated when present (e.g. omitting scope is valid; passing scope: { type: "", id: "x" } throws).

Inspired by Google Zanzibar

This component implements concepts from Google Zanzibar, Google's global authorization system that powers Google Drive, YouTube, Cloud, and more.

Zanzibar Concepts Implemented

| Zanzibar Concept | Our Implementation | Description | | ---------------

…(truncated)