@bevel-software/platform-core-backend 0.20.0 → 0.21.0

package/src/tenancy/__tests__/tenant-host.test.ts

@@ -0,0 +1,372 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import express from 'express';
+import http from 'node:http';
+import net, { type AddressInfo } from 'node:net';
+import type { TenantConfig } from '../../core-config.js';
+import { createTenantHost, isLoopbackAddress, selectTenant, type TenantHost } from '../tenant-host.js';
+import type { TenantGraph } from '../tenant-runtime.js';
+import type { TenantDescriptor, TenantSource } from '../tenant-source.contract.js';
+
+/**
+ * Two tenants behind one host, with a tiny app standing in for each graph:
+ * what these cases pin is the front door — which requests reach which
+ * tenant, what an unknown host gets, what happens while a tenant starts —
+ * and none of it depends on what a real graph does once it has the request.
+ */
+const tenants: TenantDescriptor[] = [
+  { slug: 'acme', hosts: ['acme.test'], config: {} as TenantConfig },
+  { slug: 'globex', hosts: ['globex.test'], config: {} as TenantConfig },
+];
+
+const source: TenantSource = {
+  async resolveByHost(host) {
+    return tenants.find((t) => t.hosts.includes(host)) ?? null;
+  },
+  async describe(slug) {
+    return tenants.find((t) => t.slug === slug) ?? null;
+  },
+};
+
+function tenantApp(slug: string) {
+  const app = express();
+  app.get('/api/whoami', (req, res) => {
+    res.json({ tenant: slug, path: req.path, query: req.query });
+  });
+  // Anything else: which tenant got it, and with what path.
+  app.use((req, res) => {
+    res.status(404).json({ tenant: slug, path: req.path, unhandled: true });
+  });
+  return app;
+}
+
+let server: http.Server | null = null;
+let host: TenantHost | null = null;
+
+async function listen(h: TenantHost): Promise<number> {
+  host = h;
+  server = await new Promise<http.Server>((resolve) => {
+    const s = h.app.listen(0, '127.0.0.1', () => resolve(s));
+  });
+  return (server.address() as AddressInfo).port;
+}
+
+/** A request with an explicit Host header — which `fetch` refuses to set. */
+function request(
+  port: number,
+  path: string,
+  hostHeader: string,
+  headers: Record<string, string> = {},
+): Promise<{ status: number; headers: http.IncomingHttpHeaders; body: string }> {
+  return new Promise((resolve, reject) => {
+    const req = http.request(
+      { host: '127.0.0.1', port, path, method: 'GET', headers: { ...headers, host: hostHeader } },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (c: Buffer) => chunks.push(c));
+        res.on('end', () => resolve({ status: res.statusCode ?? 0, headers: res.headers, body: Buffer.concat(chunks).toString() }));
+      },
+    );
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+afterEach(async () => {
+  await host?.stop();
+  host = null;
+  if (server) await new Promise<void>((resolve) => server!.close(() => resolve()));
+  server = null;
+});
+
+describe('selectTenant', () => {
+  it('picks the tenant by host name, however the header spells it', () => {
+    expect(selectTenant({ hostname: 'Acme.Test', url: '/api/x', peer: '10.0.0.5' })).toEqual({ kind: 'host', host: 'acme.test' });
+  });
+
+  it('honours the loopback prefix only from a loopback peer, and strips it from the path', () => {
+    expect(selectTenant({ hostname: 'localhost', url: '/_tenant/acme/api/x?y=1', peer: '127.0.0.1' })).toEqual({
+      kind: 'slug',
+      slug: 'acme',
+      rest: '/api/x?y=1',
+    });
+    expect(selectTenant({ hostname: 'localhost', url: '/_tenant/acme', peer: '::ffff:127.0.0.1' })).toEqual({
+      kind: 'slug',
+      slug: 'acme',
+      rest: '/',
+    });
+    // From outside, the prefix is just a path nobody serves.
+    expect(selectTenant({ hostname: 'acme.test', url: '/_tenant/globex/api/x', peer: '10.0.0.5' })).toEqual({
+      kind: 'host',
+      host: 'acme.test',
+    });
+    // From a loopback peer that is a reverse proxy on the same machine — it
+    // forwarded someone, and says so — the prefix is not honoured either.
+    expect(
+      selectTenant({ hostname: 'acme.test', url: '/_tenant/globex/api/x', peer: '127.0.0.1', forwardedFor: '203.0.113.9' }),
+    ).toEqual({ kind: 'host', host: 'acme.test' });
+    expect(
+      selectTenant({ hostname: 'acme.test', url: '/_tenant/globex/api/x', peer: '127.0.0.1', forwardedFor: ['203.0.113.9'] }),
+    ).toEqual({ kind: 'host', host: 'acme.test' });
+    // An empty header is no header.
+    expect(selectTenant({ hostname: 'localhost', url: '/_tenant/acme/api/x', peer: '127.0.0.1', forwardedFor: '' })).toEqual({
+      kind: 'slug',
+      slug: 'acme',
+      rest: '/api/x',
+    });
+    // A prefix that names nothing a slug could be is not a selector either.
+    expect(selectTenant({ hostname: 'localhost', url: '/_tenant/../etc', peer: '127.0.0.1' })).toEqual({
+      kind: 'host',
+      host: 'localhost',
+    });
+  });
+
+  it('knows which peers are this machine', () => {
+    expect(isLoopbackAddress('127.0.0.1')).toBe(true);
+    expect(isLoopbackAddress('127.9.9.9')).toBe(true);
+    expect(isLoopbackAddress('::1')).toBe(true);
+    expect(isLoopbackAddress('::ffff:127.0.0.1')).toBe(true);
+    expect(isLoopbackAddress('10.0.0.5')).toBe(false);
+    expect(isLoopbackAddress('::ffff:10.0.0.5')).toBe(false);
+    expect(isLoopbackAddress(undefined)).toBe(false);
+  });
+});
+
+describe('createTenantHost', () => {
+  it('hands each host name to its own tenant, and activates each tenant once', async () => {
+    const activations: string[] = [];
+    const port = await listen(
+      createTenantHost({
+        source,
+        process: { port: 0, nodeEnv: 'test', trustProxy: '' },
+        runtime: {
+          activate: async (d) => {
+            activations.push(d.slug);
+            return { core: {}, app: tenantApp(d.slug) } as unknown as TenantGraph;
+          },
+          stop: async () => undefined,
+        },
+      }),
+    );
+    const a = await request(port, '/api/whoami', 'acme.test');
+    const b = await request(port, '/api/whoami', 'globex.test:443');
+    const again = await request(port, '/api/whoami', 'ACME.TEST');
+    expect(JSON.parse(a.body)).toMatchObject({ tenant: 'acme' });
+    expect(JSON.parse(b.body)).toMatchObject({ tenant: 'globex' });
+    expect(JSON.parse(again.body)).toMatchObject({ tenant: 'acme' });
+    expect(activations).toEqual(['acme', 'globex']);
+    expect([...host!.runtimes().keys()]).toEqual(['acme', 'globex']);
+  });
+
+  it('answers 404 for a host no tenant claims, JSON under /api and a plain page elsewhere, building nothing', async () => {
+    let activations = 0;
+    const port = await listen(
+      createTenantHost({
+        source,
+        process: { port: 0, nodeEnv: 'test', trustProxy: '' },
+        runtime: {
+          activate: async () => {
+            activations += 1;
+            return { core: {}, app: tenantApp('x') } as unknown as TenantGraph;
+          },
+        },
+      }),
+    );
+    const api = await request(port, '/api/whoami', 'nobody.test');
+    expect(api.status).toBe(404);
+    expect(JSON.parse(api.body)).toEqual({ error: 'No workspace at this address' });
+    const page = await request(port, '/some/page', 'nobody.test');
+    expect(page.status).toBe(404);
+    expect(page.headers['content-type']).toContain('text/plain');
+    expect(activations).toBe(0);
+  });
+
+  it('answers process health itself, whatever the host, and per-tenant paths through the tenant', async () => {
+    const port = await listen(
+      createTenantHost({
+        source,
+        process: { port: 0, nodeEnv: 'test', trustProxy: '' },
+        runtime: { activate: async (d) => ({ core: {}, app: tenantApp(d.slug) }) as unknown as TenantGraph, stop: async () => undefined },
+      }),
+    );
+    const health = await request(port, '/api/health', 'nobody.test');
+    expect(health.status).toBe(200);
+    expect(JSON.parse(health.body)).toMatchObject({ status: 'ok', tenants: 0 });
+  });
+
+  it('reaches a tenant over loopback by the path prefix, with the prefix stripped', async () => {
+    const port = await listen(
+      createTenantHost({
+        source,
+        process: { port: 0, nodeEnv: 'test', trustProxy: '' },
+        runtime: { activate: async (d) => ({ core: {}, app: tenantApp(d.slug) }) as unknown as TenantGraph, stop: async () => undefined },
+      }),
+    );
+    const res = await request(port, '/_tenant/globex/api/whoami?k=v', '127.0.0.1');
+    expect(res.status).toBe(200);
+    expect(JSON.parse(res.body)).toEqual({ tenant: 'globex', path: '/api/whoami', query: { k: 'v' } });
+    const unknown = await request(port, '/_tenant/nobody/api/whoami', '127.0.0.1');
+    expect(unknown.status).toBe(404);
+    // The same path through a same-machine reverse proxy: decided by host.
+    const proxied = await request(port, '/_tenant/globex/api/whoami', 'acme.test', { 'x-forwarded-for': '203.0.113.9' });
+    expect(JSON.parse(proxied.body)).toEqual({ tenant: 'acme', path: '/_tenant/globex/api/whoami', unhandled: true });
+  });
+
+  it('does not count a client that dropped while its tenant was being looked up', async () => {
+    // A registry-backed source: the lookup is a real round trip, and the
+    // client is gone before it answers.
+    const slowSource: TenantSource = {
+      resolveByHost: async (host) => {
+        await new Promise((resolve) => setTimeout(resolve, 150));
+        return source.resolveByHost(host);
+      },
+      describe: (slug) => source.describe(slug),
+    };
+    const port = await listen(
+      createTenantHost({
+        source: slowSource,
+        process: { port: 0, nodeEnv: 'test', trustProxy: '' },
+        runtime: { activate: async (d) => ({ core: {}, app: tenantApp(d.slug) }) as unknown as TenantGraph, stop: async () => undefined },
+      }),
+    );
+    const socket = net.connect(port, '127.0.0.1');
+    await new Promise<void>((resolve) => socket.on('connect', resolve));
+    socket.write('GET /api/whoami HTTP/1.1\r\nHost: acme.test\r\n\r\n');
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    socket.destroy();
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    const runtime = host!.runtimes().get('acme');
+    expect(runtime?.open).toBe(0);
+    // ...and a client that stays is still counted, and left once it goes.
+    const served = await request(port, '/api/whoami', 'acme.test');
+    expect(served.status).toBe(200);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    expect(runtime?.open).toBe(0);
+  });
+
+  it('keeps a tenant with an open response alive through the sweep, and lets it go once that response closes', async () => {
+    const events: string[] = [];
+    const streams: import('express').Response[] = [];
+    let now = 0;
+    const port = await listen(
+      createTenantHost({
+        source,
+        process: { port: 0, nodeEnv: 'test', trustProxy: '' },
+        idleMinutes: 1,
+        sweepIntervalMs: 10,
+        runtime: {
+          activate: async (d) => {
+            events.push(`activate:${d.slug}`);
+            const app = express();
+            // An event stream: headers sent, body held open until told.
+            app.get('/api/events', (_req, res) => {
+              res.writeHead(200, { 'content-type': 'text/event-stream' });
+              res.write(': hello\n\n');
+              streams.push(res);
+            });
+            return { core: {}, app } as unknown as TenantGraph;
+          },
+          stop: async (g) => {
+            events.push('stop');
+            void g;
+          },
+          busy: async () => false,
+          now: () => now,
+        },
+      }),
+    );
+    const opened = new Promise<http.IncomingMessage>((resolve, reject) => {
+      const req = http.request({ host: '127.0.0.1', port, path: '/api/events', headers: { host: 'acme.test' } }, resolve);
+      req.on('error', reject);
+      req.end();
+    });
+    const stream = await opened;
+    expect(stream.statusCode).toBe(200);
+    expect(streams).toHaveLength(1);
+    expect(host!.runtimes().get('acme')?.open).toBe(1);
+    // An hour with no new request, and several sweeps: the stream keeps it.
+    now += 3_600_000;
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    expect(host!.runtimes().get('acme')?.state).toBe('active');
+    expect(events).toEqual(['activate:acme']);
+    // The stream ends; idleness counts from here, so it is not evicted yet...
+    streams[0]!.end();
+    await new Promise<void>((resolve) => stream.on('end', resolve).resume());
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    expect(host!.runtimes().get('acme')?.state).toBe('active');
+    // ...and a minute after it closed, it is.
+    now += 61_000;
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    expect(host!.runtimes().get('acme')?.state).toBe('idle');
+    expect(events).toEqual(['activate:acme', 'stop']);
+  });
+
+  it('answers 503 with Retry-After while a tenant is still starting, and when its start failed', async () => {
+    let fail = true;
+    let release: (() => void) | null = null;
+    const port = await listen(
+      createTenantHost({
+        source,
+        process: { port: 0, nodeEnv: 'test', trustProxy: '' },
+        activationWaitMs: 50,
+        runtime: {
+          // No retry window here: the second request must try again at once.
+          retry: { initialMs: 0 },
+          activate: async (d) => {
+            if (fail) throw new Error('no');
+            await new Promise<void>((resolve) => {
+              release = resolve;
+            });
+            return { core: {}, app: tenantApp(d.slug) } as unknown as TenantGraph;
+          },
+          stop: async () => undefined,
+        },
+      }),
+    );
+    const failed = await request(port, '/api/whoami', 'acme.test');
+    expect(failed.status).toBe(503);
+    expect(failed.headers['retry-after']).toBe('5');
+
+    fail = false;
+    const slow = await request(port, '/api/whoami', 'acme.test');
+    expect(slow.status).toBe(503);
+    // The activation keeps going behind the 503; once it lands, the next request is served.
+    release!();
+    const served = await request(port, '/api/whoami', 'acme.test');
+    expect(served.status).toBe(200);
+  });
+
+  it('evicts every tenant on stop, and an idle tenant on the sweep, then reactivates on demand', async () => {
+    const events: string[] = [];
+    let now = 0;
+    const port = await listen(
+      createTenantHost({
+        source,
+        process: { port: 0, nodeEnv: 'test', trustProxy: '' },
+        idleMinutes: 1,
+        sweepIntervalMs: 10,
+        runtime: {
+          activate: async (d) => {
+            events.push(`activate:${d.slug}`);
+            return { core: {}, app: tenantApp(d.slug) } as unknown as TenantGraph;
+          },
+          stop: async (g) => {
+            events.push(`stop:${(g.app as unknown as { slug?: string }).slug ?? ''}`);
+          },
+          busy: async () => false,
+          now: () => now,
+        },
+      }),
+    );
+    await request(port, '/api/whoami', 'acme.test');
+    expect(events).toEqual(['activate:acme']);
+    // A minute passes with no request: the sweep stops the graph.
+    now += 61_000;
+    await new Promise((resolve) => setTimeout(resolve, 60));
+    expect(host!.runtimes().get('acme')?.state).toBe('idle');
+    // ...and the next request brings it back.
+    await request(port, '/api/whoami', 'acme.test');
+    expect(events.filter((e) => e === 'activate:acme')).toHaveLength(2);
+    await host!.stop();
+    expect(host!.runtimes().get('acme')?.state).toBe('idle');
+  });
+});

package/src/tenancy/__tests__/tenant-runtime.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect } from 'vitest';
+import type { TenantConfig } from '../../core-config.js';
+import { TenantRuntime, type TenantGraph } from '../tenant-runtime.js';
+import type { TenantDescriptor } from '../tenant-source.contract.js';
+
+const descriptor: TenantDescriptor = { slug: 'acme', hosts: ['acme.test'], config: {} as TenantConfig };
+
+/** A graph builder whose completion the test controls. */
+function harness(opts: { fail?: boolean | (() => boolean); now?: () => number; retry?: { initialMs: number; maxMs: number } } = {}) {
+  const events: string[] = [];
+  let release: (() => void) | null = null;
+  let activations = 0;
+  const runtime = new TenantRuntime(descriptor, {
+    activate: async () => {
+      activations += 1;
+      events.push(`activate:${activations}`);
+      await new Promise<void>((resolve) => {
+        release = resolve;
+      });
+      if (typeof opts.fail === 'function' ? opts.fail() : opts.fail) throw new Error('the remote said no');
+      return { core: { id: activations } } as unknown as TenantGraph;
+    },
+    stop: async (graph) => {
+      events.push(`stop:${(graph.core as unknown as { id: number }).id}`);
+    },
+    busy: async () => false,
+    now: opts.now,
+    retry: opts.retry,
+  });
+  return { runtime, events, finish: () => release?.(), activations: () => activations };
+}
+
+const settle = () => new Promise((resolve) => setImmediate(resolve));
+
+describe('TenantRuntime', () => {
+  it('builds the graph once for a burst of first requests, and hands every one the same graph', async () => {
+    const h = harness();
+    expect(h.runtime.state).toBe('idle');
+    const first = h.runtime.handle();
+    const second = h.runtime.handle();
+    const third = h.runtime.handle();
+    await settle();
+    expect(h.runtime.state).toBe('activating');
+    h.finish();
+    const graphs = await Promise.all([first, second, third]);
+    expect(h.activations()).toBe(1);
+    expect(graphs[1]).toBe(graphs[0]);
+    expect(graphs[2]).toBe(graphs[0]);
+    expect(h.runtime.state).toBe('active');
+    // Once active, a request is answered from the running graph.
+    expect(await h.runtime.handle()).toBe(graphs[0]);
+    expect(h.activations()).toBe(1);
+  });
+
+  it('remembers a failed activation for a growing window, and tries again once it has passed', async () => {
+    let now = 0;
+    const h = harness({ fail: true, now: () => now, retry: { initialMs: 100, maxMs: 300 } });
+    const first = h.runtime.handle();
+    await settle();
+    h.finish();
+    await expect(first).rejects.toThrow('the remote said no');
+    expect(h.runtime.state).toBe('idle');
+
+    // Inside the window: the same failure, from memory, without a build.
+    now = 99;
+    await expect(h.runtime.handle()).rejects.toThrow('the remote said no');
+    expect(h.activations()).toBe(1);
+
+    // Past it: tried again; a second failure doubles the window.
+    now = 100;
+    const second = h.runtime.handle();
+    await settle();
+    expect(h.activations()).toBe(2);
+    h.finish();
+    await expect(second).rejects.toThrow();
+    now = 299;
+    await expect(h.runtime.handle()).rejects.toThrow();
+    expect(h.activations()).toBe(2);
+
+    // The window is capped: 100, 200, then 300 and no more.
+    now = 300;
+    const third = h.runtime.handle();
+    await settle();
+    h.finish();
+    await expect(third).rejects.toThrow();
+    now = 599;
+    await expect(h.runtime.handle()).rejects.toThrow();
+    now = 600;
+    const fourth = h.runtime.handle();
+    await settle();
+    expect(h.activations()).toBe(4);
+    h.finish();
+    await expect(fourth).rejects.toThrow();
+    now = 899;
+    await expect(h.runtime.handle()).rejects.toThrow();
+    expect(h.activations()).toBe(4);
+  });
+
+  it('forgets the failures once an activation succeeds', async () => {
+    let now = 0;
+    let fail = true;
+    const h = harness({ fail: () => fail, now: () => now, retry: { initialMs: 100, maxMs: 300 } });
+    const first = h.runtime.handle();
+    await settle();
+    h.finish();
+    await expect(first).rejects.toThrow();
+    fail = false;
+    now = 100;
+    const ok = h.runtime.handle();
+    await settle();
+    h.finish();
+    await ok;
+    expect(h.runtime.state).toBe('active');
+    // A later failure, after an eviction, starts the window from the beginning.
+    await h.runtime.evict();
+    fail = true;
+    const again = h.runtime.handle();
+    await settle();
+    h.finish();
+    await expect(again).rejects.toThrow();
+    now = 199;
+    await expect(h.runtime.handle()).rejects.toThrow();
+    now = 200;
+    const retried = h.runtime.handle();
+    await settle();
+    expect(h.activations()).toBe(4);
+    h.finish();
+    await expect(retried).rejects.toThrow();
+  });
+
+  it('evicts a running graph, and builds a fresh one on the next request', async () => {
+    const h = harness();
+    const pending = h.runtime.handle();
+    await settle();
+    h.finish();
+    await pending;
+    await h.runtime.evict();
+    expect(h.events).toEqual(['activate:1', 'stop:1']);
+    expect(h.runtime.state).toBe('idle');
+    const next = h.runtime.handle();
+    await settle();
+    h.finish();
+    await next;
+    expect(h.events).toEqual(['activate:1', 'stop:1', 'activate:2']);
+  });
+
+  it('an eviction that lands during an activation waits for it and stops what it built', async () => {
+    const h = harness();
+    const pending = h.runtime.handle();
+    await settle();
+    const evicting = h.runtime.evict();
+    expect(h.runtime.state).toBe('evicting');
+    h.finish();
+    await pending;
+    await evicting;
+    expect(h.events).toEqual(['activate:1', 'stop:1']);
+    expect(h.runtime.state).toBe('idle');
+  });
+
+  it('a second eviction joins the one under way, and evicting an idle runtime stops nothing', async () => {
+    const h = harness();
+    await h.runtime.evict();
+    expect(h.events).toEqual([]);
+    const pending = h.runtime.handle();
+    await settle();
+    h.finish();
+    await pending;
+    const a = h.runtime.evict();
+    const b = h.runtime.evict();
+    await Promise.all([a, b]);
+    expect(h.events).toEqual(['activate:1', 'stop:1']);
+  });
+
+  it('measures idleness from the last request, and reports busy only for a running graph', async () => {
+    let now = 1_000;
+    let busy = false;
+    const runtime = new TenantRuntime(descriptor, {
+      activate: async () => ({ core: {} } as unknown as TenantGraph),
+      stop: async () => undefined,
+      busy: async () => busy,
+      now: () => now,
+    });
+    expect(await runtime.busy()).toBe(false);
+    await runtime.handle();
+    now += 5_000;
+    expect(runtime.idleFor()).toBe(5_000);
+    await runtime.handle();
+    expect(runtime.idleFor()).toBe(0);
+    busy = true;
+    expect(await runtime.busy()).toBe(true);
+  });
+
+  it('is busy while any response is open, and counts idleness from the last one that closed', async () => {
+    let now = 1_000;
+    const runtime = new TenantRuntime(descriptor, {
+      activate: async () => ({ core: {} } as unknown as TenantGraph),
+      stop: async () => undefined,
+      busy: async () => false,
+      now: () => now,
+    });
+    await runtime.handle();
+    // An event stream a browser holds: entered long ago, never left.
+    runtime.enter();
+    runtime.enter();
+    now += 3_600_000;
+    expect(runtime.idleFor()).toBe(3_600_000);
+    expect(await runtime.busy()).toBe(true);
+    expect(runtime.open).toBe(2);
+    runtime.leave();
+    expect(await runtime.busy()).toBe(true);
+    // The last response closing is what idleness counts from.
+    now += 10;
+    runtime.leave();
+    expect(runtime.open).toBe(0);
+    expect(runtime.idleFor()).toBe(0);
+    expect(await runtime.busy()).toBe(false);
+    // A stray leave cannot make the count negative.
+    runtime.leave();
+    expect(runtime.open).toBe(0);
+  });
+});

package/src/tenancy/__tests__/tenant-secrets.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { deriveTenantSecrets } from '../tenant-secrets.js';
+
+const MASTER = 'a-master-key-that-is-long-enough-to-count-as-random';
+
+describe('deriveTenantSecrets', () => {
+  it('is reproducible: the same master key and slug give the same secrets, on the day of an export too', () => {
+    expect(deriveTenantSecrets(MASTER, 'acme')).toEqual(deriveTenantSecrets(MASTER, 'acme'));
+  });
+
+  it('gives each tenant, and each of the three secrets, a value of its own', () => {
+    const acme = deriveTenantSecrets(MASTER, 'acme');
+    const globex = deriveTenantSecrets(MASTER, 'globex');
+    expect(acme.jwtSecret).not.toBe(globex.jwtSecret);
+    expect(acme.secretsEncKey).not.toBe(globex.secretsEncKey);
+    expect(acme.internalTokenSecret).not.toBe(globex.internalTokenSecret);
+    expect(new Set([acme.jwtSecret, acme.secretsEncKey, acme.internalTokenSecret]).size).toBe(3);
+  });
+
+  it('derives 32-byte keys, which is what the vault encryption requires', () => {
+    const { secretsEncKey } = deriveTenantSecrets(MASTER, 'acme');
+    expect(Buffer.from(secretsEncKey, 'base64')).toHaveLength(32);
+  });
+
+  it('changes every secret when the master key changes', () => {
+    const a = deriveTenantSecrets(MASTER, 'acme');
+    const b = deriveTenantSecrets(`${MASTER}-rotated`, 'acme');
+    expect(a.jwtSecret).not.toBe(b.jwtSecret);
+  });
+
+  it('refuses a master key too short to be random, and a missing slug', () => {
+    expect(() => deriveTenantSecrets('short', 'acme')).toThrow(/TENANT_MASTER_KEY/);
+    expect(() => deriveTenantSecrets(MASTER, '')).toThrow(/slug/);
+  });
+});

package/src/tenancy/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Serving several knowledge bases from one process — see
+ * `docs/multi-tenant.md` and `openspec/changes/multi-tenant-runtime`.
+ *
+ * The contract (`TenantSource`) and the mechanism (runtime, host) are core's;
+ * where tenants come from is the caller's. Core ships a file-based source.
+ */
+export {
+  assertTenantSlug,
+  normalizeHost,
+  TENANT_SLUG_PATTERN,
+  type TenantDescriptor,
+  type TenantSource,
+} from './tenant-source.contract.js';
+export { deriveTenantSecrets, type TenantSecrets } from './tenant-secrets.js';
+export {
+  StaticTenantSource,
+  tenantConfigFrom,
+  tenantHostEnv,
+  type TenantHostEnv,
+  type TenantHostSettings,
+  type TenantRecord,
+  type TenantsFile,
+} from './static-tenant-source.js';
+export { TenantRuntime, type TenantGraph, type TenantRuntimeDeps, type TenantState } from './tenant-runtime.js';
+export {
+  createTenantHost,
+  isLoopbackAddress,
+  loopbackTenantBaseUrl,
+  selectTenant,
+  LOOPBACK_TENANT_PREFIX,
+  type TenantHost,
+  type TenantHostOptions,
+  type TenantSelector,
+} from './tenant-host.js';