rowstile 0.1.0a2__py3-none-any.whl

rowstile/__init__.py

@@ -0,0 +1,335 @@
+"""rowstile for Python apps.
+
+Every transaction signs in as whoever the request (or the job) acts for, with `authz.act_as()`; the database's
+refusals become `Refused` (a 403 with the reason), rows the user can't see become `NotFound` (a 404). The
+package holds no rowstile logic: it calls the `authz.*` functions the policy made, and translates their answers.
+
+    import rowstile
+    with rowstile.acting_as(42):                  # or ("service", 3), or None for nobody
+        ...                                       # every transaction in here signs in as user 42
+
+The integrations: `rowstile.fastapi` (one line: Rowstile(app, engine, user=...)), `rowstile.sqlalchemy` (sync
+and async engines, SQLModel too), `rowstile.psycopg`, `rowstile.asyncpg`, `rowstile.alembic` (autogenerate
+leaves rowstile's objects alone) and `rowstile.testing` (pytest fixtures).
+"""
+from __future__ import annotations
+
+import contextlib
+import contextvars
+import enum
+from collections.abc import Callable, Iterable, Iterator, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, LiteralString, ParamSpec, TypeAlias, TypeVar, cast
+
+from ._version import __version__
+
+if TYPE_CHECKING:
+    from sqlalchemy.engine import Engine
+
+Id: TypeAlias = "int | str"
+# who a transaction acts for: 42, '42' (a user, whatever the id holds), ('service', 3), a Principal, or None (nobody)
+Who: TypeAlias = "Principal | Id | tuple[str, Id | None] | None"
+Problem: TypeAlias = "dict[str, str | int | list[str] | None]"     # an RFC 9457 problem body
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+@dataclass(frozen=True)
+class Principal:
+    """Who a transaction acts for: a user (type 'user'), another principal type the policy declares
+    (a service, a bot), or nobody (id None: only what `anyone` may see)."""
+    type: str = "user"
+    id: str | None = None
+
+    @classmethod
+    def of(cls, who: Who) -> Principal:
+        """42, '42', ('service', 3), a Principal, or None (nobody). A plain id is a user's, whatever it holds:
+        'service:3' is the user whose id that is (ids often come from outside: a username, an identity
+        provider's subject), never service 3. Another principal type is named: ('service', 3)."""
+        if isinstance(who, Principal):
+            return who
+        if who is None:
+            return NOBODY
+        if isinstance(who, tuple):
+            kind, pid = who
+            return cls(str(kind), None if pid is None else str(pid))
+        return cls("user", str(who))
+
+    @classmethod
+    def parse(cls, text: str) -> Principal:
+        """What str() wrote, read back: 'service:3' is service 3, '42' user 42, 'nobody' nobody. For text your
+        own code wrote (a job's argument, the audit trail's `by`), not for an id that came from outside."""
+        if text == "nobody":
+            return NOBODY
+        if ":" in text and not text.startswith("("):
+            kind, pid = text.split(":", 1)
+            return cls(kind, pid)
+        return cls("user", text)
+
+    def __str__(self) -> str:
+        return "nobody" if self.id is None else (self.id if self.type == "user" else f"{self.type}:{self.id}")
+
+
+NOBODY = Principal("user", None)
+_current: contextvars.ContextVar[Principal | None] = contextvars.ContextVar("rowstile_principal", default=None)
+# the rows the ORM updated or deleted lately (sqlalchemy.why_stale): a list each request or acting_as block
+# makes, which the ORM's hooks add to (they may run in another greenlet, which sees the same list)
+# (the engine, the table, update or delete, the row's key)
+_Write: TypeAlias = "tuple[Engine, str, str, tuple[object, ...]]"
+_writes: contextvars.ContextVar[list[_Write] | None] = contextvars.ContextVar("rowstile_writes", default=None)
+
+
+class _Unset(enum.Enum):
+    UNSET = "unset"            # an argument left out: whoever the code acts for now
+
+
+_UNSET = _Unset.UNSET
+
+
+def current() -> Principal | None:
+    """Who the code running now acts for (set by acting_as, the web integration or a job), or None if unset."""
+    return _current.get()
+
+
+@contextlib.contextmanager
+def acting_as(who: Who) -> Iterator[Principal | None]:
+    """Everything in the block (every transaction the integrations begin) acts for `who`."""
+    token, writes = _current.set(Principal.of(who)), _writes.set([])
+    try:
+        yield _current.get()
+    finally:
+        _writes.reset(writes)
+        _current.reset(token)
+
+
+def job(who: Who) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """A decorator for background jobs (Celery, RQ, FastAPI's BackgroundTasks): the job acts for `who`, e.g.
+    @rowstile.job(("service", 3)). Async functions work too."""
+    import functools
+    import inspect
+
+    def wrap(fn: Callable[P, R]) -> Callable[P, R]:
+        if inspect.iscoroutinefunction(fn):
+            coroutine = fn
+
+            @functools.wraps(fn)
+            async def run_async(*a: P.args, **kw: P.kwargs) -> object:
+                with acting_as(who):
+                    return await coroutine(*a, **kw)
+            return cast("Callable[P, R]", run_async)       # R is the coroutine run_async returns too
+
+        @functools.wraps(fn)
+        def run(*a: P.args, **kw: P.kwargs) -> R:
+            with acting_as(who):
+                return fn(*a, **kw)
+        return run
+    return wrap
+
+
+def literal(value: object) -> str:
+    """A SQL string literal (standard_conforming_strings, as every supported Postgres has it)."""
+    return "NULL" if value is None else "'" + str(value).replace("'", "''") + "'"
+
+
+def act_as_args(who: Who | _Unset = _UNSET) -> tuple[str | None, str | None]:
+    """authz.act_as's arguments, (type, id): ('user', '42'), or (None, None) for nobody (who is None). With
+    no argument, as whoever the code acts for now (nobody if unset)."""
+    p = (current() or NOBODY) if isinstance(who, _Unset) else Principal.of(who)
+    return (None, None) if p.id is None else (p.type, p.id)
+
+
+def act_as_sql(who: Who | _Unset = _UNSET) -> str:
+    """The statement that signs a transaction in: SELECT authz.act_as('user', '42'); None is nobody. With no
+    argument, as whoever the code acts for now (nobody if unset). The values are written into the statement:
+    where the driver takes parameters, pass act_as_args() instead (psycopg reads % in a statement)."""
+    kind, pid = act_as_args(who)
+    return f"SELECT authz.act_as({literal(kind)}, {literal(pid)})"
+
+
+# --- errors -------------------------------------------------------------------------------------------
+class Refused(Exception):
+    """The database refused a write, and said why: the rule (table and command), and the explanation."""
+    code = "AZ709"                      # rowstile help AZ709
+
+    def __init__(self, message: str, table: str | None = None, command: str | None = None,
+                 why: Sequence[str] = ()) -> None:
+        super().__init__(message)
+        self.message, self.table, self.command, self.why = message, table, command, list(why)
+
+    def problem(self) -> Problem:
+        """An RFC 9457 problem body for a 403."""
+        return {"type": "https://rowstile.dev/problems/refused", "title": "Forbidden", "status": 403,
+                "detail": self.message, "table": self.table, "command": self.command, "why": self.why,
+                "code": self.code}
+
+
+class NotFound(Exception):
+    """The row isn't there, or whoever the transaction acts for can't see it."""
+
+    def __init__(self, table: str | None = None, id_: object = None) -> None:
+        super().__init__(f"{table or 'the row'} {'' if id_ is None else id_} not found".replace("  ", " "))
+        self.table, self.id = table, None if id_ is None else str(id_)
+
+    def problem(self) -> Problem:
+        return {"type": "https://rowstile.dev/problems/not-found", "title": "Not Found", "status": 404,
+                "detail": str(self)}
+
+
+class NotSignedIn(Exception):
+    """A query that needs to know who is asking ran in a transaction nobody signed in to (strict sign-in)."""
+    code = "AZ701"                      # rowstile help AZ701
+
+
+class ConnectionProblem(RuntimeError):
+    """authz.connection_check() found that the app's connection skips row-level security (or worse)."""
+
+    def __init__(self, problems: Iterable[str]) -> None:
+        self.problems = list(problems)
+        super().__init__("the app's database connection can't be used with rowstile: " + "; ".join(self.problems))
+
+
+def _db_error(exc: BaseException) -> list[BaseException]:
+    """The error and the driver's errors inside it: SQLAlchemy keeps the driver's in .orig, and its asyncpg
+    adapter keeps asyncpg's own as the cause of that."""
+    out: list[BaseException] = []
+    seen: set[int] = set()
+    todo: list[BaseException | None] = [exc]
+    while todo:
+        e = todo.pop(0)
+        if e is None or id(e) in seen:
+            continue
+        seen.add(id(e))
+        out.append(e)
+        todo += [getattr(e, "orig", None), e.__cause__]
+    return out
+
+
+def _field(errs: list[BaseException], *names: str) -> str | None:
+    for err in errs:
+        for n in names:
+            v = getattr(err, n, None)
+            if v and isinstance(v, str):
+                return v
+            diag = getattr(err, "diag", None)
+            v = getattr(diag, n, None) if diag is not None else None
+            if v:
+                return str(v)
+    return None
+
+
+def error_code(exc: BaseException) -> str | None:
+    """rowstile's code for a database error (AZ709; `rowstile help AZ709` says what it means): from its HINT,
+    where the runtime puts it, or its message. None for an error rowstile didn't raise."""
+    import re
+    errs = _db_error(exc)
+    for text in (_field(errs, "message_hint", "hint"), _field(errs, "message_primary", "message") or str(errs[-1])):
+        m = re.search(r"(?:rowstile|rowfence) help (AZ\d{3})|\[(AZ\d{3})\]", text or "")
+        if m:
+            return m.group(1) or m.group(2)
+    return None
+
+
+def sqlstate(exc: BaseException) -> str | None:
+    err = _db_error(exc)
+    return _field(err, "sqlstate", "pgcode")
+
+
+def refusal(exc: BaseException) -> Refused | None:
+    """A Refused for an error that is the database refusing a write (SQLSTATE 42501, raised by rowstile's
+    policies with the rule and why), else None. psycopg, psycopg2 and asyncpg, bare or in SQLAlchemy's.
+    Another 42501 (a table the app role was never granted) is the app's mistake, not a refusal: None."""
+    err = _db_error(exc)
+    if _field(err, "sqlstate", "pgcode") != "42501":
+        return None
+    message = _field(err, "message_primary", "message") or str(err[-1]).split("\n")[0]
+    if error_code(exc) is None and not message.startswith("new row violates row-level security policy"):
+        return None
+    detail = _field(err, "message_detail", "detail") or ""
+    schema, table = _field(err, "schema_name"), _field(err, "table_name")
+    constraint = _field(err, "constraint_name") or ""
+    if message.startswith("new row violates row-level security policy"):
+        # Postgres's own words, not rowstile's: the row was allowed in, but may not be read back
+        # (INSERT ... RETURNING, or an ORM that reads the new row), which the select rule decides
+        import re
+        m = re.search(r'for table "([^"]+)"', message)
+        return Refused(f"{message}: the write was allowed, but the select rule doesn't let this user read the row "
+                       f"back (RETURNING); read it back only if the select rule allows it", m.group(1) if m else table,
+                       "select", [])
+    return Refused(message, f"{schema}.{table}" if schema and table else table,
+                   constraint[6:] if constraint.startswith("authz_") else None,
+                   detail.split("\n") if detail else [])
+
+
+def not_signed_in(exc: BaseException) -> bool:
+    return sqlstate(exc) == "28000"
+
+
+def check_problems(rows: Iterable[tuple[str, str]]) -> list[str]:
+    """The errors among authz.connection_check()'s rows (severity, problem)."""
+    return [problem for severity, problem in rows if severity == "error"]
+
+
+def _field_text(value: object) -> str:
+    """One field of a row as Postgres writes it, quoted: a comma, a quote or a space in it stays in its field."""
+    if value is None:
+        return ""
+    return '"' + str(value).replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def key_text(key: object) -> str | None:
+    """A row's key as the database compares it: one value, or a composite key as Postgres writes a row."""
+    if isinstance(key, (tuple, list)):
+        if len(key) != 1:
+            return "(" + ",".join(_field_text(v) for v in key) + ")"
+        key = key[0]
+    return None if key is None else str(key)
+
+
+def explain_rule_args(table: str, command: str, key: object) -> tuple[str, str, str | None]:
+    """authz.explain_rule's arguments for a row's key: one value, or several (a composite key's row text)."""
+    return table, command, key_text(key)
+
+
+def explain_rule_sql(table: LiteralString, command: LiteralString, key: LiteralString) -> LiteralString:
+    """SELECT authz.explain_rule($1, $2, $3, NULL) with the driver's placeholders for the table, the command and
+    the key (':t', '%(t)s', '$1'). The policy names tables with their schema; a table named without one (a
+    model that names no schema) is looked up on the search_path."""
+    found = ("SELECT n.nspname || '.' || c.relname FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n "
+             f"ON n.oid = c.relnamespace WHERE position('.' in {table}) = 0 "
+             f"AND c.oid = pg_catalog.to_regclass(pg_catalog.quote_ident({table}))")
+    return f"SELECT authz.explain_rule(coalesce(({found}), {table}), {command}, {key}, NULL)"
+
+
+def verdict(table: str, command: str, key: object, lines: Sequence[str] | None) -> NotFound | Refused:
+    """What an UPDATE or DELETE that changed nothing was: NotFound when the row isn't there for this user
+    (authz.explain_rule answered NULL), or when the rule allows the write (its first line says yes: the
+    statement matched nothing for another reason, such as a WHERE with more than the key); Refused, with
+    why, otherwise."""
+    key = key[0] if isinstance(key, (tuple, list)) and len(key) == 1 else key
+    if lines is None or (lines and lines[0].lstrip().startswith("yes")):
+        return NotFound(table, key)
+    return Refused(f"permission denied: may not {command} {table} {key}", table, command, lines)
+
+
+__all__ = [
+    "NOBODY",
+    "ConnectionProblem",
+    "Id",
+    "NotFound",
+    "NotSignedIn",
+    "Principal",
+    "Problem",
+    "Refused",
+    "Who",
+    "__version__",
+    "act_as_args",
+    "act_as_sql",
+    "acting_as",
+    "current",
+    "error_code",
+    "job",
+    "not_signed_in",
+    "refusal",
+    "sqlstate",
+    "verdict",
+]

rowstile/__main__.py

@@ -0,0 +1,3 @@
+from .command import main
+
+main()

rowstile/_command/authzlib/__init__.py

@@ -0,0 +1,33 @@
+"""authzlib: compile a .authz policy file into PostgreSQL (views, closure tables,
+triggers, row-level security policies and an API for app code)."""
+from .devtools import DevMixin
+from .output import OutputMixin
+from .parse import Loc, PolicyError, parse_policy
+from .testing import TestMixin
+
+
+class Compiler(TestMixin, DevMixin, OutputMixin):
+    """A policy compiled: each part of the output is one of its bases (OutputMixin assembles them)."""
+
+
+__version__ = "0.1.0-alpha.2"   # set with packaging/version.py (the packages copy it); authz.policy_versions records it on each apply
+
+
+def _build() -> str:
+    """The version apply records and trusts: a release's own, and for a build of the next one (X.Y.Z-dev)
+    the version with a hash of the compiler's sources, since two such builds may make different SQL."""
+    if not __version__.endswith("-dev"):
+        return __version__
+    import hashlib
+    import os
+    here, h = os.path.dirname(os.path.abspath(__file__)), hashlib.sha256()
+    for name in sorted(os.listdir(here)):
+        if name.endswith(".py"):
+            with open(os.path.join(here, name), "rb") as fh:
+                h.update(name.encode() + b"\0" + fh.read().replace(b"\r\n", b"\n") + b"\0")
+    return f"{__version__}+{h.hexdigest()[:12]}"
+
+
+BUILD = _build()
+
+__all__ = ["BUILD", "Compiler", "Loc", "PolicyError", "__version__", "parse_policy"]

rowstile/_command/authzlib/base.py

@@ -0,0 +1,185 @@
+"""SQL kept across re-applies: the tables people's data lives in, and migrations."""
+
+BASE_SQL = r"""-- Base objects (kept across re-applies)
+CREATE SCHEMA IF NOT EXISTS authz;
+REVOKE ALL ON SCHEMA authz FROM PUBLIC;
+
+-- 0.1.0 renamed authz.grants to authz.shares
+DO $mg$
+BEGIN
+  IF to_regclass('authz.grants') IS NOT NULL AND to_regclass('authz.shares') IS NULL THEN
+    ALTER TABLE authz.grants RENAME TO shares;
+    ALTER TABLE authz.shares RENAME CONSTRAINT grants_pkey TO shares_pkey;
+    ALTER INDEX IF EXISTS authz.grants_by_subject RENAME TO shares_by_subject;
+  END IF;
+END $mg$;
+
+-- Shares people create in the app, for relations marked 'shared' (and custom role assignments)
+CREATE TABLE IF NOT EXISTS authz.shares (
+  object_type      text        NOT NULL,
+  object_id        text        NOT NULL,
+  relation         text        NOT NULL,
+  subject_type     text        NOT NULL,
+  subject_id       text        NOT NULL,
+  subject_relation text        NOT NULL DEFAULT '',
+  expires_at       timestamptz,
+  created_by       text,
+  starts_at        timestamptz,
+  caveat           text,
+  caveat_args      jsonb,
+  created_at       timestamptz DEFAULT now(),
+  PRIMARY KEY (object_type, object_id, relation, subject_type, subject_id, subject_relation));
+-- earlier versions stored integer ids
+DO $m$
+BEGIN
+  IF (SELECT atttypid FROM pg_attribute WHERE attrelid = 'authz.shares'::regclass AND attname = 'object_id') <> 'text'::regtype THEN
+    ALTER TABLE authz.shares ALTER COLUMN object_id TYPE text USING object_id::text,
+                             ALTER COLUMN subject_id TYPE text USING subject_id::text,
+                             ALTER COLUMN created_by TYPE text USING created_by::text;
+  END IF;
+END $m$;
+ALTER TABLE authz.shares ADD COLUMN IF NOT EXISTS starts_at timestamptz;
+ALTER TABLE authz.shares ADD COLUMN IF NOT EXISTS caveat text;
+ALTER TABLE authz.shares ADD COLUMN IF NOT EXISTS caveat_args jsonb;
+ALTER TABLE authz.shares ADD COLUMN IF NOT EXISTS created_at timestamptz DEFAULT now();
+CREATE INDEX IF NOT EXISTS shares_by_subject
+  ON authz.shares (subject_type, subject_id, subject_relation, object_type, relation);
+REVOKE ALL ON authz.shares FROM PUBLIC;
+
+-- Custom roles: sets of permissions defined as data, assigned like shares ('role:<id>')
+CREATE TABLE IF NOT EXISTS authz.roles (
+  id          bigserial PRIMARY KEY,
+  owner_type  text NOT NULL,
+  owner_id    text NOT NULL,
+  object_type text NOT NULL,
+  name        text NOT NULL,
+  created_by  text,
+  created_at  timestamptz DEFAULT now(),
+  UNIQUE (owner_type, owner_id, object_type, name));
+CREATE TABLE IF NOT EXISTS authz.role_permissions (
+  role_id    bigint NOT NULL REFERENCES authz.roles ON DELETE CASCADE,
+  permission text   NOT NULL,
+  PRIMARY KEY (role_id, permission));
+REVOKE ALL ON authz.roles, authz.role_permissions FROM PUBLIC;
+
+-- API keys (only a hash of each is kept)
+CREATE TABLE IF NOT EXISTS authz.api_keys (
+  id           bigserial PRIMARY KEY,
+  user_id      text NOT NULL,
+  name         text NOT NULL,
+  prefix       text NOT NULL,
+  hash         text NOT NULL UNIQUE,
+  scopes       text NOT NULL DEFAULT '',
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  expires_at   timestamptz,
+  last_used_at timestamptz,
+  revoked_at   timestamptz);
+-- whose key: user_id is the principal's id, of this type
+ALTER TABLE authz.api_keys ADD COLUMN IF NOT EXISTS principal_type text NOT NULL DEFAULT 'user';
+-- Settings for the functions (jwt_secret, jwt_issuer, jwt_audience, jwt_user_claim, jwt_type_claim, ...)
+CREATE TABLE IF NOT EXISTS authz.settings (key text PRIMARY KEY, value text NOT NULL);
+-- The audit trail: every share, role, key, request and impersonation, and relationship changes
+CREATE TABLE IF NOT EXISTS authz.audit (
+  id               bigserial PRIMARY KEY,
+  at               timestamptz NOT NULL DEFAULT clock_timestamp(),
+  txid             bigint NOT NULL DEFAULT txid_current(),
+  db_role          text,
+  user_id          text,
+  acting_user      text,
+  action           text NOT NULL,
+  object_type      text,
+  object_id        text,
+  relation         text,
+  subject_type     text,
+  subject_id       text,
+  subject_relation text,
+  detail           jsonb,
+  reason           text);
+CREATE INDEX IF NOT EXISTS audit_by_object ON authz.audit (object_type, object_id, at);
+REVOKE ALL ON authz.api_keys, authz.settings, authz.audit FROM PUBLIC;
+
+-- Change feed: objects whose access may have changed, for caches, search indexes, file stores
+CREATE TABLE IF NOT EXISTS authz.changes (
+  pos         bigserial PRIMARY KEY,
+  at          timestamptz NOT NULL DEFAULT clock_timestamp(),
+  txid        bigint NOT NULL DEFAULT txid_current(),
+  object_type text NOT NULL,
+  object_ids  text[] NOT NULL,
+  cause       text NOT NULL);
+-- Access requests, approvals, and emergency access
+CREATE TABLE IF NOT EXISTS authz.requests (
+  id          bigserial PRIMARY KEY,
+  object_type text NOT NULL,
+  object_id   text NOT NULL,
+  relation    text NOT NULL,
+  requester   text NOT NULL,
+  reason      text,
+  duration    interval,
+  status      text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'denied', 'cancelled')),
+  decided_by  text,
+  decided_at  timestamptz,
+  note        text,
+  created_at  timestamptz NOT NULL DEFAULT now());
+-- Access reviews: a snapshot of the shares on an object, each kept or revoked by a reviewer
+CREATE TABLE IF NOT EXISTS authz.reviews (
+  id          bigserial PRIMARY KEY,
+  object_type text NOT NULL,
+  object_id   text NOT NULL,
+  created_by  text,
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  closes_at   timestamptz,
+  closed_at   timestamptz);
+CREATE TABLE IF NOT EXISTS authz.review_items (
+  review_id        bigint NOT NULL REFERENCES authz.reviews ON DELETE CASCADE,
+  item             int    NOT NULL,
+  relation         text   NOT NULL,
+  subject_type     text   NOT NULL,
+  subject_id       text   NOT NULL,
+  subject_relation text   NOT NULL,
+  expires_at       timestamptz,
+  keep             boolean,
+  decided_by       text,
+  decided_at       timestamptz,
+  PRIMARY KEY (review_id, item));
+-- Tables whose table-wide SELECT was replaced by column privileges because of masks
+CREATE TABLE IF NOT EXISTS authz.masked_tables (tbl text, role text, PRIMARY KEY (tbl, role));
+REVOKE ALL ON authz.changes, authz.requests, authz.reviews, authz.review_items, authz.masked_tables FROM PUBLIC;
+
+-- Every policy the rowstile command applied or removed, with the rowstile version that did it
+CREATE TABLE IF NOT EXISTS authz.policy_versions (
+  id      bigserial PRIMARY KEY,
+  at      timestamptz NOT NULL DEFAULT now(),
+  by_role text NOT NULL DEFAULT current_user,
+  action  text NOT NULL CHECK (action IN ('apply', 'remove')),
+  policy  text,
+  files   jsonb NOT NULL DEFAULT '{}',
+  version text NOT NULL);
+-- 0.1.0 kept it in the extension, as extension_version
+DO $pv$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_attribute WHERE attrelid = 'authz.policy_versions'::regclass
+             AND attname = 'extension_version' AND NOT attisdropped) THEN
+    ALTER TABLE authz.policy_versions RENAME COLUMN extension_version TO version;
+  END IF;
+END $pv$;
+-- what the migrations' lock file said about this policy (its hash), for the next migration to check
+ALTER TABLE authz.policy_versions ADD COLUMN IF NOT EXISTS lock text;
+REVOKE ALL ON authz.policy_versions FROM PUBLIC;
+
+-- Request context for conditions: SET LOCAL authz_ctx.mfa = 'yes', then {authz.ctx('mfa') = 'yes'}
+CREATE OR REPLACE FUNCTION authz.ctx(key text) RETURNS text LANGUAGE sql STABLE AS
+  $$ SELECT current_setting('authz_ctx.' || key, true) $$;
+
+-- Link tokens the request presents: SET LOCAL authz_ctx.links = '<token>,<token>'
+CREATE OR REPLACE FUNCTION authz.link_hashes() RETURNS text[] LANGUAGE sql STABLE AS $$
+  SELECT coalesce(array_agg(encode(sha256(convert_to(btrim(x), 'UTF8')), 'hex')), '{}')
+  FROM unnest(string_to_array(nullif(current_setting('authz_ctx.links', true), ''), ',')) x
+  WHERE btrim(x) <> '' $$;"""
+
+# Functions each apply recreates (dropped first, whatever their old signature).
+GENERATED_FUNCTIONS = ("act_as", "can", "list", "perms", "perms_of", "share", "unshare", "verify", "create_link", "principal",
+                       "create_role", "set_role_permissions", "delete_role", "roles_of", "who", "explain", "list_shares", "shares",
+                       "create_api_key", "list_api_keys", "revoke_api_key", "login_key", "login_jwt", "view_as",
+                       "sync_members", "changes_since", "trim_changes", "trim_audit", "request_access", "pending_requests", "decide_request",
+                       "cancel_request", "break_glass", "start_review", "review_items", "review_decide",
+                       "close_review", "check_invariants", "lint", "connection_check", "explain_rule", "who_among")