@wtfalch/foundry 0.4.0 → 0.5.0

package/dist/calls-sfu-keys.js

@@ -0,0 +1,27 @@
+/**
+ * Mints the LiveKit API key/secret pair the shared calls SFU signs tokens
+ * with (#170). Before this, `scripts/calls-sfu-deploy.mjs` read
+ * `LIVEKIT_API_KEY`/`LIVEKIT_API_SECRET` from the environment -- a human
+ * minted the pair by hand and put it in the secrets store. The platform
+ * `sfu` step (`plan/platform-sfu.ts`) mints it instead, once, and delivers it
+ * to held keys through `CallsSfuKeysPort.deliverLivekitKeys`; every apply
+ * after that reads the same pair back through `resolveLivekitKeys` rather
+ * than minting a second one.
+ *
+ * The shape matches LiveKit's own self-hosting docs: an `API`-prefixed key
+ * id and a long random secret, both plain alphanumeric so they drop straight
+ * into `livekit.yaml`'s `keys:` map (`calls-sfu.ts`'s `livekitConfigYaml`)
+ * with no escaping to worry about.
+ */
+import { randomBytes } from 'node:crypto';
+const ALPHANUMERIC = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+function randomAlphanumeric(length) {
+    return Array.from(randomBytes(length), (byte) => ALPHANUMERIC[byte % ALPHANUMERIC.length]).join('');
+}
+/** A fresh LiveKit API key/secret pair, minted with `node:crypto`'s CSPRNG. */
+export function mintLivekitCredentials() {
+    return {
+        apiKey: `API${randomAlphanumeric(12)}`,
+        apiSecret: randomAlphanumeric(40),
+    };
+}

package/dist/calls-sfu-ssh-adapter.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Turns one open SSH session into the `CallsSfuHostPort` {@link applyCallsSfu}
+ * needs, applying `calls-sfu-deploy-support.ts`'s decision logic
+ * (`verifyHostKey`, `fileWriteMode`, the preflight check) exactly once so
+ * `scripts/calls-sfu-deploy.mjs` and the platform `sfu` step
+ * (`plan/platform-sfu.ts`, #170) share it rather than each re-deriving it.
+ *
+ * {@link CallsSfuSshSession} is deliberately narrow -- the host key an
+ * already-open session presented, a way to run a command, a way to write a
+ * file at a chosen mode -- so a test hands in a fake session and proves the
+ * host-key refusal and the 0600 file mode without ever opening a socket.
+ * `calls-sfu-ssh-client.ts`'s `connectCallsSfuSsh` is the one real
+ * implementation, over `ssh2`, and stays untested for the same reason
+ * `foundry-db-provision.mjs`/`foundry-db-migrate.mjs` do: real I/O, no
+ * branch logic worth a fake session over.
+ */
+import { type CallsSfuConfig, type CallsSfuHostPort } from './calls-sfu.js';
+export declare class UnknownCallsSfuHostKeyError extends Error {
+    constructor();
+}
+/**
+ * One already-open SSH session, narrow enough to fake in a test: the raw
+ * host key it presented during the handshake, a way to run one command, and
+ * a way to write a file at a chosen mode (`undefined` for the SFTP server's
+ * own default, same as {@link CallsSfuHostPort.writeFile} today).
+ */
+export interface CallsSfuSshSession {
+    hostKey: Buffer;
+    exec(command: string): Promise<{
+        exitCode: number;
+        stdout: string;
+        stderr: string;
+    }>;
+    writeFile(path: string, contents: string, mode: number | undefined): Promise<void>;
+}
+/**
+ * Refuses with {@link UnknownCallsSfuHostKeyError} before adapting anything
+ * when `session.hostKey` does not match `expectedFingerprint` -- checked
+ * here, in code a fake session exercises directly, rather than only inside
+ * `ssh2`'s own `hostVerifier` (PR #125's review, finding 1). Otherwise
+ * returns a {@link CallsSfuHostPort} that writes each file at
+ * {@link fileWriteMode}'s mode (finding 2) and runs commands as-is.
+ */
+export declare function toCallsSfuHostPort(session: CallsSfuSshSession, expectedFingerprint: string | undefined): CallsSfuHostPort;
+/**
+ * The whole deploy, over one already-open session: refuse an unknown host
+ * key first (before any command runs), check `docker`/`ufw` are installed
+ * (PR #125's review, finding 3), make sure `/opt/livekit` exists, then hand
+ * off to {@link applyCallsSfu} -- the same order
+ * `scripts/calls-sfu-deploy.mjs` ran by hand, now shared with the platform
+ * `sfu` step. Every step here is safe to re-run, the same "safe to re-run"
+ * {@link applyCallsSfu} itself promises, so calling this twice with the same
+ * `session`/`config` changes nothing on the second call.
+ */
+export declare function applyCallsSfuOverSession(session: CallsSfuSshSession, config: CallsSfuConfig, expectedFingerprint: string | undefined): Promise<void>;

package/dist/calls-sfu-ssh-adapter.js

@@ -0,0 +1,78 @@
+/**
+ * Turns one open SSH session into the `CallsSfuHostPort` {@link applyCallsSfu}
+ * needs, applying `calls-sfu-deploy-support.ts`'s decision logic
+ * (`verifyHostKey`, `fileWriteMode`, the preflight check) exactly once so
+ * `scripts/calls-sfu-deploy.mjs` and the platform `sfu` step
+ * (`plan/platform-sfu.ts`, #170) share it rather than each re-deriving it.
+ *
+ * {@link CallsSfuSshSession} is deliberately narrow -- the host key an
+ * already-open session presented, a way to run a command, a way to write a
+ * file at a chosen mode -- so a test hands in a fake session and proves the
+ * host-key refusal and the 0600 file mode without ever opening a socket.
+ * `calls-sfu-ssh-client.ts`'s `connectCallsSfuSsh` is the one real
+ * implementation, over `ssh2`, and stays untested for the same reason
+ * `foundry-db-provision.mjs`/`foundry-db-migrate.mjs` do: real I/O, no
+ * branch logic worth a fake session over.
+ */
+import { dirname } from 'node:path';
+import { PREFLIGHT_COMMAND, fileWriteMode, preflightFailureMessage, verifyHostKey, } from './calls-sfu-deploy-support.js';
+import { LIVEKIT_COMPOSE_PATH, LIVEKIT_CONFIG_PATH, applyCallsSfu, livekitConfigYaml, } from './calls-sfu.js';
+export class UnknownCallsSfuHostKeyError extends Error {
+    constructor() {
+        super('The calls SFU host key did not match the fingerprint held for it; refusing to ' +
+            'deploy. See calls-sfu-deploy-support.ts’s verifyHostKey (PR #125) -- the ' +
+            'expected fingerprint comes from held keys (#170’s "Human steps").');
+        this.name = 'UnknownCallsSfuHostKeyError';
+    }
+}
+/**
+ * Refuses with {@link UnknownCallsSfuHostKeyError} before adapting anything
+ * when `session.hostKey` does not match `expectedFingerprint` -- checked
+ * here, in code a fake session exercises directly, rather than only inside
+ * `ssh2`'s own `hostVerifier` (PR #125's review, finding 1). Otherwise
+ * returns a {@link CallsSfuHostPort} that writes each file at
+ * {@link fileWriteMode}'s mode (finding 2) and runs commands as-is.
+ */
+export function toCallsSfuHostPort(session, expectedFingerprint) {
+    if (!verifyHostKey(session.hostKey, expectedFingerprint)) {
+        throw new UnknownCallsSfuHostKeyError();
+    }
+    return {
+        writeFile: (path, contents) => session.writeFile(path, contents, fileWriteMode(path)),
+        exec: (command) => session.exec(command),
+    };
+}
+/**
+ * The whole deploy, over one already-open session: refuse an unknown host
+ * key first (before any command runs), check `docker`/`ufw` are installed
+ * (PR #125's review, finding 3), make sure `/opt/livekit` exists, then hand
+ * off to {@link applyCallsSfu} -- the same order
+ * `scripts/calls-sfu-deploy.mjs` ran by hand, now shared with the platform
+ * `sfu` step. Every step here is safe to re-run, the same "safe to re-run"
+ * {@link applyCallsSfu} itself promises, so calling this twice with the same
+ * `session`/`config` changes nothing on the second call.
+ */
+export async function applyCallsSfuOverSession(session, config, expectedFingerprint) {
+    const host = toCallsSfuHostPort(session, expectedFingerprint);
+    const preflight = await host.exec(PREFLIGHT_COMMAND);
+    if (preflight.exitCode !== 0) {
+        throw new Error(preflightFailureMessage(preflight));
+    }
+    const mkdir = await host.exec(`mkdir -p ${dirname(LIVEKIT_COMPOSE_PATH)}`);
+    if (mkdir.exitCode !== 0) {
+        throw new Error(`mkdir -p failed: ${mkdir.stderr || mkdir.stdout}`);
+    }
+    // `docker compose up -d` leaves a running container alone when the compose
+    // file is unchanged, so LiveKit would keep the old keys in memory after a
+    // new `livekit.yaml` lands. Read the config before it is overwritten and
+    // restart LiveKit afterwards if the keys (or anything else in it) changed.
+    const previous = await host.exec(`cat ${LIVEKIT_CONFIG_PATH}`);
+    const configChanged = previous.exitCode === 0 && previous.stdout !== livekitConfigYaml(config);
+    await applyCallsSfu(host, config);
+    if (configChanged) {
+        const restart = await host.exec(`docker compose -f ${LIVEKIT_COMPOSE_PATH} restart livekit`);
+        if (restart.exitCode !== 0) {
+            throw new Error(`restarting livekit failed: ${restart.stderr || restart.stdout}`);
+        }
+    }
+}

package/dist/calls-sfu-ssh-client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The real {@link CallsSfuSshConnector} (`plan/platform-sfu.ts`), over `ssh2`:
+ * the same `connect()`/`exec`/SFTP wiring `scripts/calls-sfu-deploy.mjs` uses
+ * by hand. A host (archon) passes {@link connectCallsSfuSsh} as the `ssh` dep
+ * of `CallsSfuPlatformDeps`.
+ *
+ * The host key is verified inside `ssh2`'s own `hostVerifier`, which returns
+ * `false` on a mismatch or a missing fingerprint so the handshake is refused
+ * before any authentication happens and the private key is never offered to
+ * an unknown host. `applyCallsSfuOverSession` checks the captured key again.
+ *
+ * `ssh2` is loaded lazily and the `Client` class can be injected, so a test
+ * hands in a fake and never opens a socket.
+ */
+import type { CallsSfuSshSession } from './calls-sfu-ssh-adapter.js';
+interface SshStream {
+    on(event: string, listener: (...args: never[]) => void): SshStream;
+    stderr: {
+        on(event: string, listener: (...args: never[]) => void): unknown;
+    };
+}
+interface SshSftp {
+    writeFile(path: string, contents: string, options: {
+        mode: number;
+    } | undefined, cb: (err?: Error | null) => void): void;
+    chmod(path: string, mode: number, cb: (err?: Error | null) => void): void;
+}
+interface SshClient {
+    on(event: string, listener: (...args: never[]) => void): SshClient;
+    connect(options: Record<string, unknown>): void;
+    exec(command: string, cb: (err: Error | undefined, stream: SshStream) => void): void;
+    sftp(cb: (err: Error | undefined, sftp: SshSftp) => void): void;
+    end(): void;
+}
+export type SshClientConstructor = new () => SshClient;
+export interface CallsSfuSshConnectOptions {
+    address: string;
+    sshUser: string;
+    sshPort: number;
+    sshPrivateKey: string;
+    /** `SHA256:...`. Without it every host key is refused. */
+    sshHostFingerprint: string | undefined;
+}
+export declare function connectCallsSfuSsh(options: CallsSfuSshConnectOptions, deps?: {
+    Client?: SshClientConstructor;
+}): Promise<CallsSfuSshSession & {
+    close(): void;
+}>;
+export {};

package/dist/calls-sfu-ssh-client.js

@@ -0,0 +1,82 @@
+/**
+ * The real {@link CallsSfuSshConnector} (`plan/platform-sfu.ts`), over `ssh2`:
+ * the same `connect()`/`exec`/SFTP wiring `scripts/calls-sfu-deploy.mjs` uses
+ * by hand. A host (archon) passes {@link connectCallsSfuSsh} as the `ssh` dep
+ * of `CallsSfuPlatformDeps`.
+ *
+ * The host key is verified inside `ssh2`'s own `hostVerifier`, which returns
+ * `false` on a mismatch or a missing fingerprint so the handshake is refused
+ * before any authentication happens and the private key is never offered to
+ * an unknown host. `applyCallsSfuOverSession` checks the captured key again.
+ *
+ * `ssh2` is loaded lazily and the `Client` class can be injected, so a test
+ * hands in a fake and never opens a socket.
+ */
+import { verifyHostKey } from './calls-sfu-deploy-support.js';
+function sshExec(conn, command) {
+    return new Promise((resolve, reject) => {
+        conn.exec(command, (err, stream) => {
+            if (err)
+                return reject(err);
+            let stdout = '';
+            let stderr = '';
+            stream.on('close', (code) => resolve({ exitCode: code ?? 0, stdout, stderr }));
+            stream.on('data', (chunk) => {
+                stdout += chunk;
+            });
+            stream.stderr.on('data', (chunk) => {
+                stderr += chunk;
+            });
+        });
+    });
+}
+function sshWriteFile(conn, path, contents, mode) {
+    return new Promise((resolve, reject) => {
+        conn.sftp((err, sftp) => {
+            if (err)
+                return reject(err);
+            sftp.writeFile(path, contents, mode ? { mode } : undefined, (writeErr) => {
+                if (writeErr)
+                    return reject(writeErr);
+                // `mode` on writeFile only applies when the file is created; chmod
+                // repairs a file that already existed with looser permissions.
+                if (!mode)
+                    return resolve();
+                sftp.chmod(path, mode, (chmodErr) => (chmodErr ? reject(chmodErr) : resolve()));
+            });
+        });
+    });
+}
+export async function connectCallsSfuSsh(options, deps = {}) {
+    const Client = deps.Client ?? (await loadSsh2()).Client;
+    return new Promise((resolve, reject) => {
+        const conn = new Client();
+        let hostKey = Buffer.alloc(0);
+        conn.on('ready', () => resolve({
+            hostKey,
+            exec: (command) => sshExec(conn, command),
+            writeFile: (path, contents, mode) => sshWriteFile(conn, path, contents, mode),
+            close: () => conn.end(),
+        }));
+        conn.on('error', reject);
+        conn.connect({
+            host: options.address,
+            port: options.sshPort,
+            username: options.sshUser,
+            privateKey: options.sshPrivateKey,
+            // One argument: ssh2 treats the return value as the verdict.
+            hostVerifier: (key) => {
+                hostKey = key;
+                return verifyHostKey(key, options.sshHostFingerprint);
+            },
+        });
+    });
+}
+async function loadSsh2() {
+    const specifier = 'ssh2';
+    const mod = (await import(specifier));
+    const Client = mod.Client ?? mod.default?.Client;
+    if (!Client)
+        throw new Error('ssh2 did not export a Client');
+    return { Client };
+}

package/dist/calls-sfu.d.ts

@@ -17,8 +17,9 @@
  * 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.
+ * (`packages/foundry/scripts/calls-sfu-deploy.mjs`, and, as of #170, the
+ * platform's own `sfu:livekit` step, `plan/platform-sfu.ts`), 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
@@ -102,8 +103,8 @@ export declare const CLOUDFLARED_ENV_PATH = "/opt/livekit/cloudflared.env";
  * 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";
+/** Pinned to a release tag; equals `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:2026.9.3";
 /** 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. */

package/dist/calls-sfu.js

@@ -17,8 +17,9 @@
  * 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.
+ * (`packages/foundry/scripts/calls-sfu-deploy.mjs`, and, as of #170, the
+ * platform's own `sfu:livekit` step, `plan/platform-sfu.ts`), 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
@@ -99,8 +100,8 @@ export const CLOUDFLARED_ENV_PATH = '/opt/livekit/cloudflared.env';
  * 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';
+/** Pinned to a release tag; equals `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:2026.9.3';
 /** 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. */

package/dist/index.d.ts

@@ -1,21 +1,46 @@
 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, validateSite } from './org.js';
+export type { DeclaredPlatform, PlatformService, PlatformServiceKey } from './platform.js';
+export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
+export type { RequestableField, CallsChange, StorageLimitChange, AiLimitChange, DomainChange, MailTierChange, RequestedChangeValue, ChangeClassification, RequestedChangeState, RequestedChange, } from './requested-changes.js';
+export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export type { SlugRejectionReason, SlugRejection } 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 { DeclaredOrgStore, PlatformStore, RequestedChangeStore } from './store.js';
 export type { PlanApply } from './apply.js';
-export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
+export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.js';
 export { createPostgresAuditLog } from './store/audit.js';
 export type { FoundryStoreDb } from './store/postgres.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, CallsSfuPort, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } from './plan/index.js';
+export { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, type AuditEventRow, type DeclaredOrgRow, type NewDeclaredOrgRow, type AppliedStateRow, type NewAppliedStateRow, type DeclaredPlatformRow, type NewDeclaredPlatformRow, type RequestedChangeRow, type NewRequestedChangeRow, } from './store/schema.js';
+export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, StepAction, PlannedStep, PlanDetail, PlatformPlanDetail, AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan/index.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export type { HeldKeyResolver, OrgPlatformReadiness } from './plan/index.js';
+export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
+export type { PlatformOrgClientFactories } from './plan/index.js';
+export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
+export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, AgoraHostPort, AgoraHostValues, } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './plan/index.js';
+export { HttpJobsSchedulerClient } from './plan/index.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
+export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './plan/index.js';
+export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './plan/index.js';
+export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './plan/index.js';
+export { PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, PLATFORM_AI_MINTER_MISSING, } from './plan/index.js';
+export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './plan/index.js';
+export type { CallsSfuConnection, CallsSfuConnectionPort, CallsSfuKeysPort, CallsSfuSshConnector, CallsSfuPlatformDeps, } from './plan/index.js';
+export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './plan/index.js';
+export type { CallsSfuSshSession } from './calls-sfu-ssh-adapter.js';
+export { connectCallsSfuSsh } from './calls-sfu-ssh-client.js';
+export type { CallsSfuSshConnectOptions } from './calls-sfu-ssh-client.js';
+export { UnknownCallsSfuHostKeyError, toCallsSfuHostPort, applyCallsSfuOverSession, } from './calls-sfu-ssh-adapter.js';
+export type { LivekitCredentials } from './calls-sfu-keys.js';
+export { mintLivekitCredentials } from './calls-sfu-keys.js';
 export type { MigrateSql, MigrationResult } from './migrate.js';
 export { MIGRATIONS_DIR, migrate } from './migrate.js';
+export type { BootstrapCompany, BootstrapExecutorDeps, BootstrapOwner, BootstrapPlatformDeps, BootstrapPlatformInput, BootstrapProgress, BootstrapResult, RootCredentials, } from './bootstrap/index.js';
+export { bootstrapPlatform } from './bootstrap/index.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,10 +1,23 @@
 export { validateBuyerIdentity, validateHosting, validateOwner, validateSite } from './org.js';
+export { PLATFORM_SERVICE_KEYS, defaultPlatformHostname, validatePlatform, } from './platform.js';
+export { REQUESTABLE_FIELDS, classifyChange, RequestedChangeError } from './requested-changes.js';
 export { validateSlug, slugFromName, RESERVED_SLUGS } from './slug.js';
-export { createPostgresDeclaredOrgStore, DeclaredOrgError } from './store/postgres.js';
+export { createPostgresDeclaredOrgStore, createPostgresPlatformStore, createPostgresRequestedChangeStore, DeclaredOrgError, PlatformError, } from './store/postgres.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 { declaredOrgs, foundryAppliedState, foundryAuditEvents, foundryDeclaredPlatform, foundryRequestedChanges, } from './store/schema.js';
+export { readLiveResources, readLivePlatformResources, computePlanDetail, toPlan, planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan/index.js';
+export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './plan/index.js';
+export { PlatformOrgBlockedError, PlatformOrgPorts } from './plan/index.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './plan/index.js';
+export { HttpJobsSchedulerClient } from './plan/index.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, createZitadelAdminMinter, PLATFORM_AUTH_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './plan/index.js';
+export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './plan/index.js';
+export { PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, PLATFORM_AI_MINTER_MISSING, } from './plan/index.js';
+export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './plan/index.js';
+export { connectCallsSfuSsh } from './calls-sfu-ssh-client.js';
+export { UnknownCallsSfuHostKeyError, toCallsSfuHostPort, applyCallsSfuOverSession, } from './calls-sfu-ssh-adapter.js';
+export { mintLivekitCredentials } from './calls-sfu-keys.js';
 export { MIGRATIONS_DIR, migrate } from './migrate.js';
+export { bootstrapPlatform } from './bootstrap/index.js';
 export { AlreadyRunningError, RunNotFoundError, StepFailedError, StepMismatchError, } from './runner/errors.js';
 export { createJobRunner } from './runner/runner.js';

package/dist/migrations/0016_platform.sql

@@ -0,0 +1,61 @@
+-- @wtfalch/foundry: the declared platform -- the one shared set of services
+-- (auth, mail, sfu, files, ai, jobs, integrations, archon) decided in #165,
+-- owned by Company Included, with its own plan and apply. Mirrors
+-- src/store/schema.ts's `foundryDeclaredPlatform` table.
+--
+-- Singleton by construction: `id` is a boolean that can only ever be `true`
+-- (the check constraint below refuses `false`), and it is the primary key,
+-- so a second row can never exist. This is the same "one declared platform"
+-- decision `foundry_declared_orgs` enforces per-org uniqueness for (#28,
+-- #131), applied here to the whole table instead of a column.
+
+create table if not exists foundry_declared_platform (
+  id                     boolean not null default true,
+
+  -- Company Included's own OrgId (org.ts). Not a level-1 org itself, but
+  -- the platform's resources are billed and owned by one.
+  owner_org_id           text not null,
+
+  -- The shared apex every service's hostname defaults under, e.g.
+  -- companyincluded.com. Validated by src/platform.ts's `validatePlatform`,
+  -- not here, the same two-file split declared_orgs uses (#10).
+  apex                   text not null,
+
+  auth_enabled           boolean not null default false,
+  auth_hostname          text not null,
+  auth_git_ref           text not null default '',
+
+  mail_enabled           boolean not null default false,
+  mail_hostname          text not null,
+  mail_git_ref           text not null default '',
+
+  sfu_enabled            boolean not null default false,
+  sfu_hostname           text not null,
+  sfu_git_ref            text not null default '',
+
+  files_enabled          boolean not null default false,
+  files_hostname         text not null,
+  files_git_ref          text not null default '',
+
+  ai_enabled             boolean not null default false,
+  ai_hostname            text not null,
+  ai_git_ref             text not null default '',
+
+  jobs_enabled           boolean not null default false,
+  jobs_hostname          text not null,
+  jobs_git_ref           text not null default '',
+
+  integrations_enabled   boolean not null default false,
+  integrations_hostname  text not null,
+  integrations_git_ref   text not null default '',
+
+  archon_enabled         boolean not null default false,
+  archon_hostname        text not null,
+  archon_git_ref         text not null default '',
+
+  created_at             timestamptz not null default now(),
+  updated_at             timestamptz not null default now(),
+
+  constraint foundry_declared_platform_pkey primary key (id),
+  constraint foundry_declared_platform_singleton check (id)
+);

package/dist/migrations/0017_requested_changes.sql

@@ -0,0 +1,42 @@
+-- @wtfalch/foundry: a company's own requested setting changes on its
+-- declared org (#178, map #165: "a company's Boule can request setting
+-- changes on its own declared org, and Archon applies them"). Mirrors
+-- src/store/schema.ts's `foundryRequestedChanges` table.
+--
+-- `field` is the whitelist itself, checked here the same way
+-- `foundry_declared_orgs_mail_mode_check` checks `mail_mode`'s closed set --
+-- src/requested-changes.ts's `REQUESTABLE_FIELDS` is the source of truth for
+-- what the list means, this constraint is the database-level copy of it.
+-- `value` carries whatever that field's own shape needs (`enabled` for
+-- calls, `limitBytes`/`limitMicros` for storageLimit, and so on) -- one
+-- jsonb column rather than a column per possible field, since only one
+-- field is ever set per request.
+--
+-- `state` starts at whatever `src/requested-changes.ts`'s `classifyChange`
+-- decided for this request at create time (`auto` or `needs_approval`) --
+-- foundry only stores and classifies (#178 "Why"); archon's own workflow is
+-- what carries a request on to `approved`/`rejected`/`applied`.
+
+create table if not exists foundry_requested_changes (
+  id            bigserial not null,
+  org_id        text not null,
+
+  field         text not null,
+  value         jsonb not null,
+
+  requested_by  text not null,
+  created_at    timestamptz not null default now(),
+
+  state         text not null default 'needs_approval',
+
+  constraint foundry_requested_changes_pkey primary key (id),
+  constraint foundry_requested_changes_org_fkey
+    foreign key (org_id) references foundry_declared_orgs (id),
+  constraint foundry_requested_changes_field_check
+    check (field in ('calls', 'storageLimit', 'aiLimit', 'domain', 'mailTier')),
+  constraint foundry_requested_changes_state_check
+    check (state in ('auto', 'needs_approval', 'approved', 'rejected', 'applied'))
+);
+
+create index if not exists foundry_requested_changes_org_id_idx
+  on foundry_requested_changes (org_id);

package/dist/migrations/0018_platform_apply.sql

@@ -0,0 +1,19 @@
+-- @wtfalch/foundry: what applying the declared platform (#167) needs to
+-- remember, and how its audit rows are told apart from an org's.
+--
+-- `service_ids` is the platform's own applied state: the provider ids its
+-- apply made or adopted, keyed `system:kind:key` like
+-- `foundry_applied_state.service_ids`. Without it a Cloudflare zone created
+-- by one apply is forgotten if the next plan's read lags behind the create.
+-- It lives on the singleton row because there is one platform, and
+-- `put`'s upsert never writes it, so re-declaring the platform keeps it.
+--
+-- `target` marks an audit row as the platform's. It is null for an org row.
+-- A platform plan is stamped with the owner org's id, so `org_id` alone
+-- cannot say which of the two a row is.
+
+alter table foundry_declared_platform
+  add column if not exists service_ids jsonb not null default '{}'::jsonb;
+
+alter table foundry_audit_events
+  add column if not exists target text check (target in ('platform'));

package/dist/org.js

@@ -49,6 +49,14 @@ export function validateHosting(hosting) {
         if (!ISSUER_APP_KINDS.has(app.kind)) {
             return `issuerApps '${app.name}' has an unknown kind '${app.kind}'`;
         }
+        // The fixed 'agora' ZITADEL client (#164, `plan/diff.ts`'s
+        // `planAgoraClient`) already owns the `zitadel:app:agora` key, for
+        // every org -- Agora is always on, unlike the cms client's own 'cms'
+        // reservation (`validateSite` below), which only applies once
+        // `site.enabled` is true.
+        if (app.name === 'agora') {
+            return `issuerApps '${app.name}' is reserved for the always-on Agora client every org gets`;
+        }
     }
     return null;
 }