@wtfalch/foundry 0.33.1 → 0.35.1

package/dist/plan/mail-relay.js

@@ -0,0 +1,400 @@
+import { createHash } from 'node:crypto';
+import { pinnedRef } from '../bootstrap/versions.js';
+import { waitForDeploymentFinished } from './deploy-health.js';
+import { commandHealthCheckSettings, tcpProbe } from './health-check-settings.js';
+/**
+ * The shared mail relay: one Postfix container that owns host port 25 and
+ * hands each message to the mail server that serves its recipient's domain,
+ * on the Docker network. One server address has one inbound mail port, so a
+ * company's own mail server cannot bind it; this container does, for all.
+ *
+ * It is a platform step (`coolify:app` keyed {@link PLATFORM_MAIL_RELAY_KEY}),
+ * planned only when `platform.mail.relay` is true. It mints no secret.
+ * Everything it knows reaches the container as env the step writes.
+ */
+export const PLATFORM_MAIL_RELAY_KEY = 'platform:mail-relay';
+/** Fingerprint of the sorted routes the last successful apply put live. */
+export const PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY = 'mail_relay_routes_applied';
+/**
+ * Fingerprint of what forces an image rebuild (the Dockerfile text, which holds
+ * the base image pin) and the spool volume the last successful apply put live.
+ * A routes change leaves it alone, so it restarts the container and rebuilds nothing.
+ */
+export const PLATFORM_MAIL_RELAY_BUILD_SCOPE_KEY = 'mail_relay_build_applied';
+/** Postfix's queue. On a volume, so mail not yet handed on survives a restart and a rebuild. */
+export const MAIL_RELAY_SPOOL_DIR = '/var/spool/postfix';
+export const MAIL_RELAY_SPOOL_VOLUME = 'platform-mail-relay-spool';
+/**
+ * The org-applied-state key the company mail step records its server's SMTP address under: `<server address>:<port>`,
+ * the port the company's Stalwart publishes on the server for the relay ({@link OWN_MAIL_SMTP_PORT_SCOPE_KEY}).
+ * The relay is on the platform's network and a company's mail server on the company's own, so the relay
+ * reaches it through the server, not by its container name.
+ */
+export const OWN_MAIL_SMTP_INTERNAL_SCOPE_KEY = 'mail_smtp_internal';
+/** The host port a company's Stalwart publishes (mapped to its port 25) for the relay. */
+export const OWN_MAIL_SMTP_PORT_SCOPE_KEY = 'mail_smtp_port';
+/** The host ports companies' mail servers take, one each: the lowest free one in this range. */
+export const OWN_MAIL_SMTP_PORT_BASE = 25000;
+export const OWN_MAIL_SMTP_PORT_MAX = 25999;
+/** Whether `port` is one of the ports a company's mail server may publish. */
+export function isOwnMailSmtpPort(port) {
+    return (typeof port === 'number' &&
+        Number.isInteger(port) &&
+        port >= OWN_MAIL_SMTP_PORT_BASE &&
+        port <= OWN_MAIL_SMTP_PORT_MAX);
+}
+/** `executor.ts`'s `isRunningOrStarting`, restated: importing it would make this module and the planner import each other. */
+function isRunningOrStarting(status) {
+    if (!status)
+        return true;
+    return !status.startsWith('exited') && !status.startsWith('stopped');
+}
+export const MAIL_RELAY_APP_NAME = 'platform-mail-relay';
+const LABEL = '[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?';
+const DOMAIN_PATTERN = new RegExp(`^(${LABEL}\\.)+[a-z]{2,63}$`);
+const HOST_PATTERN = new RegExp(`^${LABEL}(\\.${LABEL})*$`);
+/** Lower-cases and checks a recipient domain; `null` for anything that is not a plain DNS name. */
+export function normalizeMailDomain(domain) {
+    const lower = domain.toLowerCase();
+    return lower.length <= 253 && DOMAIN_PATTERN.test(lower) ? lower : null;
+}
+/** Lower-cases and checks `<host>:<port>`; `null` for whitespace, metacharacters, a port outside 1..65535 or no host. */
+export function normalizeMailTarget(target) {
+    const lower = target.toLowerCase();
+    const colon = lower.lastIndexOf(':');
+    if (colon < 1)
+        return null;
+    const host = lower.slice(0, colon);
+    const port = lower.slice(colon + 1);
+    if (!/^[1-9][0-9]{0,4}$/.test(port) || Number(port) > 65535)
+        return null;
+    return host.length <= 253 && HOST_PATTERN.test(host) ? lower : null;
+}
+/**
+ * The routes, checked and sorted by domain. `null` when any entry is invalid or
+ * one domain has two targets (a message could not know where to go).
+ */
+export function normalizeMailRoutes(routes) {
+    const byDomain = new Map();
+    for (const route of routes) {
+        const domain = normalizeMailDomain(route.domain);
+        const target = normalizeMailTarget(route.target);
+        if (!domain || !target)
+            return null;
+        const existing = byDomain.get(domain);
+        if (existing !== undefined && existing !== target)
+            return null;
+        byDomain.set(domain, target);
+    }
+    return [...byDomain.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([domain, target]) => ({ domain, target }));
+}
+/**
+ * What the relay was last built to do, as one value. Order of the inputs does
+ * not matter; a changed target or a new route does.
+ * Never empty, so a platform with no company route still records one.
+ */
+export function mailRelayFingerprint(routes) {
+    const sortedRoutes = normalizeMailRoutes(routes) ?? [];
+    return createHash('sha256')
+        .update(JSON.stringify(sortedRoutes.map((r) => [r.domain, r.target])))
+        .digest('hex');
+}
+/**
+ * The relay's container start script. It renders Postfix's config from env
+ * only and refuses to start on a value that is not a plain domain or host, so
+ * nothing from env reaches a config line unchecked. The relay accepts mail for
+ * the listed domains and nothing else (`reject_unauth_destination`), so it
+ * cannot be used to send to a third party.
+ *
+ * Mail for a domain no company routes is refused: there is no platform mail
+ * server to fall back on, so no default target exists.
+ *
+ * Env: `MAIL_RELAY_HOSTNAME`, `MAIL_RELAY_ROUTES` (`domain=host:port`, comma
+ * separated). `MAIL_RELAY_RENDER_ONLY=1` writes the files and stops, and
+ * `MAIL_RELAY_CONF_DIR` moves them; both are for tests.
+ */
+export const MAIL_RELAY_ENTRYPOINT = `#!/bin/sh
+set -eu
+set -f
+conf="\${MAIL_RELAY_CONF_DIR:-/etc/postfix}"
+fail() { echo "mail relay: $1" >&2; exit 1; }
+ok_name() {
+  case "$1" in
+    ''|*[!a-z0-9.-]*|.*|*.|*..*|-*|*.-*|*-.*) return 1 ;;
+  esac
+  return 0
+}
+ok_domain() { ok_name "$1" && case "$1" in *.*) return 0 ;; esac; return 1; }
+ok_target() {
+  h="\${1%:*}"
+  p="\${1##*:}"
+  [ "$h" != "$1" ] || return 1
+  case "$p" in ''|0*|*[!0-9]*) return 1 ;; esac
+  [ "\${#p}" -le 5 ] || return 1
+  [ "$p" -le 65535 ] || return 1
+  ok_name "$h"
+}
+ok_name "\${MAIL_RELAY_HOSTNAME:-}" || fail "MAIL_RELAY_HOSTNAME is not a host name"
+: > "$conf/relay_domains"
+: > "$conf/transport"
+IFS=','
+for entry in \${MAIL_RELAY_ROUTES:-}; do
+  d="\${entry%%=*}"
+  t="\${entry#*=}"
+  ok_domain "$d" || fail "a route domain is not a plain domain"
+  ok_target "$t" || fail "a route target is not <host>:<port>"
+  printf '%s OK\\n' "$d" >> "$conf/relay_domains"
+  printf '%s smtp:[%s]:%s\\n' "$d" "\${t%:*}" "\${t##*:}" >> "$conf/transport"
+done
+unset IFS
+cat > "$conf/main.cf" <<CONF
+myhostname = $MAIL_RELAY_HOSTNAME
+myorigin = \\$myhostname
+inet_interfaces = all
+inet_protocols = ipv4
+mydestination =
+mynetworks = 127.0.0.0/8
+local_recipient_maps =
+alias_maps =
+alias_database =
+relay_domains = texthash:$conf/relay_domains
+parent_domain_matches_subdomains =
+transport_maps = texthash:$conf/transport
+relay_recipient_maps =
+smtpd_relay_restrictions = reject_unauth_destination
+smtpd_recipient_restrictions = reject_unauth_destination
+disable_vrfy_command = yes
+maillog_file = /dev/stdout
+CONF
+[ "\${MAIL_RELAY_RENDER_ONLY:-}" = "1" ] && exit 0
+exec postfix start-fg
+`;
+/** The inline Dockerfile Coolify builds. The start script travels base64-encoded so no quoting can alter it. */
+export function mailRelayDockerfile() {
+    const script = Buffer.from(MAIL_RELAY_ENTRYPOINT, 'utf8').toString('base64');
+    return [
+        `FROM alpine:${pinnedRef('alpine')}`,
+        `RUN apk add --no-cache postfix && echo ${script} | base64 -d > /entrypoint.sh && chmod +x /entrypoint.sh`,
+        'EXPOSE 25',
+        'ENTRYPOINT ["/entrypoint.sh"]',
+        '',
+    ].join('\n');
+}
+/** What a rebuild depends on: the Dockerfile and the spool mount. Routes, domains and hostname are not in it. */
+export function mailRelayBuildFingerprint() {
+    return createHash('sha256')
+        .update(JSON.stringify([mailRelayDockerfile(), MAIL_RELAY_SPOOL_DIR]))
+        .digest('hex');
+}
+/** The env the step writes; the only input the container reads. */
+export function mailRelayEnv(input) {
+    return [
+        { key: 'MAIL_RELAY_HOSTNAME', value: input.hostname },
+        {
+            key: 'MAIL_RELAY_ROUTES',
+            value: input.routes.map((r) => `${r.domain}=${r.target}`).join(','),
+        },
+    ].map((e) => ({ ...e, literal: true }));
+}
+export const MAIL_RELAY_BLOCKED = {
+    executorMissing: "the platform's mail relay is blocked, not planned: the host built the platform executor without its mail dependencies",
+    invalidRoutes: "the platform's mail relay is blocked, not planned: a mail route is not valid (a domain must be a plain DNS name, a target must be <host>:25, one domain needs one target)",
+};
+/**
+ * Plans the relay: nothing unless `mail.relay` is true. Planned when it was
+ * never applied, when the fingerprint of its routes differs from the recorded
+ * one, or when the base image pin changed. Blocked (reported, not planned) while
+ * the platform mail server is not applied, the executor cannot run it, or an
+ * input is invalid.
+ */
+export function planMailRelay(platform, recordedIds, input) {
+    if (platform.mail.relay !== true)
+        return { step: null, blocked: null };
+    if (input.executorBlocked)
+        return { step: null, blocked: input.executorBlocked };
+    const routes = normalizeMailRoutes(input.routes);
+    if (!routes)
+        return { step: null, blocked: MAIL_RELAY_BLOCKED.invalidRoutes };
+    const fingerprint = mailRelayFingerprint(routes);
+    const applied = Boolean(recordedIds[`coolify:app:${PLATFORM_MAIL_RELAY_KEY}`]);
+    if (applied &&
+        recordedIds[PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY] === fingerprint &&
+        recordedIds[PLATFORM_MAIL_RELAY_BUILD_SCOPE_KEY] === mailRelayBuildFingerprint()) {
+        return { step: null, blocked: null };
+    }
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'app',
+                key: PLATFORM_MAIL_RELAY_KEY,
+                desired: { routes, fingerprint },
+            },
+            step: {
+                description: applied
+                    ? `redeploy the shared mail relay with ${routes.length} company route${routes.length === 1 ? '' : 's'}`
+                    : `provision the shared mail relay on port 25 with ${routes.length} company route${routes.length === 1 ? '' : 's'}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: null,
+    };
+}
+/**
+ * Makes the relay true: finds or creates the app, sets its internal name and
+ * host port 25, mounts the queue volume once, writes env, and then does the
+ * least that makes it true (decided from the live app):
+ * - a rebuild (stop, deploy) when the app was just created, the Dockerfile or
+ *   volume changed, or the volume was just added. The old container is stopped
+ *   first, because two containers cannot both bind port 25;
+ * - a deploy when the container is not running;
+ * - a restart of the same container when only the routes, domains or hostname
+ *   changed. Postfix reads its routes at start, nothing else is needed.
+ * The two fingerprints are recorded last, so a run that fails halfway (env
+ * written, restart failed) leaves the step planned and the next apply
+ * finishes it. No secret exists here.
+ */
+export async function provisionMailRelay(action, context, deps, input) {
+    const routes = normalizeMailRoutes((action.desired.routes ?? []));
+    if (!routes) {
+        throw new Error('platform:mail-relay: a mail route is invalid');
+    }
+    const runtime = deps.runtime ?? {};
+    const sleep = runtime.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const recorded = context.recordedIds();
+    const record = async (key, id) => {
+        context.recordScopeId(key, id);
+        await context.persist?.();
+    };
+    const { environment } = await deps.coolify.findOrCreateEnvironment(input.projectUuid, 'production');
+    const existing = await deps.coolify.findApplicationByName(MAIL_RELAY_APP_NAME, {
+        environmentIds: [environment.id],
+    });
+    let appId;
+    let running = false;
+    const justCreated = !existing;
+    if (existing) {
+        appId = existing.uuid;
+        running = isRunningOrStarting((await deps.coolify.getApplication(appId)).status);
+    }
+    else {
+        appId = (await deps.coolify.createDockerfileApplication({
+            project_uuid: input.projectUuid,
+            server_uuid: input.serverUuid,
+            environment_name: environment.name,
+            environment_uuid: environment.uuid,
+            dockerfile: mailRelayDockerfile(),
+            name: MAIL_RELAY_APP_NAME,
+            description: 'Postfix relay that owns host port 25 and routes by recipient domain',
+            instant_deploy: false,
+        })).uuid;
+    }
+    await record(input.appScopeKey, appId);
+    const buildFingerprint = mailRelayBuildFingerprint();
+    const routesFingerprint = mailRelayFingerprint(routes);
+    const spoolMounted = (await deps.coolify.listStorages(appId)).persistent_storages?.some((s) => s.mount_path === MAIL_RELAY_SPOOL_DIR);
+    if (!spoolMounted) {
+        await deps.coolify.createPersistentStorage(appId, {
+            name: MAIL_RELAY_SPOOL_VOLUME,
+            mount_path: MAIL_RELAY_SPOOL_DIR,
+        });
+    }
+    // A volume added to an app that already exists binds only at a new container, so it is a rebuild too.
+    const baseChanged = !justCreated &&
+        (recorded[PLATFORM_MAIL_RELAY_BUILD_SCOPE_KEY] !== buildFingerprint || !spoolMounted);
+    await deps.coolify.updateApplication(appId, {
+        custom_internal_name: MAIL_RELAY_APP_NAME,
+        ports_exposes: '25',
+        ports_mappings: '25:25',
+        // Postfix has no HTTP: a connect to port 25 on the loopback is the check.
+        ...commandHealthCheckSettings(tcpProbe('25')),
+        ...(baseChanged
+            ? { dockerfile: Buffer.from(mailRelayDockerfile(), 'utf8').toString('base64') }
+            : {}),
+    });
+    const envs = mailRelayEnv({
+        hostname: input.hostname,
+        routes,
+    });
+    const live = new Map((await deps.coolify.listEnvs(appId)).filter((e) => !e.is_preview).map((e) => [e.key, e.value]));
+    const envsChanged = envs.some((e) => live.get(e.key) !== e.value);
+    await deps.coolify.bulkUpsertEnvs(appId, envs);
+    // The recorded routes fingerprint, not only the env diff: env written by a run whose restart failed
+    // reads as unchanged on the next apply, and the routes would never go live.
+    const routesChanged = envsChanged || recorded[PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY] !== routesFingerprint;
+    const rebuild = async (stopFirst) => {
+        if (stopFirst) {
+            await deps.coolify.raw('POST', `/applications/${appId}/stop`);
+            await waitForStopped(deps.coolify, appId, runtime, sleep);
+        }
+        await waitForDeploymentFinished(deps.coolify, appId, runtime, 'platform:mail-relay', 'the relay keeps its previous routes');
+    };
+    if (justCreated || !running || baseChanged) {
+        await rebuild(!justCreated && running);
+    }
+    else if (routesChanged) {
+        // A restart that names no deployment cannot be told from the old container still being healthy.
+        const followed = await restartAndWaitHealthy(deps.coolify, appId, runtime, sleep);
+        if (!followed)
+            await rebuild(true);
+    }
+    await record(PLATFORM_MAIL_RELAY_BUILD_SCOPE_KEY, buildFingerprint);
+    await record(PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, routesFingerprint);
+    return { resourceId: appId };
+}
+async function waitForStopped(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (!status || !isRunningOrStarting(status))
+            return;
+        if (now() >= deadline) {
+            throw new Error(`platform:mail-relay: the relay app ${appId} did not stop within ${Math.round(timeout / 1000)}s; apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/**
+ * Restarts the same container (no stop, no image build) and returns once it is
+ * healthy again. Coolify queues a restart and answers before the container
+ * moves, so the old container's healthy status alone proves nothing: the
+ * answer must name a deployment and that record must finish first. Returns
+ * false, having waited for nothing, when the answer names none.
+ */
+async function restartAndWaitHealthy(coolify, appId, runtime, sleep) {
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? 300_000;
+    const interval = runtime.readyIntervalMs ?? 5_000;
+    const deadline = now() + timeout;
+    const late = (what) => new Error(`platform:mail-relay: the relay app ${appId} did not ${what} within ${Math.round(timeout / 1000)}s after its restart; the relay keeps its previous routes. Apply again`);
+    const answer = (await coolify.restart(appId));
+    const deploymentUuid = typeof answer?.deployment_uuid === 'string' ? answer.deployment_uuid : undefined;
+    // No deployment to follow: health would be the old container's, so the caller rebuilds instead.
+    if (!deploymentUuid)
+        return false;
+    for (;;) {
+        const { status } = await coolify.getDeployment(deploymentUuid);
+        if (status === 'finished')
+            break;
+        if (status === 'failed' || status.startsWith('cancelled')) {
+            throw new Error(`platform:mail-relay: the restart (${deploymentUuid}) of ${appId} did not finish (status: ${status}); the relay keeps its previous routes. Apply again`);
+        }
+        if (now() >= deadline)
+            throw late('finish restarting');
+        await sleep(interval);
+    }
+    for (;;) {
+        const { status } = await coolify.getApplication(appId);
+        if (status?.includes('healthy') && !status.includes('unhealthy'))
+            return true;
+        if (now() >= deadline)
+            throw late('become healthy');
+        await sleep(interval);
+    }
+}

package/dist/plan/network-move.d.ts

@@ -0,0 +1,20 @@
+import type { DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * Recorded when a company's Coolify resources are known to sit on its own network (`co-<slug>`): by the
+ * first run for a company that has none yet, and by the move step when it ends. The value is the network name.
+ */
+export declare const NETWORK_APPLIED_SCOPE_KEY = "network_applied";
+/** A company with a Coolify project but no network marker was built on the shared network. */
+export declare function networkMoveNeeded(recordedIds: Readonly<Record<string, string>>): boolean;
+/** Whether the company holds a resource foundry adopted: it did not create it and never deletes it. */
+export declare function hasAdoptedResources(recordedIds: Readonly<Record<string, string>>): boolean;
+/**
+ * The one step a company built on the shared network plans, instead of all its others. Coolify cannot
+ * move a resource between networks in production, so the move deletes the company's apps and databases and
+ * the next apply builds them again on `co-<slug>`. It destroys and migrates, so apply asks for the typed
+ * company name, and it needs a fresh dump of every database first (`requireFreshBackupsForMove`). A company
+ * that adopted resources plans no move: foundry does not delete what it did not create, so those stay on
+ * the shared network (`diff.ts` reports it).
+ */
+export declare function planNetworkMove(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>): DraftStep | null;

package/dist/plan/network-move.js

@@ -0,0 +1,41 @@
+/**
+ * Recorded when a company's Coolify resources are known to sit on its own network (`co-<slug>`): by the
+ * first run for a company that has none yet, and by the move step when it ends. The value is the network name.
+ */
+export const NETWORK_APPLIED_SCOPE_KEY = 'network_applied';
+/** The company's Coolify project: where `ensureCoolifyProject` records it. */
+const COOLIFY_PROJECT_SCOPE_KEY = 'coolify_project';
+/** A company with a Coolify project but no network marker was built on the shared network. */
+export function networkMoveNeeded(recordedIds) {
+    return Boolean(recordedIds[COOLIFY_PROJECT_SCOPE_KEY]) && !recordedIds[NETWORK_APPLIED_SCOPE_KEY];
+}
+/** Whether the company holds a resource foundry adopted: it did not create it and never deletes it. */
+export function hasAdoptedResources(recordedIds) {
+    return Object.keys(recordedIds).some((key) => key.startsWith('adopted.'));
+}
+/**
+ * The one step a company built on the shared network plans, instead of all its others. Coolify cannot
+ * move a resource between networks in production, so the move deletes the company's apps and databases and
+ * the next apply builds them again on `co-<slug>`. It destroys and migrates, so apply asks for the typed
+ * company name, and it needs a fresh dump of every database first (`requireFreshBackupsForMove`). A company
+ * that adopted resources plans no move: foundry does not delete what it did not create, so those stay on
+ * the shared network (`diff.ts` reports it).
+ */
+export function planNetworkMove(org, recordedIds) {
+    if (!networkMoveNeeded(recordedIds) || hasAdoptedResources(recordedIds))
+        return null;
+    const network = `co-${org.slug}`;
+    return {
+        action: {
+            system: 'coolify',
+            kind: 'network',
+            key: org.id,
+            desired: { network },
+        },
+        step: {
+            description: `move ${org.slug} onto its own Docker network ${network}: delete its apps and databases in Coolify after a fresh backup, then apply again to build them there (data is restored by hand)`,
+            destroys: true,
+            migrates: true,
+        },
+    };
+}

package/dist/plan/oikos-ingress.d.ts

@@ -0,0 +1,111 @@
+import type { DeclaredPlatform } from '../platform.js';
+import type { DraftStep } from './diff.js';
+import type { DnsPort } from './edge-dns.js';
+import type { RateLimitPort, RateLimitRuleInput } from './edge-ratelimits.js';
+import type { TunnelIngress, TunnelPort } from './edge-tunnels.js';
+import type { ZonePort } from './edge-zones.js';
+import type { CoolifyPort } from './executor.js';
+import type { PlatformStepExecutionContext } from './plan-apply.js';
+/**
+ * The shared `oikos.host` ingress: one Cloudflare tunnel, its connector app on
+ * Coolify, one proxied wildcard record `*.oikos.host` and one zone-wide rate
+ * limiting rule for the sign-in paths. Every company without a domain of its
+ * own is reached through it, so a fresh platform needs it before such a company
+ * can be planned. It is the platform step that `scripts/shared-ingress.mjs`
+ * used to be run by hand for. The script keeps its own copy of the rate limit
+ * constants (it runs outside this package) and a test here keeps them equal.
+ *
+ * The three names below are found by name, and the tunnel's whole ingress is
+ * replaced. They differ from the script's (`oikos-shared`) on purpose: a hand-made
+ * project or tunnel of that name may carry other traffic, and this step must only
+ * ever find its own.
+ *
+ * One `coolify:app` step keyed {@link PLATFORM_OIKOS_INGRESS_KEY}. Its applied
+ * id (the connector app) is recorded by the runner only when the whole step
+ * returns, so a run that fails halfway is planned again and finds what it made
+ * by name.
+ */
+export declare const PLATFORM_OIKOS_INGRESS_KEY = "platform:oikos-ingress";
+export declare const OIKOS_INGRESS_ZONE = "oikos.host";
+export declare const OIKOS_INGRESS_TUNNEL_NAME = "platform-oikos-ingress";
+export declare const OIKOS_INGRESS_WILDCARD = "*.oikos.host";
+export declare const OIKOS_INGRESS_CONNECTOR_APP_NAME = "platform-oikos-ingress-cloudflared";
+export declare const OIKOS_INGRESS_PROJECT = "platform-oikos-ingress";
+export declare const OIKOS_INGRESS_ENVIRONMENT = "production";
+/** Bookkeeping of what the last run finished; none of these is the applied marker. */
+export declare const OIKOS_INGRESS_PROJECT_SCOPE_KEY = "oikos_ingress_project";
+export declare const OIKOS_INGRESS_TUNNEL_SCOPE_KEY = "oikos_ingress_tunnel";
+export declare const OIKOS_INGRESS_CONNECTOR_APP_SCOPE_KEY = "oikos_ingress_connector_app";
+export declare const OIKOS_INGRESS_DNS_SCOPE_KEY = "oikos_ingress_dns";
+export declare const OIKOS_INGRESS_RATELIMIT_SCOPE_KEY = "oikos_ingress_ratelimit";
+/** True once the step has finished: the readiness a company without a domain waits for. */
+export declare function oikosIngressApplied(recordedIds: Readonly<Record<string, string>>): boolean;
+/** Fixed texts. None carries a provider's error. */
+export declare const OIKOS_INGRESS_BLOCKED: {
+    readonly edgeNotApplied: "the shared oikos.host ingress is blocked, not planned: every DNS record and tunnel is written through edge, and edge is not applied yet";
+    readonly zoneMissing: "the shared oikos.host ingress is blocked, not planned: the oikos.host zone is not on the Cloudflare account the platform's edge reaches; add the zone to that account";
+    readonly zoneUnchecked: "the shared oikos.host ingress is blocked, not planned: the oikos.host zone could not be looked up through edge just now; apply again";
+    readonly executorMissing: "the shared oikos.host ingress is blocked, not planned: the host built the platform executor without its oikos ingress dependencies";
+};
+/**
+ * The step, or the reason it cannot be planned. Nothing when the platform has
+ * no edge (it could not write a record) or the step is already applied.
+ * `edgeApplied` is whether edge has recorded its address.
+ */
+export declare function planOikosIngress(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>, input: {
+    edgeApplied: boolean;
+    executorBlocked?: string;
+}): {
+    step: DraftStep | null;
+    blocked: string | null;
+};
+/** The tunnel's ingress: the wildcard to Coolify's proxy, then the mandatory catch-all. */
+export declare function oikosIngressTunnelIngress(): TunnelIngress[];
+/** What the wildcard record needs: nothing, a create, or an update. */
+export declare function planWildcardRecord(live: {
+    content: string;
+    proxied?: boolean;
+} | undefined, tunnelId: string): 'exists' | 'create' | 'update';
+export declare const OIKOS_INGRESS_RATE_LIMIT_DESCRIPTION = "foundry: rate limit sign-in paths (oikos.host, shared)";
+/** The Free plan allows one rule per zone, with only "Path" in the expression, a 10 second period and IP counting. */
+export declare const OIKOS_INGRESS_RATE_LIMIT_PERIOD_SECONDS = 10;
+export declare const OIKOS_INGRESS_RATE_LIMIT_REQUESTS = 10;
+export declare const OIKOS_INGRESS_SIGN_IN_EXPRESSION = "starts_with(http.request.uri.path, \"/auth/\")";
+export declare function oikosIngressRateLimitRule(): RateLimitRuleInput;
+/** Ours is there, nothing is there, or a rule that is not ours holds the zone's one Free-plan slot. */
+export declare function planOikosRateLimit(rules: ReadonlyArray<{
+    id: string;
+    description: string | null;
+}>): {
+    status: 'exists';
+    ruleId: string;
+} | {
+    status: 'create' | 'conflict';
+    ruleId: null;
+};
+export interface OikosIngressPorts {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'findApplicationByName' | 'getApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy'>;
+    tunnels: Pick<TunnelPort, 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken'>;
+    dns: Pick<DnsPort, 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'>;
+    ratelimits: RateLimitPort;
+    zones: Pick<ZonePort, 'findZoneByApex'>;
+    resolveServer: () => Promise<{
+        uuid: string;
+    }>;
+    /** One outside call's limit in milliseconds; 60 s by default. The connector step gets five times it. */
+    callTimeoutMs?: number;
+}
+/**
+ * Why the step cannot be planned for want of its zone, or `null` when the zone
+ * is on the account edge reaches. The texts are fixed; a lookup error is never carried.
+ */
+export declare function oikosIngressZoneBlocked(zones: Pick<ZonePort, 'findZoneByApex'>, callTimeoutMs?: number): Promise<string | null>;
+/**
+ * Makes the ingress, in this order: tunnel, its ingress, the connector app, the
+ * wildcard record, the rate limit rule. Each is found by name or content before
+ * it is made, so a second run makes nothing twice. Returns the connector app id,
+ * which the runner records as the step's applied marker only on success.
+ */
+export declare function provisionOikosIngress(context: Pick<PlatformStepExecutionContext, 'recordedIds' | 'recordScopeId' | 'persist'>, ports: OikosIngressPorts): Promise<{
+    resourceId: string;
+}>;