@wtfalch/foundry 0.3.0 → 0.4.0

package/dist/calls-sfu.d.ts

@@ -118,6 +118,23 @@ export declare const LIVEKIT_MEDIA_UDP_RANGE = "50000:60000";
  * reachable from the public internet at all -- #127's "Decided" section.
  */
 export declare const CALLS_SFU_PRIVATE_CIDR = "10.10.10.0/24";
+/**
+ * The SFU's own address on {@link CALLS_SFU_PRIVATE_CIDR}'s private network
+ * -- decided as a fixed value (foundry#145's "Decided", 2026-09-27) rather
+ * than threaded through as config: the estate has exactly one calls SFU (VM
+ * 105, this file's own top doc comment), and `.105` is that VM's own number.
+ * The calls service (foundry#145, part 2 of #128) reaches LiveKit's API here,
+ * over `vmbr1`, never through the tunnel.
+ */
+export declare const CALLS_SFU_PRIVATE_URL = "http://10.10.10.105:7880";
+/**
+ * The SFU's public `wss://`-capable address, reached through its own named
+ * tunnel (#127, `scripts/calls-sfu-ingress.mjs`) -- also decided as a fixed
+ * value (foundry#145's "Decided", 2026-09-27): `../slug.ts` reserves the
+ * `calls-sfu` slug for exactly this reason, so no org can ever take this
+ * hostname out from under it.
+ */
+export declare const CALLS_SFU_PUBLIC_URL = "https://calls-sfu.oikos.host";
 /**
  * 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

package/dist/calls-sfu.js

@@ -115,6 +115,23 @@ export const LIVEKIT_MEDIA_UDP_RANGE = '50000:60000';
  * reachable from the public internet at all -- #127's "Decided" section.
  */
 export const CALLS_SFU_PRIVATE_CIDR = '10.10.10.0/24';
+/**
+ * The SFU's own address on {@link CALLS_SFU_PRIVATE_CIDR}'s private network
+ * -- decided as a fixed value (foundry#145's "Decided", 2026-09-27) rather
+ * than threaded through as config: the estate has exactly one calls SFU (VM
+ * 105, this file's own top doc comment), and `.105` is that VM's own number.
+ * The calls service (foundry#145, part 2 of #128) reaches LiveKit's API here,
+ * over `vmbr1`, never through the tunnel.
+ */
+export const CALLS_SFU_PRIVATE_URL = `http://10.10.10.105:${LIVEKIT_SIGNALLING_PORT}`;
+/**
+ * The SFU's public `wss://`-capable address, reached through its own named
+ * tunnel (#127, `scripts/calls-sfu-ingress.mjs`) -- also decided as a fixed
+ * value (foundry#145's "Decided", 2026-09-27): `../slug.ts` reserves the
+ * `calls-sfu` slug for exactly this reason, so no org can ever take this
+ * hostname out from under it.
+ */
+export const CALLS_SFU_PUBLIC_URL = 'https://calls-sfu.oikos.host';
 /**
  * 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

package/dist/index.d.ts

@@ -12,7 +12,7 @@ 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, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } from './plan/index.js';
+export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, FilesOrgLimits, AiOrgLimits, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, } 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';

package/dist/migrations/0014_calls_enabled.sql

@@ -0,0 +1,7 @@
+-- @wtfalch/foundry: turns on an org's own calls Matrix stack (#128). Mirrors
+-- `src/store/schema.ts`'s `callsEnabled`. Defaults false, same as every other
+-- per-org on/off switch (`site_enabled`, `hosting_enabled`) -- an existing
+-- org has no calls stack until it declares one.
+
+alter table foundry_declared_orgs
+  add column if not exists calls_enabled boolean not null default false;

package/dist/migrations/0015_domain_unique.sql

@@ -0,0 +1,39 @@
+-- @wtfalch/foundry: the declared org's domain is globally unique, one non-
+-- null value per org, on top of #0001's `foundry_declared_orgs` table (#131).
+-- Mirrors src/store/schema.ts's `domain` column, which has no index of its
+-- own to express -- this file, not the schema, is the index's source of
+-- truth, the same convention `0004_slug_unique.sql`'s header explains.
+--
+-- Partial (`where domain is not null`): a brand new org has no domain yet
+-- (org.ts's own doc comment on `DeclaredOrg.domain`), so a plain unique
+-- index would let only one such org exist at a time -- every other null
+-- would collide with it.
+--
+-- Forced by the same routing collision `0004_slug_unique.sql` exists for: an
+-- org's domain is the Cloudflare zone and Coolify hostname it is served on
+-- once any service opts in (org.ts's `MailConfig`/`ChatConfig`/etc.
+-- `usesDomain`, plan/executor.ts's `hostnameFor`), so two orgs sharing a
+-- domain would fight over both from the moment the second is declared, with
+-- no refusal today. src/store/postgres.ts's `create` and `update` already
+-- call org.ts's `validateDomain` before this index is ever reached; the
+-- index exists to catch the race the pre-check cannot -- two concurrent
+-- writes for the same domain -- which postgres.ts maps back to the same
+-- `DeclaredOrgError` a pre-check would have thrown, per #18's rule that a
+-- caller gets a reason by name either way.
+--
+-- Format validity (DNS-label-per-segment) is org.ts's `validateDomain`'s
+-- job, not a CHECK constraint's -- #0001's header already gives the
+-- reasoning for keeping "combinations foundry knows are impossible" in the
+-- code path that can explain itself, not in SQL that can't. Whether this
+-- index (or `validateDomain`) should normalize case before comparing is
+-- still open (#131 "Decide") -- `validateDomain` requires lowercase input
+-- outright today, so this index never has to compare two differently-cased
+-- values in the first place.
+--
+-- Human step before this ships (#131): audit existing declared orgs for a
+-- pre-existing domain collision -- this index refuses to apply if one
+-- already exists.
+
+create unique index if not exists foundry_declared_orgs_domain_idx
+  on foundry_declared_orgs (domain)
+  where domain is not null;

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

@@ -52,6 +52,48 @@ export function validateHosting(hosting) {
     }
     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;
+}
 /**
  * `null` when `site` is valid; otherwise the reason it is not (#101).
  *
@@ -68,6 +110,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 +124,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/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;

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

@@ -56,10 +56,14 @@ 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`). Everything
+ * else in `live` that none of these fifteen 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.