permissions-rbac
Skill315 starsChanged 31 days agoApache-2.0View on GitHub
Gate a route or a service on who may do it — add a permission, wire a role, decide between require() and resolve_access, share a resource with a grant, or debug "this user can see something they should not" and "a Viewer with an edit grant is being refused". Use for any authorization work, any new org-scoped route, and any review of one. There is no UserRole, RoleChecker or CurrentAdmin in this project.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- frontend/AGENTS.mdAGENTS.md
- llms.txtllms.txt
- agent-capabilitySkill
- agent-specSkill
- alembic-migrationSkill
- backend-testsSkill
- background-taskSkill
- channel-botSkill
- dev-agentSkill
- e2e-testsSkill
- frontend-featureSkill
- mcp-connectionsSkill
- pr-commentsSkill
- pr-descriptionSkill
- project-docsSkill
- rag-knowledgeSkill
- resolve-changelog-conflictSkill
- review-mapSkill
- ste-writingSkill
- vault-secretsSkill
- vstorm-code-reviewSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 80
Only two user aliases exist: CurrentUser and CurrentAppAdmin.
- Very specific: line 85
Add to Perm in app/core/permissions.py.
- Very specific: line 86
Add it to every role in the matrix that should have it — with a Scope if it is a resource permission.
- Distinctive: line 89
Test the refusal, and test it cross-tenant.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Permissions — three layers, and one rule people get wrong
Read docs/permissions.md for the model and docs/reference/permissions.md
for the generated catalog. .claude/rules/exceptions-security.md has the code
shapes. This file is what to do and what not to.
Permissions are defined in code; roles are composed from them. Call sites check permissions, never role names, so adding or re-shaping a role never means editing an endpoint.
The rule that gets broken
require(...)gates belong on collection routes, not per-resource ones.
| Route shape | Gate |
GET /agents, POST /agents, GET /agents/capabilities | dependencies=[Depends(require(Perm.AGENTS_EDIT))] |
GET/PATCH/DELETE /agents/{id}, POST /agents/{id}/publish | No route gate. The service calls resolve_access |
A role gate cannot see the grants on a row. Put one on a per-resource route and it
refuses a Viewer holding an explicit edit grant before resolve_access ever
widens their access — which directly contradicts the platform's own promise that a
grant widens what a role allows and never narrows it.
tests/api/test_platform_routes.py enforces both halves. If it fails after you
added a gate, the gate is the bug.
The two calls
# Collection route — a permission, as a route dependency.
@router.post("", dependencies=[Depends(require(Perm.AGENTS_EDIT))])
async def create_agent(ctx: Auth, service: AgentSvc) -> Any: ...
# One row — in the service, never as a route gate.
if not await resolve_access(self.db, ctx, agent, Perm.AGENTS_EDIT, resource_type=AGENT):
raise AuthorizationError(message="...")Listings need the third call, or shared rows silently vanish:
extra = await visible_resource_ids(db, ctx, resource_type=AGENT, perm=Perm.AGENTS_VIEW)
# None means the role already reaches everything — skip the grant lookup.
# An empty list is NOT the same as None; a context with no subject gets [].The three layers
users.is_app_admin— the deployment superadmin.CurrentAppAdmin.uv run agenticos cmd create-app-admin <email> [--revoke].- The organization role —
owner,admin,builder,operator,member,viewer. Composed from permissions inapp/core/permissions.py. - Visibility and grants — a grant on one row, to a person or to a group
(
docs/directory.md#groups).effective = max(role scope, grant on this resource).
Capability scopes (knowledge:read, web:read, code:execute) are a separate
axis, not a fourth layer: they are what an organization allows its agents to do,
checked when an agent is assembled rather than per request. See the
agent-capability skill.
Resource permissions carry a Scope: none, own, shared, all. It answers the
question a role cannot — not "may this role touch agents?" but which agents.
What does not exist
UserRole, User.has_role(), RoleChecker, CurrentAdmin, CurrentSuperuser.
The users.role column was dropped before the migration chain was squashed, so
there is no revision to point at: 0001_baseline simply creates users without
it. Do not reintroduce any of
them, and do not add --role to a CLI command. Authority inside an organization is
a membership row plus this catalog.
Only two user aliases exist: CurrentUser and CurrentAppAdmin. Anything
org-scoped goes through Auth (AuthContext) plus a permission.
Adding a permission
- Add to
Perminapp/core/permissions.py. - Add it to every role in the matrix that should have it — with a
Scopeif it is a resource permission. - Gate the collection routes; hand per-resource decisions to a service.
- Test the refusal, and test it cross-tenant. Most of this platform's value is in what it refuses.
- The frontend reads the effective permission set — check what it hides, and add an
integration test that a button is actually gone (see the
frontend-featureande2e-testsskills).
Always test
- Tenant isolation — unreachable from another organization including when the caller owns the row.
- A grant widening, not promoting — a Viewer with an
editgrant on one agent edits that agent and nothing else. - A context with no subject — API key, embed session, channel run. See
docs/permissions.md#contexts-with-no-subject.
Depth
references/catalog.md — the permission list, the role matrix, and how
resolve_access decides.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

