Using it from app code
The database holds each transaction to one principal, whatever signs it in: authz.act_as and the logins refuse to sign in a transaction signed in as someone else already (AZ716, Identity). The SDKs below refuse it earlier, in their own words, before anything is sent.
Python apps use the Python SDK: Rowstile(app, engine, user=...) for FastAPI, install(engine) for SQLAlchemy, and transactions for psycopg and asyncpg sign each transaction in. Rowstile(...) and Django's middleware turn refusals into 403 and hidden rows into 404, and check the app's connection at start-up (on psycopg or asyncpg alone, problems(conn) is that check). A transaction is one principal's: inside one signed in already, work for someone else raises a RuntimeError before any SQL is sent for it. SQLAlchemy and Django check each statement; psycopg and asyncpg check each transaction() block, and a statement inside a block runs as the block's principal. integrations/fastapi is its conformance suite. TypeScript apps use the TypeScript SDK: @rowstile/prisma (a driver adapter that signs every transaction in, and a client extension), /pg, /postgres (postgres.js), /drizzle, /next (signed-in reads kept out of caches, 403 and 404 from route handlers and server actions), /react (usePerms, <Can>, a headless share dialog, live updates), /vitest and /jest (a preview); integrations/nextjs is their conformance suite, integrations/node a plain Express server's (a preview), integrations/electric that of /client's route in front of Electric (Electric, a preview), and rowstile client writes only the policy's names for them (src/authz.gen.ts), as rowstile client ts-sdk does. rowstile client ts is a client of its own, for pg without the SDK: its types don't reach the SDK's calls. A transaction is one principal's: inside one these packages signed in, their work for anyone else throws an Error before anything is sent for it (Node apps). The TypeScript SDK's calls (calls(q), and each driver's: Prisma's db.$authz) are can, perms, permsOf, list, listShares, share, unshare, requestAccess, explainRule, connectionCheck and expect (and Prisma's ids). Its share takes no expiry, start or caveat. For those, and for the rest of the table below (who, explain, links, requests, reviews, keys), call the authz.* function in SQL. The other SDKs' calls are fewer: their paragraphs below name them. Go apps use the Go SDK (preview): rowstile.Tx signs pgx transactions in, rowstile.Middleware says whom each request acts for, and Handler and WriteProblem answer refusals with problem details; integrations/go is its conformance suite, and rowstile client go writes the policy's names for it (internal/authz/authz.go). .NET apps use the .NET SDK (preview): Rowstile.EntityFrameworkCore signs in every EF Core transaction, and every command outside one; Rowstile.AspNetCore says whom each request acts for and answers refusals with problem details; on Npgsql alone, Rowstile begins transactions signed in. integrations/aspnetcore is its conformance suite, and rowstile client csharp writes the policy's names for it (Authz.g.cs). Rails apps use the Ruby SDK, a preview: its Railtie signs every Active Record transaction in, answers a refusal with 403 and a hidden row with 404, and checks the app's connection when it is served; integrations/rails is its conformance suite. Java apps use the Java SDK (preview): dev.rowstile:rowstile over JDBC, and dev.rowstile:rowstile-spring-boot-starter, which signs in every transaction Spring begins as the request's user and answers refusals with problem details; integrations/spring is their conformance suite, and rowstile client java writes the policy's names for them (AuthzNames.java). Kotlin apps use its Kotlin module, dev.rowstile:rowstile-kotlin (preview): transactions signed in from coroutines, Exposed's transactions signed in, and a Ktor plugin that signs in each request's transactions and answers refusals with problem details; integrations/ktor is its conformance suite, on the names rowstile client java writes. Rust apps use the Rust SDK (preview): the rowstile crate signs sqlx and tokio-postgres transactions in, turns refusals into typed errors and problem details, and gives Axum an extractor for each request's transaction; integrations/axum is its conformance suite, and rowstile client rust writes the policy's names for it (src/authz.rs). Elixir apps use the Elixir SDK (preview): Rowstile.transact signs an Ecto or Postgrex transaction in, Rowstile.Plug says whom each request acts for, and its Phoenix fallback answers refusals with problem details; integrations/phoenix is its conformance suite, and rowstile client elixir writes the policy's names for it (lib/my_app/authz.ex). PHP apps use the PHP SDK (preview): rowstile/rowstile over PDO, and in Laravel a service provider that signs in every transaction as the request's or the job's principal and answers refusals with problem details; integrations/laravel is its conformance suite, and rowstile client php writes the policy's names for it (database/authz.php).
What every SDK reads of an error. The SDKs read the database's errors by the same rules, and each SDK's own tests hold each rule:
- rowstile's code is the
rowstile help AZ709in the error's HINT. The message is not read for one: Postgres's own messages quote the input they couldn't read (invalid input syntax for type bigint: "..."), so a code there would be the request's choice. - The not-signed-in error is a 28000 with code AZ701. A 28000 without a code is Postgres's own: a login turned down when connecting, a role that isn't there, a line missing from
pg_hba.conf. It stays a database error, a 500. - Postgres's own row-level security refusal (
new row violates row-level security policy for table "notes": an insert read back without the select rule, an upsert, a MERGE) is a refusal, a 403, in any language. So is one by a restrictive policy of the app's own, which Postgres names (new row violates row-level security policy "short_notes" for table "notes";authz.lint()reports such a policy): its refusal is Postgres's words and no rule's, with no command but an upsert'supdate. The SDKs tell these by the function in Postgres that raised them (ExecWithCheckOptions, the error's routine field), not by their words. Those words name the table without its schema, and so does the refusal:notes, where a rule's refusal saysapp.notes. Through Prisma, the TypeScript SDK adds the schema back from the models. On a server whoselc_messagesisn't English, the table and the rule it names are in words the SDKs don't read, so the refusal names neither. Two drivers give the server's text and not that field: PHP's, and Prisma's adapters. There, the refusal in another language stays a database error, a 500, and PHP'sphp artisan rowstile:checksays so (and exits 0). Set the app role's messages to English (ALTER ROLE app_user SET lc_messages = 'C', by a superuser). - Nobody has one spelling: a principal without an id (none, or empty), whatever its type, is the SDK's nobody, as
authz.act_assigns it in. So work for nobody runs inside a transaction begun for any spelling of it.
What every SDK writes of a key, a page and a principal. The SDKs write these the same way, and each SDK's own tests hold each rule:
- A key of several columns is given as any of the language's arrays, lists or tuples, its values in the key's order (in Rust,
composite_key). An array of one value is that value, and no key (null) is sent as NULL. - It is written as Postgres writes the row:
(1,"a b",). A field is quoted when it is empty, or holds a quote, a comma, a backslash, a parenthesis or one of ASCII's six spaces (space, tab, newline, carriage return, vertical tab, form feed), asrecord_outdoes; a no-break space or an em space is not quoted. A NULL field is nothing. So a hidden row's id, a refusal's message and the keys ofpermsOf's answer spell a key asauthz.listdoes. In Go, a value whose text in Go isn't Postgres's (atime.Time, a[]byte, a struct withoutStringorValue) is an error before anything is sent: give its text. - A page without a cursor (null) starts at the first row, and a page without a size is every row after its cursor (a NULL size). In Go,
Page.Limit0 is no size; in Rust,Page.limitis anOption. - A hidden row's 404 says
app.notes 7 not found:app.notes not foundwithout the key,row 7 not foundwithout the table,not foundwith neither. - A principal is written as text as the audit trail and
created_byname who acted, and read back by the SDK:42for a user,service:3,nobody, anduser:<id>for a user whose id holds:or isnobody.
Underneath every SDK, and for every other stack:
Everything is a SQL function in schema authz, callable by the app role, acting as the signed-in user. Ids are text or the type's key type. A composite key's id is the text Postgres writes for the row: authz.can('folder', '(1,42)', 'view'), or from SQL ROW(f.org_id, f.id)::text; authz.list returns ids in that form ('(1,"a b")' for a text column that needs quoting), and the generated clients take a tuple or array.
authz.can, authz.list, authz.perms and authz.perms_of answer for the rows you may see: on a table with a select rule, a row its rule doesn't let you select reads as a missing one, whatever you hold on it (false, left out of the list, no permissions). authz.who_among asks authz.can as each one, so it answers the same way. Seeing who has access (authz.who, authz.list_shares, authz.list_links, authz.explain for someone else) takes share on a row you may see. What acts on an object asks the permission itself: authz.break_glass works on a folder you can't see.
| task | function |
|---|---|
| check, list, all permissions | authz.can('file', 11, 'edit'), authz.list('folder', 'edit'), authz.perms('file', 11) |
| all permissions on many objects (a list's buttons) | authz.perms_of('file', ARRAY['10', '11']): a row per id, id and perms |
| list in pages, in key order | authz.list('file', 'view', NULL, 1000), then authz.list('file', 'view', '<last id>', 1000) (a NULL size: no limit; a cursor that isn't an id, or a negative size: AZ710) |
| who has access (for people who may share it) | authz.who('folder', 3, 'view') |
| why, or what is missing | authz.explain('file', 11, 'edit'); for someone else (people who may share it, as for who): ..., 'edit', '7'), which says only what you may see: it stops at an object or a team you can't see, and gives who made a share and until when only where you may list the shares |
| why a write is or would be refused | authz.explain_rule('app.files', 'update', '11', '{"name": "x"}'): NULL if the row isn't there or you can't see it (404); an insert: authz.explain_rule('app.files', 'insert', NULL, '{"folder_id": 6}') |
| which of these people may see it (live updates) | authz.who_among('file', 11, 'view', ARRAY['1', '2']): 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), in a transaction signed in like any other (as nobody will do: authz.act_as(NULL, NULL)) |
| the sharing dialog | authz.list_shares('folder', 3), for people who may share it: a row a share, with relation, role (a custom role's name), subject_type, subject_id ((link) for a share link), subject_relation (member for team#member, else empty), expires_at, starts_at, caveat, created_by and created_at |
| share and unshare | authz.share('file', 13, 'viewer', 'user', 4, '', now() + interval '1 day') (then when it starts, a caveat and its arguments: the language), authz.unshare(...) |
| share links | authz.create_link('folder', 3, 'viewer') returns a token; requests use it with SET LOCAL authz_ctx.links = '<token>', which the rules read through authz.link_hashes() (the tokens' hashes: the app sets the setting, and has no need to call it) |
| an object's links, and turning one off | authz.list_links('folder', 3): each link's id, relation, who made it, when, and until when, for people who can share the object or may make such links; authz.revoke_link('folder', 3, '<id>') turns one off, and needs what unsharing its relation needs (the id is not the token, and opens nothing; an id that names no link there: AZ708); a link given in several relations is judged in each as things are before it goes, and goes from all of them or from none |
| custom roles | authz.create_role('org', 1, 'folder', 'reviewer', ARRAY['view']) returns the role's id (needs manage_roles on the org); share it as authz.share('folder', 3, 'role:<id>', 'user', 7); authz.set_role_permissions(id, ARRAY[...]) (adding a permission needs it held on each object the role is given on), authz.delete_role(id), authz.roles_of('org', 1) (for those who hold manage_roles or view on the org); for users, not services (AZ715) |
| API keys | authz.create_api_key('laptop', 'read') (shown once), authz.list_api_keys(), authz.revoke_api_key(id); a service's keys are made by a user holding manage_keys on it (Identity), and a service making its own is refused (AZ715) |
| sign in | authz.login_key('ak_...'), authz.login_jwt('eyJ...') (HS256 with a secret in authz.settings, or RS256 with the provider's keys, which the owner stores: Identity) |
| the app's connection, at start-up | authz.connection_check(): a row per problem, severity and problem (Checking the database) |
| support "view as" | authz.view_as('42', 'ticket 1234'): read-only, audited, needs can impersonate on the user; for users, not services (AZ715) . In a session limited by scopes (an API key's, a token's) it keeps them, and never reads more than they give . It writes nothing, whatever they hold: the rules refuse every write while a session views as someone |
| is the session limited | authz.session_limited(): true while a key's or a token's scopes, or viewing as someone, limit the transaction, as a sync engine's route asks (Identity) |
| ask for access | authz.request_access('folder', 3, 'viewer', 'for the audit', '7 days'), authz.cancel_request(id); for users, not services (AZ715) |
| decide requests | authz.pending_requests(), authz.decide_request(id, true, 'ok'): approving makes a share that ends after the requested time; for users, not services (AZ715) |
| emergency access | authz.break_glass('folder', 6, 'viewer', 'INC-7 outage', '1 hour'): needs break_glass, one day at most, audited, announced on channel authz_alerts; for users, not services (AZ715); refused over a share of yours of the relation that starts later or has a caveat (AZ717) |
| access reviews | authz.start_review('folder', 3), authz.review_items(id), authz.review_decide(id, item, false), authz.close_review(id); for users, not services (AZ715) |
Administrators (the policy's owner and superusers; the app role is refused) also have:
| task | function |
|---|---|
| inheritance tables match a rebuild | authz.verify() |
| the change feed (for caches, search indexes, sync jobs) | poll authz.changes_since(pos), pos the last entry read (where to start: an entry shows once the transactions older than its own end, so a listener polls now and then too); LISTEN authz_changes only after INSERT INTO authz.settings VALUES ('notify_changes', 'on') (every notifying commit waits its turn) |
| the audit trail | SELECT * FROM authz.audit (append-only; every share, unshare, role, membership change, request, review, break-glass, view-as, API key) |
| retention (schedule these: pg_cron, or the app's jobs) | authz.trim_changes() keeps 7 days of the feed (or the setting changes_keep); authz.trim_audit(interval '2 years') removes older audit entries and records that it did ; authz.announce_timed_shares() tells the feed of the shares that ended or began since it last ran |
| group sync from an identity provider | authz.sync_members('team', '10', 'member', ARRAY['1', '2']) makes the group's rows in the relation's table (app.team_members) this list: it deletes and inserts there. For a relation read from one table, without where; shares are not touched. An empty list removes every member; a NULL list, or a NULL in it, is refused (AZ710). |
| a SCIM endpoint for an identity provider's users and groups | authz.scim(method, path, query, body, token) answers a SCIM request with a status, a body and a location, once the owner said what it reads (authz.set_scim): Identity |
| invariants | authz.check_invariants() |
| ways around RLS | authz.lint(): see Checking the database |
Generated clients wrap these with the policy's names, so a typo in a permission is a compile error: rowstile client py > authz_client.py (DB-API: psycopg and friends) or rowstile client ts > authz.ts (TypeScript, for pg or anything with query(text, params); on the TypeScript SDK, rowstile client ts-sdk, the names alone); rowstile client go writes the names alone, for the Go SDK. Generate it from the policy in force and commit it next to your code; regenerate when the policy changes (the file manager's tests fail when it is stale).
- Python: supported. Whether its names are part of what 1.0 promises is decided before 1.0. It has
Authz(conn), withsign_in,sign_in_as(a principal other than a user),principal,connection_check,can,list(withafterandlimitfor pages),perms,who,explain,share(itscaveat_argsa dict),unshare,list_shares,create_link,list_links,revoke_link,use_links,request_access,decide_request,cancel_request,pending_requests,break_glass,start_review,review_items,review_decide,close_review,login_key,login_jwt,create_api_key,list_api_keys,revoke_api_key,explain_rule,expectandwho_among; the errorsRefused(.table,.command,.why) andNotFound, withrefusal(error)turning a driver's error into aRefused; and the policy's names as types:ObjectType,Permission, and each type's own,FilePermissionforfile(the type's name with a capital first letter; two types that would get the same name,docandDoc, get none). Rows come back as dicts. The file manager and the messenger use it.
Refusals say why. A write the rules refuse raises SQLSTATE 42501 with the rule and what is missing, as the signed-in user may know it (nothing about rows they can't see):
ERROR: permission denied: user 1 may not insert this row into app.files
DETAIL: no insert : folder.edit and owner (line 80)
yes folder.edit
no ownerThe error's table, schema and constraint (authz_insert, authz_update) fields are set, which is what refusal(error) reads. An allowed write never runs this (the check is rule OR refuse(row)). A share or an unshare refused (AZ705) says why in its DETAIL too, which the SDKs give as why: what authz.explain answers the one sharing, for the permission sharing takes, and for an object they can't see the words one that isn't there gets. Updates and deletes the rules don't allow change no rows instead (row-level security leaves them out): az.expect(result, table, command, id) then raises NotFound or Refused with authz.explain_rule's answer, worded like the refused insert above: permission denied: user 3 may not update row 11 of app.files. A key of several columns is written as the database writes it, (1,2).
- TypeScript: preview.
asUser(db, id, fn)andasPrincipal(db, type, id, fn)runfnin a transaction signed in (Python'ssign_inandsign_in_as).authz(db)hascan,connectionCheck,list,perms,who,explain,share(its options in an object:subjectRelation,expiresAt,startsAt,caveat,caveatArgs),unshare,listShares,createLink,listLinks,revokeLink,useLinks,requestAccess,decideRequest,cancelRequest,pendingRequests,breakGlass,startReview,reviewItems,reviewDecide,closeReview,loginKey,loginJwt,createApiKey,listApiKeys,revokeApiKey,explainRule,expectandwhoAmong: Python's calls in camelCase, exceptprincipal. It also hasRefused,NotFoundandrefusal(e), and the typesObjectTypeandPermission<T>. It may change before it is supported. - Go: preview.
rowstile client go > internal/authz/authz.gowrites the policy's names alone, for the Go SDK (github.com/rowstile/rowstile/sdk/go, a preview too): each type is a constant (TypeNote), and each type's permissions a type of their own (NotePermission, withNoteEditandNoteView), which the SDK'sCan,PermsOfandListtake. The calls themselves are the SDK's: Go. A transaction is one principal's: inside onerowstile.Txsigned in already,Txfor someone else gives an error before any SQL is sent, androwstile.LoginKey(ctx, tx, key)(orLoginJWT) signs a request's key in inside it, whichTxthen follows;rowstile.WithOptions(pool, opts)hasTxbegin one with pgx's options. It may change before it is supported. - C#: preview.
rowstile client csharp > Authz.g.cswrites the policy's names for the .NET SDK (ASP.NET Core and EF Core): a class for each type, holding itsObjectTypeand its permissions (Policy.Note.Edit), which the SDK's calls take, so a misspelled one doesn't compile. A name is the policy's in PascalCase (org_unitisOrgUnit); two that would get the same,docandDoc, get none, and neither does one that would hide what every class inherits (to_string:ToString); the file says so. A transaction is one principal's: in EF Core, work for someone else inside one signed in already (oneBeginSignedInAsyncbegan on the context's connection too) throws anInvalidOperationExceptionbefore any SQL is sent, and so does work in aTransactionScopethe connection takes part in. It may change before it is supported. - Ruby: preview.
rowstile client rubywrites the policy's names as constants (Authz::Note::EDIT), androwstile client rbstheir signatures, for Steep:Authz.querieshascan,perms_ofandpermittedtaking the policy's types and permissions. The gem hasRowstile.acting_as,Rowstile::Refused,Rowstile::NotFound,Rowstile.refusal(e)andRowstile.expect. A transaction is one principal's: inside one signed in already, a statement while the code acts for someone else raises aRuntimeErrorbefore it is sent. It may change before it is supported. - Java: preview.
Rowstile.transaction(conn, who, work)runsworkin a transaction signed in, andRowstile.signIn(conn, who)signs in one already open;Rowstile.actingAs(who, work)andRowstile.job(who, work)say whom the transactions Spring begins act for. A transaction is one principal's: in Spring, work for someone else that joins one signed in already, or a statement on its connection while the code acts for someone else, throws anIllegalStateExceptionbefore any SQL is sent.Rowstile.signedInAlready(signed, who)is that error.Authzhascan,perms,permsOf,list(withafterandlimit),verdict,expect,connectionCheckandcheck, over one connection (Authz.on(conn)) or, in Spring, the transaction open now. It also hasRefused,NotFound,ConnectionProblem,ProblemandErrors.problem(e), and the policy's names asObjectTypeconstants and an enum of each type's permissions. It may change before it is supported. - Kotlin: preview.
DataSource.transaction(who) { ... }runs a block in a transaction signed in, onDispatchers.IO.transaction(who, db)andsuspendTransaction(who, db)are Exposed's, signed in first, andJdbcTransaction.signIn(who)signs in one already open.ActingAs(who), an element of a coroutine's context, says whom the code acts for, andactingFor()reads it; the Ktor pluginRowstilegives each request one, and answers rowstile's errors with problem details (respondProblem).calls, on a connection or in an Exposed transaction, is the Java SDK'sAuthz, andexpecttakes an Exposed table.problem(),refusal()anderrorCode()read an error, or give null;assertRefusedandassertNotFoundare for tests. A transaction is one principal's: in one these signed in, a statement while the code acts for someone else (withContext(ActingAs(...))), or for nobody, throws anIllegalStateExceptionbefore it is sent, and the transaction goes on as it was. It may change before it is supported. - Rust: preview.
rowstile::sqlx::begin(pool, who)androwstile::pg::begin(client, who)begin a transaction signed in; each module hascan,perms_of,list(with aPage),expectandcheck.ErrorisRefused,NotFound,Call,NotSignedIn,Connection,DatabaseorOther, withcode()andproblem(). With theaxumfeature,TxandSignedIn(who, with no connection yet: for a handler that reads a body) are extractors for a state that isSignIn, whoseprincipalis async, andErroris a response; withtesting,per_binary,refusedandnot_found.rowstile client rustwrites the policy's names: a constant for each type and an enum of each type's permissions, implementingPermission. A transaction is one principal's, and neitherbeginruns inside another:sqlx::begintakes a connection of its own from the pool, andpg::begintakes the client, which its open transaction holds. It may change before it is supported. - Elixir: preview.
rowstile client elixirwrites the policy's names as a module for each type and a function for each permission (MyApp.Authz.Note.edit()), whichRowstile.can?,perms_ofandlisttake, so a misspelled one doesn't compile. The package hasRowstile.transact,Rowstile.expect,Rowstile.Refused,Rowstile.NotFound,Rowstile.CallErrorandRowstile.problem(e): Phoenix. A transaction is one principal's: inside oneRowstile.transactsigned in already, atransactfor someone else raises aRuntimeErrorbefore anything is sent, and so does atransactinside a transaction it didn't begin. It may change before it is supported. - PHP: preview.
Rowstile::transaction($pdo, fn)andtransactionAs($pdo, $who, fn)runfnin a PDO transaction signed in;Rowstile::actingAs($who, fn)says whom the transactions Laravel's connections begin act for. A transaction is one principal's: inside one signed in already, work for someone else throws aLogicExceptionbefore any SQL is sent.Querieshascan,permsOfandlist(withafterandlimit), over PDO or a Laravel connection (Laravel\Database::queries()), and the SDK hasRowstile::expect,Rowstile::check,Refused,NotFound,CallError,ProblemandRowstile::problemOf($e).rowstile client phpwrites an enum of each type's permissions, in the namespaceAuthz(Authz\NotePermission::Edit), which the SDK's calls take, so PHPStan finds a misspelled one. It may change before it is supported.