Guard / How Guard works
What safety bugs Guard prevents
Authorization bugs rarely come from one bad if check. They come from gaps between layers: a missed query, a race condition, a leaky error, or an edit that moves a row across tenants. Guard blocks each of these structurally.
Unprotected endpoints and unguarded table copies
Calling GuardServer.validate(Policy, { entities, domain, server }) (from foldkit-guard/server) checks your whole server at startup. It throws before serving a request if any guarded Entity's data source, query, live stream, or write skips its rules, or if a query filters or sorts by a hidden field.
Because Guards.attach returns a new copy of the Entity carrying the rules, passing the bare NoteFields copy by mistake could serve rows unguarded. Every Guard server adapter detects when another copy of that Entity carries guards and throws if you pass the unguarded one.
Moving a row out of your own reach
Suppose a user may edit rows in their own organization, and they send an update changing orgId to another company's ID. Checking only the row before the write would allow it.
GuardServer.writer (the guarded wrapper for declared database writes) checks an update's row rule on both the row before and the row after. If the new row fails the Update rule, the write fails with Forbidden. When a write changes two fields together (for example status and price), each field's rule is checked with the other edit already applied, so one edit cannot unlock a field rule for another. Custom handlers wrapped with GuardServer.mutation check the row before running; the handler owns what it writes.
Race conditions between checking and writing
Between reading a row to check permissions and saving an update, another request might change the row's owner or status. Passing revision: 'revision' (naming a numeric version column on your Entity) to GuardServer.writer pins every update and delete to the revision the guards checked. If another write moves that column first, the writer re-reads the row and re-evaluates the guards up to three times instead of overwriting blind.
Hidden-field leaks through filters, writes, and errors
Hiding a field like salary or internalNote from JSON responses is not enough. A caller could still filter by salary > 100000, sort by salary, or trigger a write condition (when) that fails only when salary exceeds a threshold.
Guard blocks those side channels. GuardServer.validate refuses queries that filter or sort by any field or relation (called a member) that has a Read rule. GuardServer.writer refuses writes whose precondition (when), expected revision (expect), or computed field reads a hidden member. If a data rule (invariant) over a hidden field fails, the writer returns a generic Invalid error without naming which rule failed.
Unsafe cascading deletes
When deleting a parent row cascades to child rows, GuardServer.writer checks every child row against its own Delete rule in the same SQL statement before removing anything. If even one child fails, the whole delete returns Forbidden naming only the child Entity, never a row ID. Pass guarded children in { children: [...] }, or declare authorizedBy: 'parent' on a relation when parent permission is enough.
Guessing when client data is incomplete
A browser holds only the rows it has fetched and never runs guard.principal() functions. Treating unknown permission as "no" locks buttons the user can click; treating it as "yes" misleads the UI.
Piping Guards.may onto an Entity adds a server-computed may field per row. Reading it with May.answer(may, 'Update') (imported from foldkit-guard) returns three values: Option.some(true) (allowed), Option.some(false) (denied), or Option.none() (undecided). Use May.refused(may, 'Update') to disable controls only on a known "no", leaving undecided actions live for the server to judge.