@auth-gate/rbac 0.8.0 → 0.9.0

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,
@@ -88,15 +89,28 @@ function validateRbacConfig(config) {
         );
       }
     }
-    resourceActions.set(key, new Set(resource.actions));
+    const actionSet = /* @__PURE__ */ new Set();
+    for (const action of resource.actions) {
+      if (actionSet.has(action)) {
+        throw new Error(`Resource "${key}" has duplicate action: "${action}".`);
+      }
+      actionSet.add(action);
+    }
+    resourceActions.set(key, actionSet);
     if (resource.scopes !== void 0) {
       if (!Array.isArray(resource.scopes)) {
         throw new Error(`Resource "${key}".scopes must be an array of strings.`);
       }
+      const scopeSet = /* @__PURE__ */ new Set();
       for (let i = 0; i < resource.scopes.length; i++) {
         if (typeof resource.scopes[i] !== "string") {
           throw new Error(`Resource "${key}".scopes[${i}] must be a string.`);
         }
+        const scope = resource.scopes[i];
+        if (scopeSet.has(scope)) {
+          throw new Error(`Resource "${key}" has duplicate scope: "${scope}".`);
+        }
+        scopeSet.add(scope);
       }
     }
   }
@@ -137,14 +151,40 @@ function validateRbacConfig(config) {
           );
         }
         const value = actionsGrant[actionKey];
-        if (value !== true && typeof value !== "string" && !(value && typeof value === "object" && "when" in value && typeof value.when === "string")) {
+        if (value !== true && (typeof value !== "string" || value === "") && !(value && typeof value === "object" && "when" in value && typeof value.when === "string" && value.when !== "")) {
           throw new Error(
-            `Role "${key}".grants.${resourceKey}.${actionKey} has invalid value. Expected true, a scope string, or { when: string }.`
+            `Role "${key}".grants.${resourceKey}.${actionKey} has invalid value. Expected true, a non-empty scope string, or { when: non-empty string }.`
           );
         }
+        if (typeof value === "string" && value !== "") {
+          const resource = resources[resourceKey];
+          if (resource.scopes && Array.isArray(resource.scopes)) {
+            const declaredScopes = new Set(resource.scopes);
+            if (!declaredScopes.has(value)) {
+              throw new Error(
+                `Role "${key}".grants.${resourceKey}.${actionKey} scope "${value}" is not in declared scopes for "${resourceKey}": ${[...declaredScopes].join(", ")}.`
+              );
+            }
+          }
+        }
       }
     }
   }
+  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) {
@@ -210,6 +250,7 @@ function validateRbacConfig(config) {
       renameTargets.set(role.renamedFrom, key);
     }
   }
+  const conditionKeys = /* @__PURE__ */ new Set();
   if (c.conditions !== void 0) {
     if (typeof c.conditions !== "object" || Array.isArray(c.conditions) || c.conditions === null) {
       throw new Error("RBAC config `conditions` must be an object mapping names to functions.");
@@ -221,6 +262,23 @@ function validateRbacConfig(config) {
           `Condition "${condKey}" must be a function. Got ${typeof condValue}.`
         );
       }
+      conditionKeys.add(condKey);
+    }
+  }
+  for (const key of roleKeys) {
+    const role = roles[key];
+    const grants = role.grants;
+    for (const [resourceKey, actionGrants] of Object.entries(grants)) {
+      for (const [actionKey, value] of Object.entries(actionGrants)) {
+        if (value && typeof value === "object" && "when" in value) {
+          const whenKey = value.when;
+          if (!conditionKeys.has(whenKey)) {
+            throw new Error(
+              `Role "${key}".grants.${resourceKey}.${actionKey} references condition "${whenKey}" but it is not declared in conditions.` + (conditionKeys.size > 0 ? ` Declared conditions: ${[...conditionKeys].join(", ")}.` : ` No conditions are declared.`)
+            );
+          }
+        }
+      }
     }
   }
   return config;
@@ -259,17 +317,27 @@ Run \`npx @auth-gate/rbac init\` to create one.`
 }
 
 // src/diff.ts
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    return a.every((val, i) => deepEqual(val, b[i]));
+  }
+  const keysA = Object.keys(a).sort();
+  const keysB = Object.keys(b).sort();
+  if (keysA.length !== keysB.length) return false;
+  return keysA.every(
+    (key, i) => key === keysB[i] && deepEqual(a[key], b[key])
+  );
+}
 function hashConditionSource(fn) {
-  const src = fn.toString();
-  let hash = 0;
-  for (let i = 0; i < src.length; i++) {
-    const ch = src.charCodeAt(i);
-    hash = (hash << 5) - hash + ch | 0;
-  }
-  return hash.toString(36);
+  const { createHash } = require("crypto");
+  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;
+  var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n;
   const resourceOps = [];
   const roleOps = [];
   const conditionOps = [];
@@ -328,7 +396,7 @@ function computeRbacDiff(config, server, memberCounts) {
     if (!existing && role.renamedFrom) {
       existing = (_d = serverRoleByKey.get(role.renamedFrom)) != null ? _d : serverRoleByPreviousKey.get(role.renamedFrom);
       if (existing) {
-        const members = (_e = memberCounts[existing.id]) != null ? _e : 0;
+        const members = (_e = memberCounts[existing.configKey]) != null ? _e : 0;
         roleOps.push({
           type: "rename",
           key,
@@ -352,16 +420,19 @@ function computeRbacDiff(config, server, memberCounts) {
       if (((_f = existing.description) != null ? _f : void 0) !== ((_g = role.description) != null ? _g : void 0)) {
         changes.push("description changed");
       }
-      const existingGrants = JSON.stringify((_h = existing.grants) != null ? _h : null);
-      const configGrants = JSON.stringify(role.grants);
-      if (existingGrants !== configGrants) {
+      if (!deepEqual((_h = existing.grants) != null ? _h : null, (_i = role.grants) != null ? _i : null)) {
         changes.push("grants changed");
       }
-      const existingInherits = [...(_i = existing.inherits) != null ? _i : []].sort().join(",");
-      const configInherits = [...(_j = role.inherits) != null ? _j : []].sort().join(",");
+      const existingInherits = [...(_j = existing.inherits) != null ? _j : []].sort().join(",");
+      const configInherits = [...(_k = role.inherits) != null ? _k : []].sort().join(",");
       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 });
       }
@@ -371,7 +442,7 @@ function computeRbacDiff(config, server, memberCounts) {
   for (const [key, role] of serverRoleByKey) {
     if (renameMap.has(key)) continue;
     if (role.isActive) {
-      const members = (_k = memberCounts[role.id]) != null ? _k : 0;
+      const members = (_n = memberCounts[role.configKey]) != null ? _n : 0;
       if (members > 0) hasDestructive = true;
       roleOps.push({ type: "archive", key, existing: role, assignedMembers: members });
     }
@@ -407,6 +478,11 @@ var RbacSyncClient = class {
   constructor(config) {
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
     this.apiKey = config.apiKey;
+    if (!this.baseUrl.startsWith("https://") && !this.baseUrl.startsWith("http://localhost") && !this.baseUrl.startsWith("http://127.0.0.1")) {
+      console.warn(
+        "WARNING: AUTHGATE_BASE_URL does not use HTTPS. API key may be transmitted insecurely."
+      );
+    }
   }
   async request(method, path, body) {
     var _a, _b;
@@ -425,9 +501,12 @@ var RbacSyncClient = class {
       let message;
       try {
         const json = JSON.parse(text);
-        message = (_b = (_a = json.error) != null ? _a : json.message) != null ? _b : text;
+        message = (_b = (_a = json.error) != null ? _a : json.message) != null ? _b : "Unknown error";
       } catch (e) {
-        message = text;
+        message = text.length > 500 ? text.slice(0, 500) + "..." : text;
+      }
+      if (this.apiKey) {
+        message = message.replaceAll(this.apiKey, "[REDACTED]");
       }
       throw new Error(`API error (${res.status}): ${message}`);
     }
@@ -447,7 +526,10 @@ var RbacSyncClient = class {
       resources: config.resources,
       roles: config.roles,
       conditions: config.conditions ? Object.fromEntries(
-        Object.entries(config.conditions).map(([k]) => [k, { key: k }])
+        Object.entries(config.conditions).map(([k, fn]) => [
+          k,
+          { key: k, sourceHash: hashConditionSource(fn) }
+        ])
       ) : void 0,
       force
     });
@@ -510,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) {
@@ -580,8 +665,98 @@ 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) {
+function defineRbac(config, opts) {
+  var _a;
+  if ((opts == null ? void 0 : opts.validate) !== false) {
+    validateRbacConfig(config);
+  }
   const resources = {};
   for (const [key, resource] of Object.entries(config.resources)) {
     const actions = {};
@@ -592,7 +767,7 @@ function defineRbac(config) {
   }
   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)) {
@@ -615,6 +790,7 @@ function defineRbac(config) {
 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;
@@ -245,7 +310,7 @@ interface DiffResult {
     conditionOps: ConditionOp[];
     hasDestructive: boolean;
 }
-/** Simple hash of a condition function's source code for change detection. */
+/** Hash of a condition function's source code for change detection. */
 declare function hashConditionSource(fn: Function): string;
 declare function computeRbacDiff(config: RbacConfig, server: ServerState, memberCounts: Record<string, number>): DiffResult;
 
@@ -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,6 +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): TypedRbac<T>;
+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 };