@wtfalch/foundry 0.2.0 → 0.3.0

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

@@ -147,6 +147,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 +165,24 @@ export interface HostingConfig {
  *   list, and a `kind` that is one of `IssuerAppKind`'s three values.
  */
 export declare function validateHosting(hosting: HostingConfig): 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.
+ */
+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,35 @@ export function validateHosting(hosting) {
     }
     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.
+ */
+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';
+    }
+    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/diff.js

@@ -73,6 +73,18 @@ export function computePlanDetail(org, live, recordedIds = {}) {
     const site = planSite(org, byKey, claimed);
     if (site)
         plannedSteps.push(site);
+    // Every declared ZITADEL app, before the app cluster below (level-1
+    // app-env campaign, gap P2): `coolifyApp`'s own env push
+    // (`executor.ts`'s `pushAppEnv`) reads a web app's `clientId` to set
+    // `AUTH_CLIENT_ID`, which only exists once that app's own `zitadel:app`
+    // step has run -- `plan-apply.ts`'s `runSteps` executes `plannedSteps` in
+    // this array order, one at a time.
+    plannedSteps.push(...planIssuerApps(org, byKey, claimed));
+    // The Access gate before the database, app, tunnel and zone (#84): on a
+    // first apply the hostname is gated before anything answers on it.
+    const access = planAccess(org, recordedIds);
+    if (access)
+        plannedSteps.push(access);
     // Database before app (hosting-wiring campaign): `plan-apply.ts`'s
     // `runSteps` executes `plannedSteps` in this array order, and the app's own
     // step (`executor.ts`'s `coolifyApp`) pushes the database's connection
@@ -91,7 +103,12 @@ export function computePlanDetail(org, live, recordedIds = {}) {
     const zone = planZone(org, byKey, claimed);
     if (zone)
         plannedSteps.push(zone);
-    plannedSteps.push(...planIssuerApps(org, byKey, claimed));
+    // Right after the zone (#43): `cloudflareRateLimit` resolves the zone by
+    // apex domain, so the zone step above must already have run (or the zone
+    // must already exist live) by the time this one's action executes.
+    const rateLimit = planRateLimit(org, recordedIds);
+    if (rateLimit)
+        plannedSteps.push(rateLimit);
     // After the apps: the customers org is granted the project the first app
     // step creates.
     const customers = planCustomers(org, live, claimed, recordedIds);
@@ -562,9 +579,42 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
  * The org's own app on Coolify (`org.ts`'s `HostingConfig.enabled`, #71), a
  * per-org singleton resource modeled on {@link planSite}: park, not delete,
  * on the way off (#7 corrections 1).
+ *
+ * #75: every app foundry deploys also carries a durable log directory (a
+ * persistent volume mounted at `/app/logs`, `LOG_DIR` in its env) so a
+ * database outage does not erase the only other copy of the evidence
+ * (`executor.ts`'s `ensureLogVolume`/`pushAppEnv`, lokessmie's own pilot at
+ * https://github.com/wtfalch/lokessmie/pull/521). `planHostingToggle` above
+ * only tracks on/off, so once it finds nothing to toggle -- app live and
+ * already enabled -- this planner adds one more check on top: a live app
+ * that predates this feature (`live.config.hasLogVolume === false`,
+ * `providers-readers.ts`'s `withLogVolumeConfig`) is planned for it, reusing
+ * the same `coolify:app`/`enabled: true` action `planHostingToggle`'s own
+ * provision step uses -- `executor.ts`'s `coolifyApp` already runs
+ * `ensureLogVolume` unconditionally on that action, whether it just created
+ * the app or found it already there, so no new step kind is needed. A
+ * missing `hasLogVolume` (rather than an explicit `false`) reads as
+ * compliant, the same convention `planHostingToggle` itself uses for a live
+ * resource's `enabled` field -- a live resource nothing has actually
+ * checked yet is assumed fine rather than replanned every time.
  */
 function planApp(org, byKey, claimed) {
-    return planHostingToggle('coolify', 'app', org.hosting.enabled, org, byKey, claimed, () => `provision ${org.slug}'s app`, () => `park ${org.slug}'s app (stops serving; app data is retained, not deleted -- #7 corrections 1)`);
+    const toggled = planHostingToggle('coolify', 'app', org.hosting.enabled, org, byKey, claimed, () => `provision ${org.slug}'s app`, () => `park ${org.slug}'s app (stops serving; app data is retained, not deleted -- #7 corrections 1)`);
+    if (toggled)
+        return toggled;
+    if (!org.hosting.enabled)
+        return null;
+    const live = byKey.get(resourceKey('coolify', 'app', org.id));
+    if (!live || live.config.hasLogVolume !== false)
+        return null;
+    return {
+        action: { system: 'coolify', kind: 'app', key: org.id, desired: { enabled: true } },
+        step: {
+            description: `add a durable log directory to ${org.slug}'s app (persistent volume at /app/logs + LOG_DIR) so a database outage does not erase the evidence (#75)`,
+            destroys: false,
+            migrates: false,
+        },
+    };
 }
 /**
  * A Postgres database beside the org's app (`org.ts`'s
@@ -579,10 +629,25 @@ function planDatabase(org, byKey, claimed) {
  * A Cloudflare tunnel reaching the org's app (`org.ts`'s
  * `HostingConfig.tunnel`, #71) -- `validateHosting` requires
  * `hosting.enabled` before this can be true. Same park-not-delete shape as
- * {@link planApp}.
+ * {@link planApp}, gated on the same `usesDomain`+`domain` pair
+ * {@link planZone} checks: a level-1 org (no own domain, served at
+ * `<slug>.oikos.host`) gets no per-org tunnel at all -- one shared tunnel
+ * with a wildcard `*.oikos.host` record serves every level-1 org instead
+ * (William, 2026-09-26, map gap N3). The gate folds into the `desired`
+ * flag rather than an early return, so an org that drops its domain while
+ * a per-org tunnel is still live gets that tunnel parked, not left
+ * unmanaged, through `planHostingToggle`'s own park path.
+ *
+ * https://github.com/wtfalch/foundry/issues/115: a site-enabled org always
+ * needs its tunnel too, routing both its public site and its cms studio
+ * (`executor.ts`'s `tunnelIngressHostnames`) -- there is no separate
+ * `site.tunnel` toggle to gate on the way `hosting.tunnel` does, since a site
+ * has no meaning without one.
  */
 function planTunnel(org, byKey, claimed) {
-    return planHostingToggle('cloudflare', 'tunnel', org.hosting.tunnel, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
+    const desired = (org.hosting.tunnel && org.hosting.usesDomain && Boolean(org.domain)) ||
+        (org.site.enabled && Boolean(org.domain));
+    return planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`);
 }
 /**
  * The org's Cloudflare zone for its own domain (`org.ts`'s
@@ -593,9 +658,15 @@ function planTunnel(org, byKey, claimed) {
  * foundry should stop managing a domain the org may still own elsewhere, so
  * a live zone under a not-`usesDomain` org is left unmanaged rather than
  * claimed -- the same choice {@link planMail} makes for a `mode: 'off'` org.
+ *
+ * https://github.com/wtfalch/foundry/issues/115: a site-enabled org
+ * (`org.ts`'s `SiteConfig.enabled`) also needs a zone for its domain, even
+ * though it can never have `hosting` on at the same time (`validateSite`) --
+ * `org.site.enabled` already guarantees both `domain` and `site.usesDomain`
+ * are set, so the `org.domain` check below still covers it.
  */
 function planZone(org, byKey, claimed) {
-    if (!org.hosting.usesDomain || !org.domain)
+    if (!(org.hosting.usesDomain || org.site.enabled) || !org.domain)
         return null;
     const key = resourceKey('cloudflare', 'zone', org.domain);
     const live = byKey.get(key);
@@ -693,3 +764,63 @@ function planCustomers(org, live, claimed, recordedIds) {
         },
     };
 }
+/**
+ * #84: a Cloudflare Access gate on the org's app hostname, letting only
+ * `hosting.accessEmails` through. Idempotent on the recorded Access app id,
+ * like `planOwner`: Cloudflare's live listing has no Access apps. A later
+ * change to the email list is not reconciled yet.
+ */
+function planAccess(org, recordedIds) {
+    if (!org.hosting.enabled || org.hosting.accessEmails.length === 0)
+        return null;
+    if (recordedIds[resourceKey('cloudflare', 'access', org.id)])
+        return null;
+    return {
+        action: { system: 'cloudflare', kind: 'access', key: org.id, desired: {} },
+        step: {
+            description: `put ${org.slug}'s app behind Cloudflare Access`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}
+/**
+ * https://github.com/wtfalch/foundry/issues/43: one Cloudflare rate-limiting
+ * rule on the org's own app hostname's sign-in paths (`@wtfalch/auth`'s
+ * `NextAuth.handlers`, mounted at `app/auth/[...auth]/route.ts` -- every
+ * sign-in request passes through `/auth/*`, `executor.ts`'s
+ * `cloudflareRateLimit`). Gated on the same `usesDomain`/`site.enabled`
+ * +`domain` pair {@link planZone} and {@link planTunnel} check (widened for a
+ * site-enabled org by #115: the cms studio signs in under `/auth/` too, on
+ * the same zone {@link planZone} provisions for it): only an own-domain org
+ * gets this step. A level-1 org (no own domain, served at
+ * `<slug>.oikos.host`) shares the `oikos.host` zone with every other level-1
+ * org, and Cloudflare's Free plan allows exactly one rate limiting rule per
+ * zone (developers.cloudflare.com/waf/rate-limiting-rules/, checked
+ * 2026-09-26) -- a per-org step here would fight every other level-1 org's
+ * for that one slot the moment a second org applied. The shared zone instead
+ * gets one rule covering every level-1 org at once, provisioned by
+ * `scripts/shared-ingress.mjs`, not by this planner (#43's own task brief).
+ *
+ * Idempotent on the recorded rule id, like {@link planAccess}: rate limiting
+ * rules are not part of any system's `listResources` (`@wtfalch/providers`
+ * 0.5.0 has no typed reader for them, only its generic `request` escape
+ * hatch -- `executor.ts`'s `CloudflarePort.request` doc comment), so there is
+ * no live resource to diff against here. Planned right after {@link planZone}
+ * so the zone `cloudflareRateLimit` needs to resolve always exists by the
+ * time this step's own action runs.
+ */
+function planRateLimit(org, recordedIds) {
+    if (!(org.hosting.usesDomain || org.site.enabled) || !org.domain)
+        return null;
+    if (recordedIds[resourceKey('cloudflare', 'ratelimit', org.id)])
+        return null;
+    return {
+        action: { system: 'cloudflare', kind: 'ratelimit', key: org.id, desired: {} },
+        step: {
+            description: `rate limit ${org.slug}'s sign-in paths on Cloudflare (free-plan allowance: one rule per zone)`,
+            destroys: false,
+            migrates: false,
+        },
+    };
+}