@itboxful/typed-perms

Libreria para manejar permisos con YAML y TypeScript.

Que problema resuelve?

Evitamos hardcodear permisos. Tenerlos en base de datos tambien desenvuelve problemas para micro-servicios que pueden querer compartir permisos. Esta libreria te deja definirlos en YAML y te da un cliente para chequearlos.

Para que proyectos sirve?

Cualquier backend Node.js/NestJS que necesite RBAC.

Instalacion

yarn add @itboxful/typed-perms

Uso basico

1. Defines permisos en YAML

# permissions/core.yaml
module: core

permissions:
  clients:
    view: null
    create: null
    delete: null

roles:
  admin:
    - core.clients.*
  viewer:
    - core.clients.view

2. Creas el cliente

import { createPermissions } from '@itboxful/typed-perms';

const perms = await createPermissions({ path: './permissions' });

3. Chequeas permisos

const user = {
  roles: ['viewer'],
  entitlements: { add: [], deny: [] }
};

perms.can(user, 'core.clients.view');    // true
perms.can(user, 'core.clients.delete');  // false

Wildcards

Podes usar * al final para darle a un rol todos los permisos de un recurso:

roles:
  admin:
    - core.clients.*     # todos los permisos de clients
    - core.reports.*     # todos los permisos de reports
  viewer:
    - core.clients.view  # solo este permiso

Los wildcards se expanden cuando carga el YAML. Si despues llamas rolePermissions('admin'), ves los permisos reales, no el wildcard.

Prioridad

deny > add > rol

Si esta en deny, el permiso NO lo tiene.

const user = {
  roles: ['admin'],
  entitlements: {
    deny: ['core.clients.delete']
  }
};

perms.can(user, 'core.clients.delete');  // false (aunque es admin)

API del cliente

perms.can(user, 'permiso')      // tiene el permiso?
perms.resolve(user)             // todos sus permisos efectivos
perms.rolePermissions('admin')  // permisos del rol
perms.exists('permiso')         // existe el permiso?
perms.allPermissions()          // todos los permisos definidos
perms.allRoles()                // todos los roles definidos
perms.reload()                  // recarga los YAML

Tipos

type Permission = string;  // 'module.resource.action'
type Role = string;        // 'admin', 'viewer', etc

interface PermissionContext {
  roles: Role[];
  entitlements?: {
    add?: Permission[];
    deny?: Permission[];
  };
}

Errores

| Error | Cuando | |-------|--------| | PermissionNotFoundError | El permiso no existe | | RoleNotDefinedError | El rol no existe | | DefinitionsLoadError | Error cargando YAML | | InvalidPermissionFormatError | Formato invalido |