Identity & access

Row-level security policies

Restricts which rows a caller can read or write, for example letting users see their own records and no others.

BetaEngine edition 5f8ea3af

What it does

A small policy language evaluated on the server for every row. Policies are written per operation (select, insert, update, delete) as boolean expressions over the row and the caller, such as owner_id == auth.uid(). A request can also declare a purpose that a policy can require.

How it works

A collection can carry policies, each with a name, an operation and an expression. Expressions use the comparisons ==, !=, <, >, <= and >=, the operators &&, || and !, string, number, boolean and null literals, row fields, and four caller functions: auth.uid(), auth.role(), auth.email() and auth.purpose(). The language is a hand-written parser and evaluator with no code execution. An expression that does not parse is rejected when the collection is saved, and one that fails to parse or evaluate later denies.

When a collection has no policy for an operation, access follows the role rules alone. When it has one or more, a row passes if any one of them is true. A comparison with null never succeeds, so a caller without a uid, or a request without a declared purpose, is denied by a policy that needs one. An insert is checked against the incoming row, and an update or delete against the row as stored.

A request declares its purpose in the X-Kynetra-Purpose header. A policy such as auth.purpose() == 'billing' then allows access for requests that declare that purpose and denies the rest. When a purpose-gated insert is denied, the denial is written to the audit log.

Realtime subscriptions evaluate select policies for each subscriber and each change, so a subscriber receives events for rows it could have read. A service connection skips that lookup.

Where you reach it

  • HTTPPOST /v1/collections (rules.policies on the definition)
  • HTTPGET|POST|PATCH|DELETE /rest/v1/:table
  • HTTPPOST /v1/query
  • HTTPGET /realtime/v1 (subscriptions are filtered by select policies)

Example

Users read and insert their own notesjson
{
  "name": "notes",
  "fields": [
    { "name": "title", "type": "text", "required": true },
    { "name": "owner_id", "type": "text", "required": true }
  ],
  "rules": {
    "list": ["*"],
    "view": ["*"],
    "create": ["admin", "editor"],
    "update": ["admin", "editor"],
    "delete": ["admin"],
    "policies": [
      { "name": "owners read their notes", "op": "select", "expr": "owner_id == auth.uid()" },
      { "name": "owners insert their notes", "op": "insert", "expr": "owner_id == auth.uid()" }
    ]
  },
  "created_at": 0,
  "updated_at": 0
}

Limits

  • Policies are enforced on the table routes under /rest/v1, on KynQL queries at /v1/query, on typed views and on realtime subscriptions. The record routes under /v1/collections apply the role lists alone. Serve end-user traffic through the first four surfaces.
  • Project service keys, and organisation console sessions acting inside a project, skip policies.
  • Policies are evaluated row by row after the candidate rows are selected, so they restrict results but do not make a query cheaper. No throughput figure is published.
  • The language has no joins, subqueries or functions beyond the four auth functions.

Evidence

  • On this siteDocs: collections and rules
  • Tests54 policy-language tests (tokens, parsing, precedence, null handling, fail-closed evaluation, purpose), 15 collection-level RLS tests, 3 realtime subscription tests and a mounted insert-route test for declared purposes

Test coverage is listed as present in the engine repository at this edition. This page does not report test results.

KynetraDB is in private preview

Request a preview to talk through the limits above against your own workload.