Skip to content

Plan organisation selection and domain scoping #463

Open
0 of 3 issues completed
Open

Description

@stakach

REST organisation selection and Staff API domain plan

Date: 2026-11-16; contract updated 2026-11-17 (Australia/Sydney)
Owner: stakach. Tracking: #463
Milestone: Multi-tenancy

Current implementation and P1/P2 verification: #465. API changes are implemented in the four draft PRs; client UI updates, release-pin replacement and deployment remain subsequent work. Historical audit/verification sections below describe their dated baselines.

Desired contract

Existing REST API callers belonging to one organisation keep their URL, Host, JWT/API key and payloads. Omitting organisation_id defaults to the authenticated domain's owner for every role, including partner/management staff. Partner staff discover accessible organisations and select one explicitly when accessing another organisation. Selection is per request, so browser tabs and concurrent requests cannot change each other's scope.

Use the existing organisation_id=<uuid> query parameter consistently across REST API resource routes, including detail and write requests. Do not introduce a second competing organisation selector. The login authority remains the authority that authenticated the caller. Selecting an organisation never requires changing Host or obtaining a new token.

Staff API remains domain-based, as confirmed by Steve on 2026-11-16. Its authenticated Host/domain and existing calendar Tenant resolution remain the resource context. Do not add organisation_id selection to staff resource routes or switch calendar credentials based on a REST organisation selection. A client using another staff domain must follow the existing authentication/domain contract.

For REST API, separate three concepts: authenticated identity; allowed resource scopes and operation permissions; selected resource organisation. Selection narrows permission and never grants it.

  • Any caller with no selector: use the home organisation inferred from their authenticated Authority. Additional grants must not change that default or require selection. Explicit organisation_id can select another permitted organisation. A missing home organisation fails closed under enforcement.
  • Structural partner/management staff also default to their authenticated domain owner. Their broader reach permits explicit selection of another organisation; it never expands the implicit default or makes a selector mandatory.
  • Explicit selection: verify UUID syntax and existence/allowed access. Use 400 for malformed/duplicate selectors, 404 for unknown/inaccessible organisation or resource, and existing 403 semantics for an operation lacking permission.
  • A selected organisation scopes lists, pagination totals, search, aggregates, details, writes, references and subscriptions. A sibling organisation remains out of scope even if the caller could explicitly select it in a separate request.
  • No wildcard all on ordinary resource routes. Any genuine platform overview remains an explicitly privileged, separately documented operation.
  • New ownership comes from selected context or a matching parent; payloads cannot transfer ownership. Cluster maintenance/claim routes stay explicit. Updates must revalidate changed owner/user/authority references as well as the original row (API keys and OAuth applications currently only check the original owner on update).
  • Preserve intentionally shared catalogs and public/guest behavior through explicit route classification. Unowned legacy records must be reconciled before enforcement; they must not become visible through a fallback to all records.

Baseline audit before REST implementation

Models and init

Models PR #332 provides partners, organisations, organisation ownership, partner staff organisations and expiring permission grants. Users still belong to an Authority (models/src/placeos-models/user.cr:116); an Authority belongs to an Organisation (models/src/placeos-models/authority.cr:37). There is no new user-membership junction to require for this contract. Existing login tokens can remain compatible through server-side identity lookup.

Grant.resolve retains the permission bitmask and authority -> organisation -> partner chain (models/src/placeos-models/grant.cr:86-123). The reach helpers currently flatten this into an organisation set and lose both authority precision and verb permissions. Preserve precise grants in REST selection and Staff tenant administration; Staff resource routes keep their domain boundary.

The backfill creates one organisation per authority by default and leaves contested/unresolved estate ownership NULL (models/migration/db/migrations/20261105100600000_backfill_organisation_ownership.sql:74). Multi-domain real-world organisations need deliberate reconciliation; automatic guessing would change results.

Init PR #105 already seeds the management partner and its staff organisation, adopts an untouched first-domain backfill and owns placeholders (init/src/tasks/entities.cr:48-115, init/src/tasks/initialization.cr:35-57). It supplies provisioning, not API selection.

REST API

PR #451 already has GET /api/engine/v2/organisations/current and list/show routes (rest-api/src/placeos-rest-api/controllers/organisations.cr:14-73). Current exposes home organisation/partner/reach; list/show currently require support/admin. Ordinary grant holders need a safe, permission-scoped discovery response too. Avoid exposing billing/config fields merely to populate a selector.

Several list routes accept organisation_id already (zones, systems, modules, domains, users, edges and triggers). With no selector partner lists use every reachable organisation. Helpers distinguish reach but have no request-wide active organisation (rest-api/src/placeos-rest-api/utilities/tenancy.cr:62-102,173-195). Detail/write gates and WebSockets use reach. Modules with control_system_id return before organisation narrowing (controllers/modules.cr:189-203), and users with authority_id bypass organisation narrowing (controllers/users.cr:179-184); combined selectors must be checked for consistency. Tags aggregate reach rather than selection (controllers/zones.cr:273). Ownership inference may use the caller's home organisation (utilities/tenancy.cr:224-265).

Domain-owned features remain bound to current_authority; assets/categories are examples (controllers/assets.cr:47-50,99-106). JWT domain must match the real request host (utilities/current-user.cr:137-149,178). Replacing the login authority globally or changing Host is not a valid solution.

Staff API

PR #390 scopes tenant administration to reachable Authority domains, with no organisation discovery or selection (staff-api/src/controllers/utilities/tenancy.cr:17-71; src/controllers/tenants.cr:14-38). Bookings/events/guests retain their current calendar-tenant scoping.

current_tenant validates the token domain and chooses credentials by request host plus user email domain (staff-api/src/controllers/utilities/multi_tenant.cr:33-60). An organisation may own multiple Authorities and calendar/email-domain Tenant variants. The user confirmed this existing domain/calendar model should remain; no cross-organisation calendar-selection feature is planned.

Newer master endpoints also access models directly: find_system! and systems_with_emails (src/controllers/utilities/placeos-helpers.cr:73-80); spaces falls back to broad zone/system queries when org_zone is missing (src/controllers/spaces.cr). Audit these against the current request domain and existing org_zone/tenant contract rather than adding an active organisation selector. Missing org_zone must not silently expose unrelated domains. Tenant PATCH checks the original domain but permits changing domain without rechecking (src/controllers/tenants.cr:46-64).

Rollout blockers in the current enforcement design

  1. Both resolvers grant cluster reach to admin/support users whenever their organisation's partner is the management partner, without requiring partner_staff (REST utilities/tenancy.cr:91; staff controllers/utilities/tenancy.cr:27). A PlaceOS-managed customer organisation must not gain management-staff access.
  2. Authority grants are widened to their entire organisation; a read grant combined with the caller's home-domain admin flag can authorize writes elsewhere. Retain both resource scope and operation permission.
  3. REST Flux proxy executes arbitrary queries using server credentials with no organisation filter (controllers/flux.cr:9-44). Do not claim full isolation while this remains unrestricted. Preserve existing single-org metrics through a proven scoped path; restrict raw proxy to explicit platform administration unless equivalent isolation can be demonstrated.
  4. PLACE_TENANCY_ENFORCE defaults off in both APIs. Flag-off currently also assigns ownership and can reject mixed-zone writes, so it is not a perfect no-op. Test and document rollout semantics explicitly before changing the default.

Tracking and native dependencies

Implementation sequence and acceptance criteria

  • Phase 1 — Agree the contract and write failing regression specs first. Use a fixture with organisation A, sibling B, another partner C, management staff and a management-partner customer. Include multiple Authorities per organisation. Snapshot master behavior for correctly owned single-org REST fixtures and unchanged Staff domain/calendar fixtures.
  • Phase 2 — Implement REST request context and exact permission evaluation. Keep home identity immutable; resolve selection once, narrow every resource gate/query and enforce grant scope/verb. Require partner_staff for structural management reach. Expose safe discovery for authorised callers and selection-required/current-selection metadata while retaining master response contracts. These new PR discovery routes can use minimal DTOs rather than exposing model config/billing fields.
  • Phase 3 — Apply selected context to all REST consumers: estate/domain-owned controllers, settings/metadata/history, tags/counts, bulk paths, assets/categories/signage, uploads, notifications and sockets. Classify shared catalogs and platform infrastructure explicitly. Audit raw metrics and close that bypass before enabling isolation.
  • Phase 4 — Verify Staff API’s existing domain isolation independently. Retain request Host/JWT matching, host/email-domain Tenant resolution and existing delegated/application credential behavior. Add no organisation selector, discovery alias or calendar retargeting. Check direct system/zone/asset/user references, spaces/staff, batches and background jobs against the current domain/tenant. Revalidate changed Tenant domain, keep authority/read grants exact in tenant administration, and require partner_staff for management structural reach. Fix only demonstrated violations of the existing domain contract, with regression specs first.
  • Phase 5 — OpenAPI/MCP/client integration. Document organisation_id on applicable REST routes and propagate REST MCP selection without shared mutable defaults. Staff MCP tools/cards keep their existing domain context. Refreshed backoffice/ts-client currently have no organisation selection integration; add selector UI and request propagation as a separate client follow-up after the API contract is established. Regenerate REST OpenAPI/MCP contracts after selection changes. Update Staff documentation only if domain-isolation fixes change its documented behavior.
  • Phase 6 — Verify provisioning and rollout. Fresh install and upgraded DB; idempotent seeding; contested/unowned report and manual reconciliation; flag-off/flag-on checks; local full-platform smoke via local/docker-compose.yml; sequential local suites via test agents and GitHub CI for changed repos. Merge models first using squash, then replace downstream branch pins with the released version and migration source. Re-run downstream CI before squash merging each PR.

Required test matrix

  • Unchanged single-org requests: normal user, admin, support, API key and permitted guests. Include JWTs issued before migration and existing keys with no new org claims or reissuance; preserve API keys’ stored permission behavior, including permitted privileges above the owner’s flags. Compare statuses, response fields, IDs, ordering, counts, pagination and write effects with master using the same authorised organisation dataset. Cover engine routes beyond lists; independently prove Staff requests retain their existing domain/calendar behavior.
  • Adding an organisation or authority grant to an ordinary caller does not change their default home-organisation results. Partner discovery is scoped and paginated; omitting selection defaults every role to its authenticated domain owner; selecting A/B per request works with the same token/Host and independent concurrent requests.
  • With A selected, B lists/counts/tags/search and direct IDs are excluded, including sibling B otherwise in reach. Organisation/context must be part of cache keys and captured explicitly by asynchronous jobs. Check PATCH/DELETE, nested parents, bulk operations, writes and emitted notifications. Creates belong to A; mixed-org parent/child combinations fail atomically.
  • Ordinary partner-customer and management-partner-customer admins stay in their own organisation. Only authorised partner staff span their partner; only management staff have structural platform reach.
  • Authority-only/read-only/expired/revoked grants remain exact; selection cannot elevate permission. Test live revocation and stale socket/cache/background contexts. REST OAuth scopes and API-key restrictions still intersect effective permission; Staff tenant administration retains exact granted domain/verb scope.
  • Staff requests keep the same Host, token, tenant/email-domain resolution and delegated/application credential behavior as master. A REST organisation selection must not change a staff call’s tenant or credentials. Cross-domain direct IDs, missing org_zone fallbacks and Tenant domain mutation cannot escape the authorised domain/tenant contract; preserve explicitly authorised cross-domain tenant administration. Guests/public callbacks retain their domain restrictions.
  • NULL ownership, absent organisation, malformed/foreign selectors and unmatched configuration fail closed under enforcement. Intentional global catalogs and platform administration have explicit tests and documented boundaries.
  • Flag-off legacy behavior and flag-on enforcement have separate assertions; migration/backfill does not silently hide the organisation's existing estate.

Compatibility boundary to review

Unchanged requests and equal results are the target for organisation-owned data the caller is entitled to see. Some master admin endpoints return cluster-wide data today, and enabling isolation necessarily changes those results (REST history/brokers are currently made cluster-only and Staff Tenant#index currently returns cluster-wide data to admins on master). Do not silently treat that as backwards compatibility. Classify organisation history and formerly shared infrastructure explicitly, and preserve legitimate single-org capabilities through scoped alternatives before enforcement rollout. Partner aggregation is intentionally replaced by explicit selection.

Maintenance verification before implementation

The initial maintenance phase refreshed branches and dependencies before the REST implementation in #464. Staff domain isolation, client selection UI and production rollout remain separate work.

  • Refresh all cloned repositories, preserve local work, select expected branches and install shards. Full inventory: tasks/clone-refresh-2026-11-16.md.
  • Merge latest master into models#332 (5adba67), rest-api#451 (6392a7c), staff-api#390 (06e8672) and init#105 (merge 127a0e9; build fixes b28f7f2, 8b67d6c), preserving PR history.
  • Refresh downstream models dependency locks to 5adba67; root and migrator dependencies installed.
  • Audit REST identity, organisation reach/selection and list/detail/write scoping; retain Staff calendar domain tenancy; compare master behavior.
  • Record implementation phases, native issue dependencies, owner, milestone and acceptance matrix before feature implementation.
  • Apply and check the build-only init compiler concurrency change; verify all current-head GitHub test/lint suites. Image publication status is recorded separately below.

User decision: Staff API remains domain-based; request-wide organisation selection and calendar credential switching are excluded.

Repository Refresh-phase HEAD Test/lint verification Image build
models 5adba67 CI passed: latest and unstable each 936 examples, 0 failures/errors; style passed No separate image job
rest-api 6392a7c CI passed: latest and unstable each 1,378 examples, 0 failures/errors, 1 pending; lint/style passed Running
staff-api 06e8672 CI passed: latest and unstable each 638 examples, 0 failures/errors, 12 pending; browser e2e 136 passed; lint/style passed Passed
init 8b67d6c Current-head CI passed: latest and unstable each 13 examples, 0 failures/errors; lint/style passed Passed

All active cloned checkouts are clean and match upstream. Each tenancy branch contains its current origin/master. Historical worktrees and pinned submodules are intentionally preserved; see the clone inventory for exact exceptions and shard checks. pg-orm installs with its supported skip-postinstall/executables options because the declared old Ameba does not compile with host Crystal 1.22; its shard dependency check passes.

Maintenance introduced no new organisation feature behavior. Staff’s merge also simplified an existing redundant assignment found by lint in its touched application controller. Local app no-codegen compilation passed for REST, Staff and init; formatting and focused lint checks passed. GitHub test/lint CI is authoritative; newer local Ameba has pre-existing findings on master too.

Init’s previous image run failed with compiler memory exhaustion at src/sam.cr while both architectures compiled concurrently, matching the earlier PR run. Commits b28f7f2 and 8b67d6c limit LLVM compiler threads to one using Shards-compatible --threads=1, preserving debug/frame-pointer/link settings. The initial spaced form was rejected as a Shards target; the corrected form was reproduced in an isolated shard and actual init targets passed no-codegen compilation. The subsequent image build passed, verifying the corrected compiler option in CI.

The refreshed Staff and init image builds subsequently passed. Superseded REST image builds were cancelled after a newer candidate was pushed; the final REST image build is tracked with #464. No PRs were merged. REST implementation followed in #464; see its final verification and rollout notes.

Historical REST implementation review — 2026-11-16

Implemented in #451, final head 722722a; checklist and test history: #464. Ordinary callers default to their home organisation even with extra grants; partner/management staff select one organisation. Exact grants, immutable login identity, domain-owned resources, metadata/history, destructive references, control/MCP sockets and MQTT owner checks are covered. Staff remains domain-based with no selector or calendar credential changes.

Verification: Final CI passed on 722722a: latest and unstable each ran 1,481 examples, 0 failures, 0 errors, 1 existing pending (Edges::ConnectionManager). Ameba, Crystal/Dockerfile style and PR checks passed. Final image build passed. The branch is clean, matches upstream and contains origin/master.

The local Docker compiler exceeded the 8 GB VM before examples ran; runtime verification used GitHub's full matrix. Native application build and focused spec semantic checks pass, along with formatting/lint and final generated OpenAPI/MCP contracts. A legacy zone test's first-page assumption was fixed with isolated tagged fixtures and unchanged assertions; no production pagination limit changed.

Remaining work is deliberate: Staff's independent domain-isolation follow-up (#396), client selector integration, ownership reconciliation/test-cluster provisioning and rollout, and replacing downstream models branch pins after models#332 releases. PLACE_TENANCY_ENFORCE remains off by default. The implementation is ready for review; no deployment, enforcement activation or PR merge is performed here.

P1/P2 implementation review — 2026-11-17

See #465 for the completed source checklist, regression-first evidence and final-head CI links. All runtime matrices now pass: models716ca76 (970 examples), REST1507d3a (1,538), Staffa9b8a21 (654) and init2a986f8 (18), in both compiler variants. Existing pending specs are unchanged. REST, Staff and init current-head multiarch image builds have all passed. Every required check is green; the four PRs remain drafts for review.

REST uses domain-owner defaults for all roles and zone-only execution authorisation, with ownership/alias validation. Staff stays domain/calendar based. Existing customer organisations/configuration are preserved; unknown/mixed references are reported rather than reassigned. The cluster-admin reconciliation API provides bounded preview, audited/idempotent apply and safe access summaries, including before enforcement is enabled. Driver source remains unchanged; the deferred consumer ledger is in #465.

Deferred work: support-client selector UI, driver updates, operator review/provisioning and test-cluster rollout, downstream release pins after models#332 merges, then coordinated squash merges/deployment. Enforcement remains off by default. No production rollout or full-platform local smoke is claimed here.

Activity

  1. added this to the Multi-tenancy milestone on Nov 16, 2026
  2. self-assigned this
    on Nov 16, 2026
  3. changed the title [-]Plan organisation selection across APIs[/-] [+]Plan organisation selection and domain scoping[/+] on Nov 16, 2026
  4. stakach commented on Nov 16, 2026

    @stakach
    MemberAuthor

    Approved implementation follow-up: #465. New contract supersedes the earlier mandatory partner selector: omitted organisation_id defaults to the authenticated domain owner for every role; explicit selection narrows authorised reach. Staff remains domain/calendar-based; driver updates are deferred. Zone execution authorises the addressed zone only, with bounded dispatch ownership and appropriate OAuth/key scopes, without separate descendant operation grants. Regression-first work has begun; no merges or deployments are authorised by this follow-up.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions