Sign-in by customer: realm petrolyst, row rules, guest role (PD-21)

Keycloak import for realm petrolyst: two clients, petrolyst with MFA for
Superset and Traefik, petrolyst-app password only. It lists only
app.petrolyst.com and traefik.petrolyst.com, and no customer names, as this
repository is public. public.v_operator shows each customer's group. Dashboards
overview and site, role Petrolyst Guest, filtered by row. Superset refuses a
user with no mapped role. The realm travels with the release: each release's
compose files name their realm and secret file, and a rollback needs only its
target's secret. Not deployed.

Checks earlier on this content: tests/run.sh 109 of 109 and read-only, dashboards
import twice, column drift 0, compose config on old and new trees, the secret
check on a scratch folder, a rehearsal on a throwaway Keycloak 26.4. Never a real
deploy or rollback; shellcheck not installed today, clean when last run. Codex
inspected once; its fixes are not re-inspected, on the owner's word.

Bands: persistence, Superset. Rules: 1, 2, 3, 6, 14.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

stacks/fuel-monitoring/fuel-db/migrations/0001_fm_core.sql

@@ -18,7 +18,9 @@ CREATE TABLE fm.operator (
   name              text NOT NULL,
   label_issuer      text NOT NULL,                 -- whose labels this customer's people see (holder_alias.issuer)
   programme         text NOT NULL,                 -- the programme v_site reports (participation.programme)
-  timezone          text NOT NULL                  -- for a holder with no place, or a place without its own
+  timezone          text NOT NULL,                 -- for a holder with no place, or a place without its own
+  keycloak_group    text NOT NULL UNIQUE           -- the top-level Keycloak group of this customer's people (PD-21)
+                    CHECK (keycloak_group ~ '^/[^/]+$')
 );
 
 -- Provenance ------------------------------------------------------------------------------

stacks/fuel-monitoring/fuel-db/migrations/0003_bi_views.sql

@@ -631,4 +631,9 @@ SELECT s.site_uid, s.site_code, s.site_name, s.site_label, s.operator_uid,
 FROM fm.imported_calculation c JOIN public.v_site s ON s.site_uid = c.holder_uid
 WHERE c.claim_status IN ('asserted','reviewed','disputed');
 
+-- Which Keycloak group is which customer (PD-21). Only server/ reads this, at sign-in; it holds no
+-- site data, and no dashboard has a dataset on it.
+CREATE VIEW public.v_operator AS
+SELECT operator_uid, name, keycloak_group FROM fm.operator;
+
 COMMIT;

stacks/fuel-monitoring/fuel-db/migrations/README.md

@@ -14,7 +14,7 @@ The design and its rationale live in the fuel-monitoring corpus:
 |---|---|---|
 | `0001_fm_core.sql` | schema `fm`, `btree_gist` in it, 29 tables (customers, assets, places and holders, claims, reviews, baselines), constraints, trigger-backed rules 1–15 | no |
 | `0002_fm_derivations.sql` | internal views in `fm`: claims → visits → stock intervals → L/h and L/day intervals, dependency hashes, baseline validity | no |
-| `0003_bi_views.sql` | `fm.v_site_baseline_status` and the 18 `public.v_*` views Superset reads | yes, read-only |
+| `0003_bi_views.sql` | `fm.v_site_baseline_status` and the 19 `public.v_*` views Superset reads | yes, read-only |
 | `0004_licence.sql` | schema `licence`: plans, prices, entitlements, customer licences, overrides and their change log (PD-19, PD-20). Holds no customer's licence | no |
 
 Each file is one transaction. Apply them in order.
@@ -51,7 +51,7 @@ point 8, closed 30 Oct 2026).
 
 3. Check as `fuel_ro`
    (`docker exec -it petrolyst-fuel-db-1 psql -U postgres -d fuel`, then `SET ROLE fuel_ro;`):
-   - `\dv public.*` lists the 18 `v_*` views;
+   - `\dv public.*` lists the 19 `v_*` views;
    - `SELECT count(*) FROM fm.holder;` fails with "permission denied for schema fm";
    - `SELECT count(*) FROM licence.plan;` fails with "permission denied for schema licence".
 

stacks/fuel-monitoring/fuel-db/tests/read_only.sql

@@ -7,15 +7,15 @@ BEGIN
   FOREACH v IN ARRAY ARRAY['v_site','v_kpi_measures','v_hour_meter_evidence','v_assumption','v_baseline_version',
                            'v_baseline_input','v_evidence','v_delivery','v_stock_reading','v_interval','v_runtime',
                            'v_coverage','v_reconciliation','v_data_quality','v_spec_reference','v_modelled_lph',
-                           'v_electricity_cost','v_imported_calculation'] LOOP
+                           'v_electricity_cost','v_imported_calculation','v_operator'] LOOP
     EXECUTE format('SELECT count(*) FROM public.%I', v);
     SELECT EXISTS (SELECT 1 FROM information_schema.columns c
                    WHERE c.table_schema = 'public' AND c.table_name = v AND c.column_name = 'operator_uid') INTO has;
     IF NOT has THEN RAISE EXCEPTION '% has no operator_uid', v; END IF;
     n := n + 1;
   END LOOP;
-  IF n <> 18 THEN RAISE EXCEPTION 'expected 18 views, checked %', n; END IF;
-  IF (SELECT count(*) FROM information_schema.views WHERE table_schema = 'public' AND table_name LIKE 'v\_%') <> 18 THEN
+  IF n <> 19 THEN RAISE EXCEPTION 'expected 19 views, checked %', n; END IF;
+  IF (SELECT count(*) FROM information_schema.views WHERE table_schema = 'public' AND table_name LIKE 'v\_%') <> 19 THEN
     RAISE EXCEPTION 'public holds a view this list does not name';
   END IF;
 
@@ -32,5 +32,5 @@ BEGIN
     RAISE EXCEPTION USING ERRCODE = 'TT001', MESSAGE = 'fuel_ro created a table';
   EXCEPTION WHEN insufficient_privilege OR read_only_sql_transaction THEN NULL;
   END;
-  RAISE NOTICE 'read-only role: 18 views readable, each with operator_uid; fm and licence refused; writes refused';
+  RAISE NOTICE 'read-only role: 19 views readable, each with operator_uid; fm and licence refused; writes refused';
 END $$;

stacks/fuel-monitoring/fuel-db/tests/rules.sql

@@ -52,9 +52,9 @@ CREATE FUNCTION rules_test.sha(c text) RETURNS text LANGUAGE sql IMMUTABLE AS
   $$ SELECT repeat(c, 64) $$;
 
 -- Two customers ------------------------------------------------------------------------------
-INSERT INTO fm.operator (operator_uid, name, label_issuer, programme, timezone) VALUES
-  ('OPR-0001', 'Customer A', 'Issuer A', 'Programme A', 'Asia/Kabul'),
-  ('OPR-0002', 'Customer B', 'Issuer B', 'Programme B', 'Europe/Berlin');
+INSERT INTO fm.operator (operator_uid, name, label_issuer, programme, timezone, keycloak_group) VALUES
+  ('OPR-0001', 'Customer A', 'Issuer A', 'Programme A', 'Asia/Kabul', '/customer-a'),
+  ('OPR-0002', 'Customer B', 'Issuer B', 'Programme B', 'Europe/Berlin', '/customer-b');
 INSERT INTO fm.source_document (sha256, operator_uid, source_family, kind, issuer, title, corpus_path, contains_personal_data) VALUES
   (rules_test.sha('a'), 'OPR-0001', 'family-a', 'operator_workbook', 'Issuer A', 'workbook A', 'a.xlsx', false),
   (rules_test.sha('b'), 'OPR-0002', 'family-b', 'operator_workbook', 'Issuer B', 'workbook B', 'b.xlsx', false);
@@ -102,6 +102,11 @@ SELECT 'stock:' || k, rules_test.sha('d'), 'OPR-0001', rules_test.visit(k), 'SIT
 FROM (VALUES ('SITE-0001:2026-01-01:1', 100.0), ('SITE-0001:2026-01-11:1', 50.0)) x(k, l);
 
 SELECT rules_test.ok('fixture holds two customers', 'SELECT 1');
+SELECT rules_test.no('customers: one Keycloak group is one customer', 'duplicate key',
+  'UPDATE fm.operator SET keycloak_group = ''/customer-a'' WHERE operator_uid = ''OPR-0002''');
+SELECT rules_test.no('customers: the group is a top-level one', 'keycloak_group_check',
+  'UPDATE fm.operator SET keycloak_group = ''/customer-a/team'' WHERE operator_uid = ''OPR-0001''');
+SELECT rules_test.eq('customers: v_operator gives the group', 'SELECT operator_uid FROM public.v_operator WHERE keycloak_group = ''/customer-b''', 'OPR-0002');
 
 -- Rule 1: baseline versions --------------------------------------------------------------------
 \set bv 'INSERT INTO fm.baseline_version (code, operator_uid, holder_uid, metric, population, population_key, window_start, window_end, policy_version, meets_policy, computed_at, computed_by_role'