Security

RolesCopy Anchor Link

Application roles get no grants on schema _gnomon tables. Grants on a tracked table are mirrored onto its routing view (and re-mirrored on every GRANT/REVOKE by the event trigger).

ConfinementCopy Anchor Link

gnomon.confine(role, branches) revokes the role's DML on base tables, removes it from gnomon_merger, and records which branches it may write (gnomon.acl; branches it creates are added). Branch writes check the acl inside the definer path, so a confined role sending arbitrary SQL still cannot write main or another branch, merge, or undo on main. cli/internal/mcp's agent test sends exactly such SQL through the MCP execute tool and checks each refusal. A mask profile additionally removes SELECT on base tables and routing views; the role reads through masked views.

Read isolation. A confined role reads only the branches in its access list and their ancestors; the check runs once per statement in _ctx_compute and raises 42501. The shared runs login (runs_role) is in every run's access list, so each of its transactions is bound to one run when it calls gnomon.begin(run), and it reads only that run's branch.

A role is a branch. gnomon.assign(role, branch) sets the role's defaults for gnomon.branch and search_path. Only gnomon_admin assigns, and only a superuser assigns a role that is a superuser, has BYPASSRLS or is a gnomon_admin member. The defaults are a convenience, not the boundary: a confined role that resets them still writes only its branches, and with no grant on the base tables a qualified name fails instead of reading main.

Agents and tokens. gnomon.agent_create makes a login role confined to its own branch with no grant on base tables, and a token for the MCP HTTP transport. Tokens are stored as SHA-256 hashes; agent_auth(token) (gnomon_admin and gnomon_runner only) maps one to its role, which the server then SET ROLEs to in the request's transaction. agent_stop disables the token, sets the role NOLOGIN, ends its sessions where the caller may, closes its branches and change requests, and can undo the merges of branches the agent created. The run record (gnomon.agent_call) is written through an insert-only definer function and hash-chained per run; agents cannot read it, gnomon_admin and gnomon_merger can, and verify_run checks the chain.

HTTP. gnomon serve and gnomon mcp --http log in as one role that is a member of every role they act as and issue SET ROLE per request inside a transaction, so every check in the database applies to the person or agent. The review app takes a database login or a trusted proxy's header (with a role map), sets a CSRF token for writes, and binds to 127.0.0.1 by default.

Schema changes on a branch. gnomon.ddl runs the statement as the caller against a shadow schema the caller owns, so it can do nothing the caller could not do by hand; a statement that touches real tables is detected and rolled back. What the merge later runs on main with gnomon's rights is derived from the catalogs, never the statement's text: column definitions with constant defaults, moving the hidden table, index definitions whose expressions call pg_catalog functions only, and comments. A merger should still read gnomon schema <branch> before merging.

Row-level securityCopy Anchor Link

On tables without user policies gnomon enables RLS with a permissive true policy for everyone (no effect on query plans) plus the restrictive arm-1 policy for gnomon_reader only. Tables that already use RLS keep their policies; gnomon adds no true policy and compiles the user's SELECT policies into gnomon_reader policies evaluated for the caller (current_user inside a policy reached through a view is the caller), on main's table, the branch heads, and the history arm. Superusers, BYPASSRLS roles and the table owner (unless RLS is forced) bypass, as on main. Branch writes are checked against the table's INSERT, UPDATE and DELETE policies as the caller, in the routing view's (invoker) INSTEAD OF trigger, before the definer write path: what main would refuse, the branch refuses, so a merge cannot publish rows their writer could not have written. Whether the table's own RLS is in force is re-evaluated on every DDL to it: RLS enabled without policies stays deny-all, and policies created after tracking replace gnomon's permissive policy instead of being OR'ed with it. Tested in 06_ops (two roles on a branch; a deny-all table; policies added after tracking; write policies; RLS turned off again; untrack).

Writes to main from a branch sessionCopy Anchor Link

A session on a branch (or reading the past) that names a tracked table with its schema (public.t) would write main in SQL-only mode; the versioning triggers refuse it (25006). gnomon's own writes to main (merges, undo) carry a merge token, which lets them through. Writes to main through a routing view (PostgREST profiles do this) that would overwrite a row changed since the statement read it raise 40001 instead.

Every SECURITY DEFINER pathCopy Anchor Link

All pin search_path = pg_catalog, pg_temp. Generated SQL qualifies every name and uses OPERATOR(schema.=) for comparisons, so a caller's objects cannot capture them. Functions owned by the extension owner run with its rights and check the caller (_gnomon.who(): the SET ROLE target, else the session user) where noted.

Agents, runs, policies and workflows:

test/sql/09_security.sql runs an ordinary role and a confined role against these and expects a refusal for each operation it must not perform.

Known limitsCopy Anchor Link

• User triggers mirrored onto branches run as gnomon_writer; a table owner can therefore run code with gnomon_writer's rights by adding a trigger to their own tracked table. Treat table ownership as trusted, or keep tracked tables owned by a role you trust.
• Checks (gnomon.add_check) are arbitrary SQL run inside merges; only gnomon_admin can add them.
• gnomon_merger is a member of gnomon_writer and so has DML on branch storage tables: grant it only to roles trusted with main.
• Custom merge strategies run inside gnomon.merge with gnomon's rights; only the roles that may manage a table (a superuser, gnomon's owner, or a gnomon_admin member that owns it) can set one.
• Erasure cannot reach WAL, base backups or replicas until they expire. Crypto-shredding reaches archives at once, but the subject keys are rows of _gnomon.subject_key and so are in WAL, backups and pg_dump output until those expire: an erased subject's archived values stay recoverable by whoever holds such a backup and the archive.
• A run's login (run_login) is a real role with a password; anyone holding its connection string can work on that run's branch until run_end. It is confined, so it never reaches main or other branches.
• The Kafka sink speaks plaintext only (no TLS or SASL): keep it on a private network, or use a webhook into a REST proxy.
• With the C module, a branch session's DDL on tracked tables runs as gnomon.ddl(statement), so the same checks apply as when it is called directly (the statement runs as the caller against the shadow; recorded expressions may use pg_catalog only).
• Search views evaluate the branch filter as an ordinary WHERE, so a function in a query can see a main row the branch hides. That is why only roles that may read the table itself get them.
• gnomon._in_ddl and gnomon._ddl_internal are ordinary custom settings any session can set; they turn off gnomon's DDL event triggers (and the refusal of plain DDL from a branch session) for that session. They guard against accidents, not against a role that may run DDL anyway.
• Notification and sink webhooks carry change data to the URLs gnomon_admin configures; secrets in their configuration are readable by gnomon_admin members.
• With the C module, gnomon.c_module and the hooks are global to the server; routing is skipped inside gnomon's own code (detected by its pinned search path) and while gnomon._in_ddl is set.