@firetail/finchly 0.0.6 → 0.0.7

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to `@firetail/finchly`. Versions follow semver.
 
 ## Unreleased
 
+## 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.**
@@ -214,7 +228,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.7` |
 | `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/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/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.7",
   "description": "Node SDK for the Finchly platform",
   "type": "module",
   "main": "./dist/index.js",