@fayz-ai/db 0.10.0 → 0.12.0

package/migrations/039_unit_tree.sql

@@ -0,0 +1,270 @@
+-- ============================================================================
+-- 039_unit_tree.sql — the org tree `locations` always was, finally readable.
+--
+-- WHAT A UNIT IS. A franchise brand is ONE tenant with N units: "Alem do Olhar"
+-- has 15 of them. The unit is not a new noun — it is `public.locations`, which
+-- 001_core created with `is_headquarters` and `kind DEFAULT 'branch'` and which
+-- nothing has ever read for authorization. Two kinds and only two:
+--
+--     kind='region'  groups units          kind='branch'  IS the unit
+--
+-- A ROOM IS NOT A UNIT. Sala, cadeira, mesa, consultório are *service
+-- locations* — operational places that HAVE a unit — and they do not belong in
+-- this table; mixing "where the chair is" with "who may see the money" is how
+-- an authorization model stops being explainable. No room concept exists in the
+-- code today (`kind='room'`/`'zone'` appears in prose documentation and in no
+-- table and no screen), so there is nothing to migrate and the tree is exactly
+-- two levels deep.
+--
+-- WHAT THIS FILE DOES NOT DO. Nothing here changes what any query returns. It
+-- adds the tree, the bindings, the per-tenant switch and the five helper
+-- functions; 042 is the file that turns them into a boundary, and even that one
+-- is inert until a tenant sets `unit_scoping_enabled`.
+--
+-- IT ALSO REPAIRS `location_members`. That table has existed since 001_core
+-- with a SELECT policy and NOTHING else: no INSERT, no UPDATE, no DELETE, so no
+-- screen has ever been able to write a binding. It also has no index leading
+-- with `user_id`, which would make `user_unit_ids()` seq-scan it on every
+-- single query. Both are fixed here.
+--
+-- Additive and idempotent: safe to re-run, no-ops when already applied.
+-- ============================================================================
+
+-- ── The tree ────────────────────────────────────────────────────────────────
+ALTER TABLE public.locations
+  ADD COLUMN IF NOT EXISTS parent_id uuid,
+  ADD COLUMN IF NOT EXISTS code text;
+
+COMMENT ON COLUMN public.locations.parent_id IS
+  'Parent node of the org tree: a branch points at its region. Two levels only.';
+COMMENT ON COLUMN public.locations.code IS
+  'The unit code the franchise already uses on its own paperwork (e.g. "RJ-042").';
+
+-- A parent in ANOTHER tenant would be a cross-tenant edge inside the very
+-- structure that decides visibility. The composite FK makes it unrepresentable
+-- rather than merely discouraged — cheaper and more honest than a trigger.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'locations_id_tenant_uniq'
+  ) THEN
+    ALTER TABLE public.locations ADD CONSTRAINT locations_id_tenant_uniq UNIQUE (id, tenant_id);
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'locations_parent_same_tenant'
+  ) THEN
+    ALTER TABLE public.locations
+      ADD CONSTRAINT locations_parent_same_tenant
+      FOREIGN KEY (parent_id, tenant_id)
+      REFERENCES public.locations (id, tenant_id) ON DELETE SET NULL;
+  END IF;
+
+  -- Self-parenting is the one cycle a CHECK can catch. Deeper cycles are
+  -- survivable by construction: user_unit_ids() walks with UNION (which dedupes
+  -- and therefore terminates) plus a depth guard. NOT VALID so no live table is
+  -- scanned; new and updated rows are checked from here on.
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint WHERE conname = 'locations_no_self_parent'
+  ) THEN
+    ALTER TABLE public.locations
+      ADD CONSTRAINT locations_no_self_parent CHECK (parent_id IS DISTINCT FROM id) NOT VALID;
+  END IF;
+END $$;
+
+CREATE INDEX IF NOT EXISTS locations_parent_idx
+  ON public.locations (parent_id) WHERE parent_id IS NOT NULL;
+
+-- ── The bindings ────────────────────────────────────────────────────────────
+-- `tenant_id` denormalised so this table's own policies take the canonical
+-- shape instead of joining back through `locations` on every check.
+ALTER TABLE public.location_members
+  ADD COLUMN IF NOT EXISTS tenant_id uuid REFERENCES public.tenants(id) ON DELETE CASCADE;
+
+UPDATE public.location_members lm
+   SET tenant_id = l.tenant_id
+  FROM public.locations l
+ WHERE l.id = lm.location_id
+   AND lm.tenant_id IS DISTINCT FROM l.tenant_id;
+
+-- The column is derived, so deriving it is the trigger's job — a caller that
+-- has to remember to pass it will eventually not, and a binding with a NULL
+-- tenant is invisible to every policy below.
+CREATE OR REPLACE FUNCTION public.handle_location_member_tenant()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+BEGIN
+  SELECT l.tenant_id INTO NEW.tenant_id
+    FROM public.locations l WHERE l.id = NEW.location_id;
+  RETURN NEW;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.handle_location_member_tenant() FROM public, anon;
+
+DROP TRIGGER IF EXISTS location_members_tenant ON public.location_members;
+CREATE TRIGGER location_members_tenant
+  BEFORE INSERT OR UPDATE OF location_id ON public.location_members
+  FOR EACH ROW EXECUTE FUNCTION public.handle_location_member_tenant();
+
+-- Without this index every RLS-evaluated call of user_unit_ids() seq-scans the
+-- table. 001_core's only index is UNIQUE(location_id, user_id) — wrong leading
+-- column for the one question this table is ever asked.
+CREATE INDEX IF NOT EXISTS location_members_user_idx
+  ON public.location_members (user_id, location_id);
+
+-- A binding with no role is the normal case: it says "you work here", and the
+-- role you already have in the org applies. A role here only ever ADDS.
+ALTER TABLE public.location_members ALTER COLUMN role DROP DEFAULT;
+
+COMMENT ON COLUMN public.location_members.role IS
+  'Additional role INSIDE this unit. Unions with the org role, never subtracts. NULL = no extra role.';
+
+-- ── The per-tenant switch ───────────────────────────────────────────────────
+-- A column and not a key in `tenants.settings`, following the precedent shop
+-- 0020 set with `storefront_strict_scope`: a security flag read inside a policy
+-- has to be cheap and indexable, and a jsonb extraction is neither.
+ALTER TABLE public.tenants
+  ADD COLUMN IF NOT EXISTS unit_scoping_enabled boolean NOT NULL DEFAULT false;
+
+COMMENT ON COLUMN public.tenants.unit_scoping_enabled IS
+  'Off by default. While false, every unit predicate in 042 short-circuits and this tenant behaves exactly as before.';
+
+-- ── Helpers ─────────────────────────────────────────────────────────────────
+-- Every one of these is zero-argument on purpose. A helper that takes the row's
+-- own column (is_tenant_admin(tenant_id) is the cautionary example) is
+-- correlated: RLS injects the predicate into securityQuals, where the planner
+-- never turns a sublink into a semijoin, so it becomes a SubPlan re-executed
+-- once PER ROW. Zero-argument helpers wrapped in `(SELECT …)` become one
+-- InitPlan per query, hashed, then a probe per row.
+--
+-- All are SECURITY DEFINER for the reason 023 spells out: they read the very
+-- tables whose policies will call them, and invoker semantics would recurse.
+
+-- The pool-level short circuit. On a pool where nobody uses units this returns
+-- false once per query and the whole predicate in 042 costs one boolean test
+-- per row — no hash build, because OR does not evaluate its later arms.
+CREATE OR REPLACE FUNCTION public.unit_scoping_active()
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT EXISTS (SELECT 1 FROM public.tenants WHERE unit_scoping_enabled);
+$$;
+
+CREATE OR REPLACE FUNCTION public.unit_scoped_tenants()
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT id FROM public.tenants WHERE unit_scoping_enabled;
+$$;
+
+-- The tenants where the caller may see everything regardless of unit. Mirrors
+-- is_tenant_admin's role set exactly (001_core:87) — divergence here would mean
+-- the settings screens and the row predicate disagree about who is an admin.
+CREATE OR REPLACE FUNCTION public.user_admin_tenant_ids()
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  SELECT tm.tenant_id
+    FROM public.tenant_members tm
+   WHERE tm.user_id = auth.uid()
+     AND tm.role IN ('owner', 'admin');
+$$;
+
+-- The units the caller reaches. A binding to a region reaches its branches;
+-- reach flows DOWN the tree and never up — a unit manager is not a regional.
+--
+-- Deliberately NOT tenant-aware: a user can belong to tenant A with units on
+-- and tenant B with units off, and one answer cannot serve both. The mode check
+-- lives in the predicate (042), where it is free.
+CREATE OR REPLACE FUNCTION public.user_unit_ids()
+RETURNS SETOF uuid
+LANGUAGE sql STABLE SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+  WITH RECURSIVE seed AS (
+    SELECT lm.location_id AS id, 0 AS depth
+      FROM public.location_members lm
+     WHERE lm.user_id = auth.uid()
+  ),
+  tree AS (
+    SELECT id, depth FROM seed
+    UNION                                -- UNION, not UNION ALL: dedupes, and
+    SELECT l.id, t.depth + 1             -- therefore terminates on a cycle
+      FROM public.locations l
+      JOIN tree t ON l.parent_id = t.id
+     WHERE t.depth < 8                   -- a policy must never be able to hang
+  )
+  SELECT id FROM tree;
+$$;
+
+-- The unit the browser says it is looking at, read from a request header the
+-- same way shop 0020 reads `x-fayz-store`. It NARROWS a write's default stamp;
+-- it never grants anything — 042 validates the stamped unit against
+-- user_unit_ids() in WITH CHECK. Swallows every parse failure for the reason
+-- 028 states: an RLS-adjacent function is not a place to raise.
+CREATE OR REPLACE FUNCTION public.requested_unit()
+RETURNS uuid
+LANGUAGE plpgsql STABLE
+SET search_path = public, pg_temp
+AS $$
+DECLARE v text;
+BEGIN
+  v := nullif(current_setting('request.headers', true), '')::json ->> 'x-fayz-unit';
+  RETURN nullif(v, '')::uuid;
+EXCEPTION WHEN OTHERS THEN
+  RETURN NULL;
+END;
+$$;
+
+GRANT EXECUTE ON FUNCTION public.unit_scoping_active()     TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.unit_scoped_tenants()     TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.user_admin_tenant_ids()   TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.user_unit_ids()           TO authenticated, service_role;
+GRANT EXECUTE ON FUNCTION public.requested_unit()          TO authenticated, service_role;
+
+-- ── Policies on the tree itself ─────────────────────────────────────────────
+-- `locations` and `location_members` are in 002's core_tables exclusion list,
+-- so they carry curated policies and no sweep will overwrite these.
+--
+-- RLS is re-enabled rather than assumed: 001_core enables it, but a pool built
+-- by hand (the ecommerce pool has tables the ledger never heard of) may not have
+-- run 001, and a policy on a table without RLS is decoration.
+ALTER TABLE public.locations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.location_members ENABLE ROW LEVEL SECURITY;
+--
+-- The tree stays readable tenant-wide even under unit scoping, on purpose: the
+-- unit switcher, the "Unidade: Ipanema" label on a record and the reports
+-- breakdown all need to name a unit the reader may not have data in. A unit's
+-- NAME is not its data.
+DROP POLICY IF EXISTS "locations_select" ON public.locations;
+CREATE POLICY "locations_select" ON public.locations FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+DROP POLICY IF EXISTS "loc_members_select" ON public.location_members;
+CREATE POLICY "loc_members_select" ON public.location_members FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+
+-- The missing three quarters of the table. Only a tenant admin hands out
+-- access to a unit — the same bar `tenant_role_overrides` and `invitations`
+-- already set for who may change who can do what.
+DROP POLICY IF EXISTS "loc_members_insert" ON public.location_members;
+CREATE POLICY "loc_members_insert" ON public.location_members FOR INSERT TO authenticated
+  WITH CHECK (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+DROP POLICY IF EXISTS "loc_members_update" ON public.location_members;
+CREATE POLICY "loc_members_update" ON public.location_members FOR UPDATE TO authenticated
+  USING (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+DROP POLICY IF EXISTS "loc_members_delete" ON public.location_members;
+CREATE POLICY "loc_members_delete" ON public.location_members FOR DELETE TO authenticated
+  USING (tenant_id IN (SELECT public.user_admin_tenant_ids()));
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.location_members TO authenticated;
+GRANT ALL ON public.location_members TO service_role;