How Authorization Works

"Can Alice download this file?" sounds simple, until you add groups, orgs, public links, nested folders, shared drives and a few thousand tenants. Platrium answers it with a small, boring model that lives in plain SQL. Let's walk through it!

Capabilities Are Bits

A capability is one thing you may do to an item. Each one is a single bit in a 64-bit integer, so a set of capabilities is just a number and "is this allowed?" is one bitwise AND.

Some capabilities imply others (EDIT implies VIEW, which implies LIST). Grants are normalized when written, so checks never apply rules.

Grants

A grant says: this subject gets these capabilities on this item (and everything under it).

One grant per subject per item, so sharing again just replaces it.

The Check

Two queries do the work: one recursive CTE walks the ancestors up to the drive root, marking every ancestor above a restriction as cut, and one indexed lookup loads the unexpired grants that match your user, groups, tenant or PUBLIC. On a cut ancestor only grants that carry MANAGE count; everywhere else every grant does. CapsMany runs the whole thing for many items at once, which is how folder listings stay fast.

Inheritance

Grants flow down the tree. A grant on a folder covers everything inside it. To lock a subfolder down, set inherit_perms = false on it: ancestors' grants stop applying there, and only grants on the item itself (and below) count.

There's one exception, and it's what keeps a drive administrable: a grant that carries MANAGE (a Drive Admin's) keeps applying through a restriction. Restricting hides a folder from members, editors and public links, never from the drive's admins. So restricting needs no extra grant to "keep you in", and resuming inheritance leaves nothing behind.

There are no deny rules. Access only ever adds up, which keeps checks order-independent and easy to explain.

Groups: Flatten The Small Side

Groups can nest. We keep the direct memberships in group_members and a flattened group_closures table (every group → every user beneath it), rebuilt in the same transaction as each membership change. Resolving "which groups is Alice in?" is then one indexed lookup, however deep the nesting.

What Enforces It

Every fsops operation requires a capability on the item(s) involved:

Listings, counts, change feeds and breadcrumbs also hide what you can't see. A breadcrumb starts at the topmost folder you can open, so someone shared a deep folder never learns the names above it.

Changing Access: The Rules

Reading access has one choke point (CapsMany). Writing access has one too: the rules in authz.CheckChange.

An item's access is just the set of grants on it, and every write is a change to that set: share, revoke, set general access, restrict, create a drive. So a writer does the same thing every time. It works out what the grants will be, hands the before and after to CheckChange, and writes only if the rules agree.

Where It Lives

The rules are in package authz, with no database access, and they take plain types: a Change, the item's ItemFacts (is it a drive root, is it in a shared drive, does it inherit) and the grants. The adapter fills in the facts and does the locking and writing. That is what keeps them engine-neutral. An OpenFGA engine runs the same rules, and the shared scenarios in authztest check that every engine agrees. See scaling and OpenFGA.

Code Layout

engine/internal/authz/
├── capability.go   the bit registry, implied rules, Verbs()/Parse
├── role.go         built-in roles and their wording per context
├── level.go        the general-access levels (restricted, organization, public)
├── model.go        Principal, Grant, Subject, GeneralAccess
├── rules.go        the change rules and CheckChange (no storage imports)
├── authz.go        the Authorizer interface (reads AND writes)
├── authztest/      scenarios every engine must pass
└── sqlauthz/       the SQL engine: check, grants, groups, shared, general,
                    and mutate.go (lock, load, check) used by every writer

The Authorizer interface owns writes as well as reads. Each engine stores its own data, so there is never a dual-write to keep in sync. That's what makes swapping engines possible. More on that in scaling and OpenFGA.