@wtfalch/foundry 0.2.0 → 0.3.0

package/dist/calls-sfu-deploy-support.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure decision logic for `scripts/calls-sfu-deploy.mjs`'s SSH/SFTP adapter,
+ * split out so it is unit-tested by vitest against `src/**` -- before
+ * `pnpm build` produces `dist` -- the same way `calls-sfu.ts` is, rather
+ * than only by hand against a real VM. The adapter itself (`ssh2`'s
+ * `Client`/`sftp`/`exec` wiring) stays untested, same as
+ * `foundry-db-provision.mjs`/`foundry-db-migrate.mjs`: real I/O, no branch
+ * logic worth a fake session over.
+ *
+ * Each export here answers one finding from PR #125's review (#122):
+ * 1. No host-key check -- {@link hostKeyFingerprint} / {@link verifyHostKey}.
+ * 2. `livekit.yaml` landing world-readable -- {@link fileWriteMode}.
+ * 3. No preflight for `docker`/`ufw` -- {@link PREFLIGHT_COMMAND} / {@link preflightFailureMessage}.
+ * 4. Incomplete secret redaction -- {@link redactSecrets}.
+ */
+/**
+ * The `ssh-keygen -lf`-style fingerprint of a host key: `SHA256:` plus the
+ * unpadded base64 SHA-256 digest of the key's raw bytes. Matches what an
+ * operator reads from `ssh-keyscan -t ed25519 <host> | ssh-keygen -lf -`, so
+ * `CALLS_SFU_SSH_HOST_FINGERPRINT` can be pasted from that command's output
+ * verbatim.
+ */
+export declare function hostKeyFingerprint(rawKey: Buffer): string;
+/**
+ * `ssh2`'s `hostVerifier(key, verify)` contract: `true` accepts the session,
+ * `false` refuses it. VM 105's SSH port is open to the internet, so with no
+ * expected fingerprint configured the session is refused rather than
+ * silently trusting whatever key is presented -- PR #125's review, finding 1.
+ */
+export declare function verifyHostKey(rawKey: Buffer, expectedFingerprint: string | undefined): boolean;
+/**
+ * `livekit.yaml` holds the LiveKit API key and secret in plain text
+ * (`calls-sfu.ts`'s `livekitConfigYaml`), and `cloudflared.env` holds the
+ * tunnel token the same way (`cloudflaredEnvFile`, #127) -- every other file
+ * this script writes holds no secret. Returns the SFTP file mode to write
+ * with, or `undefined` for anything else (the SFTP server's own default).
+ * PR #125's review, finding 2; extended for #127's second secret file.
+ */
+export declare function fileWriteMode(path: string): number | undefined;
+/**
+ * Checked before either file is written -- a Debian cloud image ships
+ * neither `docker` nor `ufw`, and bringing LiveKit up with
+ * `network_mode: host` before `ufw` exists would leave every port open with
+ * no firewall left to narrow it. PR #125's review, finding 3.
+ */
+export declare const PREFLIGHT_COMMAND = "command -v docker && command -v ufw";
+export declare function preflightFailureMessage(result: {
+    stdout: string;
+    stderr: string;
+}): string;
+/**
+ * Scrubs every secret this script ever handles out of a string -- an error
+ * message or stack trace, most often. PR #125's review, finding 4: the
+ * original left `livekitApiKey` out of this list, so a thrown error could
+ * still print it.
+ */
+export declare function redactSecrets(text: string, secrets: Array<string | undefined>): string;

package/dist/calls-sfu-deploy-support.js

@@ -0,0 +1,82 @@
+/**
+ * Pure decision logic for `scripts/calls-sfu-deploy.mjs`'s SSH/SFTP adapter,
+ * split out so it is unit-tested by vitest against `src/**` -- before
+ * `pnpm build` produces `dist` -- the same way `calls-sfu.ts` is, rather
+ * than only by hand against a real VM. The adapter itself (`ssh2`'s
+ * `Client`/`sftp`/`exec` wiring) stays untested, same as
+ * `foundry-db-provision.mjs`/`foundry-db-migrate.mjs`: real I/O, no branch
+ * logic worth a fake session over.
+ *
+ * Each export here answers one finding from PR #125's review (#122):
+ * 1. No host-key check -- {@link hostKeyFingerprint} / {@link verifyHostKey}.
+ * 2. `livekit.yaml` landing world-readable -- {@link fileWriteMode}.
+ * 3. No preflight for `docker`/`ufw` -- {@link PREFLIGHT_COMMAND} / {@link preflightFailureMessage}.
+ * 4. Incomplete secret redaction -- {@link redactSecrets}.
+ */
+import { createHash } from 'node:crypto';
+import { CLOUDFLARED_ENV_PATH, LIVEKIT_CONFIG_PATH } from './calls-sfu.js';
+// ---------------------------------------------------------------------------
+// 1. Host-key verification
+// ---------------------------------------------------------------------------
+/**
+ * The `ssh-keygen -lf`-style fingerprint of a host key: `SHA256:` plus the
+ * unpadded base64 SHA-256 digest of the key's raw bytes. Matches what an
+ * operator reads from `ssh-keyscan -t ed25519 <host> | ssh-keygen -lf -`, so
+ * `CALLS_SFU_SSH_HOST_FINGERPRINT` can be pasted from that command's output
+ * verbatim.
+ */
+export function hostKeyFingerprint(rawKey) {
+    const digest = createHash('sha256').update(rawKey).digest('base64').replace(/=+$/, '');
+    return `SHA256:${digest}`;
+}
+/**
+ * `ssh2`'s `hostVerifier(key, verify)` contract: `true` accepts the session,
+ * `false` refuses it. VM 105's SSH port is open to the internet, so with no
+ * expected fingerprint configured the session is refused rather than
+ * silently trusting whatever key is presented -- PR #125's review, finding 1.
+ */
+export function verifyHostKey(rawKey, expectedFingerprint) {
+    if (!expectedFingerprint)
+        return false;
+    return hostKeyFingerprint(rawKey) === expectedFingerprint;
+}
+// ---------------------------------------------------------------------------
+// 2. File permissions
+// ---------------------------------------------------------------------------
+/**
+ * `livekit.yaml` holds the LiveKit API key and secret in plain text
+ * (`calls-sfu.ts`'s `livekitConfigYaml`), and `cloudflared.env` holds the
+ * tunnel token the same way (`cloudflaredEnvFile`, #127) -- every other file
+ * this script writes holds no secret. Returns the SFTP file mode to write
+ * with, or `undefined` for anything else (the SFTP server's own default).
+ * PR #125's review, finding 2; extended for #127's second secret file.
+ */
+export function fileWriteMode(path) {
+    return path === LIVEKIT_CONFIG_PATH || path === CLOUDFLARED_ENV_PATH ? 0o600 : undefined;
+}
+// ---------------------------------------------------------------------------
+// 3. Preflight
+// ---------------------------------------------------------------------------
+/**
+ * Checked before either file is written -- a Debian cloud image ships
+ * neither `docker` nor `ufw`, and bringing LiveKit up with
+ * `network_mode: host` before `ufw` exists would leave every port open with
+ * no firewall left to narrow it. PR #125's review, finding 3.
+ */
+export const PREFLIGHT_COMMAND = 'command -v docker && command -v ufw';
+export function preflightFailureMessage(result) {
+    const detail = (result.stderr || result.stdout || '').trim();
+    return `install docker and ufw first (\`${PREFLIGHT_COMMAND}\` failed${detail ? `: ${detail}` : ''})`;
+}
+// ---------------------------------------------------------------------------
+// 4. Redaction
+// ---------------------------------------------------------------------------
+/**
+ * Scrubs every secret this script ever handles out of a string -- an error
+ * message or stack trace, most often. PR #125's review, finding 4: the
+ * original left `livekitApiKey` out of this list, so a thrown error could
+ * still print it.
+ */
+export function redactSecrets(text, secrets) {
+    return secrets.reduce((acc, secret) => (secret ? acc.split(secret).join('<redacted>') : acc), text);
+}

package/dist/calls-sfu.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Deploys LiveKit onto the estate's one calls SFU VM (VM 105, `82.39.206.243`
+ * as of 2026-09-27, calls#15). One instance for every org: calls are
+ * end-to-end encrypted, so LiveKit only ever forwards ciphertext and orgs are
+ * kept apart by room names and signed tokens, not by a VM or a port range
+ * each -- #122's "Decided" section, 2026-09-27. That is also why this is its
+ * own module rather than a case in `plan/executor.ts`'s per-`DeclaredOrg`
+ * dispatch, or an addition to `provision.ts` (foundry's *other* estate-wide
+ * singleton, its own Postgres): #122 asked for this to stay small, one
+ * module and one test file, rather than repeat app-template's
+ * `calls-instance` step, which grew to 1147 untested lines before anyone
+ * noticed (app-template#338, foundry#42).
+ *
+ * How: plain Docker Compose on the VM, applied over SSH -- not a Coolify
+ * server. LiveKit needs host networking and a wide UDP port range; Coolify
+ * would add a second host to manage for no gain, and the SFU got its own VM
+ * specifically to keep Coolify's own firewall script (`ADR 0011`) untouched
+ * (calls#15). {@link CallsSfuHostPort} is deliberately narrow -- write a
+ * file, run a command -- so a real implementation is a thin SSH/SFTP client
+ * (`packages/foundry/scripts/calls-sfu-deploy.mjs`), never imported here,
+ * and every test in `calls-sfu.test.ts` runs against a fake.
+ *
+ * The address, the LiveKit API key and its secret are never hardcoded here
+ * ({@link CallsSfuConfig}): PR 344's review on app-template's
+ * `calls-instance` step found its first cut created three Coolify apps
+ * before it ever checked the address was known.
+ * {@link requireCallsSfuAddress} is that check, run first, before either
+ * file is written.
+ *
+ * #127 adds a second compose service, `cloudflared`, so the SFU has a public
+ * `wss://` address through its own named tunnel -- browsers on an https page
+ * cannot open a plain `ws://` connection, and 7880 was open to the whole
+ * internet with nothing in front of it. `cloudflared` only ever dials out
+ * (`scripts/calls-sfu-ingress.mjs`, beside `scripts/shared-ingress.mjs`, owns
+ * the tunnel/DNS side of this -- the estate's Cloudflare resources, not
+ * anything on the VM), so 7880 no longer needs to be reachable from the
+ * internet at all: {@link applyCallsSfu} narrows it to the host's own private
+ * network on `vmbr1` ({@link CALLS_SFU_PRIVATE_CIDR}), where the calls
+ * service reaches LiveKit's API directly (#127's "Decided" section). 7881
+ * and the UDP media range stay open to everyone -- media isn't part of this.
+ * The tunnel token reaches the VM the same way the LiveKit secret does: a
+ * file written at 0600 ({@link requireCloudflaredTunnelToken}, mirrored in
+ * `calls-sfu-deploy-support.ts`'s `fileWriteMode`), never logged, scrubbed
+ * from any error `calls-sfu-deploy.mjs` prints.
+ */
+export declare class MissingCallsSfuAddressError extends Error {
+    constructor();
+}
+/**
+ * Refuses on a missing or blank address; returns the trimmed address
+ * otherwise. Called first in {@link applyCallsSfu}, ahead of either file
+ * write, so a re-run with no address configured touches nothing.
+ */
+export declare function requireCallsSfuAddress(address: string | undefined | null): string;
+export declare class MissingCloudflaredTunnelTokenError extends Error {
+    constructor();
+}
+/**
+ * Refuses on a missing or blank token; returns the trimmed token otherwise.
+ * Called first in {@link applyCallsSfu}, alongside
+ * {@link requireCallsSfuAddress}, ahead of any file write.
+ */
+export declare function requireCloudflaredTunnelToken(token: string | undefined | null): string;
+/**
+ * Everything {@link applyCallsSfu} needs and this package never invents on
+ * its own: the SFU's own address (calls#15), the LiveKit API key/secret pair
+ * every client and the service sign tokens with, and the token for the
+ * named tunnel `scripts/calls-sfu-ingress.mjs` creates. All four come from
+ * the secrets store, at the caller's own script -- #122's and #127's "Human
+ * steps".
+ */
+export interface CallsSfuConfig {
+    address: string;
+    livekitApiKey: string;
+    livekitApiSecret: string;
+    cloudflaredTunnelToken: string;
+}
+/**
+ * The one thing a real deploy needs beyond {@link CallsSfuConfig}: a way to
+ * put a file on the VM and run a command on it. Shaped to fit an SSH/SFTP
+ * session directly (`writeFile` -> SFTP, `exec` -> a single SSH channel), so
+ * `calls-sfu-deploy.mjs`'s real implementation is a thin adapter, not a
+ * reimplementation.
+ */
+export interface CallsSfuHostPort {
+    /** Writes a file's full contents at an absolute path, overwriting whatever was there. */
+    writeFile(path: string, contents: string): Promise<void>;
+    /** Runs one command; never throws on a non-zero exit -- {@link applyCallsSfu} checks it. */
+    exec(command: string): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+}
+export declare const LIVEKIT_COMPOSE_PATH = "/opt/livekit/docker-compose.yml";
+export declare const LIVEKIT_CONFIG_PATH = "/opt/livekit/livekit.yaml";
+/** Holds `TUNNEL_TOKEN=...` -- the one secret the `cloudflared` compose service reads (`env_file:`, below). */
+export declare const CLOUDFLARED_ENV_PATH = "/opt/livekit/cloudflared.env";
+/**
+ * `:latest`, matching this codebase's one other pinned-by-tag-only image
+ * (`scripts/shared-ingress.mjs`'s `CLOUDFLARED_IMAGE_REF`) -- neither runs
+ * anywhere a supply-chain review has asked for a digest pin yet.
+ */
+export declare const LIVEKIT_IMAGE_REF = "livekit/livekit-server:latest";
+/** Same tag policy as {@link LIVEKIT_IMAGE_REF}; matches `scripts/shared-ingress.mjs`'s own `CLOUDFLARED_IMAGE_REF` constant (duplicated, not imported -- this package and that top-level script sit in separate places in the tree). */
+export declare const CLOUDFLARED_IMAGE_REF = "cloudflare/cloudflared:latest";
+/** LiveKit signalling -- reachable only through the tunnel as of #127 (see {@link CALLS_SFU_PRIVATE_CIDR}). */
+export declare const LIVEKIT_SIGNALLING_PORT = 7880;
+/** Media fallback for networks that block UDP -- reaches the SFU's own address directly. */
+export declare const LIVEKIT_MEDIA_TCP_PORT = 7881;
+/** RTP media. Matches #122's "Decided" section exactly; not the wider range `docs/research/2026-09-19-meetings-research.md` lists for embedded TURN, which #122 does not turn on. */
+export declare const LIVEKIT_MEDIA_UDP_RANGE = "50000:60000";
+/**
+ * The host's private network on `vmbr1`, where the calls service reaches
+ * LiveKit's API directly (#127's "Human steps": VM 105 gets a second NIC on
+ * this network). `cloudflared` only ever dials out to Cloudflare, so once it
+ * carries signalling, {@link LIVEKIT_SIGNALLING_PORT} no longer needs to be
+ * reachable from the public internet at all -- #127's "Decided" section.
+ */
+export declare const CALLS_SFU_PRIVATE_CIDR = "10.10.10.0/24";
+/**
+ * Exported for the test file. Reads `ufw status`'s own report rather than
+ * assuming the exit code of a blind `ufw delete allow 7880/tcp` -- real
+ * ufw's behaviour when the rule is already gone differs by version, and a
+ * status check works the same on every one of them.
+ */
+export declare function hasUnscopedSignallingRule(status: string): boolean;
+/**
+ * `network_mode: host`: LiveKit's own self-hosting guide recommends this
+ * over mapping ten thousand individual UDP ports, and the SFU VM has no
+ * other service to collide with (calls#15 -- it exists so this workload gets
+ * a host to itself). `cloudflared` shares the same host network so it can
+ * reach LiveKit at `localhost:7880` -- #127's "How": its one ingress rule
+ * sends the SFU hostname there.
+ */
+export declare function dockerComposeYaml(): string;
+/**
+ * The `cloudflared` service's own secret file ({@link CLOUDFLARED_ENV_PATH}),
+ * mirroring {@link livekitConfigYaml}: refuses before writing anything when
+ * the token is missing, same guard as the address.
+ */
+export declare function cloudflaredEnvFile(token: string): string;
+/**
+ * `use_external_ip: false` with an explicit `node_ip`, not `true`: the VM
+ * has one public address of its own, bridged directly rather than sitting
+ * behind NAT (calls#15's decision comment), so there is a known-good answer
+ * and no reason to make LiveKit discover it via STUN.
+ */
+export declare function livekitConfigYaml(config: CallsSfuConfig): string;
+/**
+ * Writes all three files, brings LiveKit and `cloudflared` up, then narrows
+ * the VM firewall to exactly what #122's and #127's "Decided" sections name
+ * -- in that order, and with every `allow` rule added before `default deny
+ * incoming` takes effect, so a run never has a window where the SSH session
+ * it is running over would be refused. Every step is idempotent (`docker
+ * compose up -d`, `ufw allow` and `ufw --force enable` all no-op safely on a
+ * repeat), so a retry after a partial failure is always safe -- #122's own
+ * "safe to re-run".
+ *
+ * {@link LIVEKIT_SIGNALLING_PORT} is narrowed to
+ * {@link CALLS_SFU_PRIVATE_CIDR} rather than opened to everyone, as of #127:
+ * `cloudflared` only ever dials out, so signalling reaches the SFU over the
+ * tunnel, and the one thing left that still needs 7880 directly is the calls
+ * service, from the host's own private network. `ufw` only ever adds rules,
+ * so a VM already carrying PR 125's wide-open `ufw allow 7880/tcp` keeps it
+ * reachable from the whole internet beside the new scoped one unless
+ * something removes it first -- {@link hasUnscopedSignallingRule} reads `ufw
+ * status` and this function deletes that rule before adding the scoped
+ * replacement, and leaves a VM that never had it untouched.
+ *
+ * Stops at the first failing step: a `docker compose up -d` that fails
+ * leaves the firewall untouched rather than locking a broken deploy behind
+ * a narrowed one.
+ */
+export declare function applyCallsSfu(host: CallsSfuHostPort, config: CallsSfuConfig): Promise<void>;

package/dist/calls-sfu.js

@@ -0,0 +1,239 @@
+/**
+ * Deploys LiveKit onto the estate's one calls SFU VM (VM 105, `82.39.206.243`
+ * as of 2026-09-27, calls#15). One instance for every org: calls are
+ * end-to-end encrypted, so LiveKit only ever forwards ciphertext and orgs are
+ * kept apart by room names and signed tokens, not by a VM or a port range
+ * each -- #122's "Decided" section, 2026-09-27. That is also why this is its
+ * own module rather than a case in `plan/executor.ts`'s per-`DeclaredOrg`
+ * dispatch, or an addition to `provision.ts` (foundry's *other* estate-wide
+ * singleton, its own Postgres): #122 asked for this to stay small, one
+ * module and one test file, rather than repeat app-template's
+ * `calls-instance` step, which grew to 1147 untested lines before anyone
+ * noticed (app-template#338, foundry#42).
+ *
+ * How: plain Docker Compose on the VM, applied over SSH -- not a Coolify
+ * server. LiveKit needs host networking and a wide UDP port range; Coolify
+ * would add a second host to manage for no gain, and the SFU got its own VM
+ * specifically to keep Coolify's own firewall script (`ADR 0011`) untouched
+ * (calls#15). {@link CallsSfuHostPort} is deliberately narrow -- write a
+ * file, run a command -- so a real implementation is a thin SSH/SFTP client
+ * (`packages/foundry/scripts/calls-sfu-deploy.mjs`), never imported here,
+ * and every test in `calls-sfu.test.ts` runs against a fake.
+ *
+ * The address, the LiveKit API key and its secret are never hardcoded here
+ * ({@link CallsSfuConfig}): PR 344's review on app-template's
+ * `calls-instance` step found its first cut created three Coolify apps
+ * before it ever checked the address was known.
+ * {@link requireCallsSfuAddress} is that check, run first, before either
+ * file is written.
+ *
+ * #127 adds a second compose service, `cloudflared`, so the SFU has a public
+ * `wss://` address through its own named tunnel -- browsers on an https page
+ * cannot open a plain `ws://` connection, and 7880 was open to the whole
+ * internet with nothing in front of it. `cloudflared` only ever dials out
+ * (`scripts/calls-sfu-ingress.mjs`, beside `scripts/shared-ingress.mjs`, owns
+ * the tunnel/DNS side of this -- the estate's Cloudflare resources, not
+ * anything on the VM), so 7880 no longer needs to be reachable from the
+ * internet at all: {@link applyCallsSfu} narrows it to the host's own private
+ * network on `vmbr1` ({@link CALLS_SFU_PRIVATE_CIDR}), where the calls
+ * service reaches LiveKit's API directly (#127's "Decided" section). 7881
+ * and the UDP media range stay open to everyone -- media isn't part of this.
+ * The tunnel token reaches the VM the same way the LiveKit secret does: a
+ * file written at 0600 ({@link requireCloudflaredTunnelToken}, mirrored in
+ * `calls-sfu-deploy-support.ts`'s `fileWriteMode`), never logged, scrubbed
+ * from any error `calls-sfu-deploy.mjs` prints.
+ */
+// ---------------------------------------------------------------------------
+// The guard
+// ---------------------------------------------------------------------------
+export class MissingCallsSfuAddressError extends Error {
+    constructor() {
+        super('The calls SFU address is required and was not supplied. See ' +
+            'https://github.com/wtfalch/calls/issues/15 for where it comes from, ' +
+            'and https://github.com/wtfalch/foundry/issues/122 for why nothing ' +
+            'here may create anything before it is known.');
+        this.name = 'MissingCallsSfuAddressError';
+    }
+}
+/**
+ * Refuses on a missing or blank address; returns the trimmed address
+ * otherwise. Called first in {@link applyCallsSfu}, ahead of either file
+ * write, so a re-run with no address configured touches nothing.
+ */
+export function requireCallsSfuAddress(address) {
+    const trimmed = address?.trim();
+    if (!trimmed)
+        throw new MissingCallsSfuAddressError();
+    return trimmed;
+}
+export class MissingCloudflaredTunnelTokenError extends Error {
+    constructor() {
+        super('The cloudflared tunnel token is required and was not supplied. Run ' +
+            'scripts/calls-sfu-ingress.mjs --apply to create the named tunnel ' +
+            '`calls-sfu`, then put its token in the secrets store -- see ' +
+            'https://github.com/wtfalch/foundry/issues/127.');
+        this.name = 'MissingCloudflaredTunnelTokenError';
+    }
+}
+/**
+ * Refuses on a missing or blank token; returns the trimmed token otherwise.
+ * Called first in {@link applyCallsSfu}, alongside
+ * {@link requireCallsSfuAddress}, ahead of any file write.
+ */
+export function requireCloudflaredTunnelToken(token) {
+    const trimmed = token?.trim();
+    if (!trimmed)
+        throw new MissingCloudflaredTunnelTokenError();
+    return trimmed;
+}
+// ---------------------------------------------------------------------------
+// What gets written and run
+// ---------------------------------------------------------------------------
+export const LIVEKIT_COMPOSE_PATH = '/opt/livekit/docker-compose.yml';
+export const LIVEKIT_CONFIG_PATH = '/opt/livekit/livekit.yaml';
+/** Holds `TUNNEL_TOKEN=...` -- the one secret the `cloudflared` compose service reads (`env_file:`, below). */
+export const CLOUDFLARED_ENV_PATH = '/opt/livekit/cloudflared.env';
+/**
+ * `:latest`, matching this codebase's one other pinned-by-tag-only image
+ * (`scripts/shared-ingress.mjs`'s `CLOUDFLARED_IMAGE_REF`) -- neither runs
+ * anywhere a supply-chain review has asked for a digest pin yet.
+ */
+export const LIVEKIT_IMAGE_REF = 'livekit/livekit-server:latest';
+/** Same tag policy as {@link LIVEKIT_IMAGE_REF}; matches `scripts/shared-ingress.mjs`'s own `CLOUDFLARED_IMAGE_REF` constant (duplicated, not imported -- this package and that top-level script sit in separate places in the tree). */
+export const CLOUDFLARED_IMAGE_REF = 'cloudflare/cloudflared:latest';
+/** LiveKit signalling -- reachable only through the tunnel as of #127 (see {@link CALLS_SFU_PRIVATE_CIDR}). */
+export const LIVEKIT_SIGNALLING_PORT = 7880;
+/** Media fallback for networks that block UDP -- reaches the SFU's own address directly. */
+export const LIVEKIT_MEDIA_TCP_PORT = 7881;
+/** RTP media. Matches #122's "Decided" section exactly; not the wider range `docs/research/2026-09-19-meetings-research.md` lists for embedded TURN, which #122 does not turn on. */
+export const LIVEKIT_MEDIA_UDP_RANGE = '50000:60000';
+/**
+ * The host's private network on `vmbr1`, where the calls service reaches
+ * LiveKit's API directly (#127's "Human steps": VM 105 gets a second NIC on
+ * this network). `cloudflared` only ever dials out to Cloudflare, so once it
+ * carries signalling, {@link LIVEKIT_SIGNALLING_PORT} no longer needs to be
+ * reachable from the public internet at all -- #127's "Decided" section.
+ */
+export const CALLS_SFU_PRIVATE_CIDR = '10.10.10.0/24';
+/**
+ * Matches `ufw status`'s report of the exact wide-open rule PR 125 added
+ * (`ufw allow 7880/tcp`) -- "Anywhere" in the From column -- and not the
+ * scoped one #127 replaces it with, whose From column names
+ * {@link CALLS_SFU_PRIVATE_CIDR} instead. Multiline so it matches the plain,
+ * non-`(v6)` row regardless of what comes before or after it in `ufw
+ * status`'s table.
+ */
+const UNSCOPED_SIGNALLING_RULE_PATTERN = new RegExp(`^${LIVEKIT_SIGNALLING_PORT}/tcp\\s+ALLOW\\s+Anywhere\\b`, 'm');
+/**
+ * Exported for the test file. Reads `ufw status`'s own report rather than
+ * assuming the exit code of a blind `ufw delete allow 7880/tcp` -- real
+ * ufw's behaviour when the rule is already gone differs by version, and a
+ * status check works the same on every one of them.
+ */
+export function hasUnscopedSignallingRule(status) {
+    return UNSCOPED_SIGNALLING_RULE_PATTERN.test(status);
+}
+/**
+ * `network_mode: host`: LiveKit's own self-hosting guide recommends this
+ * over mapping ten thousand individual UDP ports, and the SFU VM has no
+ * other service to collide with (calls#15 -- it exists so this workload gets
+ * a host to itself). `cloudflared` shares the same host network so it can
+ * reach LiveKit at `localhost:7880` -- #127's "How": its one ingress rule
+ * sends the SFU hostname there.
+ */
+export function dockerComposeYaml() {
+    return `services:
+  livekit:
+    image: ${LIVEKIT_IMAGE_REF}
+    restart: unless-stopped
+    network_mode: host
+    volumes:
+      - ${LIVEKIT_CONFIG_PATH}:/etc/livekit.yaml:ro
+    command: --config /etc/livekit.yaml
+  cloudflared:
+    image: ${CLOUDFLARED_IMAGE_REF}
+    restart: unless-stopped
+    network_mode: host
+    env_file:
+      - ${CLOUDFLARED_ENV_PATH}
+    command: tunnel --no-autoupdate run
+`;
+}
+/**
+ * The `cloudflared` service's own secret file ({@link CLOUDFLARED_ENV_PATH}),
+ * mirroring {@link livekitConfigYaml}: refuses before writing anything when
+ * the token is missing, same guard as the address.
+ */
+export function cloudflaredEnvFile(token) {
+    const trimmed = requireCloudflaredTunnelToken(token);
+    return `TUNNEL_TOKEN=${trimmed}\n`;
+}
+/**
+ * `use_external_ip: false` with an explicit `node_ip`, not `true`: the VM
+ * has one public address of its own, bridged directly rather than sitting
+ * behind NAT (calls#15's decision comment), so there is a known-good answer
+ * and no reason to make LiveKit discover it via STUN.
+ */
+export function livekitConfigYaml(config) {
+    const address = requireCallsSfuAddress(config.address);
+    return `port: ${LIVEKIT_SIGNALLING_PORT}
+rtc:
+  tcp_port: ${LIVEKIT_MEDIA_TCP_PORT}
+  port_range_start: 50000
+  port_range_end: 60000
+  use_external_ip: false
+  node_ip: ${address}
+keys:
+  ${config.livekitApiKey}: ${config.livekitApiSecret}
+`;
+}
+async function run(host, command) {
+    const result = await host.exec(command);
+    if (result.exitCode !== 0) {
+        throw new Error(`"${command}" exited ${result.exitCode}: ${result.stderr || result.stdout}`);
+    }
+}
+/**
+ * Writes all three files, brings LiveKit and `cloudflared` up, then narrows
+ * the VM firewall to exactly what #122's and #127's "Decided" sections name
+ * -- in that order, and with every `allow` rule added before `default deny
+ * incoming` takes effect, so a run never has a window where the SSH session
+ * it is running over would be refused. Every step is idempotent (`docker
+ * compose up -d`, `ufw allow` and `ufw --force enable` all no-op safely on a
+ * repeat), so a retry after a partial failure is always safe -- #122's own
+ * "safe to re-run".
+ *
+ * {@link LIVEKIT_SIGNALLING_PORT} is narrowed to
+ * {@link CALLS_SFU_PRIVATE_CIDR} rather than opened to everyone, as of #127:
+ * `cloudflared` only ever dials out, so signalling reaches the SFU over the
+ * tunnel, and the one thing left that still needs 7880 directly is the calls
+ * service, from the host's own private network. `ufw` only ever adds rules,
+ * so a VM already carrying PR 125's wide-open `ufw allow 7880/tcp` keeps it
+ * reachable from the whole internet beside the new scoped one unless
+ * something removes it first -- {@link hasUnscopedSignallingRule} reads `ufw
+ * status` and this function deletes that rule before adding the scoped
+ * replacement, and leaves a VM that never had it untouched.
+ *
+ * Stops at the first failing step: a `docker compose up -d` that fails
+ * leaves the firewall untouched rather than locking a broken deploy behind
+ * a narrowed one.
+ */
+export async function applyCallsSfu(host, config) {
+    requireCallsSfuAddress(config.address);
+    requireCloudflaredTunnelToken(config.cloudflaredTunnelToken);
+    await host.writeFile(LIVEKIT_COMPOSE_PATH, dockerComposeYaml());
+    await host.writeFile(LIVEKIT_CONFIG_PATH, livekitConfigYaml(config));
+    await host.writeFile(CLOUDFLARED_ENV_PATH, cloudflaredEnvFile(config.cloudflaredTunnelToken));
+    await run(host, `docker compose -f ${LIVEKIT_COMPOSE_PATH} up -d`);
+    await run(host, 'ufw allow 22/tcp');
+    const status = await host.exec('ufw status');
+    if (status.exitCode === 0 && hasUnscopedSignallingRule(status.stdout)) {
+        await run(host, `ufw delete allow ${LIVEKIT_SIGNALLING_PORT}/tcp`);
+    }
+    await run(host, `ufw allow from ${CALLS_SFU_PRIVATE_CIDR} to any port ${LIVEKIT_SIGNALLING_PORT} proto tcp`);
+    await run(host, `ufw allow ${LIVEKIT_MEDIA_TCP_PORT}/tcp`);
+    await run(host, `ufw allow ${LIVEKIT_MEDIA_UDP_RANGE}/udp`);
+    await run(host, 'ufw default deny incoming');
+    await run(host, 'ufw default allow outgoing');
+    await run(host, 'ufw --force enable');
+}

package/dist/index.d.ts

@@ -1,18 +1,21 @@
 export type { OrgId, MailMode, MailConfig, ChatConfig, CallsConfig, IssuerConfig, SiteConfig, IssuerAppKind, IssuerApp, HostingConfig, SsoConfig, GuestsConfig, SoloConfig, StorageConfig, AiConfig, BuyerAddress, BuyerIdentity, AdoptedAppForm, AdoptedApp, OwnerIdentity, DeclaredOrg, } from './org.js';
-export { validateBuyerIdentity, validateHosting, validateOwner } from './org.js';
+export { validateBuyerIdentity, validateHosting, validateOwner, validateSite } from './org.js';
 export type { SlugRejectionReason, SlugRejection } from './slug.js';
-export { validateSlug, RESERVED_SLUGS } from './slug.js';
+export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export type { Checkpoint, LastApplied, AppliedState } from './state.js';
 export type { PlanStep, UnmanagedItem, Plan } from './plan.js';
 export type { DeclaredOrgStore } from './store.js';
 export type { PlanApply } from './apply.js';
 export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
+export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.js';
-export { declaredOrgs, foundryAppliedState, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, } from './store/schema.js';
+export { declaredOrgs, foundryAppliedState, foundryAuditEvents, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, } from './store/schema.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, StepAction, PlannedStep, PlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
 export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan/index.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } from './plan/index.js';
-export { FoundryStepExecutor, NotBuiltError, MissingBespokeAppRepoError } from './plan/index.js';
+export { FoundryStepExecutor, NotBuiltError, healthUrls } from './plan/index.js';
+export type { MigrateSql, MigrationResult } from './migrate.js';
+export { MIGRATIONS_DIR, migrate } from './migrate.js';
 export type { RunnerDb } from './runner/db.js';
 export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';
 export { createJobRunner } from './runner/runner.js';

package/dist/index.js

@@ -1,8 +1,10 @@
-export { validateBuyerIdentity, validateHosting, validateOwner } from './org.js';
-export { validateSlug, RESERVED_SLUGS } from './slug.js';
+export { validateBuyerIdentity, validateHosting, validateOwner, validateSite } from './org.js';
+export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
 export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
-export { declaredOrgs, foundryAppliedState, } from './store/schema.js';
+export { createPostgresAuditLog } from './store/audit.js';
+export { declaredOrgs, foundryAppliedState, foundryAuditEvents, } from './store/schema.js';
 export { readLiveResources, computePlanDetail, toPlan, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, } from './plan/index.js';
-export { FoundryStepExecutor, NotBuiltError, MissingBespokeAppRepoError } from './plan/index.js';
+export { FoundryStepExecutor, NotBuiltError, healthUrls } from './plan/index.js';
+export { MIGRATIONS_DIR, migrate } from './migrate.js';
 export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';
 export { createJobRunner } from './runner/runner.js';

package/dist/migrate.d.ts

@@ -0,0 +1,38 @@
+/** This package's own migrations -- `../migrations` from `src/`, `./migrations` once built to `dist/` (`package.json`'s `build` script copies the `.sql` files there alongside `migrate.js`). */
+export declare const MIGRATIONS_DIR: string;
+/**
+ * The one capability `migrate` needs from a driver: run SQL text (one
+ * statement or several) and run a callback inside a transaction. Deliberately
+ * not a drizzle `PgDatabase` or a concrete driver type -- drizzle's own
+ * `.execute()` routes a multi-statement string through a single prepared
+ * query on PGlite, which rejects it, so a migration file's raw text has to
+ * reach the driver's own multi-statement path (`postgres`'s `.unsafe()`,
+ * PGlite's `.exec()`) instead. Same "narrow port, no concrete client type"
+ * shape `plan/executor.ts`'s `CoolifyPort` uses, for the same reason: a real
+ * driver satisfies this structurally, with a few lines of adapter at the
+ * call site (see `scripts/foundry-db-migrate.mjs` and `migrate.test.ts`).
+ */
+export interface MigrateSql {
+    /** Run SQL text and discard any result -- the tracking table's own DDL, and each migration file's contents. */
+    exec(text: string): Promise<void>;
+    /**
+     * Run one literal SELECT and return its rows. Only ever called here with
+     * fixed text this module builds itself (the tracking table's name, and a
+     * migration filename already checked against `/^\d{4}_.+\.sql$/`), so
+     * there is no external input to inject.
+     */
+    query<T = Record<string, unknown>>(text: string): Promise<T[]>;
+    /** Run `fn` inside one transaction, handing it a `MigrateSql` scoped to it; rolled back if `fn` throws. */
+    transaction<T>(fn: (tx: MigrateSql) => Promise<T>): Promise<T>;
+}
+export interface MigrationResult {
+    /** Names of the migration files applied this run, in filename order -- empty when the database was already current. */
+    applied: string[];
+}
+/**
+ * Applies every migration file in `dir` (default: this package's own
+ * `../migrations`) not yet recorded in `foundry_schema_migrations`, in
+ * filename order, one transaction per file. Safe to call repeatedly: a file
+ * already recorded is never re-read, let alone re-run.
+ */
+export declare function migrate(sql: MigrateSql, dir?: string): Promise<MigrationResult>;