Modelling folders: inherited, broken and limited access¶
A document system asks for three things: a file in a folder is readable by whoever can read the folder; one folder can stop inheriting from its parent; one person can be given one file. The first instinct is an exclusion rule ("viewer of the parent, except here"). The model subset has no exclusion, no conditions and no wildcards, by design. The pattern below needs none of them, and it is the one the engine evaluates best: every answer is a walk along explicit tuples.
The model¶
Two object types, each with an anchor, a parent relation and a viewer relation that is
either direct or inherited through the parent:
"relations": {
"folder": {
"company_module": { "this": true },
"parent": { "this": true },
"viewer": { "union": [
{ "this": true },
{ "tupleToUserset": { "tupleset": "parent", "computedUserset": "viewer" } }
] }
},
"file": {
"company_module": { "this": true },
"parent": { "this": true },
"viewer": { "union": [
{ "this": true },
{ "tupleToUserset": { "tupleset": "parent", "computedUserset": "viewer" } }
] }
}
}
Read the viewer rule as: whoever holds viewer directly on this object, or holds viewer
on whatever this object's parent tuple points at. editor and owner follow the same shape;
they are left out here to keep the tuples short.
Inheritance is a tuple¶
A tree is a set of parent tuples. Three objects, one grant:
folder:root # viewer @ group:sales#member
folder:q3 # parent @ folder:root
file:plan # parent @ folder:q3
Check "may Alice, a member of Sales, view file:plan": file:plan#viewer has no direct tuple
for her; the parent tuple leads to folder:q3, whose viewer has no direct tuple either; its
parent leads to folder:root, where viewer @ group:sales#member matches. Allowed. Every
check binds to the company through the anchors, as always.
Breaking inheritance¶
To stop folder:q3 inheriting from root, delete the edge and copy what should survive:
- Revoke
folder:q3 # parent @ folder:root. - Grant on
folder:q3the direct viewers that should keep access, for examplefolder:q3 # viewer @ group:sales#memberif Sales stays, or a narrower subject if not.
Nothing else changes. file:plan still points at folder:q3, so it inherits from q3 and from
nothing above it. There is no "except" anywhere: a broken folder is simply a folder whose
parent tuple is gone. Your application copies the grants it wants to keep, which is also the
moment to show the user what they are keeping.
Re-attaching is the reverse: grant the parent tuple again and revoke the copies you no longer
want.
Limited access¶
One person, one file, nothing above it:
file:plan # viewer @ user:<bob's subject>
Bob is not in Sales and cannot see folder:q3 or root. The check on file:plan matches the
direct tuple before it ever walks a parent. Revoking that one tuple removes the access. The same
works for a position (position:<id>#holder) or a group.
When the parent moves¶
Moving file:plan from q3 to q4 is two tuple writes in one grant call and one revoke:
- Grant
file:plan # parent @ folder:q4. - Revoke
file:plan # parent @ folder:q3.
Nothing on the file's own viewer relation changes. Direct grants (Bob's) travel with the file;
inherited access follows the new parent from the next check onward. Do the grant before the
revoke so no check in between sees a file with no parent.
Moving a folder moves its whole subtree the same way, with one parent tuple, because every
descendant reaches it through its own parent chain.
Depth and cycles¶
The engine follows parent chains up to 32 levels and refuses deeper trees with
DEPTH_EXCEEDED, which is a denial. A cycle (a folder whose chain reaches itself) contributes
nothing to its own answer and is not an error; your application should still refuse to create
one.
What this gives up¶
A rule such as "everyone in Sales except Carol" cannot be written. Model the exception the other way round: give the folder a group that excludes Carol, or grant the people who should see it directly. Exclusion is a property of your groups and your grants, not of the model, and that keeps every decision a walk along tuples your audit trail already records.