@wtfalch/foundry 0.3.0 → 0.5.0

package/dist/plan/calls-matrix.js

@@ -0,0 +1,275 @@
+import { generateKeyPairSync, randomBytes } from 'node:crypto';
+/**
+ * The calls Matrix stack (#128, part 1 of 2 -- see that issue's "If this
+ * passes about 800 changed lines, split it" note): pure config generation
+ * for the dedicated Synapse and matrix-authentication-service (MAS)
+ * `executor.ts`'s `coolifyCalls` deploys per org, adapted from
+ * `wtfalch/app-template#344`'s `bootstrap/steps/calls-instance.ts`.
+ *
+ * TWO COOLIFY DATABASES, NOT ONE SHARED POSTGRES
+ * ------------------------------------------------
+ * PR 344 ran one bare `postgres` container and created Synapse's and MAS's
+ * databases on it with hand-rolled SQL over a direct connection -- workable
+ * for a CLI run with network access to the box, but this executor never
+ * connects to a database it creates (`executor.ts`'s `pushDatabaseUrl`/
+ * `ensureCmsRuntimeUrl` only ever read `internal_db_url` back through
+ * Coolify's own API). So this stack instead asks Coolify for two ordinary
+ * managed Postgres databases, `coolifyCalls`'s own `CoolifyPort.
+ * createPostgresDatabase` calls -- the same primitive `coolifyDatabase`/
+ * `ensureCmsDatabase` already use for the org's own app and its cms site.
+ * That also means neither app needs a postgres superuser password minted
+ * here: Coolify mints and owns each database's own credential.
+ *
+ * NOT CHAT'S STACK, BY CONSTRUCTION
+ * ----------------------------------
+ * PR 344's review settled that a call guest must never gain chat membership.
+ * This is not a gate bolted onto shared infrastructure -- there is no shared
+ * infrastructure: this stack is an entirely separate homeserver from
+ * `archon/bootstrap/steps/chat-instance.ts`'s own Synapse+MAS, with its own
+ * databases, its own `server_name` ({@link callsServerName}) and its own MAS
+ * client. A guest account minted here cannot join a chat room because it does
+ * not exist on chat's homeserver at all.
+ *
+ * NO PUBLIC HOSTNAME OF ITS OWN
+ * -------------------------------
+ * `@wtfalch/calls`' own `SYNAPSE_URL`/`MAS_URL` env vars
+ * (`calls/packages/service/src/config.mjs`) are plain internal addresses --
+ * the calls service is the only thing that ever talks to either, over
+ * Coolify's own Docker network, proxying the Matrix client-server API on a
+ * guest's behalf (`calls/packages/service/src/matrix-gateway.mjs`). Neither
+ * app needs a Cloudflare-routed hostname, unlike chat's own Synapse (real
+ * Matrix clients, real federation surface). That is also why this module
+ * mints no tunnel or DNS anything: the only public hostname this stack ever
+ * needs is the calls *service's* own, which foundry#145 (part 2 of #128)
+ * gives it -- `<slug>-calls.oikos.host` on the shared tunnel for a level-1
+ * org, `calls.<domain>` on its own per-org tunnel for an own-domain one
+ * (`executor.ts`'s `callsHostnameFor`).
+ */
+export const SYNAPSE_IMAGE = 'ghcr.io/element-hq/synapse';
+export const SYNAPSE_TAG = 'v1.161.0';
+export const MAS_IMAGE = 'ghcr.io/element-hq/matrix-authentication-service:1.24.0';
+/**
+ * Never resolved by DNS and never federates (`callsSynapseHomeserverYaml`'s
+ * `federation_domain_whitelist: []`) -- purely a logical identifier MAS and
+ * Synapse agree on, and the same value the calls service's own
+ * `MAS_HOMESERVER` (part 2) must carry. `<org.slug>` alone would collide with
+ * a real domain some org might later own; `.internal` never resolves and
+ * matches `@wtfalch/calls`' own bare-homeserver-domain regex
+ * (`^[A-Za-z0-9.:-]+$`).
+ */
+export function callsServerName(orgSlug) {
+    return `calls-${orgSlug}.internal`;
+}
+/**
+ * Coolify's own `internal_db_url` is `postgres://user:password@host[:port]/db`
+ * -- `URL` parses it exactly the way `executor.ts`'s `ensureCmsRuntimeUrl`
+ * already parses the same shape for the cms app's own database. Returns
+ * `null` on a malformed URL rather than throwing, the same defensive stance
+ * `ensureCmsRuntimeUrl` takes: Coolify's own superuser password is not
+ * something this package controls the alphabet of.
+ */
+export function parseCallsDbUrl(internalDbUrl) {
+    try {
+        const url = new URL(internalDbUrl);
+        const database = url.pathname.replace(/^\//, '');
+        if (!url.hostname || !url.username || !database)
+            return null;
+        return {
+            host: url.hostname,
+            port: url.port ? Number(url.port) : 5432,
+            user: decodeURIComponent(url.username),
+            password: decodeURIComponent(url.password),
+            database,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function mintCallsMatrixSecrets() {
+    const rsa = generateKeyPairSync('rsa', {
+        modulusLength: 2048,
+        privateKeyEncoding: { type: 'pkcs1', format: 'pem' },
+        publicKeyEncoding: { type: 'pkcs1', format: 'pem' },
+    });
+    const ec = generateKeyPairSync('ec', {
+        namedCurve: 'P-256',
+        privateKeyEncoding: { type: 'sec1', format: 'pem' },
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+    });
+    return {
+        masSynapseSharedSecret: randomBytes(32).toString('hex'),
+        masClientId: generateUlid(),
+        masClientSecret: randomBytes(24).toString('base64url'),
+        masEncryptionKey: randomBytes(32).toString('hex'),
+        masRsaKeyPem: rsa.privateKey,
+        masEcKeyPem: ec.privateKey,
+    };
+}
+/**
+ * A ULID-shaped (26-char Crockford base32) id -- MAS's `clients[].client_id`
+ * must be one (`docs/reference/configuration.md`). Not time-sortable (a
+ * static config value, not an event id), just shape-valid: 16 random bytes,
+ * Crockford-encoded. Identical to `chat-instance.ts`'s own helper of the same
+ * name -- restated, not imported, since neither `plan/` nor `archon`'s
+ * bootstrap tree exposes the other as a dependency.
+ */
+export function generateUlid(bytes = randomBytes(16)) {
+    const alphabet = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+    let bits = 0n;
+    for (const b of bytes)
+        bits = (bits << 8n) | BigInt(b);
+    let out = '';
+    for (let i = 0; i < 26; i++) {
+        const shift = BigInt(130 - (i + 1) * 5);
+        const idx = shift >= 0n ? Number((bits >> shift) & 0x1fn) : Number((bits << -shift) & 0x1fn);
+        out += alphabet[idx];
+    }
+    return out;
+}
+/**
+ * `homeserver.yaml` -- rate limits raised well past Synapse's defaults
+ * (`rc_*` below), matching `calls/proof/provider/scripts/guest-stack.mjs`'s
+ * own real-deployment values: every guest session this stack mints goes
+ * through MAS's admin API and Synapse's client API in a burst when a call
+ * starts, not at human typing speed.
+ */
+export function callsSynapseHomeserverYaml(input) {
+    const serverName = callsServerName(input.orgSlug);
+    const rateLimit = '{ per_second: 100, burst_count: 1000 }';
+    return [
+        '# Generated by @wtfalch/foundry (executor.ts, coolify:calls). Do not edit',
+        '# by hand; re-run apply instead -- it is idempotent and will not rotate',
+        '# secrets that already exist.',
+        '',
+        `server_name: "${serverName}"`,
+        'pid_file: /data/homeserver.pid',
+        'report_stats: false',
+        '',
+        'listeners:',
+        '  - port: 8008',
+        '    type: http',
+        '    tls: false',
+        '    bind_addresses: ["0.0.0.0"]',
+        '    x_forwarded: true',
+        '    resources:',
+        '      - names: [client]',
+        '        compress: false',
+        '',
+        'database:',
+        '  name: psycopg2',
+        '  args:',
+        `    user: ${input.db.user}`,
+        `    password: "${input.db.password}"`,
+        `    dbname: ${input.db.database}`,
+        `    host: ${input.db.host}`,
+        `    port: ${input.db.port}`,
+        '    cp_min: 5',
+        '    cp_max: 10',
+        '',
+        '# "Specifying an empty list ([]) here is the recommended way of disabling',
+        '# federation." (config_documentation.md, federation_domain_whitelist) --',
+        '# this homeserver never federates: it exists only to authenticate calls',
+        '# guests, never to talk to another Matrix server.',
+        'federation_domain_whitelist: []',
+        '',
+        'presence:',
+        '  enabled: false',
+        '',
+        'media_store_path: /data/media_store',
+        'signing_key_path: /data/signing.key',
+        '',
+        'matrix_authentication_service:',
+        '  enabled: true',
+        `  endpoint: "http://${input.masHost}:8080/"`,
+        `  secret: "${input.masSharedSecret}"`,
+        '',
+        `rc_message: ${rateLimit}`,
+        `rc_room_creation: ${rateLimit}`,
+        'rc_joins:',
+        `  local: ${rateLimit}`,
+        `  remote: ${rateLimit}`,
+        'rc_invites:',
+        `  per_room: ${rateLimit}`,
+        `  per_user: ${rateLimit}`,
+        `  per_issuer: ${rateLimit}`,
+        '',
+    ].join('\n');
+}
+/**
+ * `config.yaml` -- password login and registration off (the calls service is
+ * the only way in, minting a guest a personal session through the admin API,
+ * `calls/proof/provider/scripts/guest-stack.mjs`'s `provisioner`); the one
+ * registered client is the calls service itself, granted `admin_clients` so
+ * its `client_credentials` grant can carry `urn:mas:admin`.
+ */
+export function callsMasConfigYaml(input) {
+    const serverName = callsServerName(input.orgSlug);
+    const indentKey = (pem, spaces) => pem
+        .trimEnd()
+        .split('\n')
+        .map((line) => `${' '.repeat(spaces)}${line}`)
+        .join('\n');
+    return [
+        '# Generated by @wtfalch/foundry (executor.ts, coolify:calls). Do not edit by hand.',
+        '',
+        'http:',
+        '  listeners:',
+        '    - name: web',
+        '      resources:',
+        '        - name: discovery',
+        '        - name: human',
+        '        - name: oauth',
+        '        - name: compat',
+        '        - name: graphql',
+        '        - name: assets',
+        '        - name: adminapi',
+        '        - name: health',
+        '      binds:',
+        '        - address: "[::]:8080"',
+        '      proxy_protocol: false',
+        `  public_base: "http://${serverName}/"`,
+        '  trusted_proxies:',
+        '    - 0.0.0.0/0',
+        '',
+        'database:',
+        `  host: ${input.db.host}`,
+        `  port: ${input.db.port}`,
+        `  username: ${input.db.user}`,
+        `  password: "${input.db.password}"`,
+        `  database: ${input.db.database}`,
+        '  ssl_mode: disable',
+        '',
+        'matrix:',
+        '  kind: synapse',
+        `  homeserver: ${serverName}`,
+        `  endpoint: "http://${input.synapseHost}:8008"`,
+        `  secret: "${input.sharedSecret}"`,
+        '',
+        '# The calls service is the only way in.',
+        'passwords:',
+        '  enabled: false',
+        '',
+        'account:',
+        '  password_registration_enabled: false',
+        '',
+        'clients:',
+        `  - client_id: "${input.clientId}"`,
+        '    client_auth_method: client_secret_basic',
+        `    client_secret: "${input.clientSecret}"`,
+        '',
+        'policy:',
+        '  data:',
+        '    admin_clients:',
+        `      - "${input.clientId}"`,
+        '',
+        'secrets:',
+        `  encryption: ${input.encryptionKey}`,
+        '  keys:',
+        '    - key: |',
+        indentKey(input.rsaKeyPem, 8),
+        '    - key: |',
+        indentKey(input.ecKeyPem, 8),
+        '',
+    ].join('\n');
+}

package/dist/plan/cloudflared-connector.d.ts

@@ -0,0 +1,70 @@
+import type { CloudflarePort, CoolifyPort } from './executor.js';
+/**
+ * #197: the pinned `cloudflared` image, the same release tag as
+ * `scripts/shared-ingress.mjs`'s and `calls-sfu.ts`'s own
+ * `CLOUDFLARED_IMAGE_REF`. A test in each keeps the three equal.
+ */
+export declare const CLOUDFLARED_IMAGE_REF = "cloudflare/cloudflared:2026.9.3";
+/**
+ * The inline Dockerfile a docker-image `cloudflared` app needs, copied from
+ * `scripts/shared-ingress.mjs`'s `cloudflaredDockerfile()`: the published
+ * image's own `CMD` is `version`, and Coolify's `start_command` is ignored
+ * for image-based applications, so the run command has to be stated in a
+ * Dockerfile's `CMD` instead. `TUNNEL_TOKEN` is never baked in here; it
+ * reaches the container only via `bulkUpsertEnvs`, as an environment
+ * variable `cloudflared` reads at boot.
+ */
+export declare function cloudflaredDockerfile(): string;
+/**
+ * #197: ensure one `cloudflared` connector app exists in Coolify for a
+ * tunnel, with the current token, deployed if needed. Decision: one connector
+ * per platform tunnel, so each tunnel-owning platform step (auth, mail,
+ * archon) calls this once with its own app name and scope key.
+ */
+export interface EnsureCloudflaredConnectorInput {
+    coolify: Pick<CoolifyPort, 'findApplicationByName' | 'getApplication' | 'createDockerfileApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy'>;
+    cloudflare: Pick<CloudflarePort, 'getTunnelToken'>;
+    /** The Cloudflare tunnel this connector dials into (already created and configured by the caller). */
+    tunnelId: string;
+    /** Fixed name, found before created -- so a second apply reuses this app rather than making a second one. */
+    appName: string;
+    projectUuid: string;
+    environment: {
+        id: number;
+        name: string;
+        uuid: string;
+    };
+    /** Called only when the app must be created -- never on the found-by-name or found-by-id paths. */
+    resolveServer: () => Promise<{
+        uuid: string;
+    }>;
+    /**
+     * The app's uuid from a prior run's recorded scope id, or `null`. When
+     * given, it is trusted over a by-name lookup, so a renamed or
+     * duplicate-named app never causes a second create. A recorded uuid whose
+     * app no longer exists (not found) falls through to find-by-name, then create.
+     */
+    recordedConnectorAppId: string | null;
+    /**
+     * Called with the app's uuid as soon as it is created or found by name,
+     * before the token fetch, env write and deploy. The caller records and
+     * persists it there, so a later failure never leaves an app nothing points at.
+     */
+    recordAppId: (appId: string) => Promise<void>;
+}
+/**
+ * Finds or creates the one Coolify app that runs `cloudflared` for
+ * {@link EnsureCloudflaredConnectorInput.tunnelId}, writes its tunnel token as
+ * `TUNNEL_TOKEN` (a literal env var) when the token is new or changed, and
+ * deploys it when it was just created, its token changed, or it is not
+ * explicitly running (a missing status counts as not running, so a run that
+ * failed after the env write is repaired by the next one). `CLAUDE.md` rule 4.
+ *
+ * The token is a credential (`CLAUDE.md` rule 6): it goes to `bulkUpsertEnvs`
+ * and nowhere else. A failed write throws an error that names the app only,
+ * with no cause, because a Coolify error can echo the request body.
+ */
+export declare function ensureCloudflaredConnector(input: EnsureCloudflaredConnectorInput): Promise<{
+    appId: string;
+    deployed: boolean;
+}>;

package/dist/plan/cloudflared-connector.js

@@ -0,0 +1,106 @@
+import { isNotFoundError } from './executor.js';
+/**
+ * #197: the pinned `cloudflared` image, the same release tag as
+ * `scripts/shared-ingress.mjs`'s and `calls-sfu.ts`'s own
+ * `CLOUDFLARED_IMAGE_REF`. A test in each keeps the three equal.
+ */
+export const CLOUDFLARED_IMAGE_REF = 'cloudflare/cloudflared:2026.9.3';
+/**
+ * The inline Dockerfile a docker-image `cloudflared` app needs, copied from
+ * `scripts/shared-ingress.mjs`'s `cloudflaredDockerfile()`: the published
+ * image's own `CMD` is `version`, and Coolify's `start_command` is ignored
+ * for image-based applications, so the run command has to be stated in a
+ * Dockerfile's `CMD` instead. `TUNNEL_TOKEN` is never baked in here; it
+ * reaches the container only via `bulkUpsertEnvs`, as an environment
+ * variable `cloudflared` reads at boot.
+ */
+export function cloudflaredDockerfile() {
+    return `FROM ${CLOUDFLARED_IMAGE_REF}\nCMD ["tunnel", "--no-autoupdate", "run"]\n`;
+}
+/**
+ * Finds or creates the one Coolify app that runs `cloudflared` for
+ * {@link EnsureCloudflaredConnectorInput.tunnelId}, writes its tunnel token as
+ * `TUNNEL_TOKEN` (a literal env var) when the token is new or changed, and
+ * deploys it when it was just created, its token changed, or it is not
+ * explicitly running (a missing status counts as not running, so a run that
+ * failed after the env write is repaired by the next one). `CLAUDE.md` rule 4.
+ *
+ * The token is a credential (`CLAUDE.md` rule 6): it goes to `bulkUpsertEnvs`
+ * and nowhere else. A failed write throws an error that names the app only,
+ * with no cause, because a Coolify error can echo the request body.
+ */
+export async function ensureCloudflaredConnector(input) {
+    const { coolify, cloudflare } = input;
+    const liveStatus = async (uuid) => {
+        try {
+            return { found: true, status: (await coolify.getApplication(uuid)).status };
+        }
+        catch (error) {
+            if (isNotFoundError(error))
+                return { found: false };
+            throw error;
+        }
+    };
+    let appId = null;
+    let status;
+    let justCreated = false;
+    if (input.recordedConnectorAppId) {
+        const live = await liveStatus(input.recordedConnectorAppId);
+        if (live.found) {
+            appId = input.recordedConnectorAppId;
+            status = live.status;
+        }
+    }
+    if (!appId) {
+        const found = await coolify.findApplicationByName(input.appName, {
+            environmentIds: [input.environment.id],
+        });
+        if (found) {
+            const live = await liveStatus(found.uuid);
+            if (live.found) {
+                appId = found.uuid;
+                status = live.status;
+            }
+        }
+    }
+    if (!appId) {
+        const server = await input.resolveServer();
+        const created = await coolify.createDockerfileApplication({
+            project_uuid: input.projectUuid,
+            server_uuid: server.uuid,
+            environment_name: input.environment.name,
+            environment_uuid: input.environment.uuid,
+            dockerfile: cloudflaredDockerfile(),
+            name: input.appName,
+            description: 'cloudflared connector for this platform tunnel (#197)',
+            instant_deploy: false,
+        });
+        appId = created.uuid;
+        justCreated = true;
+    }
+    if (appId !== input.recordedConnectorAppId)
+        await input.recordAppId(appId);
+    const token = await cloudflare.getTunnelToken(input.tunnelId);
+    const tokenChanged = justCreated || (await tunnelTokenDiffers(coolify, appId, token));
+    if (tokenChanged) {
+        try {
+            await coolify.bulkUpsertEnvs(appId, [{ key: 'TUNNEL_TOKEN', value: token, literal: true }]);
+        }
+        catch {
+            throw new Error(`cloudflared connector ${input.appName}: writing TUNNEL_TOKEN failed`);
+        }
+    }
+    // Only a connector that is up or on its way up is left alone; a missing,
+    // stopped, crash-looping or degraded one is deployed.
+    const upOrStarting = Boolean(status?.startsWith('running') || status?.startsWith('starting'));
+    const deployed = justCreated || tokenChanged || !upOrStarting;
+    if (deployed) {
+        await coolify.deploy(appId);
+    }
+    return { appId, deployed };
+}
+/** Whether the app's live `TUNNEL_TOKEN` is missing or differs from the token just fetched. */
+async function tunnelTokenDiffers(coolify, appId, token) {
+    const live = (await coolify.listEnvs(appId)).find((e) => e.key === 'TUNNEL_TOKEN' && !e.is_preview);
+    return !live || live.value !== token;
+}

package/dist/plan/diff.d.ts

@@ -1,6 +1,8 @@
 import type { DeclaredOrg, OrgId } from '../org.js';
 import type { Plan, PlanStep, UnmanagedItem } from '../plan.js';
+import { type AgoraHostReading } from './agora.js';
 import type { LiveResource } from './live.js';
+import { type OrgPlatformReadiness } from './platform-org.js';
 /**
  * What a {@link StepExecutor} (see `plan-apply.ts`) needs to actually make a
  * step true, alongside the public {@link PlanStep} an operator reads.
@@ -56,12 +58,31 @@ export declare function toPlan(detail: PlanDetail): Plan;
  * rest: the org's owner, invited by ZITADEL email, idempotent on the
  * *recorded* resource id (`recordedIds`, sourced from
  * `AppliedState.serviceIds`) rather than a live resource, since a human user
- * is never something `live` can contain. Everything else in `live` that none
- * of these twelve singletons and however many declared issuer apps claim is
- * unmanaged. The full field-by-field provisioning surface (SSO, guests,
- * calls, adopted/bespoke apps, the actual
+ * is never something `live` can contain. #128 adds one more singleton, off
+ * by default unlike chat's own: {@link planCalls}, the org's own calls
+ * Matrix stack (`org.ts`'s `CallsConfig.enabled`). #145 adds one more,
+ * planned right after it and gated on the same flag: {@link planCallsService},
+ * the calls service itself (`wtfalch/calls`'s `packages/service`). #164 adds
+ * two more, unconditionally -- no `DeclaredOrg` field gates either, since
+ * every org's own Agora is always on: {@link planAgoraClient}, a fixed
+ * ZITADEL web client named `agora` (modeled on {@link planCmsClient}), and
+ * {@link planAgora}, the Agora itself as a Coolify app (modeled on
+ * {@link planSite}, minus the park branch -- foundry never deletes an
+ * Agora). #173 adds one more, gated on `org.hosting.enabled` like
+ * {@link planApp} itself: {@link planJobsRegistration}, registering the org's
+ * app with the platform's jobs scheduler, idempotent on the *recorded*
+ * resource id like {@link planOwner} rather than a live resource, since
+ * nothing in `live` can report a scheduler registration (no reader exists for
+ * it). Everything
+ * else in `live` that none of these eighteen singletons and however many
+ * declared issuer apps claim is unmanaged. The full field-by-field provisioning surface (SSO,
+ * guests, calls on the org's own domain, adopted/bespoke apps, the actual
  * Zitadel/Coolify/Cloudflare/Files/AI/cms shapes) is #20's "provision
  * Company Factory end to end", which wires real readers and executors
  * against this seam.
  */
-export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>): PlanDetail;
+export declare function computePlanDetail(org: DeclaredOrg, live: LiveResource[], recordedIds?: Readonly<Record<string, string>>, agoraHost?: AgoraHostReading, jobsAvailable?: boolean, platformReadiness?: OrgPlatformReadiness): PlanDetail;
+/** Restated from `executor.ts`, the same rule: the id of an ai key minted but not delivered. */
+export declare const AI_KEY_UNDELIVERED_SCOPE_KEY = "ai_key_undelivered";
+/** Restated from `executor.ts`, the same rule: the id of a jobs project registered but not delivered. */
+export declare const JOBS_REGISTRATION_UNDELIVERED_SCOPE_KEY = "jobs_registration_undelivered";