@auth-gate/rbac 0.9.3 → 0.11.0

package/README.md

@@ -0,0 +1,117 @@
+<p align="center">
+  <img src="icon.png" alt="AuthGate" width="120" height="120" />
+</p>
+
+# @auth-gate/rbac
+
+RBAC as code for [AuthGate](https://www.authgate.dev) — define resources, roles, and permissions in TypeScript and sync them with a single CLI command.
+
+## Installation
+
+```bash
+npm install @auth-gate/rbac
+```
+
+## Quick Start
+
+### 1. Generate a starter config
+
+```bash
+npx @auth-gate/rbac init
+```
+
+### 2. Define your RBAC config
+
+```ts
+// 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
+
+```bash
+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.
+
+```ts
+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
+
+```ts
+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

package/dist/index.d.cts

@@ -94,30 +94,28 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
 type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
 /**
  * Compile-time constraint: if more than one role has `isDefault: true`,
- * intersect those roles' `isDefault` with an error string so TypeScript
- * produces a descriptive message.
+ * produce a descriptive error at the `roles` level naming the conflicting roles.
  *
- * Error reads: Type 'true' is not assignable to type '"ERROR: ..."'.
+ * The error string includes the names of all roles that have `isDefault: true`
+ * so the developer knows exactly which roles to fix.
  */
 type ValidateSingleDefault<T> = T extends {
     roles: infer Roles;
 } ? IsUnion<DefaultRoleKeys<Roles>> extends true ? {
-    roles: {
-        [K in DefaultRoleKeys<Roles> & keyof Roles]: {
-            isDefault: "ERROR: Only one role may have isDefault: true";
-        };
-    };
+    roles: `ERROR: multiple roles have isDefault: true ("${DefaultRoleKeys<Roles> & string}"). Only one role may be the default`;
 } : {} : {};
 /** Extract valid action string literals from a resource config. */
 type ValidActions<R> = R extends {
     actions: readonly (infer U)[];
 } ? U & string : never;
+/** Extract action keys that are NOT declared in the resource config. */
+type InvalidActions<Actions, Res extends ResourceConfig> = Exclude<keyof Actions & string, ValidActions<Res>>;
 /**
  * Compile-time constraint: validates grant resource/action keys against
  * declared resources at the type level.
  *
  * - **Invalid resource key** → descriptive error naming the resource.
- * - **Invalid action key** → descriptive error listing valid actions.
+ * - **Invalid action key** → descriptive error naming the specific invalid key(s).
  * - **Valid grants** → passes through original types transparently.
  *
  * Used as `T & ValidateConfig<T>` in the `defineRbac()` parameter type.
@@ -136,7 +134,7 @@ type ValidateConfig<T> = T extends {
             grants: {
                 [ResK in keyof G]: ResK extends keyof R ? keyof G[ResK] extends ValidActions<R[ResK & keyof R]> ? {
                     [ActK in keyof G[ResK]]: G[ResK][ActK];
-                } : `ERROR: invalid action(s) in "${ResK & string}" grants. Valid actions: ${ValidActions<R[ResK & keyof R]>}` : `ERROR: resource "${ResK & string}" is not declared in resources`;
+                } : `ERROR: unknown action(s) "${InvalidActions<G[ResK], R[ResK & keyof R]>}" in "${ResK & string}" grants. Valid actions: ${ValidActions<R[ResK & keyof R]>}` : `ERROR: resource "${ResK & string}" is not declared in resources`;
             };
         } : Roles[RK];
     };

package/dist/index.d.ts

@@ -94,30 +94,28 @@ type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (
 type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
 /**
  * Compile-time constraint: if more than one role has `isDefault: true`,
- * intersect those roles' `isDefault` with an error string so TypeScript
- * produces a descriptive message.
+ * produce a descriptive error at the `roles` level naming the conflicting roles.
  *
- * Error reads: Type 'true' is not assignable to type '"ERROR: ..."'.
+ * The error string includes the names of all roles that have `isDefault: true`
+ * so the developer knows exactly which roles to fix.
  */
 type ValidateSingleDefault<T> = T extends {
     roles: infer Roles;
 } ? IsUnion<DefaultRoleKeys<Roles>> extends true ? {
-    roles: {
-        [K in DefaultRoleKeys<Roles> & keyof Roles]: {
-            isDefault: "ERROR: Only one role may have isDefault: true";
-        };
-    };
+    roles: `ERROR: multiple roles have isDefault: true ("${DefaultRoleKeys<Roles> & string}"). Only one role may be the default`;
 } : {} : {};
 /** Extract valid action string literals from a resource config. */
 type ValidActions<R> = R extends {
     actions: readonly (infer U)[];
 } ? U & string : never;
+/** Extract action keys that are NOT declared in the resource config. */
+type InvalidActions<Actions, Res extends ResourceConfig> = Exclude<keyof Actions & string, ValidActions<Res>>;
 /**
  * Compile-time constraint: validates grant resource/action keys against
  * declared resources at the type level.
  *
  * - **Invalid resource key** → descriptive error naming the resource.
- * - **Invalid action key** → descriptive error listing valid actions.
+ * - **Invalid action key** → descriptive error naming the specific invalid key(s).
  * - **Valid grants** → passes through original types transparently.
  *
  * Used as `T & ValidateConfig<T>` in the `defineRbac()` parameter type.
@@ -136,7 +134,7 @@ type ValidateConfig<T> = T extends {
             grants: {
                 [ResK in keyof G]: ResK extends keyof R ? keyof G[ResK] extends ValidActions<R[ResK & keyof R]> ? {
                     [ActK in keyof G[ResK]]: G[ResK][ActK];
-                } : `ERROR: invalid action(s) in "${ResK & string}" grants. Valid actions: ${ValidActions<R[ResK & keyof R]>}` : `ERROR: resource "${ResK & string}" is not declared in resources`;
+                } : `ERROR: unknown action(s) "${InvalidActions<G[ResK], R[ResK & keyof R]>}" in "${ResK & string}" grants. Valid actions: ${ValidActions<R[ResK & keyof R]>}` : `ERROR: resource "${ResK & string}" is not declared in resources`;
             };
         } : Roles[RK];
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-gate/rbac",
-  "version": "0.9.3",
+  "version": "0.11.0",
   "type": "module",
   "exports": {
     ".": {
@@ -16,13 +16,14 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "icon.png"
   ],
   "dependencies": {
     "chalk": "^5.4.0",
     "dotenv": "^17.2.4",
     "jiti": "^2.4.0",
-    "@auth-gate/core": "0.9.3"
+    "@auth-gate/core": "0.11.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",