ADR-013: Organization plane (tenant hierarchy and scope-typed credentials)
Date: 2026-11-09 Status: Accepted
Context
This section records the situation before ADR-013; the decision and implementation below replace that model.
LumiBase is multi-tenant by default: every domain table carries site_id,
every query filters by it, and an API key (lbk_…) is bound to exactly one
site (api_keys.site_id, packages/database/src/schema/access.ts). Roles,
policies and memberships (user_sites) are all per site. The only principal
that stands above a site is the bootstrap admin (users.is_bootstrap), and it
is a boolean flag, not a principal with an API surface.
The model therefore has one plane: the site. Nothing in the schema can answer the question "who may create a site, and whose site is it?":
sites(packages/database/src/schema/core.ts) has no parent column — noowner_id, noorganization_id. A site belongs to nobody./api/v1/admin/sites(former create/delete routes) (apps/cms/src/routes/admin.ts) exist only because the test runner needs them. They are guarded byrequireSiteAdminof the calling site, so an administrator of site A can create arbitrary sites or delete site B. Tenant isolation is only as strong as the weakest route, and these two routes have no tenant to be isolated to.- The MCP server (
packages/mcp-server) mirrors the model exactly: oneLUMIBASE_SITE_ID, one site-scoped token, therefore nocreate_site,list_sitesorswitch_sitetool. That is correct for the credential it holds — a site token must never reach outside its site — but it leaves no credential that could.
The trigger for this ADR was a user asking the MCP server to create a new site and discovering it cannot. The real gap is not a missing tool; it is a missing tier above the site.
Terminology already in use
LumiBase already uses "control plane" for site-scoped administration:
CONTROL_PLANE_PATHS in apps/cms/src/middleware/control-plane-access-guard.ts
(/api/v1/access, /api/v1/admin, /api/v1/roles, …), the
controlPlaneAdmin grant in EffectiveCapabilityService, and "control-plane
skills" in the MCP route. That meaning is kept unchanged. This ADR introduces a
tier above it and names it the organization plane to avoid overloading
the word. Three tiers result:
| Tier | Scope | Who | Credential | Examples |
|---|---|---|---|---|
| Instance plane | one deployment | self-host operator | process env, setup token, is_bootstrap user | first-run setup, instance-wide lockout policy, enabling org sign-up |
| Organization plane (new) | one tenant account, N sites | org owner / admin / billing | Studio session with org membership, or lbo_… organization key | create/delete/transfer site, org members, billing, org-level defaults |
| Site plane (existing) | one site | site roles | Studio session with user_sites row, or lbk_… site key | control plane (/admin, /roles, …) + data plane (items, collections, flows) |
What the industry converged on
Every large platform solved the same problem with the same shape, differing only in names:
| Platform | Container | Resource | Lesson taken |
|---|---|---|---|
| AWS | Organization → OU → Account | IAM inside the account | Creating an account is an Organizations API, not an IAM permission inside any account. Service-control policies cap the whole tree. |
| GCP | Organization → Folder → Project | IAM inside the project | resourcemanager.projects.create is a permission on the parent; IAM is inherited downward. Service accounts live inside a project (≈ lbk_). |
| Azure | Entra tenant → Management group → Subscription | ARM RBAC | Identity plane and resource plane are separate; a Global Administrator must explicitly elevate access (audited) to touch resources. |
| Cloudflare | Account → Zone | zone roles | Closest analogue (Zone ≈ Site). API tokens are typed by scope (account vs zone) and carry an explicit permission list. |
| Supabase | Organization → Project | anon / service keys | Two credential kinds: a Personal Access Token for the Management API (create_project, list_organizations) and per-project keys for data. Its MCP server runs on the PAT with --read-only and --project-ref to narrow it. |
| Kubernetes | Cluster | Namespace | ClusterRole vs Role; creating a namespace is a cluster-scoped verb. The cleanest semantic model. |
The common pattern, which this ADR adopts: (1) a container tier above the resource; (2) the permission to create a resource lives on its parent; (3) credentials are typed by scope, not ranked by power — a resource-scoped credential can never call the container tier, however privileged it is inside its resource; (4) the operator of the whole installation is a third, separate tier.
Decision
1. Add an organizations tier; a site belongs to exactly one organization
organizations ← lumibase_organizations
id (nanoid), slug (unique), name, settings jsonb, created_at, updated_at
organization_members ← lumibase_organization_members
(user_id, organization_id) PK, role: owner | admin | billing | member
sites.organization_id ← NEW, FK → organizations.id, NOT NULL after backfill
api_keys.scope ← NEW, 'site' | 'organization' (default 'site')
api_keys.organization_id ← NEW, FK, set iff scope = 'organization'
api_keys.site_id ← becomes nullable (null iff scope = 'organization')
- IDs follow Strict Rule #1 (
nanoid()); table names follow ADR-010. organization_members.roleis a closed enum, not a row inroles. The siteroles/policiesDSL (ADR-008) models what you can do to content; the organization tier has a small fixed vocabulary and does not need the DSL.owneris the only role that can delete the organization or transfer a site out; at least oneownermust always exist (same invariant style asusers_is_bootstrap_unique).- Backfill: every existing site is attached to a personal organization
created for the bootstrap user (
slug = 'default', name from the__default__site). This is the Vercel "personal team" / GitHub personal account pattern: self-hosted single-tenant installs never see an organization unless they create a second one.
2. Organization-plane authorization is a separate check, not a bigger role
A fixed action vocabulary is evaluated against organization_members.role:
| Action | owner | admin | billing | member |
|---|---|---|---|---|
org:read | ✓ | ✓ | ✓ | ✓ |
org:sites:create | ✓ | ✓ | ||
org:sites:delete, org:sites:transfer | ✓ | |||
org:members:manage | ✓ | ✓ | ||
org:keys:manage (organization keys) | ✓ | ✓ | ||
org:billing:manage | ✓ | ✓ | ||
org:settings:write | ✓ | ✓ | ||
org:delete | ✓ |
Inheritance into the site plane (GCP/Cloudflare model): an organization
owner or admin is treated as a site administrator on every site of the
organization — hasSiteAdminAccess consults organization_members after
user_sites. Rationale: it prevents lockout (an owner can always recover a
site whose last admin left) and matches operator expectations. Every such
access is recorded in audit_log with via: 'organization' so provenance is
preserved. billing and member inherit nothing; they need a user_sites
row like anyone else.
No upward inheritance, ever. A site administrator, a site lbk_ key,
and the controlPlaneAdmin grant give zero organization-plane rights. The
existing CONTROL_PLANE_FORBIDDEN posture stays exactly as it is for the
site tier; the organization tier gets its own ORGANIZATION_FORBIDDEN code.
3. Credentials are typed by scope; the prefix says which
| Credential | Prefix | Carries | Can call |
|---|---|---|---|
| Site key (existing) | lbk_ | site_id | site plane only |
| Publishable site key (existing) | lbk_pub_ | site_id | public data plane only |
| Organization key (new) | lbo_ | organization_id | organization plane; plus any site of that organization as if it were an administrator there, narrowed by an optional site pin |
| Studio session (existing) | JWT aud: studio | user | both planes according to memberships |
A distinct prefix keeps secret scanners and audit queries unambiguous, the
same reason lbk_pub_ exists (apps/cms/src/services/api-key-publishable.ts).
The organization key is minted and rotated through the organization plane
(/api/v1/orgs/:orgId/keys), never through /api/v1/api-keys, so a site admin
cannot mint one. EffectiveCapabilityService gains a third caller class
organization_api_key; resolving it with an X-Lumi-Site header checks that
the site belongs to the key's organization and then grants administrator
capabilities on that site.
4. Routing: the organization plane does not require X-Lumi-Site
GET /api/v1/orgs list organizations the principal belongs to
POST /api/v1/orgs create (instance plane decides who may: §6)
GET /api/v1/orgs/:orgId
PATCH /api/v1/orgs/:orgId
DELETE /api/v1/orgs/:orgId human owner only; no organization-delete MCP tool
GET /api/v1/orgs/:orgId/sites
POST /api/v1/orgs/:orgId/sites replaces former test-only site creation
DELETE /api/v1/orgs/:orgId/sites/:siteId replaces former test-only site deletion
POST /api/v1/orgs/:orgId/sites/:siteId/transfer
GET|POST|PATCH|DELETE /api/v1/orgs/:orgId/members[/:userId]
GET|POST|DELETE /api/v1/orgs/:orgId/keys[/:keyId]
- The tenant middleware (
apps/cms/src/middleware/tenant.ts) exempts/api/v1/orgsfrom theX-Lumi-Siterequirement; RLS request scope (rls-request-scopespec) is set to the organization instead. /api/v1/admin/sites(former create/delete routes) are removed once the test runner is moved to the new routes with an organization key. Their interim containment (restrict delete to the caller's own site, gate create behind the bootstrap user) is a separate hotfix, not part of this ADR.- Site creation runs the same provisioning the setup wizard runs for a site
(
administrator/memberroles, officiallumibase-*extensions viareconcileOfficialExtensions, negative-cache purge), so a site created from the organization plane is indistinguishable from one created at first run.
5. MCP: one server, tool set decided by the credential
The MCP server stays a single package. At start-up it inspects
LUMIBASE_TOKEN:
| Token | LUMIBASE_SITE_ID | Exposed tools |
|---|---|---|
lbk_ | required (as today) | current site tool set, unchanged |
lbo_ + site id | pins client routing to one site | current site tool set plus list_sites, get_organization (read-only org tools) |
lbo_ without site id | — | organization tools (get_organization, list_sites, create_site, delete_site, transfer_site, list_org_members, invite_org_member, create_org_key) plus site tools that take a site argument |
Rules:
LUMIBASE_READ_ONLY=truehides every mutating tool regardless of token (Supabase--read-onlypattern). Recommended default in the published configuration snippets.- Organization-plane mutations are destructive by definition and route
through
ai_approvals(Strict Rule #4; ADR-003) when called by an agent principal, independently of theconfirm=trueconvention used by site tools. They start at autonomy L0/L1 (propose → human approves) and are not eligible for veto-window or autopilot promotion in this ADR. - The per-site
contentOs.mcpflag keeps gating site tools. An organization settingcontentOs.mcp.allowOrganizationTools(defaultfalse) gates the organization tools; the instance operator can force it off withLUMIBASE_MCP_ORG_TOOLS=off. - The governed harness (
packages/mcp-server/src/governed.ts) is extended to carryorganizationIdso run audit and kill switch cover organization-plane calls.
6. Instance plane: who may create organizations
- Self-host (Docker): by default only the
is_bootstrapuser may create additional organizations;LUMIBASE_ALLOW_ORG_SIGNUP=trueopensPOST /api/v1/orgsto anystudio-audience user. No new instance role is introduced; the bootstrap user is the instance operator, as today. - Hosted integration: enable the flag and have the staff signup flow call
POST /api/v1/orgsafter the first Studio login to provision a personal organization. This is an integration through the guarded API; public frontend self-service is not promoted into Studio identity. Billing belongs to the organization settings container; real billing is outside this ADR. - Instance-wide settings keep living on the
__default__site (apps/cms/src/modules/setup/site-constants.ts); this ADR does not move them. A later ADR may lift them to aninstance_settingstable.
Consequences
Positive
- Site creation, deletion and ownership have a home. The "who may create a site" question is answered by data, not by a test-only route.
- A leaked
lbk_key — even one with an admin policy — can never create or delete sites. Blast radius of the most common credential is unchanged by this ADR and becomes provably bounded to its site. - The MCP server gains organization capabilities without any site-token user seeing a single new tool. Agents get the capability under HITL from day one.
- Mirrors the mental model operators already have from AWS/GCP/Cloudflare; Studio can show an organization switcher like every comparable product.
- Billing, quotas and org-level defaults (locales, branding templates, allowed extensions) get a natural owner, unblocking the hosted offering.
Negative / trade-offs
- Two organization tables and hand-written migrations
0024_organizations(schema/backfill) and0025_organization_approvals(real organization approval scope and receipts). Migration numbering was reconciled across open branches; rollback requires restoring a pre-upgrade backup. api_keys.site_idbecomes nullable. Every reader ofapi_keysmust handlescope = 'organization';EffectiveCapabilityServiceand the key auth middleware are the choke points, but the audit is real work.- Downward inheritance (org owner ⇒ site administrator) widens what an organization owner can read. Mitigated by audit provenance and by the fact that owners already hold the keys that could grant themselves access.
- Self-hosted single-tenant users gain a concept they do not need. Mitigated by the personal-organization backfill: Studio hides only the switcher with one organization. Organization Settings remains visible to owner/admin.
Verified controls and boundaries
- Credential scope is tested in
apps/cms/src/__tests__/auth-middleware-matrix.test.tsand real organization API integration tests. Site credentials cannot enter the organization plane; organization keys cannot access foreign sites. - Hotfix #628 landed on main first; Phase 2 removed the legacy test-only admin site routes in #666.
- Organization mutations always require a human decision. Migration
0025_organization_approvalsstores an organization parent and requester; authorization is rechecked and the mutation/receipt commit atomically. A minted key's plaintext is returned once, in the approver's decide response; the stored receipt keeps only key metadata (tokenRedacted: true), also on read and replay.organizationIdand run ids are present in audit metadata. - An organization key cannot change who holds authority. Member writes, organization-key writes and
PATCH /orgs/:orgIdrequire a user session; a key requests them through MCP approval. Without this, the admin role would let a leaked key add its holder as a human admin, mint keys that outlive its revocation, or enable its own MCP tools. - Transfer requires the same human owner in both organizations. Organization keys may mint site keys for owned sites, but never gain owner authority. Only owners may rename the personal organization's
defaultslug; it is reusable afterward. - Password login/refresh still require a live site. An organization with no sites remains accessible with a valid organization key or Studio session; fully site-free human recovery is separate instance-level work (backlog B196). Keep a recovery credential or restore a backup.
Alternatives considered
- A
super_adminflag or role aboveadministrator. Rejected: it ranks power instead of typing scope, so a leaked key with that role is worse, not safer; it has no place to record which sites the holder owns; and every vendor surveyed moved away from it (Azure's "elevate access" is the audited escape hatch, not the model). - A second MCP package (
@lumibase/mcp-admin). Rejected for now: it doubles release and docs surface, and the credential already carries the information needed to choose the tool set. Revisit if the organization tool set grows past ~15 tools. - Treat
__default__as the "root site" and hang others under it. Rejected: it conflates instance settings with a tenant, keepssitesowner-less, and would make deleting the root site catastrophic. - Model organization roles with the site Policy DSL (ADR-008). Rejected: the organization vocabulary is nine fixed actions; the DSL's collection/field/row semantics do not apply, and a fixed enum is easier to reason about in a security review.
References
apps/cms/src/routes/admin.ts— formerPOST/DELETE /sites(removed in #666)apps/cms/src/middleware/control-plane-access-guard.ts— existing site-scoped "control plane" (unchanged)apps/cms/src/services/effective-capability-service.ts— caller classesapps/cms/src/services/api-key-publishable.ts— prefix precedent (lbk_pub_)packages/database/src/schema/{core,access}.ts—sites,users,api_keyspackages/mcp-server/src/{client,governed}.ts— token/site configurationdocs/en/security/user-management.md§7 — prior MCP exposure assessment- ADR-003 (HITL), ADR-008 (Policy DSL), ADR-010 (table prefix), ADR-011 (realms)
- Spec:
.kiro/specs/organizations/