From 354e3dac50f9f9ce48fdacdf929019e0ac5c0534 Mon Sep 17 00:00:00 2001 From: Cameron Reeves Date: Tue, 18 Aug 2026 16:57:30 +1000 Subject: [PATCH 01/23] feat: PPT-526 add Partner->Client hierarchy and client ownership columns The first persisted layer of the Integrator/Partner -> Client -> Domain hierarchy: - partners (uuidv7; management flag for the platform operator's own org; nullable self-parent reserving a 2-tier channel) and clients (nullable partner_id, NULL = client-owned; payer flag records who is invoiced, partner-pays default). All delete paths RESTRICT - teardown must be orchestrated, never a silent DB cascade. - authority.client_id plus client_id on zone/sys/mod/trigger/edge/broker (nullable; ownership ground truth for the query enforcement that follows). mass_assignment: false everywhere - ownership is not writable via untrusted payloads. - authority.domain gains a real UNIQUE index (self-signup depends on it), preceded by a quarantine step that renames legacy duplicate domains so the index always builds. - dormant partial UNIQUE (client_id, name) indexes on zone/sys/edge/broker, activated per-row as ownership is assigned. - idempotent backfill: management partner, one client-owned Client per authority, estate inference via org_zone resolved per zone TREE (contested or subtree-only claims left NULL for a human), collision-safe against the new unique indexes. Verified: full spec suite green (660 examples; the one error is the known flaky user_spec concurrency test, passes in isolation); backfill exercised against realistic + adversarial fixtures via tasks/PPT-526/backfill-verify.sh (24 assertions incl. duplicate names, contested trees, operator-created partner rows, domain quarantine); ameba clean. --- ...0818100500000_add_partners_and_clients.sql | 211 +++++++++++++++++ ...818100600000_backfill_client_ownership.sql | 222 ++++++++++++++++++ spec/client_spec.cr | 104 ++++++++ spec/generator.cr | 16 ++ spec/helper.cr | 2 + spec/partner_spec.cr | 70 ++++++ src/placeos-models/authority.cr | 9 + src/placeos-models/broker.cr | 10 + src/placeos-models/client.cr | 71 ++++++ src/placeos-models/control_system.cr | 9 + src/placeos-models/edge.cr | 9 + src/placeos-models/module.cr | 11 + src/placeos-models/partner.cr | 72 ++++++ src/placeos-models/trigger.cr | 10 + src/placeos-models/zone.cr | 9 + 15 files changed, 835 insertions(+) create mode 100644 migration/db/migrations/20260818100500000_add_partners_and_clients.sql create mode 100644 migration/db/migrations/20260818100600000_backfill_client_ownership.sql create mode 100644 spec/client_spec.cr create mode 100644 spec/partner_spec.cr create mode 100644 src/placeos-models/client.cr create mode 100644 src/placeos-models/partner.cr diff --git a/migration/db/migrations/20260818100500000_add_partners_and_clients.sql b/migration/db/migrations/20260818100500000_add_partners_and_clients.sql new file mode 100644 index 00000000..59478ca6 --- /dev/null +++ b/migration/db/migrations/20260818100500000_add_partners_and_clients.sql @@ -0,0 +1,211 @@ +-- +micrate Up +-- SQL in section 'Up' is executed when this migration is applied + +-- MERGE-TIME CHECK: micrate refuses out-of-order version ids (see models#323). +-- If any later-dated migration lands on master before this merges, renumber +-- this file AND 20260818100600000 above it (preserving schema-before-backfill +-- order). Safe: neither has been applied anywhere and the backfill is +-- idempotent. + +-- --------------------------------------------------------------------------- +-- PPT-526: the Partner → Client → Authority(domain) hierarchy. +-- +-- partners: integrators/resellers (e.g. NTT). `management = true` marks the +-- platform operator's own organisation (PlaceOS staff) — the "management +-- client" concept from the ticket, done at the partner level. `parent_id` +-- reserves a 2-tier channel (distributor → reseller) without any UI or +-- enforcement yet. +-- +-- clients: the customer organisation (e.g. UCLA, Acadian). `partner_id` NULL +-- means client-owned (self-managed, no integrator). `payer` records who is +-- invoiced: 'partner' (integrator pays us and re-bills, the default channel +-- model) or 'client' (direct). A client without a partner can only pay for +-- itself — enforced by CHECK. +-- +-- Every delete path is RESTRICT: removing a partner/client must go through an +-- orchestrated teardown (the PPT-1203 pattern), never a silent DB cascade — +-- model-level cleanup callbacks do not fire on DB cascades. +-- --------------------------------------------------------------------------- +CREATE TABLE IF NOT EXISTS "partners"( + id UUID PRIMARY KEY DEFAULT uuidv7(), + name TEXT NOT NULL, + description TEXT NOT NULL DEFAULT '', + management BOOLEAN NOT NULL DEFAULT false, + parent_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, + config JSONB NOT NULL DEFAULT '{}', + created_at TIMESTAMPTZ NOT NULL, + updated_at TIMESTAMPTZ NOT NULL +); + +CREATE UNIQUE INDEX IF NOT EXISTS partners_name_unique + ON "partners" USING BTREE (name); +CREATE INDEX IF NOT EXISTS partners_parent_id_index + ON "partners" USING BTREE (parent_id); + +CREATE TABLE IF NOT EXISTS "clients"( + id UUID PRIMARY KEY DEFAULT uuidv7(), + name TEXT NOT NULL, + description TEXT NOT NULL DEFAULT '', + partner_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, + payer TEXT NOT NULL DEFAULT 'partner' + CHECK (payer IN ('partner', 'client')), + config JSONB NOT NULL DEFAULT '{}', + created_at TIMESTAMPTZ NOT NULL, + updated_at TIMESTAMPTZ NOT NULL, + CONSTRAINT clients_payer_requires_partner + CHECK (partner_id IS NOT NULL OR payer = 'client') +); + +-- Client names are unique within a partner's book of business, and unique +-- among client-owned clients. Two partial indexes because UNIQUE treats +-- NULLs as distinct — a plain UNIQUE (partner_id, name) would let every +-- client-owned client share a name. +CREATE UNIQUE INDEX IF NOT EXISTS clients_name_unique_per_partner + ON "clients" USING BTREE (partner_id, name) WHERE partner_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS clients_name_unique_owned + ON "clients" USING BTREE (name) WHERE partner_id IS NULL; +CREATE INDEX IF NOT EXISTS clients_partner_id_index + ON "clients" USING BTREE (partner_id); + +-- --------------------------------------------------------------------------- +-- Authority → Client ownership. Nullable at the DB level for backwards +-- compatibility (init seeds authorities before any client exists); the +-- provisioning flow and backfill populate it. RESTRICT so a client cannot be +-- deleted while it still owns domains. +-- --------------------------------------------------------------------------- +ALTER TABLE "authority" + ADD COLUMN IF NOT EXISTS client_id UUID; + +ALTER TABLE ONLY "authority" + DROP CONSTRAINT IF EXISTS authority_client_id_fkey; +ALTER TABLE ONLY "authority" + ADD CONSTRAINT authority_client_id_fkey + FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; + +CREATE INDEX IF NOT EXISTS authority_client_id_index + ON "authority" USING BTREE (client_id); + +-- The domain column has only ever had model-level uniqueness (a plain BTREE +-- index) — a concurrent-signup race can create duplicate authorities. Make it +-- a hard guarantee; self-service signup depends on it. +-- +-- Quarantine first: exact-duplicate domains left behind by that race would +-- make the unique index unbuildable and (because micrate autocommits each +-- statement) leave this migration half-applied. Keep the oldest row per +-- domain and rename the rest so they stop answering for the domain — +-- find_by_domain picks an arbitrary row across duplicates today, so this +-- cannot break a reliably-working login. Idempotent: renamed rows no longer +-- collide. Renamed rows are for an operator to merge or delete. +UPDATE "authority" a +SET domain = a.domain || '.duplicate.' || a.id +WHERE EXISTS ( + SELECT 1 FROM "authority" b + WHERE b.domain = a.domain + AND (b.created_at, b.id) < (a.created_at, a.id) +); + +CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique + ON "authority" USING BTREE (domain); + +-- --------------------------------------------------------------------------- +-- Client ownership columns on the (previously cluster-global) control plane. +-- Nullable: populated by the backfill migration where inference is +-- unambiguous, and by the provisioning flow for everything new. Query-path +-- enforcement is phased in separately (rest-api); these columns are the +-- ground truth it will filter on. +-- --------------------------------------------------------------------------- +ALTER TABLE "zone" ADD COLUMN IF NOT EXISTS client_id UUID; +ALTER TABLE "sys" ADD COLUMN IF NOT EXISTS client_id UUID; +ALTER TABLE "mod" ADD COLUMN IF NOT EXISTS client_id UUID; +ALTER TABLE "trigger" ADD COLUMN IF NOT EXISTS client_id UUID; +ALTER TABLE "edge" ADD COLUMN IF NOT EXISTS client_id UUID; +ALTER TABLE "broker" ADD COLUMN IF NOT EXISTS client_id UUID; + +ALTER TABLE ONLY "zone" + DROP CONSTRAINT IF EXISTS zone_client_id_fkey; +ALTER TABLE ONLY "zone" + ADD CONSTRAINT zone_client_id_fkey + FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "sys" + DROP CONSTRAINT IF EXISTS sys_client_id_fkey; +ALTER TABLE ONLY "sys" + ADD CONSTRAINT sys_client_id_fkey + FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "mod" + DROP CONSTRAINT IF EXISTS mod_client_id_fkey; +ALTER TABLE ONLY "mod" + ADD CONSTRAINT mod_client_id_fkey + FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "trigger" + DROP CONSTRAINT IF EXISTS trigger_client_id_fkey; +ALTER TABLE ONLY "trigger" + ADD CONSTRAINT trigger_client_id_fkey + FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "edge" + DROP CONSTRAINT IF EXISTS edge_client_id_fkey; +ALTER TABLE ONLY "edge" + ADD CONSTRAINT edge_client_id_fkey + FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "broker" + DROP CONSTRAINT IF EXISTS broker_client_id_fkey; +ALTER TABLE ONLY "broker" + ADD CONSTRAINT broker_client_id_fkey + FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; + +CREATE INDEX IF NOT EXISTS zone_client_id_index ON "zone" USING BTREE (client_id); +CREATE INDEX IF NOT EXISTS sys_client_id_index ON "sys" USING BTREE (client_id); +CREATE INDEX IF NOT EXISTS mod_client_id_index ON "mod" USING BTREE (client_id); +CREATE INDEX IF NOT EXISTS trigger_client_id_index ON "trigger" USING BTREE (client_id); +CREATE INDEX IF NOT EXISTS edge_client_id_index ON "edge" USING BTREE (client_id); +CREATE INDEX IF NOT EXISTS broker_client_id_index ON "broker" USING BTREE (client_id); + +-- Per-client name uniqueness for the estate. Dormant while client_id is NULL +-- (UNIQUE treats NULLs as distinct) and strictly weaker than the current +-- model-level global uniqueness, so it cannot conflict with existing data. +-- When query enforcement lands, the model-level checks flip from global to +-- client-scoped and these indexes become the hard guarantee. +CREATE UNIQUE INDEX IF NOT EXISTS zone_client_id_name_unique + ON "zone" USING BTREE (client_id, name) WHERE client_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS sys_client_id_name_unique + ON "sys" USING BTREE (client_id, name) WHERE client_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS edge_client_id_name_unique + ON "edge" USING BTREE (client_id, name) WHERE client_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS broker_client_id_name_unique + ON "broker" USING BTREE (client_id, name) WHERE client_id IS NOT NULL; + +-- +micrate Down +-- SQL section 'Down' is executed when this migration is rolled back + +DROP INDEX IF EXISTS broker_client_id_name_unique; +DROP INDEX IF EXISTS edge_client_id_name_unique; +DROP INDEX IF EXISTS sys_client_id_name_unique; +DROP INDEX IF EXISTS zone_client_id_name_unique; + +DROP INDEX IF EXISTS broker_client_id_index; +DROP INDEX IF EXISTS edge_client_id_index; +DROP INDEX IF EXISTS trigger_client_id_index; +DROP INDEX IF EXISTS mod_client_id_index; +DROP INDEX IF EXISTS sys_client_id_index; +DROP INDEX IF EXISTS zone_client_id_index; + +ALTER TABLE ONLY "broker" DROP CONSTRAINT IF EXISTS broker_client_id_fkey; +ALTER TABLE ONLY "edge" DROP CONSTRAINT IF EXISTS edge_client_id_fkey; +ALTER TABLE ONLY "trigger" DROP CONSTRAINT IF EXISTS trigger_client_id_fkey; +ALTER TABLE ONLY "mod" DROP CONSTRAINT IF EXISTS mod_client_id_fkey; +ALTER TABLE ONLY "sys" DROP CONSTRAINT IF EXISTS sys_client_id_fkey; +ALTER TABLE ONLY "zone" DROP CONSTRAINT IF EXISTS zone_client_id_fkey; + +ALTER TABLE "broker" DROP COLUMN IF EXISTS client_id; +ALTER TABLE "edge" DROP COLUMN IF EXISTS client_id; +ALTER TABLE "trigger" DROP COLUMN IF EXISTS client_id; +ALTER TABLE "mod" DROP COLUMN IF EXISTS client_id; +ALTER TABLE "sys" DROP COLUMN IF EXISTS client_id; +ALTER TABLE "zone" DROP COLUMN IF EXISTS client_id; + +DROP INDEX IF EXISTS authority_domain_unique; +DROP INDEX IF EXISTS authority_client_id_index; +ALTER TABLE ONLY "authority" DROP CONSTRAINT IF EXISTS authority_client_id_fkey; +ALTER TABLE "authority" DROP COLUMN IF EXISTS client_id; + +DROP TABLE IF EXISTS "clients"; +DROP TABLE IF EXISTS "partners"; diff --git a/migration/db/migrations/20260818100600000_backfill_client_ownership.sql b/migration/db/migrations/20260818100600000_backfill_client_ownership.sql new file mode 100644 index 00000000..f26b266b --- /dev/null +++ b/migration/db/migrations/20260818100600000_backfill_client_ownership.sql @@ -0,0 +1,222 @@ +-- +micrate Up +-- SQL in section 'Up' is executed when this migration is applied + +-- --------------------------------------------------------------------------- +-- PPT-526: backfill Partner/Client ownership for existing data. +-- +-- Idempotent and additive: every statement only creates missing rows or fills +-- NULL client_id columns, so it is safe to re-apply and safe on databases +-- where operators have already assigned ownership by hand. Where inference is +-- ambiguous the row is deliberately LEFT NULL for a human to resolve (the +-- org_zone convention is known to be non-exclusive and sometimes absent). +-- +-- What it does: +-- 1. Ensures a management partner exists ("PlaceOS" — the platform +-- operator's own organisation). +-- 2. Creates one client-owned Client per Authority that has none, named +-- " ()" (domain uniqueness makes this collision +-- free), and points the authority at it. Estates that span several +-- authorities under one real-world client (e.g. NTT's two domains) are +-- merged later by re-pointing authority.client_id by hand or API. +-- 3. Zones: a zone belongs to the client of the authority whose +-- config->>'org_zone' names the zone's ROOT zone — only when exactly one +-- client is implied (shared org zones stay NULL). +-- 4. Systems: the single distinct client of their zones, if unambiguous. +-- 5. Modules: logic modules via their control system; shared device/service +-- modules via the systems that reference them, if unambiguous. +-- 6. Trigger definitions: via their control system when system-scoped; +-- unscoped trigger definitions stay NULL (shared library semantics). +-- 7. Edges: via their bound user's authority. +-- Brokers are deliberately NOT backfilled (cluster-level MQTT infra). +-- --------------------------------------------------------------------------- + +-- 1. Management partner. ON CONFLICT: if an operator already created a +-- non-management partner named 'PlaceOS', leave it for a human rather +-- than promote it (this file only creates missing rows / fills NULLs). +INSERT INTO "partners" (name, description, management, created_at, updated_at) +SELECT 'PlaceOS', 'Platform operator (management partner)', true, now(), now() +WHERE NOT EXISTS (SELECT 1 FROM "partners" WHERE management = true) +ON CONFLICT DO NOTHING; + +-- 2. One client-owned Client per orphan Authority +-- +micrate StatementBegin +DO $$ +DECLARE + auth RECORD; + new_client UUID; +BEGIN + FOR auth IN SELECT id, name, domain FROM "authority" WHERE client_id IS NULL LOOP + new_client := NULL; + INSERT INTO "clients" (name, description, partner_id, payer, created_at, updated_at) + VALUES ( + COALESCE(NULLIF(auth.name, ''), auth.domain) || ' (' || auth.domain || ')', + 'Auto-created from authority ' || auth.id || ' during PPT-526 client backfill', + NULL, 'client', now(), now() + ) + ON CONFLICT DO NOTHING + RETURNING id INTO new_client; + + -- If the name already existed (re-run against a partially-backfilled DB), + -- reuse the existing row rather than leaving the authority orphaned. + IF new_client IS NULL THEN + SELECT id INTO new_client FROM "clients" + WHERE partner_id IS NULL + AND name = COALESCE(NULLIF(auth.name, ''), auth.domain) || ' (' || auth.domain || ')'; + END IF; + + IF new_client IS NOT NULL THEN + UPDATE "authority" SET client_id = new_client WHERE id = auth.id; + END IF; + END LOOP; +END $$; +-- +micrate StatementEnd + +-- 3. Zones via org_zone → root-zone walk (unambiguous owners only). +-- UNION (not UNION ALL) so accidental cycles in zone parentage terminate. +-- Ambiguity is judged per TREE, not per org_zone string: every authority's +-- org_zone claim is resolved to its tree root, a tree claimed by more than +-- one distinct client is vetoed, and ownership is only assigned when at +-- least one claim names the root itself (a claim on a sub-zone alone must +-- not annex the whole tree). Rows whose (client_id, name) would collide +-- with the partial unique indexes are skipped (left NULL for a human) — +-- duplicate names within one estate are legacy race artifacts. +-- +micrate StatementBegin +WITH RECURSIVE zone_roots AS ( + SELECT id, id AS root_id + FROM "zone" + WHERE parent_id IS NULL OR parent_id = '' + UNION + SELECT z.id, r.root_id + FROM "zone" z + INNER JOIN zone_roots r ON z.parent_id = r.id +), +tree_claims AS ( + SELECT r.root_id, + (a.config->>'org_zone' = r.root_id) AS names_root, + a.client_id + FROM "authority" a + INNER JOIN zone_roots r ON r.id = a.config->>'org_zone' + WHERE COALESCE(a.config->>'org_zone', '') <> '' + AND a.client_id IS NOT NULL +), +org_owner AS ( + SELECT root_id, MIN(client_id::text)::uuid AS client_id + FROM tree_claims + GROUP BY root_id + HAVING COUNT(DISTINCT client_id) = 1 + AND bool_or(names_root) +), +candidates AS ( + SELECT z.id, o.client_id, z.name, + ROW_NUMBER() OVER ( + PARTITION BY o.client_id, z.name + ORDER BY z.created_at, z.id + ) AS rn + FROM "zone" z + INNER JOIN zone_roots r ON z.id = r.id + INNER JOIN org_owner o ON r.root_id = o.root_id + WHERE z.client_id IS NULL +) +UPDATE "zone" z +SET client_id = c.client_id +FROM candidates c +WHERE z.id = c.id + AND c.rn = 1 + AND NOT EXISTS ( + SELECT 1 FROM "zone" x + WHERE x.client_id = c.client_id AND x.name = z.name AND x.id <> z.id + ); +-- +micrate StatementEnd + +-- 4. Systems: single distinct client across their zones. Same collision +-- skip as zones (sys carries a (client_id, name) partial unique index). +-- +micrate StatementBegin +WITH sys_candidates AS ( + SELECT s2.id AS sys_id, s2.name, + MIN(z.client_id::text)::uuid AS client_id + FROM "sys" s2 + INNER JOIN "zone" z ON z.id = ANY(s2.zones) + WHERE z.client_id IS NOT NULL + AND s2.client_id IS NULL + GROUP BY s2.id, s2.name + HAVING COUNT(DISTINCT z.client_id) = 1 +), +ranked AS ( + SELECT sys_id, name, client_id, + ROW_NUMBER() OVER ( + PARTITION BY client_id, name + ORDER BY sys_id + ) AS rn + FROM sys_candidates +) +UPDATE "sys" s +SET client_id = r.client_id +FROM ranked r +WHERE s.id = r.sys_id + AND r.rn = 1 + AND NOT EXISTS ( + SELECT 1 FROM "sys" x + WHERE x.client_id = r.client_id AND x.name = s.name AND x.id <> s.id + ); +-- +micrate StatementEnd + +-- 5a. Logic modules via their control system +UPDATE "mod" m +SET client_id = s.client_id +FROM "sys" s +WHERE m.control_system_id = s.id + AND s.client_id IS NOT NULL + AND m.client_id IS NULL; + +-- 5b. Device/service modules via the systems that reference them +UPDATE "mod" m +SET client_id = sc.client_id +FROM ( + SELECT m2.id AS mod_id, MIN(s.client_id::text)::uuid AS client_id + FROM "mod" m2 + INNER JOIN "sys" s ON m2.id = ANY(s.modules) + WHERE s.client_id IS NOT NULL + GROUP BY m2.id + HAVING COUNT(DISTINCT s.client_id) = 1 +) sc +WHERE m.id = sc.mod_id AND m.client_id IS NULL; + +-- 6. System-scoped trigger definitions +UPDATE "trigger" t +SET client_id = s.client_id +FROM "sys" s +WHERE t.control_system_id = s.id + AND s.client_id IS NOT NULL + AND t.client_id IS NULL; + +-- 7. Edges via their bound user's authority. Same collision skip (edge +-- carries a (client_id, name) partial unique index). +-- +micrate StatementBegin +WITH edge_candidates AS ( + SELECT e.id, e.name, a.client_id, + ROW_NUMBER() OVER ( + PARTITION BY a.client_id, e.name + ORDER BY e.id + ) AS rn + FROM "edge" e + INNER JOIN "user" u ON e.user_id = u.id + INNER JOIN "authority" a ON u.authority_id = a.id + WHERE a.client_id IS NOT NULL + AND e.client_id IS NULL +) +UPDATE "edge" e +SET client_id = c.client_id +FROM edge_candidates c +WHERE e.id = c.id + AND c.rn = 1 + AND NOT EXISTS ( + SELECT 1 FROM "edge" x + WHERE x.client_id = c.client_id AND x.name = e.name AND x.id <> e.id + ); +-- +micrate StatementEnd + +-- +micrate Down +-- Deliberate no-op: the backfill only fills NULLs and creates rows that +-- operators may since have adopted; unwinding it automatically could destroy +-- hand-made ownership assignments. Rolling back the schema migration +-- (20260818100500000) removes the columns and tables wholesale. diff --git a/spec/client_spec.cr b/spec/client_spec.cr new file mode 100644 index 00000000..e0f8bb36 --- /dev/null +++ b/spec/client_spec.cr @@ -0,0 +1,104 @@ +require "./helper" + +module PlaceOS::Model + describe Client do + Spec.before_each do + ControlSystem.clear + Zone.clear + Authority.clear + Client.clear + Partner.clear + end + + it "saves a partnered client with partner-pays default" do + partner = Generator.partner.save! + client = Generator.client(partner: partner).save! + client.persisted?.should be_true + client.payer.should eq Client::PAYER_PARTNER + client.client_owned?.should be_false + client.partner.try(&.id).should eq partner.id + end + + it "normalizes a client-owned client to pay for itself" do + client = Generator.client.save! + client.partner_id.should be_nil + client.payer.should eq Client::PAYER_CLIENT + client.client_owned?.should be_true + end + + it "rejects an unknown payer" do + client = Generator.client(partner: Generator.partner.save!, payer: "nobody") + client.valid?.should be_false + client.errors.map(&.field).should contain(:payer) + end + + it "scopes client name uniqueness to the partner" do + partner_a = Generator.partner.save! + partner_b = Generator.partner.save! + original = Generator.client(partner: partner_a).save! + + # Same name under a different partner is fine + sibling = Generator.client(partner: partner_b) + sibling.name = original.name + sibling.valid?.should be_true + + # Same name under the same partner is not + duplicate = Generator.client(partner: partner_a) + duplicate.name = original.name + duplicate.valid?.should be_false + duplicate.errors.map(&.field).should contain(:name) + end + + it "rejects duplicate names among client-owned clients" do + original = Generator.client.save! + duplicate = Generator.client + duplicate.name = original.name + duplicate.valid?.should be_false + duplicate.errors.map(&.field).should contain(:name) + end + + it "owns authorities via authority.client_id" do + client = Generator.client.save! + authority = Generator.authority(domain: "client-spec.example.com") + authority.client_id = client.id + authority.save! + + authority.client.try(&.id).should eq client.id + client.authorities.to_a.map(&.id).should eq [authority.id] + end + + it "refuses to delete a client that still owns a domain" do + client = Generator.client.save! + authority = Generator.authority(domain: "client-restrict.example.com") + authority.client_id = client.id + authority.save! + + expect_raises(Exception, /foreign key/) { client.destroy } + Client.find?(client.id.not_nil!).should_not be_nil + end + + it "rejects renaming a client onto a sibling's name" do + partner = Generator.partner.save! + original = Generator.client(partner: partner).save! + sibling = Generator.client(partner: partner).save! + + sibling.name = original.name + sibling.valid?.should be_false + sibling.errors.map(&.field).should contain(:name) + end + + it "records client ownership on zones and systems" do + client = Generator.client.save! + zone = Generator.zone + zone.client_id = client.id + zone.save! + + sys = Generator.control_system + sys.client_id = client.id + sys.save! + + Zone.find!(zone.id.not_nil!).client.try(&.id).should eq client.id + ControlSystem.find!(sys.id.not_nil!).client.try(&.id).should eq client.id + end + end +end diff --git a/spec/generator.cr b/spec/generator.cr index fb81f068..c748be59 100644 --- a/spec/generator.cr +++ b/spec/generator.cr @@ -566,6 +566,22 @@ module PlaceOS::Model ) end + def self.partner(management : Bool = false, parent : Partner? = nil) + Partner.new( + name: Faker::Hacker.noun + "-" + RANDOM.hex(3), + management: management, + parent_id: parent.try(&.id), + ) + end + + def self.client(partner : Partner? = nil, payer : String = Client::PAYER_PARTNER) + Client.new( + name: Faker::Hacker.noun + "-" + RANDOM.hex(3), + partner_id: partner.try(&.id), + payer: payer, + ) + end + def self.user(authority : Authority? = nil, support : Bool = false, admin : Bool = false) unless authority # look up an existing authority diff --git a/spec/helper.cr b/spec/helper.cr index 4f7a6394..347d35d2 100644 --- a/spec/helper.cr +++ b/spec/helper.cr @@ -39,6 +39,8 @@ Spec.after_suite do PlaceOS::Model::GroupPlaylistItem, PlaceOS::Model::GroupPlaylist, PlaceOS::Model::Group, + PlaceOS::Model::Client, + PlaceOS::Model::Partner, ].each(&.clear) end diff --git a/spec/partner_spec.cr b/spec/partner_spec.cr new file mode 100644 index 00000000..914502e2 --- /dev/null +++ b/spec/partner_spec.cr @@ -0,0 +1,70 @@ +require "./helper" + +module PlaceOS::Model + describe Partner do + Spec.before_each do + ControlSystem.clear + Zone.clear + Authority.clear + Client.clear + Partner.clear + end + + it "saves a partner" do + partner = Generator.partner.save! + partner.persisted?.should be_true + partner.management.should be_false + partner.parent_id.should be_nil + end + + it "saves a management partner" do + partner = Generator.partner(management: true).save! + partner.management.should be_true + end + + it "rejects duplicate partner names" do + existing = Generator.partner.save! + duplicate = Generator.partner + duplicate.name = existing.name + duplicate.valid?.should be_false + duplicate.errors.map(&.field).should contain(:name) + end + + it "supports a two-tier parent chain" do + distributor = Generator.partner.save! + reseller = Generator.partner(parent: distributor).save! + reseller.parent_id.should eq distributor.id + distributor.children.to_a.map(&.id).should contain(reseller.id) + end + + it "rejects a partner as its own parent" do + partner = Generator.partner.save! + partner.parent_id = partner.id + partner.valid?.should be_false + partner.errors.map(&.field).should contain(:parent_id) + end + + it "rejects a cycle in the parent chain" do + top = Generator.partner.save! + bottom = Generator.partner(parent: top).save! + top.parent_id = bottom.id + top.valid?.should be_false + top.errors.map(&.field).should contain(:parent_id) + end + + it "lists its clients" do + partner = Generator.partner.save! + client = Generator.client(partner: partner).save! + Generator.client.save! + partner.clients.to_a.map(&.id).should eq [client.id] + end + + it "refuses to delete a partner that still has clients" do + partner = Generator.partner.save! + Generator.client(partner: partner).save! + + expect_raises(Exception, /foreign key/) { partner.destroy } + Partner.find?(partner.id.not_nil!).should_not be_nil + end + end +end diff --git a/src/placeos-models/authority.cr b/src/placeos-models/authority.cr index b903105f..29cd4f48 100644 --- a/src/placeos-models/authority.cr +++ b/src/placeos-models/authority.cr @@ -32,6 +32,10 @@ module PlaceOS::Model attribute email_domains : Array(String) = [] of String + # PPT-526: the Client (customer organisation) that owns this domain. + # Nullable while ownership backfill and provisioning are phased in. + attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + macro finished # Ensure only the host is saved. # @@ -77,6 +81,11 @@ module PlaceOS::Model Authority.where(domain: host).first? end + # The owning Client, when ownership has been assigned. + def client : PlaceOS::Model::Client? + self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + end + # Locates an authority by email domain def self.find_by_email(email : String) : Authority? parts = email.split('@', 2) diff --git a/src/placeos-models/broker.cr b/src/placeos-models/broker.cr index e68459c8..0677195a 100644 --- a/src/placeos-models/broker.cr +++ b/src/placeos-models/broker.cr @@ -33,6 +33,16 @@ module PlaceOS::Model # Matches will be replaced with a hmac_256(secret, match). attribute filters : Array(String) = -> { [] of String } + # PPT-526: the Client (customer organisation) that owns this broker. + # NULL = cluster-level infrastructure (the default; the backfill never + # assigns brokers). Nullable while query enforcement is phased in. + attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + + # The owning Client, when ownership has been assigned. + def client : PlaceOS::Model::Client? + self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + end + # Validation ############################################################################################### diff --git a/src/placeos-models/client.cr b/src/placeos-models/client.cr new file mode 100644 index 00000000..f211c448 --- /dev/null +++ b/src/placeos-models/client.cr @@ -0,0 +1,71 @@ +require "uuid" +require "uuid/json" + +require "./base/model" +require "./partner" + +module PlaceOS::Model + # A customer organisation (e.g. UCLA, Acadian) — the estate owner in the + # PPT-526 hierarchy: Partner -> Client -> Authority (domain) -> ... + # + # `partner_id` NULL means client-owned: the customer signed up and manages + # itself without an integrator. `payer` records who receives invoices for + # this client: the partner (integrator pays us and re-bills — the default + # channel model) or the client directly. A client without a partner can + # only pay for itself; `normalize_payer` keeps that invariant ahead of the + # DB CHECK constraint. + class Client < ::PgORM::Base + include PgORM::Timestamps + + table :clients + + PAYER_PARTNER = "partner" + PAYER_CLIENT = "client" + PAYERS = [PAYER_PARTNER, PAYER_CLIENT] + + default_primary_key id : UUID, autogenerated: true + + attribute name : String, sanitize: :text + attribute description : String = "", sanitize: :common + attribute payer : String = PAYER_PARTNER, mass_assignment: false + attribute config : Hash(String, JSON::Any) = {} of String => JSON::Any + + attribute partner_id : UUID? + belongs_to :partner, class_name: Partner, foreign_key: partner_id + + before_save :normalize_payer + + validates :name, presence: true + + validate ->(this : Client) { + unless PAYERS.includes?(this.payer) + this.validation_error(:payer, "must be one of #{PAYERS.join(", ")}") + end + } + + validate ->(this : Client) { + # Friendlier error ahead of the DB's partial unique indexes: names are + # unique within a partner's book, and unique among client-owned clients. + name = this.name + return if name.nil? || name.empty? + existing = Client.where(partner_id: this.partner_id, name: name).first? + return if existing.nil? + return if this.persisted? && existing.id == this.id + this.validation_error(:name, "a client with this name already exists") + } + + protected def normalize_payer + self.payer = PAYER_CLIENT if self.partner_id.nil? + end + + # True when the customer manages itself without an integrator. + def client_owned? : Bool + self.partner_id.nil? + end + + # Domains (authorities) owned by this client. + def authorities + Authority.where(client_id: self.id) + end + end +end diff --git a/src/placeos-models/control_system.cr b/src/placeos-models/control_system.cr index f54ebb01..ce3995f6 100644 --- a/src/placeos-models/control_system.cr +++ b/src/placeos-models/control_system.cr @@ -46,6 +46,15 @@ module PlaceOS::Model # Array of security group ids for room access attribute security_groups : Array(String) = -> { [] of String } + # PPT-526: the Client (customer organisation) that owns this system. + # Nullable while ownership backfill and query enforcement are phased in. + attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + + # The owning Client, when ownership has been assigned. + def client : PlaceOS::Model::Client? + self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + end + attribute timezone : Time::Location?, converter: Time::Location::Converter, es_type: "text" # Provide fields for simplifying support diff --git a/src/placeos-models/edge.cr b/src/placeos-models/edge.cr index b65ce340..3909ff8d 100644 --- a/src/placeos-models/edge.cr +++ b/src/placeos-models/edge.cr @@ -20,6 +20,15 @@ module PlaceOS::Model attribute last_seen : Time?, converter: Time::EpochConverterOptional, mass_assignment: false attribute online : Bool = false, mass_assignment: false + # PPT-526: the Client (customer organisation) that owns this edge node. + # Nullable while ownership backfill and query enforcement are phased in. + attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + + # The owning Client, when ownership has been assigned. + def client : PlaceOS::Model::Client? + self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + end + @[JSON::Field(ignore: true)] getter x_api_key : String do self.api_key.as(ApiKey).x_api_key.as(String) diff --git a/src/placeos-models/module.cr b/src/placeos-models/module.cr index 754d1d47..4ff1764b 100644 --- a/src/placeos-models/module.cr +++ b/src/placeos-models/module.cr @@ -52,6 +52,17 @@ module PlaceOS::Model attribute ignore_connected : Bool = false attribute ignore_startstop : Bool = false + # PPT-526: the Client (customer organisation) that owns this module. + # Nullable while ownership backfill and query enforcement are phased in; + # shared device/service modules referenced by several clients' systems + # stay NULL until a sharing policy is decided. + attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + + # The owning Client, when ownership has been assigned. + def client : PlaceOS::Model::Client? + self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + end + # Runtime Error Indicators attribute has_runtime_error : Bool = false, mass_assignment: false attribute error_timestamp : Time? = nil, converter: Time::EpochConverterOptional, type: "integer", format: "Int64", mass_assignment: false diff --git a/src/placeos-models/partner.cr b/src/placeos-models/partner.cr new file mode 100644 index 00000000..25927ae7 --- /dev/null +++ b/src/placeos-models/partner.cr @@ -0,0 +1,72 @@ +require "uuid" +require "uuid/json" + +require "./base/model" + +module PlaceOS::Model + # An integrator/reseller organisation (e.g. NTT) that brings clients onto + # the platform and may manage them. The top of the PPT-526 hierarchy: + # Partner -> Client -> Authority (domain) -> zones/systems/... + # + # `management = true` marks the platform operator's own organisation + # (PlaceOS staff): members of a management partner may be granted + # cluster-wide visibility. `parent_id` reserves a two-tier channel + # (distributor -> reseller); it carries no behaviour yet. + class Partner < ::PgORM::Base + include PgORM::Timestamps + + table :partners + + default_primary_key id : UUID, autogenerated: true + + attribute name : String, sanitize: :text + attribute description : String = "", sanitize: :common + attribute management : Bool = false, mass_assignment: false + attribute config : Hash(String, JSON::Any) = {} of String => JSON::Any + + attribute parent_id : UUID? + belongs_to :parent, class_name: Partner, foreign_key: parent_id + + validates :name, presence: true + + validate ->(this : Partner) { + # Friendlier error ahead of the DB's unique index. + name = this.name + return if name.nil? || name.empty? + existing = Partner.where(name: name).first? + return if existing.nil? + return if this.persisted? && existing.id == this.id + this.validation_error(:name, "a partner with this name already exists") + } + + validate ->(this : Partner) { + # The parent chain must not loop back to this partner. + parent_id = this.parent_id + return if parent_id.nil? + if this.persisted? && parent_id == this.id + this.validation_error(:parent_id, "a partner cannot be its own parent") + return + end + seen = Set(UUID).new + current = parent_id + while current + if this.persisted? && current == this.id + this.validation_error(:parent_id, "parent chain forms a cycle") + return + end + break unless seen.add?(current) + current = Partner.find?(current).try(&.parent_id) + end + } + + # Immediate child partners (distributor -> reseller). + def children + Partner.where(parent_id: self.id) + end + + # Clients under this partner's book of business. + def clients + Client.where(partner_id: self.id) + end + end +end diff --git a/src/placeos-models/trigger.cr b/src/placeos-models/trigger.cr index 509f830c..c16433c2 100644 --- a/src/placeos-models/trigger.cr +++ b/src/placeos-models/trigger.cr @@ -30,6 +30,16 @@ module PlaceOS::Model METHODS = %w(GET POST PUT PATCH DELETE) attribute supported_methods : Array(String) = ["POST"] + # PPT-526: the Client (customer organisation) that owns this trigger + # definition. NULL = shared/cluster-wide definition. Nullable while + # ownership backfill and query enforcement are phased in. + attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + + # The owning Client, when ownership has been assigned. + def client : PlaceOS::Model::Client? + self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + end + # Association ############################################################################################### diff --git a/src/placeos-models/zone.cr b/src/placeos-models/zone.cr index b8adc1bc..b8256e0c 100644 --- a/src/placeos-models/zone.cr +++ b/src/placeos-models/zone.cr @@ -52,6 +52,15 @@ module PlaceOS::Model attribute images : Array(String) = [] of String attribute playlists : Array(String) = [] of String, es_type: "keyword" + # PPT-526: the Client (customer organisation) that owns this zone. + # Nullable while ownership backfill and query enforcement are phased in. + attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + + # The owning Client, when ownership has been assigned. + def client : PlaceOS::Model::Client? + self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + end + attribute place_id : String? # Association From 5c20249247c2c36a3df922dc961f36230a2c9fd0 Mon Sep 17 00:00:00 2001 From: Cameron Reeves Date: Wed, 19 Aug 2026 15:03:13 +1000 Subject: [PATCH 02/23] feat: PPT-526 Stage 3 add cross-tenant authorization grants table The models foundation of the authorization layer: a Zanzibar-lite `grants` tuple that gives a user a Permissions bitmask over a Partner, Client, or Authority scope. Authorization resolves by walking UP from the touched resource (authority -> its client -> that client's partner) and OR-ing every live grant on the chain, so a single partner-scope grant covers all of that partner's clients, current and future (decided 2026-08-19). Decisions applied: reuse the existing Permissions flags enum (Int32 bitmask, same shape as group_users); partner grants auto-apply to all the partner's clients via the walk-up resolution; scope_id is polymorphic (no FK, inert when its scope is deleted); user_id FK CASCADE. Grant.resolve(user_id, authority) returns effective Permissions; for_user / for_scope back the future admin-console and audit views. The management-partner "support sees all" rule and rest-api enforcement are the enforcement layer's job, not the model's. Verified: grant_spec 11 examples green (authority/client/partner resolution, cross-partner isolation, permission OR, expiry, user-delete cascade); full models suite 671 examples 0 failures; ameba clean. expires_at is TIMESTAMPTZ mapped as a plain Time (no epoch converter). --- .../20260819100500000_add_grants.sql | 56 ++++++++ spec/generator.cr | 17 +++ spec/grant_spec.cr | 109 ++++++++++++++ spec/helper.cr | 1 + src/placeos-models/grant.cr | 135 ++++++++++++++++++ 5 files changed, 318 insertions(+) create mode 100644 migration/db/migrations/20260819100500000_add_grants.sql create mode 100644 spec/grant_spec.cr create mode 100644 src/placeos-models/grant.cr diff --git a/migration/db/migrations/20260819100500000_add_grants.sql b/migration/db/migrations/20260819100500000_add_grants.sql new file mode 100644 index 00000000..521c15f4 --- /dev/null +++ b/migration/db/migrations/20260819100500000_add_grants.sql @@ -0,0 +1,56 @@ +-- +micrate Up +-- SQL in section 'Up' is executed when this migration is applied + +-- MERGE-TIME CHECK: micrate refuses out-of-order version ids. If a later-dated +-- migration lands on master before this merges, renumber this file above it. + +-- --------------------------------------------------------------------------- +-- PPT-526 Stage 3: the authorization `grants` table (Zanzibar-lite tuple). +-- +-- A grant gives a user a permission bitmask over a scope, which is one of a +-- Partner, a Client, or an Authority. Authorization walks UP from the touched +-- resource (authority -> its client -> that client's partner) and ORs every +-- live grant found on the chain, so a single grant at partner scope applies to +-- all of that partner's clients, current and future (decision b, 2026-08-19). +-- +-- `scope_id` is polymorphic (a partner/client UUID as text, or an authority +-- TEXT id), so it carries no DB foreign key. A grant naming a deleted scope is +-- inert: resolution walks up from live resources and never matches it, so +-- orphan grants are harmless and can be swept lazily. The one real FK is +-- user_id (CASCADE) so a user's grants vanish with the user. +-- +-- `permissions` is the existing `PlaceOS::Model::Permissions` flags enum stored +-- as an Int32 bitmask (decision a) — the same column shape as group_users. +-- --------------------------------------------------------------------------- +CREATE TABLE IF NOT EXISTS "grants"( + id UUID PRIMARY KEY DEFAULT uuidv7(), + user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE, + scope_type TEXT NOT NULL CHECK (scope_type IN ('partner', 'client', 'authority')), + scope_id TEXT NOT NULL, + permissions INTEGER NOT NULL DEFAULT 0, + expires_at TIMESTAMPTZ, + granted_by TEXT, + created_at TIMESTAMPTZ NOT NULL, + updated_at TIMESTAMPTZ NOT NULL +); + +-- One grant per (user, scope) — a re-grant updates the existing row's bitmask +-- and expiry rather than stacking duplicates. +CREATE UNIQUE INDEX IF NOT EXISTS grants_user_scope_unique + ON "grants" USING BTREE (user_id, scope_type, scope_id); + +-- "what can this user reach" (resolution walks per user). +CREATE INDEX IF NOT EXISTS grants_user_id_index + ON "grants" USING BTREE (user_id); + +-- "who can reach this scope" (partner/client admin console, audit). +CREATE INDEX IF NOT EXISTS grants_scope_index + ON "grants" USING BTREE (scope_type, scope_id); + +-- +micrate Down +-- SQL section 'Down' is executed when this migration is rolled back + +DROP INDEX IF EXISTS grants_scope_index; +DROP INDEX IF EXISTS grants_user_id_index; +DROP INDEX IF EXISTS grants_user_scope_unique; +DROP TABLE IF EXISTS "grants"; diff --git a/spec/generator.cr b/spec/generator.cr index c748be59..b6115f30 100644 --- a/spec/generator.cr +++ b/spec/generator.cr @@ -582,6 +582,23 @@ module PlaceOS::Model ) end + def self.grant( + user : User, + scope_type : String, + scope_id : String, + permissions : Permissions = Permissions::Read, + expires_at : Time? = nil, + ) + grant = Grant.new( + user_id: user.id.not_nil!, + scope_type: scope_type, + scope_id: scope_id, + expires_at: expires_at, + ) + grant.permission_flags = permissions + grant + end + def self.user(authority : Authority? = nil, support : Bool = false, admin : Bool = false) unless authority # look up an existing authority diff --git a/spec/grant_spec.cr b/spec/grant_spec.cr new file mode 100644 index 00000000..9c2f2988 --- /dev/null +++ b/spec/grant_spec.cr @@ -0,0 +1,109 @@ +require "./helper" + +# Build partner -> client -> authority -> user, returning all four. +private def build_estate(payer = PlaceOS::Model::Client::PAYER_PARTNER) + partner = PlaceOS::Model::Generator.partner.save! + client = PlaceOS::Model::Generator.client(partner: partner, payer: payer).save! + authority = PlaceOS::Model::Generator.authority(domain: "grant-#{RANDOM.hex(4)}.example.com") + authority.client_id = client.id + authority.save! + user = PlaceOS::Model::Generator.user(authority: authority).save! + {partner, client, authority, user} +end + +module PlaceOS::Model + describe Grant do + Spec.before_each do + Grant.clear + Authority.clear + User.clear + Client.clear + Partner.clear + end + + it "saves a grant with a permission bitmask" do + _, client, _, user = build_estate + grant = Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Manage).save! + grant.persisted?.should be_true + grant.permission_flags.should eq Permissions::Manage + end + + it "rejects an unknown scope_type" do + _, _, _, user = build_estate + grant = Generator.grant(user, "galaxy", "scope-1") + grant.valid?.should be_false + grant.errors.map(&.field).should contain(:scope_type) + end + + it "resolves an authority-scope grant" do + _, _, authority, user = build_estate + Generator.grant(user, Grant::SCOPE_AUTHORITY, authority.id.not_nil!, Permissions::Update).save! + Grant.resolve(user.id.not_nil!, authority).should eq Permissions::Update + end + + it "resolves a client-scope grant onto the client's authority" do + _, client, authority, user = build_estate + Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Operate).save! + Grant.resolve(user.id.not_nil!, authority).should eq Permissions::Operate + end + + it "resolves a partner-scope grant onto every authority under that partner (decision b)" do + partner = Generator.partner.save! + client_a = Generator.client(partner: partner).save! + client_b = Generator.client(partner: partner).save! + auth_a = Generator.authority(domain: "a-#{RANDOM.hex(4)}.example.com") + auth_a.client_id = client_a.id + auth_a.save! + auth_b = Generator.authority(domain: "b-#{RANDOM.hex(4)}.example.com") + auth_b.client_id = client_b.id + auth_b.save! + staff = Generator.user(authority: auth_a).save! + + # One grant at partner scope reaches both clients' authorities. + Generator.grant(staff, Grant::SCOPE_PARTNER, partner.id.not_nil!.to_s, Permissions::Manage).save! + Grant.resolve(staff.id.not_nil!, auth_a).should eq Permissions::Manage + Grant.resolve(staff.id.not_nil!, auth_b).should eq Permissions::Manage + end + + it "ORs permissions across scopes on the chain" do + partner, client, authority, user = build_estate + Generator.grant(user, Grant::SCOPE_PARTNER, partner.id.not_nil!.to_s, Permissions::Read).save! + Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Update).save! + Grant.resolve(user.id.not_nil!, authority).should eq(Permissions::Read | Permissions::Update) + end + + it "does not leak a grant into a different partner's estate" do + _, _, authority_one, user = build_estate + # A second, unrelated estate. + _, _, authority_two, _ = build_estate + Generator.grant(user, Grant::SCOPE_AUTHORITY, authority_one.id.not_nil!, Permissions::Manage).save! + Grant.resolve(user.id.not_nil!, authority_two).should eq Permissions::None + end + + it "ignores expired grants" do + _, client, authority, user = build_estate + Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Manage, + expires_at: Time.utc - 1.hour).save! + Grant.resolve(user.id.not_nil!, authority).should eq Permissions::None + end + + it "honours a future expiry" do + _, client, authority, user = build_estate + Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Read, + expires_at: Time.utc + 1.hour).save! + Grant.resolve(user.id.not_nil!, authority).should eq Permissions::Read + end + + it "returns None for a resource with no matching grant" do + _, _, authority, user = build_estate + Grant.resolve(user.id.not_nil!, authority).should eq Permissions::None + end + + it "cascades on user delete" do + _, client, _, user = build_estate + grant = Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s).save! + user.destroy + Grant.find?(grant.id.not_nil!).should be_nil + end + end +end diff --git a/spec/helper.cr b/spec/helper.cr index 347d35d2..b4fa95fc 100644 --- a/spec/helper.cr +++ b/spec/helper.cr @@ -39,6 +39,7 @@ Spec.after_suite do PlaceOS::Model::GroupPlaylistItem, PlaceOS::Model::GroupPlaylist, PlaceOS::Model::Group, + PlaceOS::Model::Grant, PlaceOS::Model::Client, PlaceOS::Model::Partner, ].each(&.clear) diff --git a/src/placeos-models/grant.cr b/src/placeos-models/grant.cr new file mode 100644 index 00000000..66243003 --- /dev/null +++ b/src/placeos-models/grant.cr @@ -0,0 +1,135 @@ +require "uuid" +require "uuid/json" + +require "./base/model" +require "./permissions" +require "./authority" +require "./client" +require "./partner" + +module PlaceOS::Model + # PPT-526 Stage 3: a cross-tenant authorization grant. + # + # Gives a user a `Permissions` bitmask over one scope — a Partner, a Client, + # or an Authority. Authorization resolves by walking UP from the touched + # resource: authority -> its client -> that client's partner. A grant at + # partner scope therefore covers every one of that partner's clients, current + # and future (the NTT-over-its-clients case); a grant at client scope covers + # that client's authorities; a grant at authority scope is a single domain. + # + # `scope_id` is polymorphic (a Partner/Client UUID as text, or an Authority + # TEXT id) so it carries no FK; a grant naming a deleted scope is inert. + class Grant < ::PgORM::Base + include PgORM::Timestamps + + table :grants + + SCOPE_PARTNER = "partner" + SCOPE_CLIENT = "client" + SCOPE_AUTHORITY = "authority" + SCOPE_TYPES = [SCOPE_PARTNER, SCOPE_CLIENT, SCOPE_AUTHORITY] + + default_primary_key id : UUID, autogenerated: true + + attribute user_id : String + belongs_to :user, class_name: User, foreign_key: user_id + + attribute scope_type : String + attribute scope_id : String + + # Stored as an Int32 bitmask. Use `permission_flags` / `permission_flags=` + # to work with the `Permissions` flags enum directly (same shape as + # group_users.permissions). + attribute permissions : Int32 = 0 + + # NULL = a standing grant. A non-null value in the past means expired. + # Plain Time maps to the TIMESTAMPTZ column (same as created_at/updated_at). + attribute expires_at : Time? + + # The user id of whoever issued this grant (audit; no FK so the trail + # survives the grantor's deletion). + attribute granted_by : String? + + validates :user_id, presence: true + validates :scope_id, presence: true + + validate ->(this : Grant) { + unless SCOPE_TYPES.includes?(this.scope_type) + this.validation_error(:scope_type, "must be one of #{SCOPE_TYPES.join(", ")}") + end + } + + def permission_flags : Permissions + Permissions.new(self.permissions) + end + + def permission_flags=(flags : Permissions) + self.permissions = flags.to_i + end + + # A grant is live when it has not expired. + def live?(at : Time = Time.utc) : Bool + exp = self.expires_at + exp.nil? || exp > at + end + + # ------------------------------------------------------------------ + # Resolution + # ------------------------------------------------------------------ + + # Effective permissions a user holds over `authority`, resolved by walking + # up authority -> client -> partner and OR-ing every live grant on the + # chain. Explicit grants only; the management-partner "support sees all" + # rule is applied by the enforcement layer, not here. + def self.resolve(user_id : String, authority : Authority, at : Time = Time.utc) : Permissions + resolve_for_chain(user_id, scope_chain(authority), at) + end + + # As above, addressed by authority id (returns None for an unknown id). + def self.resolve(user_id : String, authority_id : String, at : Time = Time.utc) : Permissions + authority = Authority.find?(authority_id) + return Permissions::None if authority.nil? + resolve(user_id, authority, at) + end + + # The (scope_type, scope_id) pairs to check for a given authority, from + # most specific to least: the authority itself, its client, that client's + # partner. Missing links are simply absent. + def self.scope_chain(authority : Authority) : Array({String, String}) + chain = [{SCOPE_AUTHORITY, authority.id.to_s}] + if (client_id = authority.client_id) + chain << {SCOPE_CLIENT, client_id.to_s} + if (client = Client.find?(client_id)) && (partner_id = client.partner_id) + chain << {SCOPE_PARTNER, partner_id.to_s} + end + end + chain + end + + private def self.resolve_for_chain(user_id : String, chain : Array({String, String}), at : Time) : Permissions + return Permissions::None if chain.empty? + + # Query by the scalar user_id (a user holds few grants), then keep only + # the live grants whose (scope_type, scope_id) is on the resource's chain + # and OR their permissions. Filtering in memory sidesteps array binding. + wanted = chain.to_set + effective = Permissions::None + Grant.where(user_id: user_id).each do |grant| + next unless wanted.includes?({grant.scope_type, grant.scope_id}) + next unless grant.live?(at) + effective |= grant.permission_flags + end + effective + end + + # All live grants for a user (any scope). + def self.for_user(user_id : String) : Array(Grant) + Grant.where(user_id: user_id).select(&.live?) + end + + # Everyone granted access to a specific scope (partner/client admin console). + def self.for_scope(scope_type : String, scope_id : String) : Array(Grant) + Grant.where(scope_type: scope_type, scope_id: scope_id).to_a + end + end +end From b4d811089daa89c638de7c06c1718a7eb9790445 Mon Sep 17 00:00:00 2001 From: Cameron Reeves Date: Wed, 19 Aug 2026 15:27:00 +1000 Subject: [PATCH 03/23] refactor: PPT-526 rename Client to Organization Steve's multi-tenancy-template calls the customer tenant "Organization"; we align on that name (decided 2026-08-19). The Partner tier above it is unchanged. Since nothing is shipped, the migrations are rewritten in place rather than adding a rename migration. - clients table -> organizations; client_id -> organization_id on authority/zone/sys/mod/trigger/edge/broker; the Client model -> Organization (payer value 'client' -> 'organization'; client_owned? -> self_managed?). - grants scope_type value 'client' -> 'organization'; Grant.resolve walk now authority -> organization -> partner. - migrations, backfill, generator, specs, helper, and backfill-verify.sh all updated; the OAuth/credential `client_id` fields (oauth_strat, tenant credentials JSON) are deliberately left as-is. Verified: full models suite 671 examples, 0 failures (the 1 error is the pre-existing flaky admin_destroy_lock concurrency test); organization/partner/ grant specs 28 green; backfill-verify.sh all assertions pass; ameba clean. --- ...0818100500000_add_partners_and_clients.sql | 211 ------------------ ...0500000_add_partners_and_organizations.sql | 211 ++++++++++++++++++ ...00000_backfill_organization_ownership.sql} | 118 +++++----- .../20260819100500000_add_grants.sql | 12 +- spec/client_spec.cr | 104 --------- spec/generator.cr | 4 +- spec/grant_spec.cr | 46 ++-- spec/helper.cr | 2 +- spec/organization_spec.cr | 104 +++++++++ spec/partner_spec.cr | 10 +- src/placeos-models/authority.cr | 10 +- src/placeos-models/broker.cr | 10 +- src/placeos-models/control_system.cr | 10 +- src/placeos-models/edge.cr | 10 +- src/placeos-models/grant.cr | 34 +-- src/placeos-models/module.cr | 12 +- .../{client.cr => organization.cr} | 41 ++-- src/placeos-models/partner.cr | 6 +- src/placeos-models/trigger.cr | 10 +- src/placeos-models/zone.cr | 10 +- 20 files changed, 488 insertions(+), 487 deletions(-) delete mode 100644 migration/db/migrations/20260818100500000_add_partners_and_clients.sql create mode 100644 migration/db/migrations/20260818100500000_add_partners_and_organizations.sql rename migration/db/migrations/{20260818100600000_backfill_client_ownership.sql => 20260818100600000_backfill_organization_ownership.sql} (63%) delete mode 100644 spec/client_spec.cr create mode 100644 spec/organization_spec.cr rename src/placeos-models/{client.cr => organization.cr} (57%) diff --git a/migration/db/migrations/20260818100500000_add_partners_and_clients.sql b/migration/db/migrations/20260818100500000_add_partners_and_clients.sql deleted file mode 100644 index 59478ca6..00000000 --- a/migration/db/migrations/20260818100500000_add_partners_and_clients.sql +++ /dev/null @@ -1,211 +0,0 @@ --- +micrate Up --- SQL in section 'Up' is executed when this migration is applied - --- MERGE-TIME CHECK: micrate refuses out-of-order version ids (see models#323). --- If any later-dated migration lands on master before this merges, renumber --- this file AND 20260818100600000 above it (preserving schema-before-backfill --- order). Safe: neither has been applied anywhere and the backfill is --- idempotent. - --- --------------------------------------------------------------------------- --- PPT-526: the Partner → Client → Authority(domain) hierarchy. --- --- partners: integrators/resellers (e.g. NTT). `management = true` marks the --- platform operator's own organisation (PlaceOS staff) — the "management --- client" concept from the ticket, done at the partner level. `parent_id` --- reserves a 2-tier channel (distributor → reseller) without any UI or --- enforcement yet. --- --- clients: the customer organisation (e.g. UCLA, Acadian). `partner_id` NULL --- means client-owned (self-managed, no integrator). `payer` records who is --- invoiced: 'partner' (integrator pays us and re-bills, the default channel --- model) or 'client' (direct). A client without a partner can only pay for --- itself — enforced by CHECK. --- --- Every delete path is RESTRICT: removing a partner/client must go through an --- orchestrated teardown (the PPT-1203 pattern), never a silent DB cascade — --- model-level cleanup callbacks do not fire on DB cascades. --- --------------------------------------------------------------------------- -CREATE TABLE IF NOT EXISTS "partners"( - id UUID PRIMARY KEY DEFAULT uuidv7(), - name TEXT NOT NULL, - description TEXT NOT NULL DEFAULT '', - management BOOLEAN NOT NULL DEFAULT false, - parent_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, - config JSONB NOT NULL DEFAULT '{}', - created_at TIMESTAMPTZ NOT NULL, - updated_at TIMESTAMPTZ NOT NULL -); - -CREATE UNIQUE INDEX IF NOT EXISTS partners_name_unique - ON "partners" USING BTREE (name); -CREATE INDEX IF NOT EXISTS partners_parent_id_index - ON "partners" USING BTREE (parent_id); - -CREATE TABLE IF NOT EXISTS "clients"( - id UUID PRIMARY KEY DEFAULT uuidv7(), - name TEXT NOT NULL, - description TEXT NOT NULL DEFAULT '', - partner_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, - payer TEXT NOT NULL DEFAULT 'partner' - CHECK (payer IN ('partner', 'client')), - config JSONB NOT NULL DEFAULT '{}', - created_at TIMESTAMPTZ NOT NULL, - updated_at TIMESTAMPTZ NOT NULL, - CONSTRAINT clients_payer_requires_partner - CHECK (partner_id IS NOT NULL OR payer = 'client') -); - --- Client names are unique within a partner's book of business, and unique --- among client-owned clients. Two partial indexes because UNIQUE treats --- NULLs as distinct — a plain UNIQUE (partner_id, name) would let every --- client-owned client share a name. -CREATE UNIQUE INDEX IF NOT EXISTS clients_name_unique_per_partner - ON "clients" USING BTREE (partner_id, name) WHERE partner_id IS NOT NULL; -CREATE UNIQUE INDEX IF NOT EXISTS clients_name_unique_owned - ON "clients" USING BTREE (name) WHERE partner_id IS NULL; -CREATE INDEX IF NOT EXISTS clients_partner_id_index - ON "clients" USING BTREE (partner_id); - --- --------------------------------------------------------------------------- --- Authority → Client ownership. Nullable at the DB level for backwards --- compatibility (init seeds authorities before any client exists); the --- provisioning flow and backfill populate it. RESTRICT so a client cannot be --- deleted while it still owns domains. --- --------------------------------------------------------------------------- -ALTER TABLE "authority" - ADD COLUMN IF NOT EXISTS client_id UUID; - -ALTER TABLE ONLY "authority" - DROP CONSTRAINT IF EXISTS authority_client_id_fkey; -ALTER TABLE ONLY "authority" - ADD CONSTRAINT authority_client_id_fkey - FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; - -CREATE INDEX IF NOT EXISTS authority_client_id_index - ON "authority" USING BTREE (client_id); - --- The domain column has only ever had model-level uniqueness (a plain BTREE --- index) — a concurrent-signup race can create duplicate authorities. Make it --- a hard guarantee; self-service signup depends on it. --- --- Quarantine first: exact-duplicate domains left behind by that race would --- make the unique index unbuildable and (because micrate autocommits each --- statement) leave this migration half-applied. Keep the oldest row per --- domain and rename the rest so they stop answering for the domain — --- find_by_domain picks an arbitrary row across duplicates today, so this --- cannot break a reliably-working login. Idempotent: renamed rows no longer --- collide. Renamed rows are for an operator to merge or delete. -UPDATE "authority" a -SET domain = a.domain || '.duplicate.' || a.id -WHERE EXISTS ( - SELECT 1 FROM "authority" b - WHERE b.domain = a.domain - AND (b.created_at, b.id) < (a.created_at, a.id) -); - -CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique - ON "authority" USING BTREE (domain); - --- --------------------------------------------------------------------------- --- Client ownership columns on the (previously cluster-global) control plane. --- Nullable: populated by the backfill migration where inference is --- unambiguous, and by the provisioning flow for everything new. Query-path --- enforcement is phased in separately (rest-api); these columns are the --- ground truth it will filter on. --- --------------------------------------------------------------------------- -ALTER TABLE "zone" ADD COLUMN IF NOT EXISTS client_id UUID; -ALTER TABLE "sys" ADD COLUMN IF NOT EXISTS client_id UUID; -ALTER TABLE "mod" ADD COLUMN IF NOT EXISTS client_id UUID; -ALTER TABLE "trigger" ADD COLUMN IF NOT EXISTS client_id UUID; -ALTER TABLE "edge" ADD COLUMN IF NOT EXISTS client_id UUID; -ALTER TABLE "broker" ADD COLUMN IF NOT EXISTS client_id UUID; - -ALTER TABLE ONLY "zone" - DROP CONSTRAINT IF EXISTS zone_client_id_fkey; -ALTER TABLE ONLY "zone" - ADD CONSTRAINT zone_client_id_fkey - FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "sys" - DROP CONSTRAINT IF EXISTS sys_client_id_fkey; -ALTER TABLE ONLY "sys" - ADD CONSTRAINT sys_client_id_fkey - FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "mod" - DROP CONSTRAINT IF EXISTS mod_client_id_fkey; -ALTER TABLE ONLY "mod" - ADD CONSTRAINT mod_client_id_fkey - FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "trigger" - DROP CONSTRAINT IF EXISTS trigger_client_id_fkey; -ALTER TABLE ONLY "trigger" - ADD CONSTRAINT trigger_client_id_fkey - FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "edge" - DROP CONSTRAINT IF EXISTS edge_client_id_fkey; -ALTER TABLE ONLY "edge" - ADD CONSTRAINT edge_client_id_fkey - FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "broker" - DROP CONSTRAINT IF EXISTS broker_client_id_fkey; -ALTER TABLE ONLY "broker" - ADD CONSTRAINT broker_client_id_fkey - FOREIGN KEY (client_id) REFERENCES "clients"(id) ON DELETE RESTRICT; - -CREATE INDEX IF NOT EXISTS zone_client_id_index ON "zone" USING BTREE (client_id); -CREATE INDEX IF NOT EXISTS sys_client_id_index ON "sys" USING BTREE (client_id); -CREATE INDEX IF NOT EXISTS mod_client_id_index ON "mod" USING BTREE (client_id); -CREATE INDEX IF NOT EXISTS trigger_client_id_index ON "trigger" USING BTREE (client_id); -CREATE INDEX IF NOT EXISTS edge_client_id_index ON "edge" USING BTREE (client_id); -CREATE INDEX IF NOT EXISTS broker_client_id_index ON "broker" USING BTREE (client_id); - --- Per-client name uniqueness for the estate. Dormant while client_id is NULL --- (UNIQUE treats NULLs as distinct) and strictly weaker than the current --- model-level global uniqueness, so it cannot conflict with existing data. --- When query enforcement lands, the model-level checks flip from global to --- client-scoped and these indexes become the hard guarantee. -CREATE UNIQUE INDEX IF NOT EXISTS zone_client_id_name_unique - ON "zone" USING BTREE (client_id, name) WHERE client_id IS NOT NULL; -CREATE UNIQUE INDEX IF NOT EXISTS sys_client_id_name_unique - ON "sys" USING BTREE (client_id, name) WHERE client_id IS NOT NULL; -CREATE UNIQUE INDEX IF NOT EXISTS edge_client_id_name_unique - ON "edge" USING BTREE (client_id, name) WHERE client_id IS NOT NULL; -CREATE UNIQUE INDEX IF NOT EXISTS broker_client_id_name_unique - ON "broker" USING BTREE (client_id, name) WHERE client_id IS NOT NULL; - --- +micrate Down --- SQL section 'Down' is executed when this migration is rolled back - -DROP INDEX IF EXISTS broker_client_id_name_unique; -DROP INDEX IF EXISTS edge_client_id_name_unique; -DROP INDEX IF EXISTS sys_client_id_name_unique; -DROP INDEX IF EXISTS zone_client_id_name_unique; - -DROP INDEX IF EXISTS broker_client_id_index; -DROP INDEX IF EXISTS edge_client_id_index; -DROP INDEX IF EXISTS trigger_client_id_index; -DROP INDEX IF EXISTS mod_client_id_index; -DROP INDEX IF EXISTS sys_client_id_index; -DROP INDEX IF EXISTS zone_client_id_index; - -ALTER TABLE ONLY "broker" DROP CONSTRAINT IF EXISTS broker_client_id_fkey; -ALTER TABLE ONLY "edge" DROP CONSTRAINT IF EXISTS edge_client_id_fkey; -ALTER TABLE ONLY "trigger" DROP CONSTRAINT IF EXISTS trigger_client_id_fkey; -ALTER TABLE ONLY "mod" DROP CONSTRAINT IF EXISTS mod_client_id_fkey; -ALTER TABLE ONLY "sys" DROP CONSTRAINT IF EXISTS sys_client_id_fkey; -ALTER TABLE ONLY "zone" DROP CONSTRAINT IF EXISTS zone_client_id_fkey; - -ALTER TABLE "broker" DROP COLUMN IF EXISTS client_id; -ALTER TABLE "edge" DROP COLUMN IF EXISTS client_id; -ALTER TABLE "trigger" DROP COLUMN IF EXISTS client_id; -ALTER TABLE "mod" DROP COLUMN IF EXISTS client_id; -ALTER TABLE "sys" DROP COLUMN IF EXISTS client_id; -ALTER TABLE "zone" DROP COLUMN IF EXISTS client_id; - -DROP INDEX IF EXISTS authority_domain_unique; -DROP INDEX IF EXISTS authority_client_id_index; -ALTER TABLE ONLY "authority" DROP CONSTRAINT IF EXISTS authority_client_id_fkey; -ALTER TABLE "authority" DROP COLUMN IF EXISTS client_id; - -DROP TABLE IF EXISTS "clients"; -DROP TABLE IF EXISTS "partners"; diff --git a/migration/db/migrations/20260818100500000_add_partners_and_organizations.sql b/migration/db/migrations/20260818100500000_add_partners_and_organizations.sql new file mode 100644 index 00000000..524e9084 --- /dev/null +++ b/migration/db/migrations/20260818100500000_add_partners_and_organizations.sql @@ -0,0 +1,211 @@ +-- +micrate Up +-- SQL in section 'Up' is executed when this migration is applied + +-- MERGE-TIME CHECK: micrate refuses out-of-order version ids (see models#323). +-- If any later-dated migration lands on master before this merges, renumber +-- this file AND 20260818100600000 above it (preserving schema-before-backfill +-- order). Safe: neither has been applied anywhere and the backfill is +-- idempotent. + +-- --------------------------------------------------------------------------- +-- PPT-526: the Partner → Organization → Authority(domain) hierarchy. +-- +-- partners: integrators/resellers (e.g. NTT). `management = true` marks the +-- platform operator's own organisation (PlaceOS staff) — the "management +-- organization" concept from the ticket, done at the partner level. `parent_id` +-- reserves a 2-tier channel (distributor → reseller) without any UI or +-- enforcement yet. +-- +-- organizations: the customer organisation (e.g. UCLA, Acadian). `partner_id` NULL +-- means organization-owned (self-managed, no integrator). `payer` records who is +-- invoiced: 'partner' (integrator pays us and re-bills, the default channel +-- model) or 'organization' (direct). A organization without a partner can only pay for +-- itself — enforced by CHECK. +-- +-- Every delete path is RESTRICT: removing a partner/organization must go through an +-- orchestrated teardown (the PPT-1203 pattern), never a silent DB cascade — +-- model-level cleanup callbacks do not fire on DB cascades. +-- --------------------------------------------------------------------------- +CREATE TABLE IF NOT EXISTS "partners"( + id UUID PRIMARY KEY DEFAULT uuidv7(), + name TEXT NOT NULL, + description TEXT NOT NULL DEFAULT '', + management BOOLEAN NOT NULL DEFAULT false, + parent_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, + config JSONB NOT NULL DEFAULT '{}', + created_at TIMESTAMPTZ NOT NULL, + updated_at TIMESTAMPTZ NOT NULL +); + +CREATE UNIQUE INDEX IF NOT EXISTS partners_name_unique + ON "partners" USING BTREE (name); +CREATE INDEX IF NOT EXISTS partners_parent_id_index + ON "partners" USING BTREE (parent_id); + +CREATE TABLE IF NOT EXISTS "organizations"( + id UUID PRIMARY KEY DEFAULT uuidv7(), + name TEXT NOT NULL, + description TEXT NOT NULL DEFAULT '', + partner_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, + payer TEXT NOT NULL DEFAULT 'partner' + CHECK (payer IN ('partner', 'organization')), + config JSONB NOT NULL DEFAULT '{}', + created_at TIMESTAMPTZ NOT NULL, + updated_at TIMESTAMPTZ NOT NULL, + CONSTRAINT organizations_payer_requires_partner + CHECK (partner_id IS NOT NULL OR payer = 'organization') +); + +-- Organization names are unique within a partner's book of business, and unique +-- among organization-owned organizations. Two partial indexes because UNIQUE treats +-- NULLs as distinct — a plain UNIQUE (partner_id, name) would let every +-- organization-owned organization share a name. +CREATE UNIQUE INDEX IF NOT EXISTS organizations_name_unique_per_partner + ON "organizations" USING BTREE (partner_id, name) WHERE partner_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS organizations_name_unique_owned + ON "organizations" USING BTREE (name) WHERE partner_id IS NULL; +CREATE INDEX IF NOT EXISTS organizations_partner_id_index + ON "organizations" USING BTREE (partner_id); + +-- --------------------------------------------------------------------------- +-- Authority → Organization ownership. Nullable at the DB level for backwards +-- compatibility (init seeds authorities before any organization exists); the +-- provisioning flow and backfill populate it. RESTRICT so a organization cannot be +-- deleted while it still owns domains. +-- --------------------------------------------------------------------------- +ALTER TABLE "authority" + ADD COLUMN IF NOT EXISTS organization_id UUID; + +ALTER TABLE ONLY "authority" + DROP CONSTRAINT IF EXISTS authority_organization_id_fkey; +ALTER TABLE ONLY "authority" + ADD CONSTRAINT authority_organization_id_fkey + FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; + +CREATE INDEX IF NOT EXISTS authority_organization_id_index + ON "authority" USING BTREE (organization_id); + +-- The domain column has only ever had model-level uniqueness (a plain BTREE +-- index) — a concurrent-signup race can create duplicate authorities. Make it +-- a hard guarantee; self-service signup depends on it. +-- +-- Quarantine first: exact-duplicate domains left behind by that race would +-- make the unique index unbuildable and (because micrate autocommits each +-- statement) leave this migration half-applied. Keep the oldest row per +-- domain and rename the rest so they stop answering for the domain — +-- find_by_domain picks an arbitrary row across duplicates today, so this +-- cannot break a reliably-working login. Idempotent: renamed rows no longer +-- collide. Renamed rows are for an operator to merge or delete. +UPDATE "authority" a +SET domain = a.domain || '.duplicate.' || a.id +WHERE EXISTS ( + SELECT 1 FROM "authority" b + WHERE b.domain = a.domain + AND (b.created_at, b.id) < (a.created_at, a.id) +); + +CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique + ON "authority" USING BTREE (domain); + +-- --------------------------------------------------------------------------- +-- Organization ownership columns on the (previously cluster-global) control plane. +-- Nullable: populated by the backfill migration where inference is +-- unambiguous, and by the provisioning flow for everything new. Query-path +-- enforcement is phased in separately (rest-api); these columns are the +-- ground truth it will filter on. +-- --------------------------------------------------------------------------- +ALTER TABLE "zone" ADD COLUMN IF NOT EXISTS organization_id UUID; +ALTER TABLE "sys" ADD COLUMN IF NOT EXISTS organization_id UUID; +ALTER TABLE "mod" ADD COLUMN IF NOT EXISTS organization_id UUID; +ALTER TABLE "trigger" ADD COLUMN IF NOT EXISTS organization_id UUID; +ALTER TABLE "edge" ADD COLUMN IF NOT EXISTS organization_id UUID; +ALTER TABLE "broker" ADD COLUMN IF NOT EXISTS organization_id UUID; + +ALTER TABLE ONLY "zone" + DROP CONSTRAINT IF EXISTS zone_organization_id_fkey; +ALTER TABLE ONLY "zone" + ADD CONSTRAINT zone_organization_id_fkey + FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "sys" + DROP CONSTRAINT IF EXISTS sys_organization_id_fkey; +ALTER TABLE ONLY "sys" + ADD CONSTRAINT sys_organization_id_fkey + FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "mod" + DROP CONSTRAINT IF EXISTS mod_organization_id_fkey; +ALTER TABLE ONLY "mod" + ADD CONSTRAINT mod_organization_id_fkey + FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "trigger" + DROP CONSTRAINT IF EXISTS trigger_organization_id_fkey; +ALTER TABLE ONLY "trigger" + ADD CONSTRAINT trigger_organization_id_fkey + FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "edge" + DROP CONSTRAINT IF EXISTS edge_organization_id_fkey; +ALTER TABLE ONLY "edge" + ADD CONSTRAINT edge_organization_id_fkey + FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "broker" + DROP CONSTRAINT IF EXISTS broker_organization_id_fkey; +ALTER TABLE ONLY "broker" + ADD CONSTRAINT broker_organization_id_fkey + FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; + +CREATE INDEX IF NOT EXISTS zone_organization_id_index ON "zone" USING BTREE (organization_id); +CREATE INDEX IF NOT EXISTS sys_organization_id_index ON "sys" USING BTREE (organization_id); +CREATE INDEX IF NOT EXISTS mod_organization_id_index ON "mod" USING BTREE (organization_id); +CREATE INDEX IF NOT EXISTS trigger_organization_id_index ON "trigger" USING BTREE (organization_id); +CREATE INDEX IF NOT EXISTS edge_organization_id_index ON "edge" USING BTREE (organization_id); +CREATE INDEX IF NOT EXISTS broker_organization_id_index ON "broker" USING BTREE (organization_id); + +-- Per-organization name uniqueness for the estate. Dormant while organization_id is NULL +-- (UNIQUE treats NULLs as distinct) and strictly weaker than the current +-- model-level global uniqueness, so it cannot conflict with existing data. +-- When query enforcement lands, the model-level checks flip from global to +-- organization-scoped and these indexes become the hard guarantee. +CREATE UNIQUE INDEX IF NOT EXISTS zone_organization_id_name_unique + ON "zone" USING BTREE (organization_id, name) WHERE organization_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS sys_organization_id_name_unique + ON "sys" USING BTREE (organization_id, name) WHERE organization_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS edge_organization_id_name_unique + ON "edge" USING BTREE (organization_id, name) WHERE organization_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS broker_organization_id_name_unique + ON "broker" USING BTREE (organization_id, name) WHERE organization_id IS NOT NULL; + +-- +micrate Down +-- SQL section 'Down' is executed when this migration is rolled back + +DROP INDEX IF EXISTS broker_organization_id_name_unique; +DROP INDEX IF EXISTS edge_organization_id_name_unique; +DROP INDEX IF EXISTS sys_organization_id_name_unique; +DROP INDEX IF EXISTS zone_organization_id_name_unique; + +DROP INDEX IF EXISTS broker_organization_id_index; +DROP INDEX IF EXISTS edge_organization_id_index; +DROP INDEX IF EXISTS trigger_organization_id_index; +DROP INDEX IF EXISTS mod_organization_id_index; +DROP INDEX IF EXISTS sys_organization_id_index; +DROP INDEX IF EXISTS zone_organization_id_index; + +ALTER TABLE ONLY "broker" DROP CONSTRAINT IF EXISTS broker_organization_id_fkey; +ALTER TABLE ONLY "edge" DROP CONSTRAINT IF EXISTS edge_organization_id_fkey; +ALTER TABLE ONLY "trigger" DROP CONSTRAINT IF EXISTS trigger_organization_id_fkey; +ALTER TABLE ONLY "mod" DROP CONSTRAINT IF EXISTS mod_organization_id_fkey; +ALTER TABLE ONLY "sys" DROP CONSTRAINT IF EXISTS sys_organization_id_fkey; +ALTER TABLE ONLY "zone" DROP CONSTRAINT IF EXISTS zone_organization_id_fkey; + +ALTER TABLE "broker" DROP COLUMN IF EXISTS organization_id; +ALTER TABLE "edge" DROP COLUMN IF EXISTS organization_id; +ALTER TABLE "trigger" DROP COLUMN IF EXISTS organization_id; +ALTER TABLE "mod" DROP COLUMN IF EXISTS organization_id; +ALTER TABLE "sys" DROP COLUMN IF EXISTS organization_id; +ALTER TABLE "zone" DROP COLUMN IF EXISTS organization_id; + +DROP INDEX IF EXISTS authority_domain_unique; +DROP INDEX IF EXISTS authority_organization_id_index; +ALTER TABLE ONLY "authority" DROP CONSTRAINT IF EXISTS authority_organization_id_fkey; +ALTER TABLE "authority" DROP COLUMN IF EXISTS organization_id; + +DROP TABLE IF EXISTS "organizations"; +DROP TABLE IF EXISTS "partners"; diff --git a/migration/db/migrations/20260818100600000_backfill_client_ownership.sql b/migration/db/migrations/20260818100600000_backfill_organization_ownership.sql similarity index 63% rename from migration/db/migrations/20260818100600000_backfill_client_ownership.sql rename to migration/db/migrations/20260818100600000_backfill_organization_ownership.sql index f26b266b..35d7ed60 100644 --- a/migration/db/migrations/20260818100600000_backfill_client_ownership.sql +++ b/migration/db/migrations/20260818100600000_backfill_organization_ownership.sql @@ -2,10 +2,10 @@ -- SQL in section 'Up' is executed when this migration is applied -- --------------------------------------------------------------------------- --- PPT-526: backfill Partner/Client ownership for existing data. +-- PPT-526: backfill Partner/Organization ownership for existing data. -- -- Idempotent and additive: every statement only creates missing rows or fills --- NULL client_id columns, so it is safe to re-apply and safe on databases +-- NULL organization_id columns, so it is safe to re-apply and safe on databases -- where operators have already assigned ownership by hand. Where inference is -- ambiguous the row is deliberately LEFT NULL for a human to resolve (the -- org_zone convention is known to be non-exclusive and sometimes absent). @@ -13,15 +13,15 @@ -- What it does: -- 1. Ensures a management partner exists ("PlaceOS" — the platform -- operator's own organisation). --- 2. Creates one client-owned Client per Authority that has none, named +-- 2. Creates one organization-owned Organization per Authority that has none, named -- " ()" (domain uniqueness makes this collision -- free), and points the authority at it. Estates that span several --- authorities under one real-world client (e.g. NTT's two domains) are --- merged later by re-pointing authority.client_id by hand or API. --- 3. Zones: a zone belongs to the client of the authority whose +-- authorities under one real-world organization (e.g. NTT's two domains) are +-- merged later by re-pointing authority.organization_id by hand or API. +-- 3. Zones: a zone belongs to the organization of the authority whose -- config->>'org_zone' names the zone's ROOT zone — only when exactly one --- client is implied (shared org zones stay NULL). --- 4. Systems: the single distinct client of their zones, if unambiguous. +-- organization is implied (shared org zones stay NULL). +-- 4. Systems: the single distinct organization of their zones, if unambiguous. -- 5. Modules: logic modules via their control system; shared device/service -- modules via the systems that reference them, if unambiguous. -- 6. Trigger definitions: via their control system when system-scoped; @@ -38,34 +38,34 @@ SELECT 'PlaceOS', 'Platform operator (management partner)', true, now(), now() WHERE NOT EXISTS (SELECT 1 FROM "partners" WHERE management = true) ON CONFLICT DO NOTHING; --- 2. One client-owned Client per orphan Authority +-- 2. One organization-owned Organization per orphan Authority -- +micrate StatementBegin DO $$ DECLARE auth RECORD; - new_client UUID; + new_org UUID; BEGIN - FOR auth IN SELECT id, name, domain FROM "authority" WHERE client_id IS NULL LOOP - new_client := NULL; - INSERT INTO "clients" (name, description, partner_id, payer, created_at, updated_at) + FOR auth IN SELECT id, name, domain FROM "authority" WHERE organization_id IS NULL LOOP + new_org := NULL; + INSERT INTO "organizations" (name, description, partner_id, payer, created_at, updated_at) VALUES ( COALESCE(NULLIF(auth.name, ''), auth.domain) || ' (' || auth.domain || ')', - 'Auto-created from authority ' || auth.id || ' during PPT-526 client backfill', - NULL, 'client', now(), now() + 'Auto-created from authority ' || auth.id || ' during PPT-526 organization backfill', + NULL, 'organization', now(), now() ) ON CONFLICT DO NOTHING - RETURNING id INTO new_client; + RETURNING id INTO new_org; -- If the name already existed (re-run against a partially-backfilled DB), -- reuse the existing row rather than leaving the authority orphaned. - IF new_client IS NULL THEN - SELECT id INTO new_client FROM "clients" + IF new_org IS NULL THEN + SELECT id INTO new_org FROM "organizations" WHERE partner_id IS NULL AND name = COALESCE(NULLIF(auth.name, ''), auth.domain) || ' (' || auth.domain || ')'; END IF; - IF new_client IS NOT NULL THEN - UPDATE "authority" SET client_id = new_client WHERE id = auth.id; + IF new_org IS NOT NULL THEN + UPDATE "authority" SET organization_id = new_org WHERE id = auth.id; END IF; END LOOP; END $$; @@ -75,9 +75,9 @@ END $$; -- UNION (not UNION ALL) so accidental cycles in zone parentage terminate. -- Ambiguity is judged per TREE, not per org_zone string: every authority's -- org_zone claim is resolved to its tree root, a tree claimed by more than --- one distinct client is vetoed, and ownership is only assigned when at +-- one distinct organization is vetoed, and ownership is only assigned when at -- least one claim names the root itself (a claim on a sub-zone alone must --- not annex the whole tree). Rows whose (client_id, name) would collide +-- not annex the whole tree). Rows whose (organization_id, name) would collide -- with the partial unique indexes are skipped (left NULL for a human) — -- duplicate names within one estate are legacy race artifacts. -- +micrate StatementBegin @@ -93,125 +93,125 @@ WITH RECURSIVE zone_roots AS ( tree_claims AS ( SELECT r.root_id, (a.config->>'org_zone' = r.root_id) AS names_root, - a.client_id + a.organization_id FROM "authority" a INNER JOIN zone_roots r ON r.id = a.config->>'org_zone' WHERE COALESCE(a.config->>'org_zone', '') <> '' - AND a.client_id IS NOT NULL + AND a.organization_id IS NOT NULL ), org_owner AS ( - SELECT root_id, MIN(client_id::text)::uuid AS client_id + SELECT root_id, MIN(organization_id::text)::uuid AS organization_id FROM tree_claims GROUP BY root_id - HAVING COUNT(DISTINCT client_id) = 1 + HAVING COUNT(DISTINCT organization_id) = 1 AND bool_or(names_root) ), candidates AS ( - SELECT z.id, o.client_id, z.name, + SELECT z.id, o.organization_id, z.name, ROW_NUMBER() OVER ( - PARTITION BY o.client_id, z.name + PARTITION BY o.organization_id, z.name ORDER BY z.created_at, z.id ) AS rn FROM "zone" z INNER JOIN zone_roots r ON z.id = r.id INNER JOIN org_owner o ON r.root_id = o.root_id - WHERE z.client_id IS NULL + WHERE z.organization_id IS NULL ) UPDATE "zone" z -SET client_id = c.client_id +SET organization_id = c.organization_id FROM candidates c WHERE z.id = c.id AND c.rn = 1 AND NOT EXISTS ( SELECT 1 FROM "zone" x - WHERE x.client_id = c.client_id AND x.name = z.name AND x.id <> z.id + WHERE x.organization_id = c.organization_id AND x.name = z.name AND x.id <> z.id ); -- +micrate StatementEnd --- 4. Systems: single distinct client across their zones. Same collision --- skip as zones (sys carries a (client_id, name) partial unique index). +-- 4. Systems: single distinct organization across their zones. Same collision +-- skip as zones (sys carries a (organization_id, name) partial unique index). -- +micrate StatementBegin WITH sys_candidates AS ( SELECT s2.id AS sys_id, s2.name, - MIN(z.client_id::text)::uuid AS client_id + MIN(z.organization_id::text)::uuid AS organization_id FROM "sys" s2 INNER JOIN "zone" z ON z.id = ANY(s2.zones) - WHERE z.client_id IS NOT NULL - AND s2.client_id IS NULL + WHERE z.organization_id IS NOT NULL + AND s2.organization_id IS NULL GROUP BY s2.id, s2.name - HAVING COUNT(DISTINCT z.client_id) = 1 + HAVING COUNT(DISTINCT z.organization_id) = 1 ), ranked AS ( - SELECT sys_id, name, client_id, + SELECT sys_id, name, organization_id, ROW_NUMBER() OVER ( - PARTITION BY client_id, name + PARTITION BY organization_id, name ORDER BY sys_id ) AS rn FROM sys_candidates ) UPDATE "sys" s -SET client_id = r.client_id +SET organization_id = r.organization_id FROM ranked r WHERE s.id = r.sys_id AND r.rn = 1 AND NOT EXISTS ( SELECT 1 FROM "sys" x - WHERE x.client_id = r.client_id AND x.name = s.name AND x.id <> s.id + WHERE x.organization_id = r.organization_id AND x.name = s.name AND x.id <> s.id ); -- +micrate StatementEnd -- 5a. Logic modules via their control system UPDATE "mod" m -SET client_id = s.client_id +SET organization_id = s.organization_id FROM "sys" s WHERE m.control_system_id = s.id - AND s.client_id IS NOT NULL - AND m.client_id IS NULL; + AND s.organization_id IS NOT NULL + AND m.organization_id IS NULL; -- 5b. Device/service modules via the systems that reference them UPDATE "mod" m -SET client_id = sc.client_id +SET organization_id = sc.organization_id FROM ( - SELECT m2.id AS mod_id, MIN(s.client_id::text)::uuid AS client_id + SELECT m2.id AS mod_id, MIN(s.organization_id::text)::uuid AS organization_id FROM "mod" m2 INNER JOIN "sys" s ON m2.id = ANY(s.modules) - WHERE s.client_id IS NOT NULL + WHERE s.organization_id IS NOT NULL GROUP BY m2.id - HAVING COUNT(DISTINCT s.client_id) = 1 + HAVING COUNT(DISTINCT s.organization_id) = 1 ) sc -WHERE m.id = sc.mod_id AND m.client_id IS NULL; +WHERE m.id = sc.mod_id AND m.organization_id IS NULL; -- 6. System-scoped trigger definitions UPDATE "trigger" t -SET client_id = s.client_id +SET organization_id = s.organization_id FROM "sys" s WHERE t.control_system_id = s.id - AND s.client_id IS NOT NULL - AND t.client_id IS NULL; + AND s.organization_id IS NOT NULL + AND t.organization_id IS NULL; -- 7. Edges via their bound user's authority. Same collision skip (edge --- carries a (client_id, name) partial unique index). +-- carries a (organization_id, name) partial unique index). -- +micrate StatementBegin WITH edge_candidates AS ( - SELECT e.id, e.name, a.client_id, + SELECT e.id, e.name, a.organization_id, ROW_NUMBER() OVER ( - PARTITION BY a.client_id, e.name + PARTITION BY a.organization_id, e.name ORDER BY e.id ) AS rn FROM "edge" e INNER JOIN "user" u ON e.user_id = u.id INNER JOIN "authority" a ON u.authority_id = a.id - WHERE a.client_id IS NOT NULL - AND e.client_id IS NULL + WHERE a.organization_id IS NOT NULL + AND e.organization_id IS NULL ) UPDATE "edge" e -SET client_id = c.client_id +SET organization_id = c.organization_id FROM edge_candidates c WHERE e.id = c.id AND c.rn = 1 AND NOT EXISTS ( SELECT 1 FROM "edge" x - WHERE x.client_id = c.client_id AND x.name = e.name AND x.id <> e.id + WHERE x.organization_id = c.organization_id AND x.name = e.name AND x.id <> e.id ); -- +micrate StatementEnd diff --git a/migration/db/migrations/20260819100500000_add_grants.sql b/migration/db/migrations/20260819100500000_add_grants.sql index 521c15f4..f7073c09 100644 --- a/migration/db/migrations/20260819100500000_add_grants.sql +++ b/migration/db/migrations/20260819100500000_add_grants.sql @@ -8,12 +8,12 @@ -- PPT-526 Stage 3: the authorization `grants` table (Zanzibar-lite tuple). -- -- A grant gives a user a permission bitmask over a scope, which is one of a --- Partner, a Client, or an Authority. Authorization walks UP from the touched --- resource (authority -> its client -> that client's partner) and ORs every +-- Partner, a Organization, or an Authority. Authorization walks UP from the touched +-- resource (authority -> its organization -> that organization's partner) and ORs every -- live grant found on the chain, so a single grant at partner scope applies to --- all of that partner's clients, current and future (decision b, 2026-08-19). +-- all of that partner's organizations, current and future (decision b, 2026-08-19). -- --- `scope_id` is polymorphic (a partner/client UUID as text, or an authority +-- `scope_id` is polymorphic (a partner/organization UUID as text, or an authority -- TEXT id), so it carries no DB foreign key. A grant naming a deleted scope is -- inert: resolution walks up from live resources and never matches it, so -- orphan grants are harmless and can be swept lazily. The one real FK is @@ -25,7 +25,7 @@ CREATE TABLE IF NOT EXISTS "grants"( id UUID PRIMARY KEY DEFAULT uuidv7(), user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE, - scope_type TEXT NOT NULL CHECK (scope_type IN ('partner', 'client', 'authority')), + scope_type TEXT NOT NULL CHECK (scope_type IN ('partner', 'organization', 'authority')), scope_id TEXT NOT NULL, permissions INTEGER NOT NULL DEFAULT 0, expires_at TIMESTAMPTZ, @@ -43,7 +43,7 @@ CREATE UNIQUE INDEX IF NOT EXISTS grants_user_scope_unique CREATE INDEX IF NOT EXISTS grants_user_id_index ON "grants" USING BTREE (user_id); --- "who can reach this scope" (partner/client admin console, audit). +-- "who can reach this scope" (partner/organization admin console, audit). CREATE INDEX IF NOT EXISTS grants_scope_index ON "grants" USING BTREE (scope_type, scope_id); diff --git a/spec/client_spec.cr b/spec/client_spec.cr deleted file mode 100644 index e0f8bb36..00000000 --- a/spec/client_spec.cr +++ /dev/null @@ -1,104 +0,0 @@ -require "./helper" - -module PlaceOS::Model - describe Client do - Spec.before_each do - ControlSystem.clear - Zone.clear - Authority.clear - Client.clear - Partner.clear - end - - it "saves a partnered client with partner-pays default" do - partner = Generator.partner.save! - client = Generator.client(partner: partner).save! - client.persisted?.should be_true - client.payer.should eq Client::PAYER_PARTNER - client.client_owned?.should be_false - client.partner.try(&.id).should eq partner.id - end - - it "normalizes a client-owned client to pay for itself" do - client = Generator.client.save! - client.partner_id.should be_nil - client.payer.should eq Client::PAYER_CLIENT - client.client_owned?.should be_true - end - - it "rejects an unknown payer" do - client = Generator.client(partner: Generator.partner.save!, payer: "nobody") - client.valid?.should be_false - client.errors.map(&.field).should contain(:payer) - end - - it "scopes client name uniqueness to the partner" do - partner_a = Generator.partner.save! - partner_b = Generator.partner.save! - original = Generator.client(partner: partner_a).save! - - # Same name under a different partner is fine - sibling = Generator.client(partner: partner_b) - sibling.name = original.name - sibling.valid?.should be_true - - # Same name under the same partner is not - duplicate = Generator.client(partner: partner_a) - duplicate.name = original.name - duplicate.valid?.should be_false - duplicate.errors.map(&.field).should contain(:name) - end - - it "rejects duplicate names among client-owned clients" do - original = Generator.client.save! - duplicate = Generator.client - duplicate.name = original.name - duplicate.valid?.should be_false - duplicate.errors.map(&.field).should contain(:name) - end - - it "owns authorities via authority.client_id" do - client = Generator.client.save! - authority = Generator.authority(domain: "client-spec.example.com") - authority.client_id = client.id - authority.save! - - authority.client.try(&.id).should eq client.id - client.authorities.to_a.map(&.id).should eq [authority.id] - end - - it "refuses to delete a client that still owns a domain" do - client = Generator.client.save! - authority = Generator.authority(domain: "client-restrict.example.com") - authority.client_id = client.id - authority.save! - - expect_raises(Exception, /foreign key/) { client.destroy } - Client.find?(client.id.not_nil!).should_not be_nil - end - - it "rejects renaming a client onto a sibling's name" do - partner = Generator.partner.save! - original = Generator.client(partner: partner).save! - sibling = Generator.client(partner: partner).save! - - sibling.name = original.name - sibling.valid?.should be_false - sibling.errors.map(&.field).should contain(:name) - end - - it "records client ownership on zones and systems" do - client = Generator.client.save! - zone = Generator.zone - zone.client_id = client.id - zone.save! - - sys = Generator.control_system - sys.client_id = client.id - sys.save! - - Zone.find!(zone.id.not_nil!).client.try(&.id).should eq client.id - ControlSystem.find!(sys.id.not_nil!).client.try(&.id).should eq client.id - end - end -end diff --git a/spec/generator.cr b/spec/generator.cr index b6115f30..f3b55d42 100644 --- a/spec/generator.cr +++ b/spec/generator.cr @@ -574,8 +574,8 @@ module PlaceOS::Model ) end - def self.client(partner : Partner? = nil, payer : String = Client::PAYER_PARTNER) - Client.new( + def self.organization(partner : Partner? = nil, payer : String = Organization::PAYER_PARTNER) + Organization.new( name: Faker::Hacker.noun + "-" + RANDOM.hex(3), partner_id: partner.try(&.id), payer: payer, diff --git a/spec/grant_spec.cr b/spec/grant_spec.cr index 9c2f2988..ed9bce3d 100644 --- a/spec/grant_spec.cr +++ b/spec/grant_spec.cr @@ -1,14 +1,14 @@ require "./helper" -# Build partner -> client -> authority -> user, returning all four. -private def build_estate(payer = PlaceOS::Model::Client::PAYER_PARTNER) +# Build partner -> org -> authority -> user, returning all four. +private def build_estate(payer = PlaceOS::Model::Organization::PAYER_PARTNER) partner = PlaceOS::Model::Generator.partner.save! - client = PlaceOS::Model::Generator.client(partner: partner, payer: payer).save! + org = PlaceOS::Model::Generator.organization(partner: partner, payer: payer).save! authority = PlaceOS::Model::Generator.authority(domain: "grant-#{RANDOM.hex(4)}.example.com") - authority.client_id = client.id + authority.organization_id = org.id authority.save! user = PlaceOS::Model::Generator.user(authority: authority).save! - {partner, client, authority, user} + {partner, org, authority, user} end module PlaceOS::Model @@ -17,13 +17,13 @@ module PlaceOS::Model Grant.clear Authority.clear User.clear - Client.clear + Organization.clear Partner.clear end it "saves a grant with a permission bitmask" do - _, client, _, user = build_estate - grant = Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Manage).save! + _, org, _, user = build_estate + grant = Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Manage).save! grant.persisted?.should be_true grant.permission_flags.should eq Permissions::Manage end @@ -41,21 +41,21 @@ module PlaceOS::Model Grant.resolve(user.id.not_nil!, authority).should eq Permissions::Update end - it "resolves a client-scope grant onto the client's authority" do - _, client, authority, user = build_estate - Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Operate).save! + it "resolves a org-scope grant onto the org's authority" do + _, org, authority, user = build_estate + Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Operate).save! Grant.resolve(user.id.not_nil!, authority).should eq Permissions::Operate end it "resolves a partner-scope grant onto every authority under that partner (decision b)" do partner = Generator.partner.save! - client_a = Generator.client(partner: partner).save! - client_b = Generator.client(partner: partner).save! + client_a = Generator.organization(partner: partner).save! + client_b = Generator.organization(partner: partner).save! auth_a = Generator.authority(domain: "a-#{RANDOM.hex(4)}.example.com") - auth_a.client_id = client_a.id + auth_a.organization_id = client_a.id auth_a.save! auth_b = Generator.authority(domain: "b-#{RANDOM.hex(4)}.example.com") - auth_b.client_id = client_b.id + auth_b.organization_id = client_b.id auth_b.save! staff = Generator.user(authority: auth_a).save! @@ -66,9 +66,9 @@ module PlaceOS::Model end it "ORs permissions across scopes on the chain" do - partner, client, authority, user = build_estate + partner, org, authority, user = build_estate Generator.grant(user, Grant::SCOPE_PARTNER, partner.id.not_nil!.to_s, Permissions::Read).save! - Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Update).save! + Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Update).save! Grant.resolve(user.id.not_nil!, authority).should eq(Permissions::Read | Permissions::Update) end @@ -81,15 +81,15 @@ module PlaceOS::Model end it "ignores expired grants" do - _, client, authority, user = build_estate - Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Manage, + _, org, authority, user = build_estate + Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Manage, expires_at: Time.utc - 1.hour).save! Grant.resolve(user.id.not_nil!, authority).should eq Permissions::None end it "honours a future expiry" do - _, client, authority, user = build_estate - Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s, Permissions::Read, + _, org, authority, user = build_estate + Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Read, expires_at: Time.utc + 1.hour).save! Grant.resolve(user.id.not_nil!, authority).should eq Permissions::Read end @@ -100,8 +100,8 @@ module PlaceOS::Model end it "cascades on user delete" do - _, client, _, user = build_estate - grant = Generator.grant(user, Grant::SCOPE_CLIENT, client.id.not_nil!.to_s).save! + _, org, _, user = build_estate + grant = Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s).save! user.destroy Grant.find?(grant.id.not_nil!).should be_nil end diff --git a/spec/helper.cr b/spec/helper.cr index b4fa95fc..44f3dd34 100644 --- a/spec/helper.cr +++ b/spec/helper.cr @@ -40,7 +40,7 @@ Spec.after_suite do PlaceOS::Model::GroupPlaylist, PlaceOS::Model::Group, PlaceOS::Model::Grant, - PlaceOS::Model::Client, + PlaceOS::Model::Organization, PlaceOS::Model::Partner, ].each(&.clear) end diff --git a/spec/organization_spec.cr b/spec/organization_spec.cr new file mode 100644 index 00000000..8d166f49 --- /dev/null +++ b/spec/organization_spec.cr @@ -0,0 +1,104 @@ +require "./helper" + +module PlaceOS::Model + describe Organization do + Spec.before_each do + ControlSystem.clear + Zone.clear + Authority.clear + Organization.clear + Partner.clear + end + + it "saves a partnered org with partner-pays default" do + partner = Generator.partner.save! + org = Generator.organization(partner: partner).save! + org.persisted?.should be_true + org.payer.should eq Organization::PAYER_PARTNER + org.self_managed?.should be_false + org.partner.try(&.id).should eq partner.id + end + + it "normalizes a org-owned org to pay for itself" do + org = Generator.organization.save! + org.partner_id.should be_nil + org.payer.should eq Organization::PAYER_ORGANIZATION + org.self_managed?.should be_true + end + + it "rejects an unknown payer" do + org = Generator.organization(partner: Generator.partner.save!, payer: "nobody") + org.valid?.should be_false + org.errors.map(&.field).should contain(:payer) + end + + it "scopes org name uniqueness to the partner" do + partner_a = Generator.partner.save! + partner_b = Generator.partner.save! + original = Generator.organization(partner: partner_a).save! + + # Same name under a different partner is fine + sibling = Generator.organization(partner: partner_b) + sibling.name = original.name + sibling.valid?.should be_true + + # Same name under the same partner is not + duplicate = Generator.organization(partner: partner_a) + duplicate.name = original.name + duplicate.valid?.should be_false + duplicate.errors.map(&.field).should contain(:name) + end + + it "rejects duplicate names among org-owned clients" do + original = Generator.organization.save! + duplicate = Generator.organization + duplicate.name = original.name + duplicate.valid?.should be_false + duplicate.errors.map(&.field).should contain(:name) + end + + it "owns authorities via authority.organization_id" do + org = Generator.organization.save! + authority = Generator.authority(domain: "org-spec.example.com") + authority.organization_id = org.id + authority.save! + + authority.organization.try(&.id).should eq org.id + org.authorities.to_a.map(&.id).should eq [authority.id] + end + + it "refuses to delete a org that still owns a domain" do + org = Generator.organization.save! + authority = Generator.authority(domain: "org-restrict.example.com") + authority.organization_id = org.id + authority.save! + + expect_raises(Exception, /foreign key/) { org.destroy } + Organization.find?(org.id.not_nil!).should_not be_nil + end + + it "rejects renaming a org onto a sibling's name" do + partner = Generator.partner.save! + original = Generator.organization(partner: partner).save! + sibling = Generator.organization(partner: partner).save! + + sibling.name = original.name + sibling.valid?.should be_false + sibling.errors.map(&.field).should contain(:name) + end + + it "records org ownership on zones and systems" do + org = Generator.organization.save! + zone = Generator.zone + zone.organization_id = org.id + zone.save! + + sys = Generator.control_system + sys.organization_id = org.id + sys.save! + + Zone.find!(zone.id.not_nil!).organization.try(&.id).should eq org.id + ControlSystem.find!(sys.id.not_nil!).organization.try(&.id).should eq org.id + end + end +end diff --git a/spec/partner_spec.cr b/spec/partner_spec.cr index 914502e2..492c98ab 100644 --- a/spec/partner_spec.cr +++ b/spec/partner_spec.cr @@ -6,7 +6,7 @@ module PlaceOS::Model ControlSystem.clear Zone.clear Authority.clear - Client.clear + Organization.clear Partner.clear end @@ -54,14 +54,14 @@ module PlaceOS::Model it "lists its clients" do partner = Generator.partner.save! - client = Generator.client(partner: partner).save! - Generator.client.save! - partner.clients.to_a.map(&.id).should eq [client.id] + org = Generator.organization(partner: partner).save! + Generator.organization.save! + partner.organizations.to_a.map(&.id).should eq [org.id] end it "refuses to delete a partner that still has clients" do partner = Generator.partner.save! - Generator.client(partner: partner).save! + Generator.organization(partner: partner).save! expect_raises(Exception, /foreign key/) { partner.destroy } Partner.find?(partner.id.not_nil!).should_not be_nil diff --git a/src/placeos-models/authority.cr b/src/placeos-models/authority.cr index 29cd4f48..dd990514 100644 --- a/src/placeos-models/authority.cr +++ b/src/placeos-models/authority.cr @@ -32,9 +32,9 @@ module PlaceOS::Model attribute email_domains : Array(String) = [] of String - # PPT-526: the Client (customer organisation) that owns this domain. + # PPT-526: the Organization (customer organisation) that owns this domain. # Nullable while ownership backfill and provisioning are phased in. - attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false macro finished # Ensure only the host is saved. @@ -81,9 +81,9 @@ module PlaceOS::Model Authority.where(domain: host).first? end - # The owning Client, when ownership has been assigned. - def client : PlaceOS::Model::Client? - self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + # The owning Organization, when ownership has been assigned. + def organization : PlaceOS::Model::Organization? + self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } end # Locates an authority by email domain diff --git a/src/placeos-models/broker.cr b/src/placeos-models/broker.cr index 0677195a..f643fd8e 100644 --- a/src/placeos-models/broker.cr +++ b/src/placeos-models/broker.cr @@ -33,14 +33,14 @@ module PlaceOS::Model # Matches will be replaced with a hmac_256(secret, match). attribute filters : Array(String) = -> { [] of String } - # PPT-526: the Client (customer organisation) that owns this broker. + # PPT-526: the Organization (customer organisation) that owns this broker. # NULL = cluster-level infrastructure (the default; the backfill never # assigns brokers). Nullable while query enforcement is phased in. - attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Client, when ownership has been assigned. - def client : PlaceOS::Model::Client? - self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + # The owning Organization, when ownership has been assigned. + def organization : PlaceOS::Model::Organization? + self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } end # Validation diff --git a/src/placeos-models/control_system.cr b/src/placeos-models/control_system.cr index ce3995f6..bb43fe52 100644 --- a/src/placeos-models/control_system.cr +++ b/src/placeos-models/control_system.cr @@ -46,13 +46,13 @@ module PlaceOS::Model # Array of security group ids for room access attribute security_groups : Array(String) = -> { [] of String } - # PPT-526: the Client (customer organisation) that owns this system. + # PPT-526: the Organization (customer organisation) that owns this system. # Nullable while ownership backfill and query enforcement are phased in. - attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Client, when ownership has been assigned. - def client : PlaceOS::Model::Client? - self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + # The owning Organization, when ownership has been assigned. + def organization : PlaceOS::Model::Organization? + self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } end attribute timezone : Time::Location?, converter: Time::Location::Converter, es_type: "text" diff --git a/src/placeos-models/edge.cr b/src/placeos-models/edge.cr index 3909ff8d..d703d1bb 100644 --- a/src/placeos-models/edge.cr +++ b/src/placeos-models/edge.cr @@ -20,13 +20,13 @@ module PlaceOS::Model attribute last_seen : Time?, converter: Time::EpochConverterOptional, mass_assignment: false attribute online : Bool = false, mass_assignment: false - # PPT-526: the Client (customer organisation) that owns this edge node. + # PPT-526: the Organization (customer organisation) that owns this edge node. # Nullable while ownership backfill and query enforcement are phased in. - attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Client, when ownership has been assigned. - def client : PlaceOS::Model::Client? - self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + # The owning Organization, when ownership has been assigned. + def organization : PlaceOS::Model::Organization? + self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } end @[JSON::Field(ignore: true)] diff --git a/src/placeos-models/grant.cr b/src/placeos-models/grant.cr index 66243003..459830c4 100644 --- a/src/placeos-models/grant.cr +++ b/src/placeos-models/grant.cr @@ -4,30 +4,30 @@ require "uuid/json" require "./base/model" require "./permissions" require "./authority" -require "./client" +require "./organization" require "./partner" module PlaceOS::Model # PPT-526 Stage 3: a cross-tenant authorization grant. # - # Gives a user a `Permissions` bitmask over one scope — a Partner, a Client, + # Gives a user a `Permissions` bitmask over one scope — a Partner, an Organization, # or an Authority. Authorization resolves by walking UP from the touched - # resource: authority -> its client -> that client's partner. A grant at - # partner scope therefore covers every one of that partner's clients, current - # and future (the NTT-over-its-clients case); a grant at client scope covers - # that client's authorities; a grant at authority scope is a single domain. + # resource: authority -> its organization -> that organization's partner. A grant at + # partner scope therefore covers every one of that partner's organizations, current + # and future (the NTT-over-its-clients case); a grant at organization scope covers + # that organization's authorities; a grant at authority scope is a single domain. # - # `scope_id` is polymorphic (a Partner/Client UUID as text, or an Authority + # `scope_id` is polymorphic (a Partner/Organization UUID as text, or an Authority # TEXT id) so it carries no FK; a grant naming a deleted scope is inert. class Grant < ::PgORM::Base include PgORM::Timestamps table :grants - SCOPE_PARTNER = "partner" - SCOPE_CLIENT = "client" - SCOPE_AUTHORITY = "authority" - SCOPE_TYPES = [SCOPE_PARTNER, SCOPE_CLIENT, SCOPE_AUTHORITY] + SCOPE_PARTNER = "partner" + SCOPE_ORGANIZATION = "organization" + SCOPE_AUTHORITY = "authority" + SCOPE_TYPES = [SCOPE_PARTNER, SCOPE_ORGANIZATION, SCOPE_AUTHORITY] default_primary_key id : UUID, autogenerated: true @@ -78,7 +78,7 @@ module PlaceOS::Model # ------------------------------------------------------------------ # Effective permissions a user holds over `authority`, resolved by walking - # up authority -> client -> partner and OR-ing every live grant on the + # up authority -> organization -> partner and OR-ing every live grant on the # chain. Explicit grants only; the management-partner "support sees all" # rule is applied by the enforcement layer, not here. def self.resolve(user_id : String, authority : Authority, at : Time = Time.utc) : Permissions @@ -93,13 +93,13 @@ module PlaceOS::Model end # The (scope_type, scope_id) pairs to check for a given authority, from - # most specific to least: the authority itself, its client, that client's + # most specific to least: the authority itself, its organization, that organization's # partner. Missing links are simply absent. def self.scope_chain(authority : Authority) : Array({String, String}) chain = [{SCOPE_AUTHORITY, authority.id.to_s}] - if (client_id = authority.client_id) - chain << {SCOPE_CLIENT, client_id.to_s} - if (client = Client.find?(client_id)) && (partner_id = client.partner_id) + if (organization_id = authority.organization_id) + chain << {SCOPE_ORGANIZATION, organization_id.to_s} + if (organization = Organization.find?(organization_id)) && (partner_id = organization.partner_id) chain << {SCOPE_PARTNER, partner_id.to_s} end end @@ -127,7 +127,7 @@ module PlaceOS::Model Grant.where(user_id: user_id).select(&.live?) end - # Everyone granted access to a specific scope (partner/client admin console). + # Everyone granted access to a specific scope (partner/organization admin console). def self.for_scope(scope_type : String, scope_id : String) : Array(Grant) Grant.where(scope_type: scope_type, scope_id: scope_id).to_a end diff --git a/src/placeos-models/module.cr b/src/placeos-models/module.cr index 4ff1764b..f0d5865c 100644 --- a/src/placeos-models/module.cr +++ b/src/placeos-models/module.cr @@ -52,15 +52,15 @@ module PlaceOS::Model attribute ignore_connected : Bool = false attribute ignore_startstop : Bool = false - # PPT-526: the Client (customer organisation) that owns this module. + # PPT-526: the Organization (customer organisation) that owns this module. # Nullable while ownership backfill and query enforcement are phased in; - # shared device/service modules referenced by several clients' systems + # shared device/service modules referenced by several organizations' systems # stay NULL until a sharing policy is decided. - attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Client, when ownership has been assigned. - def client : PlaceOS::Model::Client? - self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + # The owning Organization, when ownership has been assigned. + def organization : PlaceOS::Model::Organization? + self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } end # Runtime Error Indicators diff --git a/src/placeos-models/client.cr b/src/placeos-models/organization.cr similarity index 57% rename from src/placeos-models/client.cr rename to src/placeos-models/organization.cr index f211c448..5294211b 100644 --- a/src/placeos-models/client.cr +++ b/src/placeos-models/organization.cr @@ -6,22 +6,23 @@ require "./partner" module PlaceOS::Model # A customer organisation (e.g. UCLA, Acadian) — the estate owner in the - # PPT-526 hierarchy: Partner -> Client -> Authority (domain) -> ... + # PPT-526 hierarchy: Partner -> Organization -> Authority (domain) -> ... + # This is the entity the multi-tenancy-template calls "Organization". # # `partner_id` NULL means client-owned: the customer signed up and manages # itself without an integrator. `payer` records who receives invoices for - # this client: the partner (integrator pays us and re-bills — the default - # channel model) or the client directly. A client without a partner can - # only pay for itself; `normalize_payer` keeps that invariant ahead of the - # DB CHECK constraint. - class Client < ::PgORM::Base + # this organization: the partner (integrator pays us and re-bills — the + # default channel model) or the organization directly. An organization + # without a partner can only pay for itself; `normalize_payer` keeps that + # invariant ahead of the DB CHECK constraint. + class Organization < ::PgORM::Base include PgORM::Timestamps - table :clients + table :organizations - PAYER_PARTNER = "partner" - PAYER_CLIENT = "client" - PAYERS = [PAYER_PARTNER, PAYER_CLIENT] + PAYER_PARTNER = "partner" + PAYER_ORGANIZATION = "organization" + PAYERS = [PAYER_PARTNER, PAYER_ORGANIZATION] default_primary_key id : UUID, autogenerated: true @@ -37,35 +38,35 @@ module PlaceOS::Model validates :name, presence: true - validate ->(this : Client) { + validate ->(this : Organization) { unless PAYERS.includes?(this.payer) this.validation_error(:payer, "must be one of #{PAYERS.join(", ")}") end } - validate ->(this : Client) { + validate ->(this : Organization) { # Friendlier error ahead of the DB's partial unique indexes: names are - # unique within a partner's book, and unique among client-owned clients. + # unique within a partner's book, and unique among client-owned orgs. name = this.name return if name.nil? || name.empty? - existing = Client.where(partner_id: this.partner_id, name: name).first? + existing = Organization.where(partner_id: this.partner_id, name: name).first? return if existing.nil? return if this.persisted? && existing.id == this.id - this.validation_error(:name, "a client with this name already exists") + this.validation_error(:name, "an organization with this name already exists") } protected def normalize_payer - self.payer = PAYER_CLIENT if self.partner_id.nil? + self.payer = PAYER_ORGANIZATION if self.partner_id.nil? end - # True when the customer manages itself without an integrator. - def client_owned? : Bool + # True when the customer manages itself without an integrator (no partner). + def self_managed? : Bool self.partner_id.nil? end - # Domains (authorities) owned by this client. + # Domains (authorities) owned by this organization. def authorities - Authority.where(client_id: self.id) + Authority.where(organization_id: self.id) end end end diff --git a/src/placeos-models/partner.cr b/src/placeos-models/partner.cr index 25927ae7..82325f08 100644 --- a/src/placeos-models/partner.cr +++ b/src/placeos-models/partner.cr @@ -64,9 +64,9 @@ module PlaceOS::Model Partner.where(parent_id: self.id) end - # Clients under this partner's book of business. - def clients - Client.where(partner_id: self.id) + # Organizations under this partner's book of business. + def organizations + Organization.where(partner_id: self.id) end end end diff --git a/src/placeos-models/trigger.cr b/src/placeos-models/trigger.cr index c16433c2..6b6f2614 100644 --- a/src/placeos-models/trigger.cr +++ b/src/placeos-models/trigger.cr @@ -30,14 +30,14 @@ module PlaceOS::Model METHODS = %w(GET POST PUT PATCH DELETE) attribute supported_methods : Array(String) = ["POST"] - # PPT-526: the Client (customer organisation) that owns this trigger + # PPT-526: the Organization (customer organisation) that owns this trigger # definition. NULL = shared/cluster-wide definition. Nullable while # ownership backfill and query enforcement are phased in. - attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Client, when ownership has been assigned. - def client : PlaceOS::Model::Client? - self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + # The owning Organization, when ownership has been assigned. + def organization : PlaceOS::Model::Organization? + self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } end # Association diff --git a/src/placeos-models/zone.cr b/src/placeos-models/zone.cr index b8256e0c..6a67fe22 100644 --- a/src/placeos-models/zone.cr +++ b/src/placeos-models/zone.cr @@ -52,13 +52,13 @@ module PlaceOS::Model attribute images : Array(String) = [] of String attribute playlists : Array(String) = [] of String, es_type: "keyword" - # PPT-526: the Client (customer organisation) that owns this zone. + # PPT-526: the Organization (customer organisation) that owns this zone. # Nullable while ownership backfill and query enforcement are phased in. - attribute client_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Client, when ownership has been assigned. - def client : PlaceOS::Model::Client? - self.client_id.try { |id| PlaceOS::Model::Client.find?(id) } + # The owning Organization, when ownership has been assigned. + def organization : PlaceOS::Model::Organization? + self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } end attribute place_id : String? From 6f1f5cb16f7ec80874ce83975993d7060f1798b3 Mon Sep 17 00:00:00 2001 From: Cameron Reeves Date: Wed, 7 Oct 2026 11:57:55 +1100 Subject: [PATCH 04/23] refactor: PPT-526 spell Organisation and renumber the tenancy migrations above master Cam's call on 7 Oct 2026: the entity is Organisation everywhere (table organisations, column organisation_id, grant scope organisation). The three migrations move from 20260818/19 ids to 20261007100500000, 20261007100600000 and 20261007100700000 so they sort after 20261001100500000, the newest migration on master. --- ...0500000_add_partners_and_organizations.sql | 211 ------------------ ...0500000_add_partners_and_organisations.sql | 211 ++++++++++++++++++ ...00000_backfill_organisation_ownership.sql} | 110 ++++----- ...s.sql => 20261007100700000_add_grants.sql} | 12 +- spec/generator.cr | 4 +- spec/grant_spec.cr | 28 +-- spec/helper.cr | 2 +- ...anization_spec.cr => organisation_spec.cr} | 52 ++--- spec/partner_spec.cr | 10 +- src/placeos-models/authority.cr | 10 +- src/placeos-models/broker.cr | 10 +- src/placeos-models/control_system.cr | 10 +- src/placeos-models/edge.cr | 10 +- src/placeos-models/grant.cr | 30 +-- src/placeos-models/module.cr | 12 +- .../{organization.cr => organisation.cr} | 30 +-- src/placeos-models/partner.cr | 6 +- src/placeos-models/trigger.cr | 10 +- src/placeos-models/zone.cr | 10 +- 19 files changed, 389 insertions(+), 389 deletions(-) delete mode 100644 migration/db/migrations/20260818100500000_add_partners_and_organizations.sql create mode 100644 migration/db/migrations/20261007100500000_add_partners_and_organisations.sql rename migration/db/migrations/{20260818100600000_backfill_organization_ownership.sql => 20261007100600000_backfill_organisation_ownership.sql} (67%) rename migration/db/migrations/{20260819100500000_add_grants.sql => 20261007100700000_add_grants.sql} (87%) rename spec/{organization_spec.cr => organisation_spec.cr} (62%) rename src/placeos-models/{organization.cr => organisation.cr} (68%) diff --git a/migration/db/migrations/20260818100500000_add_partners_and_organizations.sql b/migration/db/migrations/20260818100500000_add_partners_and_organizations.sql deleted file mode 100644 index 524e9084..00000000 --- a/migration/db/migrations/20260818100500000_add_partners_and_organizations.sql +++ /dev/null @@ -1,211 +0,0 @@ --- +micrate Up --- SQL in section 'Up' is executed when this migration is applied - --- MERGE-TIME CHECK: micrate refuses out-of-order version ids (see models#323). --- If any later-dated migration lands on master before this merges, renumber --- this file AND 20260818100600000 above it (preserving schema-before-backfill --- order). Safe: neither has been applied anywhere and the backfill is --- idempotent. - --- --------------------------------------------------------------------------- --- PPT-526: the Partner → Organization → Authority(domain) hierarchy. --- --- partners: integrators/resellers (e.g. NTT). `management = true` marks the --- platform operator's own organisation (PlaceOS staff) — the "management --- organization" concept from the ticket, done at the partner level. `parent_id` --- reserves a 2-tier channel (distributor → reseller) without any UI or --- enforcement yet. --- --- organizations: the customer organisation (e.g. UCLA, Acadian). `partner_id` NULL --- means organization-owned (self-managed, no integrator). `payer` records who is --- invoiced: 'partner' (integrator pays us and re-bills, the default channel --- model) or 'organization' (direct). A organization without a partner can only pay for --- itself — enforced by CHECK. --- --- Every delete path is RESTRICT: removing a partner/organization must go through an --- orchestrated teardown (the PPT-1203 pattern), never a silent DB cascade — --- model-level cleanup callbacks do not fire on DB cascades. --- --------------------------------------------------------------------------- -CREATE TABLE IF NOT EXISTS "partners"( - id UUID PRIMARY KEY DEFAULT uuidv7(), - name TEXT NOT NULL, - description TEXT NOT NULL DEFAULT '', - management BOOLEAN NOT NULL DEFAULT false, - parent_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, - config JSONB NOT NULL DEFAULT '{}', - created_at TIMESTAMPTZ NOT NULL, - updated_at TIMESTAMPTZ NOT NULL -); - -CREATE UNIQUE INDEX IF NOT EXISTS partners_name_unique - ON "partners" USING BTREE (name); -CREATE INDEX IF NOT EXISTS partners_parent_id_index - ON "partners" USING BTREE (parent_id); - -CREATE TABLE IF NOT EXISTS "organizations"( - id UUID PRIMARY KEY DEFAULT uuidv7(), - name TEXT NOT NULL, - description TEXT NOT NULL DEFAULT '', - partner_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, - payer TEXT NOT NULL DEFAULT 'partner' - CHECK (payer IN ('partner', 'organization')), - config JSONB NOT NULL DEFAULT '{}', - created_at TIMESTAMPTZ NOT NULL, - updated_at TIMESTAMPTZ NOT NULL, - CONSTRAINT organizations_payer_requires_partner - CHECK (partner_id IS NOT NULL OR payer = 'organization') -); - --- Organization names are unique within a partner's book of business, and unique --- among organization-owned organizations. Two partial indexes because UNIQUE treats --- NULLs as distinct — a plain UNIQUE (partner_id, name) would let every --- organization-owned organization share a name. -CREATE UNIQUE INDEX IF NOT EXISTS organizations_name_unique_per_partner - ON "organizations" USING BTREE (partner_id, name) WHERE partner_id IS NOT NULL; -CREATE UNIQUE INDEX IF NOT EXISTS organizations_name_unique_owned - ON "organizations" USING BTREE (name) WHERE partner_id IS NULL; -CREATE INDEX IF NOT EXISTS organizations_partner_id_index - ON "organizations" USING BTREE (partner_id); - --- --------------------------------------------------------------------------- --- Authority → Organization ownership. Nullable at the DB level for backwards --- compatibility (init seeds authorities before any organization exists); the --- provisioning flow and backfill populate it. RESTRICT so a organization cannot be --- deleted while it still owns domains. --- --------------------------------------------------------------------------- -ALTER TABLE "authority" - ADD COLUMN IF NOT EXISTS organization_id UUID; - -ALTER TABLE ONLY "authority" - DROP CONSTRAINT IF EXISTS authority_organization_id_fkey; -ALTER TABLE ONLY "authority" - ADD CONSTRAINT authority_organization_id_fkey - FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; - -CREATE INDEX IF NOT EXISTS authority_organization_id_index - ON "authority" USING BTREE (organization_id); - --- The domain column has only ever had model-level uniqueness (a plain BTREE --- index) — a concurrent-signup race can create duplicate authorities. Make it --- a hard guarantee; self-service signup depends on it. --- --- Quarantine first: exact-duplicate domains left behind by that race would --- make the unique index unbuildable and (because micrate autocommits each --- statement) leave this migration half-applied. Keep the oldest row per --- domain and rename the rest so they stop answering for the domain — --- find_by_domain picks an arbitrary row across duplicates today, so this --- cannot break a reliably-working login. Idempotent: renamed rows no longer --- collide. Renamed rows are for an operator to merge or delete. -UPDATE "authority" a -SET domain = a.domain || '.duplicate.' || a.id -WHERE EXISTS ( - SELECT 1 FROM "authority" b - WHERE b.domain = a.domain - AND (b.created_at, b.id) < (a.created_at, a.id) -); - -CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique - ON "authority" USING BTREE (domain); - --- --------------------------------------------------------------------------- --- Organization ownership columns on the (previously cluster-global) control plane. --- Nullable: populated by the backfill migration where inference is --- unambiguous, and by the provisioning flow for everything new. Query-path --- enforcement is phased in separately (rest-api); these columns are the --- ground truth it will filter on. --- --------------------------------------------------------------------------- -ALTER TABLE "zone" ADD COLUMN IF NOT EXISTS organization_id UUID; -ALTER TABLE "sys" ADD COLUMN IF NOT EXISTS organization_id UUID; -ALTER TABLE "mod" ADD COLUMN IF NOT EXISTS organization_id UUID; -ALTER TABLE "trigger" ADD COLUMN IF NOT EXISTS organization_id UUID; -ALTER TABLE "edge" ADD COLUMN IF NOT EXISTS organization_id UUID; -ALTER TABLE "broker" ADD COLUMN IF NOT EXISTS organization_id UUID; - -ALTER TABLE ONLY "zone" - DROP CONSTRAINT IF EXISTS zone_organization_id_fkey; -ALTER TABLE ONLY "zone" - ADD CONSTRAINT zone_organization_id_fkey - FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "sys" - DROP CONSTRAINT IF EXISTS sys_organization_id_fkey; -ALTER TABLE ONLY "sys" - ADD CONSTRAINT sys_organization_id_fkey - FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "mod" - DROP CONSTRAINT IF EXISTS mod_organization_id_fkey; -ALTER TABLE ONLY "mod" - ADD CONSTRAINT mod_organization_id_fkey - FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "trigger" - DROP CONSTRAINT IF EXISTS trigger_organization_id_fkey; -ALTER TABLE ONLY "trigger" - ADD CONSTRAINT trigger_organization_id_fkey - FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "edge" - DROP CONSTRAINT IF EXISTS edge_organization_id_fkey; -ALTER TABLE ONLY "edge" - ADD CONSTRAINT edge_organization_id_fkey - FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; -ALTER TABLE ONLY "broker" - DROP CONSTRAINT IF EXISTS broker_organization_id_fkey; -ALTER TABLE ONLY "broker" - ADD CONSTRAINT broker_organization_id_fkey - FOREIGN KEY (organization_id) REFERENCES "organizations"(id) ON DELETE RESTRICT; - -CREATE INDEX IF NOT EXISTS zone_organization_id_index ON "zone" USING BTREE (organization_id); -CREATE INDEX IF NOT EXISTS sys_organization_id_index ON "sys" USING BTREE (organization_id); -CREATE INDEX IF NOT EXISTS mod_organization_id_index ON "mod" USING BTREE (organization_id); -CREATE INDEX IF NOT EXISTS trigger_organization_id_index ON "trigger" USING BTREE (organization_id); -CREATE INDEX IF NOT EXISTS edge_organization_id_index ON "edge" USING BTREE (organization_id); -CREATE INDEX IF NOT EXISTS broker_organization_id_index ON "broker" USING BTREE (organization_id); - --- Per-organization name uniqueness for the estate. Dormant while organization_id is NULL --- (UNIQUE treats NULLs as distinct) and strictly weaker than the current --- model-level global uniqueness, so it cannot conflict with existing data. --- When query enforcement lands, the model-level checks flip from global to --- organization-scoped and these indexes become the hard guarantee. -CREATE UNIQUE INDEX IF NOT EXISTS zone_organization_id_name_unique - ON "zone" USING BTREE (organization_id, name) WHERE organization_id IS NOT NULL; -CREATE UNIQUE INDEX IF NOT EXISTS sys_organization_id_name_unique - ON "sys" USING BTREE (organization_id, name) WHERE organization_id IS NOT NULL; -CREATE UNIQUE INDEX IF NOT EXISTS edge_organization_id_name_unique - ON "edge" USING BTREE (organization_id, name) WHERE organization_id IS NOT NULL; -CREATE UNIQUE INDEX IF NOT EXISTS broker_organization_id_name_unique - ON "broker" USING BTREE (organization_id, name) WHERE organization_id IS NOT NULL; - --- +micrate Down --- SQL section 'Down' is executed when this migration is rolled back - -DROP INDEX IF EXISTS broker_organization_id_name_unique; -DROP INDEX IF EXISTS edge_organization_id_name_unique; -DROP INDEX IF EXISTS sys_organization_id_name_unique; -DROP INDEX IF EXISTS zone_organization_id_name_unique; - -DROP INDEX IF EXISTS broker_organization_id_index; -DROP INDEX IF EXISTS edge_organization_id_index; -DROP INDEX IF EXISTS trigger_organization_id_index; -DROP INDEX IF EXISTS mod_organization_id_index; -DROP INDEX IF EXISTS sys_organization_id_index; -DROP INDEX IF EXISTS zone_organization_id_index; - -ALTER TABLE ONLY "broker" DROP CONSTRAINT IF EXISTS broker_organization_id_fkey; -ALTER TABLE ONLY "edge" DROP CONSTRAINT IF EXISTS edge_organization_id_fkey; -ALTER TABLE ONLY "trigger" DROP CONSTRAINT IF EXISTS trigger_organization_id_fkey; -ALTER TABLE ONLY "mod" DROP CONSTRAINT IF EXISTS mod_organization_id_fkey; -ALTER TABLE ONLY "sys" DROP CONSTRAINT IF EXISTS sys_organization_id_fkey; -ALTER TABLE ONLY "zone" DROP CONSTRAINT IF EXISTS zone_organization_id_fkey; - -ALTER TABLE "broker" DROP COLUMN IF EXISTS organization_id; -ALTER TABLE "edge" DROP COLUMN IF EXISTS organization_id; -ALTER TABLE "trigger" DROP COLUMN IF EXISTS organization_id; -ALTER TABLE "mod" DROP COLUMN IF EXISTS organization_id; -ALTER TABLE "sys" DROP COLUMN IF EXISTS organization_id; -ALTER TABLE "zone" DROP COLUMN IF EXISTS organization_id; - -DROP INDEX IF EXISTS authority_domain_unique; -DROP INDEX IF EXISTS authority_organization_id_index; -ALTER TABLE ONLY "authority" DROP CONSTRAINT IF EXISTS authority_organization_id_fkey; -ALTER TABLE "authority" DROP COLUMN IF EXISTS organization_id; - -DROP TABLE IF EXISTS "organizations"; -DROP TABLE IF EXISTS "partners"; diff --git a/migration/db/migrations/20261007100500000_add_partners_and_organisations.sql b/migration/db/migrations/20261007100500000_add_partners_and_organisations.sql new file mode 100644 index 00000000..cefe2179 --- /dev/null +++ b/migration/db/migrations/20261007100500000_add_partners_and_organisations.sql @@ -0,0 +1,211 @@ +-- +micrate Up +-- SQL in section 'Up' is executed when this migration is applied + +-- MERGE-TIME CHECK: micrate refuses out-of-order version ids (see models#323). +-- If any later-dated migration lands on master before this merges, renumber +-- this file AND 20261007100600000 above it (preserving schema-before-backfill +-- order). Safe: neither has been applied anywhere and the backfill is +-- idempotent. + +-- --------------------------------------------------------------------------- +-- PPT-526: the Partner → Organisation → Authority(domain) hierarchy. +-- +-- partners: integrators/resellers (e.g. NTT). `management = true` marks the +-- platform operator's own organisation (PlaceOS staff) — the "management +-- organisation" concept from the ticket, done at the partner level. `parent_id` +-- reserves a 2-tier channel (distributor → reseller) without any UI or +-- enforcement yet. +-- +-- organisations: the customer organisation (e.g. UCLA, Acadian). `partner_id` NULL +-- means organisation-owned (self-managed, no integrator). `payer` records who is +-- invoiced: 'partner' (integrator pays us and re-bills, the default channel +-- model) or 'organisation' (direct). A organisation without a partner can only pay for +-- itself — enforced by CHECK. +-- +-- Every delete path is RESTRICT: removing a partner/organisation must go through an +-- orchestrated teardown (the PPT-1203 pattern), never a silent DB cascade — +-- model-level cleanup callbacks do not fire on DB cascades. +-- --------------------------------------------------------------------------- +CREATE TABLE IF NOT EXISTS "partners"( + id UUID PRIMARY KEY DEFAULT uuidv7(), + name TEXT NOT NULL, + description TEXT NOT NULL DEFAULT '', + management BOOLEAN NOT NULL DEFAULT false, + parent_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, + config JSONB NOT NULL DEFAULT '{}', + created_at TIMESTAMPTZ NOT NULL, + updated_at TIMESTAMPTZ NOT NULL +); + +CREATE UNIQUE INDEX IF NOT EXISTS partners_name_unique + ON "partners" USING BTREE (name); +CREATE INDEX IF NOT EXISTS partners_parent_id_index + ON "partners" USING BTREE (parent_id); + +CREATE TABLE IF NOT EXISTS "organisations"( + id UUID PRIMARY KEY DEFAULT uuidv7(), + name TEXT NOT NULL, + description TEXT NOT NULL DEFAULT '', + partner_id UUID REFERENCES "partners"(id) ON DELETE RESTRICT, + payer TEXT NOT NULL DEFAULT 'partner' + CHECK (payer IN ('partner', 'organisation')), + config JSONB NOT NULL DEFAULT '{}', + created_at TIMESTAMPTZ NOT NULL, + updated_at TIMESTAMPTZ NOT NULL, + CONSTRAINT organisations_payer_requires_partner + CHECK (partner_id IS NOT NULL OR payer = 'organisation') +); + +-- Organisation names are unique within a partner's book of business, and unique +-- among organisation-owned organisations. Two partial indexes because UNIQUE treats +-- NULLs as distinct — a plain UNIQUE (partner_id, name) would let every +-- organisation-owned organisation share a name. +CREATE UNIQUE INDEX IF NOT EXISTS organisations_name_unique_per_partner + ON "organisations" USING BTREE (partner_id, name) WHERE partner_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS organisations_name_unique_owned + ON "organisations" USING BTREE (name) WHERE partner_id IS NULL; +CREATE INDEX IF NOT EXISTS organisations_partner_id_index + ON "organisations" USING BTREE (partner_id); + +-- --------------------------------------------------------------------------- +-- Authority → Organisation ownership. Nullable at the DB level for backwards +-- compatibility (init seeds authorities before any organisation exists); the +-- provisioning flow and backfill populate it. RESTRICT so a organisation cannot be +-- deleted while it still owns domains. +-- --------------------------------------------------------------------------- +ALTER TABLE "authority" + ADD COLUMN IF NOT EXISTS organisation_id UUID; + +ALTER TABLE ONLY "authority" + DROP CONSTRAINT IF EXISTS authority_organisation_id_fkey; +ALTER TABLE ONLY "authority" + ADD CONSTRAINT authority_organisation_id_fkey + FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT; + +CREATE INDEX IF NOT EXISTS authority_organisation_id_index + ON "authority" USING BTREE (organisation_id); + +-- The domain column has only ever had model-level uniqueness (a plain BTREE +-- index) — a concurrent-signup race can create duplicate authorities. Make it +-- a hard guarantee; self-service signup depends on it. +-- +-- Quarantine first: exact-duplicate domains left behind by that race would +-- make the unique index unbuildable and (because micrate autocommits each +-- statement) leave this migration half-applied. Keep the oldest row per +-- domain and rename the rest so they stop answering for the domain — +-- find_by_domain picks an arbitrary row across duplicates today, so this +-- cannot break a reliably-working login. Idempotent: renamed rows no longer +-- collide. Renamed rows are for an operator to merge or delete. +UPDATE "authority" a +SET domain = a.domain || '.duplicate.' || a.id +WHERE EXISTS ( + SELECT 1 FROM "authority" b + WHERE b.domain = a.domain + AND (b.created_at, b.id) < (a.created_at, a.id) +); + +CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique + ON "authority" USING BTREE (domain); + +-- --------------------------------------------------------------------------- +-- Organisation ownership columns on the (previously cluster-global) control plane. +-- Nullable: populated by the backfill migration where inference is +-- unambiguous, and by the provisioning flow for everything new. Query-path +-- enforcement is phased in separately (rest-api); these columns are the +-- ground truth it will filter on. +-- --------------------------------------------------------------------------- +ALTER TABLE "zone" ADD COLUMN IF NOT EXISTS organisation_id UUID; +ALTER TABLE "sys" ADD COLUMN IF NOT EXISTS organisation_id UUID; +ALTER TABLE "mod" ADD COLUMN IF NOT EXISTS organisation_id UUID; +ALTER TABLE "trigger" ADD COLUMN IF NOT EXISTS organisation_id UUID; +ALTER TABLE "edge" ADD COLUMN IF NOT EXISTS organisation_id UUID; +ALTER TABLE "broker" ADD COLUMN IF NOT EXISTS organisation_id UUID; + +ALTER TABLE ONLY "zone" + DROP CONSTRAINT IF EXISTS zone_organisation_id_fkey; +ALTER TABLE ONLY "zone" + ADD CONSTRAINT zone_organisation_id_fkey + FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "sys" + DROP CONSTRAINT IF EXISTS sys_organisation_id_fkey; +ALTER TABLE ONLY "sys" + ADD CONSTRAINT sys_organisation_id_fkey + FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "mod" + DROP CONSTRAINT IF EXISTS mod_organisation_id_fkey; +ALTER TABLE ONLY "mod" + ADD CONSTRAINT mod_organisation_id_fkey + FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "trigger" + DROP CONSTRAINT IF EXISTS trigger_organisation_id_fkey; +ALTER TABLE ONLY "trigger" + ADD CONSTRAINT trigger_organisation_id_fkey + FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "edge" + DROP CONSTRAINT IF EXISTS edge_organisation_id_fkey; +ALTER TABLE ONLY "edge" + ADD CONSTRAINT edge_organisation_id_fkey + FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT; +ALTER TABLE ONLY "broker" + DROP CONSTRAINT IF EXISTS broker_organisation_id_fkey; +ALTER TABLE ONLY "broker" + ADD CONSTRAINT broker_organisation_id_fkey + FOREIGN KEY (organisation_id) REFERENCES "organisations"(id) ON DELETE RESTRICT; + +CREATE INDEX IF NOT EXISTS zone_organisation_id_index ON "zone" USING BTREE (organisation_id); +CREATE INDEX IF NOT EXISTS sys_organisation_id_index ON "sys" USING BTREE (organisation_id); +CREATE INDEX IF NOT EXISTS mod_organisation_id_index ON "mod" USING BTREE (organisation_id); +CREATE INDEX IF NOT EXISTS trigger_organisation_id_index ON "trigger" USING BTREE (organisation_id); +CREATE INDEX IF NOT EXISTS edge_organisation_id_index ON "edge" USING BTREE (organisation_id); +CREATE INDEX IF NOT EXISTS broker_organisation_id_index ON "broker" USING BTREE (organisation_id); + +-- Per-organisation name uniqueness for the estate. Dormant while organisation_id is NULL +-- (UNIQUE treats NULLs as distinct) and strictly weaker than the current +-- model-level global uniqueness, so it cannot conflict with existing data. +-- When query enforcement lands, the model-level checks flip from global to +-- organisation-scoped and these indexes become the hard guarantee. +CREATE UNIQUE INDEX IF NOT EXISTS zone_organisation_id_name_unique + ON "zone" USING BTREE (organisation_id, name) WHERE organisation_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS sys_organisation_id_name_unique + ON "sys" USING BTREE (organisation_id, name) WHERE organisation_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS edge_organisation_id_name_unique + ON "edge" USING BTREE (organisation_id, name) WHERE organisation_id IS NOT NULL; +CREATE UNIQUE INDEX IF NOT EXISTS broker_organisation_id_name_unique + ON "broker" USING BTREE (organisation_id, name) WHERE organisation_id IS NOT NULL; + +-- +micrate Down +-- SQL section 'Down' is executed when this migration is rolled back + +DROP INDEX IF EXISTS broker_organisation_id_name_unique; +DROP INDEX IF EXISTS edge_organisation_id_name_unique; +DROP INDEX IF EXISTS sys_organisation_id_name_unique; +DROP INDEX IF EXISTS zone_organisation_id_name_unique; + +DROP INDEX IF EXISTS broker_organisation_id_index; +DROP INDEX IF EXISTS edge_organisation_id_index; +DROP INDEX IF EXISTS trigger_organisation_id_index; +DROP INDEX IF EXISTS mod_organisation_id_index; +DROP INDEX IF EXISTS sys_organisation_id_index; +DROP INDEX IF EXISTS zone_organisation_id_index; + +ALTER TABLE ONLY "broker" DROP CONSTRAINT IF EXISTS broker_organisation_id_fkey; +ALTER TABLE ONLY "edge" DROP CONSTRAINT IF EXISTS edge_organisation_id_fkey; +ALTER TABLE ONLY "trigger" DROP CONSTRAINT IF EXISTS trigger_organisation_id_fkey; +ALTER TABLE ONLY "mod" DROP CONSTRAINT IF EXISTS mod_organisation_id_fkey; +ALTER TABLE ONLY "sys" DROP CONSTRAINT IF EXISTS sys_organisation_id_fkey; +ALTER TABLE ONLY "zone" DROP CONSTRAINT IF EXISTS zone_organisation_id_fkey; + +ALTER TABLE "broker" DROP COLUMN IF EXISTS organisation_id; +ALTER TABLE "edge" DROP COLUMN IF EXISTS organisation_id; +ALTER TABLE "trigger" DROP COLUMN IF EXISTS organisation_id; +ALTER TABLE "mod" DROP COLUMN IF EXISTS organisation_id; +ALTER TABLE "sys" DROP COLUMN IF EXISTS organisation_id; +ALTER TABLE "zone" DROP COLUMN IF EXISTS organisation_id; + +DROP INDEX IF EXISTS authority_domain_unique; +DROP INDEX IF EXISTS authority_organisation_id_index; +ALTER TABLE ONLY "authority" DROP CONSTRAINT IF EXISTS authority_organisation_id_fkey; +ALTER TABLE "authority" DROP COLUMN IF EXISTS organisation_id; + +DROP TABLE IF EXISTS "organisations"; +DROP TABLE IF EXISTS "partners"; diff --git a/migration/db/migrations/20260818100600000_backfill_organization_ownership.sql b/migration/db/migrations/20261007100600000_backfill_organisation_ownership.sql similarity index 67% rename from migration/db/migrations/20260818100600000_backfill_organization_ownership.sql rename to migration/db/migrations/20261007100600000_backfill_organisation_ownership.sql index 35d7ed60..904715a2 100644 --- a/migration/db/migrations/20260818100600000_backfill_organization_ownership.sql +++ b/migration/db/migrations/20261007100600000_backfill_organisation_ownership.sql @@ -2,10 +2,10 @@ -- SQL in section 'Up' is executed when this migration is applied -- --------------------------------------------------------------------------- --- PPT-526: backfill Partner/Organization ownership for existing data. +-- PPT-526: backfill Partner/Organisation ownership for existing data. -- -- Idempotent and additive: every statement only creates missing rows or fills --- NULL organization_id columns, so it is safe to re-apply and safe on databases +-- NULL organisation_id columns, so it is safe to re-apply and safe on databases -- where operators have already assigned ownership by hand. Where inference is -- ambiguous the row is deliberately LEFT NULL for a human to resolve (the -- org_zone convention is known to be non-exclusive and sometimes absent). @@ -13,15 +13,15 @@ -- What it does: -- 1. Ensures a management partner exists ("PlaceOS" — the platform -- operator's own organisation). --- 2. Creates one organization-owned Organization per Authority that has none, named +-- 2. Creates one organisation-owned Organisation per Authority that has none, named -- " ()" (domain uniqueness makes this collision -- free), and points the authority at it. Estates that span several --- authorities under one real-world organization (e.g. NTT's two domains) are --- merged later by re-pointing authority.organization_id by hand or API. --- 3. Zones: a zone belongs to the organization of the authority whose +-- authorities under one real-world organisation (e.g. NTT's two domains) are +-- merged later by re-pointing authority.organisation_id by hand or API. +-- 3. Zones: a zone belongs to the organisation of the authority whose -- config->>'org_zone' names the zone's ROOT zone — only when exactly one --- organization is implied (shared org zones stay NULL). --- 4. Systems: the single distinct organization of their zones, if unambiguous. +-- organisation is implied (shared org zones stay NULL). +-- 4. Systems: the single distinct organisation of their zones, if unambiguous. -- 5. Modules: logic modules via their control system; shared device/service -- modules via the systems that reference them, if unambiguous. -- 6. Trigger definitions: via their control system when system-scoped; @@ -38,20 +38,20 @@ SELECT 'PlaceOS', 'Platform operator (management partner)', true, now(), now() WHERE NOT EXISTS (SELECT 1 FROM "partners" WHERE management = true) ON CONFLICT DO NOTHING; --- 2. One organization-owned Organization per orphan Authority +-- 2. One organisation-owned Organisation per orphan Authority -- +micrate StatementBegin DO $$ DECLARE auth RECORD; new_org UUID; BEGIN - FOR auth IN SELECT id, name, domain FROM "authority" WHERE organization_id IS NULL LOOP + FOR auth IN SELECT id, name, domain FROM "authority" WHERE organisation_id IS NULL LOOP new_org := NULL; - INSERT INTO "organizations" (name, description, partner_id, payer, created_at, updated_at) + INSERT INTO "organisations" (name, description, partner_id, payer, created_at, updated_at) VALUES ( COALESCE(NULLIF(auth.name, ''), auth.domain) || ' (' || auth.domain || ')', - 'Auto-created from authority ' || auth.id || ' during PPT-526 organization backfill', - NULL, 'organization', now(), now() + 'Auto-created from authority ' || auth.id || ' during PPT-526 organisation backfill', + NULL, 'organisation', now(), now() ) ON CONFLICT DO NOTHING RETURNING id INTO new_org; @@ -59,13 +59,13 @@ BEGIN -- If the name already existed (re-run against a partially-backfilled DB), -- reuse the existing row rather than leaving the authority orphaned. IF new_org IS NULL THEN - SELECT id INTO new_org FROM "organizations" + SELECT id INTO new_org FROM "organisations" WHERE partner_id IS NULL AND name = COALESCE(NULLIF(auth.name, ''), auth.domain) || ' (' || auth.domain || ')'; END IF; IF new_org IS NOT NULL THEN - UPDATE "authority" SET organization_id = new_org WHERE id = auth.id; + UPDATE "authority" SET organisation_id = new_org WHERE id = auth.id; END IF; END LOOP; END $$; @@ -75,9 +75,9 @@ END $$; -- UNION (not UNION ALL) so accidental cycles in zone parentage terminate. -- Ambiguity is judged per TREE, not per org_zone string: every authority's -- org_zone claim is resolved to its tree root, a tree claimed by more than --- one distinct organization is vetoed, and ownership is only assigned when at +-- one distinct organisation is vetoed, and ownership is only assigned when at -- least one claim names the root itself (a claim on a sub-zone alone must --- not annex the whole tree). Rows whose (organization_id, name) would collide +-- not annex the whole tree). Rows whose (organisation_id, name) would collide -- with the partial unique indexes are skipped (left NULL for a human) — -- duplicate names within one estate are legacy race artifacts. -- +micrate StatementBegin @@ -93,125 +93,125 @@ WITH RECURSIVE zone_roots AS ( tree_claims AS ( SELECT r.root_id, (a.config->>'org_zone' = r.root_id) AS names_root, - a.organization_id + a.organisation_id FROM "authority" a INNER JOIN zone_roots r ON r.id = a.config->>'org_zone' WHERE COALESCE(a.config->>'org_zone', '') <> '' - AND a.organization_id IS NOT NULL + AND a.organisation_id IS NOT NULL ), org_owner AS ( - SELECT root_id, MIN(organization_id::text)::uuid AS organization_id + SELECT root_id, MIN(organisation_id::text)::uuid AS organisation_id FROM tree_claims GROUP BY root_id - HAVING COUNT(DISTINCT organization_id) = 1 + HAVING COUNT(DISTINCT organisation_id) = 1 AND bool_or(names_root) ), candidates AS ( - SELECT z.id, o.organization_id, z.name, + SELECT z.id, o.organisation_id, z.name, ROW_NUMBER() OVER ( - PARTITION BY o.organization_id, z.name + PARTITION BY o.organisation_id, z.name ORDER BY z.created_at, z.id ) AS rn FROM "zone" z INNER JOIN zone_roots r ON z.id = r.id INNER JOIN org_owner o ON r.root_id = o.root_id - WHERE z.organization_id IS NULL + WHERE z.organisation_id IS NULL ) UPDATE "zone" z -SET organization_id = c.organization_id +SET organisation_id = c.organisation_id FROM candidates c WHERE z.id = c.id AND c.rn = 1 AND NOT EXISTS ( SELECT 1 FROM "zone" x - WHERE x.organization_id = c.organization_id AND x.name = z.name AND x.id <> z.id + WHERE x.organisation_id = c.organisation_id AND x.name = z.name AND x.id <> z.id ); -- +micrate StatementEnd --- 4. Systems: single distinct organization across their zones. Same collision --- skip as zones (sys carries a (organization_id, name) partial unique index). +-- 4. Systems: single distinct organisation across their zones. Same collision +-- skip as zones (sys carries a (organisation_id, name) partial unique index). -- +micrate StatementBegin WITH sys_candidates AS ( SELECT s2.id AS sys_id, s2.name, - MIN(z.organization_id::text)::uuid AS organization_id + MIN(z.organisation_id::text)::uuid AS organisation_id FROM "sys" s2 INNER JOIN "zone" z ON z.id = ANY(s2.zones) - WHERE z.organization_id IS NOT NULL - AND s2.organization_id IS NULL + WHERE z.organisation_id IS NOT NULL + AND s2.organisation_id IS NULL GROUP BY s2.id, s2.name - HAVING COUNT(DISTINCT z.organization_id) = 1 + HAVING COUNT(DISTINCT z.organisation_id) = 1 ), ranked AS ( - SELECT sys_id, name, organization_id, + SELECT sys_id, name, organisation_id, ROW_NUMBER() OVER ( - PARTITION BY organization_id, name + PARTITION BY organisation_id, name ORDER BY sys_id ) AS rn FROM sys_candidates ) UPDATE "sys" s -SET organization_id = r.organization_id +SET organisation_id = r.organisation_id FROM ranked r WHERE s.id = r.sys_id AND r.rn = 1 AND NOT EXISTS ( SELECT 1 FROM "sys" x - WHERE x.organization_id = r.organization_id AND x.name = s.name AND x.id <> s.id + WHERE x.organisation_id = r.organisation_id AND x.name = s.name AND x.id <> s.id ); -- +micrate StatementEnd -- 5a. Logic modules via their control system UPDATE "mod" m -SET organization_id = s.organization_id +SET organisation_id = s.organisation_id FROM "sys" s WHERE m.control_system_id = s.id - AND s.organization_id IS NOT NULL - AND m.organization_id IS NULL; + AND s.organisation_id IS NOT NULL + AND m.organisation_id IS NULL; -- 5b. Device/service modules via the systems that reference them UPDATE "mod" m -SET organization_id = sc.organization_id +SET organisation_id = sc.organisation_id FROM ( - SELECT m2.id AS mod_id, MIN(s.organization_id::text)::uuid AS organization_id + SELECT m2.id AS mod_id, MIN(s.organisation_id::text)::uuid AS organisation_id FROM "mod" m2 INNER JOIN "sys" s ON m2.id = ANY(s.modules) - WHERE s.organization_id IS NOT NULL + WHERE s.organisation_id IS NOT NULL GROUP BY m2.id - HAVING COUNT(DISTINCT s.organization_id) = 1 + HAVING COUNT(DISTINCT s.organisation_id) = 1 ) sc -WHERE m.id = sc.mod_id AND m.organization_id IS NULL; +WHERE m.id = sc.mod_id AND m.organisation_id IS NULL; -- 6. System-scoped trigger definitions UPDATE "trigger" t -SET organization_id = s.organization_id +SET organisation_id = s.organisation_id FROM "sys" s WHERE t.control_system_id = s.id - AND s.organization_id IS NOT NULL - AND t.organization_id IS NULL; + AND s.organisation_id IS NOT NULL + AND t.organisation_id IS NULL; -- 7. Edges via their bound user's authority. Same collision skip (edge --- carries a (organization_id, name) partial unique index). +-- carries a (organisation_id, name) partial unique index). -- +micrate StatementBegin WITH edge_candidates AS ( - SELECT e.id, e.name, a.organization_id, + SELECT e.id, e.name, a.organisation_id, ROW_NUMBER() OVER ( - PARTITION BY a.organization_id, e.name + PARTITION BY a.organisation_id, e.name ORDER BY e.id ) AS rn FROM "edge" e INNER JOIN "user" u ON e.user_id = u.id INNER JOIN "authority" a ON u.authority_id = a.id - WHERE a.organization_id IS NOT NULL - AND e.organization_id IS NULL + WHERE a.organisation_id IS NOT NULL + AND e.organisation_id IS NULL ) UPDATE "edge" e -SET organization_id = c.organization_id +SET organisation_id = c.organisation_id FROM edge_candidates c WHERE e.id = c.id AND c.rn = 1 AND NOT EXISTS ( SELECT 1 FROM "edge" x - WHERE x.organization_id = c.organization_id AND x.name = e.name AND x.id <> e.id + WHERE x.organisation_id = c.organisation_id AND x.name = e.name AND x.id <> e.id ); -- +micrate StatementEnd @@ -219,4 +219,4 @@ WHERE e.id = c.id -- Deliberate no-op: the backfill only fills NULLs and creates rows that -- operators may since have adopted; unwinding it automatically could destroy -- hand-made ownership assignments. Rolling back the schema migration --- (20260818100500000) removes the columns and tables wholesale. +-- (20261007100500000) removes the columns and tables wholesale. diff --git a/migration/db/migrations/20260819100500000_add_grants.sql b/migration/db/migrations/20261007100700000_add_grants.sql similarity index 87% rename from migration/db/migrations/20260819100500000_add_grants.sql rename to migration/db/migrations/20261007100700000_add_grants.sql index f7073c09..65b18537 100644 --- a/migration/db/migrations/20260819100500000_add_grants.sql +++ b/migration/db/migrations/20261007100700000_add_grants.sql @@ -8,12 +8,12 @@ -- PPT-526 Stage 3: the authorization `grants` table (Zanzibar-lite tuple). -- -- A grant gives a user a permission bitmask over a scope, which is one of a --- Partner, a Organization, or an Authority. Authorization walks UP from the touched --- resource (authority -> its organization -> that organization's partner) and ORs every +-- Partner, a Organisation, or an Authority. Authorization walks UP from the touched +-- resource (authority -> its organisation -> that organisation's partner) and ORs every -- live grant found on the chain, so a single grant at partner scope applies to --- all of that partner's organizations, current and future (decision b, 2026-08-19). +-- all of that partner's organisations, current and future (decision b, 2026-08-19). -- --- `scope_id` is polymorphic (a partner/organization UUID as text, or an authority +-- `scope_id` is polymorphic (a partner/organisation UUID as text, or an authority -- TEXT id), so it carries no DB foreign key. A grant naming a deleted scope is -- inert: resolution walks up from live resources and never matches it, so -- orphan grants are harmless and can be swept lazily. The one real FK is @@ -25,7 +25,7 @@ CREATE TABLE IF NOT EXISTS "grants"( id UUID PRIMARY KEY DEFAULT uuidv7(), user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE, - scope_type TEXT NOT NULL CHECK (scope_type IN ('partner', 'organization', 'authority')), + scope_type TEXT NOT NULL CHECK (scope_type IN ('partner', 'organisation', 'authority')), scope_id TEXT NOT NULL, permissions INTEGER NOT NULL DEFAULT 0, expires_at TIMESTAMPTZ, @@ -43,7 +43,7 @@ CREATE UNIQUE INDEX IF NOT EXISTS grants_user_scope_unique CREATE INDEX IF NOT EXISTS grants_user_id_index ON "grants" USING BTREE (user_id); --- "who can reach this scope" (partner/organization admin console, audit). +-- "who can reach this scope" (partner/organisation admin console, audit). CREATE INDEX IF NOT EXISTS grants_scope_index ON "grants" USING BTREE (scope_type, scope_id); diff --git a/spec/generator.cr b/spec/generator.cr index f3b55d42..a73a3f1f 100644 --- a/spec/generator.cr +++ b/spec/generator.cr @@ -574,8 +574,8 @@ module PlaceOS::Model ) end - def self.organization(partner : Partner? = nil, payer : String = Organization::PAYER_PARTNER) - Organization.new( + def self.organisation(partner : Partner? = nil, payer : String = Organisation::PAYER_PARTNER) + Organisation.new( name: Faker::Hacker.noun + "-" + RANDOM.hex(3), partner_id: partner.try(&.id), payer: payer, diff --git a/spec/grant_spec.cr b/spec/grant_spec.cr index ed9bce3d..ce03b9e1 100644 --- a/spec/grant_spec.cr +++ b/spec/grant_spec.cr @@ -1,11 +1,11 @@ require "./helper" # Build partner -> org -> authority -> user, returning all four. -private def build_estate(payer = PlaceOS::Model::Organization::PAYER_PARTNER) +private def build_estate(payer = PlaceOS::Model::Organisation::PAYER_PARTNER) partner = PlaceOS::Model::Generator.partner.save! - org = PlaceOS::Model::Generator.organization(partner: partner, payer: payer).save! + org = PlaceOS::Model::Generator.organisation(partner: partner, payer: payer).save! authority = PlaceOS::Model::Generator.authority(domain: "grant-#{RANDOM.hex(4)}.example.com") - authority.organization_id = org.id + authority.organisation_id = org.id authority.save! user = PlaceOS::Model::Generator.user(authority: authority).save! {partner, org, authority, user} @@ -17,13 +17,13 @@ module PlaceOS::Model Grant.clear Authority.clear User.clear - Organization.clear + Organisation.clear Partner.clear end it "saves a grant with a permission bitmask" do _, org, _, user = build_estate - grant = Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Manage).save! + grant = Generator.grant(user, Grant::SCOPE_ORGANISATION, org.id.not_nil!.to_s, Permissions::Manage).save! grant.persisted?.should be_true grant.permission_flags.should eq Permissions::Manage end @@ -43,19 +43,19 @@ module PlaceOS::Model it "resolves a org-scope grant onto the org's authority" do _, org, authority, user = build_estate - Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Operate).save! + Generator.grant(user, Grant::SCOPE_ORGANISATION, org.id.not_nil!.to_s, Permissions::Operate).save! Grant.resolve(user.id.not_nil!, authority).should eq Permissions::Operate end it "resolves a partner-scope grant onto every authority under that partner (decision b)" do partner = Generator.partner.save! - client_a = Generator.organization(partner: partner).save! - client_b = Generator.organization(partner: partner).save! + client_a = Generator.organisation(partner: partner).save! + client_b = Generator.organisation(partner: partner).save! auth_a = Generator.authority(domain: "a-#{RANDOM.hex(4)}.example.com") - auth_a.organization_id = client_a.id + auth_a.organisation_id = client_a.id auth_a.save! auth_b = Generator.authority(domain: "b-#{RANDOM.hex(4)}.example.com") - auth_b.organization_id = client_b.id + auth_b.organisation_id = client_b.id auth_b.save! staff = Generator.user(authority: auth_a).save! @@ -68,7 +68,7 @@ module PlaceOS::Model it "ORs permissions across scopes on the chain" do partner, org, authority, user = build_estate Generator.grant(user, Grant::SCOPE_PARTNER, partner.id.not_nil!.to_s, Permissions::Read).save! - Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Update).save! + Generator.grant(user, Grant::SCOPE_ORGANISATION, org.id.not_nil!.to_s, Permissions::Update).save! Grant.resolve(user.id.not_nil!, authority).should eq(Permissions::Read | Permissions::Update) end @@ -82,14 +82,14 @@ module PlaceOS::Model it "ignores expired grants" do _, org, authority, user = build_estate - Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Manage, + Generator.grant(user, Grant::SCOPE_ORGANISATION, org.id.not_nil!.to_s, Permissions::Manage, expires_at: Time.utc - 1.hour).save! Grant.resolve(user.id.not_nil!, authority).should eq Permissions::None end it "honours a future expiry" do _, org, authority, user = build_estate - Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s, Permissions::Read, + Generator.grant(user, Grant::SCOPE_ORGANISATION, org.id.not_nil!.to_s, Permissions::Read, expires_at: Time.utc + 1.hour).save! Grant.resolve(user.id.not_nil!, authority).should eq Permissions::Read end @@ -101,7 +101,7 @@ module PlaceOS::Model it "cascades on user delete" do _, org, _, user = build_estate - grant = Generator.grant(user, Grant::SCOPE_ORGANIZATION, org.id.not_nil!.to_s).save! + grant = Generator.grant(user, Grant::SCOPE_ORGANISATION, org.id.not_nil!.to_s).save! user.destroy Grant.find?(grant.id.not_nil!).should be_nil end diff --git a/spec/helper.cr b/spec/helper.cr index 44f3dd34..dedc18e5 100644 --- a/spec/helper.cr +++ b/spec/helper.cr @@ -40,7 +40,7 @@ Spec.after_suite do PlaceOS::Model::GroupPlaylist, PlaceOS::Model::Group, PlaceOS::Model::Grant, - PlaceOS::Model::Organization, + PlaceOS::Model::Organisation, PlaceOS::Model::Partner, ].each(&.clear) end diff --git a/spec/organization_spec.cr b/spec/organisation_spec.cr similarity index 62% rename from spec/organization_spec.cr rename to spec/organisation_spec.cr index 8d166f49..8669b67b 100644 --- a/spec/organization_spec.cr +++ b/spec/organisation_spec.cr @@ -1,33 +1,33 @@ require "./helper" module PlaceOS::Model - describe Organization do + describe Organisation do Spec.before_each do ControlSystem.clear Zone.clear Authority.clear - Organization.clear + Organisation.clear Partner.clear end it "saves a partnered org with partner-pays default" do partner = Generator.partner.save! - org = Generator.organization(partner: partner).save! + org = Generator.organisation(partner: partner).save! org.persisted?.should be_true - org.payer.should eq Organization::PAYER_PARTNER + org.payer.should eq Organisation::PAYER_PARTNER org.self_managed?.should be_false org.partner.try(&.id).should eq partner.id end it "normalizes a org-owned org to pay for itself" do - org = Generator.organization.save! + org = Generator.organisation.save! org.partner_id.should be_nil - org.payer.should eq Organization::PAYER_ORGANIZATION + org.payer.should eq Organisation::PAYER_ORGANISATION org.self_managed?.should be_true end it "rejects an unknown payer" do - org = Generator.organization(partner: Generator.partner.save!, payer: "nobody") + org = Generator.organisation(partner: Generator.partner.save!, payer: "nobody") org.valid?.should be_false org.errors.map(&.field).should contain(:payer) end @@ -35,52 +35,52 @@ module PlaceOS::Model it "scopes org name uniqueness to the partner" do partner_a = Generator.partner.save! partner_b = Generator.partner.save! - original = Generator.organization(partner: partner_a).save! + original = Generator.organisation(partner: partner_a).save! # Same name under a different partner is fine - sibling = Generator.organization(partner: partner_b) + sibling = Generator.organisation(partner: partner_b) sibling.name = original.name sibling.valid?.should be_true # Same name under the same partner is not - duplicate = Generator.organization(partner: partner_a) + duplicate = Generator.organisation(partner: partner_a) duplicate.name = original.name duplicate.valid?.should be_false duplicate.errors.map(&.field).should contain(:name) end it "rejects duplicate names among org-owned clients" do - original = Generator.organization.save! - duplicate = Generator.organization + original = Generator.organisation.save! + duplicate = Generator.organisation duplicate.name = original.name duplicate.valid?.should be_false duplicate.errors.map(&.field).should contain(:name) end - it "owns authorities via authority.organization_id" do - org = Generator.organization.save! + it "owns authorities via authority.organisation_id" do + org = Generator.organisation.save! authority = Generator.authority(domain: "org-spec.example.com") - authority.organization_id = org.id + authority.organisation_id = org.id authority.save! - authority.organization.try(&.id).should eq org.id + authority.organisation.try(&.id).should eq org.id org.authorities.to_a.map(&.id).should eq [authority.id] end it "refuses to delete a org that still owns a domain" do - org = Generator.organization.save! + org = Generator.organisation.save! authority = Generator.authority(domain: "org-restrict.example.com") - authority.organization_id = org.id + authority.organisation_id = org.id authority.save! expect_raises(Exception, /foreign key/) { org.destroy } - Organization.find?(org.id.not_nil!).should_not be_nil + Organisation.find?(org.id.not_nil!).should_not be_nil end it "rejects renaming a org onto a sibling's name" do partner = Generator.partner.save! - original = Generator.organization(partner: partner).save! - sibling = Generator.organization(partner: partner).save! + original = Generator.organisation(partner: partner).save! + sibling = Generator.organisation(partner: partner).save! sibling.name = original.name sibling.valid?.should be_false @@ -88,17 +88,17 @@ module PlaceOS::Model end it "records org ownership on zones and systems" do - org = Generator.organization.save! + org = Generator.organisation.save! zone = Generator.zone - zone.organization_id = org.id + zone.organisation_id = org.id zone.save! sys = Generator.control_system - sys.organization_id = org.id + sys.organisation_id = org.id sys.save! - Zone.find!(zone.id.not_nil!).organization.try(&.id).should eq org.id - ControlSystem.find!(sys.id.not_nil!).organization.try(&.id).should eq org.id + Zone.find!(zone.id.not_nil!).organisation.try(&.id).should eq org.id + ControlSystem.find!(sys.id.not_nil!).organisation.try(&.id).should eq org.id end end end diff --git a/spec/partner_spec.cr b/spec/partner_spec.cr index 492c98ab..74a270d5 100644 --- a/spec/partner_spec.cr +++ b/spec/partner_spec.cr @@ -6,7 +6,7 @@ module PlaceOS::Model ControlSystem.clear Zone.clear Authority.clear - Organization.clear + Organisation.clear Partner.clear end @@ -54,14 +54,14 @@ module PlaceOS::Model it "lists its clients" do partner = Generator.partner.save! - org = Generator.organization(partner: partner).save! - Generator.organization.save! - partner.organizations.to_a.map(&.id).should eq [org.id] + org = Generator.organisation(partner: partner).save! + Generator.organisation.save! + partner.organisations.to_a.map(&.id).should eq [org.id] end it "refuses to delete a partner that still has clients" do partner = Generator.partner.save! - Generator.organization(partner: partner).save! + Generator.organisation(partner: partner).save! expect_raises(Exception, /foreign key/) { partner.destroy } Partner.find?(partner.id.not_nil!).should_not be_nil diff --git a/src/placeos-models/authority.cr b/src/placeos-models/authority.cr index dd990514..97d419e5 100644 --- a/src/placeos-models/authority.cr +++ b/src/placeos-models/authority.cr @@ -32,9 +32,9 @@ module PlaceOS::Model attribute email_domains : Array(String) = [] of String - # PPT-526: the Organization (customer organisation) that owns this domain. + # PPT-526: the Organisation (customer organisation) that owns this domain. # Nullable while ownership backfill and provisioning are phased in. - attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organisation_id : UUID?, es_type: "keyword", mass_assignment: false macro finished # Ensure only the host is saved. @@ -81,9 +81,9 @@ module PlaceOS::Model Authority.where(domain: host).first? end - # The owning Organization, when ownership has been assigned. - def organization : PlaceOS::Model::Organization? - self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } + # The owning Organisation, when ownership has been assigned. + def organisation : PlaceOS::Model::Organisation? + self.organisation_id.try { |id| PlaceOS::Model::Organisation.find?(id) } end # Locates an authority by email domain diff --git a/src/placeos-models/broker.cr b/src/placeos-models/broker.cr index f643fd8e..73e47ea2 100644 --- a/src/placeos-models/broker.cr +++ b/src/placeos-models/broker.cr @@ -33,14 +33,14 @@ module PlaceOS::Model # Matches will be replaced with a hmac_256(secret, match). attribute filters : Array(String) = -> { [] of String } - # PPT-526: the Organization (customer organisation) that owns this broker. + # PPT-526: the Organisation (customer organisation) that owns this broker. # NULL = cluster-level infrastructure (the default; the backfill never # assigns brokers). Nullable while query enforcement is phased in. - attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organisation_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Organization, when ownership has been assigned. - def organization : PlaceOS::Model::Organization? - self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } + # The owning Organisation, when ownership has been assigned. + def organisation : PlaceOS::Model::Organisation? + self.organisation_id.try { |id| PlaceOS::Model::Organisation.find?(id) } end # Validation diff --git a/src/placeos-models/control_system.cr b/src/placeos-models/control_system.cr index bb43fe52..02d2ad02 100644 --- a/src/placeos-models/control_system.cr +++ b/src/placeos-models/control_system.cr @@ -46,13 +46,13 @@ module PlaceOS::Model # Array of security group ids for room access attribute security_groups : Array(String) = -> { [] of String } - # PPT-526: the Organization (customer organisation) that owns this system. + # PPT-526: the Organisation (customer organisation) that owns this system. # Nullable while ownership backfill and query enforcement are phased in. - attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organisation_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Organization, when ownership has been assigned. - def organization : PlaceOS::Model::Organization? - self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } + # The owning Organisation, when ownership has been assigned. + def organisation : PlaceOS::Model::Organisation? + self.organisation_id.try { |id| PlaceOS::Model::Organisation.find?(id) } end attribute timezone : Time::Location?, converter: Time::Location::Converter, es_type: "text" diff --git a/src/placeos-models/edge.cr b/src/placeos-models/edge.cr index d703d1bb..aae3b98f 100644 --- a/src/placeos-models/edge.cr +++ b/src/placeos-models/edge.cr @@ -20,13 +20,13 @@ module PlaceOS::Model attribute last_seen : Time?, converter: Time::EpochConverterOptional, mass_assignment: false attribute online : Bool = false, mass_assignment: false - # PPT-526: the Organization (customer organisation) that owns this edge node. + # PPT-526: the Organisation (customer organisation) that owns this edge node. # Nullable while ownership backfill and query enforcement are phased in. - attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organisation_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Organization, when ownership has been assigned. - def organization : PlaceOS::Model::Organization? - self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } + # The owning Organisation, when ownership has been assigned. + def organisation : PlaceOS::Model::Organisation? + self.organisation_id.try { |id| PlaceOS::Model::Organisation.find?(id) } end @[JSON::Field(ignore: true)] diff --git a/src/placeos-models/grant.cr b/src/placeos-models/grant.cr index 459830c4..5907a83b 100644 --- a/src/placeos-models/grant.cr +++ b/src/placeos-models/grant.cr @@ -4,20 +4,20 @@ require "uuid/json" require "./base/model" require "./permissions" require "./authority" -require "./organization" +require "./organisation" require "./partner" module PlaceOS::Model # PPT-526 Stage 3: a cross-tenant authorization grant. # - # Gives a user a `Permissions` bitmask over one scope — a Partner, an Organization, + # Gives a user a `Permissions` bitmask over one scope — a Partner, an Organisation, # or an Authority. Authorization resolves by walking UP from the touched - # resource: authority -> its organization -> that organization's partner. A grant at - # partner scope therefore covers every one of that partner's organizations, current - # and future (the NTT-over-its-clients case); a grant at organization scope covers - # that organization's authorities; a grant at authority scope is a single domain. + # resource: authority -> its organisation -> that organisation's partner. A grant at + # partner scope therefore covers every one of that partner's organisations, current + # and future (the NTT-over-its-clients case); a grant at organisation scope covers + # that organisation's authorities; a grant at authority scope is a single domain. # - # `scope_id` is polymorphic (a Partner/Organization UUID as text, or an Authority + # `scope_id` is polymorphic (a Partner/Organisation UUID as text, or an Authority # TEXT id) so it carries no FK; a grant naming a deleted scope is inert. class Grant < ::PgORM::Base include PgORM::Timestamps @@ -25,9 +25,9 @@ module PlaceOS::Model table :grants SCOPE_PARTNER = "partner" - SCOPE_ORGANIZATION = "organization" + SCOPE_ORGANISATION = "organisation" SCOPE_AUTHORITY = "authority" - SCOPE_TYPES = [SCOPE_PARTNER, SCOPE_ORGANIZATION, SCOPE_AUTHORITY] + SCOPE_TYPES = [SCOPE_PARTNER, SCOPE_ORGANISATION, SCOPE_AUTHORITY] default_primary_key id : UUID, autogenerated: true @@ -78,7 +78,7 @@ module PlaceOS::Model # ------------------------------------------------------------------ # Effective permissions a user holds over `authority`, resolved by walking - # up authority -> organization -> partner and OR-ing every live grant on the + # up authority -> organisation -> partner and OR-ing every live grant on the # chain. Explicit grants only; the management-partner "support sees all" # rule is applied by the enforcement layer, not here. def self.resolve(user_id : String, authority : Authority, at : Time = Time.utc) : Permissions @@ -93,13 +93,13 @@ module PlaceOS::Model end # The (scope_type, scope_id) pairs to check for a given authority, from - # most specific to least: the authority itself, its organization, that organization's + # most specific to least: the authority itself, its organisation, that organisation's # partner. Missing links are simply absent. def self.scope_chain(authority : Authority) : Array({String, String}) chain = [{SCOPE_AUTHORITY, authority.id.to_s}] - if (organization_id = authority.organization_id) - chain << {SCOPE_ORGANIZATION, organization_id.to_s} - if (organization = Organization.find?(organization_id)) && (partner_id = organization.partner_id) + if (organisation_id = authority.organisation_id) + chain << {SCOPE_ORGANISATION, organisation_id.to_s} + if (organisation = Organisation.find?(organisation_id)) && (partner_id = organisation.partner_id) chain << {SCOPE_PARTNER, partner_id.to_s} end end @@ -127,7 +127,7 @@ module PlaceOS::Model Grant.where(user_id: user_id).select(&.live?) end - # Everyone granted access to a specific scope (partner/organization admin console). + # Everyone granted access to a specific scope (partner/organisation admin console). def self.for_scope(scope_type : String, scope_id : String) : Array(Grant) Grant.where(scope_type: scope_type, scope_id: scope_id).to_a end diff --git a/src/placeos-models/module.cr b/src/placeos-models/module.cr index f0d5865c..d847bbd1 100644 --- a/src/placeos-models/module.cr +++ b/src/placeos-models/module.cr @@ -52,15 +52,15 @@ module PlaceOS::Model attribute ignore_connected : Bool = false attribute ignore_startstop : Bool = false - # PPT-526: the Organization (customer organisation) that owns this module. + # PPT-526: the Organisation (customer organisation) that owns this module. # Nullable while ownership backfill and query enforcement are phased in; - # shared device/service modules referenced by several organizations' systems + # shared device/service modules referenced by several organisations' systems # stay NULL until a sharing policy is decided. - attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organisation_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Organization, when ownership has been assigned. - def organization : PlaceOS::Model::Organization? - self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } + # The owning Organisation, when ownership has been assigned. + def organisation : PlaceOS::Model::Organisation? + self.organisation_id.try { |id| PlaceOS::Model::Organisation.find?(id) } end # Runtime Error Indicators diff --git a/src/placeos-models/organization.cr b/src/placeos-models/organisation.cr similarity index 68% rename from src/placeos-models/organization.cr rename to src/placeos-models/organisation.cr index 5294211b..92d5c330 100644 --- a/src/placeos-models/organization.cr +++ b/src/placeos-models/organisation.cr @@ -6,23 +6,23 @@ require "./partner" module PlaceOS::Model # A customer organisation (e.g. UCLA, Acadian) — the estate owner in the - # PPT-526 hierarchy: Partner -> Organization -> Authority (domain) -> ... - # This is the entity the multi-tenancy-template calls "Organization". + # PPT-526 hierarchy: Partner -> Organisation -> Authority (domain) -> ... + # This is the entity the multi-tenancy-template calls "Organisation". # # `partner_id` NULL means client-owned: the customer signed up and manages # itself without an integrator. `payer` records who receives invoices for - # this organization: the partner (integrator pays us and re-bills — the - # default channel model) or the organization directly. An organization + # this organisation: the partner (integrator pays us and re-bills — the + # default channel model) or the organisation directly. An organisation # without a partner can only pay for itself; `normalize_payer` keeps that # invariant ahead of the DB CHECK constraint. - class Organization < ::PgORM::Base + class Organisation < ::PgORM::Base include PgORM::Timestamps - table :organizations + table :organisations PAYER_PARTNER = "partner" - PAYER_ORGANIZATION = "organization" - PAYERS = [PAYER_PARTNER, PAYER_ORGANIZATION] + PAYER_ORGANISATION = "organisation" + PAYERS = [PAYER_PARTNER, PAYER_ORGANISATION] default_primary_key id : UUID, autogenerated: true @@ -38,25 +38,25 @@ module PlaceOS::Model validates :name, presence: true - validate ->(this : Organization) { + validate ->(this : Organisation) { unless PAYERS.includes?(this.payer) this.validation_error(:payer, "must be one of #{PAYERS.join(", ")}") end } - validate ->(this : Organization) { + validate ->(this : Organisation) { # Friendlier error ahead of the DB's partial unique indexes: names are # unique within a partner's book, and unique among client-owned orgs. name = this.name return if name.nil? || name.empty? - existing = Organization.where(partner_id: this.partner_id, name: name).first? + existing = Organisation.where(partner_id: this.partner_id, name: name).first? return if existing.nil? return if this.persisted? && existing.id == this.id - this.validation_error(:name, "an organization with this name already exists") + this.validation_error(:name, "an organisation with this name already exists") } protected def normalize_payer - self.payer = PAYER_ORGANIZATION if self.partner_id.nil? + self.payer = PAYER_ORGANISATION if self.partner_id.nil? end # True when the customer manages itself without an integrator (no partner). @@ -64,9 +64,9 @@ module PlaceOS::Model self.partner_id.nil? end - # Domains (authorities) owned by this organization. + # Domains (authorities) owned by this organisation. def authorities - Authority.where(organization_id: self.id) + Authority.where(organisation_id: self.id) end end end diff --git a/src/placeos-models/partner.cr b/src/placeos-models/partner.cr index 82325f08..eb88516b 100644 --- a/src/placeos-models/partner.cr +++ b/src/placeos-models/partner.cr @@ -64,9 +64,9 @@ module PlaceOS::Model Partner.where(parent_id: self.id) end - # Organizations under this partner's book of business. - def organizations - Organization.where(partner_id: self.id) + # Organisations under this partner's book of business. + def organisations + Organisation.where(partner_id: self.id) end end end diff --git a/src/placeos-models/trigger.cr b/src/placeos-models/trigger.cr index 6b6f2614..a43c8ac0 100644 --- a/src/placeos-models/trigger.cr +++ b/src/placeos-models/trigger.cr @@ -30,14 +30,14 @@ module PlaceOS::Model METHODS = %w(GET POST PUT PATCH DELETE) attribute supported_methods : Array(String) = ["POST"] - # PPT-526: the Organization (customer organisation) that owns this trigger + # PPT-526: the Organisation (customer organisation) that owns this trigger # definition. NULL = shared/cluster-wide definition. Nullable while # ownership backfill and query enforcement are phased in. - attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organisation_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Organization, when ownership has been assigned. - def organization : PlaceOS::Model::Organization? - self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } + # The owning Organisation, when ownership has been assigned. + def organisation : PlaceOS::Model::Organisation? + self.organisation_id.try { |id| PlaceOS::Model::Organisation.find?(id) } end # Association diff --git a/src/placeos-models/zone.cr b/src/placeos-models/zone.cr index 6a67fe22..7299d2b9 100644 --- a/src/placeos-models/zone.cr +++ b/src/placeos-models/zone.cr @@ -52,13 +52,13 @@ module PlaceOS::Model attribute images : Array(String) = [] of String attribute playlists : Array(String) = [] of String, es_type: "keyword" - # PPT-526: the Organization (customer organisation) that owns this zone. + # PPT-526: the Organisation (customer organisation) that owns this zone. # Nullable while ownership backfill and query enforcement are phased in. - attribute organization_id : UUID?, es_type: "keyword", mass_assignment: false + attribute organisation_id : UUID?, es_type: "keyword", mass_assignment: false - # The owning Organization, when ownership has been assigned. - def organization : PlaceOS::Model::Organization? - self.organization_id.try { |id| PlaceOS::Model::Organization.find?(id) } + # The owning Organisation, when ownership has been assigned. + def organisation : PlaceOS::Model::Organisation? + self.organisation_id.try { |id| PlaceOS::Model::Organisation.find?(id) } end attribute place_id : String? From 735ebedecc41388d8afdfec90353359791619a1d Mon Sep 17 00:00:00 2001 From: Cameron Reeves Date: Wed, 7 Oct 2026 14:37:40 +1100 Subject: [PATCH 05/23] feat: PPT-526 partner staff organisations, organisation-scoped names and last-admin guard organisations.partner_staff marks a partner's own staff organisation, whose admins and support users reach every organisation under that partner. Zone, system, edge and broker names are unique within an organisation rather than across the cluster, and the last-admin guard counts admins within the organisation of the user being removed. --- ..._alter_organisations_add_partner_staff.sql | 22 +++++++++++++++++++ spec/generator.cr | 3 ++- spec/organisation_spec.cr | 10 +++++++++ spec/user_spec.cr | 19 ++++++++++++++++ spec/zone_spec.cr | 20 +++++++++++++++++ src/placeos-models/broker.cr | 4 +++- src/placeos-models/control_system.cr | 7 +++--- src/placeos-models/edge.cr | 6 ++--- src/placeos-models/organisation.cr | 20 +++++++++++++++++ .../organisation_scoped_name.cr | 19 ++++++++++++++++ src/placeos-models/zone.cr | 6 ++--- 11 files changed, 124 insertions(+), 12 deletions(-) create mode 100644 migration/db/migrations/20261007100800000_alter_organisations_add_partner_staff.sql create mode 100644 src/placeos-models/organisation_scoped_name.cr diff --git a/migration/db/migrations/20261007100800000_alter_organisations_add_partner_staff.sql b/migration/db/migrations/20261007100800000_alter_organisations_add_partner_staff.sql new file mode 100644 index 00000000..6ebabf04 --- /dev/null +++ b/migration/db/migrations/20261007100800000_alter_organisations_add_partner_staff.sql @@ -0,0 +1,22 @@ +-- +micrate Up +-- SQL in section 'Up' is executed when this migration is applied +-- --------------------------------------------------------------------------- +-- PPT-526: an organisation flagged partner_staff is the partner's own staff +-- organisation. Its admins and support users administer every organisation +-- under that partner (partner reach), the way the management partner's staff +-- organisation administers the whole cluster. +-- --------------------------------------------------------------------------- +ALTER TABLE "organisations" ADD COLUMN IF NOT EXISTS partner_staff BOOLEAN NOT NULL DEFAULT false; + +ALTER TABLE "organisations" DROP CONSTRAINT IF EXISTS organisations_partner_staff_needs_partner; +ALTER TABLE "organisations" ADD CONSTRAINT organisations_partner_staff_needs_partner + CHECK (NOT partner_staff OR partner_id IS NOT NULL); + +CREATE INDEX IF NOT EXISTS organisations_partner_staff_index + ON "organisations" USING BTREE (partner_id) WHERE partner_staff; + +-- +micrate Down +-- SQL section 'Down' is executed when this migration is rolled back +DROP INDEX IF EXISTS organisations_partner_staff_index; +ALTER TABLE "organisations" DROP CONSTRAINT IF EXISTS organisations_partner_staff_needs_partner; +ALTER TABLE "organisations" DROP COLUMN IF EXISTS partner_staff; diff --git a/spec/generator.cr b/spec/generator.cr index a73a3f1f..c712cd15 100644 --- a/spec/generator.cr +++ b/spec/generator.cr @@ -574,11 +574,12 @@ module PlaceOS::Model ) end - def self.organisation(partner : Partner? = nil, payer : String = Organisation::PAYER_PARTNER) + def self.organisation(partner : Partner? = nil, payer : String = Organisation::PAYER_PARTNER, partner_staff : Bool = false) Organisation.new( name: Faker::Hacker.noun + "-" + RANDOM.hex(3), partner_id: partner.try(&.id), payer: payer, + partner_staff: partner_staff, ) end diff --git a/spec/organisation_spec.cr b/spec/organisation_spec.cr index 8669b67b..f85d5d48 100644 --- a/spec/organisation_spec.cr +++ b/spec/organisation_spec.cr @@ -26,6 +26,16 @@ module PlaceOS::Model org.self_managed?.should be_true end + it "requires a partner for a partner staff organisation" do + org = Generator.organisation(partner_staff: true) + org.valid?.should be_false + org.errors.map(&.field).should contain(:partner_staff) + + staff = Generator.organisation(partner: Generator.partner.save!, partner_staff: true).save! + staff.partner_staff.should be_true + Organisation.staff_of(staff.partner_id.as(UUID)).to_a.map(&.id).should eq [staff.id] + end + it "rejects an unknown payer" do org = Generator.organisation(partner: Generator.partner.save!, payer: "nobody") org.valid?.should be_false diff --git a/spec/user_spec.cr b/spec/user_spec.cr index 929bf85a..0a355d39 100644 --- a/spec/user_spec.cr +++ b/spec/user_spec.cr @@ -161,6 +161,25 @@ module PlaceOS::Model end end + it "counts remaining admins within the organisation, not the cluster" do + User.clear + org_a = Generator.organisation.save! + org_b = Generator.organisation.save! + authority_a = Generator.authority("a.test").tap(&.organisation_id = org_a.id).save! + authority_b = Generator.authority("b.test").tap(&.organisation_id = org_b.id).save! + admin_a = Generator.user(authority_a, admin: true).save! + Generator.user(authority_b, admin: true).save! + + # another organisation's admin does not count for this one + expect_raises(Model::Error, "At least one admin must remain") do + admin_a.destroy + end + + # a second admin in the same organisation does + Generator.user(authority_a, admin: true).save! + admin_a.destroy + end + it "does not raise if more than one sys_admin User remains" do User.clear user0 = Generator.user(admin: true).save! diff --git a/spec/zone_spec.cr b/spec/zone_spec.cr index 10936b4c..3fd6e1d5 100644 --- a/spec/zone_spec.cr +++ b/spec/zone_spec.cr @@ -34,6 +34,26 @@ module PlaceOS::Model end end + it "scopes name uniqueness to the organisation" do + org_a = Generator.organisation.save! + org_b = Generator.organisation.save! + name = "Boardroom #{RANDOM.hex(3)}" + + first = Generator.zone.tap { |z| z.name = name; z.organisation_id = org_a.id }.save! + Generator.zone.tap { |z| z.name = name; z.organisation_id = org_b.id }.save! + + duplicate = Generator.zone.tap { |z| z.name = name; z.organisation_id = org_a.id } + duplicate.valid?.should be_false + duplicate.errors.map(&.field).should contain(:name) + + # rows with no organisation are unique among themselves + unowned = Generator.zone.tap { |z| z.name = name }.save! + Generator.zone.tap { |z| z.name = name }.valid?.should be_false + + first.destroy + unowned.destroy + end + it "has unique tags" do zone = Generator.zone zone.tags << "hello" diff --git a/src/placeos-models/broker.cr b/src/placeos-models/broker.cr index 73e47ea2..07691616 100644 --- a/src/placeos-models/broker.cr +++ b/src/placeos-models/broker.cr @@ -2,6 +2,7 @@ require "openssl" require "random" require "./base/model" +require "./organisation_scoped_name" module PlaceOS::Model class Broker < ModelBase @@ -50,7 +51,8 @@ module PlaceOS::Model validates :host, presence: true validates :secret, presence: true - ensure_unique :name + include OrganisationScopedName + ensure_unique_name_within_organisation validate ->Broker.validate_filters(Broker) diff --git a/src/placeos-models/control_system.cr b/src/placeos-models/control_system.cr index 02d2ad02..67dc1427 100644 --- a/src/placeos-models/control_system.cr +++ b/src/placeos-models/control_system.cr @@ -5,6 +5,7 @@ require "future" require "./converter/time_location" require "./base/model" +require "./organisation_scoped_name" require "./settings" require "./email" require "./utilities/settings_helper" @@ -145,10 +146,8 @@ module PlaceOS::Model # Zones and settings are only required for confident coding validates :name, presence: true - # TODO: Ensure unique regardless of casing - ensure_unique :name do |name| - name.strip - end + include OrganisationScopedName + ensure_unique_name_within_organisation # Validate URIs validate ->(this : ControlSystem) { diff --git a/src/placeos-models/edge.cr b/src/placeos-models/edge.cr index aae3b98f..38f5f4ce 100644 --- a/src/placeos-models/edge.cr +++ b/src/placeos-models/edge.cr @@ -1,4 +1,5 @@ require "./base/model" +require "./organisation_scoped_name" require "./user" require "./api_key" @@ -139,8 +140,7 @@ module PlaceOS::Model # Validation ############################################################################################### - ensure_unique :name do |name| - name.strip - end + include OrganisationScopedName + ensure_unique_name_within_organisation end end diff --git a/src/placeos-models/organisation.cr b/src/placeos-models/organisation.cr index 92d5c330..c47046c0 100644 --- a/src/placeos-models/organisation.cr +++ b/src/placeos-models/organisation.cr @@ -31,6 +31,10 @@ module PlaceOS::Model attribute payer : String = PAYER_PARTNER, mass_assignment: false attribute config : Hash(String, JSON::Any) = {} of String => JSON::Any + # The partner's own staff organisation: its admins and support users reach + # every organisation under `partner_id`. Requires a partner. + attribute partner_staff : Bool = false, mass_assignment: false + attribute partner_id : UUID? belongs_to :partner, class_name: Partner, foreign_key: partner_id @@ -44,6 +48,12 @@ module PlaceOS::Model end } + validate ->(this : Organisation) { + if this.partner_staff && this.partner_id.nil? + this.validation_error(:partner_staff, "requires a partner") + end + } + validate ->(this : Organisation) { # Friendlier error ahead of the DB's partial unique indexes: names are # unique within a partner's book, and unique among client-owned orgs. @@ -68,5 +78,15 @@ module PlaceOS::Model def authorities Authority.where(organisation_id: self.id) end + + # Every organisation under the same partner, this one included. + def partner_organisations + Organisation.where(partner_id: self.partner_id) + end + + # The staff organisations of a partner. + def self.staff_of(partner_id : UUID) + Organisation.where(partner_id: partner_id, partner_staff: true) + end end end diff --git a/src/placeos-models/organisation_scoped_name.cr b/src/placeos-models/organisation_scoped_name.cr new file mode 100644 index 00000000..8c912d13 --- /dev/null +++ b/src/placeos-models/organisation_scoped_name.cr @@ -0,0 +1,19 @@ +require "./base/model" + +module PlaceOS::Model + # Name uniqueness for the organisation-owned estate models (zone, system, + # edge, broker): unique within an organisation, and unique among rows that + # have no organisation. Backed by the partial unique indexes on + # (organisation_id, name). + module OrganisationScopedName + macro ensure_unique_name_within_organisation + validate :name, "should be unique within the organisation", ->(this : self) do + name = this.name.strip + return true if name.empty? + this.name = name unless this.persisted? + existing = self.where(name: name, organisation_id: this.organisation_id).first? + !(existing && (!this.persisted? || existing.id != this.id)) + end + end + end +end diff --git a/src/placeos-models/zone.cr b/src/placeos-models/zone.cr index 7299d2b9..26eed5ac 100644 --- a/src/placeos-models/zone.cr +++ b/src/placeos-models/zone.cr @@ -1,6 +1,7 @@ require "time" require "./base/model" +require "./organisation_scoped_name" require "./settings" require "./utilities/settings_helper" require "./utilities/metadata_helper" @@ -129,9 +130,8 @@ module PlaceOS::Model ############################################################################################### validates :name, presence: true - ensure_unique :name do |name| - name.strip - end + include OrganisationScopedName + ensure_unique_name_within_organisation # Callbacks ############################################################################################### From 1848a3d9a89f2cc3907c985fac51d572b4755bc2 Mon Sep 17 00:00:00 2001 From: Cameron Reeves Date: Wed, 7 Oct 2026 15:44:36 +1100 Subject: [PATCH 06/23] fix: PPT-526 keep the last-admin guard cluster-wide A per-organisation guard blocks deleting a customer's whole domain, since the organisation's last admin goes with it. The organisation-level rule belongs in the API, where the caller's reach is known. --- spec/user_spec.cr | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/spec/user_spec.cr b/spec/user_spec.cr index 0a355d39..929bf85a 100644 --- a/spec/user_spec.cr +++ b/spec/user_spec.cr @@ -161,25 +161,6 @@ module PlaceOS::Model end end - it "counts remaining admins within the organisation, not the cluster" do - User.clear - org_a = Generator.organisation.save! - org_b = Generator.organisation.save! - authority_a = Generator.authority("a.test").tap(&.organisation_id = org_a.id).save! - authority_b = Generator.authority("b.test").tap(&.organisation_id = org_b.id).save! - admin_a = Generator.user(authority_a, admin: true).save! - Generator.user(authority_b, admin: true).save! - - # another organisation's admin does not count for this one - expect_raises(Model::Error, "At least one admin must remain") do - admin_a.destroy - end - - # a second admin in the same organisation does - Generator.user(authority_a, admin: true).save! - admin_a.destroy - end - it "does not raise if more than one sys_admin User remains" do User.clear user0 = Generator.user(admin: true).save! From 9ceba037b36246b62853d93545f9d34cad94cfe1 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Thu, 5 Nov 2026 20:50:04 +1100 Subject: [PATCH 07/23] chore: PPT-526 renumber the tenancy migrations above master Rebased onto master; move the migrations to 20261105 so they run after everything that merged in the meantime. Co-Authored-By: Claude Opus 5.5 --- ...sql => 20261105100500000_add_partners_and_organisations.sql} | 2 +- ...ql => 20261105100600000_backfill_organisation_ownership.sql} | 2 +- ...00700000_add_grants.sql => 20261105100700000_add_grants.sql} | 0 ...20261105100800000_alter_organisations_add_partner_staff.sql} | 0 4 files changed, 2 insertions(+), 2 deletions(-) rename migration/db/migrations/{20261007100500000_add_partners_and_organisations.sql => 20261105100500000_add_partners_and_organisations.sql} (99%) rename migration/db/migrations/{20261007100600000_backfill_organisation_ownership.sql => 20261105100600000_backfill_organisation_ownership.sql} (99%) rename migration/db/migrations/{20261007100700000_add_grants.sql => 20261105100700000_add_grants.sql} (100%) rename migration/db/migrations/{20261007100800000_alter_organisations_add_partner_staff.sql => 20261105100800000_alter_organisations_add_partner_staff.sql} (100%) diff --git a/migration/db/migrations/20261007100500000_add_partners_and_organisations.sql b/migration/db/migrations/20261105100500000_add_partners_and_organisations.sql similarity index 99% rename from migration/db/migrations/20261007100500000_add_partners_and_organisations.sql rename to migration/db/migrations/20261105100500000_add_partners_and_organisations.sql index cefe2179..20b2149b 100644 --- a/migration/db/migrations/20261007100500000_add_partners_and_organisations.sql +++ b/migration/db/migrations/20261105100500000_add_partners_and_organisations.sql @@ -3,7 +3,7 @@ -- MERGE-TIME CHECK: micrate refuses out-of-order version ids (see models#323). -- If any later-dated migration lands on master before this merges, renumber --- this file AND 20261007100600000 above it (preserving schema-before-backfill +-- this file AND 20261105100600000 above it (preserving schema-before-backfill -- order). Safe: neither has been applied anywhere and the backfill is -- idempotent. diff --git a/migration/db/migrations/20261007100600000_backfill_organisation_ownership.sql b/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql similarity index 99% rename from migration/db/migrations/20261007100600000_backfill_organisation_ownership.sql rename to migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql index 904715a2..27de0567 100644 --- a/migration/db/migrations/20261007100600000_backfill_organisation_ownership.sql +++ b/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql @@ -219,4 +219,4 @@ WHERE e.id = c.id -- Deliberate no-op: the backfill only fills NULLs and creates rows that -- operators may since have adopted; unwinding it automatically could destroy -- hand-made ownership assignments. Rolling back the schema migration --- (20261007100500000) removes the columns and tables wholesale. +-- (20261105100500000) removes the columns and tables wholesale. diff --git a/migration/db/migrations/20261007100700000_add_grants.sql b/migration/db/migrations/20261105100700000_add_grants.sql similarity index 100% rename from migration/db/migrations/20261007100700000_add_grants.sql rename to migration/db/migrations/20261105100700000_add_grants.sql diff --git a/migration/db/migrations/20261007100800000_alter_organisations_add_partner_staff.sql b/migration/db/migrations/20261105100800000_alter_organisations_add_partner_staff.sql similarity index 100% rename from migration/db/migrations/20261007100800000_alter_organisations_add_partner_staff.sql rename to migration/db/migrations/20261105100800000_alter_organisations_add_partner_staff.sql From 97147449b85f3b4b628570e52bd9d54755bf13f3 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Thu, 5 Nov 2026 20:50:16 +1100 Subject: [PATCH 08/23] style: PPT-526 short block notation in zone spec Co-Authored-By: Claude Opus 5.5 --- spec/zone_spec.cr | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec/zone_spec.cr b/spec/zone_spec.cr index 3fd6e1d5..4f472700 100644 --- a/spec/zone_spec.cr +++ b/spec/zone_spec.cr @@ -47,8 +47,8 @@ module PlaceOS::Model duplicate.errors.map(&.field).should contain(:name) # rows with no organisation are unique among themselves - unowned = Generator.zone.tap { |z| z.name = name }.save! - Generator.zone.tap { |z| z.name = name }.valid?.should be_false + unowned = Generator.zone.tap(&.name=(name)).save! + Generator.zone.tap(&.name=(name)).valid?.should be_false first.destroy unowned.destroy From 928f6afebe5252d64b8ddef8a0736f2d51d6e431 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Fri, 6 Nov 2026 00:45:55 +1100 Subject: [PATCH 09/23] feat: PPT-526 record change history for partners, organisations and grants Grants are correlated to their scope, so a partner, organisation or authority can audit who was given access to it; organisations are correlated to their managing partner. Co-Authored-By: Claude Opus 5.5 --- spec/grant_spec.cr | 18 ++++++++++++++++++ spec/organisation_spec.cr | 17 +++++++++++++++++ spec/partner_spec.cr | 12 ++++++++++++ src/placeos-models/grant.cr | 8 ++++++++ src/placeos-models/organisation.cr | 7 +++++++ src/placeos-models/partner.cr | 2 ++ 6 files changed, 64 insertions(+) diff --git a/spec/grant_spec.cr b/spec/grant_spec.cr index ce03b9e1..5dc6ecd2 100644 --- a/spec/grant_spec.cr +++ b/spec/grant_spec.cr @@ -105,5 +105,23 @@ module PlaceOS::Model user.destroy Grant.find?(grant.id.not_nil!).should be_nil end + + it "records changes in history against the scope" do + _, org, _, user = build_estate + grantor = Generator.user.save! + grant = Generator.grant(user, Grant::SCOPE_ORGANISATION, org.id.not_nil!.to_s) + grant.granted_by = grantor.id + grant.save! + grant.permission_flags = Permissions::Manage + grant.save! + grant.destroy + + entries = History.correlated(org.id.not_nil!.to_s).where(resource_type: "grants").to_a + entries.map(&.action).should eq ["delete", "update", "create"] + entries.map(&.resource_id).uniq!.should eq [grant.id.to_s] + entries[1].changed_fields.should eq ["permissions"] + entries[2].diff["granted_by"].should eq JSON.parse([nil, grantor.id].to_json) + entries[0].snapshot.not_nil!["user_id"].should eq user.id + end end end diff --git a/spec/organisation_spec.cr b/spec/organisation_spec.cr index f85d5d48..90b0cec7 100644 --- a/spec/organisation_spec.cr +++ b/spec/organisation_spec.cr @@ -110,5 +110,22 @@ module PlaceOS::Model Zone.find!(zone.id.not_nil!).organisation.try(&.id).should eq org.id ControlSystem.find!(sys.id.not_nil!).organisation.try(&.id).should eq org.id end + + it "records changes in history against its partner" do + partner = Generator.partner.save! + org = Generator.organisation(partner: partner).save! + org.name = "renamed-#{RANDOM.hex(3)}" + org.save! + + org.change_history.to_a.map(&.action).should eq ["update", "create"] + entries = History.correlated(partner.id.not_nil!.to_s).where(resource_type: "organisations").to_a + entries.map(&.resource_id).uniq!.should eq [org.id.to_s] + entries.first.changed_fields.should eq ["name"] + end + + it "records a self-managed organisation without a correlation" do + org = Generator.organisation.save! + org.change_history.to_a.first.correlation_id.should be_nil + end end end diff --git a/spec/partner_spec.cr b/spec/partner_spec.cr index 74a270d5..24322de9 100644 --- a/spec/partner_spec.cr +++ b/spec/partner_spec.cr @@ -66,5 +66,17 @@ module PlaceOS::Model expect_raises(Exception, /foreign key/) { partner.destroy } Partner.find?(partner.id.not_nil!).should_not be_nil end + + it "records changes in history" do + partner = Generator.partner.save! + partner.description = "managed services" + partner.save! + partner.destroy + + entries = partner.change_history.to_a + entries.map(&.action).should eq ["delete", "update", "create"] + entries[1].changed_fields.should eq ["description"] + entries[0].snapshot.not_nil!["name"].should eq partner.name + end end end diff --git a/src/placeos-models/grant.cr b/src/placeos-models/grant.cr index 5907a83b..64d2ef8f 100644 --- a/src/placeos-models/grant.cr +++ b/src/placeos-models/grant.cr @@ -6,6 +6,7 @@ require "./permissions" require "./authority" require "./organisation" require "./partner" +require "./history" module PlaceOS::Model # PPT-526 Stage 3: a cross-tenant authorization grant. @@ -21,6 +22,7 @@ module PlaceOS::Model # TEXT id) so it carries no FK; a grant naming a deleted scope is inert. class Grant < ::PgORM::Base include PgORM::Timestamps + include History::Tracked table :grants @@ -131,5 +133,11 @@ module PlaceOS::Model def self.for_scope(scope_type : String, scope_id : String) : Array(Grant) Grant.where(scope_type: scope_type, scope_id: scope_id).to_a end + + # Changes are also found under the scope, so a partner, organisation or + # authority can audit who was given access to it + def history_correlation_id : String? + scope_id + end end end diff --git a/src/placeos-models/organisation.cr b/src/placeos-models/organisation.cr index c47046c0..d8e4bded 100644 --- a/src/placeos-models/organisation.cr +++ b/src/placeos-models/organisation.cr @@ -3,6 +3,7 @@ require "uuid/json" require "./base/model" require "./partner" +require "./history" module PlaceOS::Model # A customer organisation (e.g. UCLA, Acadian) — the estate owner in the @@ -17,6 +18,7 @@ module PlaceOS::Model # invariant ahead of the DB CHECK constraint. class Organisation < ::PgORM::Base include PgORM::Timestamps + include History::Tracked table :organisations @@ -88,5 +90,10 @@ module PlaceOS::Model def self.staff_of(partner_id : UUID) Organisation.where(partner_id: partner_id, partner_staff: true) end + + # Changes are also found under the managing partner + def history_correlation_id : String? + partner_id.try(&.to_s) + end end end diff --git a/src/placeos-models/partner.cr b/src/placeos-models/partner.cr index eb88516b..b24e7f77 100644 --- a/src/placeos-models/partner.cr +++ b/src/placeos-models/partner.cr @@ -2,6 +2,7 @@ require "uuid" require "uuid/json" require "./base/model" +require "./history" module PlaceOS::Model # An integrator/reseller organisation (e.g. NTT) that brings clients onto @@ -14,6 +15,7 @@ module PlaceOS::Model # (distributor -> reseller); it carries no behaviour yet. class Partner < ::PgORM::Base include PgORM::Timestamps + include History::Tracked table :partners From 58c1789364d0333c1e8bd240baa85487fe44cdac Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Fri, 6 Nov 2026 00:45:55 +1100 Subject: [PATCH 10/23] fix(spec): unique signage AI provider names in the generator Bare Faker nouns occasionally collided on the (authority, name) unique index when a spec created two providers. Co-Authored-By: Claude Opus 5.5 --- spec/generator.cr | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec/generator.cr b/spec/generator.cr index c712cd15..f35992a1 100644 --- a/spec/generator.cr +++ b/spec/generator.cr @@ -788,7 +788,7 @@ module PlaceOS::Model text_model : String? = nil, ) row = SignageAIProvider.new - row.name = name || Faker::Hacker.noun + row.name = name || "#{Faker::Hacker.noun}-#{RANDOM.hex(3)}" row.provider = provider row.authority_id = authority.try(&.id.as(String)) row.credentials = credentials From b50200942c7e6bf30d999c1f500ce1375408edc0 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Fri, 6 Nov 2026 00:45:55 +1100 Subject: [PATCH 11/23] fix(shard.yml): require pg-orm 2.5.3 Keeps each fiber's connection and transaction on the fiber, fixing lost transaction records ("There is an existing transaction in this connection") under parallel execution contexts. Co-Authored-By: Claude Opus 5.5 --- shard.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/shard.yml b/shard.yml index 67aa6402..8f16c3e1 100644 --- a/shard.yml +++ b/shard.yml @@ -41,7 +41,7 @@ dependencies: # ORM for Postgres built on active-model pg-orm: github: spider-gazelle/pg-orm - version: ">= 2.5.1" + version: ">= 2.5.3" # PlaceOS calendar for Tenant model place_calendar: From adf6640fbd5ad09981c60d5ecbcfc052c5cbb628 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:37:04 +1100 Subject: [PATCH 12/23] test: quarantine ambiguous ownership during upgrades --- docker-compose.yml | 1 + spec/organisation_backfill_spec.cr | 140 +++++++++++++++++++++++ spec/tenancy_ownership_conflicts_spec.cr | 55 +++++++++ 3 files changed, 196 insertions(+) create mode 100644 spec/organisation_backfill_spec.cr create mode 100644 spec/tenancy_ownership_conflicts_spec.cr diff --git a/docker-compose.yml b/docker-compose.yml index c2696da3..82660701 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -9,6 +9,7 @@ services: - ${PWD}/shard.yml:/app/shard.yml.input - ${PWD}/coverage:/app/coverage - ${PWD}/.ameba.yml:/app/.ameba.yml + - ${PWD}/migration/db/migrations:/app/migration/db/migrations:ro depends_on: - migrator - postgres diff --git a/spec/organisation_backfill_spec.cr b/spec/organisation_backfill_spec.cr new file mode 100644 index 00000000..15f964b9 --- /dev/null +++ b/spec/organisation_backfill_spec.cr @@ -0,0 +1,140 @@ +require "./helper" + +module PlaceOS::Model + # Execute the shipped migration, rather than a copy of its ownership queries. + def self.apply_organisation_backfill + path = File.join(__DIR__, "..", "migration", "db", "migrations", "20261105100600000_backfill_organisation_ownership.sql") + sql = File.read(path).split("-- +micrate Down", 2).first + statement = String::Builder.new + block = false + sql.each_line do |line| + if line.includes?("-- +micrate StatementBegin") + block = true + elsif line.includes?("-- +micrate StatementEnd") + PgORM::Database.connection(&.exec(statement.to_s)) + statement = String::Builder.new + block = false + else + statement << line << '\n' + if !block && line.rstrip.ends_with?(';') + PgORM::Database.connection(&.exec(statement.to_s)) + statement = String::Builder.new + end + end + end + end + + describe "organisation ownership migration" do + around_each do |example| + PgORM::Database.transaction do |transaction| + example.run + ensure + transaction.rollback unless transaction.closed? + end + end + + it "quarantines a system with both owned and unknown zones" do + organisation = Generator.organisation.save! + owned = Generator.zone.tap(&.organisation_id = organisation.id).save! + unknown = Generator.zone.save! + system = Generator.control_system.tap(&.zones = [owned.id.as(String), unknown.id.as(String)]).save! + + apply_organisation_backfill + + ControlSystem.find!(system.id.as(String)).organisation_id.should be_nil + end + + it "assigns a system whose zones all have the same known owner" do + organisation = Generator.organisation.save! + zones = Array.new(2) { Generator.zone.tap(&.organisation_id = organisation.id).save! } + system = Generator.control_system.tap(&.zones = zones.map(&.id.as(String))).save! + + apply_organisation_backfill + + ControlSystem.find!(system.id.as(String)).organisation_id.should eq organisation.id + end + + it "quarantines a system whose zone array includes a missing reference" do + organisation = Generator.organisation.save! + owned = Generator.zone.tap(&.organisation_id = organisation.id).save! + system = Generator.control_system.tap(&.zones = [owned.id.as(String), "zone-missing-#{RANDOM.hex(5)}"]).save! + + apply_organisation_backfill + + ControlSystem.find!(system.id.as(String)).organisation_id.should be_nil + end + + it "quarantines a shared module referenced by owned and unknown systems" do + organisation = Generator.organisation.save! + mod = Generator.module(driver: Generator.driver(role: Driver::Role::Device)).save! + Generator.control_system.tap do |system| + system.organisation_id = organisation.id + system.modules = [mod.id.as(String)] + end.save! + Generator.control_system.tap(&.modules = [mod.id.as(String)]).save! + + apply_organisation_backfill + + Module.find!(mod.id.as(String)).organisation_id.should be_nil + end + + it "assigns a shared module when every referencing system has the same owner" do + organisation = Generator.organisation.save! + mod = Generator.module(driver: Generator.driver(role: Driver::Role::Device)).save! + 2.times do + Generator.control_system.tap do |system| + system.organisation_id = organisation.id + system.modules = [mod.id.as(String)] + end.save! + end + + apply_organisation_backfill + + Module.find!(mod.id.as(String)).organisation_id.should eq organisation.id + end + + it "quarantines a logic module also referenced by an unknown system" do + organisation = Generator.organisation.save! + owned = Generator.control_system.tap(&.organisation_id = organisation.id).save! + mod = Generator.module(driver: Generator.driver(role: Driver::Role::Logic), control_system: owned).save! + Generator.control_system.tap(&.modules = [mod.id.as(String)]).save! + + apply_organisation_backfill + + Module.find!(mod.id.as(String)).organisation_id.should be_nil + end + + it "quarantines a claimed zone tree containing a conflicting assigned owner" do + organisation = Generator.organisation.save! + other = Generator.organisation.save! + root = Generator.zone.save! + Generator.zone.tap do |zone| + zone.parent_id = root.id + zone.organisation_id = other.id + end.save! + unknown = Generator.zone.tap(&.parent_id = root.id).save! + Generator.authority("backfill-#{RANDOM.hex(5)}.test").tap do |authority| + authority.organisation_id = organisation.id + authority.config["org_zone"] = JSON::Any.new(root.id.as(String)) + end.save! + + apply_organisation_backfill + + Zone.find!(unknown.id.as(String)).organisation_id.should be_nil + Zone.find!(root.id.as(String)).organisation_id.should be_nil + end + + it "preserves already assigned ownership when legacy references are unresolved" do + organisation = Generator.organisation.save! + unknown = Generator.zone.save! + system = Generator.control_system.tap do |row| + row.organisation_id = organisation.id + row.zones = [unknown.id.as(String)] + end.save! + + apply_organisation_backfill + + ControlSystem.find!(system.id.as(String)).organisation_id.should eq organisation.id + end + end +end diff --git a/spec/tenancy_ownership_conflicts_spec.cr b/spec/tenancy_ownership_conflicts_spec.cr new file mode 100644 index 00000000..88e82bbe --- /dev/null +++ b/spec/tenancy_ownership_conflicts_spec.cr @@ -0,0 +1,55 @@ +require "./helper" + +module PlaceOS::Model + describe "tenancy ownership reconciliation report" do + around_each do |example| + PgORM::Database.transaction do |transaction| + example.run + ensure + transaction.rollback unless transaction.closed? + end + end + + it "reports an already assigned system's unknown references without changing its owner" do + organisation = Generator.organisation.save! + unknown = Generator.zone.save! + system = Generator.control_system.tap do |row| + row.organisation_id = organisation.id + row.zones = [unknown.id.as(String)] + end.save! + + PgORM::Database.connection do |db| + db.query_one("SELECT to_regclass('tenancy_ownership_conflicts') IS NOT NULL", &.read(Bool)).should be_true + count = db.query_one(<<-SQL, system.id, unknown.id, &.read(Int64)) + SELECT COUNT(*) FROM tenancy_ownership_conflicts + WHERE resource_type = 'sys' AND resource_id = $1 AND reason = 'unknown_reference' + AND related_type = 'zone' AND related_id = $2 + SQL + count.should eq 1 + end + ControlSystem.find!(system.id.as(String)).organisation_id.should eq organisation.id + end + + it "reports a conflicting assigned zone parent without silently reassigning either row" do + organisation = Generator.organisation.save! + other = Generator.organisation.save! + parent = Generator.zone.tap(&.organisation_id = organisation.id).save! + child = Generator.zone.tap do |row| + row.parent_id = parent.id + row.organisation_id = other.id + end.save! + + PgORM::Database.connection do |db| + db.query_one("SELECT to_regclass('tenancy_ownership_conflicts') IS NOT NULL", &.read(Bool)).should be_true + count = db.query_one(<<-SQL, child.id, parent.id, &.read(Int64)) + SELECT COUNT(*) FROM tenancy_ownership_conflicts + WHERE resource_type = 'zone' AND resource_id = $1 AND reason = 'ownership_mismatch' + AND related_type = 'zone' AND related_id = $2 + SQL + count.should eq 1 + end + Zone.find!(child.id.as(String)).organisation_id.should eq other.id + Zone.find!(parent.id.as(String)).organisation_id.should eq organisation.id + end + end +end From 6625649d5d291ca79fd5f18e53b4ad97bd48f1df Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:44:29 +1100 Subject: [PATCH 13/23] fix: quarantine unresolved organisation ownership --- ...600000_backfill_organisation_ownership.sql | 53 ++-- ...00000_reconcile_organisation_ownership.sql | 234 ++++++++++++++++++ 2 files changed, 265 insertions(+), 22 deletions(-) create mode 100644 migration/db/migrations/20261117100500000_reconcile_organisation_ownership.sql diff --git a/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql b/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql index 27de0567..71df4235 100644 --- a/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql +++ b/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql @@ -98,6 +98,11 @@ tree_claims AS ( INNER JOIN zone_roots r ON r.id = a.config->>'org_zone' WHERE COALESCE(a.config->>'org_zone', '') <> '' AND a.organisation_id IS NOT NULL + UNION ALL + SELECT r.root_id, false AS names_root, z.organisation_id + FROM "zone" z + INNER JOIN zone_roots r ON r.id = z.id + WHERE z.organisation_id IS NOT NULL ), org_owner AS ( SELECT root_id, MIN(organisation_id::text)::uuid AS organisation_id @@ -135,11 +140,12 @@ WITH sys_candidates AS ( SELECT s2.id AS sys_id, s2.name, MIN(z.organisation_id::text)::uuid AS organisation_id FROM "sys" s2 - INNER JOIN "zone" z ON z.id = ANY(s2.zones) - WHERE z.organisation_id IS NOT NULL - AND s2.organisation_id IS NULL + CROSS JOIN LATERAL unnest(s2.zones) AS reference(zone_id) + LEFT JOIN "zone" z ON z.id = reference.zone_id + WHERE s2.organisation_id IS NULL GROUP BY s2.id, s2.name HAVING COUNT(DISTINCT z.organisation_id) = 1 + AND bool_and(z.organisation_id IS NOT NULL) ), ranked AS ( SELECT sys_id, name, organisation_id, @@ -160,26 +166,29 @@ WHERE s.id = r.sys_id ); -- +micrate StatementEnd --- 5a. Logic modules via their control system -UPDATE "mod" m -SET organisation_id = s.organisation_id -FROM "sys" s -WHERE m.control_system_id = s.id - AND s.organisation_id IS NOT NULL - AND m.organisation_id IS NULL; - --- 5b. Device/service modules via the systems that reference them -UPDATE "mod" m -SET organisation_id = sc.organisation_id -FROM ( - SELECT m2.id AS mod_id, MIN(s.organisation_id::text)::uuid AS organisation_id - FROM "mod" m2 - INNER JOIN "sys" s ON m2.id = ANY(s.modules) - WHERE s.organisation_id IS NOT NULL - GROUP BY m2.id +-- 5. All module ownership sources must agree, including references from systems +-- other than a logic module's parent. Unknown/missing owners veto inference. +-- +micrate StatementBegin +WITH module_systems AS ( + SELECT id AS mod_id, control_system_id AS sys_id + FROM "mod" WHERE control_system_id IS NOT NULL + UNION + SELECT m.id AS mod_id, s.id AS sys_id + FROM "mod" m INNER JOIN "sys" s ON m.id = ANY(s.modules) +), +module_owners AS ( + SELECT links.mod_id, MIN(s.organisation_id::text)::uuid AS organisation_id + FROM module_systems links + LEFT JOIN "sys" s ON s.id = links.sys_id + GROUP BY links.mod_id HAVING COUNT(DISTINCT s.organisation_id) = 1 -) sc -WHERE m.id = sc.mod_id AND m.organisation_id IS NULL; + AND bool_and(s.organisation_id IS NOT NULL) +) +UPDATE "mod" m +SET organisation_id = owners.organisation_id +FROM module_owners owners +WHERE m.id = owners.mod_id AND m.organisation_id IS NULL; +-- +micrate StatementEnd -- 6. System-scoped trigger definitions UPDATE "trigger" t diff --git a/migration/db/migrations/20261117100500000_reconcile_organisation_ownership.sql b/migration/db/migrations/20261117100500000_reconcile_organisation_ownership.sql new file mode 100644 index 00000000..50b2e8e9 --- /dev/null +++ b/migration/db/migrations/20261117100500000_reconcile_organisation_ownership.sql @@ -0,0 +1,234 @@ +-- +micrate Up +-- Retry only unassigned ownership using conservative inference. Existing owners +-- are never corrected automatically: the report below exposes them for review. +-- 3. Zones via org_zone → root-zone walk (unambiguous owners only). +-- UNION (not UNION ALL) so accidental cycles in zone parentage terminate. +-- Ambiguity is judged per TREE, not per org_zone string: every authority's +-- org_zone claim is resolved to its tree root, a tree claimed by more than +-- one distinct organisation is vetoed, and ownership is only assigned when at +-- least one claim names the root itself (a claim on a sub-zone alone must +-- not annex the whole tree). Rows whose (organisation_id, name) would collide +-- with the partial unique indexes are skipped (left NULL for a human) — +-- duplicate names within one estate are legacy race artifacts. +-- +micrate StatementBegin +WITH RECURSIVE zone_roots AS ( + SELECT id, id AS root_id + FROM "zone" + WHERE parent_id IS NULL OR parent_id = '' + UNION + SELECT z.id, r.root_id + FROM "zone" z + INNER JOIN zone_roots r ON z.parent_id = r.id +), +tree_claims AS ( + SELECT r.root_id, + (a.config->>'org_zone' = r.root_id) AS names_root, + a.organisation_id + FROM "authority" a + INNER JOIN zone_roots r ON r.id = a.config->>'org_zone' + WHERE COALESCE(a.config->>'org_zone', '') <> '' + AND a.organisation_id IS NOT NULL + UNION ALL + SELECT r.root_id, false AS names_root, z.organisation_id + FROM "zone" z + INNER JOIN zone_roots r ON r.id = z.id + WHERE z.organisation_id IS NOT NULL +), +org_owner AS ( + SELECT root_id, MIN(organisation_id::text)::uuid AS organisation_id + FROM tree_claims + GROUP BY root_id + HAVING COUNT(DISTINCT organisation_id) = 1 + AND bool_or(names_root) +), +candidates AS ( + SELECT z.id, o.organisation_id, z.name, + ROW_NUMBER() OVER ( + PARTITION BY o.organisation_id, z.name + ORDER BY z.created_at, z.id + ) AS rn + FROM "zone" z + INNER JOIN zone_roots r ON z.id = r.id + INNER JOIN org_owner o ON r.root_id = o.root_id + WHERE z.organisation_id IS NULL +) +UPDATE "zone" z +SET organisation_id = c.organisation_id +FROM candidates c +WHERE z.id = c.id + AND c.rn = 1 + AND NOT EXISTS ( + SELECT 1 FROM "zone" x + WHERE x.organisation_id = c.organisation_id AND x.name = z.name AND x.id <> z.id + ); +-- +micrate StatementEnd + +-- 4. Systems: single distinct organisation across their zones. Same collision +-- skip as zones (sys carries a (organisation_id, name) partial unique index). +-- +micrate StatementBegin +WITH sys_candidates AS ( + SELECT s2.id AS sys_id, s2.name, + MIN(z.organisation_id::text)::uuid AS organisation_id + FROM "sys" s2 + CROSS JOIN LATERAL unnest(s2.zones) AS reference(zone_id) + LEFT JOIN "zone" z ON z.id = reference.zone_id + WHERE s2.organisation_id IS NULL + GROUP BY s2.id, s2.name + HAVING COUNT(DISTINCT z.organisation_id) = 1 + AND bool_and(z.organisation_id IS NOT NULL) +), +ranked AS ( + SELECT sys_id, name, organisation_id, + ROW_NUMBER() OVER ( + PARTITION BY organisation_id, name + ORDER BY sys_id + ) AS rn + FROM sys_candidates +) +UPDATE "sys" s +SET organisation_id = r.organisation_id +FROM ranked r +WHERE s.id = r.sys_id + AND r.rn = 1 + AND NOT EXISTS ( + SELECT 1 FROM "sys" x + WHERE x.organisation_id = r.organisation_id AND x.name = s.name AND x.id <> s.id + ); +-- +micrate StatementEnd + +-- 5. All module ownership sources must agree, including references from systems +-- other than a logic module's parent. Unknown/missing owners veto inference. +-- +micrate StatementBegin +WITH module_systems AS ( + SELECT id AS mod_id, control_system_id AS sys_id + FROM "mod" WHERE control_system_id IS NOT NULL + UNION + SELECT m.id AS mod_id, s.id AS sys_id + FROM "mod" m INNER JOIN "sys" s ON m.id = ANY(s.modules) +), +module_owners AS ( + SELECT links.mod_id, MIN(s.organisation_id::text)::uuid AS organisation_id + FROM module_systems links + LEFT JOIN "sys" s ON s.id = links.sys_id + GROUP BY links.mod_id + HAVING COUNT(DISTINCT s.organisation_id) = 1 + AND bool_and(s.organisation_id IS NOT NULL) +) +UPDATE "mod" m +SET organisation_id = owners.organisation_id +FROM module_owners owners +WHERE m.id = owners.mod_id AND m.organisation_id IS NULL; +-- +micrate StatementEnd + +-- 6. System-scoped trigger definitions +UPDATE "trigger" t +SET organisation_id = s.organisation_id +FROM "sys" s +WHERE t.control_system_id = s.id + AND s.organisation_id IS NOT NULL + AND t.organisation_id IS NULL; + +-- 7. Edges via their bound user's authority. Same collision skip (edge +-- carries a (organisation_id, name) partial unique index). +-- +micrate StatementBegin +WITH edge_candidates AS ( + SELECT e.id, e.name, a.organisation_id, + ROW_NUMBER() OVER ( + PARTITION BY a.organisation_id, e.name + ORDER BY e.id + ) AS rn + FROM "edge" e + INNER JOIN "user" u ON e.user_id = u.id + INNER JOIN "authority" a ON u.authority_id = a.id + WHERE a.organisation_id IS NOT NULL + AND e.organisation_id IS NULL +) +UPDATE "edge" e +SET organisation_id = c.organisation_id +FROM edge_candidates c +WHERE e.id = c.id + AND c.rn = 1 + AND NOT EXISTS ( + SELECT 1 FROM "edge" x + WHERE x.organisation_id = c.organisation_id AND x.name = e.name AND x.id <> e.id + ); +-- +micrate StatementEnd + + +-- A durable, read-only inventory surface for explicit reconciliation. NULL +-- brokers and unscoped triggers are intentional platform resources, not orphans. +CREATE OR REPLACE VIEW tenancy_ownership_conflicts AS +WITH resources AS ( + SELECT 'authority'::text AS resource_type, id AS resource_id, organisation_id FROM authority + UNION ALL SELECT 'zone', id, organisation_id FROM zone + UNION ALL SELECT 'sys', id, organisation_id FROM sys + UNION ALL SELECT 'mod', id, organisation_id FROM mod + UNION ALL SELECT 'edge', id, organisation_id FROM edge + UNION ALL SELECT 'broker', id, organisation_id FROM broker WHERE organisation_id IS NOT NULL + UNION ALL SELECT 'trigger', id, organisation_id FROM "trigger" + WHERE organisation_id IS NOT NULL OR control_system_id IS NOT NULL +), links AS ( + SELECT 'zone'::text AS resource_type, z.id AS resource_id, z.organisation_id, + 'zone'::text AS related_type, z.parent_id AS related_id, + p.organisation_id AS related_organisation_id, p.id IS NOT NULL AS present + FROM zone z LEFT JOIN zone p ON p.id = z.parent_id + WHERE COALESCE(z.parent_id, '') <> '' + UNION ALL + SELECT 'authority', a.id, a.organisation_id, 'zone', a.config->>'org_zone', z.organisation_id, z.id IS NOT NULL + FROM authority a LEFT JOIN zone z ON z.id = a.config->>'org_zone' + WHERE COALESCE(a.config->>'org_zone', '') <> '' + UNION ALL + SELECT 'sys', s.id, s.organisation_id, 'zone', reference.id, z.organisation_id, z.id IS NOT NULL + FROM sys s CROSS JOIN LATERAL unnest(s.zones) AS reference(id) + LEFT JOIN zone z ON z.id = reference.id + UNION ALL + SELECT 'sys', s.id, s.organisation_id, 'mod', reference.id, m.organisation_id, m.id IS NOT NULL + FROM sys s CROSS JOIN LATERAL unnest(s.modules) AS reference(id) + LEFT JOIN mod m ON m.id = reference.id + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'sys', m.control_system_id, s.organisation_id, s.id IS NOT NULL + FROM mod m LEFT JOIN sys s ON s.id = m.control_system_id + WHERE m.control_system_id IS NOT NULL + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'sys', s.id, s.organisation_id, true + FROM mod m INNER JOIN sys s ON m.id = ANY(s.modules) + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'edge', m.edge_id, e.organisation_id, e.id IS NOT NULL + FROM mod m LEFT JOIN edge e ON e.id = m.edge_id + WHERE m.edge_id IS NOT NULL + UNION ALL + SELECT 'trigger', t.id, t.organisation_id, 'sys', t.control_system_id, s.organisation_id, s.id IS NOT NULL + FROM "trigger" t LEFT JOIN sys s ON s.id = t.control_system_id + WHERE t.control_system_id IS NOT NULL + UNION ALL + SELECT 'edge', e.id, e.organisation_id, 'user', e.user_id, a.organisation_id, + u.id IS NOT NULL AND a.id IS NOT NULL + FROM edge e LEFT JOIN "user" u ON u.id = e.user_id + LEFT JOIN authority a ON a.id = u.authority_id +) +SELECT resource_type, resource_id, organisation_id, 'unknown_owner'::text AS reason, + NULL::text AS related_type, NULL::text AS related_id, + NULL::uuid AS related_organisation_id +FROM resources WHERE organisation_id IS NULL +UNION +SELECT resource_type, resource_id, organisation_id, + CASE WHEN NOT present THEN 'missing_reference' + WHEN organisation_id IS NULL OR related_organisation_id IS NULL THEN 'unknown_reference' + ELSE 'ownership_mismatch' END AS reason, + related_type, related_id, related_organisation_id +FROM links +WHERE NOT present OR organisation_id IS NULL OR related_organisation_id IS NULL + OR organisation_id <> related_organisation_id +UNION +SELECT l.resource_type, l.resource_id, l.organisation_id, 'shared_reference' AS reason, + l.related_type, l.related_id, l.related_organisation_id +FROM links l +WHERE l.resource_type = 'mod' AND l.organisation_id IS NULL + AND l.related_type = 'sys' AND l.resource_id IN ( + SELECT resource_id FROM links WHERE resource_type = 'mod' AND related_type = 'sys' + GROUP BY resource_id HAVING COUNT(DISTINCT related_organisation_id) > 1 + ); + +-- +micrate Down +DROP VIEW IF EXISTS tenancy_ownership_conflicts; +-- Inferred ownership is retained: rollback must not erase reviewed assignments. From 35351e75a061d9c214fa0b1fbd3b27fcaabbd940 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:50:36 +1100 Subject: [PATCH 14/23] test: retain durable tenancy reconciliation records --- spec/tenancy_reconciliation_ledger_spec.cr | 71 ++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 spec/tenancy_reconciliation_ledger_spec.cr diff --git a/spec/tenancy_reconciliation_ledger_spec.cr b/spec/tenancy_reconciliation_ledger_spec.cr new file mode 100644 index 00000000..e3b32bb4 --- /dev/null +++ b/spec/tenancy_reconciliation_ledger_spec.cr @@ -0,0 +1,71 @@ +require "./helper" + +module PlaceOS::Model + def self.require_reconciliation_ledger + PgORM::Database.connection do |db| + db.query_one("SELECT to_regclass('tenancy_reconciliations') IS NOT NULL", &.read(Bool)).should be_true + end + end + + def self.insert_reconciliation(actor : String, authority : String, key : String) : UUID + PgORM::Database.connection do |db| + db.query_one(<<-SQL, actor, authority, key, &.read(UUID)) + INSERT INTO tenancy_reconciliations (actor_id, authority_id, idempotency_key, digest, plan, result) + VALUES ($1, $2, $3, repeat('a', 64), '{"operation":"claim"}', '{"status":"applied"}') + RETURNING id + SQL + end + end + + describe "durable tenancy reconciliation ledger" do + around_each do |example| + PgORM::Database.transaction do |transaction| + example.run + ensure + transaction.rollback unless transaction.closed? + end + end + + it "stores UUIDv7, the verified digest and plan/result independently of history" do + require_reconciliation_ledger + id = insert_reconciliation("deleted-actor", "deleted-authority", "key-#{RANDOM.hex(5)}") + id.to_s[14].should eq '7' + PgORM::Database.connection do |db| + db.query_one("SELECT plan->>'operation' FROM tenancy_reconciliations WHERE id = $1", id, &.read(String)).should eq "claim" + db.query_one("SELECT result->>'status' FROM tenancy_reconciliations WHERE id = $1", id, &.read(String)).should eq "applied" + db.query_one("SELECT length(digest) FROM tenancy_reconciliations WHERE id = $1", id, &.read(Int32)).should eq 64 + db.query_one("SELECT created_at IS NOT NULL FROM tenancy_reconciliations WHERE id = $1", id, &.read(Bool)).should be_true + end + end + + it "rejects a repeated idempotency key for the same actor" do + require_reconciliation_ledger + key = "key-#{RANDOM.hex(5)}" + insert_reconciliation("actor", "authority", key) + expect_raises(PQ::PQError, /duplicate key/) do + insert_reconciliation("actor", "authority", key) + end + end + + it "allows different actors to use the same idempotency key" do + require_reconciliation_ledger + key = "key-#{RANDOM.hex(5)}" + first = insert_reconciliation("first-actor", "authority", key) + second = insert_reconciliation("second-actor", "authority", key) + first.should_not eq second + end + + it "retains actor and authority identifiers after their source records are deleted" do + require_reconciliation_ledger + authority = Generator.authority("audit-#{RANDOM.hex(5)}.test").save! + actor = Generator.user(authority: authority).save! + id = insert_reconciliation(actor.id.as(String), authority.id.as(String), "key-#{RANDOM.hex(5)}") + PgORM::Database.connection do |db| + db.exec("DELETE FROM \"user\" WHERE id = $1", actor.id) + db.exec("DELETE FROM authority WHERE id = $1", authority.id) + db.query_one("SELECT actor_id FROM tenancy_reconciliations WHERE id = $1", id, &.read(String)).should eq actor.id + db.query_one("SELECT authority_id FROM tenancy_reconciliations WHERE id = $1", id, &.read(String)).should eq authority.id + end + end + end +end From cd0ffdc844f5469c397800b7d29a1b87b1c30cfa Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 09:58:21 +1100 Subject: [PATCH 15/23] test: cover legacy name and domain migration safety --- spec/authority_domain_migration_spec.cr | 100 +++++++++++++++++++++ spec/organisation_backfill_spec.cr | 41 ++------- spec/organisation_scoped_name_spec.cr | 52 +++++++++++ spec/support/tenancy_migrations.cr | 26 ++++++ spec/tenancy_reconciliation_ledger_spec.cr | 18 ++-- spec/zone_spec.cr | 8 ++ 6 files changed, 204 insertions(+), 41 deletions(-) create mode 100644 spec/authority_domain_migration_spec.cr create mode 100644 spec/organisation_scoped_name_spec.cr create mode 100644 spec/support/tenancy_migrations.cr diff --git a/spec/authority_domain_migration_spec.cr b/spec/authority_domain_migration_spec.cr new file mode 100644 index 00000000..7dee04b3 --- /dev/null +++ b/spec/authority_domain_migration_spec.cr @@ -0,0 +1,100 @@ +require "./support/tenancy_migrations" + +module PlaceOS::Model + def self.legacy_duplicate_authorities : {Authority, Authority} + PgORM::Database.connection(&.exec("DROP INDEX IF EXISTS authority_domain_unique")) + first = Generator.authority("legacy-#{RANDOM.hex(5)}.test").save! + duplicate_id = "auth-legacy-duplicate-#{RANDOM.hex(6)}" + PgORM::Database.connection do |db| + db.exec(<<-SQL, args: [first.id, duplicate_id]) + INSERT INTO authority + SELECT (jsonb_populate_record(NULL::authority, + to_jsonb(a) || jsonb_build_object('id', $2::text, 'created_at', a.created_at + interval '1 second'))).* + FROM authority a WHERE a.id = $1 + SQL + end + {first, Authority.find!(duplicate_id)} + end + + describe "authority domain upgrade safety" do + around_each do |example| + PgORM::Database.transaction do |transaction| + example.run + ensure + transaction.rollback unless transaction.closed? + end + end + + it "preserves duplicate legacy domains instead of renaming them or blocking migration" do + first, second = legacy_duplicate_authorities + + apply_organisation_migration("20261105100500000_add_partners_and_organisations.sql") + + Authority.find!(first.id.as(String)).domain.should eq first.domain + Authority.find!(second.id.as(String)).domain.should eq first.domain + PgORM::Database.connection do |db| + db.query_one("SELECT to_regclass('authority_domain_unique') IS NULL", &.read(Bool)).should be_true + end + end + + it "adds the unique domain index when the existing domains are unambiguous" do + PgORM::Database.connection(&.exec("DROP INDEX IF EXISTS authority_domain_unique")) + + apply_organisation_migration("20261105100500000_add_partners_and_organisations.sql") + + PgORM::Database.connection do |db| + db.query_one("SELECT to_regclass('authority_domain_unique') IS NOT NULL", &.read(Bool)).should be_true + end + end + + it "reports both duplicate authorities for explicit operator reconciliation" do + first, second = legacy_duplicate_authorities + + PgORM::Database.connection do |db| + count = db.query_one(<<-SQL, args: [first.id, second.id], &.read(Int64)) + SELECT COUNT(*) FROM tenancy_ownership_conflicts + WHERE resource_type = 'authority' AND reason = 'duplicate_domain' AND resource_id IN ($1, $2) + SQL + count.should eq 2 + end + end + + it "does not infer organisation ownership for duplicate domains" do + first, second = legacy_duplicate_authorities + + apply_organisation_migration + + Authority.find!(first.id.as(String)).organisation_id.should be_nil + Authority.find!(second.id.as(String)).organisation_id.should be_nil + end + + it "reports domains quarantined by an already applied older migration" do + authority = Generator.authority("legacy-#{RANDOM.hex(5)}.test").save! + authority.domain = "#{authority.domain}.duplicate.#{authority.id}" + authority.save! + + PgORM::Database.connection do |db| + count = db.query_one(<<-SQL, args: [authority.id], &.read(Int64)) + SELECT COUNT(*) FROM tenancy_ownership_conflicts + WHERE resource_type = 'authority' AND resource_id = $1 AND reason = 'quarantined_domain' + SQL + count.should eq 1 + end + Authority.find!(authority.id.as(String)).domain.should eq authority.domain + end + + it "creates the missing domain index after explicit duplicate resolution on an applied install" do + first, second = legacy_duplicate_authorities + PgORM::Database.connection(&.exec("UPDATE authority SET domain = $1 WHERE id = $2", args: ["resolved-#{RANDOM.hex(5)}.test", second.id])) + migration = "20261117100700000_guard_authority_domains.sql" + File.exists?(File.join(__DIR__, "..", "migration", "db", "migrations", migration)).should be_true + + apply_organisation_migration(migration) + + PgORM::Database.connection do |db| + db.query_one("SELECT to_regclass('authority_domain_unique') IS NOT NULL", &.read(Bool)).should be_true + end + Authority.find!(first.id.as(String)).domain.should eq first.domain + end + end +end diff --git a/spec/organisation_backfill_spec.cr b/spec/organisation_backfill_spec.cr index 15f964b9..3e3e9884 100644 --- a/spec/organisation_backfill_spec.cr +++ b/spec/organisation_backfill_spec.cr @@ -1,29 +1,6 @@ -require "./helper" +require "./support/tenancy_migrations" module PlaceOS::Model - # Execute the shipped migration, rather than a copy of its ownership queries. - def self.apply_organisation_backfill - path = File.join(__DIR__, "..", "migration", "db", "migrations", "20261105100600000_backfill_organisation_ownership.sql") - sql = File.read(path).split("-- +micrate Down", 2).first - statement = String::Builder.new - block = false - sql.each_line do |line| - if line.includes?("-- +micrate StatementBegin") - block = true - elsif line.includes?("-- +micrate StatementEnd") - PgORM::Database.connection(&.exec(statement.to_s)) - statement = String::Builder.new - block = false - else - statement << line << '\n' - if !block && line.rstrip.ends_with?(';') - PgORM::Database.connection(&.exec(statement.to_s)) - statement = String::Builder.new - end - end - end - end - describe "organisation ownership migration" do around_each do |example| PgORM::Database.transaction do |transaction| @@ -39,7 +16,7 @@ module PlaceOS::Model unknown = Generator.zone.save! system = Generator.control_system.tap(&.zones = [owned.id.as(String), unknown.id.as(String)]).save! - apply_organisation_backfill + apply_organisation_migration ControlSystem.find!(system.id.as(String)).organisation_id.should be_nil end @@ -49,7 +26,7 @@ module PlaceOS::Model zones = Array.new(2) { Generator.zone.tap(&.organisation_id = organisation.id).save! } system = Generator.control_system.tap(&.zones = zones.map(&.id.as(String))).save! - apply_organisation_backfill + apply_organisation_migration ControlSystem.find!(system.id.as(String)).organisation_id.should eq organisation.id end @@ -59,7 +36,7 @@ module PlaceOS::Model owned = Generator.zone.tap(&.organisation_id = organisation.id).save! system = Generator.control_system.tap(&.zones = [owned.id.as(String), "zone-missing-#{RANDOM.hex(5)}"]).save! - apply_organisation_backfill + apply_organisation_migration ControlSystem.find!(system.id.as(String)).organisation_id.should be_nil end @@ -73,7 +50,7 @@ module PlaceOS::Model end.save! Generator.control_system.tap(&.modules = [mod.id.as(String)]).save! - apply_organisation_backfill + apply_organisation_migration Module.find!(mod.id.as(String)).organisation_id.should be_nil end @@ -88,7 +65,7 @@ module PlaceOS::Model end.save! end - apply_organisation_backfill + apply_organisation_migration Module.find!(mod.id.as(String)).organisation_id.should eq organisation.id end @@ -99,7 +76,7 @@ module PlaceOS::Model mod = Generator.module(driver: Generator.driver(role: Driver::Role::Logic), control_system: owned).save! Generator.control_system.tap(&.modules = [mod.id.as(String)]).save! - apply_organisation_backfill + apply_organisation_migration Module.find!(mod.id.as(String)).organisation_id.should be_nil end @@ -118,7 +95,7 @@ module PlaceOS::Model authority.config["org_zone"] = JSON::Any.new(root.id.as(String)) end.save! - apply_organisation_backfill + apply_organisation_migration Zone.find!(unknown.id.as(String)).organisation_id.should be_nil Zone.find!(root.id.as(String)).organisation_id.should be_nil @@ -132,7 +109,7 @@ module PlaceOS::Model row.zones = [unknown.id.as(String)] end.save! - apply_organisation_backfill + apply_organisation_migration ControlSystem.find!(system.id.as(String)).organisation_id.should eq organisation.id end diff --git a/spec/organisation_scoped_name_spec.cr b/spec/organisation_scoped_name_spec.cr new file mode 100644 index 00000000..e0e14e1b --- /dev/null +++ b/spec/organisation_scoped_name_spec.cr @@ -0,0 +1,52 @@ +require "./helper" + +module PlaceOS::Model + describe "organisation name uniqueness rollout" do + around_each do |example| + previous = ENV["PLACE_TENANCY_ENFORCE"]? + ENV["PLACE_TENANCY_ENFORCE"] = "false" + PgORM::Database.transaction do |transaction| + example.run + ensure + transaction.rollback unless transaction.closed? + end + ensure + if previous + ENV["PLACE_TENANCY_ENFORCE"] = previous + else + ENV.delete("PLACE_TENANCY_ENFORCE") + end + end + + {% for type in [Zone, ControlSystem, Edge, Broker] %} + it "keeps {{type.id}} names globally unique while tenancy is disabled" do + first_org = Generator.organisation.save! + second_org = Generator.organisation.save! + name = "legacy-name-#{RANDOM.hex(6)}" + first = Generator.{{type.stringify.split("::").last.underscore.id}} + first.name = name + first.organisation_id = first_org.id + first.save! + duplicate = Generator.{{type.stringify.split("::").last.underscore.id}} + duplicate.name = name + duplicate.organisation_id = second_org.id + + duplicate.valid?.should be_false + duplicate.errors.map(&.field).should contain(:name) + end + + it "keeps unowned {{type.id}} names from duplicating an owned legacy name" do + organisation = Generator.organisation.save! + name = "legacy-name-#{RANDOM.hex(6)}" + first = Generator.{{type.stringify.split("::").last.underscore.id}} + first.name = name + first.organisation_id = organisation.id + first.save! + duplicate = Generator.{{type.stringify.split("::").last.underscore.id}} + duplicate.name = name + + duplicate.valid?.should be_false + end + {% end %} + end +end diff --git a/spec/support/tenancy_migrations.cr b/spec/support/tenancy_migrations.cr new file mode 100644 index 00000000..fdcd9f4a --- /dev/null +++ b/spec/support/tenancy_migrations.cr @@ -0,0 +1,26 @@ +require "../helper" + +module PlaceOS::Model + # Execute the shipped migration, rather than a copy of its ownership queries. + def self.apply_organisation_migration(filename : String = "20261105100600000_backfill_organisation_ownership.sql") + path = File.join(__DIR__, "..", "..", "migration", "db", "migrations", filename) + sql = File.read(path).split("-- +micrate Down", 2).first + statement = String::Builder.new + block = false + sql.each_line do |line| + if line.includes?("-- +micrate StatementBegin") + block = true + elsif line.includes?("-- +micrate StatementEnd") + PgORM::Database.connection(&.exec(statement.to_s)) + statement = String::Builder.new + block = false + else + statement << line << '\n' + if !block && line.rstrip.ends_with?(';') + PgORM::Database.connection(&.exec(statement.to_s)) + statement = String::Builder.new + end + end + end + end +end diff --git a/spec/tenancy_reconciliation_ledger_spec.cr b/spec/tenancy_reconciliation_ledger_spec.cr index e3b32bb4..847eae32 100644 --- a/spec/tenancy_reconciliation_ledger_spec.cr +++ b/spec/tenancy_reconciliation_ledger_spec.cr @@ -9,7 +9,7 @@ module PlaceOS::Model def self.insert_reconciliation(actor : String, authority : String, key : String) : UUID PgORM::Database.connection do |db| - db.query_one(<<-SQL, actor, authority, key, &.read(UUID)) + db.query_one(<<-SQL, args: [actor, authority, key], &.read(UUID)) INSERT INTO tenancy_reconciliations (actor_id, authority_id, idempotency_key, digest, plan, result) VALUES ($1, $2, $3, repeat('a', 64), '{"operation":"claim"}', '{"status":"applied"}') RETURNING id @@ -31,10 +31,10 @@ module PlaceOS::Model id = insert_reconciliation("deleted-actor", "deleted-authority", "key-#{RANDOM.hex(5)}") id.to_s[14].should eq '7' PgORM::Database.connection do |db| - db.query_one("SELECT plan->>'operation' FROM tenancy_reconciliations WHERE id = $1", id, &.read(String)).should eq "claim" - db.query_one("SELECT result->>'status' FROM tenancy_reconciliations WHERE id = $1", id, &.read(String)).should eq "applied" - db.query_one("SELECT length(digest) FROM tenancy_reconciliations WHERE id = $1", id, &.read(Int32)).should eq 64 - db.query_one("SELECT created_at IS NOT NULL FROM tenancy_reconciliations WHERE id = $1", id, &.read(Bool)).should be_true + db.query_one("SELECT plan->>'operation' FROM tenancy_reconciliations WHERE id = $1", args: [id], &.read(String)).should eq "claim" + db.query_one("SELECT result->>'status' FROM tenancy_reconciliations WHERE id = $1", args: [id], &.read(String)).should eq "applied" + db.query_one("SELECT length(digest) FROM tenancy_reconciliations WHERE id = $1", args: [id], &.read(Int32)).should eq 64 + db.query_one("SELECT created_at IS NOT NULL FROM tenancy_reconciliations WHERE id = $1", args: [id], &.read(Bool)).should be_true end end @@ -61,10 +61,10 @@ module PlaceOS::Model actor = Generator.user(authority: authority).save! id = insert_reconciliation(actor.id.as(String), authority.id.as(String), "key-#{RANDOM.hex(5)}") PgORM::Database.connection do |db| - db.exec("DELETE FROM \"user\" WHERE id = $1", actor.id) - db.exec("DELETE FROM authority WHERE id = $1", authority.id) - db.query_one("SELECT actor_id FROM tenancy_reconciliations WHERE id = $1", id, &.read(String)).should eq actor.id - db.query_one("SELECT authority_id FROM tenancy_reconciliations WHERE id = $1", id, &.read(String)).should eq authority.id + db.exec("DELETE FROM \"user\" WHERE id = $1", args: [actor.id]) + db.exec("DELETE FROM authority WHERE id = $1", args: [authority.id]) + db.query_one("SELECT actor_id FROM tenancy_reconciliations WHERE id = $1", args: [id], &.read(String)).should eq actor.id + db.query_one("SELECT authority_id FROM tenancy_reconciliations WHERE id = $1", args: [id], &.read(String)).should eq authority.id end end end diff --git a/spec/zone_spec.cr b/spec/zone_spec.cr index 4f472700..6e38d54e 100644 --- a/spec/zone_spec.cr +++ b/spec/zone_spec.cr @@ -35,6 +35,8 @@ module PlaceOS::Model end it "scopes name uniqueness to the organisation" do + previous = ENV["PLACE_TENANCY_ENFORCE"]? + ENV["PLACE_TENANCY_ENFORCE"] = "true" org_a = Generator.organisation.save! org_b = Generator.organisation.save! name = "Boardroom #{RANDOM.hex(3)}" @@ -52,6 +54,12 @@ module PlaceOS::Model first.destroy unowned.destroy + ensure + if previous + ENV["PLACE_TENANCY_ENFORCE"] = previous + else + ENV.delete("PLACE_TENANCY_ENFORCE") + end end it "has unique tags" do From 833d1de1f8a933d0ed43164a95802ac98b58c484 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:10:09 +1100 Subject: [PATCH 16/23] test: exclude generated columns from legacy authority fixture --- spec/authority_domain_migration_spec.cr | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/spec/authority_domain_migration_spec.cr b/spec/authority_domain_migration_spec.cr index 7dee04b3..baa4899d 100644 --- a/spec/authority_domain_migration_spec.cr +++ b/spec/authority_domain_migration_spec.cr @@ -6,12 +6,20 @@ module PlaceOS::Model first = Generator.authority("legacy-#{RANDOM.hex(5)}.test").save! duplicate_id = "auth-legacy-duplicate-#{RANDOM.hex(6)}" PgORM::Database.connection do |db| - db.exec(<<-SQL, args: [first.id, duplicate_id]) - INSERT INTO authority - SELECT (jsonb_populate_record(NULL::authority, - to_jsonb(a) || jsonb_build_object('id', $2::text, 'created_at', a.created_at + interval '1 second'))).* - FROM authority a WHERE a.id = $1 + columns = db.query_all(<<-SQL, as: String) + SELECT column_name FROM information_schema.columns + WHERE table_schema = current_schema() AND table_name = 'authority' AND is_generated = 'NEVER' + ORDER BY ordinal_position SQL + fields = columns.map { |column| %Q("#{column}") }.join(", ") + values = columns.map do |column| + case column + when "id" then "$2::text" + when "created_at" then %(a."created_at" + interval '1 second') + else %(a."#{column}") + end + end.join(", ") + db.exec("INSERT INTO authority (#{fields}) SELECT #{values} FROM authority a WHERE a.id = $1", args: [first.id, duplicate_id]) end {first, Authority.find!(duplicate_id)} end From b3be732b00f4e50a02306331e3db3cf8f7cc8f61 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:13:43 +1100 Subject: [PATCH 17/23] feat: retain durable tenancy reconciliation records --- ...7100600000_add_tenancy_reconciliations.sql | 20 +++++++++++++ spec/helper.cr | 1 + src/placeos-models/tenancy_reconciliation.cr | 29 +++++++++++++++++++ 3 files changed, 50 insertions(+) create mode 100644 migration/db/migrations/20261117100600000_add_tenancy_reconciliations.sql create mode 100644 src/placeos-models/tenancy_reconciliation.cr diff --git a/migration/db/migrations/20261117100600000_add_tenancy_reconciliations.sql b/migration/db/migrations/20261117100600000_add_tenancy_reconciliations.sql new file mode 100644 index 00000000..b0f2fe82 --- /dev/null +++ b/migration/db/migrations/20261117100600000_add_tenancy_reconciliations.sql @@ -0,0 +1,20 @@ +-- +micrate Up +-- Retained independently of History. Actor and credential identifiers deliberately +-- have no foreign keys: deleting those records must not erase this audit trail. +CREATE TABLE IF NOT EXISTS tenancy_reconciliations ( + id UUID PRIMARY KEY DEFAULT uuidv7(), + actor_id TEXT NOT NULL, + authority_id TEXT NOT NULL, + api_key_id TEXT, + idempotency_key TEXT NOT NULL, + digest TEXT NOT NULL, + plan JSONB NOT NULL DEFAULT '{}', + result JSONB NOT NULL DEFAULT '{}', + created_at TIMESTAMPTZ NOT NULL DEFAULT now() +); + +CREATE UNIQUE INDEX IF NOT EXISTS tenancy_reconciliations_actor_key_unique + ON tenancy_reconciliations (actor_id, idempotency_key); + +-- +micrate Down +DROP TABLE IF EXISTS tenancy_reconciliations; diff --git a/spec/helper.cr b/spec/helper.cr index dedc18e5..85ccbf52 100644 --- a/spec/helper.cr +++ b/spec/helper.cr @@ -33,6 +33,7 @@ Spec.after_suite do PlaceOS::Model::SignageTemplate, PlaceOS::Model::PendingMail, PlaceOS::Model::History, + PlaceOS::Model::TenancyReconciliation, PlaceOS::Model::GroupInvitation, PlaceOS::Model::GroupZone, PlaceOS::Model::GroupUser, diff --git a/src/placeos-models/tenancy_reconciliation.cr b/src/placeos-models/tenancy_reconciliation.cr new file mode 100644 index 00000000..bfa64e8a --- /dev/null +++ b/src/placeos-models/tenancy_reconciliation.cr @@ -0,0 +1,29 @@ +require "json" +require "uuid" +require "uuid/json" + +require "./base/model" + +module PlaceOS::Model + # Durable reconciliation results and idempotency receipts. These records are + # independent of History retention and preserve deleted actor/credential IDs. + class TenancyReconciliation < ::PgORM::Base + table :tenancy_reconciliations + + default_primary_key id : UUID, autogenerated: true + + attribute actor_id : String + attribute authority_id : String + attribute api_key_id : String? + attribute idempotency_key : String + attribute digest : String + attribute plan : JSON::Any = JSON::Any.new({} of String => JSON::Any) + attribute result : JSON::Any = JSON::Any.new({} of String => JSON::Any) + attribute created_at : Time = -> { Time.utc }, converter: PlaceOS::Model::Timestamps::EpochConverter + + validates :actor_id, presence: true + validates :authority_id, presence: true + validates :idempotency_key, presence: true + validates :digest, presence: true + end +end From 18d197aac813a00204748765af569cc99565aee8 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:13:43 +1100 Subject: [PATCH 18/23] fix: preserve global name validation until tenancy is enabled --- README.md | 12 +++++++++ .../organisation_scoped_name.cr | 27 ++++++++++++++----- 2 files changed, 32 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index b08ee72f..5ca05212 100644 --- a/README.md +++ b/README.md @@ -76,6 +76,18 @@ docker system prune --all ./test ``` +## Organisation name validation + +`PLACE_TENANCY_ENFORCE` defaults to false, preserving global name uniqueness for +zones, systems, edges and brokers. Enable it consistently across model consumers +to validate names within each organisation instead. Specs can override the shared +setting with `PlaceOS::Model::OrganisationScopedName.enforce = true` or `false`; +assign `nil` to restore the environment default. + +After allowing duplicate names across organisations, resolve those duplicates +before disabling enforcement or rolling back to binaries with global validation. +Changing validation mode never renames existing records. + ## Contributing See [`CONTRIBUTING.md`](./CONTRIBUTING.md). diff --git a/src/placeos-models/organisation_scoped_name.cr b/src/placeos-models/organisation_scoped_name.cr index 8c912d13..66eaeac2 100644 --- a/src/placeos-models/organisation_scoped_name.cr +++ b/src/placeos-models/organisation_scoped_name.cr @@ -1,18 +1,31 @@ require "./base/model" module PlaceOS::Model - # Name uniqueness for the organisation-owned estate models (zone, system, - # edge, broker): unique within an organisation, and unique among rows that - # have no organisation. Backed by the partial unique indexes on - # (organisation_id, name). + # Global legacy name validation remains the default. Enable organisation + # scoping consistently across every model consumer with tenancy enforcement. module OrganisationScopedName + @@enforce : Bool? = nil + + def self.enforce? : Bool + configured = @@enforce + return configured unless configured.nil? + !!ENV["PLACE_TENANCY_ENFORCE"]?.try(&.downcase.in?({"1", "true"})) + end + + # nil restores the environment default; specs can explicitly override it. + def self.enforce=(value : Bool?) + @@enforce = value + end + macro ensure_unique_name_within_organisation - validate :name, "should be unique within the organisation", ->(this : self) do + validate :name, "should be unique", ->(this : self) do name = this.name.strip return true if name.empty? this.name = name unless this.persisted? - existing = self.where(name: name, organisation_id: this.organisation_id).first? - !(existing && (!this.persisted? || existing.id != this.id)) + query = self.where(name: name) + query = query.where(organisation_id: this.organisation_id) if OrganisationScopedName.enforce? + query = query.where("id <> ?", this.id) if this.persisted? + query.first?.nil? end end end From 6b8db9f8c177a11604b85842a2cf434238d72ccd Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:24:49 +1100 Subject: [PATCH 19/23] test: isolate expected reconciliation uniqueness failures --- spec/tenancy_reconciliation_ledger_spec.cr | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/spec/tenancy_reconciliation_ledger_spec.cr b/spec/tenancy_reconciliation_ledger_spec.cr index 847eae32..1678c071 100644 --- a/spec/tenancy_reconciliation_ledger_spec.cr +++ b/spec/tenancy_reconciliation_ledger_spec.cr @@ -43,7 +43,9 @@ module PlaceOS::Model key = "key-#{RANDOM.hex(5)}" insert_reconciliation("actor", "authority", key) expect_raises(PQ::PQError, /duplicate key/) do - insert_reconciliation("actor", "authority", key) + PgORM::Database.transaction do + insert_reconciliation("actor", "authority", key) + end end end From 83eaa0f995e881d77c6f01debc5c969bbabafd52 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:24:49 +1100 Subject: [PATCH 20/23] fix: preserve ambiguous legacy authority domains --- README.md | 15 +++ ...0500000_add_partners_and_organisations.sql | 38 +++----- ...600000_backfill_organisation_ownership.sql | 9 +- ...61117100700000_guard_authority_domains.sql | 97 +++++++++++++++++++ 4 files changed, 134 insertions(+), 25 deletions(-) create mode 100644 migration/db/migrations/20261117100700000_guard_authority_domains.sql diff --git a/README.md b/README.md index 5ca05212..20dabd6c 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,21 @@ After allowing duplicate names across organisations, resolve those duplicates before disabling enforcement or rolling back to binaries with global validation. Changing validation mode never renames existing records. +### Upgrading existing ownership + +The additive ownership migrations retry only unassigned rows. Assigned ownership +is retained and suspicious references are exposed through +`tenancy_ownership_conflicts` for explicit reconciliation. Unowned brokers and +unscoped trigger definitions remain intentional platform resources. + +Legacy duplicate authority domains are preserved. Their unique index is deferred +until duplicates are resolved; the report identifies `duplicate_domain` rows and +domains renamed by an older migration as `quarantined_domain`. Resolve these +before enabling tenancy enforcement. The guarded index SQL in +[`20261117100700000_guard_authority_domains.sql`](migration/db/migrations/20261117100700000_guard_authority_domains.sql) +can be reapplied after explicit resolution. Migrations never merge domains or +organisations automatically. + ## Contributing See [`CONTRIBUTING.md`](./CONTRIBUTING.md). diff --git a/migration/db/migrations/20261105100500000_add_partners_and_organisations.sql b/migration/db/migrations/20261105100500000_add_partners_and_organisations.sql index 20b2149b..e6122775 100644 --- a/migration/db/migrations/20261105100500000_add_partners_and_organisations.sql +++ b/migration/db/migrations/20261105100500000_add_partners_and_organisations.sql @@ -4,8 +4,8 @@ -- MERGE-TIME CHECK: micrate refuses out-of-order version ids (see models#323). -- If any later-dated migration lands on master before this merges, renumber -- this file AND 20261105100600000 above it (preserving schema-before-backfill --- order). Safe: neither has been applied anywhere and the backfill is --- idempotent. +-- order). Existing installations use additive migrations for corrections; +-- applied versions are not rerun. -- --------------------------------------------------------------------------- -- PPT-526: the Partner → Organisation → Authority(domain) hierarchy. @@ -85,27 +85,19 @@ ALTER TABLE ONLY "authority" CREATE INDEX IF NOT EXISTS authority_organisation_id_index ON "authority" USING BTREE (organisation_id); --- The domain column has only ever had model-level uniqueness (a plain BTREE --- index) — a concurrent-signup race can create duplicate authorities. Make it --- a hard guarantee; self-service signup depends on it. --- --- Quarantine first: exact-duplicate domains left behind by that race would --- make the unique index unbuildable and (because micrate autocommits each --- statement) leave this migration half-applied. Keep the oldest row per --- domain and rename the rest so they stop answering for the domain — --- find_by_domain picks an arbitrary row across duplicates today, so this --- cannot break a reliably-working login. Idempotent: renamed rows no longer --- collide. Renamed rows are for an operator to merge or delete. -UPDATE "authority" a -SET domain = a.domain || '.duplicate.' || a.id -WHERE EXISTS ( - SELECT 1 FROM "authority" b - WHERE b.domain = a.domain - AND (b.created_at, b.id) < (a.created_at, a.id) -); - -CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique - ON "authority" USING BTREE (domain); +-- Preserve existing domains. Ambiguous legacy rows remain available in flag-off +-- mode and are reported for explicit reconciliation before enforcement is enabled. +-- +micrate StatementBegin +DO $$ +BEGIN + LOCK TABLE authority IN SHARE MODE; + IF EXISTS (SELECT domain FROM authority GROUP BY domain HAVING COUNT(*) > 1) THEN + RAISE NOTICE 'duplicate authority domains require explicit reconciliation; unique index deferred'; + ELSE + CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique ON authority USING BTREE (domain); + END IF; +END $$; +-- +micrate StatementEnd -- --------------------------------------------------------------------------- -- Organisation ownership columns on the (previously cluster-global) control plane. diff --git a/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql b/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql index 71df4235..1b509898 100644 --- a/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql +++ b/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql @@ -38,14 +38,19 @@ SELECT 'PlaceOS', 'Platform operator (management partner)', true, now(), now() WHERE NOT EXISTS (SELECT 1 FROM "partners" WHERE management = true) ON CONFLICT DO NOTHING; --- 2. One organisation-owned Organisation per orphan Authority +-- 2. One organisation-owned Organisation per unambiguous orphan Authority. +-- Duplicate domains remain quarantined for explicit operator reconciliation. -- +micrate StatementBegin DO $$ DECLARE auth RECORD; new_org UUID; BEGIN - FOR auth IN SELECT id, name, domain FROM "authority" WHERE organisation_id IS NULL LOOP + FOR auth IN + SELECT a.id, a.name, a.domain FROM "authority" a + WHERE a.organisation_id IS NULL + AND NOT EXISTS (SELECT 1 FROM "authority" duplicate WHERE duplicate.domain = a.domain AND duplicate.id <> a.id) + LOOP new_org := NULL; INSERT INTO "organisations" (name, description, partner_id, payer, created_at, updated_at) VALUES ( diff --git a/migration/db/migrations/20261117100700000_guard_authority_domains.sql b/migration/db/migrations/20261117100700000_guard_authority_domains.sql new file mode 100644 index 00000000..940cac45 --- /dev/null +++ b/migration/db/migrations/20261117100700000_guard_authority_domains.sql @@ -0,0 +1,97 @@ +-- +micrate Up +-- Preserve existing domains. Ambiguous legacy rows remain available in flag-off +-- mode and are reported for explicit reconciliation before enforcement is enabled. +-- +micrate StatementBegin +DO $$ +BEGIN + LOCK TABLE authority IN SHARE MODE; + IF EXISTS (SELECT domain FROM authority GROUP BY domain HAVING COUNT(*) > 1) THEN + RAISE NOTICE 'duplicate authority domains require explicit reconciliation; unique index deferred'; + ELSE + CREATE UNIQUE INDEX IF NOT EXISTS authority_domain_unique ON authority USING BTREE (domain); + END IF; +END $$; +-- +micrate StatementEnd + +CREATE OR REPLACE VIEW tenancy_ownership_conflicts AS +WITH resources AS ( + SELECT 'authority'::text AS resource_type, id AS resource_id, organisation_id FROM authority + UNION ALL SELECT 'zone', id, organisation_id FROM zone + UNION ALL SELECT 'sys', id, organisation_id FROM sys + UNION ALL SELECT 'mod', id, organisation_id FROM mod + UNION ALL SELECT 'edge', id, organisation_id FROM edge + UNION ALL SELECT 'broker', id, organisation_id FROM broker WHERE organisation_id IS NOT NULL + UNION ALL SELECT 'trigger', id, organisation_id FROM "trigger" + WHERE organisation_id IS NOT NULL OR control_system_id IS NOT NULL +), links AS ( + SELECT 'zone'::text AS resource_type, z.id AS resource_id, z.organisation_id, + 'zone'::text AS related_type, z.parent_id AS related_id, + p.organisation_id AS related_organisation_id, p.id IS NOT NULL AS present + FROM zone z LEFT JOIN zone p ON p.id = z.parent_id + WHERE COALESCE(z.parent_id, '') <> '' + UNION ALL + SELECT 'authority', a.id, a.organisation_id, 'zone', a.config->>'org_zone', z.organisation_id, z.id IS NOT NULL + FROM authority a LEFT JOIN zone z ON z.id = a.config->>'org_zone' + WHERE COALESCE(a.config->>'org_zone', '') <> '' + UNION ALL + SELECT 'sys', s.id, s.organisation_id, 'zone', reference.id, z.organisation_id, z.id IS NOT NULL + FROM sys s CROSS JOIN LATERAL unnest(s.zones) AS reference(id) + LEFT JOIN zone z ON z.id = reference.id + UNION ALL + SELECT 'sys', s.id, s.organisation_id, 'mod', reference.id, m.organisation_id, m.id IS NOT NULL + FROM sys s CROSS JOIN LATERAL unnest(s.modules) AS reference(id) + LEFT JOIN mod m ON m.id = reference.id + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'sys', m.control_system_id, s.organisation_id, s.id IS NOT NULL + FROM mod m LEFT JOIN sys s ON s.id = m.control_system_id + WHERE m.control_system_id IS NOT NULL + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'sys', s.id, s.organisation_id, true + FROM mod m INNER JOIN sys s ON m.id = ANY(s.modules) + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'edge', m.edge_id, e.organisation_id, e.id IS NOT NULL + FROM mod m LEFT JOIN edge e ON e.id = m.edge_id + WHERE m.edge_id IS NOT NULL + UNION ALL + SELECT 'trigger', t.id, t.organisation_id, 'sys', t.control_system_id, s.organisation_id, s.id IS NOT NULL + FROM "trigger" t LEFT JOIN sys s ON s.id = t.control_system_id + WHERE t.control_system_id IS NOT NULL + UNION ALL + SELECT 'edge', e.id, e.organisation_id, 'user', e.user_id, a.organisation_id, + u.id IS NOT NULL AND a.id IS NOT NULL + FROM edge e LEFT JOIN "user" u ON u.id = e.user_id + LEFT JOIN authority a ON a.id = u.authority_id +) +SELECT resource_type, resource_id, organisation_id, 'unknown_owner'::text AS reason, + NULL::text AS related_type, NULL::text AS related_id, + NULL::uuid AS related_organisation_id +FROM resources WHERE organisation_id IS NULL +UNION +SELECT resource_type, resource_id, organisation_id, + CASE WHEN NOT present THEN 'missing_reference' + WHEN organisation_id IS NULL OR related_organisation_id IS NULL THEN 'unknown_reference' + ELSE 'ownership_mismatch' END AS reason, + related_type, related_id, related_organisation_id +FROM links +WHERE NOT present OR organisation_id IS NULL OR related_organisation_id IS NULL + OR organisation_id <> related_organisation_id +UNION +SELECT l.resource_type, l.resource_id, l.organisation_id, 'shared_reference' AS reason, + l.related_type, l.related_id, l.related_organisation_id +FROM links l +WHERE l.resource_type = 'mod' AND l.organisation_id IS NULL + AND l.related_type = 'sys' AND l.resource_id IN ( + SELECT resource_id FROM links WHERE resource_type = 'mod' AND related_type = 'sys' + GROUP BY resource_id HAVING COUNT(DISTINCT related_organisation_id) > 1 + ) +UNION +SELECT 'authority', a.id, a.organisation_id, 'duplicate_domain', NULL::text, NULL::text, NULL::uuid +FROM authority a +WHERE EXISTS (SELECT 1 FROM authority duplicate WHERE duplicate.domain = a.domain AND duplicate.id <> a.id) +UNION +SELECT 'authority', a.id, a.organisation_id, 'quarantined_domain', NULL::text, NULL::text, NULL::uuid +FROM authority a +WHERE RIGHT(a.domain, LENGTH('.duplicate.' || a.id)) = '.duplicate.' || a.id; + +-- +micrate Down +-- Keep the non-destructive domain guarantee and expanded diagnostic report. From 363cf899b07031c7caba07890345d153487d2fb7 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:33:04 +1100 Subject: [PATCH 21/23] fix: recognise normalized quarantined authority domains --- .../db/migrations/20261117100700000_guard_authority_domains.sql | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/migration/db/migrations/20261117100700000_guard_authority_domains.sql b/migration/db/migrations/20261117100700000_guard_authority_domains.sql index 940cac45..4622d19a 100644 --- a/migration/db/migrations/20261117100700000_guard_authority_domains.sql +++ b/migration/db/migrations/20261117100700000_guard_authority_domains.sql @@ -91,7 +91,7 @@ WHERE EXISTS (SELECT 1 FROM authority duplicate WHERE duplicate.domain = a.domai UNION SELECT 'authority', a.id, a.organisation_id, 'quarantined_domain', NULL::text, NULL::text, NULL::uuid FROM authority a -WHERE RIGHT(a.domain, LENGTH('.duplicate.' || a.id)) = '.duplicate.' || a.id; +WHERE RIGHT(LOWER(a.domain), LENGTH('.duplicate.' || a.id)) = '.duplicate.' || LOWER(a.id); -- +micrate Down -- Keep the non-destructive domain guarantee and expanded diagnostic report. From 3871fda788b4df0a8568ef1a2766d3c25dc3f339 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:36:25 +1100 Subject: [PATCH 22/23] test: quarantine module ownership across edge boundaries --- spec/module_edge_backfill_spec.cr | 99 +++++++++++++++++++++++++++++++ 1 file changed, 99 insertions(+) create mode 100644 spec/module_edge_backfill_spec.cr diff --git a/spec/module_edge_backfill_spec.cr b/spec/module_edge_backfill_spec.cr new file mode 100644 index 00000000..28968bc6 --- /dev/null +++ b/spec/module_edge_backfill_spec.cr @@ -0,0 +1,99 @@ +require "./support/tenancy_migrations" + +module PlaceOS::Model + def self.module_edge_fixture(edge_owner : Organisation?) + organisation = Generator.organisation.save! + authority = Generator.authority("edge-owner-#{RANDOM.hex(5)}.test") + authority.organisation_id = edge_owner.try(&.id) || organisation.id + authority.save! + user = Generator.user(authority: authority).save! + edge = Generator.edge(user: user) + edge.organisation_id = edge_owner.try(&.id) + edge.save! + mod = Generator.module(driver: Generator.driver(role: Driver::Role::Device)) + mod.edge_id = edge.id + mod.save! + system = Generator.control_system.tap do |row| + row.organisation_id = organisation.id + row.modules = [mod.id.as(String)] + end.save! + {organisation, edge, mod, system} + end + + describe "module edge ownership backfill" do + around_each do |example| + PgORM::Database.transaction do |transaction| + example.run + ensure + transaction.rollback unless transaction.closed? + end + end + + it "quarantines an unowned module bound to another organisation's edge" do + other = Generator.organisation.save! + _, _, mod, _ = module_edge_fixture(other) + + apply_organisation_migration + + Module.find!(mod.id.as(String)).organisation_id.should be_nil + end + + it "quarantines an unowned module whose configured edge does not exist" do + _, _, mod, _ = module_edge_fixture(nil) + PgORM::Database.connection(&.exec("UPDATE mod SET edge_id = $1 WHERE id = $2", args: ["edge-missing-#{RANDOM.hex(5)}", mod.id])) + + apply_organisation_migration + + Module.find!(mod.id.as(String)).organisation_id.should be_nil + end + + it "quarantines an unowned module when its edge owner cannot be inferred" do + _, edge, mod, _ = module_edge_fixture(nil) + PgORM::Database.connection(&.exec("UPDATE edge SET user_id = $1 WHERE id = $2", args: ["user-missing-#{RANDOM.hex(5)}", edge.id])) + + apply_organisation_migration + + Edge.find!(edge.id.as(String)).organisation_id.should be_nil + Module.find!(mod.id.as(String)).organisation_id.should be_nil + end + + it "assigns a module when its system and actual edge have the same known owner" do + organisation, edge, mod, _ = module_edge_fixture(nil) + edge.organisation_id = organisation.id + edge.save! + + apply_organisation_migration + + Module.find!(mod.id.as(String)).organisation_id.should eq organisation.id + end + + it "preserves assigned ownership and reports a conflicting edge for reconciliation" do + other = Generator.organisation.save! + organisation, _, mod, _ = module_edge_fixture(other) + mod.organisation_id = organisation.id + mod.save! + + apply_organisation_migration + + Module.find!(mod.id.as(String)).organisation_id.should eq organisation.id + PgORM::Database.connection do |db| + count = db.query_one(<<-SQL, args: [mod.id], &.read(Int64)) + SELECT COUNT(*) FROM tenancy_ownership_conflicts + WHERE resource_type = 'mod' AND resource_id = $1 AND related_type = 'edge' AND reason = 'ownership_mismatch' + SQL + count.should eq 1 + end + end + + it "applies the conservative edge guard to NULL module ownership on an already migrated install" do + other = Generator.organisation.save! + _, _, mod, _ = module_edge_fixture(other) + migration = "20261117100800000_guard_module_edge_ownership.sql" + File.exists?(File.join(__DIR__, "..", "migration", "db", "migrations", migration)).should be_true + + apply_organisation_migration(migration) + + Module.find!(mod.id.as(String)).organisation_id.should be_nil + end + end +end From 716ca764f68e09a72b9028aa3380fdb06a50a635 Mon Sep 17 00:00:00 2001 From: Stephen von Takach Date: Tue, 17 Nov 2026 10:44:28 +1100 Subject: [PATCH 23/23] fix: quarantine module inference across edge ownership --- ...600000_backfill_organisation_ownership.sql | 9 +- ...00000_reconcile_organisation_ownership.sql | 9 +- ...7100800000_guard_module_edge_ownership.sql | 119 ++++++++++++++++++ 3 files changed, 135 insertions(+), 2 deletions(-) create mode 100644 migration/db/migrations/20261117100800000_guard_module_edge_ownership.sql diff --git a/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql b/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql index 1b509898..18205867 100644 --- a/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql +++ b/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql @@ -192,7 +192,14 @@ module_owners AS ( UPDATE "mod" m SET organisation_id = owners.organisation_id FROM module_owners owners -WHERE m.id = owners.mod_id AND m.organisation_id IS NULL; +WHERE m.id = owners.mod_id AND m.organisation_id IS NULL + AND ( + COALESCE(m.edge_id, '') = '' + OR EXISTS ( + SELECT 1 FROM "edge" e + WHERE e.id = m.edge_id AND e.organisation_id = owners.organisation_id + ) + ); -- +micrate StatementEnd -- 6. System-scoped trigger definitions diff --git a/migration/db/migrations/20261117100500000_reconcile_organisation_ownership.sql b/migration/db/migrations/20261117100500000_reconcile_organisation_ownership.sql index 50b2e8e9..f7dda258 100644 --- a/migration/db/migrations/20261117100500000_reconcile_organisation_ownership.sql +++ b/migration/db/migrations/20261117100500000_reconcile_organisation_ownership.sql @@ -117,7 +117,14 @@ module_owners AS ( UPDATE "mod" m SET organisation_id = owners.organisation_id FROM module_owners owners -WHERE m.id = owners.mod_id AND m.organisation_id IS NULL; +WHERE m.id = owners.mod_id AND m.organisation_id IS NULL + AND ( + COALESCE(m.edge_id, '') = '' + OR EXISTS ( + SELECT 1 FROM "edge" e + WHERE e.id = m.edge_id AND e.organisation_id = owners.organisation_id + ) + ); -- +micrate StatementEnd -- 6. System-scoped trigger definitions diff --git a/migration/db/migrations/20261117100800000_guard_module_edge_ownership.sql b/migration/db/migrations/20261117100800000_guard_module_edge_ownership.sql new file mode 100644 index 00000000..8d1b28f2 --- /dev/null +++ b/migration/db/migrations/20261117100800000_guard_module_edge_ownership.sql @@ -0,0 +1,119 @@ +-- +micrate Up +-- Correct only unassigned module ownership. Actual edge gateways are tenant-owned; +-- missing, unknown or conflicting edge ownership vetoes inference. Assigned owners +-- remain unchanged and appear in the reconciliation report for explicit review. +-- 5. All module ownership sources must agree, including references from systems +-- other than a logic module's parent. Unknown/missing owners veto inference. +-- +micrate StatementBegin +WITH module_systems AS ( + SELECT id AS mod_id, control_system_id AS sys_id + FROM "mod" WHERE control_system_id IS NOT NULL + UNION + SELECT m.id AS mod_id, s.id AS sys_id + FROM "mod" m INNER JOIN "sys" s ON m.id = ANY(s.modules) +), +module_owners AS ( + SELECT links.mod_id, MIN(s.organisation_id::text)::uuid AS organisation_id + FROM module_systems links + LEFT JOIN "sys" s ON s.id = links.sys_id + GROUP BY links.mod_id + HAVING COUNT(DISTINCT s.organisation_id) = 1 + AND bool_and(s.organisation_id IS NOT NULL) +) +UPDATE "mod" m +SET organisation_id = owners.organisation_id +FROM module_owners owners +WHERE m.id = owners.mod_id AND m.organisation_id IS NULL + AND ( + COALESCE(m.edge_id, '') = '' + OR EXISTS ( + SELECT 1 FROM "edge" e + WHERE e.id = m.edge_id AND e.organisation_id = owners.organisation_id + ) + ); +-- +micrate StatementEnd + + +CREATE OR REPLACE VIEW tenancy_ownership_conflicts AS +WITH resources AS ( + SELECT 'authority'::text AS resource_type, id AS resource_id, organisation_id FROM authority + UNION ALL SELECT 'zone', id, organisation_id FROM zone + UNION ALL SELECT 'sys', id, organisation_id FROM sys + UNION ALL SELECT 'mod', id, organisation_id FROM mod + UNION ALL SELECT 'edge', id, organisation_id FROM edge + UNION ALL SELECT 'broker', id, organisation_id FROM broker WHERE organisation_id IS NOT NULL + UNION ALL SELECT 'trigger', id, organisation_id FROM "trigger" + WHERE organisation_id IS NOT NULL OR control_system_id IS NOT NULL +), links AS ( + SELECT 'zone'::text AS resource_type, z.id AS resource_id, z.organisation_id, + 'zone'::text AS related_type, z.parent_id AS related_id, + p.organisation_id AS related_organisation_id, p.id IS NOT NULL AS present + FROM zone z LEFT JOIN zone p ON p.id = z.parent_id + WHERE COALESCE(z.parent_id, '') <> '' + UNION ALL + SELECT 'authority', a.id, a.organisation_id, 'zone', a.config->>'org_zone', z.organisation_id, z.id IS NOT NULL + FROM authority a LEFT JOIN zone z ON z.id = a.config->>'org_zone' + WHERE COALESCE(a.config->>'org_zone', '') <> '' + UNION ALL + SELECT 'sys', s.id, s.organisation_id, 'zone', reference.id, z.organisation_id, z.id IS NOT NULL + FROM sys s CROSS JOIN LATERAL unnest(s.zones) AS reference(id) + LEFT JOIN zone z ON z.id = reference.id + UNION ALL + SELECT 'sys', s.id, s.organisation_id, 'mod', reference.id, m.organisation_id, m.id IS NOT NULL + FROM sys s CROSS JOIN LATERAL unnest(s.modules) AS reference(id) + LEFT JOIN mod m ON m.id = reference.id + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'sys', m.control_system_id, s.organisation_id, s.id IS NOT NULL + FROM mod m LEFT JOIN sys s ON s.id = m.control_system_id + WHERE m.control_system_id IS NOT NULL + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'sys', s.id, s.organisation_id, true + FROM mod m INNER JOIN sys s ON m.id = ANY(s.modules) + UNION ALL + SELECT 'mod', m.id, m.organisation_id, 'edge', m.edge_id, e.organisation_id, e.id IS NOT NULL + FROM mod m LEFT JOIN edge e ON e.id = m.edge_id + WHERE m.edge_id IS NOT NULL + UNION ALL + SELECT 'trigger', t.id, t.organisation_id, 'sys', t.control_system_id, s.organisation_id, s.id IS NOT NULL + FROM "trigger" t LEFT JOIN sys s ON s.id = t.control_system_id + WHERE t.control_system_id IS NOT NULL + UNION ALL + SELECT 'edge', e.id, e.organisation_id, 'user', e.user_id, a.organisation_id, + u.id IS NOT NULL AND a.id IS NOT NULL + FROM edge e LEFT JOIN "user" u ON u.id = e.user_id + LEFT JOIN authority a ON a.id = u.authority_id +) +SELECT resource_type, resource_id, organisation_id, 'unknown_owner'::text AS reason, + NULL::text AS related_type, NULL::text AS related_id, + NULL::uuid AS related_organisation_id +FROM resources WHERE organisation_id IS NULL +UNION +SELECT resource_type, resource_id, organisation_id, + CASE WHEN NOT present THEN 'missing_reference' + WHEN organisation_id IS NULL OR related_organisation_id IS NULL THEN 'unknown_reference' + ELSE 'ownership_mismatch' END AS reason, + related_type, related_id, related_organisation_id +FROM links +WHERE NOT present OR organisation_id IS NULL OR related_organisation_id IS NULL + OR organisation_id <> related_organisation_id +UNION +SELECT l.resource_type, l.resource_id, l.organisation_id, 'shared_reference' AS reason, + l.related_type, l.related_id, l.related_organisation_id +FROM links l +WHERE l.resource_type = 'mod' AND l.organisation_id IS NULL + AND l.related_type = 'sys' AND l.resource_id IN ( + SELECT resource_id FROM links WHERE resource_type = 'mod' AND related_type = 'sys' + GROUP BY resource_id HAVING COUNT(DISTINCT related_organisation_id) > 1 + ) +UNION +SELECT 'authority', a.id, a.organisation_id, 'duplicate_domain', NULL::text, NULL::text, NULL::uuid +FROM authority a +WHERE EXISTS (SELECT 1 FROM authority duplicate WHERE duplicate.domain = a.domain AND duplicate.id <> a.id) +UNION +SELECT 'authority', a.id, a.organisation_id, 'quarantined_domain', NULL::text, NULL::text, NULL::uuid +FROM authority a +WHERE RIGHT(LOWER(a.domain), LENGTH('.duplicate.' || a.id)) = '.duplicate.' || LOWER(a.id); + + +-- +micrate Down +-- Keep reviewed ownership assignments and the non-destructive diagnostic view.