@wtfalch/foundry 0.3.0 → 0.5.0

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.d.ts

@@ -55,10 +55,22 @@ export interface ChatConfig {
  * Calls' per-service opt-in into the org's `domain` fact, in the same shape
  * as mail, chat and the issuer so that none of them are coupled to `domain`
  * being set (#7 amendment 1, carried into
- * https://github.com/wtfalch/foundry/issues/18's "Done when" list). Nothing
- * about calls' own provisioning is decided yet beyond this.
+ * https://github.com/wtfalch/foundry/issues/18's "Done when" list).
+ *
+ * `enabled` (#128, #145) turns on the org's own calls Matrix stack — a
+ * dedicated Postgres, Synapse and matrix-authentication-service, entirely
+ * separate from chat's (a call guest must never gain chat membership,
+ * guaranteed structurally by the two never sharing a homeserver) — and the
+ * calls service itself (`wtfalch/calls`'s `packages/service`), wired to that
+ * stack and to the one shared LiveKit SFU the whole estate uses
+ * (foundry#122). `usesDomain` decides the calls service's own public
+ * hostname (#145's "Decided", 2026-09-27): `false` (or no `domain`) serves it
+ * flat at `<slug>-calls.oikos.host`, riding the shared tunnel with no new
+ * mechanism; `true` serves it at `calls.<domain>` on its own per-org tunnel,
+ * the same opt-in shape `hosting.usesDomain` and `site.usesDomain` use.
  */
 export interface CallsConfig {
+    enabled: boolean;
     usesDomain: boolean;
 }
 /**
@@ -165,6 +177,7 @@ export interface HostingConfig {
  *   list, and a `kind` that is one of `IssuerAppKind`'s three values.
  */
 export declare function validateHosting(hosting: HostingConfig): string | null;
+export declare function validateDomain(domain: string): string | null;
 /**
  * `null` when `site` is valid; otherwise the reason it is not (#101).
  *
@@ -181,6 +194,9 @@ export declare function validateHosting(hosting: HostingConfig): string | null;
  *   and the issuer, the site has no meaning anywhere but the org's own
  *   domain, so turning it on always means the domain opt-in too.
  * - `site.enabled` and `hosting.enabled` cannot both be on.
+ * - `site.enabled` refuses an `issuerApps` entry named `cms`: the fixed cms
+ *   client (#139, `plan/diff.ts`'s `planCmsClient`) already owns the
+ *   `zitadel:app:cms` key, and the two would overwrite each other.
  */
 export declare function validateSite(org: DeclaredOrg): string | null;
 /**

package/dist/org.js

@@ -49,6 +49,56 @@ 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;
+}
+/**
+ * A DNS-label-per-segment format check for `DeclaredOrg.domain` (#131): every
+ * dot-separated segment follows the exact rule `../slug.ts`'s `DNS_LABEL`
+ * enforces for a slug (1-63 characters, lowercase `a-z`, `0-9` and hyphen, no
+ * leading or trailing hyphen) -- duplicated here rather than imported, the
+ * same "restated, not shared" choice `plan/executor.ts`'s `hostnameFor` makes
+ * for the hostname rule, since a domain is not a slug: a slug is always
+ * exactly one label, a domain is at least two (a bare label has no apex
+ * Cloudflare can host a zone for).
+ *
+ * Forced by the same routing collision `../slug.ts`'s own top comment names
+ * for the slug: two orgs on the same domain would be routed to the same
+ * Cloudflare zone and Coolify hostname with no refusal
+ * (`store/postgres.ts`'s `create`/`update` call this the same place they
+ * call `requireValidSlug`; `migrations/0015_domain_unique.sql` adds the
+ * matching unique index).
+ *
+ * Requiring lowercase outright, rather than lowercasing before comparing, is
+ * the same choice `../slug.ts`'s `DNS_LABEL` already makes for a slug --
+ * whether the unique index should instead normalize case is open (#131
+ * "Decide"), but this validator never lets two domains differing only by
+ * case both exist to be compared in the first place.
+ *
+ * `null` when `domain` is valid; otherwise the reason it is not, same shape
+ * as {@link validateBuyerIdentity}/{@link validateOwner}.
+ */
+const DOMAIN_LABEL = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
+export function validateDomain(domain) {
+    if (domain.length > 253) {
+        return `domain '${domain}' exceeds 253 characters`;
+    }
+    const labels = domain.split('.');
+    if (labels.length < 2) {
+        return `domain '${domain}' must have at least two dot-separated labels`;
+    }
+    for (const label of labels) {
+        if (!DOMAIN_LABEL.test(label)) {
+            return `domain '${domain}' has an invalid label '${label}': must be 1-63 characters, lowercase a-z, 0-9 and hyphen, and may not start or end with a hyphen`;
+        }
     }
     return null;
 }
@@ -68,6 +118,9 @@ export function validateHosting(hosting) {
  *   and the issuer, the site has no meaning anywhere but the org's own
  *   domain, so turning it on always means the domain opt-in too.
  * - `site.enabled` and `hosting.enabled` cannot both be on.
+ * - `site.enabled` refuses an `issuerApps` entry named `cms`: the fixed cms
+ *   client (#139, `plan/diff.ts`'s `planCmsClient`) already owns the
+ *   `zitadel:app:cms` key, and the two would overwrite each other.
  */
 export function validateSite(org) {
     if (org.site.enabled && !org.domain) {
@@ -79,6 +132,9 @@ export function validateSite(org) {
     if (org.site.enabled && org.hosting.enabled) {
         return 'site.enabled and hosting.enabled cannot both be on';
     }
+    if (org.site.enabled && org.hosting.issuerApps.some((app) => app.name === 'cms')) {
+        return "site.enabled reserves the issuerApps name 'cms'";
+    }
     return null;
 }
 const ORG_NUMBER_PATTERN = /^\d{9}$/;

package/dist/plan/agora.d.ts

@@ -0,0 +1,77 @@
+import type { DeclaredOrg, OrgId } from '../org.js';
+/**
+ * #164: what both the planner (`diff.ts`) and the executor (`executor.ts`)
+ * need to agree on for an org's Agora -- the hostname, the values the host
+ * supplies, and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write.
+ */
+/**
+ * `AppliedState.serviceIds` scope keys `desiredAgoraEnv` reads:
+ * `zitadel_org` is `executor.ts`'s `ensureZitadelProject`/`zitadelIssuer`
+ * scope id, `agora_client_id` the fixed `agora` ZITADEL client's `clientId`
+ * (recorded by `executor.ts`'s `zitadelApp`).
+ */
+export declare const ZITADEL_ORG_SCOPE_KEY = "zitadel_org";
+export declare const AGORA_CLIENT_ID_SCOPE_KEY = "agora_client_id";
+/**
+ * The accent every org's Agora wears until orgs choose their own: the house
+ * theme's `--accent` (`@wtfalch/house`, `HOUSE_THEMES['good-company']` in
+ * `design/packages/house/src/themes.ts`, the default theme
+ * `HOUSE_DEFAULT_THEME`). Agora's config parser requires `theme.accent` as a
+ * hex colour (`agora/apps/agora/src/agoras.ts`). Restated here rather than
+ * imported: `packages/foundry` carries no `@wtfalch/house` dependency.
+ */
+export declare const AGORA_THEME_ACCENT = "#B23A0C";
+/**
+ * Provider-side values only the host can supply, like every other provider
+ * value `FoundryStepExecutorPorts` carries. As of #177, `plan-apply.ts`'s
+ * `FoundryPlanApply` derives these itself from the applied platform
+ * (`platform-org.ts`'s `agoraHostValuesFromPlatform`) whenever a host wires
+ * one in and supplies no `AgoraHostPort` of its own -- an explicit `agora`
+ * port still overrides that, unchanged. `null` means the value is not
+ * available yet. The first three are required by Agora's config parser
+ * (`agoras.ts`: `issuer`, `mailProjectId`, `messagingProjectId`);
+ * `mailUpstream`/`filesUpstream` are the mail/files servers' internal
+ * addresses, optional -- unset, `AGORA_MAIL_UPSTREAM`/`AGORA_FILES_UPSTREAM`
+ * are not pushed and Agora answers 502 on those routes rather than serving
+ * anything wrong (`executor.ts`'s `coolifyAgora` doc comment).
+ */
+export interface AgoraHostValues {
+    issuer: string | null;
+    mailProjectId: string | null;
+    messagingProjectId: string | null;
+    mailUpstream: string | null;
+    filesUpstream: string | null;
+}
+export interface AgoraHostPort {
+    valuesFor(orgId: OrgId): Promise<AgoraHostValues>;
+}
+/** No host values at all: what an absent port means. */
+export declare const NO_AGORA_HOST_VALUES: AgoraHostValues;
+/** What the plan reads from the host: its values, or why it could not get them. */
+export type AgoraHostReading = AgoraHostValues | {
+    error: string;
+};
+/** Reads the port once for a plan. An absent port, or one that throws, is a blocked Agora, never a failed plan. */
+export declare function readAgoraHost(port: AgoraHostPort | undefined, orgId: OrgId): Promise<AgoraHostReading>;
+/** The host values Agora cannot be configured without, by name -- the ones `host` lacks. */
+export declare function agoraHostMissing(host: AgoraHostValues): string[];
+/**
+ * `agora.<domain>` when the org has a domain, `<slug>-agora.oikos.host`
+ * otherwise (the 2026-09-24 layout, foundry#14; `../slug.ts`'s
+ * `AGORA_SUFFIX` reserves the collision).
+ */
+export declare function agoraHostnameFor(org: DeclaredOrg): string;
+/**
+ * The env vars an org's Agora app should carry, and every input still
+ * missing to build them. `AGORA_CONFIG` is present only when `missing` is
+ * empty; callers that write must refuse on a non-empty `missing`.
+ * `AGORA_MAIL_UPSTREAM` is present only when mail is on and the host supplies
+ * an address.
+ */
+export declare function desiredAgoraEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, host: AgoraHostValues): {
+    env: Record<string, string>;
+    missing: string[];
+};
+/** The desired env keys the live app lacks or holds a different value for. Extra live keys are ignored. */
+export declare function agoraEnvDrift(desired: Readonly<Record<string, string>>, live: Readonly<Record<string, string>>): string[];

package/dist/plan/agora.js

@@ -0,0 +1,127 @@
+/**
+ * #164: what both the planner (`diff.ts`) and the executor (`executor.ts`)
+ * need to agree on for an org's Agora -- the hostname, the values the host
+ * supplies, and the env vars those produce -- so the plan can compare the
+ * live app with exactly what the executor would write.
+ */
+/**
+ * `AppliedState.serviceIds` scope keys `desiredAgoraEnv` reads:
+ * `zitadel_org` is `executor.ts`'s `ensureZitadelProject`/`zitadelIssuer`
+ * scope id, `agora_client_id` the fixed `agora` ZITADEL client's `clientId`
+ * (recorded by `executor.ts`'s `zitadelApp`).
+ */
+export const ZITADEL_ORG_SCOPE_KEY = 'zitadel_org';
+export const AGORA_CLIENT_ID_SCOPE_KEY = 'agora_client_id';
+/**
+ * The accent every org's Agora wears until orgs choose their own: the house
+ * theme's `--accent` (`@wtfalch/house`, `HOUSE_THEMES['good-company']` in
+ * `design/packages/house/src/themes.ts`, the default theme
+ * `HOUSE_DEFAULT_THEME`). Agora's config parser requires `theme.accent` as a
+ * hex colour (`agora/apps/agora/src/agoras.ts`). Restated here rather than
+ * imported: `packages/foundry` carries no `@wtfalch/house` dependency.
+ */
+export const AGORA_THEME_ACCENT = '#B23A0C';
+/** No host values at all: what an absent port means. */
+export const NO_AGORA_HOST_VALUES = {
+    issuer: null,
+    mailProjectId: null,
+    messagingProjectId: null,
+    mailUpstream: null,
+    filesUpstream: null,
+};
+/** Reads the port once for a plan. An absent port, or one that throws, is a blocked Agora, never a failed plan. */
+export async function readAgoraHost(port, orgId) {
+    if (!port)
+        return NO_AGORA_HOST_VALUES;
+    try {
+        return await port.valuesFor(orgId);
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+}
+/** The host values Agora cannot be configured without, by name -- the ones `host` lacks. */
+export function agoraHostMissing(host) {
+    const missing = [];
+    if (!host.issuer)
+        missing.push('issuer');
+    if (!host.mailProjectId)
+        missing.push('mailProjectId');
+    if (!host.messagingProjectId)
+        missing.push('messagingProjectId');
+    return missing;
+}
+/**
+ * `agora.<domain>` when the org has a domain, `<slug>-agora.oikos.host`
+ * otherwise (the 2026-09-24 layout, foundry#14; `../slug.ts`'s
+ * `AGORA_SUFFIX` reserves the collision).
+ */
+export function agoraHostnameFor(org) {
+    return org.domain ? `agora.${org.domain}` : `${org.slug}-agora.oikos.host`;
+}
+/**
+ * The env vars an org's Agora app should carry, and every input still
+ * missing to build them. `AGORA_CONFIG` is present only when `missing` is
+ * empty; callers that write must refuse on a non-empty `missing`.
+ * `AGORA_MAIL_UPSTREAM` is present only when mail is on and the host supplies
+ * an address.
+ */
+export function desiredAgoraEnv(org, recorded, host) {
+    const env = { AGORA_CANONICAL_HOST: agoraHostnameFor(org) };
+    const zitadelOrgId = recorded[ZITADEL_ORG_SCOPE_KEY];
+    const clientId = recorded[AGORA_CLIENT_ID_SCOPE_KEY];
+    const missing = [];
+    if (!zitadelOrgId)
+        missing.push('zitadelOrgId');
+    if (!clientId)
+        missing.push('clientId');
+    missing.push(...agoraHostMissing(host));
+    if (missing.length === 0) {
+        env.AGORA_CONFIG = JSON.stringify({
+            name: org.displayName,
+            theme: { accent: AGORA_THEME_ACCENT },
+            issuer: host.issuer,
+            clientId,
+            organisationId: zitadelOrgId,
+            mailProjectId: host.mailProjectId,
+            messagingProjectId: host.messagingProjectId,
+        });
+    }
+    if (org.mail.mode !== 'off' && host.mailUpstream) {
+        env.AGORA_MAIL_UPSTREAM = host.mailUpstream;
+    }
+    // Files is always on for every org (#80), unlike mail -- no mode to gate
+    // this on, only whether the host supplies an address at all (#177).
+    if (host.filesUpstream) {
+        env.AGORA_FILES_UPSTREAM = host.filesUpstream;
+    }
+    return { env, missing };
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stable).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1);
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stable(v)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function sameEnvValue(key, desired, live) {
+    if (key !== 'AGORA_CONFIG')
+        return desired === live;
+    try {
+        return stable(JSON.parse(desired)) === stable(JSON.parse(live));
+    }
+    catch {
+        return false;
+    }
+}
+/** The desired env keys the live app lacks or holds a different value for. Extra live keys are ignored. */
+export function agoraEnvDrift(desired, live) {
+    return Object.entries(desired)
+        .filter(([key, value]) => {
+        const liveValue = live[key];
+        return liveValue === undefined || !sameEnvValue(key, value, liveValue);
+    })
+        .map(([key]) => key);
+}

package/dist/plan/calls-matrix.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 declare const SYNAPSE_IMAGE = "ghcr.io/element-hq/synapse";
+export declare const SYNAPSE_TAG = "v1.161.0";
+export declare 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 declare function callsServerName(orgSlug: string): string;
+/** One `internal_db_url`, split into the discrete fields Synapse's and MAS's own YAML shapes each want. */
+export interface CallsDbConnection {
+    host: string;
+    port: number;
+    user: string;
+    password: string;
+    database: string;
+}
+/**
+ * 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 declare function parseCallsDbUrl(internalDbUrl: string): CallsDbConnection | null;
+/**
+ * Minted once per org and kept alive only as envs on the MAS app itself
+ * ({@link CALLS_SECRET_ENV_KEYS}, read back by `executor.ts`'s
+ * `coolifyCalls` before minting fresh ones) -- this package has no
+ * `ctx.outputs` state file the way `archon/bootstrap/steps/chat-instance.ts`
+ * does, so an env already on the app that needs them is this stack's only
+ * memory across a re-run.
+ */
+export interface CallsMatrixSecrets {
+    masSynapseSharedSecret: string;
+    masClientId: string;
+    masClientSecret: string;
+    masEncryptionKey: string;
+    masRsaKeyPem: string;
+    masEcKeyPem: string;
+}
+export declare function mintCallsMatrixSecrets(): CallsMatrixSecrets;
+/**
+ * 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 declare function generateUlid(bytes?: Buffer): string;
+export interface CallsSynapseHomeserverInput {
+    orgSlug: string;
+    db: CallsDbConnection;
+    masHost: string;
+    masSharedSecret: string;
+}
+/**
+ * `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 declare function callsSynapseHomeserverYaml(input: CallsSynapseHomeserverInput): string;
+export interface CallsMasConfigInput {
+    orgSlug: string;
+    db: CallsDbConnection;
+    synapseHost: string;
+    sharedSecret: string;
+    clientId: string;
+    clientSecret: string;
+    encryptionKey: string;
+    rsaKeyPem: string;
+    ecKeyPem: string;
+}
+/**
+ * `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 declare function callsMasConfigYaml(input: CallsMasConfigInput): string;