@krutai/rbac 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,390 @@
+export { ApiKeyValidationError, createApiKeyChecker, validateApiKeyFormat, validateApiKeyWithService } from 'krutai';
+
+/**
+ * Core type definitions for @krutai/rbac
+ */
+/**
+ * A permission string in the format "resource:action"
+ * Examples: "posts:read", "users:delete", "admin:manage"
+ */
+type Permission = string;
+/**
+ * A role definition with its associated permissions and optional inheritance
+ */
+interface Role {
+    /** Unique name for this role */
+    name: string;
+    /** List of permissions granted to this role */
+    permissions: Permission[];
+    /** Names of roles whose permissions this role inherits */
+    inherits?: string[];
+    /** Human-readable description of this role */
+    description?: string;
+}
+/**
+ * Configuration for the RBACManager
+ */
+interface RBACConfig {
+    /** Initial set of roles to register */
+    roles: Role[];
+    /** Name of the role assigned to users with no explicit role */
+    defaultRole?: string;
+}
+/**
+ * Options for permission checks
+ */
+interface CheckOptions {
+    /**
+     * When checking multiple permissions:
+     * - true  → user must have ALL permissions (AND)
+     * - false → user must have AT LEAST ONE permission (OR)
+     * @default false
+     */
+    requireAll?: boolean;
+}
+/**
+ * The context object representing the current user/request being checked
+ */
+interface RBACContext {
+    /** Optional identifier for the user */
+    userId?: string;
+    /** List of role names assigned to this user */
+    roles: string[];
+    /** Optional arbitrary metadata for custom logic */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Result of a permission check with additional details
+ */
+interface PermissionCheckResult {
+    /** Whether the check passed */
+    granted: boolean;
+    /** The permission(s) that were checked */
+    permissions: Permission[];
+    /** The roles that were evaluated */
+    roles: string[];
+    /** Which permissions were missing (if denied) */
+    missing?: Permission[];
+}
+/**
+ * A guard function that takes a context and returns whether access is granted
+ */
+type GuardFn = (context: RBACContext) => boolean;
+/**
+ * A middleware-style handler function
+ */
+type HandlerFn<TContext = unknown, TResult = unknown> = (context: TContext) => TResult | Promise<TResult>;
+/**
+ * A middleware-style deny handler
+ */
+type DenyHandlerFn<TContext = unknown, TResult = unknown> = (context: TContext, permission: Permission) => TResult | Promise<TResult>;
+
+/**
+ * RBACManager — core class for role-based access control
+ */
+
+/**
+ * The main RBAC engine. Manages roles, resolves inheritance chains,
+ * and evaluates permission checks against a user context.
+ *
+ * @example
+ * const rbac = new RBACManager({
+ *   roles: [
+ *     { name: 'user', permissions: ['posts:read'] },
+ *     { name: 'admin', permissions: ['posts:delete'], inherits: ['user'] },
+ *   ],
+ * });
+ *
+ * const ctx = { roles: ['admin'] };
+ * rbac.can(ctx, 'posts:read');   // true (inherited from user)
+ * rbac.can(ctx, 'posts:delete'); // true
+ * rbac.can(ctx, 'users:manage'); // false
+ */
+declare class RBACManager {
+    private readonly roles;
+    private readonly defaultRole?;
+    /** Cache of resolved permissions per role to avoid repeated traversal */
+    private readonly permissionCache;
+    constructor(config: RBACConfig);
+    /**
+     * Register a new role. Clears the permission cache.
+     */
+    addRole(role: Role): void;
+    /**
+     * Remove a role by name. Clears the permission cache.
+     * @throws {RoleNotFoundError} if the role does not exist
+     */
+    removeRole(name: string): void;
+    /**
+     * Retrieve a role definition by name.
+     */
+    getRole(name: string): Role | undefined;
+    /**
+     * Returns all registered roles as an array.
+     */
+    getAllRoles(): Role[];
+    /**
+     * Resolves the full set of permissions for a single role,
+     * including all inherited permissions (with cycle detection).
+     *
+     * @throws {RoleNotFoundError} if the role does not exist
+     * @throws {CircularInheritanceError} if a circular inheritance chain is detected
+     */
+    getPermissionsForRole(roleName: string): Set<Permission>;
+    /**
+     * Resolves the union of all permissions across multiple roles.
+     */
+    getPermissionsForRoles(roleNames: string[]): Set<Permission>;
+    /**
+     * Check whether the context has a specific permission.
+     * Supports wildcard permissions (e.g. "*:*" or "posts:*").
+     */
+    hasPermission(context: RBACContext, permission: Permission, _opts?: CheckOptions): boolean;
+    /**
+     * Check whether the context has AT LEAST ONE of the given permissions.
+     */
+    hasAnyPermission(context: RBACContext, permissions: Permission[]): boolean;
+    /**
+     * Check whether the context has ALL of the given permissions.
+     */
+    hasAllPermissions(context: RBACContext, permissions: Permission[]): boolean;
+    /**
+     * Check whether the context has a specific role assigned.
+     */
+    hasRole(context: RBACContext, roleName: string): boolean;
+    /**
+     * Check whether the context has AT LEAST ONE of the given roles.
+     */
+    hasAnyRole(context: RBACContext, roleNames: string[]): boolean;
+    /**
+     * Alias for `hasPermission`. Reads naturally in conditional expressions.
+     *
+     * @example
+     * if (rbac.can(ctx, 'posts:delete')) { ... }
+     */
+    can(context: RBACContext, permission: Permission): boolean;
+    /**
+     * Inverse of `can`. Reads naturally in guard expressions.
+     *
+     * @example
+     * if (rbac.cannot(ctx, 'posts:delete')) throw new PermissionDeniedError(...);
+     */
+    cannot(context: RBACContext, permission: Permission): boolean;
+    /**
+     * Detailed permission check that returns a result object with context.
+     */
+    check(context: RBACContext, permissions: Permission[], opts?: CheckOptions): PermissionCheckResult;
+    private resolveContextRoles;
+    private resolvePermissions;
+    /**
+     * Matches a required permission against the user's permission set,
+     * supporting wildcard segments ("*").
+     *
+     * Wildcard rules:
+     * - "*:*"       matches everything
+     * - "posts:*"   matches any action on "posts"
+     * - "*:read"    matches "read" on any resource
+     */
+    private matchPermission;
+}
+
+/**
+ * Role and permission definition helpers for @krutai/rbac
+ */
+
+/**
+ * Type-safe helper to define a role.
+ * Useful for getting autocomplete and validation when building role configs.
+ *
+ * @example
+ * const editorRole = defineRole({
+ *   name: 'editor',
+ *   permissions: ['posts:read', 'posts:write'],
+ *   inherits: ['user'],
+ * });
+ */
+declare function defineRole(config: Role): Role;
+/**
+ * Creates a typed permission string in the format "resource:action".
+ *
+ * @example
+ * const canReadPosts = definePermission('posts', 'read'); // "posts:read"
+ * const canDeleteUsers = definePermission('users', 'delete'); // "users:delete"
+ */
+declare function definePermission(resource: string, action: string): Permission;
+/**
+ * Creates a set of CRUD permissions for a given resource.
+ *
+ * @example
+ * const postPermissions = crudPermissions('posts');
+ * // ["posts:create", "posts:read", "posts:update", "posts:delete"]
+ */
+declare function crudPermissions(resource: string): Permission[];
+/**
+ * Creates a wildcard permission for a resource (grants all actions).
+ *
+ * @example
+ * wildcardPermission('posts') // "posts:*"
+ */
+declare function wildcardPermission(resource: string): Permission;
+/**
+ * Guest role — read-only access to public resources
+ */
+declare const GUEST_ROLE: Role;
+/**
+ * User role — standard authenticated user
+ */
+declare const USER_ROLE: Role;
+/**
+ * Moderator role — can manage user-generated content
+ */
+declare const MODERATOR_ROLE: Role;
+/**
+ * Admin role — full control over application resources
+ */
+declare const ADMIN_ROLE: Role;
+/**
+ * Super Admin role — unrestricted access to everything
+ */
+declare const SUPER_ADMIN_ROLE: Role;
+/**
+ * All pre-built roles in hierarchy order (least → most privileged)
+ */
+declare const DEFAULT_ROLES: Role[];
+
+/**
+ * Guard and middleware helpers for @krutai/rbac
+ *
+ * These utilities make it easy to integrate RBAC checks into
+ * request handlers, middleware chains, and framework-agnostic guards.
+ */
+
+/**
+ * Creates a guard function that checks a single permission.
+ *
+ * @example
+ * const canDeletePosts = createPermissionGuard(rbac, 'posts:delete');
+ * if (!canDeletePosts(ctx)) throw new PermissionDeniedError('posts:delete', ctx.roles);
+ */
+declare function createPermissionGuard(rbac: RBACManager, permission: Permission): GuardFn;
+/**
+ * Creates a guard function that checks whether the context has a specific role.
+ *
+ * @example
+ * const isAdmin = createRoleGuard(rbac, 'admin');
+ * if (!isAdmin(ctx)) throw new PermissionDeniedError('admin role', ctx.roles);
+ */
+declare function createRoleGuard(rbac: RBACManager, roleName: string): GuardFn;
+/**
+ * Creates a guard that requires ALL of the given permissions.
+ *
+ * @example
+ * const canManagePosts = createAllPermissionsGuard(rbac, ['posts:read', 'posts:delete']);
+ */
+declare function createAllPermissionsGuard(rbac: RBACManager, permissions: Permission[]): GuardFn;
+/**
+ * Creates a guard that requires AT LEAST ONE of the given permissions.
+ *
+ * @example
+ * const canViewContent = createAnyPermissionGuard(rbac, ['posts:read', 'drafts:read']);
+ */
+declare function createAnyPermissionGuard(rbac: RBACManager, permissions: Permission[]): GuardFn;
+/**
+ * Wraps a handler function with a permission check.
+ * Calls `onDenied` (or throws `PermissionDeniedError`) if the check fails.
+ *
+ * @example
+ * const deletePost = withPermission(
+ *   rbac,
+ *   'posts:delete',
+ *   async (ctx) => { await db.posts.delete(ctx.postId); },
+ *   (ctx, perm) => { throw new Error(`Forbidden: ${perm}`); }
+ * );
+ */
+declare function withPermission<TContext extends {
+    rbac: RBACContext;
+}, TResult>(rbac: RBACManager, permission: Permission, handler: HandlerFn<TContext, TResult>, onDenied?: DenyHandlerFn<TContext, TResult>): HandlerFn<TContext, TResult>;
+/**
+ * Represents a minimal Express/Next.js-style request with an `rbacContext` property.
+ * Attach an `RBACContext` to your request object before using this middleware.
+ */
+interface RBACRequest {
+    rbacContext?: RBACContext;
+}
+/**
+ * Express/Next.js-compatible middleware factory.
+ * Expects `req.rbacContext` to be populated by a preceding auth middleware.
+ *
+ * @example
+ * // Express
+ * app.delete('/posts/:id', requirePermission(rbac, 'posts:delete'), deletePostHandler);
+ *
+ * @example
+ * // Next.js API route (pages router)
+ * export default requirePermission(rbac, 'posts:delete')(handler);
+ */
+declare function requirePermission(rbac: RBACManager, permission: Permission): (req: RBACRequest, res: {
+    status: (code: number) => {
+        json: (body: unknown) => void;
+    };
+}, next: () => void) => void;
+/**
+ * Express/Next.js-compatible middleware factory for role checks.
+ *
+ * @example
+ * app.get('/admin', requireRole(rbac, 'admin'), adminHandler);
+ */
+declare function requireRole(rbac: RBACManager, roleName: string): (req: RBACRequest, res: {
+    status: (code: number) => {
+        json: (body: unknown) => void;
+    };
+}, next: () => void) => void;
+
+/**
+ * Custom error classes for @krutai/rbac
+ */
+/**
+ * Base error class for all RBAC-related errors
+ */
+declare class RBACError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when a user lacks the required permission to perform an action
+ */
+declare class PermissionDeniedError extends RBACError {
+    /** The permission that was required but not held */
+    readonly permission: string;
+    /** The roles that were evaluated */
+    readonly roles: string[];
+    constructor(permission: string, roles: string[]);
+}
+/**
+ * Thrown when a referenced role does not exist in the registry
+ */
+declare class RoleNotFoundError extends RBACError {
+    /** The name of the role that was not found */
+    readonly roleName: string;
+    constructor(roleName: string);
+}
+/**
+ * Thrown when a circular inheritance chain is detected in role definitions
+ */
+declare class CircularInheritanceError extends RBACError {
+    /** The chain of roles that form the cycle */
+    readonly chain: string[];
+    constructor(chain: string[]);
+}
+
+/**
+ * @krutai/rbac — Role-Based Access Control for KrutAI
+ *
+ * A flexible, type-safe RBAC library with role inheritance,
+ * wildcard permissions, and framework-agnostic guard helpers.
+ *
+ * @packageDocumentation
+ */
+
+declare const VERSION = "0.1.0";
+
+export { ADMIN_ROLE, type CheckOptions, CircularInheritanceError, DEFAULT_ROLES, type DenyHandlerFn, GUEST_ROLE, type GuardFn, type HandlerFn, MODERATOR_ROLE, type Permission, type PermissionCheckResult, PermissionDeniedError, type RBACConfig, type RBACContext, RBACError, RBACManager, type RBACRequest, type Role, RoleNotFoundError, SUPER_ADMIN_ROLE, USER_ROLE, VERSION, createAllPermissionsGuard, createAnyPermissionGuard, createPermissionGuard, createRoleGuard, crudPermissions, definePermission, defineRole, requirePermission, requireRole, wildcardPermission, withPermission };