@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/051_authz_helpers.sql

@@ -0,0 +1,330 @@
+-- ============================================================================
+-- 051_authz_helpers.sql — the RLS helpers (§7) and effective role (§8).
+--
+-- All `STABLE SECURITY DEFINER SET search_path = ''`, meant to be called wrapped
+-- in `(select …)` so the planner caches them per statement (initPlan). They
+-- read the authz tables with the migration role's privileges (no recursion into
+-- RLS) and never raise: an RLS policy is not a place to throw, so junk resolves
+-- to "no access".
+--
+-- Also here: the RLS policies of the authz tables themselves (040 could not
+-- create them before the helpers existed).
+-- ============================================================================
+
+-- ── current_tenant_id() ─────────────────────────────────────────────────
+-- The tenant this request acts in. Same claim semantics as public.user_tenant_ids()
+-- (028): a top-level `tenant_id` JWT claim NARROWS and never widens — with a
+-- signed-in session it must match an active membership; a session-less signed
+-- token is scoped by the claim alone (only we can mint one). Without a claim,
+-- a user with exactly one active membership acts in it; a multi-tenant user
+-- without a claim acts in none (fail closed — the app sets the claim / active
+-- tenant). Only tenant_id (and, later, the active unit) live in the JWT:
+-- permissions and unit scope always come from tables (revocation is instant).
+CREATE OR REPLACE FUNCTION app.current_tenant_id()
+RETURNS uuid
+LANGUAGE plpgsql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_uid    uuid := auth.uid();
+  v_jwt    jsonb := coalesce(auth.jwt(), '{}'::jsonb);
+  v_raw    text;
+  v_tenant uuid;
+  v_n      integer;
+BEGIN
+  IF jsonb_exists(v_jwt, 'tenant_id') THEN
+    v_raw := v_jwt ->> 'tenant_id';
+    -- Presence expresses intent to be narrowed; an unparseable value is no tenant.
+    IF v_raw IS NULL OR v_raw !~* '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' THEN
+      RETURN NULL;
+    END IF;
+    v_tenant := v_raw::uuid;
+    IF v_uid IS NULL THEN
+      RETURN v_tenant;
+    END IF;
+    IF EXISTS (SELECT 1 FROM app.memberships m WHERE m.tenant_id = v_tenant AND m.user_id = v_uid AND m.active) THEN
+      RETURN v_tenant;
+    END IF;
+    RETURN NULL;
+  END IF;
+
+  IF v_uid IS NULL THEN
+    RETURN NULL;
+  END IF;
+  SELECT count(*), (array_agg(m.tenant_id))[1] INTO v_n, v_tenant
+    FROM app.memberships m WHERE m.user_id = v_uid AND m.active;
+  IF v_n = 1 THEN
+    RETURN v_tenant;
+  END IF;
+  RETURN NULL;
+END $$;
+
+-- ── unit_scoping_on() — the per-account switch main already had ─────────
+-- `039_unit_tree` gave every tenant a `unit_scoping_enabled`, off by default,
+-- and that is a better design than the always-on this chain originally shipped:
+-- a network turns it on when it is ready, and turning it off gives everything
+-- back without moving a row. The policy template honours that switch instead of
+-- replacing it.
+--
+-- Switch off ⇒ every unit of the account is yours, which is exactly the
+-- behaviour from before units existed.
+CREATE OR REPLACE FUNCTION app.unit_scoping_on()
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT coalesce((SELECT t.unit_scoping_enabled FROM public.tenants t
+                    WHERE t.id = app.current_tenant_id()), false);
+$$;
+REVOKE ALL ON FUNCTION app.unit_scoping_on() FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.unit_scoping_on() TO authenticated, service_role;
+
+-- ── has_unit(unit) ──────────────────────────────────────────────────────
+-- O(1) on the share table's PK. A NULL unit is a tenant-wide resource: the
+-- template checks `unit_id IS NULL OR has_unit(unit_id)` itself.
+CREATE OR REPLACE FUNCTION app.has_unit(p_unit uuid)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT p_unit IS NOT NULL
+     AND CASE WHEN app.unit_scoping_on()
+              THEN EXISTS (SELECT 1 FROM app.user_unit_access a
+                            WHERE a.tenant_id = app.current_tenant_id()
+                              AND a.user_id = auth.uid()
+                              AND a.unit_id = p_unit)
+              -- switch off: every unit of the account is yours
+              ELSE EXISTS (SELECT 1 FROM app.units u
+                            WHERE u.id = p_unit AND u.tenant_id = app.current_tenant_id())
+         END;
+$$;
+
+-- ── effective_role_id(tenant, user, unit) ───────────────────────────────
+-- §8: membership_units.role_override_id when present for (user, unit), else
+-- memberships.role_id. Inactive membership ⇒ no role.
+CREATE OR REPLACE FUNCTION app.effective_role_id(p_tenant uuid, p_user uuid, p_unit uuid DEFAULT NULL)
+RETURNS uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT coalesce(
+    (SELECT mu.role_override_id
+       FROM app.membership_units mu
+      WHERE p_unit IS NOT NULL
+        AND mu.tenant_id = p_tenant AND mu.user_id = p_user AND mu.unit_id = p_unit
+        AND mu.role_override_id IS NOT NULL),
+    (SELECT m.role_id
+       FROM app.memberships m
+      WHERE m.tenant_id = p_tenant AND m.user_id = p_user AND m.active)
+  );
+$$;
+
+-- ── has_permission(perm[, unit]) ────────────────────────────────────────
+-- Resolves against the effective role for the row's unit when one is given,
+-- else the base role. `{feature}.manage` implies every `{feature}.{action}`
+-- (the SDK's resolveAccess semantics, mirrored — same source, no drift). No
+-- owner bypass: an owner is a role whose permission set is the whole catalog.
+CREATE OR REPLACE FUNCTION app.has_permission(p_perm text, p_unit uuid DEFAULT NULL)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+      FROM app.role_permissions rp
+     WHERE rp.tenant_id = app.current_tenant_id()
+       AND rp.role_id = app.effective_role_id(app.current_tenant_id(), auth.uid(), p_unit)
+       AND rp.permission IN (p_perm, regexp_replace(p_perm, '\.[^.]+$', '.manage'))
+  );
+$$;
+
+-- Does the user hold the permission in ANY of their roles (base or any unit
+-- override)? For UI affordances and tenant-wide actions, not for row scope.
+CREATE OR REPLACE FUNCTION app.has_permission_anywhere(p_perm text)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+      FROM app.role_permissions rp
+     WHERE rp.tenant_id = app.current_tenant_id()
+       AND rp.permission IN (p_perm, regexp_replace(p_perm, '\.[^.]+$', '.manage'))
+       AND rp.role_id IN (
+         SELECT m.role_id FROM app.memberships m
+          WHERE m.tenant_id = rp.tenant_id AND m.user_id = auth.uid() AND m.active
+         UNION
+         SELECT mu.role_override_id FROM app.membership_units mu
+          WHERE mu.tenant_id = rp.tenant_id AND mu.user_id = auth.uid() AND mu.role_override_id IS NOT NULL
+       )
+  );
+$$;
+
+-- ── has_grant(type, id, relations[]) ────────────────────────────────────
+-- resource_grants where the subject is me, one of my units, or one of my roles.
+CREATE OR REPLACE FUNCTION app.has_grant(p_type text, p_id uuid, p_relations text[])
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT EXISTS (
+    SELECT 1
+      FROM app.resource_grants g
+     WHERE g.tenant_id = app.current_tenant_id()
+       AND g.resource_type = p_type
+       AND g.resource_id = p_id
+       AND g.relation = ANY (p_relations)
+       AND (
+            (g.subject_type = 'user' AND g.subject_id = auth.uid())
+         OR (g.subject_type = 'unit' AND EXISTS (
+               SELECT 1 FROM app.user_unit_access a
+                WHERE a.tenant_id = g.tenant_id AND a.user_id = auth.uid() AND a.unit_id = g.subject_id))
+         OR (g.subject_type = 'role' AND g.subject_id IN (
+               SELECT m.role_id FROM app.memberships m
+                WHERE m.tenant_id = g.tenant_id AND m.user_id = auth.uid() AND m.active
+               UNION
+               SELECT mu.role_override_id FROM app.membership_units mu
+                WHERE mu.tenant_id = g.tenant_id AND mu.user_id = auth.uid() AND mu.role_override_id IS NOT NULL))
+       )
+  );
+$$;
+
+-- "No available_in tuples ⇒ available everywhere" (§9.1): a tenant-wide
+-- resource is visible in a unit unless the resource has been restricted, in
+-- which case the unit must be one of the granted ones.
+CREATE OR REPLACE FUNCTION app.available_in_my_units(p_type text, p_id uuid)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT NOT EXISTS (
+           SELECT 1 FROM app.resource_grants g
+            WHERE g.tenant_id = app.current_tenant_id()
+              AND g.resource_type = p_type AND g.resource_id = p_id AND g.relation = 'available_in')
+      OR app.has_grant(p_type, p_id, ARRAY['available_in']);
+$$;
+
+-- ── is_member(tenant) ───────────────────────────────────────────────────
+-- Plain active membership, no permission — what the authz tables' own read
+-- policies need ("members see their tenant's units and roles").
+CREATE OR REPLACE FUNCTION app.is_member(p_tenant uuid)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  SELECT EXISTS (
+    SELECT 1 FROM app.memberships m
+     WHERE m.tenant_id = p_tenant AND m.user_id = auth.uid() AND m.active
+  );
+$$;
+
+REVOKE ALL ON FUNCTION app.current_tenant_id() FROM public;
+REVOKE ALL ON FUNCTION app.has_unit(uuid) FROM public;
+REVOKE ALL ON FUNCTION app.effective_role_id(uuid, uuid, uuid) FROM public;
+REVOKE ALL ON FUNCTION app.has_permission(text, uuid) FROM public;
+REVOKE ALL ON FUNCTION app.has_permission_anywhere(text) FROM public;
+REVOKE ALL ON FUNCTION app.has_grant(text, uuid, text[]) FROM public;
+REVOKE ALL ON FUNCTION app.available_in_my_units(text, uuid) FROM public;
+REVOKE ALL ON FUNCTION app.is_member(uuid) FROM public;
+GRANT EXECUTE ON FUNCTION app.current_tenant_id() TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION app.has_unit(uuid) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION app.effective_role_id(uuid, uuid, uuid) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION app.has_permission(text, uuid) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION app.has_permission_anywhere(text) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION app.has_grant(text, uuid, text[]) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION app.available_in_my_units(text, uuid) TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION app.is_member(uuid) TO authenticated, service_role;
+
+-- ═══════════════════════ RLS on the authz tables ══════════════════════════
+-- Reads: any active member of the tenant sees the tenant's units, roles and
+-- role permissions (the UI needs them to render); memberships and unit rows are
+-- visible to the member herself and to holders of members.read; the share table
+-- to the user herself and to members.read; grants to members of the tenant.
+-- Writes: platform permission keys — no owner/admin literal anywhere.
+
+-- units
+DROP POLICY IF EXISTS units_select ON app.units;
+CREATE POLICY units_select ON app.units FOR SELECT TO authenticated
+  USING ((select app.is_member(tenant_id)));
+DROP POLICY IF EXISTS units_insert ON app.units;
+CREATE POLICY units_insert ON app.units FOR INSERT TO authenticated
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('units.manage')));
+DROP POLICY IF EXISTS units_update ON app.units;
+CREATE POLICY units_update ON app.units FOR UPDATE TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('units.manage')))
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('units.manage')));
+DROP POLICY IF EXISTS units_delete ON app.units;
+CREATE POLICY units_delete ON app.units FOR DELETE TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('units.manage')));
+
+-- roles
+DROP POLICY IF EXISTS roles_select ON app.roles;
+CREATE POLICY roles_select ON app.roles FOR SELECT TO authenticated
+  USING ((select app.is_member(tenant_id)));
+DROP POLICY IF EXISTS roles_insert ON app.roles;
+CREATE POLICY roles_insert ON app.roles FOR INSERT TO authenticated
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('roles.manage')) AND NOT is_system);
+DROP POLICY IF EXISTS roles_update ON app.roles;
+CREATE POLICY roles_update ON app.roles FOR UPDATE TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('roles.manage')))
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('roles.manage')));
+DROP POLICY IF EXISTS roles_delete ON app.roles;
+CREATE POLICY roles_delete ON app.roles FOR DELETE TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('roles.manage')) AND NOT is_system);
+
+-- role_permissions
+DROP POLICY IF EXISTS role_permissions_select ON app.role_permissions;
+CREATE POLICY role_permissions_select ON app.role_permissions FOR SELECT TO authenticated
+  USING ((select app.is_member(tenant_id)));
+DROP POLICY IF EXISTS role_permissions_write ON app.role_permissions;
+CREATE POLICY role_permissions_write ON app.role_permissions FOR ALL TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('roles.manage')))
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('roles.manage')));
+
+-- memberships: yourself, or members.read; writes need members.manage and can
+-- never be a self-insert (the P0 of the old model) — creation of the first
+-- member is the create_tenant RPC's job (#134).
+DROP POLICY IF EXISTS memberships_select ON app.memberships;
+CREATE POLICY memberships_select ON app.memberships FOR SELECT TO authenticated
+  USING (user_id = (select auth.uid()) OR (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.read'))));
+DROP POLICY IF EXISTS memberships_insert ON app.memberships;
+CREATE POLICY memberships_insert ON app.memberships FOR INSERT TO authenticated
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')) AND user_id <> (select auth.uid()));
+DROP POLICY IF EXISTS memberships_update ON app.memberships;
+CREATE POLICY memberships_update ON app.memberships FOR UPDATE TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')))
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')));
+DROP POLICY IF EXISTS memberships_delete ON app.memberships;
+CREATE POLICY memberships_delete ON app.memberships FOR DELETE TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')) AND user_id <> (select auth.uid()));
+
+-- membership_units
+DROP POLICY IF EXISTS membership_units_select ON app.membership_units;
+CREATE POLICY membership_units_select ON app.membership_units FOR SELECT TO authenticated
+  USING (user_id = (select auth.uid()) OR (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.read'))));
+DROP POLICY IF EXISTS membership_units_write ON app.membership_units;
+CREATE POLICY membership_units_write ON app.membership_units FOR ALL TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')))
+  WITH CHECK (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.manage')));
+
+-- user_unit_access: read-only surface (the share table)
+DROP POLICY IF EXISTS user_unit_access_select ON app.user_unit_access;
+CREATE POLICY user_unit_access_select ON app.user_unit_access FOR SELECT TO authenticated
+  USING (user_id = (select auth.uid()) OR (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.read'))));
+
+-- resource_grants: members read; writing a tuple needs the platform key
+-- authz.grants.manage or the resource's own '{plugin}.manage' (§12.9 default).
+DROP POLICY IF EXISTS resource_grants_select ON app.resource_grants;
+CREATE POLICY resource_grants_select ON app.resource_grants FOR SELECT TO authenticated
+  USING ((select app.is_member(tenant_id)));
+DROP POLICY IF EXISTS resource_grants_write ON app.resource_grants;
+CREATE POLICY resource_grants_write ON app.resource_grants FOR ALL TO authenticated
+  USING (tenant_id = (select app.current_tenant_id())
+         AND ((select app.has_permission('authz.grants.manage')) OR (select app.has_permission(split_part(resource_type, '.', 1) || '.manage'))))
+  WITH CHECK (tenant_id = (select app.current_tenant_id())
+         AND ((select app.has_permission('authz.grants.manage')) OR (select app.has_permission(split_part(resource_type, '.', 1) || '.manage'))));
+
+-- reconciliation log: readable by members.read of the tenant
+DROP POLICY IF EXISTS authz_reconciliation_log_select ON app.authz_reconciliation_log;
+CREATE POLICY authz_reconciliation_log_select ON app.authz_reconciliation_log FOR SELECT TO authenticated
+  USING (tenant_id = (select app.current_tenant_id()) AND (select app.has_permission('members.read')));

package/migrations/052_authz_fanout.sql

@@ -0,0 +1,253 @@
+-- ============================================================================
+-- 052_authz_fanout.sql — user_unit_access maintenance (§5) + reconciliation (§6).
+--
+-- The share table is DERIVED from memberships × membership_units × units. Rather
+-- than hand-writing an add/remove per event and getting one of the four fan-out
+-- cases wrong, every trigger rebuilds the affected users' rows from the source
+-- of truth (app.compute_user_unit_access) inside the same transaction. The
+-- reconciliation job is the same rebuild for a whole tenant, with a diff-log.
+--
+-- Decisions taken as the spec's defaults (grill items 1, 2 and 8): access at a
+-- parent unit PROPAGATES to its subtree; a deactivated unit's rows are REMOVED
+-- (reconciliation restores them on reactivation); `via` provenance is kept.
+--
+-- The four cases:
+--   F1 membership_units insert/delete/update  → rebuild that user
+--   F2 memberships insert/update(all_units, active, role)/delete → rebuild that user
+--   F3 units insert (active)                  → rebuild every all_units member and
+--                                               every user with explicit access to
+--                                               an ancestor of the new unit
+--   F4 units.parent_unit_id / active change   → rebuild the tenant's affected users
+--                                               (all_units + anyone with explicit
+--                                               access anywhere in the tenant)
+-- ============================================================================
+
+-- What (unit, via) a user should have. Precedence when several paths reach the
+-- same unit: all_units > explicit > subtree.
+CREATE OR REPLACE FUNCTION app.compute_user_unit_access(p_tenant uuid, p_user uuid)
+RETURNS TABLE (unit_id uuid, via text)
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = ''
+AS $$
+  WITH m AS (
+    SELECT all_units FROM app.memberships
+     WHERE tenant_id = p_tenant AND user_id = p_user AND active
+  ),
+  explicit AS (
+    SELECT mu.unit_id
+      FROM app.membership_units mu
+      JOIN app.units u ON u.tenant_id = mu.tenant_id AND u.id = mu.unit_id AND u.active
+     WHERE mu.tenant_id = p_tenant AND mu.user_id = p_user
+       AND EXISTS (SELECT 1 FROM m)
+  ),
+  subtree AS (
+    -- descendants of every explicit unit (parent access ⇒ subtree access)
+    WITH RECURSIVE d AS (
+      SELECT u.id, u.parent_unit_id, 0 AS depth
+        FROM app.units u
+       WHERE u.tenant_id = p_tenant AND u.id IN (SELECT unit_id FROM explicit)
+      UNION ALL
+      SELECT c.id, c.parent_unit_id, d.depth + 1
+        FROM app.units c
+        JOIN d ON c.parent_unit_id = d.id
+       WHERE c.tenant_id = p_tenant AND c.active AND d.depth < 32
+    )
+    SELECT DISTINCT id AS unit_id FROM d WHERE depth > 0
+  ),
+  everything AS (
+    SELECT u.id AS unit_id FROM app.units u
+     WHERE u.tenant_id = p_tenant AND u.active
+       AND EXISTS (SELECT 1 FROM m WHERE all_units)
+  ),
+  ranked AS (
+    SELECT unit_id, 'all_units'::text AS via, 1 AS prio FROM everything
+    UNION ALL
+    SELECT unit_id, 'explicit', 2 FROM explicit
+    UNION ALL
+    SELECT unit_id, 'subtree', 3 FROM subtree
+  )
+  SELECT DISTINCT ON (unit_id) unit_id, via
+    FROM ranked
+   ORDER BY unit_id, prio;
+$$;
+
+-- Rebuild one user's rows in place. Returns (added, removed). Two statements on
+-- purpose: a row whose `via` changed is deleted by the first and re-inserted by
+-- the second — a single data-modifying CTE cannot delete and upsert the same
+-- row in one command.
+CREATE OR REPLACE FUNCTION app.refresh_user_unit_access(p_tenant uuid, p_user uuid, OUT added integer, OUT removed integer)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+BEGIN
+  WITH desired AS (
+    SELECT unit_id, via FROM app.compute_user_unit_access(p_tenant, p_user)
+  ), del AS (
+    DELETE FROM app.user_unit_access a
+     WHERE a.tenant_id = p_tenant AND a.user_id = p_user
+       AND NOT EXISTS (SELECT 1 FROM desired d WHERE d.unit_id = a.unit_id AND d.via = a.via)
+    RETURNING 1
+  )
+  SELECT count(*) INTO removed FROM del;
+
+  WITH ins AS (
+    INSERT INTO app.user_unit_access (tenant_id, user_id, unit_id, via)
+    SELECT p_tenant, p_user, d.unit_id, d.via FROM app.compute_user_unit_access(p_tenant, p_user) d
+    ON CONFLICT (tenant_id, user_id, unit_id) DO NOTHING
+    RETURNING 1
+  )
+  SELECT count(*) INTO added FROM ins;
+END $$;
+
+-- The reconciliation job (§6): rebuild a whole tenant, log the diff, return it.
+-- Runs after every authz migration (source='migration'), nightly per tenant
+-- (source='scheduled'), on demand (source='manual'). A non-zero diff outside a
+-- migration is an incident: v_authz_reconciliation_alerts (043) surfaces it.
+CREATE OR REPLACE FUNCTION app.recompute_user_unit_access(p_tenant uuid, p_source text DEFAULT 'manual')
+RETURNS TABLE (added integer, removed integer)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE
+  v_added   integer := 0;
+  v_removed integer := 0;
+  v_details jsonb := '[]'::jsonb;
+  r record;
+BEGIN
+  IF p_source NOT IN ('migration', 'scheduled', 'manual', 'test') THEN
+    RAISE EXCEPTION 'recompute_user_unit_access: unknown source %', p_source;
+  END IF;
+
+  -- Rows for users who no longer hold a membership at all cannot exist (FK
+  -- cascade); rows for members are rebuilt one by one.
+  FOR r IN SELECT m.user_id FROM app.memberships m WHERE m.tenant_id = p_tenant LOOP
+    DECLARE a integer; d integer;
+    BEGIN
+      SELECT ra.added, ra.removed INTO a, d FROM app.refresh_user_unit_access(p_tenant, r.user_id) ra;
+      IF a <> 0 OR d <> 0 THEN
+        v_details := v_details || jsonb_build_object('user_id', r.user_id, 'added', a, 'removed', d);
+      END IF;
+      v_added := v_added + a;
+      v_removed := v_removed + d;
+    END;
+  END LOOP;
+
+  INSERT INTO app.authz_reconciliation_log (tenant_id, source, added, removed, details)
+  VALUES (p_tenant, p_source, v_added, v_removed, v_details);
+
+  added := v_added; removed := v_removed;
+  RETURN NEXT;
+END $$;
+
+-- Every tenant (used by migrations touching authz tables, and by the bench).
+CREATE OR REPLACE FUNCTION app.recompute_all_user_unit_access(p_source text DEFAULT 'migration')
+RETURNS TABLE (tenant_id uuid, added integer, removed integer)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE r record; a integer; d integer;
+BEGIN
+  FOR r IN SELECT t.id FROM public.tenants t LOOP
+    SELECT x.added, x.removed INTO a, d FROM app.recompute_user_unit_access(r.id, p_source) x;
+    tenant_id := r.id; added := a; removed := d;
+    RETURN NEXT;
+  END LOOP;
+END $$;
+
+REVOKE ALL ON FUNCTION app.compute_user_unit_access(uuid, uuid) FROM public;
+REVOKE ALL ON FUNCTION app.refresh_user_unit_access(uuid, uuid) FROM public;
+REVOKE ALL ON FUNCTION app.recompute_user_unit_access(uuid, text) FROM public;
+REVOKE ALL ON FUNCTION app.recompute_all_user_unit_access(text) FROM public;
+GRANT EXECUTE ON FUNCTION app.recompute_user_unit_access(uuid, text) TO service_role;
+GRANT EXECUTE ON FUNCTION app.recompute_all_user_unit_access(text) TO service_role;
+-- An admin may reconcile her own tenant on demand (the function still needs the
+-- membership: it is gated inside the wrapper below).
+CREATE OR REPLACE FUNCTION public.authz_reconcile_my_tenant()
+RETURNS TABLE (added integer, removed integer)
+LANGUAGE plpgsql SECURITY DEFINER
+SET search_path = ''
+AS $$
+DECLARE v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL OR NOT app.has_permission('members.manage') THEN
+    RAISE EXCEPTION 'authz_reconcile_my_tenant: not allowed' USING ERRCODE = '42501';
+  END IF;
+  RETURN QUERY SELECT x.added, x.removed FROM app.recompute_user_unit_access(v_tenant, 'manual') x;
+END $$;
+REVOKE ALL ON FUNCTION public.authz_reconcile_my_tenant() FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.authz_reconcile_my_tenant() TO authenticated, service_role;
+
+-- ═════════════════════════════ triggers ═══════════════════════════════════
+
+-- F1 — membership_units
+CREATE OR REPLACE FUNCTION app.trg_membership_units_fanout()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF TG_OP IN ('INSERT', 'UPDATE') THEN
+    PERFORM app.refresh_user_unit_access(NEW.tenant_id, NEW.user_id);
+  END IF;
+  IF TG_OP IN ('DELETE', 'UPDATE') AND (TG_OP = 'DELETE' OR OLD.user_id <> NEW.user_id OR OLD.tenant_id <> NEW.tenant_id) THEN
+    PERFORM app.refresh_user_unit_access(OLD.tenant_id, OLD.user_id);
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS membership_units_fanout ON app.membership_units;
+CREATE TRIGGER membership_units_fanout
+  AFTER INSERT OR UPDATE OR DELETE ON app.membership_units
+  FOR EACH ROW EXECUTE FUNCTION app.trg_membership_units_fanout();
+
+-- F2 — memberships (insert / all_units toggle / activate / deactivate / delete)
+CREATE OR REPLACE FUNCTION app.trg_memberships_fanout()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    -- rows go with the FK cascade; nothing to rebuild
+    RETURN NULL;
+  END IF;
+  IF TG_OP = 'INSERT' OR OLD.all_units IS DISTINCT FROM NEW.all_units OR OLD.active IS DISTINCT FROM NEW.active THEN
+    PERFORM app.refresh_user_unit_access(NEW.tenant_id, NEW.user_id);
+  END IF;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS memberships_fanout ON app.memberships;
+CREATE TRIGGER memberships_fanout
+  AFTER INSERT OR UPDATE OR DELETE ON app.memberships
+  FOR EACH ROW EXECUTE FUNCTION app.trg_memberships_fanout();
+
+-- F3 + F4 — units. On insert of an active unit: every all_units member gets it,
+-- and every user with explicit access to an ancestor gets it via subtree — the
+-- classic forgotten case (franchisor opens a branch). On a parent move or an
+-- active flip: rebuild every user whose scope can depend on the tree.
+CREATE OR REPLACE FUNCTION app.trg_units_fanout()
+RETURNS trigger LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE r record;
+BEGIN
+  IF TG_OP = 'INSERT' AND NOT NEW.active THEN
+    RETURN NULL;
+  END IF;
+  IF TG_OP = 'UPDATE'
+     AND OLD.parent_unit_id IS NOT DISTINCT FROM NEW.parent_unit_id
+     AND OLD.active IS NOT DISTINCT FROM NEW.active THEN
+    RETURN NULL; -- a rename does not change scope
+  END IF;
+  -- Affected: all_units members + anyone holding explicit unit access in the
+  -- tenant (their subtree may have gained/lost this unit). Members with no
+  -- unit access at all cannot be affected.
+  FOR r IN
+    SELECT DISTINCT m.user_id
+      FROM app.memberships m
+     WHERE m.tenant_id = NEW.tenant_id
+       AND (m.all_units OR EXISTS (SELECT 1 FROM app.membership_units mu WHERE mu.tenant_id = m.tenant_id AND mu.user_id = m.user_id))
+  LOOP
+    PERFORM app.refresh_user_unit_access(NEW.tenant_id, r.user_id);
+  END LOOP;
+  RETURN NULL;
+END $$;
+DROP TRIGGER IF EXISTS units_fanout ON app.units;
+CREATE TRIGGER units_fanout
+  AFTER INSERT OR UPDATE ON app.units
+  FOR EACH ROW EXECUTE FUNCTION app.trg_units_fanout();
+
+-- Bring every tenant's share table in line with this migration (a no-op on a
+-- fresh database; on a converted one it is the first reconciliation).
+SELECT app.recompute_all_user_unit_access('migration');