@fayz-ai/db 0.11.0 → 0.13.0

package/migrations/075_company_legal_entities.sql

@@ -0,0 +1,169 @@
+-- ============================================================================
+-- 075_company_legal_entities.sql — the Empresa (legal entity) a unit operates
+-- under (#138, PRD 02 R2, default (c)).
+--
+-- Why this name. PRD 02 R2 left it open ("tabela core `companies`, nome a
+-- definir com o SDK; glossário Empresa"). The bare `companies` is taken: in V1
+-- one CNPJ IS one company IS one unit, and that row maps to app.units — calling
+-- this table `companies` would collide with the concept every V1 reader already
+-- has. `company_legal_entities` keeps the word the reviewer asked for and says
+-- exactly what the row is: the legal person (CNPJ/CPF) a unit operates under.
+--
+-- public.company_legal_entities is the company (CNPJ) or individual (CPF) that
+-- a unit operates under: legal name, trade name, document, registrations, tax
+-- regime, fiscal address, contact, bank data (contract only — no payment
+-- provider is wired here). One legal entity may serve many units (V2, 1:n); V1
+-- arrives 1:1 (companies → units + company_legal_entities).
+-- app.units.company_legal_entity_id is the reference, ON DELETE SET NULL,
+-- composite over (tenant_id, id) so a unit can never point at another tenant's
+-- company. NULL is allowed only while a unit is a draft: a CHECK would break
+-- every existing unit, so the invariant is observable instead —
+-- public.v_units_without_company_legal_entity lists the drafts and the
+-- migration/onboarding closes them.
+--
+-- The table is a business table of the 'tenancy' plugin: scaffolded with the
+-- ONE RLS template (app.scaffold_table, enforce mode; owner scoping off), so a
+-- legal entity is visible to members who reach its unit (unit_id = the unit it
+-- is registered at — the parent of the units that share it) with tenancy.read,
+-- and everything is visible to an all_units member. Permission keys
+-- tenancy.read/create/edit/delete/manage are registered here and added to the
+-- vertical templates: every role reads (a receipt needs the CNPJ), managers and
+-- admins manage. Existing tenants are re-seeded from their recorded template.
+-- The keys stay `tenancy.*`: they name the capability, not the table.
+--
+-- Next (not here): the seven inline fiscal-address columns should move to the
+-- polymorphic public.addresses (017), with owner_type gaining
+-- 'company_legal_entity'. Queued separately — see
+-- docs/data/phase-0/02-tenancy-units-company.md §1.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS public.company_legal_entities (
+  id                     uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id              uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  kind                   text NOT NULL DEFAULT 'company' CHECK (kind IN ('company', 'individual')),
+  legal_name             text NOT NULL,
+  trade_name             text,
+  document_number        text,                       -- CNPJ (14 digits) or CPF (11 digits), digits only
+  state_registration     text,
+  municipal_registration text,
+  tax_regime             text,                       -- simples_nacional | lucro_presumido | lucro_real | mei | other (free text, validated by the app)
+  address                text,
+  address_number         text,
+  address_complement     text,
+  district               text,
+  city                   text,
+  state                  text,
+  postal_code            text,
+  country                text NOT NULL DEFAULT 'BR',
+  email                  text,
+  phone                  text,
+  bank_data              jsonb NOT NULL DEFAULT '{}'::jsonb,   -- {bank_code, agency, account, account_type, pix_key}
+  metadata               jsonb NOT NULL DEFAULT '{}'::jsonb,
+  is_active              boolean NOT NULL DEFAULT true,
+  created_at             timestamptz NOT NULL DEFAULT now(),
+  updated_at             timestamptz NOT NULL DEFAULT now()
+);
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'company_legal_entities_document_number_check' AND conrelid = 'public.company_legal_entities'::regclass) THEN
+    ALTER TABLE public.company_legal_entities
+      ADD CONSTRAINT company_legal_entities_document_number_check
+      CHECK (document_number IS NULL OR document_number ~ '^[0-9]{11}$' OR document_number ~ '^[0-9]{14}$');
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'company_legal_entities_kind_document_check' AND conrelid = 'public.company_legal_entities'::regclass) THEN
+    ALTER TABLE public.company_legal_entities
+      ADD CONSTRAINT company_legal_entities_kind_document_check
+      CHECK (document_number IS NULL
+             OR (kind = 'company' AND length(document_number) = 14)
+             OR (kind = 'individual' AND length(document_number) = 11));
+  END IF;
+END $$;
+-- one document per tenant (a company may still serve many units)
+CREATE UNIQUE INDEX IF NOT EXISTS company_legal_entities_tenant_document_uidx
+  ON public.company_legal_entities (tenant_id, document_number) WHERE document_number IS NOT NULL;
+
+-- digits only, whatever the client typed
+CREATE OR REPLACE FUNCTION public.trg_company_legal_entities_normalize()
+RETURNS trigger LANGUAGE plpgsql SET search_path = '' AS $$
+BEGIN
+  NEW.document_number := nullif(regexp_replace(coalesce(NEW.document_number, ''), '[^0-9]', '', 'g'), '');
+  NEW.postal_code     := nullif(regexp_replace(coalesce(NEW.postal_code, ''), '[^0-9A-Za-z-]', '', 'g'), '');
+  NEW.legal_name      := btrim(NEW.legal_name);
+  IF NEW.legal_name = '' THEN
+    RAISE EXCEPTION 'company_legal_entities: legal_name is required' USING ERRCODE = '22023';
+  END IF;
+  RETURN NEW;
+END $$;
+REVOKE ALL ON FUNCTION public.trg_company_legal_entities_normalize() FROM public, anon;
+DROP TRIGGER IF EXISTS company_legal_entities_normalize ON public.company_legal_entities;
+CREATE TRIGGER company_legal_entities_normalize BEFORE INSERT OR UPDATE ON public.company_legal_entities
+  FOR EACH ROW EXECUTE FUNCTION public.trg_company_legal_entities_normalize();
+
+-- ── permission keys + templates ─────────────────────────────────────────
+SELECT app.seed_permissions('[
+  {"key":"tenancy.read","plugin":"tenancy","description":"Read legal entities (Empresa) of the units in scope"},
+  {"key":"tenancy.create","plugin":"tenancy","description":"Create a legal entity"},
+  {"key":"tenancy.edit","plugin":"tenancy","description":"Edit a legal entity"},
+  {"key":"tenancy.delete","plugin":"tenancy","description":"Delete a legal entity"},
+  {"key":"tenancy.manage","plugin":"tenancy","description":"Manage legal entities and their unit links"}
+]'::jsonb);
+-- every role reads; managers/admins manage
+SELECT app.seed_role_template_rows('generic', 'admin',   'Administrator', 1, ARRAY['tenancy.manage']);
+SELECT app.seed_role_template_rows('generic', 'manager', 'Manager',       2, ARRAY['tenancy.manage']);
+SELECT app.seed_role_template_rows('generic', 'staff',   'Staff',         3, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('generic', 'viewer',  'Viewer',        4, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('salon', 'manager',      'Gerente',      1, ARRAY['tenancy.manage']);
+SELECT app.seed_role_template_rows('salon', 'reception',    'Recepção',     2, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('salon', 'professional', 'Profissional', 3, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('salon', 'financial',    'Financeiro',   4, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('clinic', 'manager',      'Coordenação',  1, ARRAY['tenancy.manage']);
+SELECT app.seed_role_template_rows('clinic', 'reception',    'Recepção',     2, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('clinic', 'professional', 'Profissional', 3, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('clinic', 'financial',    'Financeiro',   4, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('restaurant', 'manager', 'Gerente', 1, ARRAY['tenancy.manage']);
+SELECT app.seed_role_template_rows('restaurant', 'cashier', 'Caixa',   2, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('restaurant', 'waiter',  'Garçom',  3, ARRAY['tenancy.read']);
+SELECT app.seed_role_template_rows('restaurant', 'kitchen', 'Cozinha', 4, ARRAY['tenancy.read']);
+-- tenants already seeded from a template receive the new keys (idempotent)
+SELECT app.seed_role_template(t.id, t.role_template)
+  FROM public.tenants t
+ WHERE t.role_template IS NOT NULL
+   AND EXISTS (SELECT 1 FROM app.role_templates rt WHERE rt.template = t.role_template);
+
+-- ── the scaffold: columns, composite FKs, indexes, forced RLS, the 4 policies
+SELECT app.scaffold_table('public.company_legal_entities', 'tenancy.company_legal_entity', 'tenancy', false, 'enforce');
+GRANT SELECT, INSERT, UPDATE, DELETE ON public.company_legal_entities TO authenticated;
+GRANT ALL ON public.company_legal_entities TO service_role;
+REVOKE ALL ON public.company_legal_entities FROM anon;
+
+-- ── the unit → company legal entity reference ───────────────────────────
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'units_company_legal_entity_fk' AND conrelid = 'app.units'::regclass) THEN
+    ALTER TABLE app.units
+      ADD CONSTRAINT units_company_legal_entity_fk
+      FOREIGN KEY (tenant_id, company_legal_entity_id) REFERENCES public.company_legal_entities (tenant_id, id)
+      ON DELETE SET NULL (company_legal_entity_id);
+  END IF;
+END $$;
+CREATE INDEX IF NOT EXISTS units_company_legal_entity_idx ON app.units (tenant_id, company_legal_entity_id) WHERE company_legal_entity_id IS NOT NULL;
+
+-- Drafts: active units that still point at no company legal entity (the
+-- invariant a CHECK cannot enforce yet). security_invoker: app.units RLS applies.
+CREATE OR REPLACE VIEW public.v_units_without_company_legal_entity WITH (security_invoker = true) AS
+  SELECT u.tenant_id, u.id AS unit_id, u.kind, u.name, u.parent_unit_id, u.created_at
+    FROM app.units u
+   WHERE u.active AND u.company_legal_entity_id IS NULL;
+GRANT SELECT ON public.v_units_without_company_legal_entity TO authenticated, service_role;
+
+-- Consolidation: every unit with its company and its parent (the network view:
+-- group by parent_unit_id gives "the franchisee's companies").
+CREATE OR REPLACE VIEW public.v_unit_company_legal_entities WITH (security_invoker = true) AS
+  SELECT u.tenant_id, u.id AS unit_id, u.kind AS unit_kind, u.name AS unit_name, u.parent_unit_id,
+         cle.id AS company_legal_entity_id, cle.kind AS company_legal_entity_kind,
+         cle.legal_name, cle.trade_name, cle.document_number,
+         cle.city, cle.state, cle.is_active AS company_legal_entity_active
+    FROM app.units u
+    LEFT JOIN public.company_legal_entities cle
+           ON cle.tenant_id = u.tenant_id AND cle.id = u.company_legal_entity_id;
+GRANT SELECT ON public.v_unit_company_legal_entities TO authenticated, service_role;

package/migrations/076_tenant_settings.sql

@@ -0,0 +1,251 @@
+-- ============================================================================
+-- 076_tenant_settings.sql — tenant settings by key (#138, PRD 02 R4/R5, default (g)).
+--
+-- V1's general_settings is a bag of columns from every layer. V2 keeps
+-- tenants.settings (jsonb) as the store and adds a REGISTRY of what may live in
+-- it: app.tenant_setting_keys (key, type, default, description, reader, scope).
+-- Core keys are seeded here; a plugin registers its own with reader
+-- 'plugin:<id>' from its migration (app.seed_setting_keys). A key that is not
+-- registered cannot be written through the RPC, and reads of unknown keys are
+-- refused — the registry is the contract. `permissions_enforcement_enabled` is
+-- deliberately absent (RLS is the law; PRD 02 R4).
+--
+-- Dotted keys are nested paths in the jsonb: 'branding.logo_url' lives at
+-- settings -> 'branding' -> 'logo_url' — the shape the admin adapter already
+-- writes ({branding: {}}). Legacy free-form keys already in tenants.settings
+-- are tolerated (nothing deletes them); only the RPC surface is governed.
+--
+-- RPCs (SECURITY DEFINER, search_path '', tenant = app.current_tenant_id()):
+--   tenant_setting(key)            → jsonb   effective value (set value, else default);
+--                                             any active member may read (the UI
+--                                             needs locale/timezone before it renders
+--                                             a settings screen); unknown key → 22023
+--   tenant_settings()              → jsonb   {key: effective value} for every registered key
+--   tenant_setting_set(key, value) → jsonb   settings.manage; type-checked; JSON null
+--                                             clears the key (default applies again)
+--   tenant_branding()              → jsonb   {tenant_id, name, logo_url, primary_color,
+--                                             custom_domain} for the current tenant;
+--                                             NEVER raises — defaults on any error
+--                                             (US-PLT-ADM-06: branding must not block login)
+--   tenant_branding_public(slug, domain) → jsonb  the same, narrow, by slug or custom
+--                                             domain, callable by anon for the login
+--                                             page (a slug is a URL; nothing else leaks)
+--
+-- tenant_domains (V1) has no table: a custom domain is the setting
+-- branding.custom_domain; routing by domain is the platform's job.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS app.tenant_setting_keys (
+  key           text PRIMARY KEY CHECK (key ~ '^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$'),
+  type          text NOT NULL CHECK (type IN ('string', 'integer', 'number', 'boolean', 'object', 'array')),
+  default_value jsonb,
+  description   text,
+  reader        text NOT NULL DEFAULT 'core' CHECK (reader = 'core' OR reader ~ '^plugin:[a-z][a-z0-9_-]*$'),
+  scope         text NOT NULL DEFAULT 'tenant' CHECK (scope IN ('tenant', 'unit')),
+  created_at    timestamptz NOT NULL DEFAULT now(),
+  updated_at    timestamptz NOT NULL DEFAULT now()
+);
+DROP TRIGGER IF EXISTS tenant_setting_keys_updated_at ON app.tenant_setting_keys;
+CREATE TRIGGER tenant_setting_keys_updated_at BEFORE UPDATE ON app.tenant_setting_keys
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+ALTER TABLE app.tenant_setting_keys ENABLE ROW LEVEL SECURITY;
+GRANT SELECT ON app.tenant_setting_keys TO authenticated;
+GRANT ALL ON app.tenant_setting_keys TO service_role;
+REVOKE ALL ON app.tenant_setting_keys FROM anon;
+DROP POLICY IF EXISTS tenant_setting_keys_select ON app.tenant_setting_keys;
+CREATE POLICY tenant_setting_keys_select ON app.tenant_setting_keys FOR SELECT TO authenticated USING (true);
+
+CREATE OR REPLACE FUNCTION app.seed_setting_keys(p_rows jsonb)
+RETURNS integer LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_n integer;
+BEGIN
+  WITH ins AS (
+    INSERT INTO app.tenant_setting_keys (key, type, default_value, description, reader, scope)
+    SELECT r ->> 'key', r ->> 'type', r -> 'default', r ->> 'description',
+           coalesce(r ->> 'reader', 'core'), coalesce(r ->> 'scope', 'tenant')
+      FROM jsonb_array_elements(p_rows) r
+    ON CONFLICT (key) DO UPDATE
+      SET type = EXCLUDED.type, default_value = EXCLUDED.default_value,
+          description = coalesce(EXCLUDED.description, app.tenant_setting_keys.description),
+          reader = EXCLUDED.reader, scope = EXCLUDED.scope
+    RETURNING 1
+  ) SELECT count(*) INTO v_n FROM ins;
+  RETURN v_n;
+END $$;
+REVOKE ALL ON FUNCTION app.seed_setting_keys(jsonb) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION app.seed_setting_keys(jsonb) TO service_role;
+
+-- ── core keys ───────────────────────────────────────────────────────────
+SELECT app.seed_setting_keys('[
+  {"key":"locale",   "type":"string", "default":"pt-BR",             "description":"UI locale of the tenant (BCP 47)"},
+  {"key":"timezone", "type":"string", "default":"America/Sao_Paulo", "description":"IANA time zone every date of the tenant is shown in"},
+  {"key":"currency", "type":"string", "default":"BRL",               "description":"ISO 4217 currency of prices and totals"},
+  {"key":"branding.logo_url",      "type":"string", "default":null, "description":"Logo shown in the app and on the login page (falls back to tenants.logo_url)"},
+  {"key":"branding.primary_color", "type":"string", "default":null, "description":"Primary brand colour (CSS colour)"},
+  {"key":"branding.custom_domain", "type":"string", "default":null, "description":"Custom domain of the tenant (white-label); routing is the platform''s"},
+  {"key":"branding.app_name",      "type":"string", "default":null, "description":"Name shown instead of the product name (falls back to tenants.name)"},
+  {"key":"units.selector_enabled", "type":"boolean","default":true, "description":"Show the unit selector to members with more than one unit"}
+]'::jsonb);
+
+-- ── helpers ─────────────────────────────────────────────────────────────
+-- jsonb_set that creates the intermediate objects of a dotted path.
+CREATE OR REPLACE FUNCTION app.jsonb_set_path(p_doc jsonb, p_path text[], p_value jsonb)
+RETURNS jsonb LANGUAGE plpgsql IMMUTABLE SET search_path = '' AS $$
+DECLARE
+  v_head text := p_path[1];
+  v_rest text[] := p_path[2:];
+  v_doc jsonb := CASE WHEN jsonb_typeof(p_doc) = 'object' THEN p_doc ELSE '{}'::jsonb END;
+BEGIN
+  IF cardinality(p_path) = 0 THEN
+    RETURN p_value;
+  END IF;
+  IF cardinality(v_rest) = 0 THEN
+    IF p_value IS NULL OR jsonb_typeof(p_value) = 'null' THEN
+      RETURN v_doc - v_head;
+    END IF;
+    RETURN jsonb_set(v_doc, ARRAY[v_head], p_value, true);
+  END IF;
+  RETURN jsonb_set(v_doc, ARRAY[v_head], app.jsonb_set_path(v_doc -> v_head, v_rest, p_value), true);
+END $$;
+REVOKE ALL ON FUNCTION app.jsonb_set_path(jsonb, text[], jsonb) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.jsonb_set_path(jsonb, text[], jsonb) TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION app.setting_type_ok(p_type text, p_value jsonb)
+RETURNS boolean LANGUAGE sql IMMUTABLE SET search_path = '' AS $$
+  SELECT CASE
+    WHEN p_value IS NULL OR jsonb_typeof(p_value) = 'null' THEN true
+    WHEN p_type = 'integer' THEN jsonb_typeof(p_value) = 'number' AND (p_value #>> '{}') ~ '^-?[0-9]+$'
+    WHEN p_type = 'number'  THEN jsonb_typeof(p_value) = 'number'
+    ELSE jsonb_typeof(p_value) = p_type
+  END;
+$$;
+REVOKE ALL ON FUNCTION app.setting_type_ok(text, jsonb) FROM public, anon;
+GRANT EXECUTE ON FUNCTION app.setting_type_ok(text, jsonb) TO authenticated, service_role;
+
+-- effective value of one key for one tenant (internal; no permission check)
+CREATE OR REPLACE FUNCTION app.tenant_setting_value(p_tenant uuid, p_key text)
+RETURNS jsonb LANGUAGE sql STABLE SECURITY DEFINER SET search_path = '' AS $$
+  SELECT coalesce(
+    (SELECT t.settings #> string_to_array(p_key, '.') FROM public.tenants t WHERE t.id = p_tenant),
+    (SELECT k.default_value FROM app.tenant_setting_keys k WHERE k.key = p_key)
+  );
+$$;
+REVOKE ALL ON FUNCTION app.tenant_setting_value(uuid, text) FROM public, anon, authenticated;
+
+-- ── RPCs ────────────────────────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION public.tenant_setting(p_key text)
+RETURNS jsonb LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'tenant_setting: no active tenant' USING ERRCODE = '42501';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM app.tenant_setting_keys k WHERE k.key = p_key) THEN
+    RAISE EXCEPTION 'tenant_setting: unknown key %', coalesce(p_key, '<null>') USING ERRCODE = '22023';
+  END IF;
+  RETURN app.tenant_setting_value(v_tenant, p_key);
+END $$;
+REVOKE ALL ON FUNCTION public.tenant_setting(text) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.tenant_setting(text) TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION public.tenant_settings()
+RETURNS jsonb LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'tenant_settings: no active tenant' USING ERRCODE = '42501';
+  END IF;
+  RETURN coalesce((SELECT jsonb_object_agg(k.key, app.tenant_setting_value(v_tenant, k.key)) FROM app.tenant_setting_keys k), '{}'::jsonb);
+END $$;
+REVOKE ALL ON FUNCTION public.tenant_settings() FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.tenant_settings() TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION public.tenant_setting_set(p_key text, p_value jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path = '' AS $$
+DECLARE
+  v_tenant uuid := app.current_tenant_id();
+  k record;
+BEGIN
+  IF v_tenant IS NULL OR auth.uid() IS NULL THEN
+    RAISE EXCEPTION 'tenant_setting_set: no session or no active tenant' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('settings.manage') THEN
+    RAISE EXCEPTION 'tenant_setting_set: settings.manage is required' USING ERRCODE = '42501';
+  END IF;
+  SELECT * INTO k FROM app.tenant_setting_keys x WHERE x.key = p_key;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'tenant_setting_set: unknown key %', coalesce(p_key, '<null>') USING ERRCODE = '22023';
+  END IF;
+  IF k.scope <> 'tenant' THEN
+    RAISE EXCEPTION 'tenant_setting_set: key % is unit-scoped', p_key USING ERRCODE = '22023';
+  END IF;
+  IF NOT app.setting_type_ok(k.type, p_value) THEN
+    RAISE EXCEPTION 'tenant_setting_set: key % expects %, got %', p_key, k.type, coalesce(jsonb_typeof(p_value), 'null') USING ERRCODE = '22023';
+  END IF;
+  UPDATE public.tenants t
+     SET settings = app.jsonb_set_path(coalesce(t.settings, '{}'::jsonb), string_to_array(p_key, '.'), p_value)
+   WHERE t.id = v_tenant;
+  RETURN app.tenant_setting_value(v_tenant, p_key);
+END $$;
+REVOKE ALL ON FUNCTION public.tenant_setting_set(text, jsonb) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.tenant_setting_set(text, jsonb) TO authenticated, service_role;
+
+-- ── branding: never raises ──────────────────────────────────────────────
+CREATE OR REPLACE FUNCTION app.branding_of(p_tenant uuid)
+RETURNS jsonb LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE t record; v jsonb;
+BEGIN
+  SELECT x.id, x.name, x.slug, x.logo_url, x.settings INTO t FROM public.tenants x WHERE x.id = p_tenant;
+  IF t.id IS NULL THEN
+    RETURN jsonb_build_object('tenant_id', NULL, 'name', NULL, 'slug', NULL, 'logo_url', NULL, 'primary_color', NULL, 'custom_domain', NULL);
+  END IF;
+  v := coalesce(t.settings, '{}'::jsonb);
+  RETURN jsonb_build_object(
+    'tenant_id', t.id,
+    'name', coalesce(nullif(v #>> '{branding,app_name}', ''), t.name),
+    'slug', t.slug,
+    'logo_url', coalesce(nullif(v #>> '{branding,logo_url}', ''), t.logo_url),
+    'primary_color', nullif(v #>> '{branding,primary_color}', ''),
+    'custom_domain', nullif(v #>> '{branding,custom_domain}', '')
+  );
+EXCEPTION WHEN OTHERS THEN
+  RETURN jsonb_build_object('tenant_id', p_tenant, 'name', NULL, 'slug', NULL, 'logo_url', NULL, 'primary_color', NULL, 'custom_domain', NULL,
+                            'error', 'branding unavailable');
+END $$;
+REVOKE ALL ON FUNCTION app.branding_of(uuid) FROM public, anon, authenticated;
+
+CREATE OR REPLACE FUNCTION public.tenant_branding()
+RETURNS jsonb LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+BEGIN
+  RETURN app.branding_of(app.current_tenant_id());
+EXCEPTION WHEN OTHERS THEN
+  RETURN jsonb_build_object('tenant_id', NULL, 'name', NULL, 'slug', NULL, 'logo_url', NULL, 'primary_color', NULL, 'custom_domain', NULL,
+                            'error', 'branding unavailable');
+END $$;
+REVOKE ALL ON FUNCTION public.tenant_branding() FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.tenant_branding() TO authenticated, service_role;
+
+-- The login page knows the slug (URL) or the host (custom domain) and nothing
+-- else: it may ask for the branding of that tenant, and only the branding.
+CREATE OR REPLACE FUNCTION public.tenant_branding_public(p_slug text DEFAULT NULL, p_domain text DEFAULT NULL)
+RETURNS jsonb LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = '' AS $$
+DECLARE v_tenant uuid;
+BEGIN
+  IF nullif(btrim(coalesce(p_slug, '')), '') IS NOT NULL THEN
+    SELECT t.id INTO v_tenant FROM public.tenants t WHERE t.slug = lower(btrim(p_slug));
+  ELSIF nullif(btrim(coalesce(p_domain, '')), '') IS NOT NULL THEN
+    SELECT t.id INTO v_tenant FROM public.tenants t
+     WHERE lower(t.settings #>> '{branding,custom_domain}') = lower(btrim(p_domain))
+     ORDER BY t.created_at LIMIT 1;
+  END IF;
+  RETURN app.branding_of(v_tenant) - 'error';
+EXCEPTION WHEN OTHERS THEN
+  RETURN jsonb_build_object('tenant_id', NULL, 'name', NULL, 'slug', NULL, 'logo_url', NULL, 'primary_color', NULL, 'custom_domain', NULL);
+END $$;
+REVOKE ALL ON FUNCTION public.tenant_branding_public(text, text) FROM public;
+GRANT EXECUTE ON FUNCTION public.tenant_branding_public(text, text) TO anon, authenticated, service_role;
+
+-- read view of the registry for the UI
+CREATE OR REPLACE VIEW public.v_tenant_setting_keys WITH (security_invoker = true) AS
+  SELECT key, type, default_value, description, reader, scope FROM app.tenant_setting_keys;
+GRANT SELECT ON public.v_tenant_setting_keys TO authenticated, service_role;