@krutai/rbac 0.1.1

package/AI_REFERENCE.md

@@ -0,0 +1,140 @@
+# AI Reference — @krutai/rbac
+
+## Package Overview
+- **Name**: `@krutai/rbac`
+- **Version**: `0.1.1`
+- **Purpose**: Role-Based Access Control (RBAC) library for KrutAI
+- **Entry**: `src/index.ts` → `dist/index.{js,mjs,d.ts}`
+- **Build**: `tsup` (CJS + ESM dual output, `krutai` is external peer dep)
+
+## Dependency Architecture
+
+```
+@krutai/rbac@0.1.1
+├── peerDependency: krutai >=0.1.2   ← auto-installed, provides API validation
+└── peerDependency: @krutai/auth >=0.1.0  ← optional
+```
+
+> **Important for AI**: The validator (`validateApiKeyFormat`, `ApiKeyValidationError`, etc.) is NOT defined in this package. It is imported from `krutai` and re-exported. Do NOT add a local `validator.ts` here.
+
+## File Structure
+```
+packages/rbac/
+├── src/
+│   ├── index.ts     # Barrel export (all public API)
+│   ├── types.ts     # Core TypeScript interfaces and types
+│   ├── errors.ts    # Custom error classes
+│   ├── role.ts      # Role/permission helpers + pre-built roles
+│   ├── rbac.ts      # RBACManager class (core engine)
+│   └── guards.ts    # Guard factories + Express/Next.js middleware
+├── package.json
+├── tsconfig.json
+└── tsup.config.ts
+```
+
+## Key Exports
+
+### Classes
+- `RBACManager` — main RBAC engine
+
+### Types
+- `Permission` — `string` alias for `"resource:action"` format
+- `Role` — `{ name, permissions, inherits?, description? }`
+- `RBACConfig` — `{ roles, defaultRole? }`
+- `RBACContext` — `{ userId?, roles, metadata? }`
+- `CheckOptions` — `{ requireAll?: boolean }`
+- `PermissionCheckResult` — `{ granted, permissions, roles, missing? }`
+- `GuardFn` — `(context: RBACContext) => boolean`
+
+### Helpers
+- `defineRole(config)` — type-safe role definition
+- `definePermission(resource, action)` — creates `"resource:action"` string
+- `crudPermissions(resource)` — creates `[create, read, update, delete]` permissions
+- `wildcardPermission(resource)` — creates `"resource:*"`
+
+### Pre-built Roles
+- `GUEST_ROLE`, `USER_ROLE`, `MODERATOR_ROLE`, `ADMIN_ROLE`, `SUPER_ADMIN_ROLE`
+- `DEFAULT_ROLES` — array of all five in hierarchy order
+
+### Guard Factories
+- `createPermissionGuard(rbac, permission)` → `GuardFn`
+- `createRoleGuard(rbac, roleName)` → `GuardFn`
+- `createAllPermissionsGuard(rbac, permissions[])` → `GuardFn`
+- `createAnyPermissionGuard(rbac, permissions[])` → `GuardFn`
+
+### Middleware
+- `requirePermission(rbac, permission)` — Express/Next.js middleware
+- `requireRole(rbac, roleName)` — Express/Next.js middleware
+- `withPermission(rbac, permission, handler, onDenied?)` — handler wrapper
+
+### Errors
+- `RBACError` — base class
+- `PermissionDeniedError(permission, roles)` — access denied
+- `RoleNotFoundError(roleName)` — role not in registry
+- `CircularInheritanceError(chain)` — circular role inheritance
+
+### Validator Re-exports (from `krutai`)
+```typescript
+// These are re-exported from krutai — NOT defined here
+export { validateApiKeyFormat, validateApiKeyWithService, createApiKeyChecker, ApiKeyValidationError } from 'krutai';
+```
+
+## RBACManager API Summary
+
+```typescript
+// Construction
+new RBACManager({ roles: Role[], defaultRole?: string })
+
+// Role management
+.addRole(role: Role): void
+.removeRole(name: string): void          // throws RoleNotFoundError
+.getRole(name: string): Role | undefined
+.getAllRoles(): Role[]
+
+// Permission resolution
+.getPermissionsForRole(name: string): Set<Permission>   // throws RoleNotFoundError
+.getPermissionsForRoles(names: string[]): Set<Permission>
+
+// Checks
+.can(ctx, permission): boolean
+.cannot(ctx, permission): boolean
+.hasPermission(ctx, permission, opts?): boolean
+.hasAnyPermission(ctx, permissions[]): boolean
+.hasAllPermissions(ctx, permissions[]): boolean
+.hasRole(ctx, roleName): boolean
+.hasAnyRole(ctx, roleNames[]): boolean
+.check(ctx, permissions[], opts?): PermissionCheckResult
+```
+
+## Wildcard Permission Rules
+- `*:*` or `*` → matches any permission
+- `posts:*` → matches any action on `posts` resource
+- `*:read` → matches `read` on any resource
+
+## Role Inheritance
+Permissions are resolved recursively. Cycles throw `CircularInheritanceError`.
+Results are cached per role name for performance.
+
+## Middleware Contract
+`requirePermission` / `requireRole` expect `req.rbacContext: RBACContext` to be set
+by a preceding auth middleware. Returns 401 if missing, 403 if denied.
+
+## tsup Configuration Notes
+- `krutai` → external (peer dep, NOT bundled — do NOT add to `noExternal`)
+- No other special external/noExternal rules
+
+## Important Notes
+
+1. **Validator lives in `krutai`**: Never add a local `validator.ts` — import from `krutai`
+2. **`krutai` must be external in tsup**: Do NOT add it to `noExternal`
+3. **`krutai` in devDependencies**: Needed for local TypeScript compilation during development
+
+## Related Packages
+
+- `krutai` — Core utilities and API validation (peer dep)
+- `@krutai/auth` — Authentication with Better Auth (optional peer dep)
+
+## Links
+
+- GitHub: https://github.com/AccountantAIOrg/krut_packages
+- npm: https://www.npmjs.com/package/@krutai/rbac

package/README.md

@@ -0,0 +1,216 @@
+# @krutai/rbac
+
+> Role-Based Access Control (RBAC) for KrutAI — type-safe, inheritance-aware, framework-agnostic.
+
+[![npm version](https://img.shields.io/npm/v/@krutai/rbac)](https://www.npmjs.com/package/@krutai/rbac)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- ✅ **Type-safe** — full TypeScript with strict types
+- 🔗 **Role inheritance** — roles can inherit permissions from parent roles
+- 🃏 **Wildcard permissions** — `posts:*` or `*:*` for broad grants
+- 🏗️ **Pre-built roles** — `guest`, `user`, `moderator`, `admin`, `super_admin`
+- 🛡️ **Guard helpers** — framework-agnostic guard factories
+- 🔌 **Middleware** — Express / Next.js-compatible middleware factories
+- 🚨 **Descriptive errors** — `PermissionDeniedError`, `RoleNotFoundError`, `CircularInheritanceError`
+- 🔑 **API Key Validation** — re-exported from `krutai` (auto-installed as peer dep)
+
+---
+
+## Installation
+
+```bash
+npm install @krutai/rbac
+# or
+bun add @krutai/rbac
+```
+
+> **Note:** `krutai` is automatically installed as a peer dependency — no extra steps needed.
+
+---
+
+## Quick Start
+
+```typescript
+import { RBACManager, defineRole, definePermission } from '@krutai/rbac';
+
+// 1. Define your roles
+const rbac = new RBACManager({
+  roles: [
+    defineRole({
+      name: 'user',
+      permissions: ['posts:read', 'posts:create'],
+    }),
+    defineRole({
+      name: 'admin',
+      permissions: ['posts:delete', 'users:manage'],
+      inherits: ['user'], // inherits all user permissions
+    }),
+  ],
+  defaultRole: 'user',
+});
+
+// 2. Build a context from your auth session
+const ctx = { userId: 'u_123', roles: ['admin'] };
+
+// 3. Check permissions
+rbac.can(ctx, 'posts:read');    // true (inherited from user)
+rbac.can(ctx, 'posts:delete'); // true
+rbac.can(ctx, 'billing:read'); // false
+rbac.cannot(ctx, 'billing:read'); // true
+```
+
+---
+
+## Core API
+
+### `RBACManager`
+
+```typescript
+const rbac = new RBACManager(config: RBACConfig);
+```
+
+#### Role Management
+
+| Method | Description |
+|--------|-------------|
+| `addRole(role)` | Register a new role |
+| `removeRole(name)` | Remove a role by name |
+| `getRole(name)` | Get a role definition |
+| `getAllRoles()` | List all registered roles |
+
+#### Permission Resolution
+
+| Method | Description |
+|--------|-------------|
+| `getPermissionsForRole(name)` | Resolved `Set<Permission>` for a role (includes inherited) |
+| `getPermissionsForRoles(names[])` | Union of permissions across multiple roles |
+
+#### Permission Checks
+
+| Method | Description |
+|--------|-------------|
+| `can(ctx, permission)` | Returns `true` if context has the permission |
+| `cannot(ctx, permission)` | Inverse of `can` |
+| `hasPermission(ctx, permission)` | Same as `can` |
+| `hasAnyPermission(ctx, permissions[])` | True if context has ≥1 permission |
+| `hasAllPermissions(ctx, permissions[])` | True if context has all permissions |
+| `hasRole(ctx, roleName)` | True if context has the role |
+| `hasAnyRole(ctx, roleNames[])` | True if context has ≥1 role |
+| `check(ctx, permissions[], opts?)` | Detailed result with `granted`, `missing` |
+
+---
+
+## Permission Strings
+
+Permissions follow the `resource:action` convention:
+
+```typescript
+import { definePermission, crudPermissions, wildcardPermission } from '@krutai/rbac';
+
+definePermission('posts', 'read')   // "posts:read"
+crudPermissions('posts')            // ["posts:create", "posts:read", "posts:update", "posts:delete"]
+wildcardPermission('posts')         // "posts:*"
+wildcardPermission('*')             // "*:*" — grants everything
+```
+
+---
+
+## Role Inheritance
+
+```typescript
+const rbac = new RBACManager({
+  roles: [
+    { name: 'guest',     permissions: ['public:read'] },
+    { name: 'user',      permissions: ['profile:read'], inherits: ['guest'] },
+    { name: 'moderator', permissions: ['posts:delete'], inherits: ['user'] },
+    { name: 'admin',     permissions: ['users:manage'], inherits: ['moderator'] },
+  ],
+});
+
+const ctx = { roles: ['moderator'] };
+rbac.can(ctx, 'public:read');   // true (guest → user → moderator)
+rbac.can(ctx, 'profile:read'); // true (user → moderator)
+rbac.can(ctx, 'posts:delete'); // true
+rbac.can(ctx, 'users:manage'); // false (admin only)
+```
+
+---
+
+## Pre-built Roles
+
+```typescript
+import { DEFAULT_ROLES, ADMIN_ROLE, SUPER_ADMIN_ROLE } from '@krutai/rbac';
+
+const rbac = new RBACManager({ roles: DEFAULT_ROLES });
+// Includes: guest, user, moderator, admin, super_admin
+```
+
+---
+
+## Guard Helpers
+
+```typescript
+import { createPermissionGuard, createRoleGuard } from '@krutai/rbac';
+
+const canDeletePosts = createPermissionGuard(rbac, 'posts:delete');
+const isAdmin = createRoleGuard(rbac, 'admin');
+
+canDeletePosts(ctx); // boolean
+isAdmin(ctx);        // boolean
+```
+
+---
+
+## Express / Next.js Middleware
+
+```typescript
+import { requirePermission, requireRole } from '@krutai/rbac';
+
+// Attach rbacContext in your auth middleware first:
+app.use((req, res, next) => {
+  req.rbacContext = { userId: req.user.id, roles: req.user.roles };
+  next();
+});
+
+// Then protect routes:
+app.delete('/posts/:id', requirePermission(rbac, 'posts:delete'), deleteHandler);
+app.get('/admin',        requireRole(rbac, 'admin'),              adminHandler);
+```
+
+---
+
+## Error Handling
+
+```typescript
+import { PermissionDeniedError, RoleNotFoundError } from '@krutai/rbac';
+
+try {
+  if (rbac.cannot(ctx, 'posts:delete')) {
+    throw new PermissionDeniedError('posts:delete', ctx.roles);
+  }
+} catch (err) {
+  if (err instanceof PermissionDeniedError) {
+    console.error(err.message);    // "Permission denied: ..."
+    console.error(err.permission); // "posts:delete"
+    console.error(err.roles);      // ["user"]
+  }
+}
+```
+
+---
+
+## API Key Validation
+
+`@krutai/rbac` re-exports the API key validator from `krutai`:
+
+```typescript
+import { validateApiKeyFormat, ApiKeyValidationError } from '@krutai/rbac';
+```
+
+---
+
+## License
+
+MIT © KrutAI