Waterfall ACL

The bug this exists to prevent

Most permission code is written against a subtractive mental model: grant broadly at the top, restrict further down. Deny beats allow. That is how filesystem ACLs and most RBAC systems work, and it is how almost everyone reasons about folders.

Box's model — and several other document stores — is the opposite. It is purely additive. There is no subtractive operation anywhere in it. A child folder cannot narrow what an ancestor already granted; adding a collaborator to a parent silently widens every descendant.

Write a "restrict this subfolder" feature against the wrong model and it appears to work: your UI shows the narrowed list, your tests pass against your own state, and the store keeps serving the ancestor's grant. Nobody sees a permission error, because there isn't one. The document is simply readable by people your interface says cannot read it.

Rule 1 — the code can only ever add

Every function here builds its result by adding to a Set. **There is no code path that removes an id once added.** That is not an implementation detail, it is the model made structural — a future change that tries to subtract has nowhere to put it, which is the point.

Rule 2 — fail closed with an explicit sentinel, not an empty set

OWNER_SENTINEL marks "owner only until explicitly shared." A principal set containing only that value is not a real membership id and must never be expanded through group lookup or rendered as a person.

An empty set would be the obvious encoding and is dangerous: empty reads as "no restrictions recorded" to the next piece of code, and the natural handling of "no restrictions" is to allow. A sentinel cannot be misread that way — it forces a decision.

Rule 3 — an open shared link is never auto-granted

A folder carrying an open shared link is surfaced for review rather than silently expanded into "everyone." The link is a fact about the folder; treating it as a grant converts one careless share into a permanent ACL entry that no longer looks like a link.

Rule 4 — generation timestamps, because a full sweep and an incremental update race

A nightly full sweep and an incremental update can complete out of order. Without a guard, the older result lands last and reinstates access that was just removed. The staleness check is here rather than in the sync layer, because it is an access decision.

What this does NOT do

No API calls, no syncing, no crawling, no storage. It computes effective principals from folder lineage and direct collaborators you supply. The sync layer around it stays a thin, mockable shell — deliberately, so the part that decides who can read a document is the part with exhaustive tests.

Group membership expansion is your lookup; this decides when expansion is legitimate.

Verified

31 tests covering inheritance to the crawl root, union semantics, the owner sentinel, groups, open shared links, missing lineage, and the generation-timestamp race.