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

package/src/shared/kb-context.ts

@@ -0,0 +1,130 @@
+import {
+  UNCONFIGURED_BRANCH_MODEL,
+  isBranchModelConfigured,
+  isProtectedBranch,
+  resolveBranchModel,
+  resolveKbLayout,
+  validateBranchModel,
+  type BranchModel,
+  type BranchModelValue,
+  type KbLayout,
+} from '@bevel-software/platform-shared';
+import { workspaceIdForBranch } from './workspace-id.js';
+
+/**
+ * What ONE knowledge base is called, on disk and in git: the checkout folder
+ * inside each workspace, the branch model (default + protected branches) and
+ * the layout (the three renameable roots and the guide's file name).
+ *
+ * Every service that needs one of these is handed the knowledge base's
+ * context at construction and reads it there — never a process-wide value.
+ * The shared package's live bindings (`DEFAULT_BRANCH`, `PLUGINS_DIR`, …) are
+ * the BROWSER'S copy of the same facts and are forbidden in this package by
+ * an ESLint rule: a server hosting several knowledge bases in one process has
+ * no single value to put there, and a service that read one would be reading
+ * whichever knowledge base configured it last.
+ *
+ * LIVE, PER INSTANCE. The values are read through getters, not captured, for
+ * the same reason the live bindings were: a fresh deployment has no branch
+ * model until its setup screen is answered, and the save that completes setup
+ * applies one to the running graph — through {@link applyBranchModel} and
+ * {@link applyLayout} — so the knowledge-base startup phase that runs in that
+ * same request already sees it. Read `defaultBranch` inside a method body;
+ * a value copied into a field at construction would be the empty string on
+ * exactly those deployments.
+ */
+export class KbContext {
+  private model: BranchModelValue;
+  private layoutValue: Required<KbLayout>;
+  private readonly layoutListeners = new Set<() => void>();
+  private readonly branchModelListeners = new Set<() => void>();
+
+  constructor(
+    /** The checkout folder inside each workspace directory (`knowledge-base` by default). */
+    readonly kbDirName: string,
+    branchModel: BranchModelValue,
+    layout: KbLayout,
+  ) {
+    this.model = branchModel;
+    this.layoutValue = resolveKbLayout(layout);
+  }
+
+  /**
+   * The model as a deployment's settings describe it, or the unconfigured one
+   * when they describe none yet. UNCONFIGURED IS ALLOWED, and that is the
+   * point: a fresh deployment has no branch model, and refusing to build
+   * services would take away the setup screen where one gets entered. What
+   * reads the model before then is the setup path itself, which does not need
+   * it; the setup gate keeps the rest of the app shut until it is set.
+   */
+  static branchModelOrUnconfigured(model: BranchModel): BranchModelValue {
+    return validateBranchModel(model) ? UNCONFIGURED_BRANCH_MODEL : resolveBranchModel(model);
+  }
+
+  get branchModel(): BranchModelValue {
+    return this.model;
+  }
+
+  /** The branch users land on and the default propose target; `''` until configured. */
+  get defaultBranch(): string {
+    return this.model.defaultBranch;
+  }
+
+  get protectedBranches(): ReadonlySet<string> {
+    return this.model.protectedBranches;
+  }
+
+  isProtectedBranch(name: string | null | undefined): boolean {
+    return isProtectedBranch(this.model, name);
+  }
+
+  isBranchModelConfigured(): boolean {
+    return isBranchModelConfigured(this.model);
+  }
+
+  /** The workspace id of the default branch's clone — the released catalog's home. */
+  defaultWorkspaceId(): string {
+    return workspaceIdForBranch(this.model.defaultBranch);
+  }
+
+  /** The layout in effect: the three roots and the guide's file name, every name trimmed. */
+  get layout(): Required<KbLayout> {
+    return this.layoutValue;
+  }
+
+  /**
+   * Apply a branch model to the running graph — the setup-completing save.
+   * Validated like every model, so a bad pair is refused rather than applied
+   * half-way. Listeners run after the value is in place.
+   */
+  applyBranchModel(model: BranchModel): void {
+    this.model = resolveBranchModel(model);
+    for (const listener of this.branchModelListeners) listener();
+  }
+
+  /**
+   * Apply a layout to the running graph — the setup-completing save, so the
+   * knowledge-base phase that runs in the same request scaffolds the names the
+   * admin just chose. Throws on an invalid one. Listeners run after the value
+   * is in place, and only when the layout was accepted.
+   */
+  applyLayout(layout: KbLayout): void {
+    this.layoutValue = resolveKbLayout(layout);
+    for (const listener of this.layoutListeners) listener();
+  }
+
+  /**
+   * Be told when {@link applyLayout} runs — for the few things that cannot
+   * read the layout at the moment they are used: a value BUILT ONCE and handed
+   * to something that keeps it, such as the tool catalog's descriptions, which
+   * are validated into frozen defs at registration and then served from a map.
+   */
+  onLayoutApplied(listener: () => void): void {
+    this.layoutListeners.add(listener);
+  }
+
+  /** Be told when {@link applyBranchModel} runs. */
+  onBranchModelApplied(listener: () => void): void {
+    this.branchModelListeners.add(listener);
+  }
+}

package/src/shared/kb-layout.test.ts

@@ -1,32 +1,42 @@
 import { describe, it, expect } from 'vitest';
+import { DEFAULT_KB_LAYOUT } from '@bevel-software/platform-shared';
 import { ontologyOf } from './kb-layout.js';
 
+/** `ontologyOf` under the default layout, which is what these cases are written against. */
+const ont = (path: string, kbDirName?: string) => ontologyOf(path, DEFAULT_KB_LAYOUT, kbDirName);
+
 describe('ontologyOf', () => {
+  it('classifies under the knowledge-base root the layout names, not the default one', () => {
+    const layout = { ...DEFAULT_KB_LAYOUT, knowledgeBaseDir: 'docs' };
+    expect(ontologyOf('docs/Product/Knowledge/Foo.md', layout)).toBe('docs/Product');
+    expect(ontologyOf('KnowledgeBase/Product/Knowledge/Foo.md', layout)).toBeNull();
+  });
+
   it('resolves a named ontology under Knowledge', () => {
-    expect(ontologyOf('KnowledgeBase/Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
   });
 
   it('resolves a named ontology under NodeTypes', () => {
-    expect(ontologyOf('KnowledgeBase/Product/NodeTypes/Process.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Product/NodeTypes/Process.md')).toBe('KnowledgeBase/Product');
   });
 
   it('is space-safe in the ontology name', () => {
-    expect(ontologyOf('KnowledgeBase/IT Architecture/NodeTypes/ServiceCommitment.md')).toBe(
+    expect(ont('KnowledgeBase/IT Architecture/NodeTypes/ServiceCommitment.md')).toBe(
       'KnowledgeBase/IT Architecture',
     );
   });
 
   it('treats a nested ontology directory as the full prefix before the marker', () => {
-    expect(ontologyOf('KnowledgeBase/Plugin/Sub/Knowledge/x.md')).toBe('KnowledgeBase/Plugin/Sub');
+    expect(ont('KnowledgeBase/Plugin/Sub/Knowledge/x.md')).toBe('KnowledgeBase/Plugin/Sub');
   });
 
   it('returns null when the marker sits directly under KnowledgeBase/', () => {
-    expect(ontologyOf('KnowledgeBase/Knowledge/Foo.md')).toBeNull();
-    expect(ontologyOf('KnowledgeBase/NodeTypes/T.md')).toBeNull();
+    expect(ont('KnowledgeBase/Knowledge/Foo.md')).toBeNull();
+    expect(ont('KnowledgeBase/NodeTypes/T.md')).toBeNull();
   });
 
   it('returns null for root-level Knowledge (not under KnowledgeBase/)', () => {
-    expect(ontologyOf('Knowledge/Foo.md')).toBeNull();
+    expect(ont('Knowledge/Foo.md')).toBeNull();
   });
 
   it('returns null for Data/ ontologies (deliberate session-ontology exemption)', () => {
@@ -35,54 +45,54 @@ describe('ontologyOf', () => {
     // Data paths as neutral — pipeline agents read knowledge and write data
     // in one session (owner decision 2026-07-27). See the `ontologyOf`
     // docstring; this is not drift.
-    expect(ontologyOf('Data/Ops/Knowledge/x.md')).toBeNull();
-    expect(ontologyOf('Data/Ops/NodeTypes/Ticket.md')).toBeNull();
+    expect(ont('Data/Ops/Knowledge/x.md')).toBeNull();
+    expect(ont('Data/Ops/NodeTypes/Ticket.md')).toBeNull();
     // KnowledgeBase paths still classify as before.
-    expect(ontologyOf('KnowledgeBase/Ops/Knowledge/x.md')).toBe('KnowledgeBase/Ops');
+    expect(ont('KnowledgeBase/Ops/Knowledge/x.md')).toBe('KnowledgeBase/Ops');
   });
 
   it('returns null for Plugins and root config (neutral)', () => {
-    expect(ontologyOf('Plugins/some-skill/SKILL.md')).toBeNull();
-    expect(ontologyOf('access.md')).toBeNull();
-    expect(ontologyOf('roles.yaml')).toBeNull();
+    expect(ont('Plugins/some-skill/SKILL.md')).toBeNull();
+    expect(ont('access.md')).toBeNull();
+    expect(ont('roles.yaml')).toBeNull();
   });
 
   it('returns null for an ontology path with no marker segment', () => {
-    expect(ontologyOf('KnowledgeBase/Product/Uploads/diagram.png')).toBeNull();
+    expect(ont('KnowledgeBase/Product/Uploads/diagram.png')).toBeNull();
   });
 
   it('does not match substring lookalikes (segment equality)', () => {
-    expect(ontologyOf('KnowledgeBase/Product/Knowledge-notes.md')).toBeNull();
-    expect(ontologyOf('KnowledgeBase/Product/KnowledgeBase/x.md')).toBeNull();
+    expect(ont('KnowledgeBase/Product/Knowledge-notes.md')).toBeNull();
+    expect(ont('KnowledgeBase/Product/KnowledgeBase/x.md')).toBeNull();
   });
 
   it('strips a kbDirName prefix (normalized and un-normalized)', () => {
-    expect(ontologyOf('knowledge-base/KnowledgeBase/Product/Knowledge/Foo.md', 'knowledge-base')).toBe(
+    expect(ont('knowledge-base/KnowledgeBase/Product/Knowledge/Foo.md', 'knowledge-base')).toBe(
       'KnowledgeBase/Product',
     );
-    expect(ontologyOf('./knowledge-base/KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base/')).toBe(
+    expect(ont('./knowledge-base/KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base/')).toBe(
       'KnowledgeBase/GTM',
     );
   });
 
   it('normalizes backslashes and leading/trailing slashes', () => {
-    expect(ontologyOf('/KnowledgeBase/Product/Knowledge/Foo.md/')).toBe('KnowledgeBase/Product');
-    expect(ontologyOf('KnowledgeBase\\Product\\Knowledge\\Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('/KnowledgeBase/Product/Knowledge/Foo.md/')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase\\Product\\Knowledge\\Foo.md')).toBe('KnowledgeBase/Product');
   });
 
   it('canonicalizes inner . and .. segments to the same ontology', () => {
-    expect(ontologyOf('KnowledgeBase/Product/./Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
-    expect(ontologyOf('KnowledgeBase/Product/Sub/../Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
-    expect(ontologyOf('KnowledgeBase/Platform/../Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Product/./Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Product/Sub/../Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
+    expect(ont('KnowledgeBase/Platform/../Product/Knowledge/Foo.md')).toBe('KnowledgeBase/Product');
     // `..` also collapses inside the stripped kbDirName prefix.
-    expect(ontologyOf('knowledge-base/x/../KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base')).toBe(
+    expect(ont('knowledge-base/x/../KnowledgeBase/GTM/NodeTypes/T.md', 'knowledge-base')).toBe(
       'KnowledgeBase/GTM',
     );
   });
 
   it('returns null for empty or root paths', () => {
-    expect(ontologyOf('')).toBeNull();
-    expect(ontologyOf('KnowledgeBase')).toBeNull();
-    expect(ontologyOf('KnowledgeBase/Product')).toBeNull();
+    expect(ont('')).toBeNull();
+    expect(ont('KnowledgeBase')).toBeNull();
+    expect(ont('KnowledgeBase/Product')).toBeNull();
   });
 });

package/src/shared/kb-layout.ts

@@ -1,4 +1,4 @@
-import { KNOWLEDGE_BASE_DIR, ONTOLOGY_MARKERS, type Ontology } from '@bevel-software/platform-shared';
+import { ONTOLOGY_MARKERS, type KbLayout, type Ontology } from '@bevel-software/platform-shared';
 
 /**
  * Resolve which named ontology a KB path belongs to — the backend-side
@@ -81,13 +81,14 @@ function toSegments(path: string, kbDirName?: string): string[] {
  * `Knowledge-notes.md` are never treated as markers; space-safe; pure (no IO).
  *
  * @param path       repo-root-relative POSIX path (may carry a `kbDirName` prefix)
+ * @param layout     the knowledge base's layout — names its `KnowledgeBase/` root
  * @param kbDirName  optional on-disk clone folder prefix to strip first
  */
-export function ontologyOf(path: string, kbDirName?: string): Ontology {
+export function ontologyOf(path: string, layout: KbLayout, kbDirName?: string): Ontology {
   const segs = toSegments(path, kbDirName);
   // Must live under the dedicated KnowledgeBase/ container, with at least one
   // ontology-name segment and a marker after it (so length >= 3).
-  if (segs.length < 3 || segs[0] !== KNOWLEDGE_BASE_DIR) return null;
+  if (segs.length < 3 || segs[0] !== layout.knowledgeBaseDir) return null;
   // The ontology id is the prefix before the first marker segment. Require at
   // least one name segment between `KnowledgeBase/` and the marker, so a marker
   // sitting directly under `KnowledgeBase/` (`KnowledgeBase/Knowledge/...`) is

package/src/shared/pending-proposals.ts

@@ -1,6 +1,6 @@
-import { DEFAULT_BRANCH, type ChangeRequest, type IWorkflowService } from '@bevel-software/platform-shared';
+import type { ChangeRequest, IWorkflowService } from '@bevel-software/platform-shared';
 import type { WorkspaceService } from '../modules/workspace/workspace.service.js';
-import { workspaceIdForBranch } from './workspace-id.js';
+import type { KbContext } from './kb-context.js';
 import type { IAccessControl } from '../modules/access/access-control.interface.js';
 import { canonicalEmail, hashEmail } from './email-identity.js';
 import { printable } from './printable.js';
@@ -34,6 +34,8 @@ export interface ProposalSources {
   workspaceService: Pick<WorkspaceService, 'ensureRemotesFetched' | 'readFileAtRef'>;
   accessControl: Pick<IAccessControl, 'canWriteBatch'>;
   workflow: Pick<IWorkflowService, 'listChangeRequests'>;
+  /** Which branch is the released one, and its clone. */
+  kb: Pick<KbContext, 'defaultBranch' | 'defaultWorkspaceId'>;
 }
 
 /** One file an open change request proposes, already read at that request's branch. */
@@ -78,8 +80,9 @@ export async function visibleProposedFiles(
     // access tree that decides who may review — so a request targeting some
     // other branch is not a proposal these surfaces can speak about: merging it
     // puts nothing in the catalog, and the card would never resolve.
+    const defaultBranch = sources.kb.defaultBranch;
     crs = (await sources.workflow.listChangeRequests()).filter(
-      (c) => c.state === 'open' && c.base === DEFAULT_BRANCH,
+      (c) => c.state === 'open' && c.base === defaultBranch,
     );
   } catch {
     return [];
@@ -91,7 +94,7 @@ export async function visibleProposedFiles(
   );
   if (candidates.length === 0) return [];
 
-  const wsId = workspaceIdForBranch(DEFAULT_BRANCH);
+  const wsId = sources.kb.defaultWorkspaceId();
   const authorHash = hashEmail(email);
 
   // One access load for every candidate, resolved on the DEFAULT branch — see

package/src/shared/redact-secret.ts

@@ -6,11 +6,11 @@
  * presigned remote keeps its credential.
  *
  * "The token in effect" is every place one can come from: each environment
- * spelling `CoreConfig` accepts (it normalises them onto `GITHUB_TOKEN` at
- * boot, but a later write to one of them is not normalised), plus whatever the
- * caller knows about — the settings-stored token, a token a request brought
- * along, or a remote's query values ({@link urlQuerySecrets}). Longest first,
- * so a secret that contains another is not half-scrubbed.
+ * spelling `CoreConfig` accepts (the operator's, process-wide), plus whatever
+ * the caller knows about — the knowledge base's own token as its git runner
+ * carries it, a token a request brought along, or a remote's query values
+ * ({@link urlQuerySecrets}). Longest first, so a secret that contains another
+ * is not half-scrubbed.
  *
  * Shared, not a module's own: the KB startup phase and the setup routes both
  * log git's words, and one scrub is the only way they cannot disagree about

package/src/tenancy/__tests__/static-tenant-source.test.ts

@@ -0,0 +1,177 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { StaticTenantSource, tenantConfigFrom, tenantHostEnv, type TenantHostSettings } from '../static-tenant-source.js';
+
+const settings: TenantHostSettings = {
+  databaseUrl: 'postgresql://u:p@db:5432/hexis',
+  port: 3001,
+  nodeEnv: 'production',
+  trustProxy: '1',
+  workspacesRoot: path.resolve('/srv/hexis/workspaces'),
+  kbTemplateDir: '/srv/hexis/template',
+  gitTimeoutMs: 120_000,
+  ontologySessionBlock: true,
+  updateCheckEnabled: false,
+  masterKey: 'a-master-key-that-is-long-enough-to-count-as-random',
+};
+
+const acme = { slug: 'acme-2', hosts: ['Acme.example.test:443', 'acme.internal'], adminEmail: 'Owner@Acme.test' };
+
+describe('tenantConfigFrom', () => {
+  it('names the schema, the folders and the credential prefixes after the slug, so two tenants never share one', () => {
+    const config = tenantConfigFrom(acme, settings);
+    expect(config.dbSchema).toBe('t_acme_2');
+    expect(config.tenantId).toBe('acme2');
+    expect(config.externalApiKeyPrefix).toBe('acme2_');
+    expect(config.workspacesRoot).toBe(path.resolve('/srv/hexis/workspaces/acme-2'));
+    expect(config.backupsRoot).toBe(path.resolve('/srv/hexis/backups/acme-2'));
+    expect(config.spillRoot).toBe(path.resolve('/srv/hexis/tool-chain-spills/acme-2'));
+    expect(config.docExtractCacheRoot).toBe(path.resolve('/srv/hexis/doc-extract-cache/acme-2'));
+    expect(config.loopbackBaseUrl).toBe('http://127.0.0.1:3001/_tenant/acme-2');
+  });
+
+  it('takes the public address from the first host, and the process facts from the host settings', () => {
+    const config = tenantConfigFrom(acme, settings);
+    expect(config.publicBackendUrl).toBe('https://acme.example.test');
+    expect(config.publicFrontendUrl).toBe('https://acme.example.test');
+    expect(config.configuredPublicFrontendUrl).toBe('https://acme.example.test');
+    expect(config.adminEmail).toBe('owner@acme.test');
+    expect(config).toMatchObject({ port: 3001, nodeEnv: 'production', trustProxy: '1', databaseUrl: settings.databaseUrl });
+  });
+
+  it('hands the graph its settings as an environment of its own: the record\'s values and nothing of the host\'s', () => {
+    const config = tenantConfigFrom(
+      {
+        ...acme,
+        kbRepoUrl: 'https://github.com/acme/kb.git',
+        gitToken: 'ghp_acme',
+        defaultBranch: 'main',
+        protectedBranches: ['main', 'staging'],
+        allowedEmailDomains: ['@Acme.com'],
+        oidc: { issuerUrl: 'https://login.acme.com', clientId: 'cid', clientSecret: 'sec' },
+      },
+      settings,
+    );
+    expect(config.settingsEnv).toEqual({
+      KB_REPO_URL: 'https://github.com/acme/kb.git',
+      GIT_TOKEN: 'ghp_acme',
+      DEFAULT_BRANCH: 'main',
+      PROTECTED_BRANCHES: 'main,staging',
+      OIDC_ISSUER_URL: 'https://login.acme.com',
+      OIDC_CLIENT_ID: 'cid',
+      OIDC_CLIENT_SECRET: 'sec',
+      ALLOWED_EMAIL_DOMAINS: 'acme.com',
+    });
+    // A record naming nothing pins nothing: the setup screen collects it,
+    // and the defaults stay defaults rather than becoming "set outside the app".
+    expect(tenantConfigFrom(acme, settings).settingsEnv).toEqual({});
+  });
+
+  it('derives the three secrets from the master key, differently per tenant', () => {
+    const a = tenantConfigFrom(acme, settings);
+    const b = tenantConfigFrom({ ...acme, slug: 'globex', hosts: ['globex.example.test'] }, settings);
+    expect(Buffer.from(a.secretsEncKey, 'base64')).toHaveLength(32);
+    expect(a.jwtSecret).not.toBe(b.jwtSecret);
+    expect(a).toEqual(tenantConfigFrom(acme, settings));
+  });
+
+  it('turns password login on exactly when a bootstrap password is given, unless told otherwise', () => {
+    expect(tenantConfigFrom(acme, settings).loginPasswordEnabled).toBe(false);
+    expect(tenantConfigFrom({ ...acme, adminPassword: 'pw' }, settings).loginPasswordEnabled).toBe(true);
+    expect(tenantConfigFrom({ ...acme, adminPassword: 'pw', loginPassword: false }, settings).loginPasswordEnabled).toBe(false);
+    expect(() => tenantConfigFrom({ ...acme, loginPassword: true }, settings)).toThrow(/adminPassword/);
+  });
+
+  it('refuses a record that would name something wrong', () => {
+    expect(() => tenantConfigFrom({ ...acme, slug: 'Acme' }, settings)).toThrow(/slug/);
+    expect(() => tenantConfigFrom({ ...acme, hosts: [] }, settings)).toThrow(/host/);
+    expect(() => tenantConfigFrom({ ...acme, adminEmail: 'nobody' }, settings)).toThrow(/adminEmail/);
+    expect(() => tenantConfigFrom({ ...acme, gitUsername: 'x"; rm -rf /; #' }, settings)).toThrow(/gitUsername/);
+    expect(() => tenantConfigFrom({ ...acme, tenantId: 'ac-me' }, settings)).toThrow(/tenantId/);
+    expect(() => tenantConfigFrom({ ...acme, dbSchema: 'Public' }, settings)).toThrow(/schema name/);
+    // A tenant on the default schema would share a single-tenant deployment's
+    // tables and drizzle's own ledger schema: refused as a tenant's schema.
+    expect(() => tenantConfigFrom({ ...acme, dbSchema: 'public' }, settings)).toThrow(/schema of its own/);
+    expect(() => tenantConfigFrom({ ...acme, dbSchema: 'drizzle' }, settings)).toThrow(/reserved/);
+    expect(() => tenantConfigFrom({ ...acme, publicBackendUrl: 'not a url' }, settings)).toThrow(/publicBackendUrl/);
+  });
+});
+
+describe('StaticTenantSource', () => {
+  const source = new StaticTenantSource(
+    [acme, { slug: 'globex', hosts: ['globex.example.test'], adminEmail: 'o@globex.test' }],
+    settings,
+  );
+
+  it('resolves a host however it is spelled: case, port, trailing dot', async () => {
+    for (const host of ['acme.example.test', 'ACME.example.test', 'acme.example.test:3001', 'acme.internal.']) {
+      expect((await source.resolveByHost(host))?.slug, host).toBe('acme-2');
+    }
+    expect((await source.resolveByHost('globex.example.test'))?.slug).toBe('globex');
+    expect(await source.resolveByHost('nobody.example.test')).toBeNull();
+  });
+
+  it('describes a tenant by slug, and only a known one', async () => {
+    expect((await source.describe('globex'))?.config.dbSchema).toBe('t_globex');
+    expect(await source.describe('nobody')).toBeNull();
+    expect(source.slugs).toEqual(['acme-2', 'globex']);
+  });
+
+  it('refuses two tenants claiming one host, or one slug listed twice', () => {
+    expect(() => new StaticTenantSource([acme, { ...acme, slug: 'other' }], settings)).toThrow(/claimed by both/);
+    expect(() => new StaticTenantSource([acme, { ...acme, hosts: ['x.test'] }], settings)).toThrow(/listed twice/);
+  });
+
+  describe('fromFile', () => {
+    let dir: string;
+    afterEach(async () => {
+      if (dir) await fs.rm(dir, { recursive: true, force: true });
+    });
+
+    it('reads the tenants file', async () => {
+      dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tenants-'));
+      const file = path.join(dir, 'tenants.json');
+      await fs.writeFile(file, JSON.stringify({ tenants: [acme] }));
+      const fromFile = await StaticTenantSource.fromFile(file, settings);
+      expect((await fromFile.resolveByHost('acme.internal'))?.slug).toBe('acme-2');
+    });
+
+    it('names the file when it is not JSON or not a tenants list', async () => {
+      dir = await fs.mkdtemp(path.join(os.tmpdir(), 'tenants-'));
+      const file = path.join(dir, 'tenants.json');
+      await fs.writeFile(file, '{ nope');
+      await expect(StaticTenantSource.fromFile(file, settings)).rejects.toThrow(/not valid JSON/);
+      await fs.writeFile(file, JSON.stringify({ tenants: 'x' }));
+      await expect(StaticTenantSource.fromFile(file, settings)).rejects.toThrow(/"tenants" array/);
+    });
+  });
+});
+
+describe('tenantHostEnv', () => {
+  it('reads the host facts from the same variables a single-tenant deployment uses, plus the host\'s own', () => {
+    const env = tenantHostEnv({
+      TENANTS_FILE: '/etc/hexis/tenants.json',
+      TENANT_MASTER_KEY: 'a-master-key-that-is-long-enough-to-count-as-random',
+      TENANT_IDLE_MINUTES: '5',
+      DATABASE_URL: 'postgresql://u:p@db:5432/hexis',
+      PORT: '4000',
+      DOMAIN: 'hexis.example.test',
+      WORKSPACES_ROOT: '/data/workspaces',
+    });
+    expect(env).toMatchObject({
+      tenantsFile: '/etc/hexis/tenants.json',
+      idleMinutes: 5,
+      databaseUrl: 'postgresql://u:p@db:5432/hexis',
+      port: 4000,
+      trustProxy: '1',
+      workspacesRoot: '/data/workspaces',
+    });
+  });
+
+  it('is not a host without a tenants file, and refuses one without a master key', () => {
+    expect(tenantHostEnv({ DATABASE_URL: 'postgresql://x' }).tenantsFile).toBeNull();
+    expect(() => tenantHostEnv({ TENANTS_FILE: '/x.json', DATABASE_URL: 'postgresql://x' })).toThrow(/TENANT_MASTER_KEY/);
+  });
+});