@zudojs/tenancy 0.1.0 → 1.1.0

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;

package/dist/repository/repository.core.js

@@ -3,40 +3,83 @@
  *
  * @module repository/repository
  */
-import { TenantNotFoundError } from "../tenancyErrors/tenancyError.types.js";
+import { TenantAlreadyExistsError } from "../tenancyErrors/tenancyError.types.js";
+/** Normalizes a domain for case-insensitive lookup. */
+function normalizeDomain(domain) {
+    return domain.trim().toLowerCase();
+}
 /**
  * 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 function createMemoryTenantRepository() {
     const tenants = new Map();
     const bySlug = new Map();
     const byDomain = new Map();
+    function unindex(id) {
+        for (const [slug, owner] of bySlug) {
+            if (owner === id)
+                bySlug.delete(slug);
+        }
+        for (const [domain, owner] of byDomain) {
+            if (owner === id)
+                byDomain.delete(domain);
+        }
+    }
     return {
         async findById(id) {
             return tenants.get(id);
         },
         async findBySlug(slug) {
-            return bySlug.get(slug);
+            const id = bySlug.get(slug.trim().toLowerCase());
+            return id ? tenants.get(id) : undefined;
         },
         async findByDomain(domain) {
-            return byDomain.get(domain);
+            const id = byDomain.get(normalizeDomain(domain));
+            return id ? tenants.get(id) : undefined;
         },
-        add(tenant) {
+        add(tenant, domains) {
+            // A slug or a domain already pointing at a different tenant must not be
+            // silently reassigned: `findByDomain` is a tenant resolution path, so a
+            // silent steal is a cross-tenant takeover, not a bookkeeping detail.
+            const slug = tenant.slug?.trim().toLowerCase();
+            if (slug) {
+                const owner = bySlug.get(slug);
+                if (owner !== undefined && owner !== tenant.id) {
+                    throw new TenantAlreadyExistsError(`slug "${slug}" is already registered to tenant "${owner}"`);
+                }
+            }
+            const normalizedDomains = (domains ?? []).map(normalizeDomain);
+            for (const domain of normalizedDomains) {
+                const owner = byDomain.get(domain);
+                if (owner !== undefined && owner !== tenant.id) {
+                    throw new TenantAlreadyExistsError(`domain "${domain}" is already registered to tenant "${owner}"`);
+                }
+            }
+            unindex(tenant.id);
             tenants.set(tenant.id, tenant);
-            if (tenant.slug)
-                bySlug.set(tenant.slug, tenant);
+            if (slug)
+                bySlug.set(slug, tenant.id);
+            for (const domain of normalizedDomains) {
+                byDomain.set(domain, tenant.id);
+            }
         },
         remove(id) {
-            const tenant = tenants.get(id);
-            if (tenant) {
-                tenants.delete(id);
-                if (tenant.slug)
-                    bySlug.delete(tenant.slug);
-            }
+            unindex(id);
+            tenants.delete(id);
         },
         all() {
             return Array.from(tenants.values());
         },
+        domainsOf(id) {
+            return Array.from(byDomain.entries())
+                .filter(([, owner]) => owner === id)
+                .map(([domain]) => domain);
+        },
     };
 }
 /**
@@ -45,14 +88,25 @@ export function createMemoryTenantRepository() {
 export function createDomainRegistry() {
     const domains = new Map();
     return {
+        /**
+         * 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, tenantId) {
-            domains.set(domain, tenantId);
+            const normalized = normalizeDomain(domain);
+            const owner = domains.get(normalized);
+            if (owner !== undefined && owner !== tenantId) {
+                throw new TenantAlreadyExistsError(`domain "${normalized}" is already registered to tenant "${owner}"`);
+            }
+            domains.set(normalized, tenantId);
         },
         unregister(domain) {
-            domains.delete(domain);
+            domains.delete(normalizeDomain(domain));
         },
         resolve(domain) {
-            return domains.get(domain);
+            return domains.get(normalizeDomain(domain));
         },
         all() {
             return Array.from(domains.entries()).map(([domain, tenantId]) => ({

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

@@ -6,13 +6,22 @@
 import type { TenantId } from "../tenancyTypes/tenantIdentity.js";
 import type { Tenant } from "../tenancyTypes/tenantInterface.js";
 import type { TenantResolution } from "../tenancyTypes/resolverTypes.js";
-import type { TenantRepository, TenantCache } from "../tenancyTypes/repositoryTypes.js";
+import type { TenantCache, TenantRepository } from "../tenancyTypes/repositoryTypes.js";
 import type { TenantContextStorage } from "../context/contextStorage.core.js";
+/** Default lifetime of a cached tenant record, in milliseconds. */
+export declare const DEFAULT_TENANT_CACHE_TTL_MS = 30000;
 /** Options for the tenant manager. */
 export interface TenantManagerOptions {
     readonly repository: TenantRepository;
     readonly cache?: TenantCache;
     readonly storage: TenantContextStorage;
+    /**
+     * How long a cached tenant may be served before it is re-read.
+     *
+     * Bounds the window in which a suspended tenant keeps being served from
+     * cache. Set to 0 to disable caching entirely.
+     */
+    readonly cacheTtlMs?: number;
 }
 /**
  * Create a tenant manager.
@@ -29,17 +38,26 @@ export declare function createTenantManager(options: TenantManagerOptions): {
     /**
      * Require a tenant by ID — throws if not found.
      */
-    require(id: TenantId): Promise<Tenant>;
+    require: (id: TenantId) => Promise<Tenant>;
+    /**
+     * Require a tenant that is also in an active state.
+     *
+     * Does not read `this`, so it survives being detached from the manager.
+     */
+    requireActive(id: TenantId): Promise<Tenant>;
     /**
      * Validate that a tenant is in an active state.
      */
-    assertActive(tenant: Tenant): void;
+    assertActive: (tenant: Tenant) => void;
     /**
      * Get the current tenant from context.
      */
     getCurrent(): Tenant | undefined;
     /**
      * Invalidate a cached tenant.
+     *
+     * Call after any write that changes a tenant's status, so the change is
+     * visible before the TTL would have expired.
      */
     invalidate(id: TenantId): Promise<void>;
 };

package/dist/repository/tenantManager.core.js

@@ -4,23 +4,47 @@
  * @module repository/tenantManager
  */
 import { TenantNotFoundError, TenantUnavailableError, } from "../tenancyErrors/tenancyError.types.js";
+/** Default lifetime of a cached tenant record, in milliseconds. */
+export const DEFAULT_TENANT_CACHE_TTL_MS = 30_000;
 /**
  * Create a tenant manager.
  */
 export function createTenantManager(options) {
     const { repository, cache, storage } = options;
+    const ttl = options.cacheTtlMs ?? DEFAULT_TENANT_CACHE_TTL_MS;
+    const cachedAt = new Map();
+    function isFresh(id) {
+        const at = cachedAt.get(id);
+        return at !== undefined && Date.now() - at < ttl;
+    }
     async function loadTenant(id) {
-        // Check cache first
-        if (cache) {
+        if (cache && ttl > 0 && isFresh(id)) {
             const cached = await cache.get(id);
             if (cached)
                 return cached;
         }
-        // Load from repository
         const tenant = await repository.findById(id);
-        if (tenant && cache) {
-            await cache.set(tenant);
+        if (cache && ttl > 0) {
+            if (tenant) {
+                await cache.set(tenant);
+                cachedAt.set(id, Date.now());
+            }
+            else {
+                await cache.delete(id);
+                cachedAt.delete(id);
+            }
+        }
+        return tenant;
+    }
+    function assertActive(tenant) {
+        if (tenant.status !== "active") {
+            throw new TenantUnavailableError(tenant.id, tenant.status);
         }
+    }
+    async function require(id) {
+        const tenant = await loadTenant(id);
+        if (!tenant)
+            throw new TenantNotFoundError(id);
         return tenant;
     }
     return {
@@ -39,20 +63,21 @@ export function createTenantManager(options) {
         /**
          * Require a tenant by ID — throws if not found.
          */
-        async require(id) {
-            const tenant = await loadTenant(id);
-            if (!tenant)
-                throw new TenantNotFoundError(id);
+        require,
+        /**
+         * Require a tenant that is also in an active state.
+         *
+         * Does not read `this`, so it survives being detached from the manager.
+         */
+        async requireActive(id) {
+            const tenant = await require(id);
+            assertActive(tenant);
             return tenant;
         },
         /**
          * Validate that a tenant is in an active state.
          */
-        assertActive(tenant) {
-            if (tenant.status !== "active") {
-                throw new TenantUnavailableError(tenant.id, tenant.status);
-            }
-        },
+        assertActive,
         /**
          * Get the current tenant from context.
          */
@@ -64,8 +89,12 @@ export function createTenantManager(options) {
         },
         /**
          * Invalidate a cached tenant.
+         *
+         * Call after any write that changes a tenant's status, so the change is
+         * visible before the TTL would have expired.
          */
         async invalidate(id) {
+            cachedAt.delete(id);
             if (cache)
                 await cache.delete(id);
         },

package/dist/resolver/index.d.ts

@@ -4,5 +4,6 @@
  * @module resolver
  */
 export { createResolverChain } from "./resolverChain.core.js";
+export type { TenantResolverChain } from "./resolverChain.core.js";
 export * from "./resolvers/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/resolver/resolverChain.core.d.ts

@@ -3,14 +3,29 @@
  *
  * @module resolver/resolverChain
  */
-import type { TenantResolver, TenantResolutionResult, ResolverChainOptions } from "../tenancyTypes/resolverTypes.js";
+import type { TenantResolver, TenantResolution, TenantResolutionResult, ResolverChainOptions } from "../tenancyTypes/resolverTypes.js";
 /**
- * Create a resolver chain that tries resolvers in priority order.
+ * A resolver chain.
+ *
+ * Exposes the full result via `resolve`, and views itself as a single
+ * `TenantResolver` via `asResolver()` so chains compose and can be passed
+ * directly to the HTTP middleware.
  */
-export declare function createResolverChain<Context = unknown>(resolvers: readonly TenantResolver<Context>[], options?: ResolverChainOptions): {
-    /**
-     * Resolve tenant from context using the chain.
-     */
+export interface TenantResolverChain<Context = unknown> {
+    readonly name: string;
+    readonly priority: number;
     resolve(context: Context): Promise<TenantResolutionResult>;
-};
+    resolveTenant(context: Context): Promise<TenantResolution | undefined>;
+    asResolver(): TenantResolver<Context>;
+}
+/**
+ * Create a resolver chain that tries resolvers in priority order.
+ *
+ * A resolver that returns `undefined` found nothing, and the chain moves on.
+ * A resolver that *throws* rejected a credential — an expired JWT, a bad
+ * signature — and the chain stops there. Continuing would let a lower-trust
+ * source such as a client-supplied header decide the tenant for a request
+ * whose credential was just refused.
+ */
+export declare function createResolverChain<Context = unknown>(resolvers: readonly TenantResolver<Context>[], options?: ResolverChainOptions): TenantResolverChain<Context>;
 //# sourceMappingURL=resolverChain.core.d.ts.map

package/dist/resolver/resolverChain.core.js

@@ -3,46 +3,78 @@
  *
  * @module resolver/resolverChain
  */
-import { TenantResolutionConflictError } from "../tenancyErrors/tenancyError.types.js";
+import { TenantResolutionConflictError, TenantResolutionError, } from "../tenancyErrors/tenancyError.types.js";
 /**
  * Create a resolver chain that tries resolvers in priority order.
+ *
+ * A resolver that returns `undefined` found nothing, and the chain moves on.
+ * A resolver that *throws* rejected a credential — an expired JWT, a bad
+ * signature — and the chain stops there. Continuing would let a lower-trust
+ * source such as a client-supplied header decide the tenant for a request
+ * whose credential was just refused.
  */
 export function createResolverChain(resolvers, options) {
     // Sort by priority descending (higher priority first)
     const sorted = [...resolvers].sort((a, b) => b.priority - a.priority);
-    return {
+    const collectAll = options?.detectConflicts ?? false;
+    const chain = {
+        name: options?.name ?? "chain",
+        priority: options?.priority ??
+            sorted.reduce((highest, r) => Math.max(highest, r.priority), 0),
         /**
          * Resolve tenant from context using the chain.
+         *
+         * @throws {TenantResolutionError} when a resolver rejects a credential.
+         * @throws {TenantResolutionConflictError} when sources disagree and
+         *   `throwOnConflict` is set.
          */
         async resolve(context) {
             const candidates = [];
             for (const resolver of sorted) {
+                let result;
                 try {
-                    const result = await resolver.resolve(context);
-                    if (result) {
-                        candidates.push(result);
-                    }
+                    result = await resolver.resolve(context);
                 }
-                catch {
-                    // Skip failed resolvers — continue chain
+                catch (error) {
+                    throw new TenantResolutionError(`Tenant resolver "${resolver.name}" rejected the request`, error);
                 }
+                if (!result)
+                    continue;
+                candidates.push(result);
+                if (!collectAll)
+                    break;
             }
             if (candidates.length === 0) {
                 return { resolution: undefined, candidates: [], conflict: false };
             }
-            // Check for conflicts
-            const uniqueTenantIds = new Set(candidates.map((c) => c.tenantId));
-            const hasConflict = uniqueTenantIds.size > 1;
-            if (hasConflict && options?.throwOnConflict) {
+            const hasConflict = new Set(candidates.map((candidate) => candidate.tenantId)).size > 1;
+            if (hasConflict && (options?.throwOnConflict ?? true)) {
                 throw new TenantResolutionConflictError(candidates.map((c) => `${c.source}:${c.tenantId}`));
             }
-            // Use highest priority (first in sorted list)
             return {
                 resolution: candidates[0],
                 candidates,
                 conflict: hasConflict,
             };
         },
+        /**
+         * Resolve the winning tenant, discarding the candidate detail.
+         *
+         * This is what makes a chain a `TenantResolver`, so chains compose with
+         * each other and can be handed straight to the HTTP middleware.
+         */
+        async resolveTenant(context) {
+            return (await chain.resolve(context)).resolution;
+        },
+        /** View the chain as a single resolver. */
+        asResolver() {
+            return {
+                name: chain.name,
+                priority: chain.priority,
+                resolve: (context) => chain.resolveTenant(context),
+            };
+        },
     };
+    return chain;
 }
 //# sourceMappingURL=resolverChain.core.js.map

package/dist/resolver/resolvers/headerResolver.core.d.ts

@@ -4,18 +4,26 @@
  * @module resolvers/headerResolver
  */
 import type { TenantResolver } from "../../tenancyTypes/resolverTypes.js";
+import type { TenantTrustLevel } from "../../tenancyTypes/tenantInterface.js";
 /** Context type with a getHeader method. */
-interface HeaderContext {
+export interface HeaderContext {
     getHeader(name: string): string | undefined;
 }
 /** Options for the header resolver. */
 export interface HeaderResolverOptions {
     readonly headerName?: string;
     readonly priority?: number;
+    /**
+     * Trust to assign to a tenant resolved from this header.
+     *
+     * Defaults to `untrusted`, because the header is client-supplied on the
+     * wire. Raise it to `verified` only when a trusted proxy strips and re-sets
+     * the header at the edge, so a client cannot forge it.
+     */
+    readonly trust?: TenantTrustLevel;
 }
 /**
  * Create a tenant resolver that reads from an HTTP header.
  */
 export declare function createHeaderResolver(options?: HeaderResolverOptions): TenantResolver<HeaderContext>;
-export {};
 //# sourceMappingURL=headerResolver.core.d.ts.map

package/dist/resolver/resolvers/headerResolver.core.js

@@ -3,25 +3,22 @@
  *
  * @module resolvers/headerResolver
  */
-import { createTenantId } from "../../tenancyTypes/tenantIdentity.js";
+import { tryCreateTenantId } from "../../tenancyTypes/tenantIdentity.js";
 /**
  * Create a tenant resolver that reads from an HTTP header.
  */
 export function createHeaderResolver(options) {
     const headerName = options?.headerName ?? "x-tenant-id";
     const priority = options?.priority ?? 80;
+    const trust = options?.trust ?? "untrusted";
     return {
         name: "header",
         priority,
         async resolve(context) {
-            const value = context.getHeader(headerName);
-            if (!value)
+            const tenantId = tryCreateTenantId(context.getHeader(headerName));
+            if (!tenantId)
                 return undefined;
-            return {
-                tenantId: createTenantId(value),
-                source: "header",
-                trust: "verified",
-            };
+            return { tenantId, source: "header", trust };
         },
     };
 }

package/dist/resolver/resolvers/index.d.ts

@@ -1,10 +1,14 @@
 /**
  * Built-in tenant resolvers.
  *
- * @module resolvers
+ * @module resolver/resolvers
  */
-export { createHeaderResolver, type HeaderResolverOptions, } from "./headerResolver.core.js";
-export { createSubdomainResolver, type SubdomainResolverOptions, } from "./subdomainResolver.core.js";
-export { createPathResolver, type PathResolverOptions, } from "./pathResolver.core.js";
-export { createJwtResolver, type JwtResolverOptions, } from "./jwtResolver.core.js";
+export { createHeaderResolver } from "./headerResolver.core.js";
+export type { HeaderContext, HeaderResolverOptions, } from "./headerResolver.core.js";
+export { createSubdomainResolver } from "./subdomainResolver.core.js";
+export type { SubdomainContext, SubdomainResolverOptions, } from "./subdomainResolver.core.js";
+export { createPathResolver } from "./pathResolver.core.js";
+export type { PathContext, PathResolverOptions } from "./pathResolver.core.js";
+export { createJwtResolver } from "./jwtResolver.core.js";
+export type { JwtContext, JwtResolverOptions } from "./jwtResolver.core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/resolver/resolvers/index.js

@@ -1,10 +1,10 @@
 /**
  * Built-in tenant resolvers.
  *
- * @module resolvers
+ * @module resolver/resolvers
  */
-export { createHeaderResolver, } from "./headerResolver.core.js";
-export { createSubdomainResolver, } from "./subdomainResolver.core.js";
-export { createPathResolver, } from "./pathResolver.core.js";
-export { createJwtResolver, } from "./jwtResolver.core.js";
+export { createHeaderResolver } from "./headerResolver.core.js";
+export { createSubdomainResolver } from "./subdomainResolver.core.js";
+export { createPathResolver } from "./pathResolver.core.js";
+export { createJwtResolver } from "./jwtResolver.core.js";
 //# sourceMappingURL=index.js.map

package/dist/resolver/resolvers/jwtResolver.core.d.ts

@@ -10,7 +10,7 @@ interface JwtClaims {
     readonly [key: string]: unknown;
 }
 /** Context with a getClaims method. */
-interface JwtContext {
+export interface JwtContext {
     getClaims(): JwtClaims | undefined;
 }
 /** Options for the JWT resolver. */

package/dist/resolver/resolvers/jwtResolver.core.js

@@ -3,7 +3,7 @@
  *
  * @module resolvers/jwtResolver
  */
-import { createTenantId } from "../../tenancyTypes/tenantIdentity.js";
+import { tryCreateTenantId } from "../../tenancyTypes/tenantIdentity.js";
 /**
  * Create a tenant resolver that reads from JWT claims.
  */
@@ -17,14 +17,10 @@ export function createJwtResolver(options) {
             const claims = context.getClaims();
             if (!claims)
                 return undefined;
-            const tenantId = claims[claimKey];
-            if (typeof tenantId !== "string" || !tenantId)
+            const tenantId = tryCreateTenantId(claims[claimKey]);
+            if (!tenantId)
                 return undefined;
-            return {
-                tenantId: createTenantId(tenantId),
-                source: "jwt",
-                trust: "trusted",
-            };
+            return { tenantId, source: "jwt", trust: "trusted" };
         },
     };
 }

package/dist/resolver/resolvers/pathResolver.core.d.ts

@@ -5,12 +5,17 @@
  */
 import type { TenantResolver } from "../../tenancyTypes/resolverTypes.js";
 /** Context with getPath method. */
-interface PathContext {
+export interface PathContext {
     getPath(): string | undefined;
 }
 /** Options for the path resolver. */
 export interface PathResolverOptions {
-    /** Prefix to strip (e.g. "/tenant"). */
+    /**
+     * Prefix to strip (e.g. "/tenant").
+     *
+     * When set, only paths under the prefix name a tenant; any other path
+     * resolves to nothing.
+     */
     readonly prefix?: string;
     readonly priority?: number;
 }
@@ -20,5 +25,4 @@ export interface PathResolverOptions {
  * Example: "/acme/users" → tenant "acme"
  */
 export declare function createPathResolver(options?: PathResolverOptions): TenantResolver<PathContext>;
-export {};
 //# sourceMappingURL=pathResolver.core.d.ts.map