@zudojs/tenancy 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zudojs Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # @zudojs/tenancy
 
-Multi-tenant context and isolation with tenant resolution, AsyncLocalStorage propagation, resolver chains, trust levels, and guard middleware.
+Multi-tenant context and isolation: tenant resolution, context propagation, resolver chains, and guard middleware.
 
 ## Installation
 
@@ -11,26 +11,77 @@ npm install @zudojs/tenancy
 ## Quick Start
 
 ```typescript
-import { createTenantContextManager } from "@zudojs/tenancy";
+import {
+  createJwtResolver,
+  createMemoryTenantRepository,
+  createResolveTenantMiddleware,
+  createResolverChain,
+  createSubdomainResolver,
+  createTenantContextStorage,
+} from "@zudojs/tenancy";
 
-const manager = createTenantContextManager({
-  resolvers: [headerResolver, subdomainResolver, jwtResolver],
+const storage = createTenantContextStorage();
+const repository = createMemoryTenantRepository();
+
+const resolver = createResolverChain([
+  createJwtResolver(), // priority 100, trusted
+  createSubdomainResolver({ baseDomain: "example.com" }), // priority 70
+]);
+
+// Resolves the tenant, enforces its status and the route's trust floor,
+// then runs the rest of the request inside the tenant context.
+const middleware = createResolveTenantMiddleware({
+  resolver: resolver.asResolver(),
+  repository,
+  storage,
+  minimumTrust: "verified",
 });
+```
+
+Read the current tenant anywhere downstream:
+
+```typescript
+import { createContextManager } from "@zudojs/tenancy";
 
-const tenant = await manager.resolve(request);
+const context = createContextManager({ storage });
+const tenant = context.requireCurrentTenant();
 ```
 
+## Resolution Trust
+
+| Source                | Default trust | Note                        |
+| --------------------- | ------------- | --------------------------- |
+| `jwt`, `api-key`      | `trusted`     | verified credential         |
+| `subdomain`, `domain` | `verified`    | host-derived                |
+| `header`, `path`      | `untrusted`   | client-supplied on the wire |
+
+`x-tenant-id` is untrusted by default. Raise it with
+`createHeaderResolver({ trust: "verified" })` only where a trusted proxy
+strips and re-sets the header at the edge.
+
 ## Features
 
-- Tenant resolution from headers, subdomains, JWT, or custom resolvers
+- Tenant resolution from JWT claims, subdomain, custom domain, header, or path
+- Resolver chains with trust grading and conflict detection
 - AsyncLocalStorage context propagation
-- Tenant isolation and data scoping
-- Trust levels (trusted, untrusted, isolated)
-- Guard middleware for route protection
+- Tenant repository with slug and custom-domain indexes
+- Guard middleware and key scoping helpers
+
+## Safety Notes
+
+- A resolver that **throws** rejected a credential, and aborts the chain. Only
+  returning `undefined` means "found nothing" and advances to the next
+  resolver — so a failed JWT verification can never fall through to a
+  client-supplied header.
+- Resolvers disagreeing about the tenant throws by default.
+- Tenant ids are normalized (NFKC, trimmed, lowercased) and constrained to
+  `^[a-z0-9][a-z0-9_-]*$`, so an id cannot forge a separator in a cache key,
+  a schema name, or a path. `tenantKey` escapes its segments as well.
+- Non-active tenants are refused during resolution. Pass `allowInactive` on
+  routes that exist to serve suspended tenants.
 
 ## Use Cases
 
-- SaaS multi-tenant applications
-- Data isolation per tenant
-- Tenant-aware routing
-- Compliance and data separation
+- SaaS multi-tenancy
+- Per-tenant data isolation
+- Tenant-scoped caching and configuration

package/dist/context/contextManager.core.d.ts

@@ -9,6 +9,13 @@ import type { ExecutionTenantContext } from "../tenancyTypes/tenantInterface.js"
 /** Options for the context manager. */
 export interface ContextManagerOptions {
     readonly storage: TenantContextStorage;
+    /**
+     * Allow entering a context for a non-active tenant. Defaults to false.
+     *
+     * This is the entry point for background jobs and scripts, where no HTTP
+     * guard runs, so a suspended tenant is refused unless explicitly permitted.
+     */
+    readonly allowInactive?: boolean;
 }
 /**
  * Create a tenant context manager.
@@ -32,6 +39,9 @@ export declare function createContextManager(options: ContextManagerOptions): {
     isSystemMode(): boolean;
     /**
      * Run a callback within a tenant context.
+     *
+     * @throws {TenantUnavailableError} when the tenant is not active and
+     *   `allowInactive` was not set.
      */
     run<T>(tenant: Tenant, callback: () => T): T;
     /**

package/dist/context/contextManager.core.js

@@ -4,11 +4,13 @@
  * @module context/contextManager
  */
 import { TenantContextMissingError } from "../tenancyErrors/tenancyError.types.js";
+import { assertTenantUsable } from "../security/guard.core.js";
 /**
  * Create a tenant context manager.
  */
 export function createContextManager(options) {
     const { storage } = options;
+    const allowInactive = options.allowInactive ?? false;
     return {
         /**
          * Get the current execution context.
@@ -43,8 +45,13 @@ export function createContextManager(options) {
         },
         /**
          * Run a callback within a tenant context.
+         *
+         * @throws {TenantUnavailableError} when the tenant is not active and
+         *   `allowInactive` was not set.
          */
         run(tenant, callback) {
+            if (!allowInactive)
+                assertTenantUsable(tenant);
             const context = {
                 mode: "tenant",
                 tenant,

package/dist/http/httpResolverContext.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Adapts an HTTP middleware context to the shape tenant resolvers expect.
+ *
+ * Resolvers take a narrow accessor object rather than a framework request, so
+ * they can be reused off the HTTP path. The middleware is what bridges the
+ * two; without this, passing the raw context type-checks (the resolver's
+ * context parameter defaults to `unknown`) and fails on the first request.
+ *
+ * @module http/httpResolverContext
+ */
+import type { HttpMiddlewareContext } from "./httpTypes.js";
+/** Claims extracted from a verified token. */
+export interface TenantClaims {
+    readonly [key: string]: unknown;
+}
+/** Everything the resolvers shipped with this package read from a request. */
+export interface HttpResolverContext {
+    getHeader(name: string): string | undefined;
+    getHost(): string | undefined;
+    getPath(): string | undefined;
+    getClaims(): TenantClaims | undefined;
+}
+/** State key under which upstream auth middleware publishes token claims. */
+export declare const TENANT_CLAIMS_STATE_KEY = "tenancy:claims";
+/**
+ * Build a resolver context from an HTTP middleware context.
+ *
+ * @param context - The framework request context.
+ * @param getClaims - Optional override for reading verified token claims.
+ *   Defaults to reading `tenancy:claims` from middleware state, which is where
+ *   an authentication middleware is expected to publish them.
+ * @returns An accessor object every shipped resolver understands.
+ */
+export declare function createHttpResolverContext(context: HttpMiddlewareContext, getClaims?: (context: HttpMiddlewareContext) => TenantClaims | undefined): HttpResolverContext;
+//# sourceMappingURL=httpResolverContext.d.ts.map

package/dist/http/httpResolverContext.js

@@ -0,0 +1,40 @@
+/**
+ * Adapts an HTTP middleware context to the shape tenant resolvers expect.
+ *
+ * Resolvers take a narrow accessor object rather than a framework request, so
+ * they can be reused off the HTTP path. The middleware is what bridges the
+ * two; without this, passing the raw context type-checks (the resolver's
+ * context parameter defaults to `unknown`) and fails on the first request.
+ *
+ * @module http/httpResolverContext
+ */
+/** State key under which upstream auth middleware publishes token claims. */
+export const TENANT_CLAIMS_STATE_KEY = "tenancy:claims";
+/**
+ * Build a resolver context from an HTTP middleware context.
+ *
+ * @param context - The framework request context.
+ * @param getClaims - Optional override for reading verified token claims.
+ *   Defaults to reading `tenancy:claims` from middleware state, which is where
+ *   an authentication middleware is expected to publish them.
+ * @returns An accessor object every shipped resolver understands.
+ */
+export function createHttpResolverContext(context, getClaims) {
+    return {
+        getHeader(name) {
+            return context.request.headers.get(name.toLowerCase());
+        },
+        getHost() {
+            return context.request.headers.get("host");
+        },
+        getPath() {
+            return context.request.path;
+        },
+        getClaims() {
+            if (getClaims)
+                return getClaims(context);
+            return context.state.get(TENANT_CLAIMS_STATE_KEY);
+        },
+    };
+}
+//# sourceMappingURL=httpResolverContext.js.map

package/dist/http/index.d.ts

@@ -1,12 +1,12 @@
 /**
- * HTTP middleware adapter barrel.
- *
- * @module http
+ * @zudojs/tenancy — HTTP Barrel
  */
-export type { HttpMiddleware, HttpMiddlewareContext } from "./httpTypes.js";
-export type { ResolveTenantMiddlewareOptions, RequireTenantMiddlewareOptions, } from "./tenancyMiddleware.core.js";
-export { TENANT_STATE_KEY, TENANT_CONTEXT_STATE_KEY, createResolveTenantMiddleware, createRequireTenantMiddleware, } from "./tenancyMiddleware.core.js";
-export type { TenantGuardMiddlewareOptions } from "./tenancyMiddleware.guard.js";
+export { TENANT_CONTEXT_STATE_KEY, TENANT_STATE_KEY, createRequireTenantMiddleware, createResolveTenantMiddleware, } from "./tenancyMiddleware.core.js";
+export type { RequireTenantMiddlewareOptions, ResolveTenantMiddlewareOptions, } from "./tenancyMiddleware.core.js";
 export { createTenantGuardMiddleware, createTenantPropagationMiddleware, } from "./tenancyMiddleware.guard.js";
-export { createForbidden, createNotFound } from "./httpHelpers.js";
+export type { TenantGuardMiddlewareOptions } from "./tenancyMiddleware.guard.js";
+export { TENANT_CLAIMS_STATE_KEY, createHttpResolverContext, } from "./httpResolverContext.js";
+export type { HttpResolverContext, TenantClaims, } from "./httpResolverContext.js";
+export { createBadRequest, createForbidden, createJsonErrorResponse, createNotFound, createUnauthorized, } from "./httpHelpers.js";
+export type * from "./httpTypes.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -1,9 +1,8 @@
 /**
- * HTTP middleware adapter barrel.
- *
- * @module http
+ * @zudojs/tenancy — HTTP Barrel
  */
-export { TENANT_STATE_KEY, TENANT_CONTEXT_STATE_KEY, createResolveTenantMiddleware, createRequireTenantMiddleware, } from "./tenancyMiddleware.core.js";
+export { TENANT_CONTEXT_STATE_KEY, TENANT_STATE_KEY, createRequireTenantMiddleware, createResolveTenantMiddleware, } from "./tenancyMiddleware.core.js";
 export { createTenantGuardMiddleware, createTenantPropagationMiddleware, } from "./tenancyMiddleware.guard.js";
-export { createForbidden, createNotFound } from "./httpHelpers.js";
+export { TENANT_CLAIMS_STATE_KEY, createHttpResolverContext, } from "./httpResolverContext.js";
+export { createBadRequest, createForbidden, createJsonErrorResponse, createNotFound, createUnauthorized, } from "./httpHelpers.js";
 //# sourceMappingURL=index.js.map

package/dist/http/tenancyMiddleware.core.d.ts

@@ -7,11 +7,12 @@
  *
  * Requires @zudojs/http as a peer dependency.
  */
-import type { Tenant, TenantRequirement } from "../tenancyTypes/tenantInterface.js";
+import type { Tenant, TenantRequirement, TenantTrustLevel } from "../tenancyTypes/tenantInterface.js";
 import type { TenantResolver, TenantResolution } from "../tenancyTypes/resolverTypes.js";
 import type { TenantRepository } from "../tenancyTypes/repositoryTypes.js";
 import type { TenantContextStorage } from "../context/contextStorage.core.js";
-import type { HttpMiddleware } from "./httpTypes.js";
+import type { HttpMiddleware, HttpMiddlewareContext } from "./httpTypes.js";
+import type { HttpResolverContext, TenantClaims } from "./httpResolverContext.js";
 /** State key for the resolved tenant. */
 export declare const TENANT_STATE_KEY = "tenancy:tenant";
 /** State key for the tenant context. */
@@ -19,11 +20,27 @@ export declare const TENANT_CONTEXT_STATE_KEY = "tenancy:context";
 /** Options for the resolve tenant middleware. */
 export interface ResolveTenantMiddlewareOptions {
     /** Resolver chain or single resolver to determine tenant. */
-    readonly resolver: TenantResolver;
+    readonly resolver: TenantResolver<HttpResolverContext>;
     /** Repository to load the full tenant after resolution. */
     readonly repository: TenantRepository;
     /** Tenant context storage for propagation. */
     readonly storage: TenantContextStorage;
+    /**
+     * Minimum trust the resolution must carry. Defaults to `untrusted`.
+     *
+     * Set this on any route where a tenant resolved from a URL path or an
+     * unverified header must not be honoured.
+     */
+    readonly minimumTrust?: TenantTrustLevel;
+    /**
+     * Whether a non-active tenant may proceed. Defaults to false.
+     *
+     * Enable only for routes that exist to serve suspended tenants, such as
+     * billing or reactivation.
+     */
+    readonly allowInactive?: boolean;
+    /** Reads verified token claims for the JWT resolver. */
+    readonly getClaims?: (context: HttpMiddlewareContext) => TenantClaims | undefined;
     /** Custom error response for missing tenant. */
     readonly notFoundResponse?: (resolution: TenantResolution | undefined) => unknown;
 }
@@ -37,6 +54,9 @@ export interface RequireTenantMiddlewareOptions {
 /**
  * Create middleware that resolves the tenant from the request
  * and creates a tenant context.
+ *
+ * Enforces trust and tenant status itself rather than relying on a second
+ * middleware being installed: the safe behaviour has to be the default.
  */
 export declare function createResolveTenantMiddleware(options: ResolveTenantMiddlewareOptions): HttpMiddleware;
 /**

package/dist/http/tenancyMiddleware.core.js

@@ -7,7 +7,10 @@
  *
  * Requires @zudojs/http as a peer dependency.
  */
-import { createForbidden } from "./httpHelpers.js";
+import { createHttpResolverContext } from "./httpResolverContext.js";
+import { createBadRequest, createForbidden, createNotFound, createUnauthorized, } from "./httpHelpers.js";
+import { meetsTrustLevel } from "../security/guard.core.js";
+import { TenantResolutionConflictError, TenantResolutionError, } from "../tenancyErrors/tenancyError.types.js";
 // ─── State Keys ───────────────────────────────────────────────────────────
 /** State key for the resolved tenant. */
 export const TENANT_STATE_KEY = "tenancy:tenant";
@@ -17,30 +20,54 @@ export const TENANT_CONTEXT_STATE_KEY = "tenancy:context";
 /**
  * Create middleware that resolves the tenant from the request
  * and creates a tenant context.
+ *
+ * Enforces trust and tenant status itself rather than relying on a second
+ * middleware being installed: the safe behaviour has to be the default.
  */
 export function createResolveTenantMiddleware(options) {
+    const minimumTrust = options.minimumTrust ?? "untrusted";
     return async (context, next) => {
-        const resolution = await options.resolver.resolve(context);
+        let resolution;
+        try {
+            resolution = await options.resolver.resolve(createHttpResolverContext(context, options.getClaims));
+        }
+        catch (error) {
+            // A resolver chain throws when a credential was rejected or when two
+            // sources name different tenants. Letting that escape produced a 500
+            // carrying the framework's own error text; both cases are a refusal
+            // the caller caused, and neither may fall through to `next()`.
+            if (error instanceof TenantResolutionConflictError) {
+                return createForbidden("Tenant could not be established: request sources name different tenants");
+            }
+            if (error instanceof TenantResolutionError) {
+                return createBadRequest("Tenant could not be resolved for this request");
+            }
+            throw error;
+        }
         if (!resolution) {
-            const body = options.notFoundResponse?.(resolution) ?? {
-                error: "Tenant not found",
-            };
-            return {
-                status: 404,
-                body,
-                headers: { "content-type": "application/json" },
-            };
+            return options.notFoundResponse
+                ? {
+                    status: 404,
+                    body: options.notFoundResponse(resolution),
+                    headers: { "content-type": "application/json" },
+                }
+                : createNotFound("Tenant not found");
+        }
+        if (!meetsTrustLevel(resolution.trust, minimumTrust)) {
+            return createForbidden("Tenant could not be established for this route");
         }
         const tenant = await options.repository.findById(resolution.tenantId);
         if (!tenant) {
-            const body = options.notFoundResponse?.(resolution) ?? {
-                error: `Tenant "${resolution.tenantId}" not found`,
-            };
-            return {
-                status: 404,
-                body,
-                headers: { "content-type": "application/json" },
-            };
+            return options.notFoundResponse
+                ? {
+                    status: 404,
+                    body: options.notFoundResponse(resolution),
+                    headers: { "content-type": "application/json" },
+                }
+                : createNotFound("Tenant not found");
+        }
+        if (!options.allowInactive && tenant.status !== "active") {
+            return createForbidden("Tenant is not available");
         }
         const tenantContext = {
             tenantId: tenant.id,
@@ -51,11 +78,7 @@ export function createResolveTenantMiddleware(options) {
         };
         context.state.set(TENANT_STATE_KEY, tenant);
         context.state.set(TENANT_CONTEXT_STATE_KEY, tenantContext);
-        return options.storage.run({
-            mode: "tenant",
-            tenant,
-            context: tenantContext,
-        }, () => next());
+        return options.storage.run({ mode: "tenant", tenant, context: tenantContext }, () => next());
     };
 }
 /**
@@ -66,26 +89,23 @@ export function createResolveTenantMiddleware(options) {
 export function createRequireTenantMiddleware(options) {
     const requirement = options?.requirement ?? "required";
     return async (context, next) => {
+        const tenant = context.state.get(TENANT_STATE_KEY);
         if (requirement === "forbidden") {
-            const tenant = context.state.get(TENANT_STATE_KEY);
             if (tenant) {
                 return createForbidden("Tenant context is not allowed for this route");
             }
             return next();
         }
-        if (requirement === "optional") {
+        if (requirement === "optional")
             return next();
-        }
-        const tenant = context.state.get(TENANT_STATE_KEY);
         if (!tenant) {
-            const body = options?.deniedResponse?.(undefined) ?? {
-                error: "Tenant context is required",
-            };
-            return {
-                status: 401,
-                body,
-                headers: { "content-type": "application/json" },
-            };
+            return options?.deniedResponse
+                ? {
+                    status: 401,
+                    body: options.deniedResponse(undefined),
+                    headers: { "content-type": "application/json" },
+                }
+                : createUnauthorized("Tenant context is required");
         }
         return next();
     };

package/dist/http/tenancyMiddleware.guard.d.ts

@@ -8,17 +8,25 @@ import type { TenantContextStorage } from "../context/contextStorage.core.js";
 import type { HttpMiddleware } from "./httpTypes.js";
 /** Options for the tenant guard middleware. */
 export interface TenantGuardMiddlewareOptions {
-    /** Tenant context storage. */
-    readonly storage: TenantContextStorage;
-    /** Repository to validate the tenant. */
-    readonly repository: TenantRepository;
+    /**
+     * Repository consulted for the tenant's current status.
+     *
+     * Optional. Supplied, the guard re-reads the tenant rather than trusting
+     * the copy an earlier middleware placed in request state — which is what
+     * lets a tenant suspended mid-request be refused. Omitted, the guard checks
+     * the state copy only.
+     *
+     * The previous shape required this field and a `storage` field, and read
+     * neither.
+     */
+    readonly repository?: TenantRepository;
 }
 /**
  * Create middleware that validates tenant status.
  *
  * Ensures the resolved tenant is active before proceeding.
  */
-export declare function createTenantGuardMiddleware(options: TenantGuardMiddlewareOptions): HttpMiddleware;
+export declare function createTenantGuardMiddleware(options?: TenantGuardMiddlewareOptions): HttpMiddleware;
 /**
  * Create middleware that propagates tenant context from state
  * into AsyncLocalStorage for downstream handlers.

package/dist/http/tenancyMiddleware.guard.js

@@ -11,13 +11,21 @@ import { TENANT_STATE_KEY, TENANT_CONTEXT_STATE_KEY, } from "./tenancyMiddleware
  *
  * Ensures the resolved tenant is active before proceeding.
  */
-export function createTenantGuardMiddleware(options) {
+export function createTenantGuardMiddleware(options = {}) {
     return async (context, next) => {
         const tenant = context.state.get(TENANT_STATE_KEY);
         if (!tenant)
             return next();
-        if (tenant.status !== "active") {
-            return createForbidden(`Tenant "${tenant.id}" is not available (status: ${tenant.status})`);
+        // A tenant that disappeared between resolution and this check must be
+        // refused, not waved through on the stale state copy.
+        const current = options.repository
+            ? await options.repository.findById(tenant.id)
+            : tenant;
+        if (!current) {
+            return createForbidden(`Tenant "${tenant.id}" is no longer available`);
+        }
+        if (current.status !== "active") {
+            return createForbidden(`Tenant "${current.id}" is not available (status: ${current.status})`);
         }
         return next();
     };

package/dist/repository/index.d.ts

@@ -4,5 +4,6 @@
  * @module repository
  */
 export { createMemoryTenantRepository, createDomainRegistry, } from "./repository.core.js";
-export { createTenantManager, type TenantManagerOptions, } from "./tenantManager.core.js";
+export type { MemoryTenantRepository, TenantWithDomains, } from "./repository.core.js";
+export { DEFAULT_TENANT_CACHE_TTL_MS, createTenantManager, type TenantManagerOptions, } from "./tenantManager.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/repository/index.js

@@ -4,5 +4,5 @@
  * @module repository
  */
 export { createMemoryTenantRepository, createDomainRegistry, } from "./repository.core.js";
-export { createTenantManager, } from "./tenantManager.core.js";
+export { DEFAULT_TENANT_CACHE_TTL_MS, createTenantManager, } from "./tenantManager.core.js";
 //# sourceMappingURL=index.js.map

package/dist/repository/repository.core.d.ts

@@ -5,20 +5,51 @@
  */
 import type { TenantId } from "../tenancyTypes/tenantIdentity.js";
 import type { Tenant } from "../tenancyTypes/tenantInterface.js";
-import type { TenantRepository } from "../tenancyTypes/repositoryTypes.js";
-import type { TenantDomain } from "../tenancyTypes/tenancyOptions.js";
+import type { TenantDomain, TenantRepository } from "../tenancyTypes/repositoryTypes.js";
+/** A tenant plus the custom domains that resolve to it. */
+export interface TenantWithDomains {
+    readonly tenant: Tenant;
+    readonly domains?: readonly string[];
+}
+/** The in-memory repository plus its write surface. */
+export interface MemoryTenantRepository extends TenantRepository {
+    /** Look a tenant up by its slug. Always present on this implementation. */
+    findBySlug(slug: string): Promise<Tenant | undefined>;
+    /** Look a tenant up by a registered custom domain. */
+    findByDomain(domain: string): Promise<Tenant | undefined>;
+    /**
+     * Insert or replace a tenant, re-indexing its slug and domains.
+     *
+     * @throws {TenantAlreadyExistsError} when the slug or one of the domains is
+     *   already indexed to a different tenant.
+     */
+    add(tenant: Tenant, domains?: readonly string[]): void;
+    /** Remove a tenant and every index entry pointing at it. */
+    remove(id: TenantId): void;
+    /** Every tenant currently stored. */
+    all(): readonly Tenant[];
+    /** Domains mapped to the given tenant. */
+    domainsOf(id: TenantId): readonly string[];
+}
 /**
  * Create an in-memory tenant repository.
+ *
+ * Secondary indexes are rebuilt on every write. A tenant whose slug or domain
+ * changed must not stay reachable under its previous one: the stale entry
+ * would keep serving the pre-update record, including its pre-suspension
+ * status.
  */
-export declare function createMemoryTenantRepository(): TenantRepository & {
-    add(tenant: Tenant): void;
-    remove(id: TenantId): void;
-    all(): readonly Tenant[];
-};
+export declare function createMemoryTenantRepository(): MemoryTenantRepository;
 /**
  * Create a domain-to-tenant registry.
  */
 export declare function createDomainRegistry(): {
+    /**
+     * Map a domain to a tenant.
+     *
+     * @throws {TenantAlreadyExistsError} when the domain already resolves to
+     *   a different tenant. Re-registering the same pair is a no-op.
+     */
     register(domain: string, tenantId: TenantId): void;
     unregister(domain: string): void;
     resolve(domain: string): TenantId | undefined;