# Feature spec: multi-tenancy Status: draft, 2026-09-18. Feature 1 in SPEC.md §4. ## Provenance Written for the clean room (SPEC.md §3). Everything here comes from these sources, and nothing else: | Source | License | Used for | |---|---|---| | Stalwart's registry schema: `crates/registry/src/schema/*.rs` and `resources/schema/schema.json.gz`, upstream `d9dee0a` | AGPL-3.0-only OR LicenseRef-SEL, taken under the AGPL | Object shapes, field meanings, enum values, permission names, what upstream flags as Enterprise | | Stalwart documentation, "Tenants" (`website` repo, `docs/auth/authorization/tenants.md`) | Unlicensed public documentation: facts used, prose not copied | Isolation, the permission ceiling, quota semantics, branding | | ihasmail FEATURES.md, "Tenants", and its admin code | AGPL-3.0-or-later, ours | Behavior observed against a live Enterprise server | | RFC 8620 | IETF | JMAP semantics for errors and `/set` | | Probes of INBUXA's live Enterprise server, 2026-09-18 (Stalwart 0.16.22) | Observation | Everything under "Observed" | No Enterprise-only file or snippet was used. The session that drafted this had seen short Enterprise snippets while surveying the license split, so it writes specs only. Where this spec needs a behavior no public source settles, it settles it by observation (see "Observed") or makes a decision of its own, marked **Decision**. It never fills a gap from memory of upstream code. ## What it is A tenant is a separate organization on one server: its own accounts, groups, mailing lists, domains and settings, and an administrator who manages only what is in it. One tenant can't see or reach another's resources. The server operator decides how much of the server each tenant may use: which permissions its people can hold, how many of each thing it can create, and how much storage it can consume. Upstream ships this only in its Enterprise Edition. inbuxa-server ships it to everybody, always on. There is no edition check. ## Data model Unchanged from upstream, so existing data opens as it is (SPEC.md §7). ### The tenant object, `x:Tenant` | Field | Type | Set by | Meaning | |---|---|---|---| | `name` | string | admin | The tenant's name. There is no separate description | | `createdAt` | UTC date-time | server | When it was created | | `logo` | string, nullable | admin | An image URL or a data URL, shown to the tenant's people | | `roles` | `Roles`: `Default`, or `Custom` with a list of roles | admin | The roles the tenant holds, which are the most its people can be given | | `permissions` | `Permissions`: `Inherit`, `Merge` or `Replace`, with enabled and disabled lists | admin | The permissions the tenant may grant | | `quotas` | map from `TenantStorageQuota` to an unsigned number | admin | Limits; a missing key is no limit | | `usedDiskQuota` | size in bytes | server | Storage used by all members together | Permission prefix: `sysTenant`. Permissions: `sysTenantGet`, `sysTenantCreate`, `sysTenantUpdate`, `sysTenantDestroy`, `sysTenantQuery`, and `taskTenantMaintenance`. ### Quota keys, `TenantStorageQuota` `maxAccounts`, `maxGroups`, `maxDomains`, `maxMailingLists`, `maxRoles`, `maxOauthClients`, `maxDkimKeys`, `maxDnsServers`, `maxDirectories`, `maxAcmeProviders`, and `maxDiskQuota` (bytes). ### Membership, `memberTenantId` A nullable reference to an `x:Tenant`. Null means the object belongs to no tenant and is managed at server level. It appears on: - principals: `UserAccount`, `GroupAccount`, `MailingList`, `Role`; - `Domain`; - signing and DNS: `Dkim1Signature`, `Dkim2Signature`, every `DnsServer*` provider, `AcmeProvider`; - directories: `LdapDirectory`, `SqlDirectory`, `OidcDirectory`; - `OAuthClient`; - incoming reports: `ArfExternalReport`, `DmarcExternalReport`, `TlsExternalReport`. ### Elsewhere - `x:Authentication.defaultTenantRoleIds`: the roles a tenant gets when its `roles` is `Default`. - Task `TenantMaintenance`, with `tenantId` and `maintenanceType`. The only type is `recalculateQuota`. - Store maintenance type `resetTenantQuotas`: reset every tenant's usage figure. - Event and metric `limit.tenant-quota`: a tenant limit was reached and the operation was refused. - `x:Cache.tenants`: cache size for tenants. Upstream flags these fields as Enterprise, and in inbuxa-server they're ordinary: every `memberTenantId` listed above, `Authentication.defaultTenantRoleIds` and `Domain.logo`. The other flagged fields belong to other features' specs. ## Required behavior Each requirement has an ID, and tests name the IDs they check. ### Isolation - **MT-1.** A principal in a tenant can reach only objects with the same `memberTenantId`. Reach covers JMAP `/get`, `/query`, `/changes` and `/set` on every object type that carries the field, directory lookups, sharing and access rights, and any list an admin screen shows. - **MT-2.** Objects in no tenant (`memberTenantId` null) are server-level. A principal in a tenant can't read or change them, except what every account already reads about itself: its own account, its own settings, and the server's public capabilities. - **MT-3.** Any write that would link an object to one in a different tenant is refused with `invalidForeignKey`, naming the object it can't link to: a group member, a list member or owner, a role, a sharing grant, a domain's ACME or DNS provider. "Different" includes no tenant. A tenant's domain can't use a server-level provider, even when a server-level admin makes the change (observed 1). Shared infrastructure is therefore per-tenant: each tenant brings its own providers. - **MT-4.** Mail flow isn't isolation. Mail between addresses in different tenants is delivered like any other mail, through the normal delivery path. Tenants separate administration and resources, not the network. - **MT-5.** Queued and outgoing mail are resources. A tenant administrator sees and acts on queued messages whose recipients are on the tenant's own domains, whoever sent them, and never sees anything else in the queue (observed 4). **Decision** for the sender side, not yet observed: it also sees messages its own principals sent, until they leave the queue. ### Membership - **MT-6.** Only an administrator in no tenant, with the matching `sys*` permission, can create a tenant, delete one, or change any object's `memberTenantId`. A tenant administrator can't move anything into or out of a tenant, their own included. - **MT-7.** A principal's tenant always matches its domain's tenant. A principal on a domain in tenant T is in T. A principal on a domain in no tenant is in no tenant. On create, `memberTenantId` defaults to the domain's tenant. A write that sets any other value is refused with `invalidForeignKey` naming the domain, which is upstream's own refusal (observed 7). **Decision**, a deliberate difference: upstream doesn't default the tenant. An account created on a tenant's domain without one lands in no tenant, a server-level account on a tenant's domain. inbuxa-server never creates that state. Existing accounts found in it (none at INBUXA, possible elsewhere) are left working and listed in the admin dashboard for an operator to resolve. **Decision** (2026-09-18): the server exposes nothing new for that list. ihasmail finds such accounts itself by comparing each account's `memberTenantId` with its domain's. - **MT-8.** A domain can move into a tenant only from no tenant, and out of one only back to no tenant. It moves only when no principal on it belongs to anything other than the destination. **Decision**, a deliberate improvement on upstream (observed 8): upstream lets a domain leave a tenant while the tenant's accounts are still on it. They stay in the tenant, on a domain that isn't, and can still sign in. - **MT-9.** Creating a domain inside a tenant also puts its DKIM keys in that tenant. Upstream generates two per domain (observed 9). - **MT-10.** A tenant can be deleted only when nothing references it. Otherwise deletion is refused with `objectIsLinked`, listing what still refers to it. **Decision**: ihasmail already enforces this in its interface, and the server should too. ### Administering a tenant - **MT-11.** A tenant's administrator is an account inside the tenant that holds administrative permissions (upstream: the `Admin` role, which inside a tenant carries 290 permissions against 641 at server level; observed 3). Within the tenant it can do what those permissions allow, on every object type that carries `memberTenantId`. Everything it creates lands in its own tenant (observed 1). It never needs to, and may not, set `memberTenantId` itself. `memberTenantId` isn't returned to it at all (observed 3). - **MT-12.** A tenant administrator can read its own tenant's `x:Tenant` object (name, logo, quotas, usage) but can't change it. Changing the tenant object itself is server-level. **Decision**, a deliberate difference: upstream refuses the read with `forbidden` (observed 3), so a tenant admin can't see its own limits or usage. ihasmail needs them to warn before a limit is hit. **Decision** (2026-09-18) on how: the read needs `sysTenantGet` (and `sysTenantQuery` to list), which the default Tenant Administrator role now holds. Inside a tenant they reach only its own `x:Tenant`; any other comes back `notFound`. `x:Tenant/set` is refused inside a tenant whatever the permissions (MT-6). Only the defaults change: roles already stored on an existing server are left as they are (SPEC.md §7), and an operator adds the two permissions to an existing tenant-admin role by hand. ### The permission ceiling - **MT-13.** A principal's effective permissions are its own, cut down to what its tenant allows. A permission the tenant doesn't hold has no effect on anyone in the tenant, whoever granted it. Granting it isn't an error. It just does nothing. - **MT-14.** What a tenant allows is computed from its `roles` and its `permissions`: 1. **Roles.** `Default` means the roles in `Authentication.defaultTenantRoleIds`; `Custom` means the listed roles. The permissions of all those roles, taken together, are the base. 2. **Permissions.** `Inherit` uses the base unchanged. `Merge` adds the enabled list to the base. `Replace` uses only the enabled list and ignores the base. 3. **Disabled wins.** In `Merge` and `Replace`, the disabled list is removed last. A disabled permission is never allowed, however it was reached. - **MT-15.** The ceiling can never exceed what the server grants. No setting on a tenant can give its people a permission the server has disabled for them. - **MT-16.** Changing a tenant's roles, permissions or quotas takes effect for its people without a restart and without them signing in again. The next request is judged by the new rules. **Decision**, a deliberate improvement: upstream caches each principal's permissions, and a change to the tenant hadn't reached an already-authenticated admin after seven minutes (observed 6). A change must invalidate the cached permissions of everyone it affects. ### Quotas - **MT-17.** Count quotas. Creating an object that would take a tenant past its count limit for that kind is refused with `overQuota`, and the server emits `limit.tenant-quota`. Moving a domain into a tenant counts its principals and keys against the tenant's limits first, and is refused the same way if any limit would be crossed. - **MT-18.** Existing objects over a lowered limit stay. Only new ones are refused. - **MT-19.** Disk quota. `maxDiskQuota` bounds the total storage of every member together. A message that would take the total past it isn't delivered, even if usage is still under the limit (observed 2). Per-account quotas still apply as well, whichever is reached first. - **MT-19a.** The refusal matches upstream: local delivery answers `451 4.3.0 Organization over quota.`, a temporary failure, so the message waits in the queue and retries until the queue gives up. Submission itself still succeeds, so the sender learns nothing until the delay notice. **Decision** on top: when a sender inside the server submits to a recipient whose tenant is over quota, say so at submission time too (a JMAP `EmailSubmission` warning, not a refusal). **Deferred** (2026-09-18): RFC 8621 has no warnings field, so the submission-time warning waits until the contract defines one. The `451` refusal is built. - **MT-20.** `usedDiskQuota` is kept current as members' usage changes: it moved on the delivery itself (observed 2). It is never written by a client. - **MT-21.** The `recalculateQuota` task recomputes one tenant's `usedDiskQuota` from its members' actual usage. `resetTenantQuotas` recomputes every tenant. Both can run while the server is live. ### Branding - **MT-22.** A signed-in principal can read the logo that applies to it: its domain's `logo` if set, else its tenant's `logo` if set, else none. **Decision** on the order: a domain is more specific than a tenant. Exposed over JMAP so ihasmail can draw it (see "Interfaces"). Branding BT-1 and BT-2 (`branding-and-templates.md`) extend the chain past the tenant, to the server-wide logo and then the built-in one, and are the full rule. **Decision** (2026-09-18) on the shape: in the JMAP session, the principal's own account's `accountCapabilities` carry `urn:inbuxa:jmap` (contract C-1) with `logo`: a string (the URL or data URL as stored) or `null`. Until branding is built it follows this chain, steps 1 and 2 of BT-1. - **MT-23.** The server never fetches a logo URL itself. ihasmail draws URL logos through its image proxy, as it does today. ## Interfaces - **Existing, unchanged:** `x:Tenant/get`, `/set`, `/query`, `/changes`; the `memberTenantId` field on the types listed above; the permission names; the task and maintenance types; the event. - **New:** the signed-in principal's applicable logo (MT-22), as `logo` in the `urn:inbuxa:jmap` account capability of its own account in the JMAP session (contract C-1). - **Errors:** RFC 8620 `SetError` types, as named above. Each refusal names the property or limit involved, so ihasmail can say which one. ## ihasmail changes These go in the INBUXA fork of ihasmail, not public ihasmail, which stays Stalwart-facing (SPEC.md §5). - Drop the "Tenants are a Stalwart Enterprise feature" notice and the edition check in front of the Tenants page. Keep `SHOW_ENTERPRISE_NOTICES` for talking to upstream Stalwart. - Show the applicable logo (MT-22) in the app for the signed-in user. - Show `overQuota` and `limit.tenant-quota` refusals in plain words, naming the limit. - The domain-leaves-tenant guard it enforces today (MT-8) stays, and becomes a second line of defense rather than the only one. ## Acceptance tests Every test runs against inbuxa-server built with no Enterprise code. The ones marked **(compat)** also run against a copy of INBUXA's data. 1. Tenant admin in T lists accounts: sees only T's (MT-1). 2. Tenant admin in T gets a U account by id: `notFound`, not `forbidden`. **Decision**: don't confirm that another tenant's object exists. 3. Tenant admin adds a U account to a T group: `invalidForeignKey` (MT-3). **Decision** (2026-09-18): MT-3's error, not `forbidden` as this test first said. 4. Mail from a T address to a U address is delivered (MT-4). 5. Tenant admin sets `memberTenantId` on anything: refused (MT-6, MT-11). 6. Account created on a T domain is in T with no `memberTenantId` sent (MT-7). 7. Domain with T accounts moved out of T: refused (MT-8). 8. Tenant with one account deleted: `objectIsLinked` (MT-10). 9. User in T granted a permission T lacks: the permission has no effect (MT-13). 10. `Replace` with an enabled permission that's also disabled: not allowed (MT-14). 11. Lowering T's roles takes effect on the user's next request with no new sign-in (MT-16). 12. `maxAccounts` 2: the third account is refused `overQuota` and the event is emitted (MT-17). Lowering it to 1 keeps both existing accounts (MT-18). 13. `maxDiskQuota` reached across two accounts: delivery to a third member is refused (MT-19). 14. `recalculateQuota` after hand-corrupting `usedDiskQuota`: restored (MT-21). 15. **(compat)** INBUXA's existing tenants, their members and quotas read back unchanged, and each tenant admin sees exactly what it saw before. ## Observed Settled on 2026-09-18 against INBUXA's live Enterprise server (Stalwart 0.16.22), over JMAP and SMTP submission. The probes ran as a temporary server-level admin, and created two tenants, two domains under `ttlhost.com` with manual certificates, four accounts, three ACME providers pointed at Let's Encrypt staging, and two probe messages. Everything was deleted afterwards, and a sweep of every affected object type found nothing left. No upstream code was read. 1. **References across tenants.** A tenant's domain can't use an ACME provider in no tenant, or one in another tenant. Both are refused with `invalidForeignKey`, even when a server-level admin makes the change. A provider the tenant admin creates lands in its tenant and works. The tenant admin can't see server-level providers at all. 2. **Full tenant disk quota.** With usage at 1,191 bytes and a 1,200-byte limit, the next message wasn't delivered: the check is on what delivery would bring the total to. Local delivery answered `451 4.3.0 Organization over quota.` at `RCPT TO` (temporary). Submission was accepted, and the message stayed queued with a retry due in 2 minutes, a delay notice due after 1 day, and expiry after 3 days. Usage rose on the delivery itself. 3. **What a tenant admin can read.** Its tenant's accounts, domain, DKIM keys and its own ACME providers, roles, DNS providers and queue. It gets `forbidden` for listeners, certificates, system settings and every tenant object, its own included. Objects in no tenant or another tenant, fetched by id, come back in `notFound`. `memberTenantId` isn't returned to it. Its `Admin` role carried 290 permissions (server-level admin: 641). 4. **The queue.** Tenant 1's admin saw exactly the two queued messages addressed to its domain, both sent from tenant 2. It saw none of the other 23 entries in the server's queue. The sender side (a tenant admin seeing its own people's outgoing mail) wasn't tested: there was no admin in tenant 2. 5. **Directory search.** A tenant user's JMAP `Principal/query`, with and without a text filter, returned only its own tenant's two principals: not the other tenant's, and not the server-level accounts. 6. **Changes to a tenant's roles and permissions.** Setting tenant 1's `permissions` to `Replace` with nothing enabled, then its `roles` to an empty custom set, left its already-signed-in admin with all 290 permissions for 2.5 minutes. A new admin created during the change was refused everything, including its JMAP session (HTTP 403): the ceiling works, but permissions are cached per principal. After the roles were restored, the new admin was still refused 6.7 minutes later, when polling stopped. The cache lifetime wasn't measured. The `permissions` field on its own wasn't isolated from the `roles` field, because only cached principals saw that change. 7. **An account's tenant.** Creating accounts on a tenant's domain without `memberTenantId` put them in no tenant. Giving one a tenant other than its domain's was refused with `invalidForeignKey` naming the domain. The same happened for a no-tenant domain with a tenant set. 8. **A domain leaving its tenant.** Allowed while one of the tenant's accounts was on it. The account kept its tenant and could still sign in. 9. **DKIM.** Each new domain got two DKIM keys, each in the domain's tenant. Not yet settled: whether deleting a tenant that still holds objects is refused (the probe accounts were deleted first), and the sender side of 4. Both are low-risk to leave for implementation-time tests.