@auth-gate/rbac 0.8.1 → 0.9.0

package/dist/{chunk-5YEMXO7B.mjs → chunk-ZFKXT2MP.mjs}

@@ -150,6 +150,21 @@ function validateRbacConfig(config) {
       }
     }
   }
+  const defaultRoles = [];
+  for (const key of roleKeys) {
+    const role = roles[key];
+    if (role.isDefault !== void 0 && typeof role.isDefault !== "boolean") {
+      throw new Error(`Role "${key}".isDefault must be a boolean.`);
+    }
+    if (role.isDefault === true) {
+      defaultRoles.push(key);
+    }
+  }
+  if (defaultRoles.length > 1) {
+    throw new Error(
+      `Only one role may have isDefault: true. Found ${defaultRoles.length}: ${defaultRoles.join(", ")}.`
+    );
+  }
   for (const key of roleKeys) {
     const role = roles[key];
     if (role.inherits !== void 0) {
@@ -302,7 +317,7 @@ function hashConditionSource(fn) {
   return createHash("sha256").update(fn.toString()).digest("hex").slice(0, 16);
 }
 function computeRbacDiff(config, server, memberCounts) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
   const resourceOps = [];
   const roleOps = [];
   const conditionOps = [];
@@ -393,6 +408,11 @@ function computeRbacDiff(config, server, memberCounts) {
       if (existingInherits !== configInherits) {
         changes.push("inherits changed");
       }
+      const existingDefault = (_l = existing.isDefault) != null ? _l : false;
+      const configDefault = (_m = role.isDefault) != null ? _m : false;
+      if (existingDefault !== configDefault) {
+        changes.push(`isDefault: ${existingDefault} -> ${configDefault}`);
+      }
       if (changes.length > 0) {
         roleOps.push({ type: "update", key, role, existing, changes });
       }
@@ -402,7 +422,7 @@ function computeRbacDiff(config, server, memberCounts) {
   for (const [key, role] of serverRoleByKey) {
     if (renameMap.has(key)) continue;
     if (role.isActive) {
-      const members = (_l = memberCounts[role.configKey]) != null ? _l : 0;
+      const members = (_n = memberCounts[role.configKey]) != null ? _n : 0;
       if (members > 0) hasDestructive = true;
       roleOps.push({ type: "archive", key, existing: role, assignedMembers: members });
     }
@@ -489,6 +509,9 @@ function formatRbacDiff(diff, dryRun) {
             chalk.dim(`    inherits: [${[...op.role.inherits].join(", ")}]`)
           );
         }
+        if (op.role.isDefault) {
+          lines.push(chalk.dim(`    isDefault: true`));
+        }
       } else if (op.type === "update") {
         lines.push(chalk.yellow(`  ~ UPDATE role "${op.key}"`));
         for (const change of op.changes) {

package/dist/cli.cjs

@@ -170,6 +170,21 @@ function validateRbacConfig(config) {
       }
     }
   }
+  const defaultRoles = [];
+  for (const key of roleKeys) {
+    const role = roles[key];
+    if (role.isDefault !== void 0 && typeof role.isDefault !== "boolean") {
+      throw new Error(`Role "${key}".isDefault must be a boolean.`);
+    }
+    if (role.isDefault === true) {
+      defaultRoles.push(key);
+    }
+  }
+  if (defaultRoles.length > 1) {
+    throw new Error(
+      `Only one role may have isDefault: true. Found ${defaultRoles.length}: ${defaultRoles.join(", ")}.`
+    );
+  }
   for (const key of roleKeys) {
     const role = roles[key];
     if (role.inherits !== void 0) {
@@ -320,7 +335,7 @@ function hashConditionSource(fn) {
   return createHash("sha256").update(fn.toString()).digest("hex").slice(0, 16);
 }
 function computeRbacDiff(config, server, memberCounts) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
   const resourceOps = [];
   const roleOps = [];
   const conditionOps = [];
@@ -411,6 +426,11 @@ function computeRbacDiff(config, server, memberCounts) {
       if (existingInherits !== configInherits) {
         changes.push("inherits changed");
       }
+      const existingDefault = (_l = existing.isDefault) != null ? _l : false;
+      const configDefault = (_m = role.isDefault) != null ? _m : false;
+      if (existingDefault !== configDefault) {
+        changes.push(`isDefault: ${existingDefault} -> ${configDefault}`);
+      }
       if (changes.length > 0) {
         roleOps.push({ type: "update", key, role, existing, changes });
       }
@@ -420,7 +440,7 @@ function computeRbacDiff(config, server, memberCounts) {
   for (const [key, role] of serverRoleByKey) {
     if (renameMap.has(key)) continue;
     if (role.isActive) {
-      const members = (_l = memberCounts[role.configKey]) != null ? _l : 0;
+      const members = (_n = memberCounts[role.configKey]) != null ? _n : 0;
       if (members > 0) hasDestructive = true;
       roleOps.push({ type: "archive", key, existing: role, assignedMembers: members });
     }
@@ -507,6 +527,9 @@ function formatRbacDiff(diff, dryRun) {
             import_chalk.default.dim(`    inherits: [${[...op.role.inherits].join(", ")}]`)
           );
         }
+        if (op.role.isDefault) {
+          lines.push(import_chalk.default.dim(`    isDefault: true`));
+        }
       } else if (op.type === "update") {
         lines.push(import_chalk.default.yellow(`  ~ UPDATE role "${op.key}"`));
         for (const change of op.changes) {
@@ -726,6 +749,7 @@ export const rbac = defineRbac({
     },
     viewer: {
       name: "Viewer",
+      isDefault: true,
       grants: {
         documents: { read: true },
       },

package/dist/cli.mjs

@@ -5,7 +5,7 @@ import {
   computeRbacDiff,
   formatRbacDiff,
   loadRbacConfig
-} from "./chunk-5YEMXO7B.mjs";
+} from "./chunk-ZFKXT2MP.mjs";
 
 // src/cli.ts
 import chalk from "chalk";
@@ -93,6 +93,7 @@ export const rbac = defineRbac({
     },
     viewer: {
       name: "Viewer",
+      isDefault: true,
       grants: {
         documents: { read: true },
       },

package/dist/index.cjs

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   RbacSyncClient: () => RbacSyncClient,
   computeRbacDiff: () => computeRbacDiff,
+  createRoleManagement: () => createRoleManagement,
   defineRbac: () => defineRbac,
   formatRbacDiff: () => formatRbacDiff,
   hashConditionSource: () => hashConditionSource,
@@ -169,6 +170,21 @@ function validateRbacConfig(config) {
       }
     }
   }
+  const defaultRoles = [];
+  for (const key of roleKeys) {
+    const role = roles[key];
+    if (role.isDefault !== void 0 && typeof role.isDefault !== "boolean") {
+      throw new Error(`Role "${key}".isDefault must be a boolean.`);
+    }
+    if (role.isDefault === true) {
+      defaultRoles.push(key);
+    }
+  }
+  if (defaultRoles.length > 1) {
+    throw new Error(
+      `Only one role may have isDefault: true. Found ${defaultRoles.length}: ${defaultRoles.join(", ")}.`
+    );
+  }
   for (const key of roleKeys) {
     const role = roles[key];
     if (role.inherits !== void 0) {
@@ -321,7 +337,7 @@ function hashConditionSource(fn) {
   return createHash("sha256").update(fn.toString()).digest("hex").slice(0, 16);
 }
 function computeRbacDiff(config, server, memberCounts) {
-  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
   const resourceOps = [];
   const roleOps = [];
   const conditionOps = [];
@@ -412,6 +428,11 @@ function computeRbacDiff(config, server, memberCounts) {
       if (existingInherits !== configInherits) {
         changes.push("inherits changed");
       }
+      const existingDefault = (_l = existing.isDefault) != null ? _l : false;
+      const configDefault = (_m = role.isDefault) != null ? _m : false;
+      if (existingDefault !== configDefault) {
+        changes.push(`isDefault: ${existingDefault} -> ${configDefault}`);
+      }
       if (changes.length > 0) {
         roleOps.push({ type: "update", key, role, existing, changes });
       }
@@ -421,7 +442,7 @@ function computeRbacDiff(config, server, memberCounts) {
   for (const [key, role] of serverRoleByKey) {
     if (renameMap.has(key)) continue;
     if (role.isActive) {
-      const members = (_l = memberCounts[role.configKey]) != null ? _l : 0;
+      const members = (_n = memberCounts[role.configKey]) != null ? _n : 0;
       if (members > 0) hasDestructive = true;
       roleOps.push({ type: "archive", key, existing: role, assignedMembers: members });
     }
@@ -571,6 +592,9 @@ function formatRbacDiff(diff, dryRun) {
             import_chalk.default.dim(`    inherits: [${[...op.role.inherits].join(", ")}]`)
           );
         }
+        if (op.role.isDefault) {
+          lines.push(import_chalk.default.dim(`    isDefault: true`));
+        }
       } else if (op.type === "update") {
         lines.push(import_chalk.default.yellow(`  ~ UPDATE role "${op.key}"`));
         for (const change of op.changes) {
@@ -641,8 +665,95 @@ function formatRbacDiff(diff, dryRun) {
   return lines.join("\n");
 }
 
+// src/role-management.ts
+function createRoleManagement(config) {
+  const baseUrl = config.baseUrl.replace(/\/$/, "");
+  const apiKey = config.apiKey;
+  async function request(method, path, body) {
+    var _a, _b;
+    const url = `${baseUrl}${path}`;
+    const headers = {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    };
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      let message;
+      try {
+        const json = JSON.parse(text);
+        message = (_b = (_a = json.error) != null ? _a : json.message) != null ? _b : "Unknown error";
+      } catch (e) {
+        message = text.length > 500 ? text.slice(0, 500) + "..." : text;
+      }
+      if (apiKey) {
+        message = message.replaceAll(apiKey, "[REDACTED]");
+      }
+      throw new Error(`API error (${res.status}): ${message}`);
+    }
+    return res.json();
+  }
+  return {
+    async listRoles() {
+      const result = await request("GET", "/api/v1/roles");
+      return result.data.map(toRole);
+    },
+    async createRole(input) {
+      var _a, _b;
+      const result = await request("POST", "/api/v1/roles", {
+        key: input.key,
+        name: input.name,
+        description: input.description,
+        is_default: (_a = input.isDefault) != null ? _a : false,
+        permissions: (_b = input.permissions) != null ? _b : []
+      });
+      return toRole(result.role);
+    },
+    async updateRole(roleId, input) {
+      const body = {};
+      if (input.name !== void 0) body.name = input.name;
+      if (input.description !== void 0) body.description = input.description;
+      if (input.permissions !== void 0) body.permissions = input.permissions;
+      if (input.isDefault !== void 0) body.is_default = input.isDefault;
+      const result = await request(
+        "PATCH",
+        `/api/v1/roles/${encodeURIComponent(roleId)}`,
+        body
+      );
+      return toRole(result.role);
+    },
+    async deleteRole(roleId) {
+      await request(
+        "DELETE",
+        `/api/v1/roles/${encodeURIComponent(roleId)}`
+      );
+    },
+    async setDefaultRole(roleId) {
+      return this.updateRole(roleId, { isDefault: true });
+    }
+  };
+}
+function toRole(raw) {
+  return {
+    id: raw.id,
+    projectId: raw.project_id,
+    key: raw.key,
+    name: raw.name,
+    description: raw.description,
+    isDefault: raw.is_default,
+    permissions: raw.permissions,
+    createdAt: raw.created_at,
+    updatedAt: raw.updated_at
+  };
+}
+
 // src/index.ts
 function defineRbac(config, opts) {
+  var _a;
   if ((opts == null ? void 0 : opts.validate) !== false) {
     validateRbacConfig(config);
   }
@@ -656,7 +767,7 @@ function defineRbac(config, opts) {
   }
   const roles = {};
   for (const [key, role] of Object.entries(config.roles)) {
-    roles[key] = { key, name: role.name, grants: role.grants };
+    roles[key] = { key, name: role.name, grants: role.grants, isDefault: (_a = role.isDefault) != null ? _a : false };
   }
   const permissions = {};
   for (const [key, resource] of Object.entries(config.resources)) {
@@ -679,6 +790,7 @@ function defineRbac(config, opts) {
 0 && (module.exports = {
   RbacSyncClient,
   computeRbacDiff,
+  createRoleManagement,
   defineRbac,
   formatRbacDiff,
   hashConditionSource,

package/dist/index.d.cts

@@ -39,6 +39,8 @@ interface RoleConfig {
     description?: string;
     inherits?: readonly string[];
     grants: Record<string, Record<string, GrantValue>>;
+    /** Mark this role as the default for new org members. Only one role may be default. */
+    isDefault?: boolean;
     /** Previous config key if this role was renamed. */
     renamedFrom?: string;
 }
@@ -80,6 +82,63 @@ type InferScopes<T, Resource extends string> = T extends {
 type InferConditionKeys<T> = T extends {
     conditions: infer C;
 } ? keyof C & string : never;
+/** Extract role keys that have `isDefault: true`. */
+type DefaultRoleKeys<Roles> = {
+    [K in keyof Roles]: Roles[K] extends {
+        isDefault: true;
+    } ? K : never;
+}[keyof Roles];
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+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.
+ *
+ * Error reads: Type 'true' is not assignable to type '"ERROR: ..."'.
+ */
+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";
+        };
+    };
+} : {} : {};
+/** Extract valid action string literals from a resource config. */
+type ValidActions<R> = R extends {
+    actions: readonly (infer U)[];
+} ? U & string : never;
+/**
+ * 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.
+ * - **Valid grants** → passes through original types transparently.
+ *
+ * Used as `T & ValidateConfig<T>` in the `defineRbac()` parameter type.
+ *
+ * @note Extra properties on role objects (e.g. `isFakeProp`) are caught
+ * by the runtime `validateRbacConfig()` which runs by default.
+ */
+type ValidateConfig<T> = T extends {
+    resources: infer R extends Record<string, ResourceConfig>;
+    roles: infer Roles;
+} ? {
+    roles: {
+        [RK in keyof Roles]: Roles[RK] extends {
+            grants: infer G;
+        } ? {
+            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`;
+            };
+        } : Roles[RK];
+    };
+} : {};
 /** A structured resource with a `key` constant and an `actions` map of `"resource:action"` strings. */
 type StructuredResource<T, K extends string> = {
     readonly key: K;
@@ -91,7 +150,7 @@ type StructuredResource<T, K extends string> = {
 type StructuredResources<T> = {
     readonly [K in InferResourceKeys<T>]: StructuredResource<T, K>;
 };
-/** A structured role with `key`, `name`, and `grants` from the config. */
+/** A structured role with `key`, `name`, `grants`, and optional `isDefault` from the config. */
 type StructuredRole<T, K extends string> = {
     readonly key: K;
     readonly name: T extends {
@@ -104,6 +163,11 @@ type StructuredRole<T, K extends string> = {
     } ? K extends keyof R ? R[K] extends {
         grants: infer G;
     } ? Readonly<G> : {} : {} : {};
+    readonly isDefault: T extends {
+        roles: infer R;
+    } ? K extends keyof R ? R[K] extends {
+        isDefault: infer D;
+    } ? D : false : false : false;
 };
 /** Map of all roles as structured objects: `roles.admin.key` -> `"admin"`. */
 type StructuredRoles<T> = {
@@ -121,7 +185,7 @@ type StructuredPermissions<T> = {
  * Carries phantom types that downstream factories use to constrain
  * permission/role string parameters -- enabling full IDE autocomplete.
  */
-interface TypedRbac<T extends RbacConfig> {
+interface TypedRbac<T> {
     /** The raw RBAC config. Access resources, roles, etc. via `rbac._config`. */
     readonly _config: T;
     /**
@@ -172,6 +236,7 @@ interface ServerRole {
     grants: Record<string, Record<string, GrantValue>> | null;
     inherits: string[];
     resolvedPermissions: string[];
+    isDefault: boolean;
     isActive: boolean;
     managedBy: string;
     version: number;
@@ -272,12 +337,61 @@ declare class RbacSyncClient {
 
 declare function formatRbacDiff(diff: DiffResult, dryRun: boolean): string;
 
+interface RoleManagementConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+interface Role {
+    id: string;
+    projectId: string;
+    key: string;
+    name: string;
+    description: string | null;
+    isDefault: boolean;
+    permissions: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateRoleInput {
+    key: string;
+    name: string;
+    description?: string;
+    isDefault?: boolean;
+    permissions?: string[];
+}
+interface UpdateRoleInput {
+    name?: string;
+    description?: string | null;
+    permissions?: string[];
+    isDefault?: boolean;
+}
+interface RoleManagementClient {
+    listRoles(): Promise<Role[]>;
+    createRole(input: CreateRoleInput): Promise<Role>;
+    updateRole(roleId: string, input: UpdateRoleInput): Promise<Role>;
+    deleteRole(roleId: string): Promise<void>;
+    setDefaultRole(roleId: string): Promise<Role>;
+}
+declare function createRoleManagement(config: RoleManagementConfig): RoleManagementClient;
+
+/** Base config shape used as the generic constraint for `defineRbac()`. */
+type DefineRbacConfig = {
+    resources: Record<string, ResourceConfig>;
+    conditions?: Record<string, ConditionFn>;
+    roles: Record<string, {
+        name: string;
+        description?: string;
+        inherits?: readonly string[];
+        isDefault?: boolean;
+        renamedFrom?: string;
+        grants: Record<string, Record<string, GrantValue>>;
+    }>;
+};
 /**
  * Define your RBAC config. Use this in your `authgate.rbac.ts` config file.
  *
- * Returns a `TypedRbac<T>` object with structured resource, role, and permission
- * objects -- enabling full IDE autocomplete via dot-notation across hooks, helpers,
- * and server-side checks.
+ * Grants are validated at compile-time: if a role references an undeclared
+ * resource or action, TypeScript flags it as a type error.
  *
  * @example
  * ```ts
@@ -310,8 +424,8 @@ declare function formatRbacDiff(diff: DiffResult, dryRun: boolean): string;
  * rbac.permissions.documents.write       // "documents:write"
  * ```
  */
-declare function defineRbac<const T extends RbacConfig>(config: T, opts?: {
+declare function defineRbac<const T extends DefineRbacConfig>(config: T & ValidateConfig<T> & ValidateSingleDefault<T>, opts?: {
     validate?: boolean;
 }): TypedRbac<T>;
 
-export { type ApplyResult, type ConditionContext, type ConditionFn, type ConditionOp, type DiffResult, type GrantValue, type InferActions, type InferConditionKeys, type InferPermissions, type InferResourceKeys, type InferRoleKeys, type InferScopes, type Permission, type RbacConfig, RbacSyncClient, type RbacSyncClientConfig, type ResourceConfig, type ResourceKey, type ResourceOp, type RoleConfig, type RoleKey, type RoleOp, type ServerCondition, type ServerResource, type ServerRole, type ServerState, type TypedRbac, computeRbacDiff, defineRbac, formatRbacDiff, hashConditionSource, loadRbacConfig, validateRbacConfig };
+export { type ApplyResult, type ConditionContext, type ConditionFn, type ConditionOp, type CreateRoleInput, type DiffResult, type GrantValue, type InferActions, type InferConditionKeys, type InferPermissions, type InferResourceKeys, type InferRoleKeys, type InferScopes, type Permission, type RbacConfig, RbacSyncClient, type RbacSyncClientConfig, type ResourceConfig, type ResourceKey, type ResourceOp, type Role, type RoleConfig, type RoleKey, type RoleManagementClient, type RoleManagementConfig, type RoleOp, type ServerCondition, type ServerResource, type ServerRole, type ServerState, type TypedRbac, type UpdateRoleInput, computeRbacDiff, createRoleManagement, defineRbac, formatRbacDiff, hashConditionSource, loadRbacConfig, validateRbacConfig };

package/dist/index.d.ts

@@ -39,6 +39,8 @@ interface RoleConfig {
     description?: string;
     inherits?: readonly string[];
     grants: Record<string, Record<string, GrantValue>>;
+    /** Mark this role as the default for new org members. Only one role may be default. */
+    isDefault?: boolean;
     /** Previous config key if this role was renamed. */
     renamedFrom?: string;
 }
@@ -80,6 +82,63 @@ type InferScopes<T, Resource extends string> = T extends {
 type InferConditionKeys<T> = T extends {
     conditions: infer C;
 } ? keyof C & string : never;
+/** Extract role keys that have `isDefault: true`. */
+type DefaultRoleKeys<Roles> = {
+    [K in keyof Roles]: Roles[K] extends {
+        isDefault: true;
+    } ? K : never;
+}[keyof Roles];
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+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.
+ *
+ * Error reads: Type 'true' is not assignable to type '"ERROR: ..."'.
+ */
+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";
+        };
+    };
+} : {} : {};
+/** Extract valid action string literals from a resource config. */
+type ValidActions<R> = R extends {
+    actions: readonly (infer U)[];
+} ? U & string : never;
+/**
+ * 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.
+ * - **Valid grants** → passes through original types transparently.
+ *
+ * Used as `T & ValidateConfig<T>` in the `defineRbac()` parameter type.
+ *
+ * @note Extra properties on role objects (e.g. `isFakeProp`) are caught
+ * by the runtime `validateRbacConfig()` which runs by default.
+ */
+type ValidateConfig<T> = T extends {
+    resources: infer R extends Record<string, ResourceConfig>;
+    roles: infer Roles;
+} ? {
+    roles: {
+        [RK in keyof Roles]: Roles[RK] extends {
+            grants: infer G;
+        } ? {
+            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`;
+            };
+        } : Roles[RK];
+    };
+} : {};
 /** A structured resource with a `key` constant and an `actions` map of `"resource:action"` strings. */
 type StructuredResource<T, K extends string> = {
     readonly key: K;
@@ -91,7 +150,7 @@ type StructuredResource<T, K extends string> = {
 type StructuredResources<T> = {
     readonly [K in InferResourceKeys<T>]: StructuredResource<T, K>;
 };
-/** A structured role with `key`, `name`, and `grants` from the config. */
+/** A structured role with `key`, `name`, `grants`, and optional `isDefault` from the config. */
 type StructuredRole<T, K extends string> = {
     readonly key: K;
     readonly name: T extends {
@@ -104,6 +163,11 @@ type StructuredRole<T, K extends string> = {
     } ? K extends keyof R ? R[K] extends {
         grants: infer G;
     } ? Readonly<G> : {} : {} : {};
+    readonly isDefault: T extends {
+        roles: infer R;
+    } ? K extends keyof R ? R[K] extends {
+        isDefault: infer D;
+    } ? D : false : false : false;
 };
 /** Map of all roles as structured objects: `roles.admin.key` -> `"admin"`. */
 type StructuredRoles<T> = {
@@ -121,7 +185,7 @@ type StructuredPermissions<T> = {
  * Carries phantom types that downstream factories use to constrain
  * permission/role string parameters -- enabling full IDE autocomplete.
  */
-interface TypedRbac<T extends RbacConfig> {
+interface TypedRbac<T> {
     /** The raw RBAC config. Access resources, roles, etc. via `rbac._config`. */
     readonly _config: T;
     /**
@@ -172,6 +236,7 @@ interface ServerRole {
     grants: Record<string, Record<string, GrantValue>> | null;
     inherits: string[];
     resolvedPermissions: string[];
+    isDefault: boolean;
     isActive: boolean;
     managedBy: string;
     version: number;
@@ -272,12 +337,61 @@ declare class RbacSyncClient {
 
 declare function formatRbacDiff(diff: DiffResult, dryRun: boolean): string;
 
+interface RoleManagementConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+interface Role {
+    id: string;
+    projectId: string;
+    key: string;
+    name: string;
+    description: string | null;
+    isDefault: boolean;
+    permissions: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateRoleInput {
+    key: string;
+    name: string;
+    description?: string;
+    isDefault?: boolean;
+    permissions?: string[];
+}
+interface UpdateRoleInput {
+    name?: string;
+    description?: string | null;
+    permissions?: string[];
+    isDefault?: boolean;
+}
+interface RoleManagementClient {
+    listRoles(): Promise<Role[]>;
+    createRole(input: CreateRoleInput): Promise<Role>;
+    updateRole(roleId: string, input: UpdateRoleInput): Promise<Role>;
+    deleteRole(roleId: string): Promise<void>;
+    setDefaultRole(roleId: string): Promise<Role>;
+}
+declare function createRoleManagement(config: RoleManagementConfig): RoleManagementClient;
+
+/** Base config shape used as the generic constraint for `defineRbac()`. */
+type DefineRbacConfig = {
+    resources: Record<string, ResourceConfig>;
+    conditions?: Record<string, ConditionFn>;
+    roles: Record<string, {
+        name: string;
+        description?: string;
+        inherits?: readonly string[];
+        isDefault?: boolean;
+        renamedFrom?: string;
+        grants: Record<string, Record<string, GrantValue>>;
+    }>;
+};
 /**
  * Define your RBAC config. Use this in your `authgate.rbac.ts` config file.
  *
- * Returns a `TypedRbac<T>` object with structured resource, role, and permission
- * objects -- enabling full IDE autocomplete via dot-notation across hooks, helpers,
- * and server-side checks.
+ * Grants are validated at compile-time: if a role references an undeclared
+ * resource or action, TypeScript flags it as a type error.
  *
  * @example
  * ```ts
@@ -310,8 +424,8 @@ declare function formatRbacDiff(diff: DiffResult, dryRun: boolean): string;
  * rbac.permissions.documents.write       // "documents:write"
  * ```
  */
-declare function defineRbac<const T extends RbacConfig>(config: T, opts?: {
+declare function defineRbac<const T extends DefineRbacConfig>(config: T & ValidateConfig<T> & ValidateSingleDefault<T>, opts?: {
     validate?: boolean;
 }): TypedRbac<T>;
 
-export { type ApplyResult, type ConditionContext, type ConditionFn, type ConditionOp, type DiffResult, type GrantValue, type InferActions, type InferConditionKeys, type InferPermissions, type InferResourceKeys, type InferRoleKeys, type InferScopes, type Permission, type RbacConfig, RbacSyncClient, type RbacSyncClientConfig, type ResourceConfig, type ResourceKey, type ResourceOp, type RoleConfig, type RoleKey, type RoleOp, type ServerCondition, type ServerResource, type ServerRole, type ServerState, type TypedRbac, computeRbacDiff, defineRbac, formatRbacDiff, hashConditionSource, loadRbacConfig, validateRbacConfig };
+export { type ApplyResult, type ConditionContext, type ConditionFn, type ConditionOp, type CreateRoleInput, type DiffResult, type GrantValue, type InferActions, type InferConditionKeys, type InferPermissions, type InferResourceKeys, type InferRoleKeys, type InferScopes, type Permission, type RbacConfig, RbacSyncClient, type RbacSyncClientConfig, type ResourceConfig, type ResourceKey, type ResourceOp, type Role, type RoleConfig, type RoleKey, type RoleManagementClient, type RoleManagementConfig, type RoleOp, type ServerCondition, type ServerResource, type ServerRole, type ServerState, type TypedRbac, type UpdateRoleInput, computeRbacDiff, createRoleManagement, defineRbac, formatRbacDiff, hashConditionSource, loadRbacConfig, validateRbacConfig };

package/dist/index.mjs

@@ -5,10 +5,97 @@ import {
   hashConditionSource,
   loadRbacConfig,
   validateRbacConfig
-} from "./chunk-5YEMXO7B.mjs";
+} from "./chunk-ZFKXT2MP.mjs";
+
+// src/role-management.ts
+function createRoleManagement(config) {
+  const baseUrl = config.baseUrl.replace(/\/$/, "");
+  const apiKey = config.apiKey;
+  async function request(method, path, body) {
+    var _a, _b;
+    const url = `${baseUrl}${path}`;
+    const headers = {
+      Authorization: `Bearer ${apiKey}`,
+      "Content-Type": "application/json"
+    };
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      let message;
+      try {
+        const json = JSON.parse(text);
+        message = (_b = (_a = json.error) != null ? _a : json.message) != null ? _b : "Unknown error";
+      } catch (e) {
+        message = text.length > 500 ? text.slice(0, 500) + "..." : text;
+      }
+      if (apiKey) {
+        message = message.replaceAll(apiKey, "[REDACTED]");
+      }
+      throw new Error(`API error (${res.status}): ${message}`);
+    }
+    return res.json();
+  }
+  return {
+    async listRoles() {
+      const result = await request("GET", "/api/v1/roles");
+      return result.data.map(toRole);
+    },
+    async createRole(input) {
+      var _a, _b;
+      const result = await request("POST", "/api/v1/roles", {
+        key: input.key,
+        name: input.name,
+        description: input.description,
+        is_default: (_a = input.isDefault) != null ? _a : false,
+        permissions: (_b = input.permissions) != null ? _b : []
+      });
+      return toRole(result.role);
+    },
+    async updateRole(roleId, input) {
+      const body = {};
+      if (input.name !== void 0) body.name = input.name;
+      if (input.description !== void 0) body.description = input.description;
+      if (input.permissions !== void 0) body.permissions = input.permissions;
+      if (input.isDefault !== void 0) body.is_default = input.isDefault;
+      const result = await request(
+        "PATCH",
+        `/api/v1/roles/${encodeURIComponent(roleId)}`,
+        body
+      );
+      return toRole(result.role);
+    },
+    async deleteRole(roleId) {
+      await request(
+        "DELETE",
+        `/api/v1/roles/${encodeURIComponent(roleId)}`
+      );
+    },
+    async setDefaultRole(roleId) {
+      return this.updateRole(roleId, { isDefault: true });
+    }
+  };
+}
+function toRole(raw) {
+  return {
+    id: raw.id,
+    projectId: raw.project_id,
+    key: raw.key,
+    name: raw.name,
+    description: raw.description,
+    isDefault: raw.is_default,
+    permissions: raw.permissions,
+    createdAt: raw.created_at,
+    updatedAt: raw.updated_at
+  };
+}
 
 // src/index.ts
 function defineRbac(config, opts) {
+  var _a;
   if ((opts == null ? void 0 : opts.validate) !== false) {
     validateRbacConfig(config);
   }
@@ -22,7 +109,7 @@ function defineRbac(config, opts) {
   }
   const roles = {};
   for (const [key, role] of Object.entries(config.roles)) {
-    roles[key] = { key, name: role.name, grants: role.grants };
+    roles[key] = { key, name: role.name, grants: role.grants, isDefault: (_a = role.isDefault) != null ? _a : false };
   }
   const permissions = {};
   for (const [key, resource] of Object.entries(config.resources)) {
@@ -44,6 +131,7 @@ function defineRbac(config, opts) {
 export {
   RbacSyncClient,
   computeRbacDiff,
+  createRoleManagement,
   defineRbac,
   formatRbacDiff,
   hashConditionSource,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@auth-gate/rbac",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "type": "module",
   "exports": {
     ".": {