DocsData

Rules

The rules language, what a rule can name, and how Sluurp enforces rules on collections and fields.

A rule is a filter expression that can name the caller. Sluurp compiles it into the SQL that reads or writes the rows, so rows a user can’t see never leave SQLite.

@request.auth.staff = true && org = @request.auth.org && id != @request.auth.id

This rule lets staff delete users in their own organisation, but not themselves.

Collection rules

Each collection has five rules, one per action. With no rule, only superusers can do it. With "", anyone can.

migrations/V1__init.json
"rules": {
  "list":   "@request.auth.id != null",
  "view":   "@request.auth.id != null",
  "create": "author = @request.auth.id",
  "update": "author = @request.auth.id",
  "delete": "author = @request.auth.id || @request.auth.staff = true"
}

Field rules

A field can have two rules of its own: visible, for who can read it, and writable, for who can set it. By default, both follow the collection’s rules.

migrations/V1__init.json
{ "name": "salary", "type": "number",
  "visible":  "@request.auth.id = employee || @request.auth.staff = true",
  "writable": "@request.auth.roles ~ \"payroll\"" }

The language

Rules use the same syntax as filters:

Compare= != > >= < <=
Contains, doesn’t contain~ !~
Combine&& || and parentheses
Values"text", numbers, true, false, null
The recordfield names: author, org, status
The caller@request.auth.…
Time@now, @days_ago.30, @years_ago.13

The caller

  • @request.auth.id, collection, email and superuser come from the token, at no cost.
  • Any other field of the caller’s record works too: @request.auth.staff, @request.auth.org. Sluurp loads the record by id, in the same transaction, only when a rule uses it.
  • @request.auth.roles is a set. @request.auth.roles ~ "admin" tests whether it holds admin, so it never matches superadmin.
  • For callers who aren’t signed in, all of these are null. A rule for members only is then false, never an error.

How rules are enforced

  • Lists filter. Callers get only the rows they may see, with the right totals.
  • View, update and delete answer 404 when refused, so rules can’t be used to find out whether a row exists.
  • Writes are checked twice: before the change, and again inside the transaction after it. A change that would put the row out of the writer’s own reach is rolled back.
  • Conditions on the caller are worked out before the query. @request.auth.roles ~ "admin" becomes a constant; conditions on the record go into the WHERE clause.
  • Field rules work the same way. A field the caller can never see isn’t selected. One that depends on the row is set to null row by row, in SQL.

Check permissions in advance

To show only the buttons that will work, ask GET /api/acl. For the signed-in user, it answers what each collection allows: allow, deny, or conditional (only for some rows, such as their own). It evaluates the same rules, so it can’t disagree with what is enforced.

View as Markdown