@zudojs/tenancy 1.3.2 → 1.4.0

package/README.md

@@ -149,8 +149,18 @@ explicitly on routes where something else ties the tenant to the principal.
 - 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.
+- For `@zudojs/cache`, use `createTenantCacheScope(tenantId, key)` rather than
+  `createTenantCacheKey`: the cache refuses `:` inside a key part (that is how
+  it stops a raw key from forging a namespace), so `tenant:acme:totals` throws
+  `ERR_INVALID_INPUT` there. The scope helper returns
+  `{ namespace: "tenant.acme", key: "totals" }`, and the cache's namespace is
+  the isolation boundary:
+  `await cache.get(scope.key, { namespace: scope.namespace })`.
 - Non-active tenants are refused during resolution. Pass `allowInactive` on
   routes that exist to serve suspended tenants.
+- Every refusal body is `{ "error": message, "code": ERR_TENANT_* }`, the
+  shape `@zudojs/http` uses, so a client can tell `ERR_TENANT_NOT_FOUND` from
+  an application 404. The codes are exported as `TENANCY_RESPONSE_CODE`.
 - An unknown tenant and a non-active one get the same `404 Tenant not found`,
   and the guard middleware answers `403 Tenant is not available` without the
   id or status, so a caller cannot enumerate tenants or learn which are

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

@@ -53,4 +53,3 @@ export declare function createContextManager(options: ContextManagerOptions): {
      */
     runAs<T>(tenant: Tenant, callback: () => T): T;
 };
-//# sourceMappingURL=contextManager.core.d.ts.map

package/dist/context/contextManager.core.js

@@ -85,4 +85,3 @@ export function createContextManager(options) {
         },
     };
 }
-//# sourceMappingURL=contextManager.core.js.map

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

@@ -21,4 +21,3 @@ export declare function getDefaultStorage(): TenantContextStorage;
  * Reset the default storage (useful for testing).
  */
 export declare function resetDefaultStorage(): void;
-//# sourceMappingURL=contextStorage.core.d.ts.map

package/dist/context/contextStorage.core.js

@@ -35,4 +35,3 @@ export function getDefaultStorage() {
 export function resetDefaultStorage() {
     defaultStorage = undefined;
 }
-//# sourceMappingURL=contextStorage.core.js.map

package/dist/context/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { createTenantContextStorage, getDefaultStorage, resetDefaultStorage, type TenantContextStorage, } from "./contextStorage.core.js";
 export { createContextManager, type ContextManagerOptions, } from "./contextManager.core.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/context/index.js

@@ -5,4 +5,3 @@
  */
 export { createTenantContextStorage, getDefaultStorage, resetDefaultStorage, } from "./contextStorage.core.js";
 export { createContextManager, } from "./contextManager.core.js";
-//# sourceMappingURL=index.js.map

package/dist/http/httpHelpers.d.ts

@@ -9,28 +9,51 @@
  * @module http/httpHelpers
  */
 import { type GuardResponse } from "@zudojs/middleware";
+/**
+ * Machine-readable `code` carried by every refusal body the tenancy
+ * middleware produces, alongside `error`. They are tenant-specific on
+ * purpose: a client (or a test) can tell "no tenant" from an application's
+ * own `404`, which `{ "error": "Tenant not found" }` alone could not.
+ */
+export declare const TENANCY_RESPONSE_CODE: Readonly<{
+    /** The request names no tenant, or an unknown or non-active one. */
+    readonly NOT_FOUND: "ERR_TENANT_NOT_FOUND";
+    /** A tenant was resolved but the route requires one it lacks. */
+    readonly REQUIRED: "ERR_TENANT_REQUIRED";
+    /** The route forbids tenant context, or the resolution is not trusted. */
+    readonly FORBIDDEN: "ERR_TENANT_FORBIDDEN";
+    /** The tenant exists but is not active (guard middleware). */
+    readonly UNAVAILABLE: "ERR_TENANT_UNAVAILABLE";
+    /** Two request sources named different tenants. */
+    readonly RESOLUTION_CONFLICT: "ERR_TENANT_RESOLUTION_CONFLICT";
+    /** A resolver rejected a credential or could not run. */
+    readonly RESOLUTION_FAILED: "ERR_TENANT_RESOLUTION_FAILED";
+}>;
+/** One of the {@link TENANCY_RESPONSE_CODE} values. */
+export type TenancyResponseCode = (typeof TENANCY_RESPONSE_CODE)[keyof typeof TENANCY_RESPONSE_CODE];
 /**
  * Create a JSON response with a caller-built body.
  */
 export declare function createJsonResponse(status: number, body: unknown): GuardResponse;
 /**
- * Create a JSON error response: `{ "error": message }`.
+ * Create a JSON error response: `{ "error": message, "code": code }`, the
+ * shape `@zudojs/http` uses for thrown errors. `code` is omitted only when
+ * not given.
  */
-export declare function createJsonErrorResponse(status: number, message: string): GuardResponse;
+export declare function createJsonErrorResponse(status: number, message: string, code?: string): GuardResponse;
 /**
  * Create a 400 Bad Request response.
  */
-export declare function createBadRequest(message: string): GuardResponse;
+export declare function createBadRequest(message: string, code?: string): GuardResponse;
 /**
  * Create a 401 Unauthorized response.
  */
-export declare function createUnauthorized(message: string): GuardResponse;
+export declare function createUnauthorized(message: string, code?: string): GuardResponse;
 /**
  * Create a 403 Forbidden response.
  */
-export declare function createForbidden(message: string): GuardResponse;
+export declare function createForbidden(message: string, code?: string): GuardResponse;
 /**
  * Create a 404 Not Found response.
  */
-export declare function createNotFound(message: string): GuardResponse;
-//# sourceMappingURL=httpHelpers.d.ts.map
+export declare function createNotFound(message: string, code?: string): GuardResponse;

package/dist/http/httpHelpers.js

@@ -10,6 +10,26 @@
  */
 import { createGuardResponse } from "@zudojs/middleware";
 const JSON_HEADERS = { "content-type": "application/json" };
+/**
+ * Machine-readable `code` carried by every refusal body the tenancy
+ * middleware produces, alongside `error`. They are tenant-specific on
+ * purpose: a client (or a test) can tell "no tenant" from an application's
+ * own `404`, which `{ "error": "Tenant not found" }` alone could not.
+ */
+export const TENANCY_RESPONSE_CODE = Object.freeze({
+    /** The request names no tenant, or an unknown or non-active one. */
+    NOT_FOUND: "ERR_TENANT_NOT_FOUND",
+    /** A tenant was resolved but the route requires one it lacks. */
+    REQUIRED: "ERR_TENANT_REQUIRED",
+    /** The route forbids tenant context, or the resolution is not trusted. */
+    FORBIDDEN: "ERR_TENANT_FORBIDDEN",
+    /** The tenant exists but is not active (guard middleware). */
+    UNAVAILABLE: "ERR_TENANT_UNAVAILABLE",
+    /** Two request sources named different tenants. */
+    RESOLUTION_CONFLICT: "ERR_TENANT_RESOLUTION_CONFLICT",
+    /** A resolver rejected a credential or could not run. */
+    RESOLUTION_FAILED: "ERR_TENANT_RESOLUTION_FAILED",
+});
 /**
  * Create a JSON response with a caller-built body.
  */
@@ -17,33 +37,34 @@ export function createJsonResponse(status, body) {
     return createGuardResponse({ status, body, headers: JSON_HEADERS });
 }
 /**
- * Create a JSON error response: `{ "error": message }`.
+ * Create a JSON error response: `{ "error": message, "code": code }`, the
+ * shape `@zudojs/http` uses for thrown errors. `code` is omitted only when
+ * not given.
  */
-export function createJsonErrorResponse(status, message) {
-    return createJsonResponse(status, { error: message });
+export function createJsonErrorResponse(status, message, code) {
+    return createJsonResponse(status, code === undefined ? { error: message } : { error: message, code });
 }
 /**
  * Create a 400 Bad Request response.
  */
-export function createBadRequest(message) {
-    return createJsonErrorResponse(400, message);
+export function createBadRequest(message, code = TENANCY_RESPONSE_CODE.RESOLUTION_FAILED) {
+    return createJsonErrorResponse(400, message, code);
 }
 /**
  * Create a 401 Unauthorized response.
  */
-export function createUnauthorized(message) {
-    return createJsonErrorResponse(401, message);
+export function createUnauthorized(message, code = TENANCY_RESPONSE_CODE.REQUIRED) {
+    return createJsonErrorResponse(401, message, code);
 }
 /**
  * Create a 403 Forbidden response.
  */
-export function createForbidden(message) {
-    return createJsonErrorResponse(403, message);
+export function createForbidden(message, code = TENANCY_RESPONSE_CODE.FORBIDDEN) {
+    return createJsonErrorResponse(403, message, code);
 }
 /**
  * Create a 404 Not Found response.
  */
-export function createNotFound(message) {
-    return createJsonErrorResponse(404, message);
+export function createNotFound(message, code = TENANCY_RESPONSE_CODE.NOT_FOUND) {
+    return createJsonErrorResponse(404, message, code);
 }
-//# sourceMappingURL=httpHelpers.js.map

package/dist/http/httpResolverContext.d.ts

@@ -42,4 +42,3 @@ export declare const TENANT_CLAIMS_STATE_KEY = "tenancy:claims";
  * @returns An accessor object every shipped resolver understands.
  */
 export declare function createHttpResolverContext<Context extends HttpMiddlewareContext = HttpMiddlewareContext>(context: Context, getClaims?: TenantClaimsReader<Context>): HttpResolverContext;
-//# sourceMappingURL=httpResolverContext.d.ts.map

package/dist/http/httpResolverContext.js

@@ -38,4 +38,3 @@ export function createHttpResolverContext(context, getClaims) {
         },
     };
 }
-//# sourceMappingURL=httpResolverContext.js.map

package/dist/http/httpSupport/httpRequest.helper.d.ts

@@ -14,4 +14,3 @@ import type { HttpRequestContext } from "../httpTypes.js";
  * then a plain object — each case-insensitive.
  */
 export declare function readRequestHeader(request: HttpRequestContext, name: string): string | undefined;
-//# sourceMappingURL=httpRequest.helper.d.ts.map

package/dist/http/httpSupport/httpRequest.helper.js

@@ -45,4 +45,3 @@ export function readRequestHeader(request, name) {
     }
     return readBag(request.headers, name);
 }
-//# sourceMappingURL=httpRequest.helper.js.map

package/dist/http/httpSupport/index.d.ts

@@ -8,4 +8,3 @@
 export { readRequestHeader } from "./httpRequest.helper.js";
 export { loadResolvedTenant } from "./tenancyMiddleware.lookup.js";
 export { toTenantResolver, type TenantResolverSource, } from "./tenancyMiddleware.resolver.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/http/httpSupport/index.js

@@ -8,4 +8,3 @@
 export { readRequestHeader } from "./httpRequest.helper.js";
 export { loadResolvedTenant } from "./tenancyMiddleware.lookup.js";
 export { toTenantResolver, } from "./tenancyMiddleware.resolver.js";
-//# sourceMappingURL=index.js.map

package/dist/http/httpSupport/tenancyMiddleware.lookup.d.ts

@@ -16,4 +16,3 @@ import type { TenantRepository } from "../../tenancyTypes/repositoryTypes.js";
  * every tenant whose id differs from its slug was unreachable.
  */
 export declare function loadResolvedTenant(repository: TenantRepository, resolution: TenantResolution, slugLookup: boolean): Promise<Tenant | undefined>;
-//# sourceMappingURL=tenancyMiddleware.lookup.d.ts.map

package/dist/http/httpSupport/tenancyMiddleware.lookup.js

@@ -22,4 +22,3 @@ export async function loadResolvedTenant(repository, resolution, slugLookup) {
         return undefined;
     return repository.findBySlug?.(resolution.tenantId);
 }
-//# sourceMappingURL=tenancyMiddleware.lookup.js.map

package/dist/http/httpSupport/tenancyMiddleware.resolver.d.ts

@@ -27,4 +27,3 @@ export type TenantResolverSource<Context> = TenantResolver<Context> | TenantReso
  * @returns A resolver that yields the winning `TenantResolution`.
  */
 export declare function toTenantResolver<Context>(source: TenantResolverSource<Context>): TenantResolver<Context>;
-//# sourceMappingURL=tenancyMiddleware.resolver.d.ts.map

package/dist/http/httpSupport/tenancyMiddleware.resolver.js

@@ -22,4 +22,3 @@ function isResolverChain(source) {
     return (typeof source.asResolver ===
         "function");
 }
-//# sourceMappingURL=tenancyMiddleware.resolver.js.map

package/dist/http/httpTypes.d.ts

@@ -65,4 +65,3 @@ export interface HttpMiddlewareState {
     get<T = unknown>(key: string): T | undefined;
     set<T = unknown>(key: string, value: T): void;
 }
-//# sourceMappingURL=httpTypes.d.ts.map

package/dist/http/httpTypes.js

@@ -8,4 +8,3 @@
  * @module http/httpTypes
  */
 export {};
-//# sourceMappingURL=httpTypes.js.map

package/dist/http/index.d.ts

@@ -9,6 +9,6 @@ export { TENANT_CLAIMS_STATE_KEY, createHttpResolverContext, } from "./httpResol
 export type { HttpResolverContext, TenantClaims, TenantClaimsReader, } from "./httpResolverContext.js";
 export { readRequestHeader } from "./httpSupport/index.js";
 export type { TenantResolverSource } from "./httpSupport/index.js";
-export { createBadRequest, createForbidden, createJsonErrorResponse, createJsonResponse, createNotFound, createUnauthorized, } from "./httpHelpers.js";
+export { createBadRequest, createForbidden, createJsonErrorResponse, createJsonResponse, createNotFound, createUnauthorized, TENANCY_RESPONSE_CODE, } from "./httpHelpers.js";
+export type { TenancyResponseCode } from "./httpHelpers.js";
 export type * from "./httpTypes.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -5,5 +5,4 @@ export { TENANT_CONTEXT_STATE_KEY, TENANT_STATE_KEY, createRequireTenantMiddlewa
 export { createTenantGuardMiddleware, createTenantPropagationMiddleware, } from "./tenancyMiddleware.guard.js";
 export { TENANT_CLAIMS_STATE_KEY, createHttpResolverContext, } from "./httpResolverContext.js";
 export { readRequestHeader } from "./httpSupport/index.js";
-export { createBadRequest, createForbidden, createJsonErrorResponse, createJsonResponse, createNotFound, createUnauthorized, } from "./httpHelpers.js";
-//# sourceMappingURL=index.js.map
+export { createBadRequest, createForbidden, createJsonErrorResponse, createJsonResponse, createNotFound, createUnauthorized, TENANCY_RESPONSE_CODE, } from "./httpHelpers.js";

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

@@ -74,7 +74,10 @@ export interface ResolveTenantMiddlewareOptions<Context extends HttpMiddlewareCo
      * `tenancy:claims` state key. May be typed with `@zudojs/http`'s context.
      */
     readonly getClaims?: TenantClaimsReader<Context>;
-    /** Custom error response for missing tenant. */
+    /**
+     * Custom body for the 404 answered when no usable tenant resolves. The
+     * default is `{ error: "Tenant not found", code: "ERR_TENANT_NOT_FOUND" }`.
+     */
     readonly notFoundResponse?: (resolution: TenantResolution | undefined) => unknown;
 }
 /** Options for the require tenant middleware. */
@@ -98,4 +101,3 @@ export declare function createResolveTenantMiddleware<Context extends HttpMiddle
  * Must run after `createResolveTenantMiddleware`.
  */
 export declare function createRequireTenantMiddleware(options?: RequireTenantMiddlewareOptions): HttpMiddleware;
-//# sourceMappingURL=tenancyMiddleware.core.d.ts.map

package/dist/http/tenancyMiddleware.core.js

@@ -8,7 +8,7 @@
  * Composes with the @zudojs/http pipeline structurally; no dependency on it.
  */
 import { createHttpResolverContext } from "./httpResolverContext.js";
-import { createBadRequest, createForbidden, createJsonResponse, createNotFound, createUnauthorized, } from "./httpHelpers.js";
+import { createBadRequest, createForbidden, createJsonResponse, createNotFound, createUnauthorized, TENANCY_RESPONSE_CODE, } from "./httpHelpers.js";
 import { meetsTrustLevel } from "../security/guard.core.js";
 import { loadResolvedTenant, toTenantResolver, } from "./httpSupport/index.js";
 import { TenantResolutionConflictError, TenantResolutionError, } from "../tenancyErrors/tenancyError.types.js";
@@ -45,7 +45,7 @@ export function createResolveTenantMiddleware(options) {
             // 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");
+                return createForbidden("Tenant could not be established: request sources name different tenants", TENANCY_RESPONSE_CODE.RESOLUTION_CONFLICT);
             }
             if (error instanceof TenantResolutionError) {
                 return createBadRequest("Tenant could not be resolved for this request");
@@ -101,4 +101,3 @@ export function createRequireTenantMiddleware(options) {
         return next();
     };
 }
-//# sourceMappingURL=tenancyMiddleware.core.js.map

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

@@ -32,4 +32,3 @@ export declare function createTenantGuardMiddleware(options?: TenantGuardMiddlew
  * into AsyncLocalStorage for downstream handlers.
  */
 export declare function createTenantPropagationMiddleware(storage: TenantContextStorage): HttpMiddleware;
-//# sourceMappingURL=tenancyMiddleware.guard.d.ts.map

package/dist/http/tenancyMiddleware.guard.js

@@ -3,7 +3,7 @@
  *
  * @module http/tenancyMiddleware.guard
  */
-import { createForbidden } from "./httpHelpers.js";
+import { createForbidden, TENANCY_RESPONSE_CODE } from "./httpHelpers.js";
 import { TENANT_STATE_KEY, TENANT_CONTEXT_STATE_KEY, } from "./tenancyMiddleware.core.js";
 // ─── Middleware Factories ──────────────────────────────────────────────────
 /**
@@ -24,7 +24,7 @@ export function createTenantGuardMiddleware(options = {}) {
         // One answer for "gone" and "not active", naming neither the tenant nor
         // its status: the body goes to the client, which must not learn either.
         if (!current || current.status !== "active") {
-            return createForbidden("Tenant is not available");
+            return createForbidden("Tenant is not available", TENANCY_RESPONSE_CODE.UNAVAILABLE);
         }
         return next();
     };
@@ -47,4 +47,3 @@ export function createTenantPropagationMiddleware(storage) {
         return next();
     };
 }
-//# sourceMappingURL=tenancyMiddleware.guard.js.map

package/dist/index.d.ts

@@ -16,4 +16,3 @@ export * from "./repository/index.js";
 export * from "./security/index.js";
 export * from "./utils/index.js";
 export * from "./http/index.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -16,4 +16,3 @@ export * from "./repository/index.js";
 export * from "./security/index.js";
 export * from "./utils/index.js";
 export * from "./http/index.js";
-//# sourceMappingURL=index.js.map

package/dist/repository/index.d.ts

@@ -6,4 +6,3 @@
 export { createMemoryTenantRepository, createDomainRegistry, } from "./repository.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

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

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

@@ -55,4 +55,3 @@ export declare function createDomainRegistry(): {
     resolve(domain: string): TenantId | undefined;
     all(): readonly TenantDomain[];
 };
-//# sourceMappingURL=repository.core.d.ts.map

package/dist/repository/repository.core.js

@@ -116,4 +116,3 @@ export function createDomainRegistry() {
         },
     };
 }
-//# sourceMappingURL=repository.core.js.map

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

@@ -61,4 +61,3 @@ export declare function createTenantManager(options: TenantManagerOptions): {
      */
     invalidate(id: TenantId): Promise<void>;
 };
-//# sourceMappingURL=tenantManager.core.d.ts.map

package/dist/repository/tenantManager.core.js

@@ -100,4 +100,3 @@ export function createTenantManager(options) {
         },
     };
 }
-//# sourceMappingURL=tenantManager.core.js.map

package/dist/resolver/index.d.ts

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

package/dist/resolver/index.js

@@ -5,4 +5,3 @@
  */
 export { createResolverChain } from "./resolverChain.core.js";
 export * from "./resolvers/index.js";
-//# sourceMappingURL=index.js.map

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

@@ -46,4 +46,3 @@ export type ResolverChainContext<Resolvers extends readonly TenantResolver<never
 export declare function createResolverChain<const Resolvers extends readonly TenantResolver<never>[]>(resolvers: Resolvers, options?: ResolverChainOptions): TenantResolverChain<ResolverChainContext<Resolvers>>;
 export declare function createResolverChain<Context = unknown>(resolvers: readonly TenantResolver<Context>[], options?: ResolverChainOptions): TenantResolverChain<Context>;
 export {};
-//# sourceMappingURL=resolverChain.core.d.ts.map

package/dist/resolver/resolverChain.core.js

@@ -68,4 +68,3 @@ export function createResolverChain(resolvers, options) {
     };
     return chain;
 }
-//# sourceMappingURL=resolverChain.core.js.map

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

@@ -32,4 +32,3 @@ export interface DomainResolverOptions {
  * so the chain moves on.
  */
 export declare function createDomainResolver(options: DomainResolverOptions): TenantResolver<DomainContext>;
-//# sourceMappingURL=domainResolver.core.d.ts.map

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

@@ -30,4 +30,3 @@ export function createDomainResolver(options) {
         },
     };
 }
-//# sourceMappingURL=domainResolver.core.js.map

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

@@ -26,4 +26,3 @@ export interface HeaderResolverOptions {
  * Create a tenant resolver that reads from an HTTP header.
  */
 export declare function createHeaderResolver(options?: HeaderResolverOptions): TenantResolver<HeaderContext>;
-//# sourceMappingURL=headerResolver.core.d.ts.map

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

@@ -22,4 +22,3 @@ export function createHeaderResolver(options) {
         },
     };
 }
-//# sourceMappingURL=headerResolver.core.js.map

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

@@ -13,4 +13,3 @@ 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

@@ -8,4 +8,3 @@ export { createSubdomainResolver } from "./subdomainResolver.core.js";
 export { createDomainResolver } from "./domainResolver.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

@@ -24,4 +24,3 @@ export interface JwtResolverOptions {
  */
 export declare function createJwtResolver(options?: JwtResolverOptions): TenantResolver<JwtContext>;
 export {};
-//# sourceMappingURL=jwtResolver.core.d.ts.map

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

@@ -24,4 +24,3 @@ export function createJwtResolver(options) {
         },
     };
 }
-//# sourceMappingURL=jwtResolver.core.js.map

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

@@ -25,4 +25,3 @@ export interface PathResolverOptions {
  * Example: "/acme/users" → tenant "acme"
  */
 export declare function createPathResolver(options?: PathResolverOptions): TenantResolver<PathContext>;
-//# sourceMappingURL=pathResolver.core.d.ts.map

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

@@ -41,4 +41,3 @@ export function createPathResolver(options) {
         },
     };
 }
-//# sourceMappingURL=pathResolver.core.js.map

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

@@ -36,4 +36,3 @@ export declare function hostnameOf(host: string): string | undefined;
  * Example: "acme.example.com" → tenant "acme"
  */
 export declare function createSubdomainResolver(options?: SubdomainResolverOptions): TenantResolver<SubdomainContext>;
-//# sourceMappingURL=subdomainResolver.core.d.ts.map

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

@@ -64,4 +64,3 @@ export function createSubdomainResolver(options) {
         },
     };
 }
-//# sourceMappingURL=subdomainResolver.core.js.map

package/dist/security/guard.core.d.ts

@@ -49,4 +49,3 @@ export declare function tenantKey(tenantId: TenantId, key: string, separator?: s
  * Create a tenant cache key.
  */
 export declare function createTenantCacheKey(tenantId: TenantId, key: string): string;
-//# sourceMappingURL=guard.core.d.ts.map

package/dist/security/guard.core.js

@@ -110,4 +110,3 @@ export function tenantKey(tenantId, key, separator = ":") {
 export function createTenantCacheKey(tenantId, key) {
     return tenantKey(tenantId, key, ":");
 }
-//# sourceMappingURL=guard.core.js.map

package/dist/security/index.d.ts

@@ -4,4 +4,4 @@
  * @module security
  */
 export { getDefaultTrust, meetsTrustLevel, assertTenantUsable, assertTenantOwnership, assertTrustLevel, assertSameTenant, tenantKey, createTenantCacheKey, } from "./guard.core.js";
-//# sourceMappingURL=index.d.ts.map
+export { createTenantCacheNamespace, createTenantCacheScope, TENANT_CACHE_PART_PATTERN, type TenantCacheScope, } from "./tenantCache.helper.js";

package/dist/security/index.js

@@ -4,4 +4,4 @@
  * @module security
  */
 export { getDefaultTrust, meetsTrustLevel, assertTenantUsable, assertTenantOwnership, assertTrustLevel, assertSameTenant, tenantKey, createTenantCacheKey, } from "./guard.core.js";
-//# sourceMappingURL=index.js.map
+export { createTenantCacheNamespace, createTenantCacheScope, TENANT_CACHE_PART_PATTERN, } from "./tenantCache.helper.js";

package/dist/security/tenantCache.helper.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tenant scoping for `@zudojs/cache`.
+ *
+ * @module security/tenantCache
+ *
+ * `createTenantCacheKey` builds `tenant:<id>:<key>`, which `@zudojs/cache`
+ * refuses: its key parts may not contain the `:` separator, precisely so a
+ * raw key cannot forge a namespace. The cache's own tenant boundary is the
+ * `namespace` option, so the compatible shape is a namespace derived from
+ * the tenant id plus the caller's key, passed separately:
+ *
+ * ```ts
+ * const scope = createTenantCacheScope(tenantId, "dashboard.totals");
+ * await cache.get(scope.key, { namespace: scope.namespace });
+ * ```
+ */
+import type { TenantId } from "../tenancyTypes/tenantIdentity.js";
+/**
+ * The alphabet `@zudojs/cache` accepts for a key part
+ * (`CACHE_KEY_PATTERN` there). Mirrored rather than imported: tenancy sits
+ * below cache in the dependency tiers.
+ */
+export declare const TENANT_CACHE_PART_PATTERN: RegExp;
+/** A tenant-scoped cache address: pass both halves to `@zudojs/cache`. */
+export interface TenantCacheScope {
+    /** Cache namespace for the tenant, e.g. `tenant.kola-motors`. */
+    readonly namespace: string;
+    /** The caller's key, unchanged. */
+    readonly key: string;
+}
+/**
+ * Cache namespace for a tenant: `tenant.<tenantId>`.
+ *
+ * Tenant ids are already constrained to `^[a-z0-9][a-z0-9_-]*$`, so the
+ * result always satisfies the cache's part alphabet.
+ */
+export declare function createTenantCacheNamespace(tenantId: TenantId): string;
+/**
+ * Build a tenant-scoped cache address that `@zudojs/cache` accepts.
+ *
+ * Isolation comes from the namespace, not from string concatenation, so two
+ * tenants can never share a fully-qualified key whatever `key` is.
+ *
+ * @param tenantId - The owning tenant.
+ * @param key - The resource key within that tenant. Must match
+ *   {@link TENANT_CACHE_PART_PATTERN}; in particular it may not contain `:`.
+ * @throws {ValidationError} when `key` would fail the cache's validation.
+ */
+export declare function createTenantCacheScope(tenantId: TenantId, key: string): TenantCacheScope;

package/dist/security/tenantCache.helper.js

@@ -0,0 +1,54 @@
+/**
+ * Tenant scoping for `@zudojs/cache`.
+ *
+ * @module security/tenantCache
+ *
+ * `createTenantCacheKey` builds `tenant:<id>:<key>`, which `@zudojs/cache`
+ * refuses: its key parts may not contain the `:` separator, precisely so a
+ * raw key cannot forge a namespace. The cache's own tenant boundary is the
+ * `namespace` option, so the compatible shape is a namespace derived from
+ * the tenant id plus the caller's key, passed separately:
+ *
+ * ```ts
+ * const scope = createTenantCacheScope(tenantId, "dashboard.totals");
+ * await cache.get(scope.key, { namespace: scope.namespace });
+ * ```
+ */
+import { ValidationError } from "@zudojs/errors";
+/**
+ * The alphabet `@zudojs/cache` accepts for a key part
+ * (`CACHE_KEY_PATTERN` there). Mirrored rather than imported: tenancy sits
+ * below cache in the dependency tiers.
+ */
+export const TENANT_CACHE_PART_PATTERN = /^[a-zA-Z0-9._-]+$/;
+/** Prefix that keeps tenant namespaces apart from any other namespace. */
+const NAMESPACE_PREFIX = "tenant.";
+/**
+ * Cache namespace for a tenant: `tenant.<tenantId>`.
+ *
+ * Tenant ids are already constrained to `^[a-z0-9][a-z0-9_-]*$`, so the
+ * result always satisfies the cache's part alphabet.
+ */
+export function createTenantCacheNamespace(tenantId) {
+    return `${NAMESPACE_PREFIX}${tenantId}`;
+}
+/**
+ * Build a tenant-scoped cache address that `@zudojs/cache` accepts.
+ *
+ * Isolation comes from the namespace, not from string concatenation, so two
+ * tenants can never share a fully-qualified key whatever `key` is.
+ *
+ * @param tenantId - The owning tenant.
+ * @param key - The resource key within that tenant. Must match
+ *   {@link TENANT_CACHE_PART_PATTERN}; in particular it may not contain `:`.
+ * @throws {ValidationError} when `key` would fail the cache's validation.
+ */
+export function createTenantCacheScope(tenantId, key) {
+    if (typeof key !== "string" || !TENANT_CACHE_PART_PATTERN.test(key)) {
+        throw new ValidationError(`Tenant cache key ${JSON.stringify(key)} must match ${String(TENANT_CACHE_PART_PATTERN)}; use "." or "-" instead of ":" to separate segments.`);
+    }
+    return Object.freeze({
+        namespace: createTenantCacheNamespace(tenantId),
+        key,
+    });
+}

package/dist/tenancyErrors/index.d.ts

@@ -5,4 +5,3 @@
  */
 export { TenantError } from "./tenancyError.base.js";
 export { InvalidTenantIdError, TenantNotFoundError, TenantContextMissingError, TenantResolutionError, TenantResolutionConflictError, TenantUnavailableError, TenantAccessDeniedError, TenantTrustLevelError, TenantAlreadyExistsError, TenantIsolationError, } from "./tenancyError.types.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/tenancyErrors/index.js

@@ -5,4 +5,3 @@
  */
 export { TenantError } from "./tenancyError.base.js";
 export { InvalidTenantIdError, TenantNotFoundError, TenantContextMissingError, TenantResolutionError, TenantResolutionConflictError, TenantUnavailableError, TenantAccessDeniedError, TenantTrustLevelError, TenantAlreadyExistsError, TenantIsolationError, } from "./tenancyError.types.js";
-//# sourceMappingURL=index.js.map

package/dist/tenancyErrors/tenancyError.base.d.ts

@@ -14,4 +14,3 @@ export declare class TenantError extends AuthorizationError {
         readonly cause?: unknown;
     });
 }
-//# sourceMappingURL=tenancyError.base.d.ts.map

package/dist/tenancyErrors/tenancyError.base.js

@@ -16,4 +16,3 @@ export class TenantError extends AuthorizationError {
         });
     }
 }
-//# sourceMappingURL=tenancyError.base.js.map

package/dist/tenancyErrors/tenancyError.types.d.ts

@@ -70,4 +70,3 @@ export declare class TenantAlreadyExistsError extends TenantError {
 export declare class TenantIsolationError extends TenantError {
     constructor(expected: string, actual: string);
 }
-//# sourceMappingURL=tenancyError.types.d.ts.map

package/dist/tenancyErrors/tenancyError.types.js

@@ -118,4 +118,3 @@ export class TenantIsolationError extends TenantError {
         });
     }
 }
-//# sourceMappingURL=tenancyError.types.js.map

package/dist/tenancyTypes/index.d.ts

@@ -8,4 +8,3 @@ export { type Tenant, type TenantResolutionSource, type TenantTrustLevel, type T
 export { type TenantResolution, type TenantResolutionResult, type TenantResolver, type ResolverChainOptions, } from "./resolverTypes.js";
 export { type TenantRepository, type TenantCache, } from "./repositoryTypes.js";
 export { type TenantDomain } from "./repositoryTypes.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/tenancyTypes/index.js

@@ -8,4 +8,3 @@ export {} from "./tenantInterface.js";
 export {} from "./resolverTypes.js";
 export {} from "./repositoryTypes.js";
 export {} from "./repositoryTypes.js";
-//# sourceMappingURL=index.js.map

package/dist/tenancyTypes/repositoryTypes.d.ts

@@ -22,4 +22,3 @@ export interface TenantCache {
     set(tenant: Tenant): Promise<void>;
     delete(id: TenantId): Promise<void>;
 }
-//# sourceMappingURL=repositoryTypes.d.ts.map

package/dist/tenancyTypes/repositoryTypes.js

@@ -4,4 +4,3 @@
  * @module tenancyTypes/repositoryTypes
  */
 export {};
-//# sourceMappingURL=repositoryTypes.js.map

package/dist/tenancyTypes/resolverTypes.d.ts

@@ -43,4 +43,3 @@ export interface ResolverChainOptions {
      */
     readonly throwOnConflict?: boolean;
 }
-//# sourceMappingURL=resolverTypes.d.ts.map

package/dist/tenancyTypes/resolverTypes.js

@@ -4,4 +4,3 @@
  * @module tenancyTypes/resolverTypes
  */
 export {};
-//# sourceMappingURL=resolverTypes.js.map

package/dist/tenancyTypes/tenantIdentity.d.ts

@@ -48,4 +48,3 @@ export declare function tryCreateTenantId(value: unknown): TenantId | undefined;
 export declare function isValidTenantId(value: unknown): value is TenantId;
 /** Tenant lifecycle status. */
 export type TenantStatus = "provisioning" | "active" | "inactive" | "suspended" | "deleting" | "deleted";
-//# sourceMappingURL=tenantIdentity.d.ts.map

package/dist/tenancyTypes/tenantIdentity.js

@@ -59,4 +59,3 @@ export function tryCreateTenantId(value) {
 export function isValidTenantId(value) {
     return tryCreateTenantId(value) !== undefined;
 }
-//# sourceMappingURL=tenantIdentity.js.map

package/dist/tenancyTypes/tenantInterface.d.ts

@@ -44,4 +44,3 @@ export type TenantRequirement = "required" | "optional" | "forbidden";
 export interface TenantResource {
     readonly tenantId: TenantId;
 }
-//# sourceMappingURL=tenantInterface.d.ts.map

package/dist/tenancyTypes/tenantInterface.js

@@ -4,4 +4,3 @@
  * @module tenancyTypes/tenantInterface
  */
 export {};
-//# sourceMappingURL=tenantInterface.js.map

package/dist/utils/index.d.ts

@@ -4,4 +4,3 @@
  * @module utils
  */
 export { isTenantActive, sameTenant, summarizeTenant, summarizeContext, } from "./utils.helper.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.js

@@ -4,4 +4,3 @@
  * @module utils
  */
 export { isTenantActive, sameTenant, summarizeTenant, summarizeContext, } from "./utils.helper.js";
-//# sourceMappingURL=index.js.map

package/dist/utils/utils.helper.d.ts

@@ -21,4 +21,3 @@ export declare function summarizeTenant(tenant: Tenant): string;
  * Create a tenant context summary string for logging.
  */
 export declare function summarizeContext(ctx: TenantContext): string;
-//# sourceMappingURL=utils.helper.d.ts.map

package/dist/utils/utils.helper.js

@@ -27,4 +27,3 @@ export function summarizeTenant(tenant) {
 export function summarizeContext(ctx) {
     return `TenantContext(${ctx.tenantId}, source=${ctx.source}, trust=${ctx.trust})`;
 }
-//# sourceMappingURL=utils.helper.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/tenancy",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Multi-tenant context and isolation with tenant resolution, AsyncLocalStorage propagation, resolver chains, trust levels, and guard middleware.",
   "license": "MIT",
   "author": {
@@ -25,9 +25,9 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.3.1",
-    "@zudojs/constants": "1.1.3",
-    "@zudojs/middleware": "1.1.1"
+    "@zudojs/errors": "1.4.0",
+    "@zudojs/constants": "1.2.0",
+    "@zudojs/middleware": "1.1.3"
   },
   "engines": {
     "node": ">=24.0.0"