@firetail/finchly 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to `@firetail/finchly`. Versions follow semver.
 
 ## Unreleased
 
+## 0.0.8 - 2026-11-12
+
+- **Breaking:** the database is per tenant. `connectDatabase` no longer
+  runs SQL itself: `database.forTenant(caller.tenantId)` gives the handle
+  with `execute`, `transaction` and `withAdvisoryLock`, and everything on
+  it happens in that tenant's schema. **Needs a platform that gives a
+  schema per tenant.**
+- `database.migrate` applies migrations in every tenant's schema and
+  resolves with the versions applied, by tenant id. A tenant that starts
+  using the service later is migrated on first use.
+- `database.tenants()` lists the tenants the service has a database for.
+
+## 0.0.7 - 2026-11-12
+
+- An identity names its tenant: `caller.tenantId`. One deployment serves
+  several tenants, and every request is for exactly one. A token with no
+  `tid` claim, or one that is not a tenant id, is rejected with reason
+  `claims`. **Needs a platform that sends `tid`.**
+- `service.call` and `service.token` take `tenantId`, which says which
+  tenant a call to another service is for.
+- New conformance vectors for `tid`.
+
 ## 0.0.6 - 2026-11-12
 
 - `connectDatabase`: PostgreSQL for a service whose manifest sets

package/README.md

@@ -51,6 +51,7 @@ const identity = createIdentityVerifier({
 // Per request.
 try {
   const caller = await identity.fromHeaders(req.headers);
+  caller.tenantId;  // the tenant this request is for
   caller.subject;   // user id, or "service:<slug>"
   caller.email;     // null for a service calling as itself
   caller.groups;    // platform groups
@@ -71,6 +72,12 @@ publishes, names that gateway as issuer and this service as its only
 audience, and has not expired. The rules are in `spec/identity-token.md` in
 `FireTail-io/finchly`.
 
+**The tenant.** One deployment serves several tenants, and every request
+is for exactly one: `caller.tenantId`. Do everything for the caller within
+that tenant, and store whatever you keep for them under it. Take it from
+the verified identity only, never from a path, a header or a request body.
+A token that names no tenant is rejected.
+
 No other header is ever consulted. On a path the manifest declares in
 `publicPaths` there is no token, and the service authenticates the request
 itself.
@@ -91,20 +98,27 @@ const service = createServiceClient({
 });
 await service.start();   // optional: fail now, not on the first call
 
-// As the service itself.
+// As the service itself, for the tenant of the request being handled.
 const res = await service.call("notification-service", "/api/send", {
+  tenantId: caller.tenantId,
   method: "POST",
   headers: { "content-type": "application/json" },
   body: JSON.stringify({ text: "hello" }),
 });
 
 // For a user: the target sees that user, and this service acting for them.
-await service.call("notification-service", "/api/inbox", { asUser: caller.subject });
+await service.call("notification-service", "/api/inbox", {
+  tenantId: caller.tenantId,
+  asUser: caller.subject,
+});
 ```
 
 `call` takes the same options as `fetch` and resolves with the response,
 whatever its status.
 
+- **`tenantId` says which tenant the call is for.** The target then works
+  within that tenant. Pass it on every call to another service, and always
+  from a verified identity. A user named in `asUser` must belong to it.
 - **403** means this service's manifest does not list the target in
   `calls`, or the user has no access to the target.
 - **A redirect is handed back, not followed.**
@@ -162,8 +176,8 @@ an app.
 
 ### A database of its own
 
-A service whose manifest sets `permissions.db` is given a PostgreSQL role
-and a schema that only that role can use. The service installs `pg` itself:
+A service whose manifest sets `permissions.db` is given a PostgreSQL schema
+of its own for each tenant that uses it. The service installs `pg` itself:
 
 ```
 npm install pg
@@ -172,9 +186,13 @@ npm install pg
 ```js
 import { connectDatabase } from "@firetail/finchly";
 
-// Once, at startup. Asks the platform for the role and schema it made.
-const db = await connectDatabase({ service });
-await db.migrate(new URL("./migrations/", import.meta.url).pathname);
+// Once, at startup. Asks the platform for the role and schemas it made,
+// and brings every tenant's schema up to date.
+const database = await connectDatabase({ service });
+await database.migrate(new URL("./migrations/", import.meta.url).pathname);
+
+// Per request: the database of the caller's tenant.
+const db = database.forTenant(caller.tenantId);
 
 const { rows } = await db.execute("SELECT id, body FROM notes WHERE author = $1", [caller.subject]);
 
@@ -183,28 +201,38 @@ await db.transaction(async (tx) => {
   await tx.execute("UPDATE authors SET notes = notes + 1 WHERE id = $1", [caller.subject]);
 });
 
-// One instance at a time, across every instance of this service.
+// One instance at a time, for this tenant, across every instance of this service.
 await db.withAdvisoryLock("nightly-import", async (tx) => {
   // ...
 });
 ```
 
-- **Names need no schema.** `notes` means the service's own table. The
-  service cannot read the platform's tables or another service's.
+- **There is no database without a tenant.** SQL is run on the handle
+  `forTenant` gives, and happens in that tenant's schema. Take the tenant
+  id from a verified identity, never from the request itself.
+- **Names need no schema.** `notes` means that tenant's table. The service
+  cannot read the platform's tables or another service's, and working for
+  one tenant it cannot reach another's.
 - **Values go in the second argument**, as `$1`, `$2`. They are never built
   into the SQL.
 - **A transaction** commits if its function returns and rolls back if it
   throws.
 - **Migrations** are files named `NNNN_name.sql`, applied in order, once
-  each, in one transaction. Every instance may call `migrate` at startup:
-  they take turns. A migration that was applied is never edited; add a new
-  one. A problem is a `FinchlyError` with code `migration_invalid`.
+  each, in every tenant's schema. Every instance may call `migrate` at
+  startup: they take turns. A tenant that starts using the service later is
+  migrated the first time its database is used. A migration that was
+  applied is never edited; add a new one. A problem is a `FinchlyError`
+  with code `migration_invalid`.
+- **Work with no request behind it**, such as a schedule, runs once for
+  each tenant: `await database.tenants()` lists them.
 - `connectDatabase` rejects with `database_not_granted` if the manifest
   does not ask for a database, and with `database_unavailable` if the
-  platform or the database cannot be reached.
+  platform or the database cannot be reached. Using a tenant the service
+  has no database for rejects with `database_not_granted`.
 
 To run a service on its own, without a platform, give the URL directly:
-`connectDatabase({ url, slug })`.
+`connectDatabase({ url, slug })`. Each tenant's schema is then made the
+first time it is used.
 
 ### What every request carries
 
@@ -214,7 +242,7 @@ release is asking:
 | Header | Value |
 |---|---|
 | `x-platform-sdk` | `@firetail/finchly` |
-| `x-platform-sdk-version` | This release, for example `0.0.6` |
+| `x-platform-sdk-version` | This release, for example `0.0.8` |
 | `x-platform-api-version` | The platform API version it speaks, `v1` |
 
 That covers fetching the gateway's issuer and keys, registering an instance

package/dist/db.d.ts

@@ -3,7 +3,7 @@ export interface QueryResult<Row> {
     readonly rows: Row[];
     readonly rowCount: number;
 }
-/** Something SQL can be run on: the database, or one transaction. */
+/** Something SQL can be run on: a tenant's database, or one transaction in it. */
 export interface Queryable {
     /**
      * Run a statement. Values go in `params` and are referred to as $1, $2
@@ -12,24 +12,36 @@ export interface Queryable {
      */
     execute<Row = Record<string, unknown>>(sql: string, params?: readonly unknown[]): Promise<QueryResult<Row>>;
 }
-export interface Database extends Queryable {
-    /** The service's schema, when the platform said which it is. Unqualified names already mean this schema. */
-    readonly schema: string | undefined;
+/** This service's database for one tenant. Unqualified names mean that tenant's tables. */
+export interface TenantDatabase extends Queryable {
+    readonly tenantId: string;
     /** Run `fn` in one transaction. It commits if `fn` returns and rolls back if it throws. */
     transaction<T>(fn: (tx: Queryable) => Promise<T>): Promise<T>;
     /**
      * Run `fn` in a transaction that holds a lock named `key`. Another
-     * instance of this service that asks for the same key waits until this
-     * transaction ends. The lock is this service's own: another service
-     * using the same name does not wait for it.
+     * instance of this service that asks for the same key, for the same
+     * tenant, waits until this transaction ends. The lock is this tenant's
+     * and this service's: the same name elsewhere does not wait for it.
      */
     withAdvisoryLock<T>(key: string, fn: (tx: Queryable) => Promise<T>): Promise<T>;
+}
+export interface Database {
+    /**
+     * The database for one tenant: `caller.tenantId` of the request being
+     * handled. Take the id from a verified identity, never from the request
+     * itself. Everything run on the handle happens in that tenant's schema.
+     */
+    forTenant(tenantId: string): TenantDatabase;
+    /** The tenants this service has a database for now. */
+    tenants(): Promise<string[]>;
     /**
-     * Apply the migrations in `directory` that have not been applied: files
-     * named NNNN_name.sql, in order, once each. Safe to call from every
-     * instance at startup. Resolves with the versions this call applied.
+     * Apply the migrations in `directory`: files named NNNN_name.sql, in
+     * order, once each, in every tenant's schema. Safe to call from every
+     * instance at startup. A tenant that starts using the service later is
+     * migrated the first time its database is used. Resolves with the
+     * versions this call applied, by tenant id.
      */
-    migrate(directory: string): Promise<string[]>;
+    migrate(directory: string): Promise<Record<string, string[]>>;
     close(): Promise<void>;
 }
 /** What the platform holds for this service. See spec/registration.md, section 4. */
@@ -37,7 +49,11 @@ export interface PlatformSettings {
     readonly slug: string;
     readonly database?: {
         readonly url: string;
-        readonly schema: string;
+        /** By tenant id: the tenant's schema, and the role to take to work in it. */
+        readonly tenants: Readonly<Record<string, {
+            readonly schema: string;
+            readonly role: string;
+        }>>;
     };
 }
 export interface DatabaseOptions {
@@ -45,7 +61,8 @@ export interface DatabaseOptions {
     readonly service?: Pick<ServiceClient, "call">;
     /**
      * Connect to this URL and do not ask the platform. For tests and for
-     * running a service on its own. Needs `slug`.
+     * running a service on its own. Needs `slug`. Each tenant's schema is
+     * made the first time it is used.
      */
     readonly url?: string;
     /** The service's slug. Only needed with `url`. */
@@ -57,7 +74,7 @@ export interface DatabaseOptions {
 export declare function fetchSettings(service: Pick<ServiceClient, "call">): Promise<PlatformSettings>;
 /**
  * Connect to this service's database. With `service`, the platform is
- * asked for the role and schema it made; the manifest must set
+ * asked for the role and schemas it made; the manifest must set
  * permissions.db. Rejects if the database cannot be reached.
  */
 export declare function connectDatabase(options: DatabaseOptions): Promise<Database>;

package/dist/db.js

@@ -1,13 +1,22 @@
-// PostgreSQL for a service: the role and schema the platform made for it.
+// PostgreSQL for a service: a schema of its own for each tenant.
 //
-// The platform gives each service that asks for one (permissions.db in the
-// manifest) a database role and a schema only that role can use. This
-// module asks the platform for them and connects. It needs the `pg`
-// package, which the service installs itself.
+// One deployment serves several tenants. The platform gives a service that
+// asks for a database (permissions.db in the manifest) a role to log in as,
+// which can read nothing by itself, and for each tenant that uses the
+// service a schema and a role that may use it. This module asks the
+// platform for them and connects.
+//
+// Nothing can be read or written without naming a tenant: the handle that
+// runs SQL is made with `forTenant`. It needs the `pg` package, which the
+// service installs itself.
 import { createHash } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { FinchlyError } from "./errors.js";
+const TENANT_ID = /^t_[a-z2-7]{16}$/;
+const IDENTIFIER = /^[a-z][a-z0-9_]{0,62}$/;
+/** The least time between two questions to the platform about a tenant it did not list. */
+const SETTINGS_COOLDOWN_MS = 5_000;
 /** Ask the platform what it holds for this service. */
 export async function fetchSettings(service) {
     const response = await service.call("core", "/api/apps/self/config");
@@ -125,30 +134,51 @@ async function applyMigrations(tx, migrations) {
     }
     return done;
 }
+/** A name the platform gave, quoted. Anything that is not such a name is refused, not escaped. */
+function quoted(name) {
+    if (typeof name !== "string" || !IDENTIFIER.test(name)) {
+        throw new FinchlyError("database_unavailable", "The platform named a schema or role that is not usable");
+    }
+    return `"${name}"`;
+}
+function placesFrom(settings) {
+    const places = new Map();
+    for (const [tenantId, place] of Object.entries(settings.database?.tenants ?? {})) {
+        if (!TENANT_ID.test(tenantId))
+            continue;
+        // Checked now, so that a bad name is never sent to the database.
+        quoted(place.schema);
+        quoted(place.role);
+        places.set(tenantId, { schema: place.schema, role: place.role });
+    }
+    return places;
+}
 /**
  * Connect to this service's database. With `service`, the platform is
- * asked for the role and schema it made; the manifest must set
+ * asked for the role and schemas it made; the manifest must set
  * permissions.db. Rejects if the database cannot be reached.
  */
 export async function connectDatabase(options) {
     let url;
     let slug;
-    let schema;
+    let places = new Map();
+    const service = options.url === undefined ? options.service : undefined;
     if (options.url !== undefined) {
         if (!options.slug) {
             throw new FinchlyError("database_unavailable", "connectDatabase needs `slug` when it is given `url`");
         }
         ({ url, slug } = { url: options.url, slug: options.slug });
     }
-    else if (options.service) {
-        const settings = await fetchSettings(options.service);
+    else if (service) {
+        const settings = await fetchSettings(service);
         if (!settings.database) {
             throw new FinchlyError("database_not_granted", "The platform made no database for this service", [
                 "Set permissions.db to true in the manifest",
             ]);
         }
-        ({ url, schema } = settings.database);
+        url = settings.database.url;
         slug = settings.slug;
+        places = placesFrom(settings);
     }
     else {
         throw new FinchlyError("database_unavailable", "connectDatabase needs `service`, or `url` and `slug`");
@@ -157,7 +187,6 @@ export async function connectDatabase(options) {
     const pool = new pg.Pool({ connectionString: url, max: options.maxConnections ?? 10 });
     // An idle connection that drops must not take the process down.
     pool.on("error", () => { });
-    const onPool = queryable(pool);
     try {
         await pool.query("SELECT 1");
     }
@@ -166,11 +195,64 @@ export async function connectDatabase(options) {
         // pg's message names the host and the role, never the password.
         throw new FinchlyError("database_unavailable", "The database could not be reached", [err.message]);
     }
-    async function transaction(fn) {
+    /** Ask the platform again which tenants there are. At most one question at a time. */
+    let refreshing;
+    let refreshedAt = Date.now();
+    function refresh() {
+        if (!service)
+            return Promise.resolve();
+        refreshing ??= fetchSettings(service)
+            .then((settings) => {
+            places = placesFrom(settings);
+            refreshedAt = Date.now();
+        })
+            .finally(() => {
+            refreshing = undefined;
+        });
+        return refreshing;
+    }
+    /** Where a tenant's data is, or a refusal if this service has none for it. */
+    async function placeOf(tenantId) {
+        let place = places.get(tenantId);
+        if (place)
+            return place;
+        if (!service) {
+            // Running on its own: the schema is named as the platform would name
+            // it, and made by whoever is connected.
+            const schema = `${tenantId}_${slug.replaceAll("-", "_")}`.slice(0, 63);
+            try {
+                await pool.query(`CREATE SCHEMA IF NOT EXISTS ${quoted(schema)}`);
+            }
+            catch (err) {
+                // Two connections making it at once: one of them is told it exists.
+                const code = err.code;
+                if (code !== "23505" && code !== "42P06")
+                    throw err;
+            }
+            place = { schema };
+            places.set(tenantId, place);
+            return place;
+        }
+        // A tenant may have started using the service since the platform was asked.
+        if (Date.now() - refreshedAt >= SETTINGS_COOLDOWN_MS || refreshing)
+            await refresh();
+        place = places.get(tenantId);
+        if (!place) {
+            throw new FinchlyError("database_not_granted", "This service has no database for that tenant", [
+                "The tenant does not use this service, or is not active",
+            ]);
+        }
+        return place;
+    }
+    /** Run `fn` in a transaction, as the tenant's role, in the tenant's schema. Both end with the transaction. */
+    async function inTenant(place, fn) {
         const client = await pool.connect();
         let broken;
         try {
             await client.query("BEGIN");
+            if (place.role !== undefined)
+                await client.query(`SET LOCAL ROLE ${quoted(place.role)}`);
+            await client.query(`SET LOCAL search_path = ${quoted(place.schema)}`);
             const result = await fn(queryable(client));
             await client.query("COMMIT");
             return result;
@@ -189,22 +271,64 @@ export async function connectDatabase(options) {
             client.release(broken);
         }
     }
-    const withAdvisoryLock = (key, fn) => transaction(async (tx) => {
-        // Advisory locks are shared by everything in the database, so the
-        // name carries the service's slug.
-        await tx.execute("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`svc:${slug}:${key}`]);
-        return fn(tx);
-    });
-    return {
-        schema,
-        execute: onPool.execute,
-        transaction,
-        withAdvisoryLock,
-        async migrate(directory) {
-            const migrations = await readMigrations(directory);
+    const lockKey = (tenantId, key) => `t:${tenantId}:svc:${slug}:${key}`;
+    const lock = (tx, tenantId, key) => tx.execute("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [lockKey(tenantId, key)]);
+    // Migrations, once `migrate` has been called: each tenant's schema is
+    // brought up to date once per process, before anything else runs in it.
+    let migrations;
+    const migrated = new Map();
+    function migrateTenant(tenantId, place) {
+        const known = migrations;
+        if (known === undefined)
+            return Promise.resolve([]);
+        let pending = migrated.get(tenantId);
+        if (!pending) {
             // One transaction: instances starting together take turns, and a
             // migration that fails leaves nothing behind.
-            return withAdvisoryLock("migrate", (tx) => applyMigrations(tx, migrations));
+            pending = inTenant(place, async (tx) => {
+                await lock(tx, tenantId, "migrate");
+                return applyMigrations(tx, known);
+            });
+            migrated.set(tenantId, pending);
+            // A failure is reported to whoever asked, and tried again next time.
+            pending.catch(() => migrated.delete(tenantId));
+        }
+        return pending;
+    }
+    /** Run `fn` for a tenant, once its schema is known and up to date. */
+    async function run(tenantId, fn) {
+        const place = await placeOf(tenantId);
+        await migrateTenant(tenantId, place);
+        return inTenant(place, fn);
+    }
+    return {
+        forTenant(tenantId) {
+            if (typeof tenantId !== "string" || !TENANT_ID.test(tenantId)) {
+                throw new FinchlyError("database_unavailable", "forTenant needs a tenant id, as in caller.tenantId");
+            }
+            return {
+                tenantId,
+                execute: (sql, params) => run(tenantId, (tx) => tx.execute(sql, params)),
+                transaction: (fn) => run(tenantId, fn),
+                withAdvisoryLock: (key, fn) => run(tenantId, async (tx) => {
+                    await lock(tx, tenantId, key);
+                    return fn(tx);
+                }),
+            };
+        },
+        async tenants() {
+            await refresh();
+            return [...places.keys()].sort();
+        },
+        async migrate(directory) {
+            migrations = await readMigrations(directory);
+            migrated.clear();
+            await refresh();
+            const applied = {};
+            for (const [tenantId, place] of [...places].sort(([a], [b]) => a.localeCompare(b))) {
+                applied[tenantId] = await migrateTenant(tenantId, place);
+            }
+            return applied;
         },
         close: () => pool.end(),
     };

package/dist/identity.d.ts

@@ -3,6 +3,13 @@ import type { JSONWebKeySet, JWTPayload } from "jose";
 export declare const IDENTITY_HEADER = "x-platform-identity";
 /** Who is calling, as asserted by the gateway. */
 export interface Identity {
+    /**
+     * The tenant the request is for. One deployment serves several tenants:
+     * everything done for this caller is done within this one, and whatever
+     * the service stores for them is stored under it. It comes from the
+     * verified token and from nowhere else.
+     */
+    readonly tenantId: string;
     /** The user's platform id, or `service:<slug>` for a service calling as itself. */
     readonly subject: string;
     /** True when the caller is a service calling as itself, with no user. */

package/dist/identity.js

@@ -7,7 +7,9 @@ import { SUPPORTED_PLATFORM_API_VERSIONS } from "./platform-api.js";
 import { SDK_REQUEST_HEADERS } from "./request-headers.js";
 /** Header the gateway sets on every request it proxies. */
 export const IDENTITY_HEADER = "x-platform-identity";
-const REQUIRED_CLAIMS = ["iss", "sub", "aud", "iat", "exp"];
+const REQUIRED_CLAIMS = ["iss", "tid", "sub", "aud", "iat", "exp"];
+/** What a tenant id looks like. See spec/identity-token.md. */
+const TENANT_ID = /^t_[a-z2-7]{16}$/;
 const DEFAULT_CLOCK_SKEW_SECONDS = 30;
 const KEY_CACHE_MS = 60 * 60 * 1000;
 const KEY_REFETCH_COOLDOWN_MS = 30 * 1000;
@@ -39,6 +41,11 @@ function toIdentity(payload, slug) {
     if (typeof payload.iat !== "number" || typeof payload.exp !== "number") {
         throw new IdentityError("claims");
     }
+    // Every token is for one tenant. One that does not say which is not usable.
+    const tenantId = payload.tid;
+    if (typeof tenantId !== "string" || !TENANT_ID.test(tenantId)) {
+        throw new IdentityError("claims");
+    }
     const email = optionalString(payload.email);
     const name = optionalString(payload.name);
     const sessionId = optionalString(payload.sid);
@@ -60,6 +67,7 @@ function toIdentity(payload, slug) {
         throw new IdentityError("claims");
     }
     return Object.freeze({
+        tenantId,
         subject: payload.sub,
         service: payload.sub.startsWith("service:"),
         email,

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { DEFAULT_MANIFEST_PATH, loadConfig } from "./config.js";
 export type { PlatformConfig } from "./config.js";
 export { connectDatabase, fetchSettings } from "./db.js";
-export type { Database, DatabaseOptions, PlatformSettings, QueryResult, Queryable } from "./db.js";
+export type { Database, DatabaseOptions, PlatformSettings, QueryResult, Queryable, TenantDatabase } from "./db.js";
 export { FinchlyError, IdentityError } from "./errors.js";
 export type { FinchlyErrorCode, IdentityRejection } from "./errors.js";
 export { IDENTITY_HEADER, createIdentityVerifier } from "./identity.js";

package/dist/service.d.ts

@@ -46,10 +46,18 @@ export declare function enrolmentFrom(config: PlatformConfig, manifest: Manifest
     readonly bundle?: string;
 }): Enrolment | undefined;
 export interface CallOptions {
+    /**
+     * The tenant this call is made for: `caller.tenantId` of the request
+     * being handled. The target then works within that tenant. Take it from
+     * a verified identity, never from the request itself. Needed on every
+     * call to another service; only the service's own calls to the platform
+     * (its settings) name none.
+     */
+    readonly tenantId?: string;
     /**
      * The id of the user this call is made for. The target then sees that
      * user, and this service as the one acting for them. Leave it out to
-     * call as the service itself.
+     * call as the service itself. The user must belong to `tenantId`.
      */
     readonly asUser?: string;
 }

package/dist/service.js

@@ -14,6 +14,7 @@ import { SDK_REQUEST_HEADERS } from "./request-headers.js";
 import { SDK_NAME, SDK_VERSION } from "./version.js";
 const SLUG = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const USER_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const TENANT_ID = /^t_[a-z2-7]{16}$/;
 /** The audience of a token meant for the gateway itself. */
 const GATEWAY_AUDIENCE = "gateway";
 const KEYS_PATH = "/_gateway/keys";
@@ -64,9 +65,9 @@ export function createServiceClient(options) {
     /** Set when a call came back 401: the gateway may no longer know the key. */
     let doubtedAt;
     let lastForcedAt = Number.NEGATIVE_INFINITY;
-    async function sign(instance, audience, subject) {
+    async function sign(instance, audience, subject, tenantId) {
         const issuedAt = Math.floor(now().getTime() / 1000);
-        return new SignJWT({})
+        return new SignJWT(tenantId !== undefined ? { tid: tenantId } : {})
             .setProtectedHeader({ alg: "ES256", kid: instance.kid, typ: "JWT" })
             .setIssuer(issuer)
             .setSubject(subject)
@@ -236,6 +237,13 @@ export function createServiceClient(options) {
         }
         return pending;
     }
+    function tenantFor(callOptions) {
+        const tenantId = callOptions?.tenantId;
+        if (tenantId !== undefined && (typeof tenantId !== "string" || !TENANT_ID.test(tenantId))) {
+            throw invalid("tenantId must be a tenant id, as in caller.tenantId");
+        }
+        return tenantId;
+    }
     function subjectFor(callOptions) {
         const user = callOptions?.asUser;
         if (user === undefined)
@@ -255,7 +263,8 @@ export function createServiceClient(options) {
             if (!SLUG.test(target))
                 throw invalid(`target ${JSON.stringify(target)} is not a slug`);
             const subject = subjectFor(callOptions);
-            return sign(await instanceKey(), target, subject);
+            const tenantId = tenantFor(callOptions);
+            return sign(await instanceKey(), target, subject, tenantId);
         },
         async call(target, path, init = {}) {
             if (!SLUG.test(target))
@@ -264,9 +273,10 @@ export function createServiceClient(options) {
             if (!path.startsWith("/") || path.includes("\\") || /(^|\/)\.\.?(\/|$|\?)/.test(path.split("?")[0] ?? "")) {
                 throw invalid('path must start with "/" and contain no "." or ".." segments');
             }
-            const { asUser, ...request } = init;
+            const { asUser, tenantId, ...request } = init;
             const subject = subjectFor(asUser !== undefined ? { asUser } : undefined);
-            const token = await sign(await instanceKey(), target, subject);
+            const tenant = tenantFor(tenantId !== undefined ? { tenantId } : undefined);
+            const token = await sign(await instanceKey(), target, subject, tenant);
             const headers = new Headers(request.headers);
             // Whatever the caller set, the gateway reads this one.
             headers.set("authorization", `Bearer ${token}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firetail/finchly",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "Node SDK for the Finchly platform",
   "type": "module",
   "main": "./dist/index.js",