@core / rbac

1.0.1 ▾

1.0.1

verificadoMIT

GitHub

Roles y permisos sobre @core/auth: comodines, permisos sobre lo propio y concesiones sin escalada

Código10 archivosContexto~615 tokensescaneo superado

~615 tokens→ src/lib/rbac/AGENTS.md→ .cursor/rules/genpm-core-rbac.mdc

Esto es exactamente lo que lee tu IA cuando trabaja en src/lib/rbac. No se añade nada más a su contexto.

@core/rbac — rules for AI agents

Purpose

Authorization on top of @core/auth users: roles stored in the database, permissions resource:action with wildcards (posts:*, *) and own-only grants (posts:update:own), and a role hierarchy (rank) that prevents privilege escalation. Default roles: owner, admin, editor, support, author. Not authentication, not multi-tenancy.

Map

index.ts — public API: can, assertCan, getGrants, grantRole, revokeRole, bootstrapOwner, defineRole, ensureDefaultRoles.
permissions.ts — pure matcher grants() (no DB).
defaults.ts — default roles and their permissions.
schema.ts — tables roles, user_roles. Depends on ../db and ../auth.
adapters/hono.ts — requirePermission(perm) middleware. adapters/next.ts — requirePermission(user, perm), permissionResponse(user, perm).
admin.ts — usersAdminResource for @core/admin (users with roles; grant/revoke actions with users:manage).

Integration

Generate and apply migrations (see src/lib/db/AGENTS.md).
At startup or in a setup script: await ensureDefaultRoles().
Make the first user owner once, e.g. in the onLogin hook of @core/auth: onLogin: async ({ user, isNewUser }) => { if (isNewUser) await bootstrapOwner(user.id); } (only the first call wins).
Hono: app.use(sessionMiddleware); app.post('/api/posts/:id/publish', requirePermission('posts:publish'), handler). Next.js: const user = await getUser(await cookies()); await requirePermission(user, 'posts:publish');
Own-only checks: await assertCan(user.id, 'posts:update', { ownerId: post.authorId }).
Verify: a user without roles gets 403; the owner gets 200.

Conventions

Permission names: lowercase resource:action (orders:refund). Actions in use: read, create, update, delete, publish, manage.
Check permissions on the server for every write and every private read; hiding UI is not authorization.
Load getGrants(userId) once per request and pass it to can() when checking several permissions.
Change roles only through grantRole/revokeRole (they enforce the hierarchy and keep at least one owner).

Don't

Don't insert into user_roles directly, and don't add an env flag or "god mode" that bypasses can().
Don't expose defineRole to users without checking users:manage and that the new rank is below the actor's.
Don't trust a role or permission sent by the client.

# @core/rbac — rules for AI agents

## Purpose
Authorization on top of @core/auth users: roles stored in the database, permissions `resource:action` with wildcards
(`posts:*`, `*`) and own-only grants (`posts:update:own`), and a role hierarchy (`rank`) that prevents privilege
escalation. Default roles: owner, admin, editor, support, author. Not authentication, not multi-tenancy.

## Map
- `index.ts` — public API: `can`, `assertCan`, `getGrants`, `grantRole`, `revokeRole`, `bootstrapOwner`, `defineRole`, `ensureDefaultRoles`.
- `permissions.ts` — pure matcher `grants()` (no DB).
- `defaults.ts` — default roles and their permissions.
- `schema.ts` — tables `roles`, `user_roles`. Depends on `../db` and `../auth`.
- `adapters/hono.ts` — `requirePermission(perm)` middleware. `adapters/next.ts` — `requirePermission(user, perm)`, `permissionResponse(user, perm)`.
- `admin.ts` — `usersAdminResource` for @core/admin (users with roles; grant/revoke actions with `users:manage`).

## Integration
1. Generate and apply migrations (see `src/lib/db/AGENTS.md`).
2. At startup or in a setup script: `await ensureDefaultRoles()`.
3. Make the first user owner once, e.g. in the `onLogin` hook of @core/auth:
   `onLogin: async ({ user, isNewUser }) => { if (isNewUser) await bootstrapOwner(user.id); }` (only the first call wins).
4. Hono: `app.use(sessionMiddleware); app.post('/api/posts/:id/publish', requirePermission('posts:publish'), handler)`.
   Next.js: `const user = await getUser(await cookies()); await requirePermission(user, 'posts:publish');`
5. Own-only checks: `await assertCan(user.id, 'posts:update', { ownerId: post.authorId })`.
6. Verify: a user without roles gets 403; the owner gets 200.

## Conventions
- Permission names: lowercase `resource:action` (`orders:refund`). Actions in use: read, create, update, delete, publish, manage.
- Check permissions on the server for every write and every private read; hiding UI is not authorization.
- Load `getGrants(userId)` once per request and pass it to `can()` when checking several permissions.
- Change roles only through `grantRole`/`revokeRole` (they enforce the hierarchy and keep at least one owner).

## Don't
- Don't insert into `user_roles` directly, and don't add an env flag or "god mode" that bypasses `can()`.
- Don't expose `defineRole` to users without checking `users:manage` and that the new rank is below the actor's.
- Don't trust a role or permission sent by the client.

El árbol exacto que se inyectará, tras aplicar .genpmignore. Anclado a

src/lib/rbac/adapters/hono.tssolo lectura · decbadd

// Adaptador Hono: `requirePermission('posts:publish')` después de `sessionMiddleware` de @core/auth.
import type { MiddlewareHandler } from 'hono';
import type { AuthVariables } from '../../auth/adapters/hono.ts';
import { can, type Grants, getGrants } from '../index.ts';

export type RbacVariables = AuthVariables & { grants: Grants | null };

/** 401 sin usuario, 403 sin permiso. Deja `c.get('grants')` para comprobaciones `:own` dentro del handler. */
export function requirePermission(permission: string): MiddlewareHandler<{ Variables: RbacVariables }> {
  return async (c, next) => {
    const user = c.get('user');
    if (!user) return c.json({ error: 'unauthorized' }, 401);
    const g = await getGrants(user.id);
    c.set('grants', g);
    if (!(await can(g, permission))) return c.json({ error: 'forbidden' }, 403);
    await next();
  };
}