@zerotal/tenancy 1.0.0

package/src/TenancyMiddleware.ts

@@ -0,0 +1,136 @@
+/**
+ * TenancyMiddleware — resolves the active tenant and opens a TenantContext boundary.
+ *
+ * You do not register this yourself: `TenancyProvider` adds it to the **global**
+ * pipeline automatically (and it is not exported from the package). It runs on every
+ * request, so once a tenant is resolved every downstream service — `Auth.user()`, model
+ * queries, cache, storage — is transparently scoped to that tenant.
+ *
+ * It is deliberately **lenient about absence**: a request that resolves no tenant simply
+ * continues with no boundary, which is what lets tenant-less routes (login, signup,
+ * marketing) coexist with tenant-scoped ones. That is safe because `Tenantable`'s scope
+ * matches nothing outside a boundary — no tenant means no rows, not everyone's rows. Apply
+ * {@link EnsureTenancyMiddleware} to routes that must *have* a tenant.
+ *
+ * It is **strict about identity**: every resolver except {@link AuthResolver} takes its
+ * identifier from the request (a subdomain, a header, a path segment), so an authenticated
+ * requester who names a tenant must be a member of it. See {@link TenantResolver.trusted}.
+ *
+ * Outcomes:
+ *   - no resolver matches → continue, no boundary (tenant-scoped models return nothing)
+ *   - resolver names a tenant that does not exist → continue, no boundary
+ *   - tenant exists but `isActive` is false → 403
+ *   - signed-in requester named a tenant they do not belong to → 403
+ *   - tenant exists and is active → open the boundary
+ */
+
+import { BaseMiddleware, type NextFn, type HttpContext } from "@zerotal/core";
+import { TenantContext } from "./TenantContext.ts";
+import { TenantModel } from "./TenantModel.ts";
+import { DB } from "@zerotal/orm";
+import { MEMBERS_TABLE } from "./Tenancy.ts";
+import { TenantInactiveError, TenancyNotConfiguredError, TenantForbiddenError } from "./errors.ts";
+import type { Tenant, TenancyConfigShape } from "./types.ts";
+
+/**
+ * The authenticated user's id, or `null` for an anonymous request.
+ *
+ * `AuthenticatedUser` is an empty interface until an app augments it, so reaching `id`
+ * needs one structural view. Kept here so the membership check has exactly one.
+ * @internal
+ */
+function _authUserId(http: HttpContext): number | null {
+  const user = (http as { user?: { id?: unknown } | null }).user;
+  return typeof user?.id === "number" ? user.id : null;
+}
+
+export class TenancyMiddleware extends BaseMiddleware {
+  protected options: {} = {};
+
+  private static _config?: TenancyConfigShape;
+
+  /** Called by TenancyProvider during boot. */
+  static configure(config: TenancyConfigShape): void {
+    TenancyMiddleware._config = config;
+  }
+
+  async handle(http: HttpContext, next: NextFn): Promise<Response | void> {
+    const config = TenancyMiddleware._config;
+    if (!config)
+      throw new TenancyNotConfiguredError(
+        "TenancyMiddleware used before TenancyProvider was booted.",
+      );
+
+    // Try each resolver in order until one identifies a tenant. Each resolver reads
+    // whatever it needs off the HttpContext (route params, the auth user, headers, …).
+    let identifier: string | number | null = null;
+    let by: "slug" | "id" = "slug";
+    let trusted = false;
+    for (const resolver of config.resolvers) {
+      const result = resolver.resolve(http);
+      if (result != null && result.identifier !== "" && result.identifier != null) {
+        identifier = result.identifier;
+        by = result.by ?? "slug";
+        trusted = resolver.trusted === true;
+        break;
+      }
+    }
+
+    // No tenant could be identified — run tenant-less against the default database.
+    // Routes that must have a tenant reject this later via EnsureTenancyMiddleware.
+    if (identifier == null) return next();
+
+    // Load the tenant from the internal registry (owned by @zerotal/tenancy), matching
+    // on slug or primary key depending on how the resolver identified it.
+    const column = by === "id" ? "id" : "slug";
+    const tenant = (await TenantModel.query().where(column, identifier).first()) as Tenant | null;
+
+    // An identifier that maps to no tenant is treated leniently (no boundary) — the
+    // EnsureTenancyMiddleware gate turns this into a 404 only where a tenant is required.
+    if (!tenant) return next();
+
+    // A known-but-disabled tenant is a definitive rejection, surfaced everywhere.
+    if (!tenant.isActive) throw new TenantInactiveError();
+
+    // An authenticated requester who *names* a tenant must belong to it. Subdomains,
+    // headers, path segments and route params are all attacker-chosen, so without this a
+    // user of tenant A reaches tenant B by editing one header — the tenant boundary would
+    // be decided entirely by the client. Anonymous requests are left alone: a public
+    // tenant surface (marketing page, login form) has no membership to check, and nothing
+    // downstream is authorised on identity yet.
+    if (!trusted) {
+      await this._assertMembership(http, tenant);
+    }
+
+    // Attach tenant to http for convenient access in controllers.
+    (http as unknown as Record<string, unknown>)["tenant"] = tenant;
+
+    // Establish the ALS boundary so all downstream code can call TenantContext.get().
+    return new Promise<Response | void>((resolve, reject) => {
+      TenantContext.run(tenant, () => {
+        next().then(resolve, reject);
+      });
+    });
+  }
+
+  /**
+   * Reject an authenticated requester who named a tenant they do not belong to.
+   *
+   * Queries the membership pivot directly rather than going through the `Tenant` facade:
+   * this check runs on every request and must not depend on the container being resolvable,
+   * and `Tenancy.isMember()` reads the *current* tenant id — which is precisely the tenant
+   * we have not entered yet.
+   *
+   * @throws {@link TenantForbiddenError} When a signed-in user is not a member.
+   */
+  private async _assertMembership(http: HttpContext, tenant: Tenant): Promise<void> {
+    const userId = _authUserId(http);
+    if (userId === null) return; // anonymous — nothing to check against
+
+    const row = await DB.table(MEMBERS_TABLE)
+      .where("tenant_id", tenant.id)
+      .where("user_id", userId)
+      .first();
+    if (!row) throw new TenantForbiddenError();
+  }
+}

package/src/TenantContext.ts

@@ -0,0 +1,56 @@
+/**
+ * TenantContext — AsyncLocalStorage-based tenant store.
+ *
+ * Once TenancyMiddleware resolves a tenant and calls `TenantContext.run()`,
+ * every async operation downstream (including ORM queries, mail jobs, queue
+ * workers dispatched from within the same request) can call
+ * `TenantContext.get()` to retrieve the active tenant without threading it
+ * manually through function arguments.
+ *
+ * This parallels how RequestContext works in @zerotal/core.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import { NoActiveTenantError } from "./errors.ts";
+import type { Tenant } from "./types.ts";
+
+const _storage = new AsyncLocalStorage<Tenant>();
+
+export class TenantContext {
+  /**
+   * Execute `callback` inside a tenant boundary.
+   * Called by TenancyMiddleware before forwarding to the next handler.
+   */
+  static run<T>(tenant: Tenant, callback: () => T): T {
+    return _storage.run(tenant, callback);
+  }
+
+  /**
+   * Return the active tenant.
+   * Throws if called outside a tenant context (i.e. without TenancyMiddleware).
+   */
+  static get(): Tenant {
+    const t = _storage.getStore();
+    if (!t) throw new NoActiveTenantError();
+    return t;
+  }
+
+  /**
+   * Return the active tenant, or undefined if called outside a tenant context.
+   * Useful in shared code that runs in both tenant and non-tenant contexts
+   * (CLI commands, background jobs that process all tenants).
+   */
+  static tryGet(): Tenant | undefined {
+    return _storage.getStore();
+  }
+
+  /** Convenience: return the current tenant's id, or null outside a context. */
+  static id(): number | null {
+    return _storage.getStore()?.id ?? null;
+  }
+
+  /** Convenience: return the current tenant's slug, or null outside a context. */
+  static slug(): string | null {
+    return _storage.getStore()?.slug ?? null;
+  }
+}

package/src/TenantManager.ts

@@ -0,0 +1,93 @@
+/**
+ * TenantManager — the per-tenant database connection pool for the multi-database
+ * strategy. You normally never touch it directly: when you give `TenancyConfig` a
+ * `connect` factory, `TenancyProvider` builds a TenantManager from it and registers
+ * an ORM connection resolver, so every model query inside a tenant boundary is routed
+ * to the right database automatically.
+ *
+ * It is exported for the rare case where you need the raw connection for a tenant
+ * outside the ORM (a manual migration, a bulk import). In the single-database strategy
+ * you don't need this class at all — `Tenantable` isolates via `WHERE tenant_id = ?`.
+ *
+ * @example
+ * // Pre-warm connections for all known tenants at startup:
+ * const tenants = await Tenant.all();
+ * for (const t of tenants) manager.warmUp(t);
+ */
+
+import type { SQLInstance } from "@zerotal/orm";
+import { TenantContext } from "./TenantContext.ts";
+import type { MultiDbTenant, Tenant } from "./types.ts";
+
+export interface TenantManagerOptions {
+  /**
+   * Factory that opens a new database connection for the given tenant.
+   * Called once per tenant on first use; the result is cached.
+   */
+  connect(tenant: MultiDbTenant): SQLInstance;
+}
+
+export class TenantManager {
+  private readonly _pool = new Map<number, SQLInstance>();
+  private readonly _opts: TenantManagerOptions;
+
+  constructor(opts: TenantManagerOptions) {
+    this._opts = opts;
+  }
+
+  /**
+   * Return the database connection for the currently active tenant.
+   * Throws if called outside a TenantContext boundary.
+   */
+  connection(): SQLInstance {
+    const tenant = TenantContext.get() as MultiDbTenant;
+    return this._forTenant(tenant);
+  }
+
+  /**
+   * Return the database connection for a specific tenant without requiring
+   * an active TenantContext. Useful in background jobs that iterate tenants.
+   */
+  connectionFor(tenant: MultiDbTenant): SQLInstance {
+    return this._forTenant(tenant);
+  }
+
+  /**
+   * Pre-open the connection for a tenant so the first request is instant.
+   * Safe to call at boot time before any requests arrive.
+   */
+  warmUp(tenant: MultiDbTenant): void {
+    this._forTenant(tenant);
+  }
+
+  /** Close and evict a tenant's connection (e.g. after a tenant is deleted). */
+  evict(tenant: Tenant): void {
+    const conn = this._pool.get(tenant.id);
+    if (conn) _closeConnection(conn);
+    this._pool.delete(tenant.id);
+  }
+
+  /** Close all open connections. */
+  closeAll(): void {
+    for (const [id, conn] of this._pool) {
+      _closeConnection(conn);
+      this._pool.delete(id);
+    }
+  }
+
+  private _forTenant(tenant: MultiDbTenant): SQLInstance {
+    let conn = this._pool.get(tenant.id);
+    if (!conn) {
+      conn = this._opts.connect(tenant);
+      this._pool.set(tenant.id, conn);
+    }
+    return conn;
+  }
+}
+
+/** Close a connection via whichever teardown method it exposes (`end`/`close`). */
+function _closeConnection(conn: SQLInstance): void {
+  const c = conn as unknown as { end?: () => unknown; close?: () => unknown };
+  if (typeof c.end === "function") c.end();
+  else if (typeof c.close === "function") c.close();
+}

package/src/TenantModel.ts

@@ -0,0 +1,25 @@
+import { BaseModel, column, table } from "@zerotal/orm";
+
+/**
+ * The internal tenant record — owned by `@zerotal/tenancy` (like `AuditLog` is owned
+ * by `@zerotal/audit`). Its table (`tenants`) and the `tenant_members` pivot are
+ * provisioned on boot by `tenantSchemaConcern`, so apps don't define a tenant model
+ * or write migrations for it. Reach tenants through the `Tenant` facade, not this
+ * class directly.
+ *
+ * `TenantModel` is deliberately NOT `Tenantable` — it lives in the central/platform
+ * database and is what bootstraps a tenant context, not something scoped within one.
+ */
+@(table("tenants").withTimestamps())
+export class TenantModel extends BaseModel {
+  @column() slug!: string;
+  @column() name!: string;
+  @column("boolean") isActive!: boolean;
+  /**
+   * Connection target for the multi-database strategy; null in single-database.
+   * Nullable so a single-database `Tenant.create()` (no `database`) doesn't violate a
+   * NOT NULL column — this must match `tenantSchemaConcern`, and it is what the ORM's
+   * model auto-synchronize uses when it provisions the `tenants` table.
+   */
+  @column({ nullable: true }) database?: string | null;
+}

package/src/Tenantable.ts

@@ -0,0 +1,138 @@
+// ── Tenantable ──────────────────────────────────────────────────────────────
+//
+// Multi-tenant model mixin. Compose it via `BaseModelWith`, like every other mixin:
+//
+//   import { BaseModelWith, column, table } from "@zerotal/orm";
+//   import { Tenantable } from "@zerotal/tenancy";
+//
+//   @table("projects").withTimestamps()
+//   export class Project extends BaseModelWith(Tenantable) {
+//     @column() name!: string;
+//     @column() tenantId!: number;
+//   }
+//
+// Configure the tenant FK column by overriding the static field (default
+// `tenant_id`):
+//
+//   protected static tenantColumn = "org_id";
+//
+// It registers two behaviours against the model:
+//   1. Query scoping — every SELECT/UPDATE/DELETE gets `WHERE <col> = <tenant id>`
+//      via the ORM global-scope system. Outside a tenant context the scope matches
+//      *nothing*, so a missing boundary is an empty result, never every tenant's rows.
+//   2. Create injection — inside a boundary the tenant column is set from the context and
+//      is authoritative, so a client-supplied `tenant_id` cannot redirect the write.
+//
+//   const projects = await Project.all();              // … WHERE tenant_id = 7
+//   const all = await Project.query().withoutTenancy().get(); // bypass for admin
+//
+// Registration is deferred: the mixin enqueues the anonymous class at module-load
+// (before the ORM context is live) and TenancyProvider.onBooted() drains the queue
+// and wires each class to the live ORM context. This matches the Auditable pattern
+// and avoids hooks/scopes being lost when registerAppScope resets the ORM context.
+
+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";
+
+const SCOPE_NAME = "__tenant__";
+const DEFAULT_COLUMN = "tenant_id";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- generic mixin base bound
+type Constructor<T = object> = new (...args: any[]) => T;
+
+/** Resolve the tenant column for a concrete model class (honours static override). */
+function _tenantColumn(ctor: unknown): string {
+  return (ctor as { tenantColumn?: string })?.tenantColumn ?? DEFAULT_COLUMN;
+}
+
+/**
+ * Classes awaiting tenant-scope registration. `Tenantable` adds to this set at
+ * 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>();
+let _tenantProviderBooted = false;
+export function _markTenantProviderBooted(): void {
+  _tenantProviderBooted = true;
+}
+
+/**
+ * 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 {
+  // ── 1. Global query scope ────────────────────────────────────────────────
+  const registry = _globalScopeRegistry();
+  let scopes = registry.get(cls as unknown as typeof BaseModel);
+  if (!scopes) {
+    scopes = new Map();
+    registry.set(cls as unknown as typeof BaseModel, scopes);
+  }
+  scopes.set(SCOPE_NAME, (qb: ModelQueryBuilder<BaseModel>) => {
+    const column = _tenantColumn((qb as unknown as { _ModelClass?: unknown })._ModelClass);
+    const tenantId = TenantContext.id();
+    if (tenantId !== null) {
+      qb.where(column, tenantId);
+      return;
+    }
+    // No tenant context: match nothing rather than everything. A tenant-scoped model
+    // queried outside a boundary — the apex domain, a queue worker, a resolver that found
+    // no tenant — otherwise returned every tenant's rows, and did it silently. Failing
+    // closed turns that into an obviously-empty result, and code that genuinely wants
+    // cross-tenant reach says so with `withoutTenancy()`.
+    qb.whereRaw("1 = 0");
+  });
+
+  // ── 2. Set the tenant column on create ───────────────────────────────────
+  HookRegistry.register(cls as unknown as typeof BaseModel, "beforeCreate", (model: BaseModel) => {
+    const column = _tenantColumn(model.constructor);
+    const rec = model as unknown as Record<string, unknown>;
+    const tenantId = TenantContext.id();
+    // Inside a boundary the context is authoritative and overwrites whatever is there.
+    // Fill-if-absent made the column mass-assignable: `Project.create(request.all())` with
+    // an attacker-supplied `tenant_id` wrote straight into another tenant, with the
+    // mass-assignment guard as the only thing in the way. Cross-tenant writes are done by
+    // running inside that tenant's context, not by naming it in the payload.
+    if (tenantId !== null) rec[column] = tenantId;
+  });
+}
+
+export function Tenantable<TBase extends Constructor>(Base: TBase) {
+  const cls = class extends Base {
+    /** Tenant foreign-key column. Override per model to change it. */
+    static tenantColumn = DEFAULT_COLUMN;
+  };
+
+  _pendingTenantable.add(cls);
+  if (_tenantProviderBooted) {
+    // Provider already booted — register into the live context now.
+    // The class stays in _pendingTenantable so future onBooted() calls
+    // (new Application instances) re-register it into the new context.
+    registerTenantScoping(cls);
+  }
+  return cls;
+}
+
+// ── Augment ModelQueryBuilder with withoutTenancy() ──────────────────────────
+
+declare module "@zerotal/orm" {
+  interface ModelQueryBuilder<M extends BaseModel> {
+    /**
+     * Remove the tenant global scope for this query only.
+     *
+     * @example
+     * // Admin route — load all projects across tenants:
+     * const all = await Project.query().withoutTenancy().get();
+     */
+    withoutTenancy(): this;
+  }
+}
+
+// Patch the prototype once at module-load time.
+(MQB.prototype as unknown as Record<string, unknown>)["withoutTenancy"] = function (
+  this: ModelQueryBuilder<BaseModel>,
+): ModelQueryBuilder<BaseModel> {
+  return this.withoutGlobalScope(SCOPE_NAME);
+};

package/src/config.ts

@@ -0,0 +1,38 @@
+/**
+ * Tenancy config factory.
+ *
+ * @example
+ * // config/tenancy.ts
+ * import { TenancyConfig, SubdomainResolver } from "@zerotal/tenancy";
+ *
+ * export default TenancyConfig({
+ *   strategy: "single-database",
+ *   resolvers: [new SubdomainResolver("myapp.com")],
+ * });
+ *
+ * The tenant registry (`tenants` table) is owned by the package — no `findTenant`
+ * callback or app tenant model needed. Reach tenants via the `Tenant` facade.
+ */
+
+import { deepMerge } from "@zerotal/core";
+import type { TenancyConfigShape } from "./types.ts";
+
+// `resolvers` has no default — it is required from the caller. deepMerge passes the
+// resolver instances through by reference (it only deep-clones plain objects/arrays).
+const defaults: Partial<TenancyConfigShape> = {
+  strategy: "single-database",
+  tenantColumn: "tenant_id",
+};
+
+export function TenancyConfig(
+  config: Partial<TenancyConfigShape> & Pick<TenancyConfigShape, "resolvers">,
+): TenancyConfigShape {
+  return deepMerge(defaults as TenancyConfigShape, config);
+}
+
+// Register this package's config namespace for typed config() dot-paths.
+declare module "@zerotal/core" {
+  interface ConfigRegistry {
+    tenancy: TenancyConfigShape;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,86 @@
+import { HttpError, ZerotalError } from "@zerotal/core";
+
+/**
+ * No tenant could be resolved from the request, or the resolved identifier
+ * doesn't match any tenant. Renders as a 404 (content-negotiated by the
+ * framework's exception handler).
+ */
+export class TenantNotFoundError extends HttpError {
+  constructor(message = "This account doesn’t exist.") {
+    super(message, 404, "E_TENANT_NOT_FOUND");
+  }
+}
+
+/**
+ * The tenant exists but is not active (`is_active === false`). Renders as a 403.
+ */
+export class TenantInactiveError extends HttpError {
+  constructor(message = "This account has been disabled.") {
+    super(message, 403, "E_TENANT_INACTIVE");
+  }
+}
+
+/**
+ * Tenancy was used before it was configured — `TenancyProvider` isn't registered
+ * or `TenancyMiddleware` ran before boot. A misconfiguration (500).
+ */
+export class TenancyNotConfiguredError extends HttpError {
+  constructor(
+    message = "Tenancy is not configured. Register TenancyProvider and apply TenancyMiddleware.",
+  ) {
+    super(message, 500, "E_TENANCY_NOT_CONFIGURED");
+  }
+}
+
+/**
+ * The current user tried an admin-only tenant action (`update`/`delete`) without
+ * being an admin member of the tenant. Renders as a 403. Use the `force*` variants
+ * to bypass the check from trusted server code.
+ */
+export class TenantForbiddenError extends HttpError {
+  constructor(message = "You don’t have permission to manage this account.") {
+    super(message, 403, "E_TENANT_FORBIDDEN");
+  }
+}
+
+/**
+ * A required companion package or configuration for a tenancy feature is missing
+ * (e.g. `tenantDisk()` without a configured disk). A misconfiguration (500).
+ */
+export class TenancyConfigError extends ZerotalError {
+  constructor(message: string) {
+    super(message, "E_TENANCY_CONFIG", 500);
+  }
+}
+
+/**
+ * `TenantContext.get()` (or `Tenant.current()`) was called outside an active
+ * tenant boundary. A programming error — wrap the code in TenancyMiddleware, or
+ * use `TenantContext.getOrNull()` in shared (tenant + non-tenant) code.
+ */
+export class NoActiveTenantError extends ZerotalError {
+  constructor(
+    message = "No active tenant. This code ran outside a tenant boundary — is TenancyMiddleware applied? (use TenantContext.getOrNull() in shared code).",
+  ) {
+    super(message, "E_NO_ACTIVE_TENANT", 500);
+  }
+}
+
+/**
+ * Raised when a caller-supplied storage key would escape the active tenant's directory.
+ *
+ * `tenantDisk()` prefixes keys with `tenants/<slug>/`, but the underlying LocalDriver confines
+ * paths to the *disk root*, not the tenant directory — so a key containing `..` resolved to a
+ * sibling tenant's folder and passed the driver's own check. Traversal is rejected at the
+ * prefixing layer instead.
+ */
+export class TenantStoragePathError extends ZerotalError {
+  constructor(path: string, slug: string) {
+    super(
+      `Storage path "${path}" is not allowed for tenant "${slug}": it would resolve outside ` +
+        `the tenant's directory. Use a relative key with no ".." segments and no leading "/".`,
+      "E_TENANT_STORAGE_PATH",
+      400,
+    );
+  }
+}

package/src/facades/Tenant.ts

@@ -0,0 +1,32 @@
+import { createFacade } from "@zerotal/core";
+import type { Tenancy } from "../Tenancy.ts";
+import type { Tenant as TenantRecord } from "../types.ts";
+
+declare module "@zerotal/core" {
+  interface ContainerBindings {
+    tenancy: Tenancy;
+  }
+}
+
+/**
+ * Tenant facade — the primary entry point to tenancy.
+ *
+ * @example
+ * import { Tenant } from "@zerotal/tenancy";
+ *
+ * Tenant.current();           // the active tenant (or null)
+ * Tenant.check();             // is there an active, enabled tenant?
+ * await Tenant.members();     // hydrated User models
+ * await Tenant.update({ name }); // admin-gated
+ *
+ * (The `Tenant` *type* — the tenant record shape — is exported separately and
+ * coexists with this value, so `Tenant.current(): Tenant` reads naturally.)
+ */
+export const Tenant = createFacade("tenancy");
+
+/**
+ * The tenant **record** shape (`{ id, slug, name, isActive, … }`). Shares the `Tenant`
+ * name with the facade value above — value and type namespaces coexist — so both
+ * `Tenant.current()` (value) and `: Tenant` (type) read naturally from one import.
+ */
+export type Tenant = TenantRecord;

package/src/index.ts

@@ -0,0 +1,55 @@
+// @zerotal/tenancy — public API
+
+// Facade + service (the primary entry point). The `Tenant` export is both the facade
+// *value* and the tenant-record *type* (they share the name from one module).
+export { Tenant } from "./facades/Tenant.ts";
+export { Tenancy } from "./Tenancy.ts";
+export type { TenantDeletedHook } from "./Tenancy.ts";
+export { TenantModel } from "./TenantModel.ts";
+
+// Core
+export { TenantContext } from "./TenantContext.ts";
+// TenancyMiddleware is intentionally NOT exported — TenancyProvider registers it globally.
+// Apps gate tenant-required routes with EnsureTenancyMiddleware instead.
+export { EnsureTenancyMiddleware } from "./EnsureTenancyMiddleware.ts";
+export { TenancyProvider } from "./provider/TenancyProvider.ts";
+export { TenantManager } from "./TenantManager.ts";
+export type { TenantManagerOptions } from "./TenantManager.ts";
+
+// Resolvers
+export { SubdomainResolver } from "./resolvers/SubdomainResolver.ts";
+export { HeaderResolver } from "./resolvers/HeaderResolver.ts";
+export { PathResolver } from "./resolvers/PathResolver.ts";
+export { RouteParamResolver } from "./resolvers/RouteParamResolver.ts";
+export { AuthResolver } from "./resolvers/AuthResolver.ts";
+
+// Model mixin
+export { Tenantable } from "./Tenantable.ts";
+
+// Storage / Cache helpers
+export { tenantDisk, tenantCache } from "./tenantStorage.ts";
+
+// Config
+export { TenancyConfig } from "./config.ts";
+
+// Errors
+export {
+  TenantNotFoundError,
+  TenantInactiveError,
+  TenantForbiddenError,
+  TenancyNotConfiguredError,
+  TenancyConfigError,
+  TenantStoragePathError,
+  NoActiveTenantError,
+} from "./errors.ts";
+
+// Types
+// Note: the `Tenant` record type is exported from ./facades/Tenant.ts (alongside the
+// facade value), so it is intentionally absent here.
+export type {
+  MultiDbTenant,
+  TenantResolver,
+  TenantResolverResult,
+  TenancyStrategy,
+  TenancyConfigShape,
+} from "./types.ts";