Tenants

tenant tells your app which customer a request belongs to. The adapter sets it first, and every db query, kv key, file path and log record is scoped to it. Core, free on every plan.

Spec tenancy, milestone 0.3. The module is built and runs on in-memory fakes: the tenant directory is held in memory today, and durable directory drivers are planned.

tenancy:
  isolation: shared                  # shared | schema | database
  resolve: [apikey, session, subdomain]
  host: acme.app
  personal: true
  directory: eu
  roles: [owner, admin, member, viewer]
  system: { allow: [src/admin/**, scripts/**] }
  suspended: { allow: [billing.*, tenant.export] }
  erase: { wait: 7d }
  global: [Plan, Country]              # models shared by every tenant
  databases:                           # isolation: database only
    tnt_acme: secret:ACME_DATABASE_URL

import { db, tenant } from "mainsdk";

// the adapter set the tenant from the API key, the session or the subdomain
const acme = tenant.current();
const orders = await db.orders.for(user).list({ limit: 20 });   // only acme's rows

// a job has no request, so it names the tenant once
await tenant.run(job.tenantId, () => sendDigest());

import { it } from "node:test";
import assert from "node:assert/strict";
import { db, s, tenant } from "mainsdk";
import { createTestApp } from "@mainsdk/testing";

it("tenancy AC8 keeps one tenant's rows from another", async () => {
  createTestApp({ yaml: "schema: 1\nproject: prj_test\ntenancy:\n  resolve: [session]\n" });
  const { orders } = db.define({ orders: s.object({ item: s.string() }) });
  const a = await tenant.create({ name: "A", region: "eu" });
  const b = await tenant.create({ name: "B", region: "us" });
  await tenant.run(a.id, () => orders.for("u1").create({ item: "x" }));
  const seen = await tenant.run(b.id, () => orders.for("u1").list({ limit: 20 }));
  assert.equal(seen.items.length, 0);
});

tenant:
  driver: builtin

Quick start

tenancy:
  isolation: shared
  resolve: [apikey, session, subdomain]
  personal: true

import { auth, models, s, tenant } from "mainsdk";

const { orders } = models({
  orders: s.object({ item: s.string(), total: s.int() }),
}); // declared once in lib/orders.ts, shown inline so the example stands alone

export async function GET(req: Request) {
  const session = await auth.require(req);
  const acme = tenant.current();                       // set by the adapter
  const page = await orders.for(session.user).list({ limit: 20 });   // only this tenant's rows
  return Response.json({ tenant: acme.id, items: page.items });
}

tenant.current() returns { id, kind, name, slug, region, plan, status, roles }. A call that needs a tenant and finds none fails with MAIN-TENANT-0001. Use tenant.maybe() where a tenant is optional: it returns the tenant or null. Without a tenancy section, every call runs in one implicit tenant, default.

Configuration

Every key lives under tenancy:.

tenancy:
  isolation: shared                  # shared | schema | database
  resolve: [apikey, session, subdomain]
  host: acme.app                     # the subdomain resolver reads <slug>.acme.app
  personal: true                     # a personal tenant for each person at first sign-in
  roles: [owner, admin, member, viewer]
  global: [plans, countries]         # db models shared by all tenants; no personal fields
  system: { allow: [src/admin/**, scripts/**] }
  suspended: { allow: [billing.*, tenant.export] }
  erase: { wait: 7d }

A tenant is pinned to one region at create (us, eu or in) and nothing it owns is written elsewhere. The key that names where the directory lives is planned with the durable directory drivers.

What you get

Always:

• Every request has a tenant, and every query, key and file path is scoped to it.
• A record, file or team of another tenant reads as not found.
• Each tenant is pinned to one region and nothing is written elsewhere.
• tenant.system() runs only in listed admin files and is audited with its reason.
• Log records carry the tenant, and each tenant has its own exportable audit chain.

Examples

Run a job as a tenant

A job has no request, so it names the tenant once with tenant.run(id, fn). It refuses an unknown or suspended tenant.

import { tenant } from "mainsdk";

declare function sendDigest(): Promise<void>;   // your own code

export async function sendDigests(tenantIds: string[]) {
  for (const id of tenantIds) {
    await tenant.run(id, () => sendDigest());   // db, kv, files and logs inside are this tenant's
  }
}

Admin code across tenants

Cross-tenant work goes through tenant.system(reason, fn). It works only in files listed under tenancy.system.allow, and it writes an audit record with your reason.

Before anyone has signed in there is no tenant yet. tenant.anonymous(fn) runs fn in the implicit default tenant; the sign-in routes use it to send a link to an address that has no session. It grants no access to any customer's records.

import { tenant } from "mainsdk";

export async function countTenants() {
  return tenant.system("monthly usage report", async (sys) => {
    const page = await sys.list({ limit: 100 });
    return page.items.length;
  });
}

Use it only in admin paths. mainsdk check fails with MAIN-TENANT-0011 when it appears anywhere else.

Create a tenant

auth.orgs.create() is the call for a signed-in person making an organisation. Use tenant.create() in admin code and scripts.

import { tenant } from "mainsdk";

const acme = await tenant.create({ name: "Acme", kind: "org", region: "eu", slug: "acme", plan: "pro" });
console.log(acme.id);   // tnt_…

Suspend, export and erase

import { tenant } from "mainsdk";

const id = "tnt_acme";
await tenant.suspend(id, { reason: "unpaid for 60 days" });   // calls fail closed with MAIN-TENANT-0003
const bundle = await tenant.export(id);                       // { files, manifest }: JSON per driver and a signed manifest
const done = tenant.erase(id, { reason: "customer request" });   // a promise that settles after tenancy.erase.wait
await tenant.cancelErase(id);                                 // changes your mind inside the waiting period; `done` rejects
await tenant.resume(id);

tenant.erase() schedules the erasure and its promise resolves with the signed record only once the waiting period has passed and every driver has erased, so do not await it in a request. Calling tenant.cancelErase() rejects it with MAIN-TENANT-0007 and returns the tenant to suspended. Erasure needs the tenant suspended first and no legal hold, or it fails with MAIN-TENANT-0007. A tenant id or slug that is invalid or taken, or a missing name or region, is refused when you create it.

Reference: more calls

The calls below are for adapters, admin code and tests. Most apps never call them, because the adapter and db use them for you.

Read the context

Scope a call

Resolve and enter

Lifecycle and audit

Helpers

These pure functions are exported for adapters and tests.

Errors and checks

Swapping drivers

tenant has no driver. Isolation is an option of the db driver (shared, schema or database), so you change it under tenancy.isolation and db.

Testing

createTestApp() reads your tenancy section and keeps the directory in memory. Create two tenants and run the same code in each with tenant.run().

import { it } from "node:test";
import assert from "node:assert/strict";
import { db, s, tenant } from "mainsdk";
import { createTestApp } from "@mainsdk/testing";

it("tenancy AC8 keeps one tenant's rows from another", async () => {
  createTestApp({ yaml: "schema: 1\nproject: prj_test\ntenancy:\n  resolve: [session]\n" });
  const { orders } = db.define({ orders: s.object({ item: s.string() }) });
  const a = await tenant.create({ name: "A", region: "eu" });
  const b = await tenant.create({ name: "B", region: "us" });
  await tenant.run(a.id, () => orders.for("u1").create({ item: "x" }));
  const seen = await tenant.run(b.id, () => orders.for("u1").list({ limit: 20 }));
  assert.equal(seen.items.length, 0);
});

A suite that runs every test as two tenants and fails on any cross-tenant read is planned (spec tenancy). See the testing kit.

Security and privacy

• A record, file or team of another tenant reads as not found, with the same body as one that does not exist.
• Each tenant has its own key under the region key, so erasing the key erases the tenant's data.
• The directory holds ids, slugs, regions and status only. It holds no personal data.
• Every log record carries the tenant, and each tenant has its own audit chain that can be exported alone.

FAQ

Do I pass the tenant id to db? No. The query is scoped for you. Passing ids by hand is how data leaks.

My app has one customer. Do I need this? No. Without a tenancy section there is one implicit tenant, default.

Can a person belong to several tenants? Yes. auth.orgs.switch() sets the active one for the session.

Next

• Sign-in and sessions: organisations, members, teams and invites.
• API keys for your customers: keys that set the tenant.
• Plans and entitlements: what each tenant's plan allows.
• Build a multi-tenant app