{"_id":"@aldanacode/rbac","name":"@aldanacode/rbac","dist-tags":{"latest":"0.3.1"},"versions":{"0.3.1":{"name":"@aldanacode/rbac","version":"0.3.1","description":"Type-safe RBAC authorization library for TypeScript applications.","repository":{"type":"git","url":"git+https://github.com/AldanaCode/-aldanacode-rbac.git"},"bugs":{"url":"https://github.com/AldanaCode/-aldanacode-rbac/issues"},"homepage":"https://github.com/AldanaCode/-aldanacode-rbac#readme","publishConfig":{"access":"public"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./redis":{"types":"./dist/redis.d.ts","import":"./dist/redis.js"}},"scripts":{"build":"tsup","dev":"tsup --watch","test":"vitest run","test:watch":"vitest","typecheck":"tsc --noEmit","lint":"eslint .","format":"prettier --write ."},"keywords":["rbac","authorization","access-control","typescript","security"],"license":"MIT","devDependencies":{"@eslint/js":"^10.0.1","@types/node":"^26.4.0","eslint":"^10.9.1","prettier":"^3.9.6","tsup":"^8.5.1","typescript":"5.7.3","typescript-eslint":"^8.69.0","vitest":"^4.1.11"},"dependencies":{"ioredis":"^6.0.0"},"_id":"@aldanacode/rbac@0.3.1","gitHead":"05ad0998b42a7a66ea1bdbae64546bf4ba916177","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-JEI/C1Wnolts2NEiAK57S5aV/Jw9Rg47mxViPiqFot+Tz4nuyoNVQ0yTNC3HziuXOQSoURF3AXjBMrPnBluE1Q==","shasum":"c338791c985aa7de949277026f4ce51b0ade174b","tarball":"https://registry.npmjs.org/@aldanacode/rbac/-/rbac-0.3.1.tgz","fileCount":12,"unpackedSize":36536,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFPWA94y697Dptv3ZenjJlATKh0dEWXIXMG4cipQxbFYAiBZtatDT4Jw/GD1S1b0XGw1l0nO7MBxjJI42ERQGEhftQ=="}]},"_npmUser":{"name":"aldanacode","email":"pedroaldana987@gmail.com"},"directories":{},"maintainers":[{"name":"aldanacode","email":"pedroaldana987@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rbac_0.3.1_1788363667974_0.7419875700402754"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-02T15:41:07.719Z","0.3.1":"2026-09-02T15:41:08.110Z","modified":"2026-09-02T15:41:08.359Z"},"maintainers":[{"name":"aldanacode","email":"pedroaldana987@gmail.com"}],"description":"Type-safe RBAC authorization library for TypeScript applications.","homepage":"https://github.com/AldanaCode/-aldanacode-rbac#readme","keywords":["rbac","authorization","access-control","typescript","security"],"repository":{"type":"git","url":"git+https://github.com/AldanaCode/-aldanacode-rbac.git"},"bugs":{"url":"https://github.com/AldanaCode/-aldanacode-rbac/issues"},"license":"MIT","readme":"# @aldanacode/rbac\r\n\r\nType-safe Role-Based Access Control (RBAC) library for TypeScript applications.\r\n\r\n`@aldanacode/rbac` provides a lightweight authorization core based on roles and permissions, with support for in-memory persistence and Redis adapters.\r\n\r\n## Features\r\n\r\n- 🔐 Role-Based Access Control\r\n- 🧩 Type-safe permissions with TypeScript\r\n- 💾 In-memory repositories\r\n- ⚡ Redis persistence adapter\r\n- 🔌 Repository-based architecture\r\n- 🏗️ Dependency injection\r\n- 🧪 Unit and integration tests\r\n- 📦 ESM package\r\n- 🐳 Docker Compose setup for local Redis development\r\n\r\n## Installation\r\n\r\n```bash\r\npnpm add @aldanacode/rbac\r\n```\r\n\r\nOr with npm:\r\n\r\n```bash\r\nnpm install @aldanacode/rbac\r\n```\r\n\r\n## Basic Usage\r\n\r\nDefine the permissions supported by your application:\r\n\r\n```typescript\r\ntype Permissions = {\r\n  \"users:create\": unknown;\r\n  \"users:read\": unknown;\r\n  \"users:update\": unknown;\r\n  \"users:delete\": unknown;\r\n  \"reports:read\": unknown;\r\n};\r\n```\r\n\r\nCreate an RBAC instance:\r\n\r\n```typescript\r\nimport { RBAC } from \"@aldanacode/rbac\";\r\n\r\nconst rbac = new RBAC<Permissions>();\r\n```\r\n\r\nCreate a role:\r\n\r\n```typescript\r\nawait rbac.addRole(\"admin\", [\r\n  \"users:create\",\r\n  \"users:read\",\r\n  \"users:update\",\r\n  \"users:delete\",\r\n  \"reports:read\",\r\n]);\r\n```\r\n\r\nCreate a user:\r\n\r\n```typescript\r\nawait rbac.createUser(\"user-1\");\r\n```\r\n\r\nAssign the role:\r\n\r\n```typescript\r\nawait rbac.assignRole(\"user-1\", \"admin\");\r\n```\r\n\r\nCheck authorization:\r\n\r\n```typescript\r\nconst allowed = await rbac.can(\r\n  \"user-1\",\r\n  \"users:create\"\r\n);\r\n\r\nconsole.log(allowed); // true\r\n```\r\n\r\n## Type-Safe Permissions\r\n\r\nPermissions are validated at compile time.\r\n\r\nFor example, given:\r\n\r\n```typescript\r\ntype Permissions = {\r\n  \"users:create\": unknown;\r\n  \"users:read\": unknown;\r\n};\r\n```\r\n\r\nThis is valid:\r\n\r\n```typescript\r\nawait rbac.can(\"user-1\", \"users:create\");\r\n```\r\n\r\nWhile this will be rejected by TypeScript:\r\n\r\n```typescript\r\nawait rbac.can(\"user-1\", \"users:cretae\");\r\n```\r\n\r\nThis helps prevent authorization bugs caused by misspelled permission names.\r\n\r\n## Redis Adapter\r\n\r\nRedis support is available through the dedicated `/redis` entry point.\r\n\r\nInstall the required packages:\r\n\r\n```bash\r\npnpm add @aldanacode/rbac ioredis\r\n```\r\n\r\nCreate a Redis client and repositories:\r\n\r\n```typescript\r\nimport {\r\n  createRedisClient,\r\n  RedisRoleRepository,\r\n  RedisUserRepository,\r\n} from \"@aldanacode/rbac/redis\";\r\n\r\nconst redis = createRedisClient({\r\n  url: \"redis://localhost:6379\",\r\n});\r\n\r\nconst roleRepository = new RedisRoleRepository(redis);\r\nconst userRepository = new RedisUserRepository(redis);\r\n```\r\n\r\nInject the repositories into RBAC:\r\n\r\n```typescript\r\nimport { RBAC } from \"@aldanacode/rbac\";\r\n\r\nconst rbac = new RBAC<Permissions>({\r\n  roleRepository,\r\n  userRepository,\r\n});\r\n```\r\n\r\nThe authorization layer remains independent of Redis.\r\n\r\nThe persistence mechanism can therefore be changed without modifying the domain authorization logic.\r\n\r\n## Repository Architecture\r\n\r\nThe library separates authorization logic from persistence through repository contracts.\r\n\r\n```text\r\n                    ┌─────────────────────┐\r\n                    │        RBAC         │\r\n                    │   Application API   │\r\n                    └──────────┬──────────┘\r\n                               │\r\n                               ▼\r\n                    ┌─────────────────────┐\r\n                    │ AuthorizationService│\r\n                    └──────────┬──────────┘\r\n                               │\r\n                     ┌─────────┴─────────┐\r\n                     │                   │\r\n                     ▼                   ▼\r\n              UserRepository      RoleRepository\r\n                     │                   │\r\n             ┌───────┴───────┐   ┌─────┴──────┐\r\n             │               │   │            │\r\n             ▼               ▼   ▼            ▼\r\n          InMemory          Redis            ...\r\n```\r\n\r\nThis allows infrastructure adapters to implement the same repository contracts without coupling the domain to a specific persistence technology.\r\n\r\n## Redis Development\r\n\r\nA local Redis instance can be started using Docker Compose:\r\n\r\n```bash\r\ndocker compose up -d\r\n```\r\n\r\nCheck the Redis connection:\r\n\r\n```bash\r\ndocker exec aldanacode-rbac-redis redis-cli ping\r\n```\r\n\r\nExpected response:\r\n\r\n```text\r\nPONG\r\n```\r\n\r\nStop the development environment:\r\n\r\n```bash\r\ndocker compose down\r\n```\r\n\r\n## Testing\r\n\r\nRun the test suite:\r\n\r\n```bash\r\npnpm test\r\n```\r\n\r\nRun TypeScript type checking:\r\n\r\n```bash\r\npnpm typecheck\r\n```\r\n\r\nBuild the package:\r\n\r\n```bash\r\npnpm build\r\n```\r\n\r\nThe project includes:\r\n\r\n- Core RBAC tests\r\n- Type-safety tests\r\n- Redis repository tests\r\n- Redis integration tests\r\n\r\n## Package Exports\r\n\r\nThe core API is available from:\r\n\r\n```typescript\r\nimport {\r\n  RBAC,\r\n  Role,\r\n  Permission,\r\n  User,\r\n  AuthorizationService,\r\n} from \"@aldanacode/rbac\";\r\n```\r\n\r\nRedis infrastructure is available separately:\r\n\r\n```typescript\r\nimport {\r\n  createRedisClient,\r\n  RedisRoleRepository,\r\n  RedisUserRepository,\r\n} from \"@aldanacode/rbac/redis\";\r\n```\r\n\r\nKeeping Redis in a dedicated entry point prevents infrastructure concerns from being coupled to the core API.\r\n\r\n## Design Principles\r\n\r\nThe project follows several core principles:\r\n\r\n- Separation of concerns\r\n- Dependency inversion\r\n- Explicit infrastructure boundaries\r\n- Type safety\r\n- Small public API\r\n- Testability\r\n- Pragmatic Clean Architecture\r\n\r\nThe goal is to provide a lightweight authorization core that can evolve without coupling applications to a specific persistence technology.\r\n\r\n## Roadmap\r\n\r\n### v0.1.0\r\n\r\n- Core RBAC\r\n- Roles\r\n- Permissions\r\n- Users\r\n- In-memory repositories\r\n\r\n### v0.2.0\r\n\r\n- Type-safe permissions\r\n\r\n### v0.3.0\r\n\r\n- Redis adapter\r\n- Redis repositories\r\n- Redis integration tests\r\n- Docker development environment\r\n\r\n### v0.4.0\r\n\r\n- Policy engine\r\n- Attribute-Based Access Control (ABAC)\r\n\r\n### v0.5.0\r\n\r\n- Multi-tenancy\r\n\r\n### v1.0.0\r\n\r\n- Stable public API\r\n- Production-ready release\r\n\r\n## License\r\n\r\nMIT © AldanaCode\r\n","readmeFilename":"README.md","_rev":"1-21f6e6f38a64b10cc87247e7937b8815"}