@zerotal/tenancy 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog — @zerotal/tenancy
+
+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`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Changed
+
+- Moved service provider to `src/provider/`.
+- Config factory renamed to `TenancyConfig` (PascalCase) with a deprecated `tenancyConfig` alias.
+- Added test suite covering tenant isolation.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+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

@@ -0,0 +1,205 @@
+# @zerotal/tenancy
+
+> First-class multi-tenancy: resolve the active tenant per request and scope ORM, storage, and cache.
+
+Resolves the active tenant from every incoming request and makes it available
+everywhere in the call stack — ORM queries, storage paths, and cache keys — with
+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.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/tenancy
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { TenancyProvider } from "@zerotal/tenancy";
+import tenancyConfig from "../config/tenancy.ts";
+
+export default [
+  // …your other providers
+  TenancyProvider.withConfig(tenancyConfig),
+];
+```
+
+Configure it in `config/tenancy.ts`:
+
+```ts
+// config/tenancy.ts
+import { TenancyConfig, SubdomainResolver } from "@zerotal/tenancy";
+import { env } from "@zerotal/core";
+
+export default TenancyConfig({
+  strategy: env("TENANCY_STRATEGY", "single-database"),
+  tenantColumn: "tenant_id",
+  resolvers: [new SubdomainResolver("myapp.com")],
+});
+```
+
+The tenant registry is **owned by the package** — the `tenants` and `tenant_members`
+tables are provisioned automatically on boot (no migration, no app `Tenant` model,
+no `findTenant` callback). Reach tenants through the `Tenant` facade.
+
+Then add `TenancyMiddleware` to the global pipeline (or a route group):
+
+```ts
+import { TenancyMiddleware } from "@zerotal/tenancy";
+
+Application.create({ providers }).use([TenancyMiddleware]);
+```
+
+## Usage
+
+Compose `Tenantable` via `BaseModelWith` onto any tenant-owned model (the same flat
+form used for every other mixin). Every query is scoped with
+`WHERE tenant_id = <current tenant>` and `create()` injects the `tenant_id`:
+
+```ts
+import { BaseModelWith, column, table } from "@zerotal/orm";
+import { Tenantable } from "@zerotal/tenancy";
+
+@table("projects")
+export class Project extends BaseModelWith(Tenantable) {
+  @column() name!: string;
+  @column() tenantId!: number;
+}
+
+// Inside a TenancyMiddleware boundary (tenant id = 7):
+await Project.all(); // SELECT * FROM projects WHERE tenant_id = 7
+await Project.create({ name: "A" }); // INSERT … (tenant_id, name) VALUES (7, 'A')
+```
+
+Bypass scoping when you need cross-tenant access, or run a job under a specific
+tenant:
+
+```ts
+import { TenantContext } from "@zerotal/tenancy";
+
+await Project.query().withoutTenancy().get(); // all tenants
+
+await TenantContext.run(tenant, async () => {
+  // queries here run scoped to `tenant`
+});
+```
+
+Access the active tenant anywhere in the async call chain, and scope storage and
+cache to it:
+
+```ts
+import { TenantContext, tenantDisk, tenantCache } from "@zerotal/tenancy";
+
+const tenant = TenantContext.get(); // throws outside a boundary
+const id = TenantContext.id(); // number | null
+
+await tenantDisk().put("avatars/alice.jpg", buffer); // → tenants/<slug>/avatars/alice.jpg
+await tenantCache().set("dashboard:stats", data, 300); // key: tenant:<slug>:dashboard:stats
+```
+
+### The `Tenant` facade
+
+The `Tenant` facade carries the day-to-day tenancy API — the current tenant, tenant
+CRUD, and membership (the `tenant_members` pivot). Mutations are admin-gated against
+the authenticated user; `force*` variants bypass the check for trusted code.
+
+```ts
+import { Tenant } from "@zerotal/tenancy";
+
+// Current tenant (inside a TenancyMiddleware boundary)
+Tenant.current(); // the active tenant, or null
+Tenant.check(); // true when there is an active, enabled tenant
+Tenant.id(); // number | null
+
+// Lifecycle — the authenticated creator becomes the first admin member
+const acme = await Tenant.create({ slug: "acme", name: "Acme Inc." });
+await Tenant.update({ name: "Acme LLC" }); // requires the current user to be an admin
+await Tenant.forceUpdate({ name: "Acme LLC" }); // bypasses the admin check
+await Tenant.delete(); // admin-gated; removes the tenant + its memberships
+await Tenant.forceDelete();
+
+// Membership — members() hydrates full User models from the ORM registry
+await Tenant.addMember(userId, { admin: true });
+await Tenant.members(); // User[]
+await Tenant.member(); // the authenticated user as a member, or null
+await Tenant.isMember(userId);
+await Tenant.isMemberAdmin(userId);
+await Tenant.promote(userId);
+await Tenant.demote(userId);
+await Tenant.removeMember(userId);
+
+// Reads + running work under a tenant
+await Tenant.find("acme"); // by slug
+await Tenant.findById(1);
+await Tenant.exists("acme");
+await Tenant.all();
+await Tenant.forId(1, () => Project.all()); // run a callback inside tenant #1's context
+```
+
+Membership hydration needs an authenticatable `User` model — compose
+`Authenticatable` from `@zerotal/auth` on it. Tenancy discovers it via the ORM
+registry, so there's no hard dependency between the two packages.
+
+Clean up tenant-owned data when a tenant is deleted:
+
+```ts
+import { Tenant } from "@zerotal/tenancy";
+
+Tenant.onTenantDeleted(async (tenant) => {
+  await Project.query().withoutTenancy().where("tenant_id", tenant.id).delete();
+});
+```
+
+### Multi-database
+
+For the database-per-tenant strategy, set `strategy: "multi-database"` and supply a
+one-line `connect` factory. Every model query inside a tenant boundary is then routed
+to that tenant's connection automatically — no `TenantManager` wiring, no raw SQL,
+the same `Project.all()` you already write:
+
+```ts
+// config/tenancy.ts
+import { TenancyConfig, SubdomainResolver } from "@zerotal/tenancy";
+import { SQL } from "bun";
+
+export default TenancyConfig({
+  strategy: "multi-database",
+  resolvers: [new SubdomainResolver("myapp.com")],
+  connect: (tenant) => new SQL(`file:./storage/tenants/${tenant.database}`),
+});
+```
+
+Routing is `AsyncLocalStorage`-scoped, so concurrent requests for different tenants
+stay isolated. See the [tenancy guide](../../docs/tenancy.md#multi-database-strategy)
+for details.
+
+## Exports
+
+- `Tenant` — the facade: current tenant, tenant CRUD, and membership.
+- `Tenancy` — the service behind the facade (bound as `"tenancy"`).
+- `TenantModel` — the internal tenant record (owned by the package; reach it via `Tenant`).
+- `TenantDeletedHook` — type of the `Tenant.onTenantDeleted` callback.
+- `TenantContext` — access the active tenant (`get`, `tryGet`, `id`, `slug`, `run`).
+- `TenancyMiddleware` — resolves the tenant per request.
+- `TenancyProvider` — wires tenancy (`.withConfig(...)`).
+- `TenantManager` / `TenantManagerOptions` — per-tenant connections (multi-database).
+- Resolvers: `SubdomainResolver`, `HeaderResolver`, `PathResolver`.
+- `Tenantable` — ORM mixin that scopes queries to the current tenant.
+- `tenantDisk`, `tenantCache` — tenant-scoped storage and cache helpers.
+- `TenancyConfig`, `tenancyConfig` — config factory.
+- Errors: `TenantNotFoundError`, `TenantInactiveError`, `TenantForbiddenError`,
+  `TenancyNotConfiguredError`, `TenancyConfigError`, `NoActiveTenantError`.
+- Types: `Tenant`, `MultiDbTenant`, `TenantResolver`, `TenantResolverResult`,
+  `TenancyStrategy`, `TenancyConfigShape`.
+
+## Documentation
+
+- [Multi-Tenancy](../../docs/tenancy.md)

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@zerotal/tenancy",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "beta",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0",
+    "@zerotal/orm": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Multi-tenancy primitives for Zerotal applications.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/tenancy"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/tenancy#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/EnsureTenancyMiddleware.ts

@@ -0,0 +1,32 @@
+/**
+ * EnsureTenancyMiddleware — gate a route on an active tenant.
+ *
+ * `TenancyMiddleware` (registered globally by `TenancyProvider`) has already tried to
+ * resolve and open the tenant boundary by the time this runs; this middleware simply
+ * asserts that it succeeded. If there is no active tenant it responds **404**; otherwise
+ * the tenant is guaranteed to be present for the rest of the request.
+ *
+ * Apply it to route groups that only make sense inside a tenant — e.g. everything under a
+ * `/:tenancy` prefix, or an `acme.myapp.com` subdomain group:
+ *
+ * @example
+ * // bootstrap/app.ts
+ * .fileBasedRouting({
+ *   dir: basePath("app/flow/pages/[tenancy]"),
+ *   prefix: "/:tenancy",
+ *   middleware: [EnsureTenancyMiddleware],
+ * });
+ */
+
+import { BaseMiddleware, type NextFn, type HttpContext } from "@zerotal/core";
+import { TenantContext } from "./TenantContext.ts";
+import { TenantNotFoundError } from "./errors.ts";
+
+export class EnsureTenancyMiddleware extends BaseMiddleware {
+  protected options: {} = {};
+
+  async handle(_http: HttpContext, next: NextFn): Promise<Response | void> {
+    if (TenantContext.tryGet() == null) throw new TenantNotFoundError();
+    return next();
+  }
+}

package/src/Tenancy.ts

@@ -0,0 +1,256 @@
+import { RequestContext } from "@zerotal/core";
+import { DB, modelsByName, type BaseModel } from "@zerotal/orm";
+import { TenantContext } from "./TenantContext.ts";
+import { TenantModel } from "./TenantModel.ts";
+import { NoActiveTenantError, TenantForbiddenError, TenancyConfigError } from "./errors.ts";
+import type { Tenant } from "./types.ts";
+
+/** The `tenant_members` pivot — central table linking users to tenants. */
+/**
+ * Pivot table holding tenant membership.
+ * @internal exported so {@link TenancyMiddleware} can check membership without going
+ * through the container-resolved facade — the check must hold on every request, including
+ * ones served before or outside a fully-booted container.
+ */
+export const MEMBERS_TABLE = "tenant_members";
+
+/** Same brand `@zerotal/auth` stamps on the User model — referenced via `Symbol.for`
+ *  so tenancy can find the user model without depending on the auth package. */
+const AUTHENTICATABLE = Symbol.for("zerotal.auth.authenticatable");
+
+type UserCtor = typeof BaseModel & {
+  find(id: number): Promise<BaseModel | null>;
+  query(): { whereIn(c: string, v: unknown[]): { get(): Promise<BaseModel[]> } };
+};
+
+/** Hook fired after a tenant is deleted, for app-level cleanup of tenant-owned data. */
+export type TenantDeletedHook = (tenant: Tenant) => void | Promise<void>;
+
+/**
+ * Tenancy service — the engine behind the `Tenant` facade. Implements the current-
+ * tenant lifecycle, tenant CRUD against the internal `TenantModel`, and membership
+ * (the `tenant_members` pivot) with admin-gated mutations.
+ *
+ * Resolved from the container as `"tenancy"`; use it via the `Tenant` facade.
+ */
+export class Tenancy {
+  private readonly _onDeleted: TenantDeletedHook[] = [];
+
+  // ── Current tenant ──────────────────────────────────────────────────────────
+
+  /** The active tenant, or null outside a tenant boundary. */
+  current(): Tenant | null {
+    return TenantContext.tryGet() ?? null;
+  }
+
+  /** True when there is an active, enabled tenant. */
+  check(): boolean {
+    const t = this.current();
+    return !!t && t.isActive;
+  }
+
+  /** The active tenant's id, or null. */
+  id(): number | null {
+    return this.current()?.id ?? null;
+  }
+
+  /** The active tenant's slug, or null. */
+  slug(): string | null {
+    return this.current()?.slug ?? null;
+  }
+
+  /** @internal The active tenant, or throw if outside a tenant boundary. */
+  private requireCurrent(): Tenant {
+    const t = TenantContext.tryGet();
+    if (!t) throw new NoActiveTenantError();
+    return t;
+  }
+
+  // ── Running work inside a tenant ─────────────────────────────────────────────
+
+  /** Run `cb` with `tenant` as the active tenant (jobs, CLI, cross-tenant loops). */
+  run<T>(tenant: Tenant, cb: () => T): T {
+    return TenantContext.run(tenant, cb);
+  }
+
+  /** Load the tenant with `id` and run `cb` inside its context. */
+  async forId<T>(id: number, cb: () => T | Promise<T>): Promise<T> {
+    const tenant = await TenantModel.findOrFail(id);
+    return TenantContext.run(tenant as unknown as Tenant, () => cb());
+  }
+
+  // ── Reads ─────────────────────────────────────────────────────────────────
+
+  find(slug: string): Promise<TenantModel | null> {
+    return TenantModel.query().where("slug", slug).first();
+  }
+
+  findById(id: number): Promise<TenantModel | null> {
+    return TenantModel.find(id);
+  }
+
+  all(): Promise<TenantModel[]> {
+    return TenantModel.query().get();
+  }
+
+  async exists(slug: string): Promise<boolean> {
+    return (await this.find(slug)) !== null;
+  }
+
+  // ── Tenant lifecycle ─────────────────────────────────────────────────────────
+
+  /**
+   * Create a new tenant. If a user is authenticated on the current request, they
+   * become the tenant's first **admin** member.
+   */
+  async create(data: Partial<Tenant> & { slug: string; name: string }): Promise<TenantModel> {
+    const tenant = await TenantModel.create({ isActive: true, ...data } as never);
+    const uid = this.currentUserId();
+    if (uid != null) {
+      await DB.table(MEMBERS_TABLE).insert({ tenant_id: tenant.id, user_id: uid, is_admin: 1 });
+    }
+    return tenant;
+  }
+
+  /** Update the current tenant. Throws unless the current user is an admin member. */
+  async update(data: Partial<Tenant>): Promise<TenantModel> {
+    if (!(await this.isMemberAdmin())) throw new TenantForbiddenError();
+    return this.forceUpdate(data);
+  }
+
+  /** Update the current tenant, bypassing the admin check. Use from trusted code only. */
+  async forceUpdate(data: Partial<Tenant>): Promise<TenantModel> {
+    const model = await TenantModel.findOrFail(this.requireCurrent().id);
+    await model.fill(data as never).save();
+    return model;
+  }
+
+  /** Delete the current tenant and its memberships. Throws unless current user is admin. */
+  async delete(): Promise<void> {
+    if (!(await this.isMemberAdmin())) throw new TenantForbiddenError();
+    return this.forceDelete();
+  }
+
+  /** Delete the current tenant and its memberships, bypassing the admin check. */
+  async forceDelete(): Promise<void> {
+    const tenant = this.requireCurrent();
+    await DB.table(MEMBERS_TABLE).where("tenant_id", tenant.id).delete();
+    const model = await TenantModel.find(tenant.id);
+    if (model) await model.delete();
+    for (const hook of this._onDeleted) await hook(tenant);
+  }
+
+  /** Register a cleanup hook fired after a tenant is deleted (drop tenant-owned data). */
+  onTenantDeleted(hook: TenantDeletedHook): void {
+    this._onDeleted.push(hook);
+  }
+
+  // ── Membership ──────────────────────────────────────────────────────────────
+
+  /** The authenticated user as a member of the current tenant, or null if not a member. */
+  async member<T = BaseModel>(): Promise<T | null> {
+    const uid = this.currentUserId();
+    if (uid == null || !(await this.isMember(uid))) return null;
+    return (await this.userModel().find(uid)) as T | null;
+  }
+
+  /** Every member of the current tenant, hydrated as User models. */
+  async members<T = BaseModel>(): Promise<T[]> {
+    const tid = this.requireCurrent().id;
+    const rows = await DB.table(MEMBERS_TABLE).where("tenant_id", tid).get<{ user_id: number }>();
+    const ids = rows.map((r) => r.user_id);
+    if (ids.length === 0) return [];
+    return (await this.userModel().query().whereIn("id", ids).get()) as T[];
+  }
+
+  /** Number of members in the current tenant. */
+  async memberCount(): Promise<number> {
+    return DB.table(MEMBERS_TABLE).where("tenant_id", this.requireCurrent().id).count();
+  }
+
+  /** True when the user (default: current authenticated user) belongs to the current tenant. */
+  async isMember(userId: number | null = this.currentUserId()): Promise<boolean> {
+    const tid = this.id();
+    if (userId == null || tid == null) return false;
+    const row = await DB.table(MEMBERS_TABLE)
+      .where("tenant_id", tid)
+      .where("user_id", userId)
+      .first();
+    return !!row;
+  }
+
+  /** True when the user (default: current authenticated user) is an admin of the current tenant. */
+  async isMemberAdmin(userId: number | null = this.currentUserId()): Promise<boolean> {
+    const tid = this.id();
+    if (userId == null || tid == null) return false;
+    const row = await DB.table(MEMBERS_TABLE)
+      .where("tenant_id", tid)
+      .where("user_id", userId)
+      .first<{ is_admin: number | boolean }>();
+    return !!row && !!row.is_admin;
+  }
+
+  /** Add `userId` to the current tenant (idempotent). Pass `{ admin: true }` for an admin. */
+  async addMember(userId: number, opts: { admin?: boolean } = {}): Promise<void> {
+    const tid = this.requireCurrent().id;
+    const flag = opts.admin ? 1 : 0;
+    const existing = await DB.table(MEMBERS_TABLE)
+      .where("tenant_id", tid)
+      .where("user_id", userId)
+      .first();
+    if (existing) {
+      if (opts.admin !== undefined) {
+        await DB.table(MEMBERS_TABLE)
+          .where("tenant_id", tid)
+          .where("user_id", userId)
+          .update({ is_admin: flag });
+      }
+      return;
+    }
+    await DB.table(MEMBERS_TABLE).insert({ tenant_id: tid, user_id: userId, is_admin: flag });
+  }
+
+  /** Remove `userId` from the current tenant. */
+  async removeMember(userId: number): Promise<void> {
+    await DB.table(MEMBERS_TABLE)
+      .where("tenant_id", this.requireCurrent().id)
+      .where("user_id", userId)
+      .delete();
+  }
+
+  /** Grant the member admin rights in the current tenant. */
+  promote(userId: number): Promise<void> {
+    return this.addMember(userId, { admin: true });
+  }
+
+  /** Revoke the member's admin rights in the current tenant. */
+  demote(userId: number): Promise<void> {
+    return this.addMember(userId, { admin: false });
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────────
+
+  /** The authenticated user's id on the active request, read structurally (no auth dep). */
+  private currentUserId(): number | null {
+    const user = (RequestContext.tryGet() as { user?: { id?: number } } | undefined)?.user;
+    return user?.id ?? null;
+  }
+
+  /** Resolve the app's authenticatable (User) model from the ORM registry. */
+  private userModel(): UserCtor {
+    let first: UserCtor | undefined;
+    for (const model of modelsByName.values()) {
+      if ((model as unknown as Record<symbol, unknown>)[AUTHENTICATABLE]) {
+        if ((model as { name?: string }).name === "User") return model as unknown as UserCtor;
+        first ??= model as unknown as UserCtor;
+      }
+    }
+    if (!first) {
+      throw new TenancyConfigError(
+        "Tenant membership requires an authenticatable User model. Compose `Authenticatable` " +
+          "(from @zerotal/auth) on your User model.",
+      );
+    }
+    return first;
+  }
+}