Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
docs(multi-tenancy): split the runtime database role out of Phase 1
Wojciech Wojtyniakd99520c69c47
diff --git a/docs/old/multi-tenancy-phase1-db.md b/docs/old/multi-tenancy-phase1-db.mdindex 3757c592e..8ebede246 100644--- a/docs/old/multi-tenancy-phase1-db.md+++ b/docs/old/multi-tenancy-phase1-db.md@@ -237,43 +237,47 @@ create policy tenant_isolation on <t>- `tenants` uses `id = (select require_tenant_id())`; every other table uses`tenant_id`.-## One new database role+## The runtime role, and why it is not in this phaseToday the application connects to Postgres as the superuser in local Compose,in the chart and in the test containers. **A superuser ignores row-level-security unconditionally** — not "unless forced", unconditionally. Shipping-policies without changing this produces a schema full of decoration and an-isolation test that passes for the wrong reason. This is the largest piece of-work in Phase 1 and the only part that touches deployment.--The change is deliberately small: **add one role, transfer nothing.**--- **The existing role keeps owning the schema** and keeps running Alembic.- Because it owns the tables it bypasses their policies, and we deliberately do- **not** set `force row level security`, so that stays true. No `ALTER TABLE- … OWNER TO`, no `REASSIGN OWNED`, nothing to go wrong during a cutover.-- **`switch_app` is new**: the runtime role, not the owner, not a superuser, no- `BYPASSRLS`. Policies apply to it and it is the only role the request path- ever uses.--Roles are cluster-level, so the migration does not create them — it grants to a-role that must already exist and fails loudly if it does not. Creating the role-belongs to Compose, to the chart, and to the RDS runbook, which already-recreates roles by hand. `alter default privileges` covers tables added later,-so a future migration cannot ship a table the runtime cannot read.--**The check that matters runs at startup, not in CI.** CI asserts nothing about-production, and the failure mode here is silent. On boot the service verifies-its own connection: not a superuser, no `BYPASSRLS`, not the owner of-`messages`, and a probe query against a scoped table with no tenant set must-raise. If any of those is wrong the service refuses to start, because a Switch-that thinks it is isolating tenants and is not is worse than one that is down.--**Sequencing.** The role is cheapest to add during the RDS cutover-(CHOO-2622), which already creates an application role by hand, and that-restore uses `--no-owner --no-privileges` — so who ends up owning the restored-tables is a decision that has to be made deliberately there, not discovered-afterwards. Coordinate, do not race.+security unconditionally** — not "unless forced", unconditionally. Until the+runtime connects as a role that policies apply to, everything in the section+above is inert in a deployed environment.++That work — creating a `switch_app` role in Compose, the chart and the RDS+runbook, granting it, pointing the service at it, and a startup self-check that+refuses to boot if the connection is a superuser or the table owner — **is+tracked separately and is not part of Phase 1.** The shape it should take, so+that whoever picks it up does not have to rediscover it:++- **Add one role, transfer nothing.** The existing role keeps owning the schema+ and keeps running Alembic. Because it owns the tables it bypasses their+ policies, and we deliberately do **not** set `force row level security`, so+ that stays true. No `ALTER TABLE … OWNER TO`, no `REASSIGN OWNED`, nothing to+ go wrong during a cutover.+- **`switch_app` is the runtime role**: not the owner, not a superuser, no+ `BYPASSRLS`, with `alter default privileges` so a later migration cannot ship+ a table it cannot read.+- **The check that matters runs at startup, not in CI.** CI asserts nothing+ about production and this failure mode is silent. A Switch that believes it+ is isolating tenants and is not is worse than one that is down.+- **Cheapest during the RDS cutover** (CHOO-2622), which already creates an+ application role by hand and restores with `--no-owner --no-privileges` — so+ who owns the restored tables is a decision made there either way.++Splitting it is a reasonable call while the deployment has one tenant, because+there is nothing to leak. It is not a follow-up nicety: **it is a prerequisite+for onboarding a second tenant**, and Phase 1 shipping without it means the+policies exist and do not yet bite.++Phase 1 does keep a restricted role **inside the test fixtures**, which is+contained to the test harness and touches no environment. Without it nothing+verifies a single policy, and 38 of them would ship unexercised.++Consequently this design's migration creates no roles and issues no grants.+Both belong to the role work, in one place, rather than half here behind a+conditional that silently does nothing.## Setting the tenant@@ -334,7 +338,7 @@ Authentication happens before a tenant is known — resolving an API key by hashor a JWT subject to its memberships, is unscoped by definition. So:> **Authentication and tenant resolution run in a system session. Everything-> downstream runs in a tenant session as `switch_app`.**+> downstream runs in a tenant session, as the restricted runtime role.**The same escape hatch covers work that is legitimately cross-tenant: Alembic,admin and bootstrap seeding at startup, the bridge and connector lifecycle@@ -405,7 +409,8 @@ One revision:and `validate constraint` after, so the validation scan does not hold anexclusive lock.8. Enable row-level security and create the policy on each table.-9. Grant to `switch_app` and set default privileges.++No roles are created and no grants issued — see the role section above.Only tenant zero exists when this runs, so the usual expand-then-contractcaution does not apply yet. From the next customer onward it does, and that@@ -414,11 +419,15 @@ note belongs in the migration's docstring.## Done whenAn integration test proves tenant A cannot read tenant B's rows through the-ordinary application paths — connected as the runtime role, through the store+ordinary application paths — connected as a restricted role, through the storelayer, not by hand-written SQL. That needs test infrastructure that does not-exist yet: the fixtures create `switch_app`, grant to it, connect as it, and-seed tenant zero, because the truncation between tests now empties `tenants`-too.+exist yet: the fixtures create the role, grant to it, connect as it, and seed+tenant zero, because the truncation between tests now empties `tenants` too.++Note what this does and does not prove. It proves the **policies** are correct,+which is the part Phase 1 owns. It does not prove the **deployment** is subject+to them — that is the role work, and until it lands the same test against a+real environment would pass for the wrong reason.Alongside it, three cheap tests that catch the regressions this design existsto prevent:@@ -434,6 +443,10 @@ to prevent:Named so they are decisions rather than omissions.+- **The policies do not bite in a deployed environment.** The runtime still+ connects as a superuser, so every policy here is inert outside the test+ suite until the runtime-role work lands. Deliberate, and safe while one+ tenant exists — and the hard prerequisite for the second.- **Cross-tenant user enumeration.** `users` and `oidc_identities` have nopolicy, so any tenant session can read every account. There is no exposurewhile one tenant exists, and the correct fix needs invitations and a