@zvk/auth-rbac

Framework-agnostic auth, organization membership, role, entitlement, and approval guard helpers for ZVK applications.

import { createAuthGuardFactory, createPermissionContextAdapter, requireOrg, requireRole } from "@zvk/auth-rbac";
import { hasEntitlement, hasRole, mergeEntitlements } from "@zvk/auth-rbac/permissions";
import { createRolePermissionCases } from "@zvk/auth-rbac/test-utils";

The root package and all subpaths are SSR-safe. They do not import React, Next.js, Supabase, Drizzle, browser APIs, or app database code.

Apps provide auth clients and data sources. This package owns reusable guard shapes and failure envelopes, not app tables or redirect policy.

Use createAuthGuardFactory when an app wants to bind an auth-client provider and organization data source once, then map guard Result values into its own action, route, or page envelopes. Use createPermissionContextAdapter when UI, action, or test contexts have an app-owned shape such as { authed, organizationId, role } but should still reuse package role and entitlement checks. The adapter maps that context into structural OrgMembership values; applications still own the allowed role sets, product copy, and redirect behavior.

Use @zvk/auth-rbac/test-utils for framework-neutral guard fakes and permission matrix case builders. The package returns case data; applications keep their test assertion library, fixture IDs, allowed role sets, and product-specific permission policies.

Repo Skill

This repository keeps the Codex usage and maintenance skill at:

.codex/skills/use-zvk-auth-rbac/SKILL.md

App-Owned Responsibilities

Applications still own route redirects, app schemas, database queries, RLS, billing policy, generated database types, and business-specific permission decisions.