Reviewing a policy change
A one-line change can widen access across many permissions, and its text doesn't show that. rowstile review says what a change does, in plain words, for the pull request:
rowstile review --base main # in a terminal
rowstile review --base main --markdown --db "$URL" # the comment CI posts- Meaning: each declaration that changed, before and after, and every permission and rule that changes through something it uses. When only permissions and rules changed, each is checked against the base in many small worlds (made-up users, objects and links,
core/authzlib/evaluate.py; among them the ones where every condition holds, or where most links do, so a change behind a longandshows, and chains of objects one link longer than the policies read), and in the worlds of up to three rows of each type, listed with the fewest links first, every one with no link or one link among them: each row with every answer its conditions can give, so a condition added to a longand, or one that must say one thing on a row and another on the row it inherits from, shows. A number a condition compares a column with in order gets the numbers either side of it and halfway to them ({level > 1}and{level >= 2}differ on 1.5), and an id a condition compares a relation's column with is the id of a row there ({owner_id <> 7}: a user 7, whose folders it leaves out). The listing stops after 3,000 worlds, once those are tried, and after 12,000 whatever: rows whose conditions give many answers make many worlds of one link. If they all grant the same, the review says "Meaning unchanged", and how far the listing got: "every one of up to 3 rows of each type", with "at most 2 links" where it stopped there (or "with no link, and some with one", where it stopped before those), and, where columns read together take more than 4,096 combinations of values, that only the first of them were tried. If one world grants otherwise, the review names what differs, for whom and on what, and the comment shows that world too. It is the first world found, made as small as it still grants otherwise in: each row, link and value it holds plays a part. Worlds that are bigger, or hold custom roles, are only drawn: for them it is a search, not a proof. Formatting and comments are "unchanged" too; text inside quotes is not formatting. A condition the worlds can't read (a subquery, a function: anything beyond the row's own columns andauthz.uid(); a text compared with a column the policies also compare with a text it may hold as the same value,'a'beside'A'under a case-insensitive collation) is a set of rows of its own there, so when a permission or rule changed only in such conditions, the review says it can't compare them and names them, instead of guessing. - Access: with
--db, a database at the base branch's state (its migrations, then the review data, prepared by CI; never production), who gains and who loses what if the pull request's policy were in force, with examples and how each is granted. The database is left as it was. - Risk: what to look at twice: access widened to
anyone,linkoruser:*; a deny removed; a new inheritance path or a new way to reach a type; a relation newly shared or shared by another permission; a permission or a rule (selecttoo) that allows more than before, with an example: because its own line changed, because it is new on a table that had rules, through a relation that changed (another column, awheretaken off a link table), or because a type'swherechanged; a mask, a column rule or an invariant removed; ashared ifremoved or changed (who a share may name); a caveat changed (what every share made with it is held to); a scope changed; a cascade marked as meant (cascade from); a sync line added, or finding its rows' readers by another permission, or mirrored now (what the sync engine is given). A permission's example comes from the small worlds, or with--dbfrom Access when the review data shows someone gaining it there: a user who had it before isn't named as one who gains it. A plainupdate afteris compared with theupdaterule that checks in its place: one added that lets more rows through after an update, or one removed whereupdatelets more through, is flagged. Awhereadded to a link table, or one that holds for fewer of its rows, allows less, and isn't flagged. Each names its policy line;--annotationswrites them for GitHub, on the file the line is in.--out FILEwrites the comment to a file as well, so one review gives both, as the action runs it:rowstile review --annotations --out review.md. "Nothing flagged" means none of these was found in the worlds tried, not a proof. - Tests: checks whose expectation flipped (the author saying "I meant this"), checks removed, new permissions no test names. A test that only changed its name is said to be renamed, and its checks are compared under the new name: a new name alone removes nothing. With
--db, the pull request's tests run on the review data after its migrations. The checks are listed whatever Meaning says. A test file of the pull request that doesn't parse, or thatrowstile testwould refuse with the pull request's policy (a permission it doesn't have, a test another file names too), is named, with its mistake: its checks are not compared, nor run, and the review goes on. - Deploy: the migrations the change needs (from the base branch's lock file), their statements, the app tables they lock and in which mode, the inheritance tables they rebuild or build beside; with
--db, how long they took on the review data. Deploy also names, in words and with the mode it locks them in, the tables a migration finds only as it runs: those an inheritance condition reads, and the partitions and child tables made since the last migration, which every migration gives rowstile's triggers and, under a table with rules, row-level security. A lock file behind the policy is called out. With no lock file on either side, the project applies its policy (rowstile apply) and keeps no migrations: Deploy says so.
The pull request that adds the policy has none at the base. Each declaration is listed as added, the app role and the user type too, and the review compares with a policy that allows nothing. A base whose policy has a mistake is reviewed the same way, so the pull request that fixes it gets a review too: it says first that the base has a mistake, with its line there and its code, in the text, the comment and the annotations (--json: base_mistake, with line, message and code), then reviews the policy as new.
review-ci/github/action.yml runs it on each pull request and keeps one comment up to date (and the annotations); review-ci/gitlab/rowstile-review.gitlab-ci.yml does the same for merge requests. rowstile fmt --check in CI keeps text diffs to real changes. On GitHub, the workflow may post the comment once it has pull-requests: write, and checks out the history the base branch's policy is read from:
on: pull_request
permissions: {contents: read, pull-requests: write}
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
with: {fetch-depth: 0}
- uses: rowstile/rowstile/review-ci/github@v0.1.0-beta.5 # the release you useA pull request from a fork gets a read-only token, whatever the workflow asks for: the review is then in the run's summary, a notice says so, and the job passes. Run it on pull_request all the same, not on pull_request_target (the threat model says why). A review longer than a comment may be is cut, and the comment says the whole review is in the run's summary; on GitLab, in the job's artifact, review.md. On GitLab the note is written with ROWSTILE_REVIEW_TOKEN, set in the project's CI/CD settings. Another release (ROWSTILE_VERSION) or another stage than test is set in the job, by its name in the including file: the template's header shows how.
The review reads the base's policy, the files it includes, its tests and its lock file with git. A file the base doesn't have is new: a policy, or a test file added since. But when git can't read one the base has, or can't list the base's folders (a partial clone that can't fetch them, a repository missing objects), the review stops, exit 2, and says what git can't read and how to fetch it. Read as missing, the policy would be reviewed as new and the base's tests left out. So check out the whole history, with no filter, as above.
The review reports; it doesn't gate. It exits 0 whatever it finds: a widened permission, a failing test and a lock file behind the policy are all in what it prints, for a person to read. (It exits 1 for a pull request whose policy doesn't compile, 2 when it can't run: no --base where there is no main or master to compare with, a commit git doesn't know, a file at the base git can't read, a database it can't reach.) What fails a pull request is the other two commands CI runs: rowstile test, which exits 1 when a check fails, and rowstile migrate --check, which exits 1 when the policy changed and no migration was written.