Threat model
What rowstile protects, from whom, where it relies on the deployment, and what it does not cover. Checked by core/tests/adversarial.sh (the app role attacking the policy), core/tests/sessions.sh (signed sessions), core/tests/identity.sh (identity and scopes), core/tests/principals.sh (services that sign in as themselves), core/tests/difftest.py (the database agrees with an independent evaluator) and core/tests/fuzz_parser.py (broken policies are refused cleanly). rowstile has not been audited by anyone outside the project.
What is protected
- Rows of governed tables: a table with
rulesin the policy. Who may read, add, change and delete each row, down to columns (column rules, masks). - Shares, roles, requests, reviews, API keys: the
authztables. The app role changes them only through rowstile's own functions, which check that the caller may. - The audit trail and the change feed: the app role can't read or change either. The audit trail is append-only for administrators too, but for
authz.trim_audit(), which they run; the feed is theirs to trim (authz.trim_changes()). - Correct inheritance: the stored closure tables match the tree at every commit, whatever the isolation level or concurrency (
tests/interleave.py,tests/stress.sh).
Who is trusted
| trusted to | not trusted to | |
|---|---|---|
Policy authors (whoever applies it with rowstile apply: the tables' owner, or a superuser) | say what the rules are; their {...} conditions run as the policy's owner | nothing: a policy can do anything its owner can |
| Database owner, migration role | own the tables and apply policies | |
The app's backend (the app role, or a member of it: the roles that may call authz.act_as()) | say who is signed in, per transaction | |
The app role (app role in the policy; the backend connects as it) | nothing beyond the rules | read or change rows the rules don't allow, touch rowstile's internals, turn row-level security off, share more than it holds, approve its own requests |
| Anyone signed in with an API key or JWT | act as that user, within the key's scopes | widen the scopes, act as someone else |
The identity provider (whoever holds jwt_secret, or the private half of a key stored with authz.set_jwks) | say who each of its tokens signs in, and with which scopes | |
The sync engine (sync role, a preview: Electric, Zero, PowerSync) | read every row (it holds BYPASSRLS) and the sync index, and serve each client the rows the index gives its keys | read a masked column, or be the app role |
The trust boundary is between the app role and everything above it. A bug in the app (say, SQL injection) should not let an attacker read hidden rows through queries. What such an attacker can do depends on identity:
- On any Postgres, sign-ins are signed:
authz.act_as(), the logins andauthz.view_as()sign who is signed in, the scopes, the backend and the transaction with a key the app role can't read, and nothing else is believed (authz.who(),authz.explain()and the like switch who is signed in only for the length of their call). So the app role can't make up who is signed in, wider scopes than a key's, or a session that no longer views as someone: the settings are believed only as rowstile signed them, in this transaction, on this connection (tests/sessions.sh). A signature is for its transaction, not for a moment in it: the settings an earlier sign-in of the same transaction signed, put back with that signature, are believed again. That is a state rowstile signed there (the one before aview_as, say), and gives the backend nothingauthz.sign_out()and a sign-in don't. - The app role may call
authz.act_as(), so code running as the app role can claim to be anyone. Postgres roles other than the app role and its members can't sign anyone in. - If the app role itself is compromised, the attacker can claim any user either way: the backend is trusted to say who is signed in. Keep the app role's credentials inside the backend, and sign other clients in with keys or JWTs.
- A token is believed as whoever signed it. Whoever holds
jwt_secret, or the private half of a key stored withauthz.set_jwks, signs in as anyone, and so does whoever writes those rows: the owner, not the app role. The stored keys are public: a copy of a database that holdsjwt_secretlets its reader sign tokens, and a copy that holds a provider's keys alone doesn't. A key the provider retired is believed until the owner stores the provider's key set again (Identity). A connection checks a token's signature once, and notes it in a setting the app role may set: the note is signed as a session is, for that token, that key and that connection, so the app role can't make one up, bring one from another connection, or use one after the key changed.
What stops what
| attack (as the app role) | stopped by | checked in |
|---|---|---|
read a hidden row, by id, by COPY, through a prepared statement run as another user | row-level security on every governed table; policies read the user per statement | adversarial.sh |
see hidden rows through a function in WHERE that prints its argument | Postgres runs row-level security before functions that aren't LEAKPROOF (only superusers can mark them) | adversarial.sh |
SET row_security = off, disable row-level security, drop or add a policy, drop a trigger, replace a generated function | not the owner (applying refuses an app role that is the policy's owner or a member of it, AZ624, and authz.lint() reports one that owns a governed table); row_security = off makes the query fail instead | adversarial.sh, apply.sh, governance.sh |
read or write authz_int, authz.shares, authz.audit, authz.changes, the lock rows; call internal functions; read what the rules look up | no privileges on them; the views and functions the rules use are in authz_int, whose names the app role can't use (Postgres keeps a rule as read when the policy was applied, and checks a schema only when a name is looked up); it calls the authz.* API and the rules' explanations, which answer only for a new row or one the user may see | adversarial.sh |
| use rowstile's tables or administrators' functions through the owner's default privileges, or a grant made since | applying takes back every privilege on rowstile's schemas the policy doesn't give; authz.lint() reports later ones | adversarial.sh |
| run code as the owner: a function in a schema on the search path of rowstile's functions that run as the owner, taking a built-in's place | applying refuses a schema on that path that Postgres roles other than the owner may create in (AZ612); authz.lint() reports one opened later | adversarial.sh |
| run code as the owner: a trigger of its own on a governed table, which a foreign key's action that writes the table's rows runs as the tables' owner | the app role holds no TRIGGER privilege on the tables unless it was given (GRANT ALL gives it); authz.lint() reports it, on a governed table, a partition of one and a table that holds relationships | governance.sh, children.sh |
| update, delete or upsert onto a hidden row | row-level security (UPDATE 0, DELETE 0, an error for the upsert) | adversarial.sh |
| take ownership, move a row where the user may not write, stop inheritance above a folder | column rules (update owner_id : share, update parent_id after : parent.edit) | adversarial.sh, scenario.sql |
| share what the user can't share, a relation that isn't shared, or to widen their own access | authz.share() checks the relation is shared and the sharer holds what the policy asks | adversarial.sh, multi_scenario.sql |
| learn who has access, or the shares or links on, an object they can't share | authz.who, authz.list_shares and authz.list_links refuse, the same way for missing objects; so does authz.revoke_link, whether or not the id names a link; authz.explain for another user stops at what the one asking can't see, and leaves out who made a share and until when where they can't list the shares | adversarial.sh |
| approve their own access request, decide one they can't share | authz.decide_request() checks the decider | governance.sh, adversarial.sh |
| act as another user; widen a key's scopes; write during "view as" | signed sessions (above); scoped and view-as sessions are read-only where they must be | sessions.sh, identity.sh |
| sign in with a token its provider didn't sign: one that says it needs no signature, one signed with the provider's public key as if it were the secret, one that names a key nobody stored | a token's alg chooses its check, HS256 against jwt_secret alone and RS256 against the stored keys alone; any other alg, and a kid that names no stored key, is refused | identity.sh |
| a stale closure table granting access after a move | the locks a tree write takes on what it touches (its whole type, for a write of many rows); serialization errors in stricter isolation levels | interleave.py, stress.sh, concurrency.sh |
| a policy with a mistake that silently grants too much | compile-time and apply-time checks with line numbers; conditions that decide inheritance must not depend on time or user | policy_errors.py, fuzz_parser.py |
The review in CI (rowstile review, the GitHub action) runs on a pull request's files, which whoever opened it wrote. An include stays in the policy's folder: no .. out of it, no absolute path, no link leading out (AZ108), and the policy, the tests and the lock file rowstile.toml names stay in the folder rowstile.toml is in, the same way; so a pull request can't make the review read one of the runner's files, or its environment, and print it in the job's log (unit_test.py, policy_errors.py, cli.sh). The files it names to be written (the snapshot, the clients, the migrations' folder) stay in the git repository rowstile.toml is in, or in its folder when it is in none: a pull request's rowstile.toml can't make rowstile snapshot --check read a file outside the checkout and print its lines, nor rowstile snapshot, client, dev or migrate write one there (cli.sh). A .env beside rowstile.toml is read the same way, for the variables that say where the database is and no other: a pull request's .env can't set PATH or what git runs. And it isn't read when --db names the database, as the review's workflow does: it can't add a host or a port to the URL the workflow gave. The review believes the pull request's rowstile.toml, as CI believes its workflow files: run it on pull_request, where a fork's pull request gets no secrets, not on pull_request_target.
Known limits (accepted)
- Side channels. Code that can run arbitrary SQL as the app role can learn things it can't read:
EXPLAIN ANALYZEshows how many rows row-level security removed, so an index lookup such asWHERE id = 12reveals whether a hidden row exists; timing can too. Constraints tell it too, to any caller: a unique constraint, or a primary key the app lets callers choose (client-made ids, an import), refuses an insert that collides with a hidden row (authz.lint()lists both), and an upsert (ON CONFLICT DO UPDATE) onto a hidden row is refused where one onto a new id inserts it; a foreign key refuses deleting a row that hidden rows reference (a folder with a hidden file in it). These are Postgres behaviours: let the database make the ids (GENERATED ALWAYS AS IDENTITY, random uuids), delete the children the user can see first and answer "not empty" for the rest, and keep arbitrary SQL away from the app role (the backend decides which queries run). - Whether a row with an id exists is told by the rules' explanations as by inserting a row with that id:
authz.explain_rule(and a refused write's message) explains a row whose id no row has, and says no to all of it for a stored row the user can't see. - Whether a subject exists is told to whoever may share an object:
authz.shareanswers a share with a user or a group that isn't there withthere is no team 7(AZ708), and doesn't ask whether the sharer may see the one that is. A share needs its subject: one made for a row that isn't there would wait for whoever gets that id. And a foreign key tells whether the row it names is there, whoever may see it:authz.lint()names an app role that may make foreign keys to a governed table (REFERENCES, whichGRANT ALLgives). - Statistics of governed tables are hidden from the app role by Postgres (
pg_statsleaves out tables with row-level security), checked in adversarial.sh. - Tables without rules are readable in full by the app role (
authz.lint()says so), which suits directories such as users and groups. - SECURITY DEFINER functions the app adds bypass row-level security unless their owner is subject to it;
authz.lint()lists those it can see. - Conditions read with the policy owner's rights, in rules as in permissions: a subquery sees every row of the tables it reads, not only those the signed-in user may (the language, Speed and limits).
- Scopes limit what a token does, not what it can find out about its own user. A scoped session (an API key or a JWT with scopes) is held to its scopes by the rules and by
authz.can,authz.listand the otherauthz.*functions that say what it may do.authz.explain, asked of its own user, says why the user holds a permission or not. On an object the session may see, its first line is the session's answer (no user 1 does not hold edit on file 11, for a key whose scope isread), and the lines below walk the permission's parts with the user's full rights (yes folder.edit), without naming the scope as the reason. So a scoped key learns, on the objects it may see, what its user holds beyond its scopes. - Request context (
authz.ctx(...),authz_ctx.*settings) is whatever the app sets: a policy that trusts it trusts the backend. - The sync index tells the sync engine who may read what (a preview, The sync index): its readers tables say, for each row, the keys that may read it, and its keys table which keys each principal holds. The engine holds BYPASSRLS and reads every row, so it is trusted as the backend is: rowstile can't check what it serves each client, only that the index is right and that the app role can't read it. Behind Electric, the app's route (
electricShape) chooses whose filter a request gets, from who the database says signed in: it is the backend's, and trusted as the backend is. - No outside audit. rowstile has had self-review only.