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

package/dist/tenancy/tenant-host.js

@@ -0,0 +1,217 @@
+import express from 'express';
+import path from 'node:path';
+import { isIP } from 'node:net';
+import { GIT_SHA } from '../version.js';
+import { logger } from '../shared/logging.js';
+import { TenantRuntime } from './tenant-runtime.js';
+import { TENANT_SLUG_PATTERN, normalizeHost } from './tenant-source.contract.js';
+const log = logger('tenancy');
+/**
+ * The path prefix under which a process reaches ONE of its own tenants over
+ * loopback: `http://127.0.0.1:<port>/_tenant/<slug>/api/...`. The MCP proxy
+ * and the UTCP manuals it seeds dial the tenant's own REST surface this way,
+ * because a loopback request carries no tenant host name and a header cannot
+ * ride a UTCP call (the proxy is a passthrough; it reshapes nothing).
+ *
+ * The host honours the prefix only for a request that came from this
+ * machine AND was forwarded by nobody: the socket peer is loopback and there
+ * is no `X-Forwarded-For`. A reverse proxy on the same host (nginx, a
+ * Coolify proxy) delivers every public request from a loopback socket, and
+ * every such proxy adds that header; the process's own dial never does.
+ * What the prefix could grant anyone who got past this is only what the
+ * tenant's host name grants already — sessions, keys and tokens are per
+ * tenant — but the addressing rule is stated so it can be relied on.
+ */
+export const LOOPBACK_TENANT_PREFIX = '/_tenant';
+/** The base URL a tenant's graph dials itself at — see {@link LOOPBACK_TENANT_PREFIX}. */
+export function loopbackTenantBaseUrl(port, slug) {
+    return `http://127.0.0.1:${port}${LOOPBACK_TENANT_PREFIX}/${slug}`;
+}
+/** Whether `address` is this machine talking to itself. */
+export function isLoopbackAddress(address) {
+    if (!address)
+        return false;
+    const bare = address.startsWith('::ffff:') ? address.slice('::ffff:'.length) : address;
+    if (bare === '::1')
+        return true;
+    return isIP(bare) === 4 && bare.startsWith('127.');
+}
+/**
+ * Which tenant a request is for. The loopback prefix wins, but only from a
+ * loopback peer that no proxy forwarded (no `X-Forwarded-For`); everything
+ * else is decided by the host name (the `X-Forwarded-Host` a trusted proxy
+ * set, else `Host`), lowercase and without its port.
+ */
+export function selectTenant(req) {
+    const forwarded = Array.isArray(req.forwardedFor) ? req.forwardedFor.length > 0 : Boolean(req.forwardedFor);
+    if (isLoopbackAddress(req.peer) && !forwarded && req.url.startsWith(`${LOOPBACK_TENANT_PREFIX}/`)) {
+        const afterPrefix = req.url.slice(LOOPBACK_TENANT_PREFIX.length + 1);
+        const end = afterPrefix.search(/[/?#]/);
+        const slug = end === -1 ? afterPrefix : afterPrefix.slice(0, end);
+        if (TENANT_SLUG_PATTERN.test(slug)) {
+            const rest = end === -1 ? '/' : afterPrefix.slice(end).replace(/^(?=[?#])/, '/');
+            return { kind: 'slug', slug, rest };
+        }
+    }
+    return { kind: 'host', host: normalizeHost(req.hostname || '') };
+}
+const DEFAULT_ACTIVATION_WAIT_MS = 60_000;
+const DEFAULT_IDLE_MINUTES = 30;
+const DEFAULT_SWEEP_INTERVAL_MS = 60_000;
+/** `promise`, or `null` once `ms` have passed. */
+function within(promise, ms) {
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), ms);
+    });
+    return Promise.race([promise, late]).finally(() => clearTimeout(timer));
+}
+/**
+ * One Express app in front of many tenants' apps. It answers process health
+ * itself, resolves each request to a tenant (see {@link selectTenant}),
+ * activates that tenant's graph on first use, hands the request to the
+ * tenant's app, and serves the SPA for whatever the tenant's app leaves
+ * unhandled. Nothing below it knows there are other tenants: each graph was
+ * built by the same composition root a single-tenant deployment uses.
+ */
+export function createTenantHost(opts) {
+    const runtimes = new Map();
+    const activationWaitMs = opts.activationWaitMs ?? DEFAULT_ACTIVATION_WAIT_MS;
+    const idleMs = (opts.idleMinutes ?? DEFAULT_IDLE_MINUTES) * 60_000;
+    const runtimeFor = (descriptor) => {
+        let runtime = runtimes.get(descriptor.slug);
+        if (!runtime) {
+            runtime = new TenantRuntime(descriptor, opts.runtime);
+            runtimes.set(descriptor.slug, runtime);
+        }
+        return runtime;
+    };
+    const app = express();
+    // Forwarded headers are honoured exactly as a single-tenant deployment
+    // honours them, and for the same reason: `req.hostname` is what picks the
+    // tenant, and behind a proxy it lives in `X-Forwarded-Host`.
+    if (opts.process.trustProxy) {
+        const raw = opts.process.trustProxy;
+        app.set('trust proxy', /^\d+$/.test(raw) ? Number(raw) : raw);
+    }
+    // The process's own health, before any tenant is involved: a load balancer
+    // asks with whatever host name it likes, and a process with no active
+    // tenant is still a healthy process.
+    app.get('/api/health', (_req, res) => {
+        res.json({ status: 'ok', sha: GIT_SHA, timestamp: Date.now(), tenants: runtimes.size });
+    });
+    app.use(async (req, res, next) => {
+        const selector = selectTenant({
+            hostname: req.hostname,
+            url: req.url,
+            peer: req.socket.remoteAddress,
+            forwardedFor: req.headers['x-forwarded-for'],
+        });
+        let descriptor;
+        try {
+            descriptor =
+                selector.kind === 'slug'
+                    ? await opts.source.describe(selector.slug)
+                    : await opts.source.resolveByHost(selector.host);
+        }
+        catch (err) {
+            log.error('tenant lookup failed:', { err });
+            res.status(503).set('Retry-After', '5').json({ error: 'Tenant lookup failed' });
+            return;
+        }
+        if (!descriptor) {
+            if (req.path.startsWith('/api/') || req.path.startsWith(LOOPBACK_TENANT_PREFIX)) {
+                res.status(404).json({ error: 'No workspace at this address' });
+            }
+            else {
+                res.status(404).type('text/plain').send('No workspace at this address.');
+            }
+            return;
+        }
+        if (selector.kind === 'slug')
+            req.url = selector.rest;
+        const runtime = runtimeFor(descriptor);
+        // Counted from here, before the graph is even asked for, until the
+        // response closes however it ends — a 503 below included. An open
+        // response is what keeps a tenant from being evicted from under it.
+        // Left exactly once: a client that dropped during the tenant lookup
+        // above has had its `close` already, and that event will not come
+        // again, so the socket is asked directly; a socket destroyed but not
+        // yet closed would otherwise be left twice, once here and once by the
+        // listener, taking another request's count with it.
+        runtime.enter();
+        let left = false;
+        const leave = () => {
+            if (left)
+                return;
+            left = true;
+            runtime.leave();
+        };
+        res.on('close', leave);
+        if (req.socket.destroyed) {
+            leave();
+            return;
+        }
+        let graph;
+        try {
+            graph = await within(runtime.handle(), activationWaitMs);
+        }
+        catch {
+            // Logged by the runtime; the caller learns only that it may try again.
+            res.status(503).set('Retry-After', '5').json({ error: 'This workspace could not be started; try again shortly' });
+            return;
+        }
+        if (!graph) {
+            res.status(503).set('Retry-After', '5').json({ error: 'This workspace is starting; try again shortly' });
+            return;
+        }
+        graph.app(req, res, next);
+    });
+    // Whatever a tenant's app left unhandled: the SPA, with the same rule a
+    // single-tenant deployment applies to the namespaces that must never
+    // resolve to `index.html` (see `createCoreServer`).
+    if (opts.staticDir) {
+        const frontendDist = opts.staticDir;
+        app.use(express.static(frontendDist));
+        app.get('{*path}', (req, res) => {
+            if (req.path.startsWith('/.well-known/') ||
+                req.path.startsWith('/api/') ||
+                req.path.startsWith('/login/oauth/')) {
+                res.status(404).json({ error: 'Not found' });
+                return;
+            }
+            res.sendFile(path.join(frontendDist, 'index.html'));
+        });
+    }
+    // Idle tenants are stopped on a timer, never on the request that would
+    // have been their last: a graph whose last response closed `idleMs` ago,
+    // with none still open and no queued commit, is not worth its pool and
+    // its lease. `busy()` is what keeps an event stream's tenant alive.
+    const sweep = async () => {
+        for (const runtime of runtimes.values()) {
+            if (runtime.state !== 'active' || runtime.idleFor() < idleMs)
+                continue;
+            if (await runtime.busy())
+                continue;
+            await runtime.evict().catch((err) => log.warn(`evicting tenant "${runtime.slug}" failed:`, { err }));
+        }
+    };
+    const sweeper = idleMs > 0
+        ? setInterval(() => void sweep(), Math.min(opts.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS, idleMs))
+        : null;
+    sweeper?.unref();
+    const evictAll = async () => {
+        await Promise.all([...runtimes.values()].map((runtime) => runtime.evict().catch(() => undefined)));
+    };
+    return {
+        app,
+        runtimes: () => runtimes,
+        evictAll,
+        async stop() {
+            if (sweeper)
+                clearInterval(sweeper);
+            await evictAll();
+        },
+    };
+}
+//# sourceMappingURL=tenant-host.js.map

package/dist/tenancy/tenant-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-host.js","sourceRoot":"","sources":["../../src/tenancy/tenant-host.ts"],"names":[],"mappings":"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"}

package/dist/tenancy/tenant-runtime.d.ts

@@ -0,0 +1,91 @@
+import type { Express } from 'express';
+import { type CoreServices } from '../core/create-core-services.js';
+import type { TenantDescriptor } from './tenant-source.contract.js';
+/** A tenant's running graph: its services and the Express app that serves them. */
+export interface TenantGraph {
+    core: CoreServices;
+    app: Express;
+}
+export type TenantState = 'idle' | 'activating' | 'active' | 'evicting';
+/** The lifecycle seams, so a suite can drive a runtime without a database. */
+export interface TenantRuntimeDeps {
+    /** Build and start the graph. Default: `createCoreServices` + `createCoreServer`. */
+    activate?: (descriptor: TenantDescriptor) => Promise<TenantGraph>;
+    /** Stop a graph. Default: `stopCore`. */
+    stop?: (graph: TenantGraph) => Promise<void>;
+    /** Whether the graph has work in flight that an eviction would strand. Default: queued commits. */
+    busy?: (graph: TenantGraph) => Promise<boolean>;
+    now?: () => number;
+    /**
+     * How long a failed activation is remembered before the next request tries
+     * again: `initialMs` after the first failure, doubling per consecutive
+     * failure up to `maxMs`. Defaults: 5 s to 60 s.
+     */
+    retry?: {
+        initialMs?: number;
+        maxMs?: number;
+    };
+}
+/**
+ * One tenant's graph, brought up on first use and stopped when the host
+ * says so: `idle → activating → active → evicting → idle`.
+ *
+ * ACTIVATE ONCE. Requests arriving while the graph is being built all await
+ * the one activation in flight. A failed activation is remembered for a
+ * short, growing window and answered from memory inside it, so a tenant
+ * whose remote is down or whose token is wrong costs one clone attempt per
+ * window rather than one per request; past the window the next request
+ * tries again, since the remote may be back or the token fixed. An eviction
+ * that lands mid-activation waits for the activation and then stops what it
+ * produced, so a graph is never left running behind an evicted runtime.
+ *
+ * IN USE MEANS A RESPONSE IS OPEN. The host tells the runtime when it hands
+ * a request over and when that response closes, so idleness counts from the
+ * last response that ENDED, and a tenant with any response still open — an
+ * event stream a browser holds, a clone in flight — is busy and never
+ * evicted from under it.
+ */
+export declare class TenantRuntime {
+    readonly descriptor: TenantDescriptor;
+    private graph;
+    private activation;
+    private eviction;
+    private failure;
+    private openResponses;
+    private lastUsedAt;
+    private readonly activate;
+    private readonly stopGraph;
+    private readonly isBusy;
+    private readonly now;
+    private readonly retryInitialMs;
+    private readonly retryMaxMs;
+    constructor(descriptor: TenantDescriptor, deps?: TenantRuntimeDeps);
+    /** A request was handed to this tenant; paired with {@link leave} when its response closes. */
+    enter(): void;
+    /** A response to this tenant closed, however it ended. */
+    leave(): void;
+    /** Responses handed over and not yet closed. */
+    get open(): number;
+    get slug(): string;
+    get state(): TenantState;
+    /** Milliseconds since a request last touched this tenant. */
+    idleFor(): number;
+    /**
+     * The graph, built if it is not running. Every caller of a concurrent
+     * first burst gets the same promise; a caller that arrives during an
+     * eviction waits for it, then starts the graph afresh.
+     */
+    handle(): Promise<TenantGraph>;
+    /**
+     * Whether an eviction would strand something: a response still open, or
+     * work the graph reports (queued commits). False when nothing runs.
+     */
+    busy(): Promise<boolean>;
+    /**
+     * Stop the graph, if one runs or is being built. Idempotent: a second call
+     * joins the eviction under way. Afterwards the runtime is idle and the
+     * next {@link handle} builds a fresh graph.
+     */
+    evict(): Promise<void>;
+}
+//# sourceMappingURL=tenant-runtime.d.ts.map

package/dist/tenancy/tenant-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-runtime.d.ts","sourceRoot":"","sources":["../../src/tenancy/tenant-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAIxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAIpE,mFAAmF;AACnF,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,YAAY,CAAC;IACnB,GAAG,EAAE,OAAO,CAAC;CACd;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAExE,8EAA8E;AAC9E,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,gBAAgB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;IAClE,yCAAyC;IACzC,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7C,mGAAmG;IACnG,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AA4BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,aAAa;IAetB,QAAQ,CAAC,UAAU,EAAE,gBAAgB;IAdvC,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,UAAU,CAAqC;IACvD,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,OAAO,CAAqE;IACpF,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyD;IAClF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAwC;IAClE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2C;IAClE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAGzB,UAAU,EAAE,gBAAgB,EACrC,IAAI,GAAE,iBAAsB;IAW9B,+FAA+F;IAC/F,KAAK,IAAI,IAAI;IAKb,0DAA0D;IAC1D,KAAK,IAAI,IAAI;IAKb,gDAAgD;IAChD,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,KAAK,IAAI,WAAW,CAKvB;IAED,6DAA6D;IAC7D,OAAO,IAAI,MAAM;IAIjB;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC;IAwBpC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAK9B;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAyBvB"}

package/dist/tenancy/tenant-runtime.js

@@ -0,0 +1,174 @@
+import { createCoreServices } from '../core/create-core-services.js';
+import { createCoreServer } from '../core/create-core-server.js';
+import { stopCore } from '../core/lifecycle.js';
+import { logger } from '../shared/logging.js';
+const log = logger('tenancy');
+const DEFAULT_RETRY_INITIAL_MS = 5_000;
+const DEFAULT_RETRY_MAX_MS = 60_000;
+/**
+ * How a tenant's graph is built with the composition root as a distribution
+ * calls it, plus the one thing a host must say: no mirroring onto the shared
+ * package's process-wide bindings, since this process has several graphs and
+ * no single value to put there.
+ */
+async function activateWithCore(descriptor) {
+    const core = await createCoreServices(descriptor.config, { ...descriptor.ports, mirrorSharedBindings: false });
+    try {
+        // No static dir: the host serves the SPA once, for every tenant.
+        const app = await createCoreServer(core, descriptor.extensions ?? {}, {});
+        return { core, app };
+    }
+    catch (err) {
+        // A graph whose boot failed still holds a pool and a lease.
+        await stopCore(core).catch(() => undefined);
+        throw err;
+    }
+}
+async function queuedCommits(graph) {
+    return (await graph.core.pendingCommitsService.oldestQueuedAt()) !== null;
+}
+/**
+ * One tenant's graph, brought up on first use and stopped when the host
+ * says so: `idle → activating → active → evicting → idle`.
+ *
+ * ACTIVATE ONCE. Requests arriving while the graph is being built all await
+ * the one activation in flight. A failed activation is remembered for a
+ * short, growing window and answered from memory inside it, so a tenant
+ * whose remote is down or whose token is wrong costs one clone attempt per
+ * window rather than one per request; past the window the next request
+ * tries again, since the remote may be back or the token fixed. An eviction
+ * that lands mid-activation waits for the activation and then stops what it
+ * produced, so a graph is never left running behind an evicted runtime.
+ *
+ * IN USE MEANS A RESPONSE IS OPEN. The host tells the runtime when it hands
+ * a request over and when that response closes, so idleness counts from the
+ * last response that ENDED, and a tenant with any response still open — an
+ * event stream a browser holds, a clone in flight — is busy and never
+ * evicted from under it.
+ */
+export class TenantRuntime {
+    descriptor;
+    graph = null;
+    activation = null;
+    eviction = null;
+    failure = null;
+    openResponses = 0;
+    lastUsedAt;
+    activate;
+    stopGraph;
+    isBusy;
+    now;
+    retryInitialMs;
+    retryMaxMs;
+    constructor(descriptor, deps = {}) {
+        this.descriptor = descriptor;
+        this.activate = deps.activate ?? activateWithCore;
+        this.stopGraph = deps.stop ?? ((graph) => stopCore(graph.core));
+        this.isBusy = deps.busy ?? queuedCommits;
+        this.now = deps.now ?? Date.now;
+        this.retryInitialMs = deps.retry?.initialMs ?? DEFAULT_RETRY_INITIAL_MS;
+        this.retryMaxMs = deps.retry?.maxMs ?? DEFAULT_RETRY_MAX_MS;
+        this.lastUsedAt = this.now();
+    }
+    /** A request was handed to this tenant; paired with {@link leave} when its response closes. */
+    enter() {
+        this.openResponses += 1;
+        this.lastUsedAt = this.now();
+    }
+    /** A response to this tenant closed, however it ended. */
+    leave() {
+        if (this.openResponses > 0)
+            this.openResponses -= 1;
+        this.lastUsedAt = this.now();
+    }
+    /** Responses handed over and not yet closed. */
+    get open() {
+        return this.openResponses;
+    }
+    get slug() {
+        return this.descriptor.slug;
+    }
+    get state() {
+        if (this.eviction)
+            return 'evicting';
+        if (this.graph)
+            return 'active';
+        if (this.activation)
+            return 'activating';
+        return 'idle';
+    }
+    /** Milliseconds since a request last touched this tenant. */
+    idleFor() {
+        return this.now() - this.lastUsedAt;
+    }
+    /**
+     * The graph, built if it is not running. Every caller of a concurrent
+     * first burst gets the same promise; a caller that arrives during an
+     * eviction waits for it, then starts the graph afresh.
+     */
+    async handle() {
+        this.lastUsedAt = this.now();
+        if (this.eviction)
+            await this.eviction;
+        if (this.graph)
+            return this.graph;
+        if (this.failure && this.now() < this.failure.until)
+            throw this.failure.error;
+        this.activation ??= this.activate(this.descriptor).then((graph) => {
+            this.graph = graph;
+            this.activation = null;
+            this.failure = null;
+            log.info(`tenant "${this.slug}" activated`);
+            return graph;
+        }, (err) => {
+            this.activation = null;
+            const backoffMs = Math.min(this.failure ? this.failure.backoffMs * 2 : this.retryInitialMs, this.retryMaxMs);
+            this.failure = { error: err, until: this.now() + backoffMs, backoffMs };
+            log.error(`tenant "${this.slug}" failed to activate; not asked again for ${backoffMs}ms:`, { err });
+            throw err;
+        });
+        return this.activation;
+    }
+    /**
+     * Whether an eviction would strand something: a response still open, or
+     * work the graph reports (queued commits). False when nothing runs.
+     */
+    async busy() {
+        if (this.openResponses > 0)
+            return true;
+        return this.graph ? this.isBusy(this.graph) : false;
+    }
+    /**
+     * Stop the graph, if one runs or is being built. Idempotent: a second call
+     * joins the eviction under way. Afterwards the runtime is idle and the
+     * next {@link handle} builds a fresh graph.
+     */
+    evict() {
+        if (this.eviction)
+            return this.eviction;
+        const eviction = (async () => {
+            if (this.activation) {
+                // Whatever the build produces is stopped; a build that fails has
+                // stopped its own graph already.
+                await this.activation.catch(() => undefined);
+            }
+            const graph = this.graph;
+            this.graph = null;
+            if (graph) {
+                await this.stopGraph(graph);
+                log.info(`tenant "${this.slug}" evicted`);
+            }
+        })();
+        // Assigned, then cleared by identity: an eviction with nothing to stop
+        // settles before this line runs, and a `finally` inside it would have
+        // cleared a field that was not yet set — leaving the settled promise
+        // in place as an eviction forever under way.
+        this.eviction = eviction;
+        void eviction.finally(() => {
+            if (this.eviction === eviction)
+                this.eviction = null;
+        });
+        return eviction;
+    }
+}
+//# sourceMappingURL=tenant-runtime.js.map

package/dist/tenancy/tenant-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-runtime.js","sourceRoot":"","sources":["../../src/tenancy/tenant-runtime.ts"],"names":[],"mappings":"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"}

package/dist/tenancy/tenant-secrets.d.ts

@@ -0,0 +1,24 @@
+/** The three secrets every graph needs, derived rather than stored. */
+export interface TenantSecrets {
+    /** Signs the tenant's login sessions and OAuth state. */
+    jwtSecret: string;
+    /** 32 bytes, base64: encrypts the tenant's vault values, MCP OAuth tokens and stored git credential. */
+    secretsEncKey: string;
+    /** HMAC key for the tenant's internal (loopback) tool tokens. */
+    internalTokenSecret: string;
+}
+/**
+ * A tenant's secrets from ONE master key and its slug, with HKDF-SHA256:
+ * the slug is the salt and each secret's name the info, so the three are
+ * independent of each other and of every other tenant's.
+ *
+ * Derived, not generated and stored, for the hand-over: a tenant that leaves
+ * for a dedicated deployment takes a `pg_dump` whose vault rows and stored
+ * git token are encrypted under its `secretsEncKey`. With derivation the key
+ * is reproducible from the master key and the slug on the day of the
+ * export, and nothing per tenant has to be kept safe in the meantime. The
+ * cloud app's registry calls this with the same inputs and gets the same
+ * answer.
+ */
+export declare function deriveTenantSecrets(masterKey: string, slug: string): TenantSecrets;
+//# sourceMappingURL=tenant-secrets.d.ts.map

package/dist/tenancy/tenant-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-secrets.d.ts","sourceRoot":"","sources":["../../src/tenancy/tenant-secrets.ts"],"names":[],"mappings":"AAEA,uEAAuE;AACvE,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,wGAAwG;IACxG,aAAa,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAYlF"}

package/dist/tenancy/tenant-secrets.js

@@ -0,0 +1,30 @@
+import { hkdfSync } from 'node:crypto';
+/** The least a master key may hold: 32 characters is 256 bits of a random string. */
+const MIN_MASTER_KEY_LENGTH = 32;
+/**
+ * A tenant's secrets from ONE master key and its slug, with HKDF-SHA256:
+ * the slug is the salt and each secret's name the info, so the three are
+ * independent of each other and of every other tenant's.
+ *
+ * Derived, not generated and stored, for the hand-over: a tenant that leaves
+ * for a dedicated deployment takes a `pg_dump` whose vault rows and stored
+ * git token are encrypted under its `secretsEncKey`. With derivation the key
+ * is reproducible from the master key and the slug on the day of the
+ * export, and nothing per tenant has to be kept safe in the meantime. The
+ * cloud app's registry calls this with the same inputs and gets the same
+ * answer.
+ */
+export function deriveTenantSecrets(masterKey, slug) {
+    if (masterKey.length < MIN_MASTER_KEY_LENGTH) {
+        throw new Error(`TENANT_MASTER_KEY must be at least ${MIN_MASTER_KEY_LENGTH} characters of random text`);
+    }
+    if (!slug)
+        throw new Error('A tenant slug is required to derive its secrets');
+    const derive = (info) => Buffer.from(hkdfSync('sha256', masterKey, `hexis-tenant:${slug}`, info, 32)).toString('base64');
+    return {
+        jwtSecret: derive('jwt-secret'),
+        secretsEncKey: derive('secrets-enc-key'),
+        internalTokenSecret: derive('internal-token-secret'),
+    };
+}
+//# sourceMappingURL=tenant-secrets.js.map

package/dist/tenancy/tenant-secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-secrets.js","sourceRoot":"","sources":["../../src/tenancy/tenant-secrets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAYvC,qFAAqF;AACrF,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,IAAY;IACjE,IAAI,SAAS,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,sCAAsC,qBAAqB,4BAA4B,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC9E,MAAM,MAAM,GAAG,CAAC,IAAY,EAAU,EAAE,CACtC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,gBAAgB,IAAI,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClG,OAAO;QACL,SAAS,EAAE,MAAM,CAAC,YAAY,CAAC;QAC/B,aAAa,EAAE,MAAM,CAAC,iBAAiB,CAAC;QACxC,mBAAmB,EAAE,MAAM,CAAC,uBAAuB,CAAC;KACrD,CAAC;AACJ,CAAC"}

package/dist/tenancy/tenant-source.contract.d.ts

@@ -0,0 +1,45 @@
+import type { TenantConfig } from '../core-config.js';
+import type { CorePorts } from '../core/core-ports.js';
+import type { ServerExtensions } from '../core/create-core-server.js';
+/**
+ * A tenant, as the host needs to know it: which host names reach it, what
+ * its service graph is built from, and what a distribution adds to that
+ * graph. One of these is one `createCoreServices` + `createCoreServer`, run
+ * on demand and stopped again when idle — see `tenant-runtime.ts`.
+ *
+ * `ports` and `extensions` are per tenant on purpose: everything the
+ * enterprise overlay does per deployment (its SSO plugin, session sink,
+ * erasure participants, extra startup steps) it does per tenant here, through
+ * the same two seams, with nothing below the front door knowing the
+ * difference.
+ */
+export interface TenantDescriptor {
+    /** The tenant's stable name: lowercase, `[a-z][a-z0-9-]*`, at most 40 characters. */
+    readonly slug: string;
+    /** Host names (no port) whose requests belong to this tenant, lowercase. */
+    readonly hosts: readonly string[];
+    readonly config: TenantConfig;
+    readonly ports?: CorePorts;
+    readonly extensions?: ServerExtensions;
+}
+/**
+ * Where tenants come from. Core ships {@link StaticTenantSource}, which
+ * reads a file, for development and tests; the cloud app implements this
+ * over its own registry, where subdomains are provisioned and plans live.
+ * A source answers `null` for a host or slug it does not know, and the host
+ * turns that into a 404 without building anything.
+ */
+export interface TenantSource {
+    resolveByHost(host: string): Promise<TenantDescriptor | null>;
+    describe(slug: string): Promise<TenantDescriptor | null>;
+}
+/** What a slug may look like: it names a schema, a folder and a loopback path. */
+export declare const TENANT_SLUG_PATTERN: RegExp;
+export declare function assertTenantSlug(slug: string): string;
+/**
+ * A host name the way the host compares it: lowercase, without a port or a
+ * trailing dot. `Host` headers and `X-Forwarded-Host` values arrive in every
+ * spelling a client or proxy chooses.
+ */
+export declare function normalizeHost(host: string): string;
+//# sourceMappingURL=tenant-source.contract.d.ts.map

package/dist/tenancy/tenant-source.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-source.contract.d.ts","sourceRoot":"","sources":["../../src/tenancy/tenant-source.contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;CACxC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,kFAAkF;AAClF,eAAO,MAAM,mBAAmB,QAA2B,CAAC;AAE5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD"}

package/dist/tenancy/tenant-source.contract.js

@@ -0,0 +1,21 @@
+/** What a slug may look like: it names a schema, a folder and a loopback path. */
+export const TENANT_SLUG_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+export function assertTenantSlug(slug) {
+    if (!TENANT_SLUG_PATTERN.test(slug)) {
+        throw new Error(`Tenant slug must match ${TENANT_SLUG_PATTERN} (lowercase, digits, hyphens); got "${slug}"`);
+    }
+    return slug;
+}
+/**
+ * A host name the way the host compares it: lowercase, without a port or a
+ * trailing dot. `Host` headers and `X-Forwarded-Host` values arrive in every
+ * spelling a client or proxy chooses.
+ */
+export function normalizeHost(host) {
+    const trimmed = host.trim().toLowerCase().replace(/\.$/, '');
+    // `[::1]:3001` keeps its brackets; `example.test:3001` loses its port.
+    if (trimmed.startsWith('['))
+        return trimmed.replace(/\]:\d+$/, ']');
+    return trimmed.replace(/:\d+$/, '');
+}
+//# sourceMappingURL=tenant-source.contract.js.map

package/dist/tenancy/tenant-source.contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-source.contract.js","sourceRoot":"","sources":["../../src/tenancy/tenant-source.contract.ts"],"names":[],"mappings":"AAsCA,kFAAkF;AAClF,MAAM,CAAC,MAAM,mBAAmB,GAAG,wBAAwB,CAAC;AAE5D,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,0BAA0B,mBAAmB,uCAAuC,IAAI,GAAG,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7D,uEAAuE;IACvE,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;IACpE,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AACtC,CAAC"}