Hand-off: build multi-tenancy

Status: ready, 2026-09-18. For the implementer of feature 1 in SPEC.md §4.

This brief is everything an implementer needs besides the repository. The spec it builds from is docs/spec/features/multi-tenancy.md, committed before any implementation (SPEC.md §3, rule 3). Read that first, then this.

Who may do this

SPEC.md §3, rule 2: the implementer must never have read Stalwart Enterprise-only code. For an AI session that means a new session, with no access to the one that wrote the specs. That session had seen Enterprise snippets.

Start it in /run/media/john/PROJECTS/inbuxa-server, not in the parent folder, so it doesn't load the spec session's memory.

What the implementer may read

This repository, all of it. Every file is AGPL: the strip step removed everything Enterprise-only before the code was committed, and upstream's git history was never imported (SPEC.md §2.2a).
docs/spec/: the specs, the contract, this brief.
RFCs and IETF drafts.
The running behavior of a server built from this repository.

What the implementer must not read

Any checkout, archive, fork or web view of stalwartlabs/stalwart (any branch, tag or commit). Upstream's own files still carry the Enterprise snippets inline.
Any folder holding an upstream checkout or a strip work tree. That includes every …/scratchpad/stalwart and …/scratchpad/strip-* under /tmp/claude-1000/.
Transcripts of other sessions, under ~/.claude/projects/.
Stalwart Enterprise binaries, and the license portal.
INBUXA's production server. Its behavior is already recorded in the spec's "Observed" section. Build against the spec and local test servers.

If the implementer reaches a question the spec doesn't answer, they stop and ask. The answer goes into the spec as a Decision and is committed before the code that depends on it. They never go looking for how upstream does it.

What exists today

Data model: complete. The stripped build keeps every tenancy object and field: x:Tenant, TenantStorageQuota, memberTenantId on every type the spec lists, Authentication.defaultTenantRoleIds, the TenantMaintenance task, the resetTenantQuotas maintenance type, the limit.tenant-quota event and the permission names. They live in the generated registry code (crates/registry/src/schema/) and resources/schema/schema.json.gz. At first boot, x:Tenant/query answered an empty list.
Behavior: missing or partial. Upstream's enforcement was Enterprise-only, and the strip step removed it. Some checks may survive in shared code; the foreign-key checks, for example, are general-purpose. Nobody has measured what's left. Test each requirement against the spec, and treat any tenancy behavior you find as a starting point to check, not as the reference.
Signposts. rg "inbuxa:" lists the hooks left for rebuilding. The two for tenancy:
- crates/common/src/auth/permissions.rs: the tenant permission ceiling (MT-13).
- crates/common/src/lib.rs: the logo lookup (MT-22).

Where code was removed. docs/fork/strip-reports/v0.16.22.json lists, file by file, how many Enterprise snippets were taken out. It gives locations, not code. For tenancy, the surrounding AGPL code in these files shows the seams:

Area	Files
Principals and access	`crates/common/src/auth/{authentication,mod,permissions}.rs`, `crates/common/src/cache/{principals,directory,invalidate}.rs`
JMAP registry	`crates/jmap/src/registry/{get,query,set}.rs`
JMAP mappings	`crates/jmap/src/registry/mapping/{principal,queued_message,task}.rs`
HTTP permissions	`crates/http/src/auth/permissions.rs`
Quotas	`crates/common/src/storage/quota.rs`
Tasks	`crates/services/src/task_manager/maintenance.rs`

Not every snippet in those files is about tenancy. Some belong to other features.

Tests. The integration suite (tests/) gates Enterprise tests behind the pending-rebuild Cargo feature. tests/src/system/mod.rs still calls tenant::test, but upstream's tenant.rs was Enterprise-only and is gone. Its mod tenant; declaration went with it. Write a new tests/src/system/tenant.rs from the spec's acceptance tests, declare the module again, and remove the gate on the call when it passes.

Where the code goes

SPEC.md §2.3: rebuilt features live in one new crate of the fork's own, crates/features (package inbuxa-features). License it AGPL-3.0-only, with the header used in crates/types/src/branding.rs. Keep upstream files' changes to the smallest hooks that call into it. Mark each hook with an inbuxa: comment naming the requirement (// inbuxa: MT-13). The crate is where later features go too, one module each: masked email, undelete and the rest.

Pick the smallest hook that works over restructuring an upstream file. Every upstream re-import merges into these files, so small hooks mean small conflicts.

What "done" means

Every requirement MT-1 to MT-23 is implemented, or deliberately deferred with a line in the spec saying so. The branding and quota warnings for ihasmail can wait for ihasmail-inbuxa.
Acceptance tests 1 to 14 pass as integration tests (tests/src/system/tenant.rs), with the pending-rebuild gate removed from the tenant call.
Test 15 (compat, INBUXA's own data) needs a copy of production data from John. Write it so it can run against a data directory, and leave it unrun until he provides one.
The whole workspace builds, and every unit test and every non-gated integration test that passed before still passes.
A local end-to-end check: a first boot of the debug binary with two tenants, their admins and users, and mail between them. Use the container recipe in "Working rules".

Working rules

Commits: plain messages, no AI attribution, no co-author trailers and no session links. Each names the requirement IDs it implements. Commit to main in small steps. This repository is local only and has no remote.
Builds go to the repository's target/ with CARGO_TARGET_DIR=target TMPDIR=$PWD/target/tmp. /tmp is a 46 GB tmpfs, and a full build fills it.
http is ambiguous for cargo -p. Use -p [email protected].
Local server: run target/debug/inbuxa in a container, with the stalwartlabs/stalwart:v0.16.22 image as a Debian runtime only:
```
docker run -d --name inbuxa-dev --entrypoint /usr/local/bin/inbuxa \
  -v $PWD/target/debug/inbuxa:/usr/local/bin/inbuxa:ro \
  -v $DIR/etc:/etc/inbuxa -v $DIR/data:/var/lib/inbuxa \
  -e INBUXA_RECOVERY_ADMIN=admin:<password> \
  -p 127.0.0.1:18080:8080 stalwartlabs/stalwart:v0.16.22 \
  --config /etc/inbuxa/config.json
```
An empty etc starts it in bootstrap mode. x:Bootstrap/set over JMAP (serverHostname, defaultDomain, requestTlsCertificate: false) returns the permanent admin. Restart it without the recovery admin variable, then create tenants, domains and accounts over JMAP (x:Tenant, x:Domain, x:Account with @type: User). Delete the container and its folders afterwards.
Never print or commit a password. Generate test passwords, keep them in files under target/, and remove them along with the test server.
Don't touch INBUXA's production server or anything on the hosts. This work is local.

Starting prompt

For the new session, pasted as its first message:

You're implementing multi-tenancy in inbuxa-server, the local AGPL fork of Stalwart in this folder. Read docs/spec/handoff/multi-tenancy.md and follow it exactly, starting with its clean-room rules, then docs/spec/features/multi-tenancy.md. Don't read anything the brief rules out. If the spec doesn't answer something, stop and ask me.

7.7 KiB Raw Permalink Blame History