Reading diagrams / Topic 36 of 42

Guarded tables: a guard on every row

The rule

Some tables keep no row per user. Each row carries its own rule instead, a guard such as can_open(caller, row), and the table's policy names it, as in Guarded(can_open). The access check then asks of every operation: was the row checked by its guard, applied to the signed-in caller, before anything used it? A policy can name several guards, as in Guarded(can_open, can_edit). Any one of them admits any operation, read or write: the check does not tie a guard to a kind of operation.

A read of a guarded table reads “read, then guarded”. The read itself passes: the rows it returns are marked, and each later use of them is its own box, which passes only under a branch on the guard. A use outside one reads “row used unguarded”. A use that takes no key draws its line from “No key drawn”. A write must sit under the guard applied to a row the table returned at the key it writes. The words after the dot name the nearest test above the operation, as in “inside can_open or can_edit”; the verdict before the dot, not the test it names, says whether a guard holds. A line takes the colour of the box it runs into. Where two boxes would carry the same handler and verb, each adds its source line, as in “each_name · db_read, line 68”.

A choice of guards can admit a write. In either_guard, the write sits under can_open or can_edit, both applied to the row it writes, and the box reads “guard proved”; its later uses are boxes of their own, and two of them read “row used unguarded”. or_of_ands has the same choice, but its write's key comes from another input, elsewhere, not the row the guards checked, so the box reads “write not guarded”. A guard vouches only for the row it was applied to, and only when that is a row the table returned. In the second picture, forged_write reads a row of third and writes third at the same key, under can_peek. But on one branch it hands can_peek a row it builds itself, so the write is not guarded either.

keep_visible filters the rows a query returns by a predicate. It counts as the guard only when the predicate can hold only where the table's guard, applied to the caller and the row, holds: a predicate that asks for the guard and something more counts, and one that offers another way through does not. honest_visible filters third by can_peek and shared by can_open, and both boxes read “guard proved”. forged_visible filters third by something else: its box reads “row used unguarded”, and so does every later use of those rows.

A source whose label says a value is not followed further, such as “p in each_name, not followed”, is where the check stopped tracing a key; point at it to read the whole label. each_name has two values called p: the signed-in caller, and each element of a list of names, which keys its second read. The check did not follow that element further, so it cannot prove the key is the caller's, and the box is amber. It reads “not provably the caller’s key”: amber means the check gave up, not that it found a leak. Red is kept for a key shown to be someone else's. each_name's other read with the caller's bare user id where other operations key notes by owner_key, and its box reads “mixed key forms”: a user id can spell another caller's owner key.

The pictures show some handlers from the access checker's own test fixtures, each with every finding the check made on it. A table's verdict covers the whole fixture, so a table can be red for a handler the picture leaves out, and its box says how many it leaves out: “+6 not shown, 3 fail, 2 not proven” on notes counts six operations on notes in handlers the first picture does not draw. Three of them fail the check, and the check gave up on two. With neither count, every operation it leaves out passes. Press a box to follow its key, and to read the check's own words about it.

either_guard, or_of_ands and each_name, from the fixture misread.bosatsu: two guarded tables, shared and other, and a table notes keyed by owner.

Loading the access check.

honest_visible, forged_visible, mixed_visible and forged_write, from the fixture mixed.bosatsu: two guarded tables, shared and third.

Loading the access check.

Loading the worked examples and practice.