@core / rbac

1.0.1 ▾

1.0.1

已验证MIT

GitHub

基于 @core/auth 的角色与权限：通配符、仅限本人规则、防提权授予

代码10 个文件上下文约 615 个 token扫描通过

约 615 个 token→ src/lib/rbac/AGENTS.md→ .cursor/rules/genpm-core-rbac.mdc

这正是你的 AI 在 src/lib/rbac 中工作时读取的内容。不会向其上下文添加其他任何内容。

@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.

应用 .genpmignore 后将被注入的确切目录树。固定于

src/lib/rbac/defaults.ts只读 · decbadd

// Roles por defecto. Las apps pueden añadir los suyos con `defineRole`; estos se crean con `ensureDefaultRoles()`.

export type RoleDefinition = { key: string; label: string; rank: number; permissions: string[] };

export const OWNER_ROLE = 'owner';

export const DEFAULT_ROLES: readonly RoleDefinition[] = [
  { key: 'owner', label: 'Owner', rank: 100, permissions: ['*'] },
  { key: 'admin', label: 'Administrator', rank: 80, permissions: ['*'] },
  {
    key: 'editor',
    label: 'Editor',
    rank: 60,
    permissions: ['admin:access', 'content:*', 'pages:*', 'posts:*', 'media:*', 'menus:*', 'comments:*', 'forms:read'],
  },
  {
    key: 'support',
    label: 'Support',
    rank: 40,
    permissions: ['admin:access', 'orders:*', 'customers:*', 'reviews:*', 'comments:read'],
  },
  {
    key: 'author',
    label: 'Author',
    rank: 20,
    permissions: [
      'admin:access',
      'posts:create',
      'posts:read',
      'posts:update:own',
      'posts:delete:own',
      'media:create',
      'media:read',
    ],
  },
];