@auth-gate/rbac 0.8.0

package/dist/index.d.cts

@@ -0,0 +1,315 @@
+/** A resource definition: declares available actions and optional scopes. */
+interface ResourceConfig {
+    actions: readonly string[];
+    scopes?: readonly string[];
+}
+/** Context provided to condition functions for attribute-based decisions. */
+interface ConditionContext {
+    user: {
+        id: string;
+        metadata?: Record<string, unknown>;
+    };
+    resource?: {
+        id?: string;
+        ownerId?: string;
+        metadata?: Record<string, unknown>;
+    };
+    env: {
+        timestamp: number;
+        hour: number;
+        dayOfWeek: number;
+    };
+}
+/** A named condition function evaluated at check time (client/edge only). */
+type ConditionFn = (ctx: ConditionContext) => boolean;
+/**
+ * Grant value for a resource action.
+ *
+ * - `true` — boolean access (Phase 1)
+ * - `string` — scope key, e.g. "own", "department", "all" (Phase 2)
+ * - `{ when: string; scope?: string }` — conditional grant (Phase 2)
+ */
+type GrantValue = true | string | {
+    when: string;
+    scope?: string;
+};
+/** A role definition with grants matrix and optional inheritance. */
+interface RoleConfig {
+    name: string;
+    description?: string;
+    inherits?: readonly string[];
+    grants: Record<string, Record<string, GrantValue>>;
+    /** Previous config key if this role was renamed. */
+    renamedFrom?: string;
+}
+/** Root RBAC config object passed to `defineRbac()`. */
+interface RbacConfig {
+    resources: Record<string, ResourceConfig>;
+    conditions?: Record<string, ConditionFn>;
+    roles: Record<string, RoleConfig>;
+}
+/** Extract literal resource keys from an RBAC config type. */
+type InferResourceKeys<T> = T extends {
+    resources: infer R;
+} ? keyof R & string : never;
+/** Extract literal role keys from an RBAC config type. */
+type InferRoleKeys<T> = T extends {
+    roles: infer R;
+} ? keyof R & string : never;
+/** Extract action literals for a specific resource from an RBAC config type. */
+type InferActions<T, Resource extends string> = T extends {
+    resources: infer R;
+} ? Resource extends keyof R ? R[Resource] extends {
+    actions: infer A;
+} ? A extends readonly (infer U)[] ? U & string : never : never : never : never;
+/** Produce `"resource:action"` union from all resources in an RBAC config type. */
+type InferPermissions<T> = T extends {
+    resources: infer R;
+} ? {
+    [K in keyof R & string]: R[K] extends {
+        actions: infer A;
+    } ? A extends readonly (infer U)[] ? `${K}:${U & string}` : never : never;
+}[keyof R & string] : never;
+/** Extract scope literals for a specific resource from an RBAC config type. */
+type InferScopes<T, Resource extends string> = T extends {
+    resources: infer R;
+} ? Resource extends keyof R ? R[Resource] extends {
+    scopes: infer S;
+} ? S extends readonly (infer U)[] ? U & string : never : never : never : never;
+/** Extract literal condition keys from an RBAC config type. */
+type InferConditionKeys<T> = T extends {
+    conditions: infer C;
+} ? keyof C & string : never;
+/** A structured resource with a `key` constant and an `actions` map of `"resource:action"` strings. */
+type StructuredResource<T, K extends string> = {
+    readonly key: K;
+    readonly actions: {
+        readonly [A in InferActions<T, K>]: `${K}:${A}`;
+    };
+};
+/** Map of all resources as structured objects: `resources.documents.actions.read` -> `"documents:read"`. */
+type StructuredResources<T> = {
+    readonly [K in InferResourceKeys<T>]: StructuredResource<T, K>;
+};
+/** A structured role with `key`, `name`, and `grants` from the config. */
+type StructuredRole<T, K extends string> = {
+    readonly key: K;
+    readonly name: T extends {
+        roles: infer R;
+    } ? K extends keyof R ? R[K] extends {
+        name: infer N;
+    } ? N : string : string : string;
+    readonly grants: T extends {
+        roles: infer R;
+    } ? K extends keyof R ? R[K] extends {
+        grants: infer G;
+    } ? Readonly<G> : {} : {} : {};
+};
+/** Map of all roles as structured objects: `roles.admin.key` -> `"admin"`. */
+type StructuredRoles<T> = {
+    readonly [K in InferRoleKeys<T>]: StructuredRole<T, K>;
+};
+/** Permissions grouped by resource then action: `permissions.documents.read` -> `"documents:read"`. */
+type StructuredPermissions<T> = {
+    readonly [K in InferResourceKeys<T>]: {
+        readonly [A in InferActions<T, K>]: `${K}:${A}`;
+    };
+};
+/**
+ * Typed RBAC definition returned by `defineRbac()`.
+ *
+ * Carries phantom types that downstream factories use to constrain
+ * permission/role string parameters -- enabling full IDE autocomplete.
+ */
+interface TypedRbac<T extends RbacConfig> {
+    /** The raw RBAC config. Access resources, roles, etc. via `rbac._config`. */
+    readonly _config: T;
+    /**
+     * Phantom type carrier -- never read at runtime.
+     * Use `A["_types"]["permission"]` to extract the permission union from a `TypedRbac`.
+     */
+    readonly _types: {
+        readonly resourceKey: InferResourceKeys<T>;
+        readonly roleKey: InferRoleKeys<T>;
+        readonly permission: InferPermissions<T>;
+        readonly conditionKey: InferConditionKeys<T>;
+    };
+    /** Structured resource objects: `rbac.resources.documents.actions.read` -> `"documents:read"`. */
+    readonly resources: StructuredResources<T>;
+    /** Structured role objects: `rbac.roles.admin.key` -> `"admin"`, `.name`, `.grants`. */
+    readonly roles: StructuredRoles<T>;
+    /** Permissions grouped by resource: `rbac.permissions.documents.read` -> `"documents:read"`. */
+    readonly permissions: StructuredPermissions<T>;
+}
+/** Extract the permission union from a `TypedRbac` instance type. Falls back to `string`. */
+type Permission<A> = A extends TypedRbac<infer T> ? InferPermissions<T> : string;
+/** Extract the role key union from a `TypedRbac` instance type. Falls back to `string`. */
+type RoleKey<A> = A extends TypedRbac<infer T> ? InferRoleKeys<T> : string;
+/** Extract the resource key union from a `TypedRbac` instance type. Falls back to `string`. */
+type ResourceKey<A> = A extends TypedRbac<infer T> ? InferResourceKeys<T> : string;
+
+/**
+ * Validate an RbacConfig object, throwing a descriptive error on the first
+ * problem found.  Returns the validated config on success.
+ */
+declare function validateRbacConfig(config: unknown): RbacConfig;
+
+declare function loadRbacConfig(cwd: string): Promise<RbacConfig>;
+
+interface ServerResource {
+    id: string;
+    key: string;
+    actions: string[];
+    scopes: string[];
+    isActive: boolean;
+    managedBy: string;
+}
+interface ServerRole {
+    id: string;
+    configKey: string;
+    name: string;
+    description: string | null;
+    grants: Record<string, Record<string, GrantValue>> | null;
+    inherits: string[];
+    resolvedPermissions: string[];
+    isActive: boolean;
+    managedBy: string;
+    version: number;
+    previousConfigKeys: string[];
+}
+interface ServerCondition {
+    id: string;
+    key: string;
+    description: string | null;
+    sourceHash: string | null;
+    isActive: boolean;
+}
+interface ServerState {
+    resources: ServerResource[];
+    roles: ServerRole[];
+    conditions: ServerCondition[];
+}
+type ResourceOp = {
+    type: "create";
+    key: string;
+    resource: RbacConfig["resources"][string];
+} | {
+    type: "update";
+    key: string;
+    resource: RbacConfig["resources"][string];
+    existing: ServerResource;
+    changes: string[];
+} | {
+    type: "archive";
+    key: string;
+    existing: ServerResource;
+};
+type RoleOp = {
+    type: "create";
+    key: string;
+    role: RoleConfig;
+} | {
+    type: "update";
+    key: string;
+    role: RoleConfig;
+    existing: ServerRole;
+    changes: string[];
+} | {
+    type: "archive";
+    key: string;
+    existing: ServerRole;
+    assignedMembers: number;
+} | {
+    type: "rename";
+    key: string;
+    oldKey: string;
+    role: RoleConfig;
+    existing: ServerRole;
+    assignedMembers: number;
+};
+type ConditionOp = {
+    type: "create";
+    key: string;
+} | {
+    type: "update";
+    key: string;
+    changes: string[];
+} | {
+    type: "archive";
+    key: string;
+    existing: ServerCondition;
+};
+interface DiffResult {
+    resourceOps: ResourceOp[];
+    roleOps: RoleOp[];
+    conditionOps: ConditionOp[];
+    hasDestructive: boolean;
+}
+/** Simple 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;
+
+interface RbacSyncClientConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+interface ApplyResult {
+    created: string[];
+    updated: string[];
+    archived: string[];
+    renamed: string[];
+    warnings: string[];
+}
+declare class RbacSyncClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: RbacSyncClientConfig);
+    private request;
+    getState(): Promise<ServerState>;
+    getMemberCounts(): Promise<Record<string, number>>;
+    apply(config: RbacConfig, force: boolean): Promise<ApplyResult>;
+}
+
+declare function formatRbacDiff(diff: DiffResult, dryRun: boolean): string;
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * 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 },
+ *       },
+ *     },
+ *     viewer: {
+ *       name: "Viewer",
+ *       grants: {
+ *         documents: { read: true },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * rbac.resources.documents.key           // "documents"
+ * rbac.resources.documents.actions.read  // "documents:read"
+ * rbac.roles.admin.key                   // "admin"
+ * rbac.roles.admin.name                  // "Admin"
+ * rbac.permissions.documents.write       // "documents:write"
+ * ```
+ */
+declare function defineRbac<const T extends RbacConfig>(config: T): 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 };

package/dist/index.d.ts

@@ -0,0 +1,315 @@
+/** A resource definition: declares available actions and optional scopes. */
+interface ResourceConfig {
+    actions: readonly string[];
+    scopes?: readonly string[];
+}
+/** Context provided to condition functions for attribute-based decisions. */
+interface ConditionContext {
+    user: {
+        id: string;
+        metadata?: Record<string, unknown>;
+    };
+    resource?: {
+        id?: string;
+        ownerId?: string;
+        metadata?: Record<string, unknown>;
+    };
+    env: {
+        timestamp: number;
+        hour: number;
+        dayOfWeek: number;
+    };
+}
+/** A named condition function evaluated at check time (client/edge only). */
+type ConditionFn = (ctx: ConditionContext) => boolean;
+/**
+ * Grant value for a resource action.
+ *
+ * - `true` — boolean access (Phase 1)
+ * - `string` — scope key, e.g. "own", "department", "all" (Phase 2)
+ * - `{ when: string; scope?: string }` — conditional grant (Phase 2)
+ */
+type GrantValue = true | string | {
+    when: string;
+    scope?: string;
+};
+/** A role definition with grants matrix and optional inheritance. */
+interface RoleConfig {
+    name: string;
+    description?: string;
+    inherits?: readonly string[];
+    grants: Record<string, Record<string, GrantValue>>;
+    /** Previous config key if this role was renamed. */
+    renamedFrom?: string;
+}
+/** Root RBAC config object passed to `defineRbac()`. */
+interface RbacConfig {
+    resources: Record<string, ResourceConfig>;
+    conditions?: Record<string, ConditionFn>;
+    roles: Record<string, RoleConfig>;
+}
+/** Extract literal resource keys from an RBAC config type. */
+type InferResourceKeys<T> = T extends {
+    resources: infer R;
+} ? keyof R & string : never;
+/** Extract literal role keys from an RBAC config type. */
+type InferRoleKeys<T> = T extends {
+    roles: infer R;
+} ? keyof R & string : never;
+/** Extract action literals for a specific resource from an RBAC config type. */
+type InferActions<T, Resource extends string> = T extends {
+    resources: infer R;
+} ? Resource extends keyof R ? R[Resource] extends {
+    actions: infer A;
+} ? A extends readonly (infer U)[] ? U & string : never : never : never : never;
+/** Produce `"resource:action"` union from all resources in an RBAC config type. */
+type InferPermissions<T> = T extends {
+    resources: infer R;
+} ? {
+    [K in keyof R & string]: R[K] extends {
+        actions: infer A;
+    } ? A extends readonly (infer U)[] ? `${K}:${U & string}` : never : never;
+}[keyof R & string] : never;
+/** Extract scope literals for a specific resource from an RBAC config type. */
+type InferScopes<T, Resource extends string> = T extends {
+    resources: infer R;
+} ? Resource extends keyof R ? R[Resource] extends {
+    scopes: infer S;
+} ? S extends readonly (infer U)[] ? U & string : never : never : never : never;
+/** Extract literal condition keys from an RBAC config type. */
+type InferConditionKeys<T> = T extends {
+    conditions: infer C;
+} ? keyof C & string : never;
+/** A structured resource with a `key` constant and an `actions` map of `"resource:action"` strings. */
+type StructuredResource<T, K extends string> = {
+    readonly key: K;
+    readonly actions: {
+        readonly [A in InferActions<T, K>]: `${K}:${A}`;
+    };
+};
+/** Map of all resources as structured objects: `resources.documents.actions.read` -> `"documents:read"`. */
+type StructuredResources<T> = {
+    readonly [K in InferResourceKeys<T>]: StructuredResource<T, K>;
+};
+/** A structured role with `key`, `name`, and `grants` from the config. */
+type StructuredRole<T, K extends string> = {
+    readonly key: K;
+    readonly name: T extends {
+        roles: infer R;
+    } ? K extends keyof R ? R[K] extends {
+        name: infer N;
+    } ? N : string : string : string;
+    readonly grants: T extends {
+        roles: infer R;
+    } ? K extends keyof R ? R[K] extends {
+        grants: infer G;
+    } ? Readonly<G> : {} : {} : {};
+};
+/** Map of all roles as structured objects: `roles.admin.key` -> `"admin"`. */
+type StructuredRoles<T> = {
+    readonly [K in InferRoleKeys<T>]: StructuredRole<T, K>;
+};
+/** Permissions grouped by resource then action: `permissions.documents.read` -> `"documents:read"`. */
+type StructuredPermissions<T> = {
+    readonly [K in InferResourceKeys<T>]: {
+        readonly [A in InferActions<T, K>]: `${K}:${A}`;
+    };
+};
+/**
+ * Typed RBAC definition returned by `defineRbac()`.
+ *
+ * Carries phantom types that downstream factories use to constrain
+ * permission/role string parameters -- enabling full IDE autocomplete.
+ */
+interface TypedRbac<T extends RbacConfig> {
+    /** The raw RBAC config. Access resources, roles, etc. via `rbac._config`. */
+    readonly _config: T;
+    /**
+     * Phantom type carrier -- never read at runtime.
+     * Use `A["_types"]["permission"]` to extract the permission union from a `TypedRbac`.
+     */
+    readonly _types: {
+        readonly resourceKey: InferResourceKeys<T>;
+        readonly roleKey: InferRoleKeys<T>;
+        readonly permission: InferPermissions<T>;
+        readonly conditionKey: InferConditionKeys<T>;
+    };
+    /** Structured resource objects: `rbac.resources.documents.actions.read` -> `"documents:read"`. */
+    readonly resources: StructuredResources<T>;
+    /** Structured role objects: `rbac.roles.admin.key` -> `"admin"`, `.name`, `.grants`. */
+    readonly roles: StructuredRoles<T>;
+    /** Permissions grouped by resource: `rbac.permissions.documents.read` -> `"documents:read"`. */
+    readonly permissions: StructuredPermissions<T>;
+}
+/** Extract the permission union from a `TypedRbac` instance type. Falls back to `string`. */
+type Permission<A> = A extends TypedRbac<infer T> ? InferPermissions<T> : string;
+/** Extract the role key union from a `TypedRbac` instance type. Falls back to `string`. */
+type RoleKey<A> = A extends TypedRbac<infer T> ? InferRoleKeys<T> : string;
+/** Extract the resource key union from a `TypedRbac` instance type. Falls back to `string`. */
+type ResourceKey<A> = A extends TypedRbac<infer T> ? InferResourceKeys<T> : string;
+
+/**
+ * Validate an RbacConfig object, throwing a descriptive error on the first
+ * problem found.  Returns the validated config on success.
+ */
+declare function validateRbacConfig(config: unknown): RbacConfig;
+
+declare function loadRbacConfig(cwd: string): Promise<RbacConfig>;
+
+interface ServerResource {
+    id: string;
+    key: string;
+    actions: string[];
+    scopes: string[];
+    isActive: boolean;
+    managedBy: string;
+}
+interface ServerRole {
+    id: string;
+    configKey: string;
+    name: string;
+    description: string | null;
+    grants: Record<string, Record<string, GrantValue>> | null;
+    inherits: string[];
+    resolvedPermissions: string[];
+    isActive: boolean;
+    managedBy: string;
+    version: number;
+    previousConfigKeys: string[];
+}
+interface ServerCondition {
+    id: string;
+    key: string;
+    description: string | null;
+    sourceHash: string | null;
+    isActive: boolean;
+}
+interface ServerState {
+    resources: ServerResource[];
+    roles: ServerRole[];
+    conditions: ServerCondition[];
+}
+type ResourceOp = {
+    type: "create";
+    key: string;
+    resource: RbacConfig["resources"][string];
+} | {
+    type: "update";
+    key: string;
+    resource: RbacConfig["resources"][string];
+    existing: ServerResource;
+    changes: string[];
+} | {
+    type: "archive";
+    key: string;
+    existing: ServerResource;
+};
+type RoleOp = {
+    type: "create";
+    key: string;
+    role: RoleConfig;
+} | {
+    type: "update";
+    key: string;
+    role: RoleConfig;
+    existing: ServerRole;
+    changes: string[];
+} | {
+    type: "archive";
+    key: string;
+    existing: ServerRole;
+    assignedMembers: number;
+} | {
+    type: "rename";
+    key: string;
+    oldKey: string;
+    role: RoleConfig;
+    existing: ServerRole;
+    assignedMembers: number;
+};
+type ConditionOp = {
+    type: "create";
+    key: string;
+} | {
+    type: "update";
+    key: string;
+    changes: string[];
+} | {
+    type: "archive";
+    key: string;
+    existing: ServerCondition;
+};
+interface DiffResult {
+    resourceOps: ResourceOp[];
+    roleOps: RoleOp[];
+    conditionOps: ConditionOp[];
+    hasDestructive: boolean;
+}
+/** Simple 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;
+
+interface RbacSyncClientConfig {
+    baseUrl: string;
+    apiKey: string;
+}
+interface ApplyResult {
+    created: string[];
+    updated: string[];
+    archived: string[];
+    renamed: string[];
+    warnings: string[];
+}
+declare class RbacSyncClient {
+    private baseUrl;
+    private apiKey;
+    constructor(config: RbacSyncClientConfig);
+    private request;
+    getState(): Promise<ServerState>;
+    getMemberCounts(): Promise<Record<string, number>>;
+    apply(config: RbacConfig, force: boolean): Promise<ApplyResult>;
+}
+
+declare function formatRbacDiff(diff: DiffResult, dryRun: boolean): string;
+
+/**
+ * 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.
+ *
+ * @example
+ * ```ts
+ * 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 },
+ *       },
+ *     },
+ *     viewer: {
+ *       name: "Viewer",
+ *       grants: {
+ *         documents: { read: true },
+ *       },
+ *     },
+ *   },
+ * });
+ *
+ * rbac.resources.documents.key           // "documents"
+ * rbac.resources.documents.actions.read  // "documents:read"
+ * rbac.roles.admin.key                   // "admin"
+ * rbac.roles.admin.name                  // "Admin"
+ * rbac.permissions.documents.write       // "documents:write"
+ * ```
+ */
+declare function defineRbac<const T extends RbacConfig>(config: T): 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 };

package/dist/index.mjs

@@ -0,0 +1,49 @@
+import {
+  RbacSyncClient,
+  computeRbacDiff,
+  formatRbacDiff,
+  hashConditionSource,
+  loadRbacConfig,
+  validateRbacConfig
+} from "./chunk-HE57TIQI.mjs";
+
+// src/index.ts
+function defineRbac(config) {
+  const resources = {};
+  for (const [key, resource] of Object.entries(config.resources)) {
+    const actions = {};
+    for (const action of resource.actions) {
+      actions[action] = `${key}:${action}`;
+    }
+    resources[key] = { key, actions };
+  }
+  const roles = {};
+  for (const [key, role] of Object.entries(config.roles)) {
+    roles[key] = { key, name: role.name, grants: role.grants };
+  }
+  const permissions = {};
+  for (const [key, resource] of Object.entries(config.resources)) {
+    const perms = {};
+    for (const action of resource.actions) {
+      perms[action] = `${key}:${action}`;
+    }
+    permissions[key] = perms;
+  }
+  return {
+    _config: config,
+    _types: void 0,
+    // phantom -- never read at runtime
+    resources,
+    roles,
+    permissions
+  };
+}
+export {
+  RbacSyncClient,
+  computeRbacDiff,
+  defineRbac,
+  formatRbacDiff,
+  hashConditionSource,
+  loadRbacConfig,
+  validateRbacConfig
+};