Skip to content

Authorization enforcement

Facet enforces authorization inside every document operation. Two components do the work: the read enforcer and the write enforcer. Every caller passes the same checks — a route, a migration, a background job.

Denied read: 404 Denied read: 404

The model is role-based access control (RBAC). Each request carries one identity and one elected role. Roles never merge.

A permission line names three things: an action, a doctype path, and an optional row scope. The action is read, create, update, delete, or a named action. The path can name one doctype, a whole domain, or every doctype at once.

Row scopes. Row scopes are named predicates that the doctype declares. The enforcer compiles them into Structured Query Language (SQL) predicates. On a list, the predicates join the query, so the database returns only the rows the role can see. On a single read, the enforcer evaluates the predicate against the row itself.

Field tags. Field tags guard content. A role sees a field only when its visible_tags hold all the field’s tags. Untagged fields carry the default tag. On reads, the server removes invisible fields at every nesting level. On writes, a change into an invisible field is refused with 403, and the error names the field path.

Denial is non-disclosing. A single read the role cannot see answers 404 — the same answer as a missing document. A list answers 200 with the visible rows only. On a nested child route, a denied parent read and a missing parent give the same 404.

The metadata gate. The metadata gate covers render-time metadata: the core.DocType definition rows and the core.Domain rows. A role with no read line on those doctypes still receives a row when it holds any action on what the row describes. Otherwise the row is absent, not 403. Field aggregates follow the same rule: a caller with no read grant gets an empty result, 200 with zero rows. Counts and schema stay hidden where the documents stay hidden.

Debugging takes longer. The 404 masking makes debugging harder. You cannot tell a missing document from a denied one; check the role’s permission lines before the id.

Scopes cost a query. Scope predicates add query cost — a context set runs one database query per request.

Some lists stay empty. Metadata non-disclosure limits listing features: a role without grants sees no schema for the hidden doctypes.