@zudojs/tenancy

OVERVIEW

Multi-tenancy means one running copy of your app serves several separate customers. Acme Corp and Globex both log in to the same servers and the same database, but neither may ever see the other's data. Each of those customers is a tenant.

That creates one question your code has to answer on every single request: which tenant is this? The answer might come from a signed login token, from the hostname (acme.example.com), from the URL path (/acme/orders), or from a header. Working that out is called tenant resolution.

@zudojs/tenancy does that resolution, checks the answer is trustworthy, and then makes it available to every function that runs afterwards, so your handlers and repositories do not have to pass a tenant ID down through every call.

Getting the answer wrong is not a crash — it is one customer quietly reading another's invoices. So this package is written to fail closed: when anything about the request is ambiguous or unverifiable, it throws or returns an error response instead of guessing.

INSTALLATION

Install the package. It pulls in @zudojs/errors, @zudojs/constants and @zudojs/middleware on its own. It needs Node 24 or newer.

The HTTP middleware plugs into the @zudojs/http pipeline without depending on it: it reads headers through request.getHeader(), or from a plain object or Map. Install @zudojs/http if you want its server; the middleware goes straight into a route's middleware list, as shown in HTTP middleware.

QUICK START

This is the whole loop in one file: store a tenant, read a tenant ID off a request, load the tenant, then run some code inside its context. No HTTP server needed — the resolver is handed a plain object with a getHeader function.

Two things to notice. The header said "Acme" but the resolved ID is "acme" — IDs are normalized. And nothing was passed into the callback: requireCurrentTenant() found the tenant on its own.

The header keeps the example short, but note the trust: "untrusted" in the result. Anyone can send x-tenant-id: acme, so on its own it proves nothing about which tenant the caller belongs to. In a real app, take the tenant from a verified token or from the host name (see Trust levels); the HTTP middleware refuses a header-only tenant by default.

TENANTS AND TENANT IDS

A tenant is a record describing one customer organization: an ID, a display name, an optional URL-friendly slug, a status, and a free-form metadata bag for things like the plan they are on.

The status matters. It is one of "provisioning", "active", "inactive", "suspended", "deleting" or "deleted". Only "active" tenants are served; everything else is refused by default.

A TenantId is not just a string. createTenantId normalizes the value (Unicode NFKC, trimmed, lowercased) and then checks it against ^[a-z0-9][a-z0-9_-]*$, up to 64 characters. Anything else throws InvalidTenantIdError.

Use tryCreateTenantId when a bad value simply means "found nothing", and isValidTenantId when you only want a yes or no.

Common mistake: casting a raw string to TenantId to get past the type checker. That skips the validation entirely — always go through createTenantId or tryCreateTenantId.

RESOLVING A TENANT

A resolver is a small object with one job: look at a request and say which tenant it is for. It returns a TenantResolution — the tenant ID, where the ID came from (source), and how much that source can be believed (trust) — or undefined if it found nothing.

Resolvers do not take a framework request object. They take a narrow accessor with just the function they need, so the same resolver works for HTTP requests, queue messages or tests.

Each one is called the same way. Here are all four against fake requests.

The subdomain resolver refuses www (change that with reserved), is case-insensitive, and will not turn a.b.example.com into a tenant called a.b unless you pass allowMultiLabel: true.

The JWT resolver does not verify the token. It reads claims that something upstream already verified, which is why it is graded trusted. If getClaims() throws — bad signature, expired token — that throw is meaningful; see the next section.

Common mistake: handing a resolver your framework's request object. It only knows about getHeader, getHost, getPath or getClaims, and will fail at runtime on anything else. On the HTTP path, createHttpResolverContext builds the accessor for you.

RESOLVER CHAINS

Most apps accept more than one way of naming a tenant. A chain holds several resolvers, sorts them by priority (highest first) and asks each in turn.

The chain's context type is inferred from its resolvers: it is the intersection of what they read, so a chain of a JWT and a header resolver needs both getClaims and getHeader, and TypeScript says so if you leave one out. chain.resolve(context) returns a TenantResolutionResult: the winning resolution, every candidate collected, and a conflict flag. chain.asResolver() hands you the chain packaged as a single resolver. Since 1.3.1 the HTTP middleware accepts the chain itself and does that for you.

What "fail closed" means

A system fails open when something goes wrong and it carries on anyway. It fails closed when something goes wrong and it stops. For a lock on a door, failing open means the door unlocks in a power cut. For tenancy, failing open means serving somebody else's data.

The chain draws a hard line between two different outcomes from a resolver:

• → Returned undefined — "I found nothing here." The chain moves on to the next resolver.
• → Threw — "I found a credential and it is bad." The chain stops and raises TenantResolutionError.

Conflicts

Two sources naming different tenants on one request is the signature of an attempted cross-tenant call. Set detectConflicts: true to run every resolver and compare, and the chain throws TenantResolutionConflictError. Conflict detection is off by default — a chain stops at the first resolver that finds a tenant. With it on, throwing is the default; pass throwOnConflict: false only if you have a good reason to let the highest-priority source win silently.

Common mistake: expecting conflict detection without asking for it. With detectConflicts off (the default) the chain stops at the first match, so there is nothing to compare and a conflict can never be seen.

TRUST LEVELS

Not every way of naming a tenant is equally believable. A tenant ID from a verified token is a fact; a tenant ID typed into a header by whoever sent the request is a suggestion. Every resolution carries one of three trust levels.

x-tenant-id is untrusted by default, because this package cannot know what sits in front of your app. If a proxy you control strips and re-sets that header at the edge, say so explicitly.

Common mistake: raising the header resolver to verified because a route stopped working. If a client can still send that header directly, you have just handed it the ability to choose its tenant.

TENANT CONTEXT

Once the tenant is known, every function underneath needs it. Passing it through every call is noisy and easy to forget. Instead the tenant is put into context: a value stored for the duration of one operation, which any code running inside that operation can read.

It is built on Node's AsyncLocalStorage, so the value survives await, callbacks and promise chains without you threading it anywhere.

createTenantContextStorage() is the store. createContextManager({ storage }) is the friendly API on top of it.

run refuses a tenant whose status is not "active", throwing TenantUnavailableError. That check is here, not only in HTTP middleware, because background jobs and scripts never pass through HTTP. Pass allowInactive: true to the manager when a job exists precisely to handle suspended tenants.

For work that belongs to no tenant — migrations, a health check, a cross-tenant report — use runSystem. Inside it getCurrentTenant() is undefined and isSystemMode() is true.

Common mistake: creating a second createTenantContextStorage() for one part of the app. Two stores do not see each other's contexts. Create one and share it — or use getDefaultStorage(), which returns a shared instance.

STORING TENANTS

A resolver gives you an ID. Something has to turn that ID into the full tenant record. That something is a repository — an object with findById, and optionally findBySlug and findByDomain.

createMemoryTenantRepository() ships in the box. It keeps tenants in a Map, so it is right for tests and small apps; for production you implement TenantRepository against your database.

The second argument to add registers custom domains. Calling add again for the same tenant rebuilds its slug and domain indexes, so an old slug stops resolving instead of quietly serving the record from before the update. The resolve middleware looks a subdomain or path value up by id, then by slug (slugLookup, default true).

Tenant manager

createTenantManager wraps a repository with an optional cache and a few assertions. Cached records expire after cacheTtlMs (30 seconds by default), which bounds how long a tenant you just suspended keeps being served. Set it to 0 to turn caching off, and call invalidate(id) right after any write that changes a status.

Common mistake: caching tenants forever. A suspended customer keeps being served until the entry expires, so keep the TTL short and invalidate on write.

HTTP MIDDLEWARE

Middleware is a function that runs before your route handler and can either pass the request on or answer it itself. createResolveTenantMiddleware is the one that turns a request into a tenant context.

On every request it does five things in order, and stops at the first that fails:

• 1. Builds a resolver accessor from the request and runs your resolver. No resolution → 404.
• 2. Checks the resolution's trust against minimumTrust (default "verified"). Too low → 403.
• 3. Loads the tenant from the repository. Not found → 404, with the same body as step 1, so the route cannot be used to probe which tenants exist.
• 4. Refuses a non-active tenant with the same 404 as an unknown one, unless allowInactive is set.
• 5. Puts the tenant in request state and runs the rest of the request inside the tenant context.

Register resolveTenant before requireTenant, and both before your routes. By default (minimumTrust: "verified") a tenant named only by an untrusted header or a URL path is refused with 403; pass minimumTrust: "untrusted" to opt down.

The refusals are real HTTP responses. Every tenancy middleware answers with a guard response built by createGuardResponse from @zudojs/middleware, which @zudojs/http sends with its status, headers and JSON body. Tested against a real server: an unknown host answered 404, a header-only tenant (with a header resolver in the chain) 403, and requireTenant with no tenant 401, each as application/json.

Where JWT claims come from

The middleware does not verify tokens. It reads already-verified claims from request state under the key TENANT_CLAIMS_STATE_KEY ("tenancy:claims"). Your authentication middleware publishes them there, or you supply a getClaims function.

Downstream, read the tenant out of state with TENANT_STATE_KEY and the resolution details with TENANT_CONTEXT_STATE_KEY. createTenantGuardMiddleware re-checks the status, and createTenantPropagationMiddleware restores the context from state when a later stage needs it.

Common mistake: installing requireTenant without resolveTenant. Nothing ever puts a tenant in state, so every request gets a 401.

KEY ISOLATION

Knowing the tenant is only half the job. The other half is making sure the things you store under that tenant cannot be reached by another one. Two helpers build keys that stay apart.

That escaping is the point. Tenant IDs are already restricted, but the second argument is not: without escaping, key "cache:k" under tenant a would produce the same string as key "k" under a tenant called a:cache.

For caching, pass the tenant as the namespace rather than building keys by hand — see @zudojs/cache, whose namespace option and createKeyBuilder keep one tenant's entries out of another's.

For rows you have already loaded, assertTenantOwnership is the last line of defence: it throws TenantIsolationError when a record does not belong to the tenant you expect.

API REFERENCE

Identity

Resolution

Context

Storage

Security

HTTP

Utilities

Errors

All extend TenantError, which extends AuthorizationError from @zudojs/errors.

COMMON MISTAKES

• Trusting x-tenant-id. Any client can send that header. If you accept it, a caller picks its own tenant. Fix: leave its trust at untrusted; the resolve middleware's default minimumTrust: "verified" refuses it. Raise its trust only if a proxy you control rewrites the header at the edge.

• Swallowing a resolver's throw. Wrapping getClaims in your own try/catch that returns undefined turns "this credential is forged" into "found nothing", and the chain falls through to a weaker source. Fix: let it throw.

• Using two context storages. Middleware writes to one, your service reads the other, and requireCurrentTenant() throws on every request. Fix: create the storage once and pass the same instance everywhere.

• Reading the tenant after the callback ends. Context only exists inside run. A promise started inside and awaited outside sees nothing. Fix: await the work inside the callback.

• Building keys by concatenation. `${tenantId}:${key}` lets a crafted key cross into another namespace. Fix: use tenantKey or createTenantCacheKey, which escape the segments.

• Forgetting background jobs. HTTP middleware never runs for a queue worker or a cron script. Fix: wrap the job body in contextManager.run(tenant, callback), which applies the same active-status check.

RELATED PACKAGES

• @zudojs/cache — pass the tenant as a cache namespace so one tenant's entries can never be read under another's key.
• @zudojs/http — the server the tenancy middleware plugs into. Not a dependency; the middleware plugs in structurally.
• @zudojs/auth — verifies the token whose claims the JWT resolver reads.
• @zudojs/errors — the AuthorizationError base and the error codes these errors carry.
• @zudojs/permissions — decides what a user may do within the tenant that tenancy established.

COMPLETE EXPORT INDEX

Every name @zudojs/tenancy exports from its package root at v1.2.1 — 95 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.