@zerotal/tenancy 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -4,10 +4,31 @@ All notable changes to this package are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); this package
 follows the Zerotal monorepo's unified versioning.
 
-**Maturity: `beta`**
+**Maturity: `stable`**
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Added
+
+- **`EnsureTenancyMiddleware` and `TenantStoragePathError` are documented.** Both were
+  public and neither appeared in the guide. `EnsureTenancyMiddleware` is the difference
+  between _resolving_ a tenant and _insisting_ on one — the guide now shows it composed
+  after `TenancyMiddleware`, and says why registering it alone fails every request.
+  `TenantStoragePathError` is the cross-tenant traversal guard: `LocalDriver` confines
+  paths to the disk root rather than the tenant directory, so a key containing `..`
+  reached a sibling tenant's folder and passed the driver's own check. The rejection
+  happens at the prefixing layer, and that is now written down where someone handling
+  upload errors will find it.
+
+### Changed
+
+- **Maturity is now `stable`** — the public API follows SemVer strictly for the rest of
+  the 1.x line. All 22 promised exports are documented, and the property that actually
+  matters here — that one tenant cannot read another's rows, files or cache — is covered
+  by a dedicated cross-tenant security suite rather than inferred from unit tests.
+
 ## [1.0.3] — 2026-08-07
 
 ### Changed

package/README.md

@@ -7,8 +7,8 @@ everywhere in the call stack — ORM queries, storage paths, and cache keys —
 no manual thread-through. Supports both single-database (a `tenant_id` column,
 scoped automatically by `Tenantable`) and multi-database (a connection per tenant,
 routed automatically from a one-line `connect` factory) strategies — in both, your
-models "just work" with no per-query wiring. **Beta** — APIs are stable but rough
-edges remain.
+models "just work" with no per-query wiring. **Stable** — the public API follows
+SemVer strictly for the rest of the 1.x line.
 
 Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zerotal/tenancy",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "license": "MIT",
-  "maturity": "beta",
+  "maturity": "stable",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
@@ -29,8 +29,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.4.0",
-    "@zerotal/orm": "1.4.0"
+    "@zerotal/core": "1.5.0",
+    "@zerotal/orm": "1.5.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/EnsureTenancyMiddleware.ts

@@ -23,7 +23,7 @@ import { TenantContext } from "./TenantContext.ts";
 import { TenantNotFoundError } from "./errors.ts";
 
 export class EnsureTenancyMiddleware extends BaseMiddleware {
-  protected options: {} = {};
+  protected options: Record<string, never> = {};
 
   async handle(_http: HttpContext, next: NextFn): Promise<Response | void> {
     if (TenantContext.tryGet() == null) throw new TenantNotFoundError();

package/src/TenancyMiddleware.ts

@@ -45,7 +45,7 @@ function _authUserId(http: HttpContext): number | null {
 }
 
 export class TenancyMiddleware extends BaseMiddleware {
-  protected options: {} = {};
+  protected options: Record<string, never> = {};
 
   private static _config?: TenancyConfigShape;
 

package/src/Tenantable.ts

@@ -35,6 +35,7 @@ import { TenantContext } from "./TenantContext.ts";
 import { _globalScopeRegistry, ModelQueryBuilder as MQB, HookRegistry } from "@zerotal/orm";
 import type { ModelQueryBuilder } from "@zerotal/orm";
 import type { BaseModel } from "@zerotal/orm";
+import type { ClassRef } from "@zerotal/core";
 
 const SCOPE_NAME = "__tenant__";
 const DEFAULT_COLUMN = "tenant_id";
@@ -52,7 +53,7 @@ function _tenantColumn(ctor: unknown): string {
  * module-load; `TenancyProvider.onBooted()` drains it once the ORM context is live.
  * After boot, new classes are registered immediately via `_markTenantProviderBooted()`.
  */
-export const _pendingTenantable = new Set<Function>();
+export const _pendingTenantable = new Set<ClassRef>();
 let _tenantProviderBooted = false;
 export function _markTenantProviderBooted(): void {
   _tenantProviderBooted = true;
@@ -62,7 +63,7 @@ export function _markTenantProviderBooted(): void {
  * Wire the global query scope and beforeCreate hook onto a model class.
  * Called by `TenancyProvider.onBooted()` for each `Tenantable`-composed class.
  */
-export function registerTenantScoping(cls: Function): void {
+export function registerTenantScoping(cls: ClassRef): void {
   // ── 1. Global query scope ────────────────────────────────────────────────
   const registry = _globalScopeRegistry();
   let scopes = registry.get(cls as unknown as typeof BaseModel);
@@ -118,6 +119,10 @@ export function Tenantable<TBase extends Constructor>(Base: TBase) {
 // ── Augment ModelQueryBuilder with withoutTenancy() ──────────────────────────
 
 declare module "@zerotal/orm" {
+  // Declaration merging requires the type parameter list to match the merged
+  // declaration exactly, so `M` cannot be renamed or dropped even though this
+  // augmentation's body never reads it.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   interface ModelQueryBuilder<M extends BaseModel> {
     /**
      * Remove the tenant global scope for this query only.

package/src/tenantStorage.ts

@@ -169,6 +169,9 @@ export function tenantCache(store?: string, cacheResolver?: CacheResolverLike):
 
 function _resolveCache(): CacheResolverLike {
   try {
+    // Optional peer probed synchronously — a static import would fail when the
+    // package is absent, and this resolver cannot be async.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
     const { Cache } = require("@zerotal/cache") as { Cache: CacheResolverLike };
     return Cache;
   } catch {