@fayz-ai/db 0.11.0 → 0.12.0

package/migrations/040_resource_grants.sql

@@ -0,0 +1,474 @@
+-- ============================================================================
+-- 040_resource_grants.sql — the exception to the default, written down.
+--
+-- Unit scoping (039) answers "which units do I reach". It cannot answer the two
+-- questions the product actually asks:
+--
+--   • "Botox is sold in 2 of our 15 units."
+--   • "This patient record is the psychologist's, not the reception's — unless
+--      she shares it with the other psychologists."
+--
+-- Both are the SAME shape: a record, a recipient, a level. That is one table,
+-- `resource_grants`, modelled on the `__Share` rows Salesforce has used for
+-- twenty years. The alternative — a `product_units` join here, a
+-- `document_shares` there — is three mechanisms, three predicates and three
+-- screens to debug.
+--
+-- WHAT DECIDES WHEN NO GRANT EXISTS is `resource_visibility_defaults`: per
+-- tenant, per record type, one of
+--
+--   tenant  everyone in the org        (today's behaviour, the default)
+--   unit    only the record's unit
+--   owner   only whoever owns it       (the patient-record case)
+--
+-- Salesforce calls this the org-wide default, and having it is the difference
+-- between "sharing" and "a checkbox on every form".
+--
+-- `scoped_resources` is the registry both of them key off — one row per table
+-- that participates, naming its unit and owner columns. It exists so that 041
+-- (which adds the columns) and 042 (which emits the policies) and the settings
+-- screen all read ONE list instead of three copies of an array that will drift.
+--
+-- WHY THESE POLICIES ARE INLINE, AND WHY THE STRICT ONES ARE RESTRICTIVE.
+-- 002's DO block sweeps every public table carrying a `tenant_id` and gives it
+-- the canonical policy. On a fresh pool it runs long before this file, so the
+-- tables here would be born with RLS enabled and no policy at all — hence the
+-- inline ones.
+--
+-- The sharper half: 002 is re-applied whenever its checksum moves or a pool is
+-- rebuilt, and on THAT pass it does discover these tables and adds a PERMISSIVE
+-- `tenant_isolation_insert` to each. Permissive policies OR together, so that
+-- one policy would reopen every gate below — any member of the tenant could
+-- write themselves a grant. The bench caught exactly this on its replay pass.
+--
+-- So the rule for every table in this file: a permissive policy carries the
+-- tenant clause (which makes 002's sweep a no-op instead of a surprise), and
+-- the ACTUAL rules are RESTRICTIVE. A restrictive policy cannot be widened by
+-- anything added later, which is the only property worth having here.
+--
+-- Idempotent: safe to re-run, no-ops when already applied.
+-- ============================================================================
+
+-- ── The registry ────────────────────────────────────────────────────────────
+-- Platform-owned, not tenant-owned: which tables carry a unit and an owner is a
+-- property of the schema, and a tenant cannot opt a table in or out.
+CREATE TABLE IF NOT EXISTS public.scoped_resources (
+  resource_table      text PRIMARY KEY,
+  -- Named rather than assumed: `orders` and `schedules` have carried
+  -- `location_id` since 004_archetypes and that column IS the unit. Adding a
+  -- second one to the busiest tables in the product to satisfy a naming
+  -- preference would be the wrong trade.
+  unit_column         text NOT NULL DEFAULT 'unit_id',
+  owner_column        text NOT NULL DEFAULT 'owner_id',
+  -- A ledger is unit-scoped but not shareable: you do not hand someone a single
+  -- financial movement.
+  shareable           boolean NOT NULL DEFAULT true,
+  -- The factory default a tenant starts from; per-tenant overrides live in
+  -- resource_visibility_defaults.
+  default_visibility  text NOT NULL DEFAULT 'tenant'
+    CHECK (default_visibility IN ('tenant', 'unit', 'owner')),
+  label               text
+);
+
+ALTER TABLE public.scoped_resources ENABLE ROW LEVEL SECURITY;
+
+-- Readable by anyone signed in (the visibility settings screen lists it),
+-- writable by nobody but the platform. There is deliberately no manage policy:
+-- a row here is created by a migration, because adding a table to the security
+-- model is a schema change.
+DROP POLICY IF EXISTS "scoped_resources_select" ON public.scoped_resources;
+CREATE POLICY "scoped_resources_select" ON public.scoped_resources FOR SELECT TO authenticated
+  USING (true);
+
+GRANT SELECT ON public.scoped_resources TO authenticated;
+GRANT ALL ON public.scoped_resources TO service_role;
+
+-- ── The per-tenant default ──────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.resource_visibility_defaults (
+  tenant_id          uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  resource_table     text NOT NULL REFERENCES public.scoped_resources(resource_table) ON DELETE CASCADE,
+  default_visibility text NOT NULL CHECK (default_visibility IN ('tenant', 'unit', 'owner')),
+  updated_by         uuid,
+  updated_at         timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, resource_table)
+);
+
+ALTER TABLE public.resource_visibility_defaults ENABLE ROW LEVEL SECURITY;
+
+-- Everyone in the tenant reads it — a screen has to be able to say "clientes:
+-- toda a organização" to the person looking at it. Only an admin changes it:
+-- this is the setting that decides who sees what.
+DROP POLICY IF EXISTS "rvd_select" ON public.resource_visibility_defaults;
+CREATE POLICY "rvd_select" ON public.resource_visibility_defaults FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS "rvd_manage" ON public.resource_visibility_defaults;
+CREATE POLICY "rvd_manage" ON public.resource_visibility_defaults FOR ALL TO authenticated
+  USING (tenant_id IN (SELECT public.user_admin_tenant_ids()))
+  WITH CHECK (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.resource_visibility_defaults TO authenticated;
+GRANT ALL ON public.resource_visibility_defaults TO service_role;
+
+-- ── Teams ───────────────────────────────────────────────────────────────────
+-- A named recipient, so "os psicólogos" is written once instead of re-picking
+-- five people on every record. A team has NO permissions of its own — it is a
+-- grant target and nothing else, which is what keeps it from quietly becoming a
+-- second, competing role system.
+CREATE TABLE IF NOT EXISTS public.teams (
+  id         uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id  uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  name       text NOT NULL,
+  color      text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (tenant_id, name)
+);
+
+CREATE TABLE IF NOT EXISTS public.team_members (
+  id        uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  team_id   uuid NOT NULL REFERENCES public.teams(id) ON DELETE CASCADE,
+  tenant_id uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  -- CASCADE and not SET NULL: a membership row whose person no longer exists is
+  -- a grant to nobody that still widens every predicate reading this table.
+  user_id   uuid NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE,
+  UNIQUE (team_id, user_id)
+);
+
+CREATE INDEX IF NOT EXISTS team_members_user_idx ON public.team_members (user_id, team_id);
+
+ALTER TABLE public.teams ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.team_members ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS "teams_select" ON public.teams;
+CREATE POLICY "teams_select" ON public.teams FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS "teams_manage" ON public.teams;
+CREATE POLICY "teams_manage" ON public.teams FOR ALL TO authenticated
+  USING (tenant_id IN (SELECT public.user_admin_tenant_ids()))
+  WITH CHECK (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+DROP POLICY IF EXISTS "team_members_select" ON public.team_members;
+CREATE POLICY "team_members_select" ON public.team_members FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS "team_members_manage" ON public.team_members;
+CREATE POLICY "team_members_manage" ON public.team_members FOR ALL TO authenticated
+  USING (tenant_id IN (SELECT public.user_admin_tenant_ids()))
+  WITH CHECK (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.teams, public.team_members TO authenticated;
+GRANT ALL ON public.teams, public.team_members TO service_role;
+
+-- ── The grants ──────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS public.resource_grants (
+  id             uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id      uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  resource_table text NOT NULL REFERENCES public.scoped_resources(resource_table) ON DELETE CASCADE,
+  resource_id    uuid NOT NULL,
+  -- uuid and not text, and no 'role' member: a role grant would duplicate what
+  -- the per-unit role in 039 and the 'tenant' default already express, and a
+  -- text key would cost a cast on every index probe.
+  grantee_type   text NOT NULL CHECK (grantee_type IN ('user', 'team', 'unit')),
+  grantee_id     uuid NOT NULL,
+  access         text NOT NULL DEFAULT 'read' CHECK (access IN ('read', 'write', 'full')),
+  -- 'manual' (someone clicked Compartilhar) vs 'catalog' (this product is sold
+  -- in these units). Same row, different story to tell on screen.
+  reason         text NOT NULL DEFAULT 'manual',
+  -- SET NULL and not CASCADE: who handed the access out is history, and the
+  -- access itself must not disappear because that person left the company.
+  granted_by     uuid REFERENCES auth.users(id) ON DELETE SET NULL,
+  created_at     timestamptz NOT NULL DEFAULT now()
+);
+
+-- The hot path: "what has been granted to me / to my units / to my teams".
+CREATE INDEX IF NOT EXISTS resource_grants_grantee_idx
+  ON public.resource_grants (grantee_type, grantee_id, resource_table, resource_id);
+
+-- The panel's direction ("who can see this record?") and the dedupe rule, in
+-- one object. One grant per (record, recipient) — re-sharing changes the level,
+-- it does not stack.
+CREATE UNIQUE INDEX IF NOT EXISTS resource_grants_record_uniq
+  ON public.resource_grants (resource_table, resource_id, grantee_type, grantee_id);
+
+-- Answers restricted_record_ids(): which rows of this table carry ANY unit
+-- grant, i.e. which ones stopped meaning "available everywhere".
+CREATE INDEX IF NOT EXISTS resource_grants_table_unit_idx
+  ON public.resource_grants (resource_table, resource_id)
+  WHERE grantee_type = 'unit';
+
+ALTER TABLE public.resource_grants ENABLE ROW LEVEL SECURITY;
+
+-- ── Helpers ─────────────────────────────────────────────────────────────────
+-- Same discipline as 039: one argument at most, and it is a CONSTANT baked into
+-- the policy text by 042's generator, never a column. A helper taking the row's
+-- own values would be correlated and re-run per row.
+--
+-- SECURITY DEFINER because they read `resource_grants`, whose own policies
+-- resolve through them — invoker semantics would recurse.
+
+CREATE OR REPLACE FUNCTION public.shareable_tables()
+RETURNS SETOF text
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT resource_table FROM public.scoped_resources WHERE shareable;
+$$;
+
+-- Everything in `p_table` explicitly granted to me: to me by name, to a unit I
+-- reach, or to a team I am in.
+CREATE OR REPLACE FUNCTION public.granted_record_ids(p_table text)
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT g.resource_id
+    FROM public.resource_grants g
+   WHERE g.resource_table = p_table
+     AND (
+          (g.grantee_type = 'user' AND g.grantee_id = auth.uid())
+       OR (g.grantee_type = 'unit' AND g.grantee_id IN (SELECT public.user_unit_ids()))
+       OR (g.grantee_type = 'team' AND g.grantee_id IN (
+             SELECT tm.team_id FROM public.team_members tm WHERE tm.user_id = auth.uid()))
+     );
+$$;
+
+-- The rows of `p_table` that carry at least one UNIT grant.
+--
+-- This is what makes "Botox in 2 of 15" work without a second mechanism: a
+-- product with no unit grant is sold everywhere, and the moment it gets two it
+-- is sold in exactly those two. The predicate in 042 reads it as "a NULL unit
+-- means the whole org, UNLESS somebody named the units".
+CREATE OR REPLACE FUNCTION public.restricted_record_ids(p_table text)
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT DISTINCT g.resource_id
+    FROM public.resource_grants g
+   WHERE g.resource_table = p_table
+     AND g.grantee_type = 'unit';
+$$;
+
+-- Is this person one of ours? Used by the write gate to stop a grant pointing
+-- at somebody outside the tenant.
+--
+-- SECURITY DEFINER and not an inline subquery on `tenant_members` on purpose:
+-- that table's SELECT policy is `user_id = auth.uid()` on any pool that has not
+-- taken 023, so an inline read would see only the caller and the gate would
+-- silently allow granting to nobody but yourself.
+CREATE OR REPLACE FUNCTION public.is_tenant_member(p_tenant_id uuid, p_user_id uuid)
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT EXISTS (
+    SELECT 1 FROM public.tenant_members tm
+     WHERE tm.tenant_id = p_tenant_id AND tm.user_id = p_user_id
+  );
+$$;
+
+-- Am I the owner of this one row? Used only in the write gate below, once per
+-- inserted row.
+--
+-- The dynamic EXECUTE is safe because `p_table` is checked against the registry
+-- FIRST — the table name comes from a controlled list, not from the caller. And
+-- SECURITY DEFINER leaks nothing: the only thing this can ever tell you is
+-- whether a row is yours, which you already know.
+CREATE OR REPLACE FUNCTION public.owns_record(p_table text, p_id uuid)
+RETURNS boolean
+LANGUAGE plpgsql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+DECLARE
+  v_owner_column text;
+  v_owner uuid;
+BEGIN
+  IF auth.uid() IS NULL THEN
+    RETURN false;
+  END IF;
+
+  SELECT owner_column INTO v_owner_column
+    FROM public.scoped_resources WHERE resource_table = p_table;
+  IF v_owner_column IS NULL THEN
+    RETURN false;
+  END IF;
+
+  EXECUTE format('SELECT %I FROM public.%I WHERE id = $1', v_owner_column, p_table)
+    INTO v_owner USING p_id;
+
+  RETURN v_owner IS NOT NULL AND v_owner = auth.uid();
+EXCEPTION WHEN OTHERS THEN
+  -- A registry row pointing at a table that has not been provisioned yet must
+  -- deny, not abort the caller's INSERT.
+  RETURN false;
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.is_tenant_member(uuid, uuid)    TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.shareable_tables()              TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.granted_record_ids(text)        TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.restricted_record_ids(text)     TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.owns_record(text, uuid)         TO authenticated, service_role;
+
+-- ── Policies on the grants themselves ───────────────────────────────────────
+-- This is where a sharing model is won or lost. If anyone can insert a row
+-- here, anyone can grant themselves anything, and every predicate in 042 is
+-- decoration.
+--
+-- NOTE, and do not "simplify" it away: none of these policies may call
+-- granted_record_ids(). That function reads this table, and this table's
+-- policies would then resolve through it — the self-loop 023's header warns
+-- about, one table over.
+DROP POLICY IF EXISTS "resource_grants_select" ON public.resource_grants;
+CREATE POLICY "resource_grants_select" ON public.resource_grants FOR SELECT TO authenticated
+  USING (
+    tenant_id IN (SELECT public.user_tenant_ids())
+    AND (
+         tenant_id IN (SELECT public.user_admin_tenant_ids())
+      OR (grantee_type = 'user' AND grantee_id = (SELECT auth.uid()))
+      OR (grantee_type = 'unit' AND grantee_id IN (SELECT public.user_unit_ids()))
+      OR (grantee_type = 'team' AND grantee_id IN (
+            SELECT tm.team_id FROM public.team_members tm WHERE tm.user_id = (SELECT auth.uid())))
+      OR granted_by = (SELECT auth.uid())
+    )
+  );
+
+-- The gate. Four conditions, each closing a different door:
+--
+--  (a) granted_by = me — you cannot write a grant that claims someone else
+--      handed it out.
+--  (b) the table is in the registry — without this, `resource_table` is free
+--      text and someone grants themselves a row in a table the model never
+--      meant to cover.
+--  (c) owner-or-admin — deliberately NOT "anyone with write access". Answering
+--      "may I write row R of table T?" needs dynamic SQL evaluated under that
+--      table's own RLS, and that is exactly where subtle escalations live.
+--  (d) the recipient belongs to this tenant — no granting across the boundary
+--      that the whole product rests on.
+DROP POLICY IF EXISTS "resource_grants_insert" ON public.resource_grants;
+CREATE POLICY "resource_grants_insert" ON public.resource_grants FOR INSERT TO authenticated
+  WITH CHECK (
+    tenant_id IN (SELECT public.user_tenant_ids())
+    AND granted_by = (SELECT auth.uid())
+    AND resource_table IN (SELECT public.shareable_tables())
+    AND (
+         tenant_id IN (SELECT public.user_admin_tenant_ids())
+      OR public.owns_record(resource_table, resource_id)
+    )
+    AND (
+         (grantee_type = 'user' AND public.is_tenant_member(resource_grants.tenant_id, grantee_id))
+      OR (grantee_type = 'unit' AND grantee_id IN (
+            SELECT l.id FROM public.locations l WHERE l.tenant_id = resource_grants.tenant_id))
+      OR (grantee_type = 'team' AND grantee_id IN (
+            SELECT t.id FROM public.teams t WHERE t.tenant_id = resource_grants.tenant_id))
+    )
+  );
+
+-- No UPDATE policy, on purpose. A grant is created or revoked, never edited:
+-- mutating `access` in place makes the record's sharing history unreadable, the
+-- same reason 026 keeps the audit trail append-only. Changing a level is a
+-- delete and an insert, and both are visible.
+DROP POLICY IF EXISTS "resource_grants_delete" ON public.resource_grants;
+CREATE POLICY "resource_grants_delete" ON public.resource_grants FOR DELETE TO authenticated
+  USING (
+    tenant_id IN (SELECT public.user_tenant_ids())
+    AND (
+         tenant_id IN (SELECT public.user_admin_tenant_ids())
+      OR granted_by = (SELECT auth.uid())
+      OR public.owns_record(resource_table, resource_id)
+    )
+  );
+
+GRANT SELECT, INSERT, DELETE ON public.resource_grants TO authenticated;
+GRANT ALL ON public.resource_grants TO service_role;
+
+-- ── The guards ──────────────────────────────────────────────────────────────
+-- Everything above is PERMISSIVE, and permissive policies OR together — so any
+-- policy added to these tables later (002's sweep is the concrete case, see the
+-- header) silently widens them. These restrictive twins cannot be widened by
+-- anything, ever, and they are what actually holds the line.
+--
+-- Written per command rather than as one FOR ALL: a restrictive policy's USING
+-- clause applies to SELECT too, so a single FOR ALL admin guard would also stop
+-- ordinary members from READING their own team list.
+DO $$
+DECLARE
+  t text;
+  admin_managed text[] := ARRAY['teams', 'team_members', 'resource_visibility_defaults'];
+BEGIN
+  FOREACH t IN ARRAY admin_managed LOOP
+    EXECUTE format('DROP POLICY IF EXISTS %I ON public.%I', t || '_insert_guard', t);
+    EXECUTE format(
+      'CREATE POLICY %I ON public.%I AS RESTRICTIVE FOR INSERT TO authenticated
+         WITH CHECK (tenant_id IN (SELECT public.user_admin_tenant_ids()))',
+      t || '_insert_guard', t);
+
+    EXECUTE format('DROP POLICY IF EXISTS %I ON public.%I', t || '_update_guard', t);
+    EXECUTE format(
+      'CREATE POLICY %I ON public.%I AS RESTRICTIVE FOR UPDATE TO authenticated
+         USING (tenant_id IN (SELECT public.user_admin_tenant_ids()))',
+      t || '_update_guard', t);
+
+    EXECUTE format('DROP POLICY IF EXISTS %I ON public.%I', t || '_delete_guard', t);
+    EXECUTE format(
+      'CREATE POLICY %I ON public.%I AS RESTRICTIVE FOR DELETE TO authenticated
+         USING (tenant_id IN (SELECT public.user_admin_tenant_ids()))',
+      t || '_delete_guard', t);
+  END LOOP;
+END $$;
+
+-- The grant gate itself, restated so it cannot be ORed away. This is the one
+-- that matters: without it, a swept-in permissive INSERT policy lets any member
+-- of the tenant write themselves access to any record.
+DROP POLICY IF EXISTS "resource_grants_insert_guard" ON public.resource_grants;
+CREATE POLICY "resource_grants_insert_guard" ON public.resource_grants
+  AS RESTRICTIVE FOR INSERT TO authenticated
+  WITH CHECK (
+    granted_by = (SELECT auth.uid())
+    AND resource_table IN (SELECT public.shareable_tables())
+    AND (
+         tenant_id IN (SELECT public.user_admin_tenant_ids())
+      OR public.owns_record(resource_table, resource_id)
+    )
+    AND (
+         (grantee_type = 'user' AND public.is_tenant_member(resource_grants.tenant_id, grantee_id))
+      OR (grantee_type = 'unit' AND grantee_id IN (
+            SELECT l.id FROM public.locations l WHERE l.tenant_id = resource_grants.tenant_id))
+      OR (grantee_type = 'team' AND grantee_id IN (
+            SELECT t.id FROM public.teams t WHERE t.tenant_id = resource_grants.tenant_id))
+    )
+  );
+
+-- A grant is created or revoked, never edited (see the note above). Stated as a
+-- restrictive `false` rather than as the absence of a policy, because absence is
+-- exactly what a later sweep fills in.
+DROP POLICY IF EXISTS "resource_grants_no_update" ON public.resource_grants;
+CREATE POLICY "resource_grants_no_update" ON public.resource_grants
+  AS RESTRICTIVE FOR UPDATE TO authenticated
+  USING (false);
+
+DROP POLICY IF EXISTS "resource_grants_delete_guard" ON public.resource_grants;
+CREATE POLICY "resource_grants_delete_guard" ON public.resource_grants
+  AS RESTRICTIVE FOR DELETE TO authenticated
+  USING (
+         tenant_id IN (SELECT public.user_admin_tenant_ids())
+      OR granted_by = (SELECT auth.uid())
+      OR public.owns_record(resource_table, resource_id)
+  );
+
+-- Who may even SEE that a record was shared. Restrictive for the same reason:
+-- a swept-in permissive SELECT would turn the grant table into a map of every
+-- private record in the tenant and who can read it.
+DROP POLICY IF EXISTS "resource_grants_select_guard" ON public.resource_grants;
+CREATE POLICY "resource_grants_select_guard" ON public.resource_grants
+  AS RESTRICTIVE FOR SELECT TO authenticated
+  USING (
+         tenant_id IN (SELECT public.user_admin_tenant_ids())
+      OR (grantee_type = 'user' AND grantee_id = (SELECT auth.uid()))
+      OR (grantee_type = 'unit' AND grantee_id IN (SELECT public.user_unit_ids()))
+      OR (grantee_type = 'team' AND grantee_id IN (
+            SELECT tm.team_id FROM public.team_members tm WHERE tm.user_id = (SELECT auth.uid())))
+      OR granted_by = (SELECT auth.uid())
+      OR public.owns_record(resource_table, resource_id)
+  );

package/migrations/041_scoped_columns.sql

@@ -0,0 +1,192 @@
+-- ============================================================================
+-- 041_scoped_columns.sql — the signature every record starts carrying.
+--
+-- 025 gave every core table a `created_by`, because "who registered this?" had
+-- no answer anywhere. This file adds the other two halves of the same question:
+--
+--   unit_id   WHERE it happened / which unit it belongs to. NULL is a real and
+--             permanent answer: "the whole organization". A brand-level product
+--             has no unit and never will.
+--   owner_id  WHO answers for it TODAY. Deliberately not the same column as
+--             created_by: provenance is not responsibility. João registered the
+--             sourdough; if João leaves, Ana owns it, and the history still says
+--             João made it.
+--
+-- WHAT ALREADY EXISTS AND IS REUSED. `orders`, `appointments` and `schedules`
+-- have carried `location_id` since 004_archetypes, pointing at the very table
+-- 039 turned into the unit tree. That column IS the unit. Adding a second one
+-- to the three busiest tables in the product to satisfy a naming preference
+-- would be the wrong trade, so the registry names the column per table instead.
+--
+-- WHAT IS DELIBERATELY LEFT OUT:
+--   locations          it IS the tree; a unit does not belong to a unit
+--   order_items,       their policies already resolve through the parent row
+--   appointment_items  (006_archetype_rls), so they inherit for free
+--   addresses          already has an `owner_id` with completely different,
+--                      polymorphic meaning (shop 0012: owner_type + owner_id).
+--                      Two columns with one name and two meanings in one schema
+--                      is a bug waiting for a maintainer.
+--   plg_*              plugin-owned tables register themselves from their own
+--                      migrations. `documents` is the exception: 002 already
+--                      lists it among the core tables, and it is the patient
+--                      record the whole owner-visibility mode exists for.
+--
+-- FACTORY VISIBILITY, and why it is not uniform: a transaction belongs to the
+-- unit where it happened; a catalogue belongs to the brand. So appointments,
+-- orders, transactions and schedules start at 'unit' and everything else starts
+-- at 'tenant'. A tenant that never turns unit scoping on is unaffected either
+-- way — nothing in this file reads these values until 042, and 042 short
+-- circuits while the switch is off.
+--
+-- Additive and idempotent. Nullable ADD COLUMN does not rewrite a table on
+-- PG 11+, so this is safe on a populated pool.
+-- ============================================================================
+
+-- ── Columns, indexes and the stamping trigger, per table ────────────────────
+DO $$
+DECLARE
+  r record;
+  spec jsonb := '[
+    {"t": "people",       "unit": "unit_id",     "vis": "tenant", "share": true,  "label": "Pessoas"},
+    {"t": "categories",   "unit": "unit_id",     "vis": "tenant", "share": false, "label": "Categorias"},
+    {"t": "products",     "unit": "unit_id",     "vis": "tenant", "share": true,  "label": "Produtos"},
+    {"t": "services",     "unit": "unit_id",     "vis": "tenant", "share": true,  "label": "Serviços"},
+    {"t": "documents",    "unit": "unit_id",     "vis": "tenant", "share": true,  "label": "Documentos"},
+    {"t": "orders",       "unit": "location_id", "vis": "unit",   "share": false, "label": "Pedidos"},
+    {"t": "transactions", "unit": "unit_id",     "vis": "unit",   "share": false, "label": "Lançamentos"},
+    {"t": "appointments", "unit": "location_id", "vis": "unit",   "share": false, "label": "Agendamentos"},
+    {"t": "schedules",    "unit": "location_id", "vis": "unit",   "share": false, "label": "Horários"}
+  ]'::jsonb;
+  v_t text;
+  v_unit text;
+  v_has_author boolean;
+  v_owner_default text;
+BEGIN
+  FOR r IN SELECT * FROM jsonb_array_elements(spec) AS e(v) LOOP
+    v_t    := r.v ->> 't';
+    v_unit := r.v ->> 'unit';
+
+    -- The direct answer to "the ledger is not to be trusted": a pool may or may
+    -- not have this table regardless of what any migration record claims.
+    IF to_regclass('public.' || v_t) IS NULL THEN
+      CONTINUE;
+    END IF;
+
+    -- ON DELETE SET NULL, not CASCADE: closing a unit must not delete its
+    -- history. The rows fall back to "the whole organization", which is the
+    -- honest state for a record whose unit no longer exists.
+    EXECUTE format(
+      'ALTER TABLE public.%I ADD COLUMN IF NOT EXISTS %I uuid REFERENCES public.locations(id) ON DELETE SET NULL',
+      v_t, v_unit);
+
+    EXECUTE format(
+      'ALTER TABLE public.%I ADD COLUMN IF NOT EXISTS owner_id uuid REFERENCES auth.users(id) ON DELETE SET NULL',
+      v_t);
+
+    -- tenant_id leads because every app query already carries it. These indexes
+    -- are for the APPLICATION's own filters, not for the policy: a disjunction
+    -- in an RLS predicate can never be index-driven (the rewriter puts it in
+    -- securityQuals, where a sublink is never turned into a semijoin), so it is
+    -- always a filter. Do not add more indexes hoping to speed the policy up.
+    EXECUTE format('CREATE INDEX IF NOT EXISTS %I ON public.%I (tenant_id, %I)',
+                   v_t || '_unit_idx', v_t, v_unit);
+    EXECUTE format('CREATE INDEX IF NOT EXISTS %I ON public.%I (tenant_id, owner_id) WHERE owner_id IS NOT NULL',
+                   v_t || '_owner_idx', v_t);
+
+    -- `created_by` arrives with 025 for the archetypes and with plugin-forms
+    -- for `documents`. Checked rather than assumed: a pool assembled by hand
+    -- may be missing it, and a migration that fails on a drifted pool is a
+    -- migration nobody can apply.
+    SELECT EXISTS (
+      SELECT 1 FROM information_schema.columns
+       WHERE table_schema = 'public' AND table_name = v_t AND column_name = 'created_by'
+    ) INTO v_has_author;
+
+    -- Existing rows get the author as owner where there is one. Rows that
+    -- predate 025 have no author and stay ownerless — inventing one would
+    -- fabricate responsibility, and 042 reads a NULL owner as "nobody owns
+    -- this", which is exactly right: an ownerless record can never be private.
+    IF v_has_author THEN
+      EXECUTE format('UPDATE public.%I SET owner_id = created_by WHERE owner_id IS NULL AND created_by IS NOT NULL', v_t);
+    END IF;
+
+    v_owner_default := CASE WHEN v_has_author THEN 'COALESCE(NEW.created_by, auth.uid())' ELSE 'auth.uid()' END;
+
+    -- One generated trigger function per table instead of one shared function
+    -- reading TG_ARGV: assigning to a column whose name is only known at
+    -- runtime means a to_jsonb/jsonb_populate_record round trip through every
+    -- inserted row, and that round trip is exactly where a text[] or a numeric
+    -- quietly changes shape. Baking the two column names in keeps it a plain
+    -- field assignment.
+    --
+    -- IT MUST NEVER RAISE. place_order, fn_invoice_from_order_internal and
+    -- every agent_* RPC are SECURITY DEFINER and insert into these tables. RLS
+    -- does not apply to them — but a BEFORE INSERT trigger still fires, so a
+    -- trigger that complains takes down anonymous checkout. Validation is the
+    -- WITH CHECK clause's job in 042, which those paths legitimately bypass.
+    EXECUTE format($f$
+      CREATE OR REPLACE FUNCTION public.%1$I() RETURNS trigger
+      LANGUAGE plpgsql SECURITY DEFINER SET search_path = public, pg_temp AS $body$
+      BEGIN
+        IF NEW.%2$I IS NULL THEN
+          NEW.%2$I := public.requested_unit();
+        END IF;
+        IF NEW.owner_id IS NULL THEN
+          NEW.owner_id := %3$s;
+        END IF;
+        RETURN NEW;
+      EXCEPTION WHEN OTHERS THEN
+        RETURN NEW;
+      END $body$;
+    $f$, 'stamp_scope_' || v_t, v_unit, v_owner_default);
+
+    EXECUTE format('REVOKE ALL ON FUNCTION public.%I() FROM public, anon', 'stamp_scope_' || v_t);
+
+    EXECUTE format('DROP TRIGGER IF EXISTS %I ON public.%I', v_t || '_scope_stamp', v_t);
+    EXECUTE format(
+      'CREATE TRIGGER %I BEFORE INSERT ON public.%I FOR EACH ROW EXECUTE FUNCTION public.%I()',
+      v_t || '_scope_stamp', v_t, 'stamp_scope_' || v_t);
+
+    -- The registry row. This is the list 042 loops over and the settings screen
+    -- reads — one source of truth instead of the same array copied into three
+    -- files that will drift apart on the first table anyone adds.
+    INSERT INTO public.scoped_resources
+      (resource_table, unit_column, owner_column, shareable, default_visibility, label)
+    VALUES
+      (v_t, v_unit, 'owner_id', (r.v ->> 'share')::boolean, r.v ->> 'vis', r.v ->> 'label')
+    ON CONFLICT (resource_table) DO UPDATE
+      SET unit_column  = EXCLUDED.unit_column,
+          owner_column = EXCLUDED.owner_column,
+          shareable    = EXCLUDED.shareable,
+          label        = EXCLUDED.label;
+    -- default_visibility is NOT updated on conflict: it is the factory setting,
+    -- and re-running a migration must not walk back a decision an operator made
+    -- (a tenant's own choice lives in resource_visibility_defaults regardless).
+  END LOOP;
+END $$;
+
+-- ── The effective visibility of a record type, per tenant ───────────────────
+-- The tenant's own choice wins over the factory setting. Restricted to tenants
+-- that actually turned unit scoping on, because that is the only set 042 ever
+-- asks about — and it keeps this set small enough to hash once per query.
+--
+-- Two arguments, both constants baked into the policy text by 042's generator,
+-- so it stays uncorrelated: one InitPlan per query, not one call per row.
+CREATE OR REPLACE FUNCTION public.resource_mode_tenants(p_table text, p_mode text)
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT t.id
+    FROM public.tenants t
+    LEFT JOIN public.resource_visibility_defaults d
+           ON d.tenant_id = t.id AND d.resource_table = p_table
+   WHERE t.unit_scoping_enabled
+     AND COALESCE(
+           d.default_visibility,
+           (SELECT sr.default_visibility FROM public.scoped_resources sr
+             WHERE sr.resource_table = p_table)
+         ) = p_mode;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.resource_mode_tenants(text, text) TO authenticated, service_role;