@wtfalch/foundry 0.2.0 → 0.4.0

package/dist/migrate.d.ts

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

package/dist/migrate.js

@@ -0,0 +1,47 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// #R2 (map gap: foundry's own Postgres, two commands): a tracked, idempotent
+// migration runner. `./test/db.ts` and `./runner/test/db.ts` already read
+// and sort this same directory to build one concatenated blob for a fresh
+// PGlite -- fine for a test fixture that always starts empty, wrong for a
+// real host that must apply only what a `foundry_schema_migrations` table
+// does not yet list. `migrationFiles` below is that same discovery, reused
+// rather than re-implemented, kept per-file instead of concatenated.
+const here = dirname(fileURLToPath(import.meta.url));
+/** This package's own migrations -- `../migrations` from `src/`, `./migrations` once built to `dist/` (`package.json`'s `build` script copies the `.sql` files there alongside `migrate.js`). */
+export const MIGRATIONS_DIR = join(here, 'migrations');
+const TRACKING_TABLE = 'foundry_schema_migrations';
+function migrationFiles(dir) {
+    return readdirSync(dir)
+        .filter((f) => /^\d{4}_.+\.sql$/.test(f))
+        .sort()
+        .map((name) => ({ name, path: join(dir, name) }));
+}
+/**
+ * Applies every migration file in `dir` (default: this package's own
+ * `../migrations`) not yet recorded in `foundry_schema_migrations`, in
+ * filename order, one transaction per file. Safe to call repeatedly: a file
+ * already recorded is never re-read, let alone re-run.
+ */
+export async function migrate(sql, dir = MIGRATIONS_DIR) {
+    await sql.exec(`create table if not exists ${TRACKING_TABLE} (name text primary key, applied_at timestamptz not null default now())`);
+    const appliedRows = await sql.query(`select name from ${TRACKING_TABLE}`);
+    const applied = new Set(appliedRows.map((row) => row.name));
+    const pending = migrationFiles(dir).filter((file) => !applied.has(file.name));
+    const done = [];
+    for (const file of pending) {
+        const text = readFileSync(file.path, 'utf8');
+        await sql.transaction(async (tx) => {
+            await tx.exec(text);
+            // `file.name` is drawn from `migrationFiles`' own regex-filtered
+            // `readdirSync`, never from outside this module -- see `MigrateSql`'s
+            // doc comment. Quotes are still escaped, so an oddly-named future
+            // migration file cannot break the statement.
+            const escaped = file.name.replace(/'/g, "''");
+            await tx.exec(`insert into ${TRACKING_TABLE} (name) values ('${escaped}')`);
+        });
+        done.push(file.name);
+    }
+    return { applied: done };
+}

package/dist/migrations/0012_audit.sql

@@ -0,0 +1,21 @@
+-- @wtfalch/foundry: who planned, applied or destroyed which org, and how it
+-- went. Mirrors `src/store/schema.ts`'s `foundryAuditEvents`.
+--
+-- Decided on #85: before any archon exists, the foundry CLI records here. An
+-- attached archon reads this table later. Rows are only ever inserted.
+-- `org_id` has no foreign key, so a destroyed org's trail survives it.
+
+create table if not exists foundry_audit_events (
+  id bigserial primary key,
+  at timestamptz not null,
+  kind text not null check (kind in ('plan', 'apply', 'destroy')),
+  actor_id text not null,
+  actor_display text not null,
+  org_id text not null,
+  outcome text check (outcome in ('applied', 'refused', 'failed', 'destroyed')),
+  reason text,
+  plan jsonb
+);
+
+create index if not exists foundry_audit_events_org_at
+  on foundry_audit_events (org_id, at);

package/dist/migrations/0013_access_emails.sql

@@ -0,0 +1,6 @@
+-- @wtfalch/foundry: emails Cloudflare Access lets through to the org's app
+-- (#84). Mirrors `src/store/schema.ts`'s `hostingAccessEmails`. An empty list
+-- means no Access gate, so every existing org keeps its current behaviour.
+
+alter table foundry_declared_orgs
+  add column if not exists hosting_access_emails jsonb not null default '[]'::jsonb;

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;
 }
 /**
@@ -147,6 +159,11 @@ export interface HostingConfig {
     buildPack: HostingBuildPack;
     /** The org's declared ZITADEL OIDC applications (#71). */
     issuerApps: IssuerApp[];
+    /**
+     * Emails Cloudflare Access lets through to the app's hostname (#84). Empty
+     * means no Access gate. Requires `enabled`.
+     */
+    accessEmails: string[];
 }
 /**
  * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
@@ -160,6 +177,28 @@ 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).
+ *
+ * Decided 2026-09-25
+ * (https://github.com/wtfalch/cms/blob/main/.plans/2026-09-25-org-sites.md):
+ * a cms site is how an org puts content on its own domain, and an org
+ * either runs its own app on its domain (`hosting`) or we host its website
+ * and cms there (`site`), never both -- both would otherwise fight over the
+ * same hostname (https://github.com/wtfalch/foundry/issues/99).
+ *
+ * - `site.enabled` requires `domain` to be set -- a site with nowhere to
+ *   live is not a site.
+ * - `site.enabled` requires `site.usesDomain` -- unlike mail, chat, calls
+ *   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;
 /**
  * Per-org SSO. Decided to exist in #14 ("Also in scope") and its resolved
  * research #3 ("per-org SSO code exists unused"); nothing about its

package/dist/org.js

@@ -29,6 +29,14 @@ export function validateHosting(hosting) {
     if (!HOSTING_BUILD_PACKS.has(hosting.buildPack)) {
         return `hosting.buildPack has an unknown value '${hosting.buildPack}'`;
     }
+    if (hosting.accessEmails.length > 0 && !hosting.enabled) {
+        return 'hosting.accessEmails requires hosting.enabled';
+    }
+    for (const email of hosting.accessEmails) {
+        if (!/^[^@\s]+@[^@\s]+$/.test(email)) {
+            return `hosting.accessEmails has an invalid email '${email}'`;
+        }
+    }
     const seenNames = new Set();
     for (const app of hosting.issuerApps) {
         if (!app.name) {
@@ -44,6 +52,83 @@ 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).
+ *
+ * Decided 2026-09-25
+ * (https://github.com/wtfalch/cms/blob/main/.plans/2026-09-25-org-sites.md):
+ * a cms site is how an org puts content on its own domain, and an org
+ * either runs its own app on its domain (`hosting`) or we host its website
+ * and cms there (`site`), never both -- both would otherwise fight over the
+ * same hostname (https://github.com/wtfalch/foundry/issues/99).
+ *
+ * - `site.enabled` requires `domain` to be set -- a site with nowhere to
+ *   live is not a site.
+ * - `site.enabled` requires `site.usesDomain` -- unlike mail, chat, calls
+ *   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) {
+        return 'site.enabled requires domain';
+    }
+    if (org.site.enabled && !org.site.usesDomain) {
+        return 'site.enabled requires site.usesDomain';
+    }
+    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}$/;
 /**
  * `null` when `buyer` is valid; otherwise the reason it is not, for a caller

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;