@zerotal/tenancy 1.0.0

package/src/provider/TenancyProvider.ts

@@ -0,0 +1,136 @@
+/**
+ * TenancyProvider — wires @zerotal/tenancy into the Zerotal application.
+ *
+ * 1. Binds the tenancy config to the container under the `'tenancy'` key.
+ * 2. Configures TenancyMiddleware with the resolved config so it can resolve
+ *    tenants without needing the container on every request.
+ *
+ * @example
+ * // bootstrap/app.ts
+ * import { TenancyProvider } from '@zerotal/tenancy';
+ *
+ * Application.create()
+ *   .register([TenancyProvider, /* … *\/])
+ *   .use([TenancyMiddleware]);   // or attach per-route-group
+ */
+
+import { ServiceProvider } from "@zerotal/core";
+import type { AppEnvironment } from "@zerotal/core";
+import { registerConnectionResolver } from "@zerotal/orm";
+import { TenancyMiddleware } from "../TenancyMiddleware.ts";
+import { TenancyNotConfiguredError, TenancyConfigError } from "../errors.ts";
+import { Tenancy } from "../Tenancy.ts";
+import { TenantManager } from "../TenantManager.ts";
+import { TenantModel } from "../TenantModel.ts";
+import { TenantContext } from "../TenantContext.ts";
+import { tenantSchemaConcern } from "../tenantSchemaConcern.ts";
+import {
+  _pendingTenantable,
+  registerTenantScoping,
+  _markTenantProviderBooted,
+} from "../Tenantable.ts";
+import type { MultiDbTenant, TenancyConfigShape } from "../types.ts";
+
+export class TenancyProvider extends ServiceProvider {
+  static override provides = ["tenancy"] as const;
+  static override environments: AppEnvironment[] = ["web", "console", "worker", "test", "repl"];
+
+  /**
+   * Supply the tenancy configuration.
+   * Call this *before* registering TenancyProvider:
+   *
+   *   TenancyProvider.withConfig(tenancyConfig({ … }));
+   *   Application.create().register([TenancyProvider]);
+   */
+  static withConfig(config: TenancyConfigShape): typeof TenancyProvider {
+    TenancyProvider._config = config;
+    return TenancyProvider;
+  }
+
+  private static _config?: TenancyConfigShape;
+
+  /**
+   * Resolve the active config: an explicit {@link withConfig} call wins, otherwise
+   * the auto-discovered `config/tenancy.ts` (loaded into the container's ConfigManager
+   * under the `tenancy` namespace). This is what makes the common setup a two-liner —
+   * register the provider and drop a `config/tenancy.ts`, no `withConfig()` needed.
+   */
+  private _resolveConfig(): TenancyConfigShape | undefined {
+    if (TenancyProvider._config) return TenancyProvider._config;
+    const config = this.app.container.makeSync("config") as {
+      get(key: string): unknown;
+    };
+    const fromFile = config.get("tenancy") as TenancyConfigShape | undefined;
+    if (fromFile && Array.isArray(fromFile.resolvers)) {
+      TenancyProvider._config = fromFile;
+      return fromFile;
+    }
+    return undefined;
+  }
+
+  /** The per-tenant connection pool for the multi-database strategy (null otherwise). */
+  private static _manager?: TenantManager;
+
+  override onRegister(): void {
+    const config = this._resolveConfig();
+    if (!config) {
+      throw new TenancyNotConfiguredError(
+        "No tenancy config found. Add a `config/tenancy.ts` (default export of TenancyConfig({ … })) " +
+          "or call TenancyProvider.withConfig(TenancyConfig({ … })) before registering the provider.",
+      );
+    }
+    if (config.strategy === "multi-database" && !config.connect) {
+      throw new TenancyConfigError(
+        "The multi-database strategy requires a `connect` factory in TenancyConfig({ … }) " +
+          "so each tenant's database connection can be opened.",
+      );
+    }
+    // The `tenancy` binding is the Tenancy service behind the `Tenant` facade.
+    this.app.container.singleton("tenancy", () => new Tenancy());
+    // Provision the `tenants` + `tenant_members` tables on boot — no migration needed.
+    this.app.registerConcern?.(tenantSchemaConcern);
+  }
+
+  override async onBooted(): Promise<void> {
+    const config = this._resolveConfig() as TenancyConfigShape;
+    TenancyMiddleware.configure(config);
+    // Pre-resolve the `tenancy` singleton so the `Tenant` facade works at request time —
+    // `createFacade` uses `makeSync`, which only returns an already-instantiated singleton.
+    await this.app.container.make("tenancy");
+    // Register the resolver/boundary middleware globally so every request is tenant-aware
+    // (Auth.user(), model queries, cache, storage). It is lenient — routes that *require* a
+    // tenant opt into EnsureTenancyMiddleware. Registered after AuthProvider's
+    // PersistUserMiddleware (its onBooting runs first) so AuthResolver can read `http.user`.
+    this.app.useOnce(TenancyMiddleware as never);
+    for (const cls of _pendingTenantable) {
+      registerTenantScoping(cls);
+    }
+    if (config.strategy === "multi-database" && config.connect) {
+      await this._wireMultiDatabase(config.connect);
+    }
+    _markTenantProviderBooted();
+  }
+
+  /**
+   * Make the multi-database strategy seamless: route every model query inside a tenant
+   * boundary to that tenant's connection via the ORM's context resolver. App models stay
+   * plain — `Project.all()` "just works". The internal `TenantModel` is exempt (the tenant
+   * registry lives in the central/default database).
+   */
+  private async _wireMultiDatabase(
+    connect: NonNullable<TenancyConfigShape["connect"]>,
+  ): Promise<void> {
+    const manager = new TenantManager({ connect });
+    TenancyProvider._manager = manager;
+
+    registerConnectionResolver((ModelClass) => {
+      if (ModelClass === TenantModel) return null; // registry → central DB
+      const tenant = TenantContext.tryGet();
+      return tenant ? manager.connectionFor(tenant as MultiDbTenant) : null;
+    });
+
+    // Drop a tenant's pooled connection when the tenant is deleted.
+    const tenancy = await this.app.container.make<Tenancy>("tenancy");
+    tenancy.onTenantDeleted((tenant) => manager.evict(tenant));
+  }
+}

package/src/resolvers/AuthResolver.ts

@@ -0,0 +1,56 @@
+/**
+ * AuthResolver — resolves the active tenant from the authenticated user.
+ *
+ * The logged-in user carries the tenant it belongs to (default column `tenantId`),
+ * and this resolver reads that foreign key off `http.user` — the user populated
+ * upstream by the auth layer's `PersistUserMiddleware`. Because it reads `http.user`
+ * (typed by core's `AuthenticatedUser`) rather than importing the auth package,
+ * `@zerotal/tenancy` stays decoupled from `@zerotal/auth`.
+ *
+ * Place it after URL-based resolvers so an explicit `/:tenancy` in the path wins,
+ * and the auth user is the fallback for tenant-scoped routes without a slug:
+ *
+ * @example
+ * // config/tenancy.ts
+ * resolvers: [
+ *   new RouteParamResolver({ param: "tenancy" }),
+ *   new AuthResolver(),   // falls back to the logged-in user's tenantId
+ * ]
+ *
+ * Requests with no authenticated user (login, signup) resolve to `null` here — and
+ * with `strict: false` (the default) fall through to the default database.
+ */
+
+import type { HttpContext } from "@zerotal/core";
+import type { TenantResolver, TenantResolverResult } from "../types.ts";
+
+interface AuthResolverOptions {
+  /**
+   * The property on the authenticated user holding the tenant foreign key.
+   * Default: `"tenantId"`.
+   */
+  column?: string;
+}
+
+export class AuthResolver implements TenantResolver {
+  /**
+   * The identifier comes off the authenticated user's own record, so it is by construction
+   * a tenant this requester belongs to — no membership check is needed or meaningful.
+   */
+  readonly trusted = true;
+
+  private readonly column: string;
+
+  constructor(opts: AuthResolverOptions = {}) {
+    this.column = opts.column ?? "tenantId";
+  }
+
+  resolve(http: HttpContext): TenantResolverResult | null {
+    // Read `user` structurally: it is augmented onto HttpContext by @zerotal/auth,
+    // which this package intentionally does not depend on.
+    const user = (http as unknown as { user?: Record<string, unknown> | null }).user;
+    const value = user?.[this.column];
+    if (value === undefined || value === null || value === "") return null;
+    return { identifier: value as string | number, by: "id" };
+  }
+}

package/src/resolvers/HeaderResolver.ts

@@ -0,0 +1,24 @@
+/**
+ * HeaderResolver — extracts the tenant slug from a request header.
+ *
+ * Useful for API-first apps where the client sends the tenant in a header
+ * instead of using subdomains.
+ *
+ * @example
+ * new HeaderResolver('X-Tenant-ID')
+ * // Request: GET /api/users  X-Tenant-ID: acme
+ * // Resolved identifier: 'acme'
+ */
+
+import type { HttpContext } from "@zerotal/core";
+import type { TenantResolver, TenantResolverResult } from "../types.ts";
+
+export class HeaderResolver implements TenantResolver {
+  constructor(private readonly header: string) {}
+
+  resolve(http: HttpContext): TenantResolverResult | null {
+    const value = http.request.headers.get(this.header);
+    if (!value) return null;
+    return { identifier: value.trim() };
+  }
+}

package/src/resolvers/PathResolver.ts

@@ -0,0 +1,52 @@
+/**
+ * PathResolver — extracts the tenant slug from a URL path segment.
+ *
+ * @example
+ * new PathResolver({ segment: 0 })
+ * // Request: GET /acme/dashboard
+ * // Resolved identifier: 'acme'
+ *
+ * new PathResolver({ segment: 1, prefix: '/tenants' })
+ * // Request: GET /tenants/acme/settings
+ * // Resolved identifier: 'acme'
+ */
+
+import type { HttpContext } from "@zerotal/core";
+import type { TenantResolver, TenantResolverResult } from "../types.ts";
+
+interface PathResolverOptions {
+  /**
+   * Zero-based index of the path segment that holds the tenant slug.
+   * Default: 0 (i.e. the first segment after the leading slash).
+   */
+  segment?: number;
+  /**
+   * Optional static prefix to strip before indexing.
+   * Example: prefix '/tenants' with segment 0 matches `/tenants/acme/…`.
+   */
+  prefix?: string;
+}
+
+export class PathResolver implements TenantResolver {
+  private readonly segment: number;
+  private readonly prefix: string;
+
+  constructor(opts: PathResolverOptions = {}) {
+    this.segment = opts.segment ?? 0;
+    this.prefix = opts.prefix ?? "";
+  }
+
+  resolve(http: HttpContext): TenantResolverResult | null {
+    let pathname = new URL(http.request.url).pathname;
+
+    if (this.prefix && pathname.startsWith(this.prefix)) {
+      pathname = pathname.slice(this.prefix.length);
+    }
+
+    // Split and filter empty strings produced by leading/trailing slashes.
+    const parts = pathname.split("/").filter(Boolean);
+    const slug = parts[this.segment];
+
+    return slug ? { identifier: slug } : null;
+  }
+}

package/src/resolvers/RouteParamResolver.ts

@@ -0,0 +1,40 @@
+/**
+ * RouteParamResolver — reads the tenant slug from a named route parameter.
+ *
+ * Pair it with a `/:tenancy` group prefix: the router captures the segment into
+ * `http.params.tenancy` before middleware runs, and this resolver hands that slug
+ * to `TenancyMiddleware`.
+ *
+ * @example
+ * // config/tenancy.ts
+ * resolvers: [new RouteParamResolver({ param: "tenancy" })]
+ *
+ * // bootstrap/app.ts
+ * .fileBasedRouting({
+ *   dir: basePath("app/routes"),
+ *   prefix: "/:tenancy",          // GET /acme/dashboard → params.tenancy = "acme"
+ *   middleware: [TenancyMiddleware],
+ * });
+ */
+
+import type { HttpContext } from "@zerotal/core";
+import type { TenantResolver, TenantResolverResult } from "../types.ts";
+
+interface RouteParamResolverOptions {
+  /** The route parameter name holding the tenant slug. Default: `"tenancy"`. */
+  param?: string;
+}
+
+export class RouteParamResolver implements TenantResolver {
+  private readonly param: string;
+
+  constructor(opts: RouteParamResolverOptions = {}) {
+    this.param = opts.param ?? "tenancy";
+  }
+
+  resolve(http: HttpContext): TenantResolverResult | null {
+    const raw = (http.params as Record<string, unknown>)[this.param];
+    const slug = typeof raw === "string" ? raw.trim() : "";
+    return slug ? { identifier: slug, by: "slug" } : null;
+  }
+}

package/src/resolvers/SubdomainResolver.ts

@@ -0,0 +1,34 @@
+/**
+ * SubdomainResolver — extracts the tenant slug from the first subdomain segment.
+ *
+ * Given `domain: 'myapp.com'` and a request to `acme.myapp.com`,
+ * the resolved identifier is `'acme'`.
+ *
+ * Any number of additional subdomains before the tenant segment is ignored —
+ * only the leftmost segment is treated as the tenant slug.
+ */
+
+import type { HttpContext } from "@zerotal/core";
+import type { TenantResolver, TenantResolverResult } from "../types.ts";
+
+export class SubdomainResolver implements TenantResolver {
+  constructor(private readonly domain: string) {}
+
+  resolve(http: HttpContext): TenantResolverResult | null {
+    const host = new URL(http.request.url).hostname;
+
+    // Strip the base domain and any trailing dot.
+    const suffix = `.${this.domain}`;
+    if (!host.endsWith(suffix)) return null;
+
+    const sub = host.slice(0, host.length - suffix.length);
+    if (!sub) return null;
+
+    // Take only the rightmost subdomain segment as the slug
+    // (e.g. "www.acme.myapp.com" → "acme").
+    const parts = sub.split(".");
+    const slug = parts[parts.length - 1]!;
+
+    return slug ? { identifier: slug } : null;
+  }
+}

package/src/tenantSchemaConcern.ts

@@ -0,0 +1,41 @@
+import type { ConcernDescriptor } from "@zerotal/core";
+import { Schema } from "@zerotal/orm";
+
+/**
+ * Provisions the tenancy tables on boot — the `tenants` registry and the
+ * `tenant_members` pivot — so apps don't define a tenant model or write migrations.
+ * Runs once after model discovery (order 70), additively and idempotently. Restricted
+ * to DB-backed environments; DDL/connection errors are swallowed so boot never fails.
+ */
+export const tenantSchemaConcern: ConcernDescriptor = {
+  name: "tenancy-schema",
+  order: 70,
+  envs: ["web", "worker", "test"],
+  async run() {
+    try {
+      if (!(await Schema.hasTable("tenants"))) {
+        await Schema.create("tenants", (t) => {
+          t.increments("id");
+          t.string("slug");
+          t.string("name");
+          t.boolean("is_active");
+          t.string("database").nullable(); // multi-database strategy target
+          t.timestamp("created_at").nullable();
+          t.timestamp("updated_at").nullable();
+        });
+      }
+
+      if (!(await Schema.hasTable("tenant_members"))) {
+        await Schema.create("tenant_members", (t) => {
+          t.increments("id");
+          t.integer("tenant_id");
+          t.integer("user_id");
+          t.boolean("is_admin");
+          t.timestamp("created_at").nullable();
+        });
+      }
+    } catch {
+      // No database (or DDL not permitted) in this runtime — skip silently.
+    }
+  },
+};

package/src/tenantStorage.ts

@@ -0,0 +1,179 @@
+/**
+ * Tenant-scoped storage and cache helpers.
+ *
+ * These thin wrappers prefix all keys and paths with the active tenant's
+ * slug so files and cache entries are automatically isolated per tenant.
+ *
+ * @example
+ * // Storage — saves to /storage/tenants/acme/logo.png on the local disk:
+ * import { tenantDisk } from '@zerotal/tenancy';
+ * await tenantDisk().put('logo.png', buffer);
+ * const url = await tenantDisk().url('logo.png');
+ *
+ * // Cache — key becomes 'tenant:acme:stats':
+ * import { tenantCache } from '@zerotal/tenancy';
+ * await tenantCache().set('stats', data, 300);
+ * const hit = await tenantCache().get<Stats>('stats');
+ */
+
+import { TenantContext } from "./TenantContext.ts";
+import { TenancyConfigError, TenantStoragePathError } from "./errors.ts";
+
+// ── Storage ───────────────────────────────────────────────────────────────────
+
+type StorageDriver = {
+  put(path: string, data: unknown): Promise<void>;
+  get(path: string): Promise<unknown>;
+  exists(path: string): Promise<boolean>;
+  delete(path: string): Promise<void>;
+  url(path: string): Promise<string> | string;
+  [key: string]: unknown;
+};
+
+type StorageManagerLike = {
+  disk(name?: string): StorageDriver;
+};
+
+/**
+ * Return a proxy over the named storage disk that prefixes every path with
+ * `tenants/<slug>/` for the currently active tenant.
+ *
+ * @param disk  The disk name passed to `Storage.disk()`. Defaults to the default disk.
+ * @param storageManager  Optional — pass the `StorageManager` instance directly (useful
+ *   in tests or when the facade isn't available).  When omitted the global `Storage`
+ *   facade is resolved dynamically at call time.
+ */
+export function tenantDisk(disk?: string, storageManager?: StorageManagerLike): StorageDriver {
+  const slug = TenantContext.get().slug;
+
+  const _getDriver = (): StorageDriver => {
+    const manager = storageManager ?? _resolveStorage();
+    return manager.disk(disk);
+  };
+
+  const _root = `tenants/${slug}/`;
+
+  /**
+   * Confine a caller-supplied key to this tenant's directory.
+   *
+   * A bare template prefix was not enough. LocalDriver._fullPath confines paths to the *disk
+   * root*, not to the tenant directory, so `../victim/invoice.txt` resolved to
+   * `<root>/tenants/victim/invoice.txt`, passed the root check, and read another tenant's file.
+   */
+  const _prefix = (path: string): string => {
+    if (typeof path !== "string") {
+      throw new TenantStoragePathError(String(path), slug);
+    }
+    const normalised = path.replaceAll("\\", "/");
+    if (
+      normalised.startsWith("/") ||
+      normalised.split("/").some((segment) => segment === ".." || segment === "~")
+    ) {
+      throw new TenantStoragePathError(path, slug);
+    }
+    return `${_root}${normalised}`;
+  };
+
+  /** Methods whose *second* argument is also a path within the same disk. */
+  const _twoPathMethods = new Set(["copy", "move"]);
+
+  return new Proxy({} as StorageDriver, {
+    get(_target, prop: string) {
+      const driver = _getDriver();
+      const method = (driver as Record<string, unknown>)[prop];
+      if (typeof method === "function") {
+        return (path: string, ...rest: unknown[]) => {
+          const args = [...rest];
+          // copy(from, to) / move(from, to): prefixing only `from` let the destination escape
+          // the tenant entirely — proxy.copy("mine.txt", "tenants/victim/pwned.txt") wrote
+          // straight into another tenant's directory.
+          if (_twoPathMethods.has(prop) && typeof args[0] === "string") {
+            args[0] = _prefix(args[0]);
+          }
+          return (method as (p: string, ...a: unknown[]) => unknown).call(
+            driver,
+            _prefix(path),
+            ...args,
+          );
+        };
+      }
+      return method;
+    },
+  });
+}
+
+function _resolveStorage(): StorageManagerLike {
+  try {
+    // Resolved lazily so tenancy works in an app that never configures a disk.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Storage } = require("@zerotal/core/storage") as { Storage: StorageManagerLike };
+    return Storage;
+  } catch {
+    throw new TenancyConfigError(
+      "tenantDisk() requires a configured storage disk (see @zerotal/core/storage).",
+    );
+  }
+}
+
+// ── Cache ─────────────────────────────────────────────────────────────────────
+
+type CacheManagerLike = {
+  get<T>(key: string): Promise<T | null>;
+  set(key: string, value: unknown, ttl?: number): Promise<void>;
+  forget(key: string): Promise<void>;
+  flush(): Promise<void>;
+  [key: string]: unknown;
+};
+
+type CacheResolverLike =
+  | {
+      store(name?: string): CacheManagerLike;
+    }
+  | CacheManagerLike;
+
+/**
+ * Return a proxy over the cache that prefixes every key with
+ * `tenant:<slug>:` for the currently active tenant.
+ *
+ * @param store  Optional store name (e.g. `'redis'`).
+ * @param cacheResolver  Optional — inject the Cache facade or manager directly.
+ */
+export function tenantCache(store?: string, cacheResolver?: CacheResolverLike): CacheManagerLike {
+  const slug = TenantContext.get().slug;
+
+  const _getManager = (): CacheManagerLike => {
+    const resolver = cacheResolver ?? _resolveCache();
+    return typeof (resolver as Record<string, unknown>)["store"] === "function"
+      ? (resolver as { store(n?: string): CacheManagerLike }).store(store)
+      : (resolver as CacheManagerLike);
+  };
+
+  const _prefix = (key: string) => `tenant:${slug}:${key}`;
+
+  return new Proxy({} as CacheManagerLike, {
+    get(_target, prop: string) {
+      const manager = _getManager();
+      const method = (manager as Record<string, unknown>)[prop];
+      if (typeof method === "function") {
+        if (prop === "flush") {
+          // flush() takes no key — delegate as-is.
+          return () => (method as () => unknown).call(manager);
+        }
+        return (key: string, ...rest: unknown[]) =>
+          (method as (k: string, ...a: unknown[]) => unknown).call(manager, _prefix(key), ...rest);
+      }
+      return method;
+    },
+  });
+}
+
+function _resolveCache(): CacheResolverLike {
+  try {
+    const { Cache } = require("@zerotal/cache") as { Cache: CacheResolverLike };
+    return Cache;
+  } catch {
+    throw new TenancyConfigError(
+      "tenantCache() requires @zerotal/cache to be installed and configured.",
+    );
+  }
+}

package/src/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Core types for @zerotal/tenancy.
+ */
+
+import type { SQLInstance } from "@zerotal/orm";
+import type { HttpContext } from "@zerotal/core";
+
+/** Minimal shape every tenant record satisfies (matches the internal `TenantModel`). */
+export interface Tenant {
+  /** Database primary key. */
+  id: number;
+  /** URL-safe identifier used in subdomains and storage paths. */
+  slug: string;
+  /** Display name. */
+  name: string;
+  /** Whether this tenant is active. Inactive tenants are rejected by TenancyMiddleware. */
+  isActive: boolean;
+}
+
+/** Extended tenant shape for the multi-database strategy. */
+export interface MultiDbTenant extends Tenant {
+  /** SQLite database file path OR connection string for this tenant's database. */
+  database: string;
+}
+
+// ── Resolver types ────────────────────────────────────────────────────────────
+
+/** A resolver extracts a tenant identifier from the incoming request. */
+export interface TenantResolverResult {
+  /** The raw identifier extracted (subdomain slug, header value, path segment, auth user, …). */
+  identifier: string | number;
+  /**
+   * How to look the tenant up in the registry. `"slug"` (default) matches the URL-safe
+   * slug; `"id"` matches the primary key — used by resolvers that read a foreign key such
+   * as the authenticated user's `tenantId`.
+   */
+  by?: "slug" | "id";
+}
+
+export interface TenantResolver {
+  /**
+   * Return an identifier if this resolver can handle the request, or null to skip.
+   *
+   * Resolvers receive the full {@link HttpContext} so they can read route params
+   * (`http.params`), the authenticated user (`http.user`), headers, or the raw
+   * `http.request` — whichever they resolve from.
+   */
+  resolve(http: HttpContext): TenantResolverResult | null;
+
+  /**
+   * Whether the identifier this resolver produces is *already known to belong to the
+   * requester* — i.e. it came from server-held state rather than from the request.
+   *
+   * Only {@link AuthResolver} is trusted: it reads the tenant off the authenticated
+   * user's own record. Subdomains, headers, path segments and route params are all
+   * attacker-chosen, so `TenancyMiddleware` requires an authenticated requester to be a
+   * member of the tenant they named before opening the boundary. Without that check, a
+   * user of tenant A reaches tenant B's data by editing one header.
+   *
+   * Defaults to `false` — a custom resolver is untrusted until it says otherwise, which is
+   * the right way round for a security default.
+   */
+  readonly trusted?: boolean;
+}
+
+// ── Strategy ─────────────────────────────────────────────────────────────────
+
+export type TenancyStrategy = "single-database" | "multi-database";
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+export interface TenancyConfigShape {
+  /** Persistence strategy. Default: 'single-database'. */
+  strategy: TenancyStrategy;
+
+  /**
+   * One or more resolvers tried in order until one returns a non-null result.
+   * If all resolvers return null the request is treated as tenant-less
+   * (TenancyMiddleware returns a 404).
+   */
+  resolvers: TenantResolver[];
+
+  /**
+   * Column name used for tenant scoping in the single-database strategy.
+   * Default: 'tenant_id'.
+   */
+  tenantColumn?: string;
+
+  /**
+   * **Multi-database strategy only — required.** Opens (or returns) the database
+   * connection for a tenant. Called once per tenant; the result is pooled. Once
+   * supplied, every model query inside a tenant boundary is transparently routed to
+   * this connection — no `TenantManager` wiring or raw SQL needed.
+   *
+   * @example
+   * connect: (tenant) => new SQL(`file:./storage/tenants/${tenant.database}`),
+   */
+  connect?: (tenant: MultiDbTenant) => SQLInstance;
+}