Skip to content

Cookbook ​

Recipes for common access rules. Each has a page of its own, with the policy lines, what each does and a test, and a folder under docs/cookbook/ with its own small tables (schema.sql), a few rows (rows.sql), policy (policy.authz), tests (tests.authz) and rowstile.toml. CI applies and tests every one, and checks that every line of policy and tests a page shows is in those files (core/tests/cookbook.sh). Each page links to the playground, where the recipe runs in your browser, or try it on a database of your own.

The language in one breath: a type is a table; a relation says who or what a row is linked to (a column, a link table, or shares people make); a permission combines relations with or, and, not, rel.perm (follow a relation) and {SQL}; rules say what each command on a table needs.

Rows and their owners ​

Groups and trees ​

Sharing ​

Tenants and roles ​

Rules on the row, and who writes ​

Live updates: who to tell ​

When a row changes, a backend that pushes updates asks once which of its connected people may see it:

sql
SELECT * FROM authz.who_among('channel', '7', 'read', ARRAY['1', '2', '3']);

It signs each one in with authz.act_as, so it is for whoever may call that: the app role, a backend trusted to sign people in. The messenger does this (examples/messenger/backend/app/events.py): its WebSocket carries only "chat 7 changed", and the browser refetches through the API.

Signing in, when the tables are under row-level security ​

Checking a password reads a table before anyone is signed in. Keep credentials in a table the policy doesn't govern, and read them through a SECURITY DEFINER function the app role may call (examples/messenger/db/migrations/0001_schema.sql: ms.credentials_for). authz.lint() notes such functions: check each only reads what it must.

Trying a recipe on your own database ​

Each recipe's folder has a rowstile.toml that names its policy and its tests, so rowstile dev finds them. In a copy of the folder, with rowstile installed:

sh
createdb owner_only
psql -d owner_only -f schema.sql -f rows.sql
DATABASE_URL=postgresql:///owner_only rowstile dev

The three lines reach the same server as the same user: the one PGHOST, PGPORT, PGUSER and PGPASSWORD name, as for psql. A URL with no host or user takes them too. For the guide's Docker container, set them first: export PGHOST=localhost PGUSER=postgres PGPASSWORD=secret.

  • schema.sql makes the recipe's tables, in the schema app, and the app role, app_user, that the app connects as. Run it as a Postgres user that may create roles. That user owns the tables, and rowstile dev connects as it too. Each recipe wants a database of its own.
  • rows.sql adds a few rows to ask about, the ones the playground shows. The tests bring their own.
  • rowstile dev applies the policy and runs the tests, then does it again each time you save one of them. rowstile dev --once does it once and stops.

CI takes these steps for every recipe, with --once (core/tests/cookbook.sh).