agentleFS
vstorm-covstorm-co/agenticos/.claude/skills/permissions-rbac/SKILL.md

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.

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
  1. Very specific:

    Only two user aliases exist: CurrentUser and CurrentAppAdmin.

    line 80
  2. Very specific:

    Add to Perm in app/core/permissions.py.

    line 85
  3. Very specific:

    Add it to every role in the matrix that should have it — with a Scope if it is a resource permission.

    line 86
  4. Distinctive:

    Test the refusal, and test it cross-tenant.

    line 89

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 shapeGate
GET /agents, POST /agents, GET /agents/capabilitiesdependencies=[Depends(require(Perm.AGENTS_EDIT))]
GET/PATCH/DELETE /agents/{id}, POST /agents/{id}/publishNo 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

  1. users.is_app_admin — the deployment superadmin. CurrentAppAdmin. uv run agenticos cmd create-app-admin <email> [--revoke].
  2. The organization role — owner, admin, builder, operator, member, viewer. Composed from permissions in app/core/permissions.py.
  3. 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

  1. Add to Perm in app/core/permissions.py.
  2. Add it to every role in the matrix that should have it — with a Scope if it is a resource permission.
  3. Gate the collection routes; hand per-resource decisions to a service.
  4. Test the refusal, and test it cross-tenant. Most of this platform's value is in what it refuses.
  5. 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-feature and e2e-tests skills).

Always test

  • Tenant isolation — unreachable from another organization including when the caller owns the row.
  • A grant widening, not promoting — a Viewer with an edit grant 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.