# auth.rbac
Role-based access control as data: a policy of roles, what each inherits and
what each grants, and four pure functions over it. The policy lives in your
code or your database; these answer "who may do what" the same way in a
TypeScript front end, a Python API and a Rust service.
```ts
const policy = {
roles: [
{ name: "viewer", inherits: [], permissions: ["posts:read", "comments:read"] },
{ name: "author", inherits: ["viewer"], permissions: ["posts:create", "posts:update:own", "posts:delete:own", "comments:*:own"] },
{ name: "editor", inherits: ["author"], permissions: ["posts:update", "posts:publish"] },
{ name: "admin", inherits: [], permissions: ["*"] },
],
permissions: ["posts:read", "posts:update", "posts:delete", "comments:delete"],
};
checkAccess(policy, { id: user.id, roles: user.roles }, "update", { resourceType: "posts", id: post.id, ownerId: post.authorId });
// { allowed: true, reason: "granted_own", grant: "posts:update:own" }
```
## Grants and permissions
- A **permission** is `resource:action`, each segment lower-case ASCII
letters, digits, `_` and `-` (`posts:update`, `api-keys:revoke`).
- A **grant** (in a role's `permissions`) is `resource:action`, or
`resource:action:own` for the subject's own resources only. Either segment
may be `*` (any resource, any action), and `*` alone means `*:*`. There are
no deny rules: a grant only ever adds.
- Anything else (`posts:read:mine`, `Posts:read`, a trailing newline) throws
`invalid grant ...` or `invalid permission ...`.
## The functions
- **resolveRoles(policy, roles)**: the roles plus everything they inherit,
and all their grants, each deduplicated and sorted (by code point, so `*`
sorts first).
- **hasPermission(policy, roles, permission)**: `posts:update` asks "may they
update every post?", which only an unrestricted grant answers yes;
`posts:update:own` asks "may they update their own?", which an unrestricted
or an `:own` grant answers yes. For a decision about one resource, use
checkAccess.
- **checkAccess(policy, subject, action, resource)**: an unrestricted grant
gives `granted`; otherwise an `:own` grant gives `granted_own` when
`resource.ownerId` equals `subject.id`, and `not_owner` when it does not
(a resource with a null owner is nobody's own); otherwise `denied`. `grant`
names the grant that allowed it, the first in sorted order; null when not
allowed.
- **accessMatrix(policy)**: the access tests the policy implies (below).
The resource field is `resourceType` rather than `type`, because `type` is a
Rust keyword and the registry's lint refuses raw identifiers.
## The policy is checked whole, every call
Every function first checks the entire policy, not just the roles in hand, so
a mistake anywhere fails the first request rather than one unlucky user's:
- `role name must be a non-empty string`, `duplicate role <name>`;
- `unknown role <name>`: inherited by a role, or given in the call;
- `invalid grant <grant>`, and `invalid permission <p>` for an entry of
`policy.permissions` (concrete `resource:action` only: no `*`, no `:own`);
- `role inheritance cycle: a -> b -> a`. Cycles are found by a depth-first
walk over the roles in policy order, following `inherits` in listed order,
so the same policy always reports the same cycle, starting from the first
role in policy order that is on it (or leads to it).
Then `checkAccess` checks `subject.id must be a non-empty string`, the
subject's roles, and that `resourceType:action` is a permission.
## Generated access tests
`accessMatrix` walks every role (policy order) by every permission in
`policy.permissions` (listed order) by ownership (not owned, then owned), and
says what checkAccess answers for a subject `{ id: "subject", roles: [role] }`
on a resource `{ resourceType, id: "resource", ownerId: own ? "subject" : "someone-else" }`.
Each case is named:
- `<role> may <action> any <resourceType>` / `<role> may not <action> any <resourceType>` (owned by someone else)
- `<role> may <action> <resourceType> they own` / `<role> may not <action> <resourceType> they own`
such as `editor may update any posts` and `viewer may not delete posts they
own`. Commit the generated table (or a snapshot of it) next to your policy:
a change to a role then shows up in review as changed expectations, and your
own tests prove the app's real authorisation path agrees with the policy.
```ts
import { accessMatrix } from "#fune/auth.rbac@^1";
for (const c of accessMatrix(policy)) {
test(c.name, async () => {
const user = await makeUser({ roles: [c.role] });
const owner = c.own ? user : await makeUser({ roles: [] });
const res = await api.as(user).request(c.action, c.resourceType, await makeResource(c.resourceType, owner));
expect(res.status === 403).toBe(!c.allowed);
});
}
```
```python
import pytest
from fune.auth.rbac import access_matrix
@pytest.mark.parametrize("case", access_matrix(POLICY), ids=lambda c: c.name)
def test_access(case, client, make_user, make_resource):
user = make_user(roles=[case.role])
owner = user if case.own else make_user(roles=[])
res = client.as_user(user).act(case.action, make_resource(case.resource_type, owner))
assert (res.status_code != 403) == case.allowed
```
## What it does not do
No deny rules, no attribute conditions beyond ownership, no organisation or
tenant scoping (put the tenant check before it), and no storage of who holds
which role.