@wtfalch/foundry 0.34.0 → 0.35.1

package/dist/plan/proxy-labels.d.ts

@@ -8,22 +8,55 @@ export interface EntryLabelSpec {
     wildcardDomain: string | null;
     port: number;
 }
+/**
+ * The label every routed container carries, with the install's token as its value. Traefik is told
+ * (`--providers.docker.constraints=Label(`foundry.edge`,`<token>`)`) to route only containers that carry
+ * it, so a route an image declares in its own `LABEL`s, which cannot know the token, is ignored.
+ */
+export declare const EDGE_LABEL = "foundry.edge";
 /**
  * The scope key holding the hash of the label set last patched onto an
  * entry's app. Present only for an entry that has had a custom label set.
  */
 export declare function appLabelsAppliedScopeKey(entryKey: string): string;
+/** The entry routes ({@link entryRoutesMarker}) the company tunnel's ingress was last written with. */
+export declare const CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY = "cloudflare_tunnel_entry_routes";
+/**
+ * The entry names in the platform's oikos.host zone ({@link entryOikosHostnames}) the company tunnel's records were
+ * last written for, comma-joined. Recorded only once every record is in place.
+ */
+export declare const CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY = "cloudflare_tunnel_oikos_hostnames";
+/**
+ * The run label every customer hosting-entry container gets. A run label overrides the image's own
+ * `LABEL` of the same key, so Traefik ignores the container whatever its image says: a customer image
+ * cannot route a hostname it does not own. The company's tunnel reaches the container directly
+ * ({@link entryRoutes}); no Traefik router and no Coolify `domains` are involved.
+ */
+export declare const ENTRY_CONTAINER_LABELS = "traefik.enable=false";
+/**
+ * What an entry's routing is built from: the names it is served at, the wildcard domain when it
+ * declares `'*'`, and the port its container listens on. Every entry has one, because every entry
+ * carries {@link ENTRY_CONTAINER_LABELS}. Coolify's default port for an app is 80.
+ */
+export declare function entryLabelSpec(org: DeclaredOrg, entry: HostingEntry): EntryLabelSpec;
+/**
+ * The company tunnel's ingress for the hosting entries: each name, and the wildcard last, goes straight to
+ * `http://<container name>:<port>` on the company network, never through `coolify-proxy`. A wildcard
+ * entry gets a wildcard hostname rule; the first entry that declares `'*'` owns it, and the first entry
+ * that declares a name owns it. An entry with no name (internal) has no rule. This holds for a company
+ * without a domain too: its `<slug>.oikos.host` name is routed by the company's own tunnel
+ * ({@link entryOikosHostnames}), not by the platform's shared ingress.
+ */
+export declare function entryRoutes(org: DeclaredOrg): Array<{
+    hostname: string;
+    service: string;
+}>;
+/** The scope value recording the routes the tunnel step last wrote; the planner compares it to {@link entryRoutes}. */
+export declare function entryRoutesMarker(org: DeclaredOrg): string;
 /**
- * The label set an entry's app needs, or `null` when it needs none. Coolify
- * replaces the labels it generates from `domains` once `custom_labels` is
- * set, so an entry with `'*'` carries its exact `Host` rules as well. An entry
- * that already has a custom set (`hadLabels`) keeps one, without the wildcard
- * rule, so a removed `'*'` stops matching and a later name change still
- * reaches the app: an empty `custom_labels` is refused by Coolify's API.
- * Coolify's default port for an app is 80.
+ * A short digest of the spec; the same spec always gives the same hash. The token is left out: the
+ * planner has none, and a changed token reaches a live app through the comparison of its live labels.
  */
-export declare function entryLabelSpec(org: DeclaredOrg, entry: HostingEntry, hadLabels: boolean): EntryLabelSpec | null;
-/** A short digest of the spec; the same spec always gives the same hash. */
 export declare function entryLabelHash(spec: EntryLabelSpec): string;
 /**
  * The Traefik labels for an entry's app, one per line. Coolify reaches an app
@@ -32,11 +65,24 @@ export declare function entryLabelHash(spec: EntryLabelSpec): string;
  * `Host(name) && PathPrefix(/)`, default priority. The wildcard is one
  * `HostRegexp` router at `priority=1`, so any exact name, this app's or
  * another's, wins over it. The regex matches one label (`[a-z0-9-]+`), the
- * same depth Cloudflare's Universal certificate covers.
+ * same depth Cloudflare's Universal certificate covers. A set that routes
+ * anything carries {@link EDGE_LABEL}; the "no route" set does not need it.
  */
-export declare function entryProxyLabels(appUuid: string, spec: EntryLabelSpec): string;
+export declare function entryProxyLabels(appUuid: string, spec: EntryLabelSpec, token: string): string;
+/** Whether a label set routes something but does not carry the token: Traefik would ignore it once the constraint is on. */
+export declare function routesWithoutToken(labels: string, token: string): boolean;
 /**
  * Whether two label sets hold the same labels. Order and the `coolify.*`
  * lines Coolify adds and strips itself do not count.
  */
 export declare function sameLabelSets(a: string, b: string): boolean;
+/**
+ * The entry names that live in the platform's `oikos.host` zone (a company with no domain of its own, or with
+ * `usesDomain` off): the names the company's tunnel gets a proxied CNAME for. Sorted.
+ */
+export declare function entryOikosHostnames(org: DeclaredOrg): string[];
+/**
+ * Whether `name` is one the company may write in the platform's `oikos.host` zone: exactly its own
+ * `<slug>.oikos.host`. A company writes no other company's name, whatever an entry declares.
+ */
+export declare function ownsOikosName(org: DeclaredOrg, name: string): boolean;

package/dist/plan/proxy-labels.js

@@ -1,5 +1,19 @@
 import { createHash } from 'node:crypto';
 import { entryHostnames, wildcardHostname } from './hostnames.js';
+import { NO_DOMAIN_ZONE } from './own-hostnames.js';
+import { appNameFor } from './platform-diff.js';
+/**
+ * The label every routed container carries, with the install's token as its value. Traefik is told
+ * (`--providers.docker.constraints=Label(`foundry.edge`,`<token>`)`) to route only containers that carry
+ * it, so a route an image declares in its own `LABEL`s, which cannot know the token, is ignored.
+ */
+export const EDGE_LABEL = 'foundry.edge';
+/** The token is a base64url string; anything else would not survive a label line or Traefik's constraint syntax. */
+const TOKEN_SHAPE = /^[A-Za-z0-9_-]{32,128}$/;
+function checkToken(token) {
+    if (!TOKEN_SHAPE.test(token))
+        throw new Error('proxy labels: the label token is malformed');
+}
 /**
  * The scope key holding the hash of the label set last patched onto an
  * entry's app. Present only for an entry that has had a custom label set.
@@ -7,26 +21,68 @@ import { entryHostnames, wildcardHostname } from './hostnames.js';
 export function appLabelsAppliedScopeKey(entryKey) {
     return `app_labels_applied.${entryKey}`;
 }
+/** The entry routes ({@link entryRoutesMarker}) the company tunnel's ingress was last written with. */
+export const CLOUDFLARE_TUNNEL_ENTRY_ROUTES_SCOPE_KEY = 'cloudflare_tunnel_entry_routes';
 /**
- * The label set an entry's app needs, or `null` when it needs none. Coolify
- * replaces the labels it generates from `domains` once `custom_labels` is
- * set, so an entry with `'*'` carries its exact `Host` rules as well. An entry
- * that already has a custom set (`hadLabels`) keeps one, without the wildcard
- * rule, so a removed `'*'` stops matching and a later name change still
- * reaches the app: an empty `custom_labels` is refused by Coolify's API.
- * Coolify's default port for an app is 80.
+ * The entry names in the platform's oikos.host zone ({@link entryOikosHostnames}) the company tunnel's records were
+ * last written for, comma-joined. Recorded only once every record is in place.
  */
-export function entryLabelSpec(org, entry, hadLabels) {
+export const CLOUDFLARE_TUNNEL_OIKOS_HOSTNAMES_SCOPE_KEY = 'cloudflare_tunnel_oikos_hostnames';
+/**
+ * The run label every customer hosting-entry container gets. A run label overrides the image's own
+ * `LABEL` of the same key, so Traefik ignores the container whatever its image says: a customer image
+ * cannot route a hostname it does not own. The company's tunnel reaches the container directly
+ * ({@link entryRoutes}); no Traefik router and no Coolify `domains` are involved.
+ */
+export const ENTRY_CONTAINER_LABELS = 'traefik.enable=false';
+/**
+ * What an entry's routing is built from: the names it is served at, the wildcard domain when it
+ * declares `'*'`, and the port its container listens on. Every entry has one, because every entry
+ * carries {@link ENTRY_CONTAINER_LABELS}. Coolify's default port for an app is 80.
+ */
+export function entryLabelSpec(org, entry) {
     const wildcard = entry.hostnames.includes('*') ? wildcardHostname(org) : null;
-    if (!wildcard && !hadLabels)
-        return null;
     return {
         names: entryHostnames(org, entry),
         wildcardDomain: wildcard ? wildcard.slice(2) : null,
         port: entry.buildPack === 'static' ? 80 : (entry.port ?? 80),
     };
 }
-/** A short digest of the spec; the same spec always gives the same hash. */
+/**
+ * The company tunnel's ingress for the hosting entries: each name, and the wildcard last, goes straight to
+ * `http://<container name>:<port>` on the company network, never through `coolify-proxy`. A wildcard
+ * entry gets a wildcard hostname rule; the first entry that declares `'*'` owns it, and the first entry
+ * that declares a name owns it. An entry with no name (internal) has no rule. This holds for a company
+ * without a domain too: its `<slug>.oikos.host` name is routed by the company's own tunnel
+ * ({@link entryOikosHostnames}), not by the platform's shared ingress.
+ */
+export function entryRoutes(org) {
+    if (!org.hosting.enabled)
+        return [];
+    const routes = [];
+    let wildcard;
+    for (const entry of org.hosting.entries) {
+        const service = `http://${appNameFor(org, entry)}:${entryLabelSpec(org, entry).port}`;
+        for (const hostname of entryHostnames(org, entry)) {
+            if (!routes.some((r) => r.hostname === hostname))
+                routes.push({ hostname, service });
+        }
+        const wildcardName = entry.hostnames.includes('*') ? wildcardHostname(org) : null;
+        if (wildcardName && !wildcard)
+            wildcard = { hostname: wildcardName, service };
+    }
+    if (wildcard)
+        routes.push(wildcard);
+    return routes;
+}
+/** The scope value recording the routes the tunnel step last wrote; the planner compares it to {@link entryRoutes}. */
+export function entryRoutesMarker(org) {
+    return JSON.stringify(entryRoutes(org));
+}
+/**
+ * A short digest of the spec; the same spec always gives the same hash. The token is left out: the
+ * planner has none, and a changed token reaches a live app through the comparison of its live labels.
+ */
 export function entryLabelHash(spec) {
     return createHash('sha256').update(JSON.stringify(spec)).digest('hex').slice(0, 16);
 }
@@ -37,9 +93,11 @@ export function entryLabelHash(spec) {
  * `Host(name) && PathPrefix(/)`, default priority. The wildcard is one
  * `HostRegexp` router at `priority=1`, so any exact name, this app's or
  * another's, wins over it. The regex matches one label (`[a-z0-9-]+`), the
- * same depth Cloudflare's Universal certificate covers.
+ * same depth Cloudflare's Universal certificate covers. A set that routes
+ * anything carries {@link EDGE_LABEL}; the "no route" set does not need it.
  */
-export function entryProxyLabels(appUuid, spec) {
+export function entryProxyLabels(appUuid, spec, token) {
+    checkToken(token);
     const labels = [];
     const route = (id, rule, priority) => {
         const router = `traefik.http.routers.${id}`;
@@ -56,9 +114,14 @@ export function entryProxyLabels(appUuid, spec) {
     }
     if (labels.length === 0)
         return 'traefik.enable=false';
-    labels.push('traefik.enable=true', 'traefik.http.middlewares.gzip.compress=true');
+    labels.push('traefik.enable=true', 'traefik.http.middlewares.gzip.compress=true', `${EDGE_LABEL}=${token}`);
     return labels.sort().join('\n');
 }
+/** Whether a label set routes something but does not carry the token: Traefik would ignore it once the constraint is on. */
+export function routesWithoutToken(labels, token) {
+    const lines = labels.split(/\r\n|\n|\r/);
+    return lines.includes('traefik.enable=true') && !lines.includes(`${EDGE_LABEL}=${token}`);
+}
 /**
  * Whether two label sets hold the same labels. Order and the `coolify.*`
  * lines Coolify adds and strips itself do not count.
@@ -71,3 +134,20 @@ export function sameLabelSets(a, b) {
         .join('\n');
     return lines(a) === lines(b);
 }
+/**
+ * The entry names that live in the platform's `oikos.host` zone (a company with no domain of its own, or with
+ * `usesDomain` off): the names the company's tunnel gets a proxied CNAME for. Sorted.
+ */
+export function entryOikosHostnames(org) {
+    return entryRoutes(org)
+        .map((r) => r.hostname)
+        .filter((h) => h.endsWith(`.${NO_DOMAIN_ZONE}`))
+        .sort();
+}
+/**
+ * Whether `name` is one the company may write in the platform's `oikos.host` zone: exactly its own
+ * `<slug>.oikos.host`. A company writes no other company's name, whatever an entry declares.
+ */
+export function ownsOikosName(org, name) {
+    return name.toLowerCase() === `${org.slug}.${NO_DOMAIN_ZONE}`;
+}

package/dist/plan/run-options.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Linux capabilities of every container foundry makes through an application call, sent in
+ * Coolify's `custom_docker_run_options`. Coolify turns `--cap-drop`, `--cap-add` and `--security-opt`
+ * into compose keys; its parser reads a value up to the first dash, so `no-new-privileges:true` is
+ * not sent. A Coolify database has no such field and keeps Docker's defaults.
+ */
+/** What no foundry service needs: raw sockets, device nodes, file capabilities, chroot, audit writes. */
+export declare const CAPS_TIER_A: readonly string[];
+/** A customer's own app: nothing, then back what nginx, node and `gosu` style entrypoints need. */
+export declare const CAPS_TIER_B: readonly string[];
+export type CapabilityTier = 'A' | 'B';
+/**
+ * `existing` with its capability options replaced by the tier's. Everything else in it (the
+ * `--entrypoint "..."`) stays as it was, so a step that sends its own entrypoint and the capability
+ * wrapper can both write the field. Running it twice gives the same string.
+ */
+export declare function withCapabilities(existing: string | null | undefined, tier: CapabilityTier): string;
+/** Whether `existing` holds exactly the tier's capability options. */
+export declare function hasCapabilities(existing: string | null | undefined, tier: CapabilityTier): boolean;

package/dist/plan/run-options.js

@@ -0,0 +1,46 @@
+/**
+ * The Linux capabilities of every container foundry makes through an application call, sent in
+ * Coolify's `custom_docker_run_options`. Coolify turns `--cap-drop`, `--cap-add` and `--security-opt`
+ * into compose keys; its parser reads a value up to the first dash, so `no-new-privileges:true` is
+ * not sent. A Coolify database has no such field and keeps Docker's defaults.
+ */
+/** What no foundry service needs: raw sockets, device nodes, file capabilities, chroot, audit writes. */
+export const CAPS_TIER_A = [
+    '--cap-drop=NET_RAW',
+    '--cap-drop=MKNOD',
+    '--cap-drop=SETFCAP',
+    '--cap-drop=SYS_CHROOT',
+    '--cap-drop=AUDIT_WRITE',
+];
+/** A customer's own app: nothing, then back what nginx, node and `gosu` style entrypoints need. */
+export const CAPS_TIER_B = [
+    '--cap-drop=ALL',
+    '--cap-add=CHOWN',
+    '--cap-add=DAC_OVERRIDE',
+    '--cap-add=FOWNER',
+    '--cap-add=SETGID',
+    '--cap-add=SETUID',
+    '--cap-add=NET_BIND_SERVICE',
+];
+const tokens = (tier) => tier === 'B' ? CAPS_TIER_B : CAPS_TIER_A;
+/** One `--cap-drop` or `--cap-add` option, with the space or equals sign and its value. */
+const CAP_OPTION = /\s*--cap-(?:drop|add)(?:=|\s+)\S+/g;
+/** The cap options of a run options string, in the order they stand. */
+function capOptionsOf(options) {
+    return (options ?? '').match(CAP_OPTION)?.map((o) => o.trim().replace(/\s+/, '=')) ?? [];
+}
+/**
+ * `existing` with its capability options replaced by the tier's. Everything else in it (the
+ * `--entrypoint "..."`) stays as it was, so a step that sends its own entrypoint and the capability
+ * wrapper can both write the field. Running it twice gives the same string.
+ */
+export function withCapabilities(existing, tier) {
+    const rest = (existing ?? '').replace(CAP_OPTION, '').trim();
+    return [rest, ...tokens(tier)].filter(Boolean).join(' ');
+}
+/** Whether `existing` holds exactly the tier's capability options. */
+export function hasCapabilities(existing, tier) {
+    const have = capOptionsOf(existing);
+    const want = tokens(tier);
+    return have.length === want.length && want.every((t) => have.includes(t));
+}

package/dist/plan/zitadel-login-policy.d.ts

@@ -20,4 +20,4 @@ export interface ZitadelLoginPolicyOptions {
  * policy (POST), so a later change to the default cannot turn registration
  * back on. A custom policy keeps its own factors and IdPs (PUT).
  */
-export declare function createZitadelLoginPolicy(options: ZitadelLoginPolicyOptions): Pick<ZitadelPort, 'closeSelfRegistration'>;
+export declare function createZitadelLoginPolicy(options: ZitadelLoginPolicyOptions): Pick<ZitadelPort, 'closeSelfRegistration' | 'enforceSecondFactor'>;

package/dist/plan/zitadel-login-policy.js

@@ -20,6 +20,21 @@ const LOGIN_POLICY_SETTINGS = [
     'forceMfaLocalOnly',
 ];
 const CALL_TIMEOUT_MS = 30_000;
+/** What {@link ZitadelPort.enforceSecondFactor} sets. The two lists are exact: any other factor (email or SMS code) is removed. */
+const SECOND_FACTOR_SETTINGS = {
+    forceMfa: true,
+    allowRegister: false,
+    allowExternalIdp: false,
+    allowUsernamePassword: true,
+    passwordlessType: 'PASSWORDLESS_TYPE_ALLOWED',
+    mfaInitSkipLifetime: '0s',
+};
+const SECOND_FACTORS = ['SECOND_FACTOR_TYPE_OTP', 'SECOND_FACTOR_TYPE_U2F'];
+const MULTI_FACTORS = ['MULTI_FACTOR_TYPE_U2F_WITH_VERIFICATION'];
+/** ZITADEL leaves false booleans and zero durations out of a read. */
+const isZeroDuration = (value) => value === undefined || (typeof value === 'string' && /^0+(\.0+)?s$/.test(value));
+const stringList = (value) => Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+const sameSet = (a, b) => a.length === b.length && b.every((v) => a.includes(v));
 /**
  * The real {@link ZitadelPort.closeSelfRegistration}: the mirror of
  * `ZitadelClient.allowSelfRegistration` in `@wtfalch/providers`, with
@@ -35,8 +50,7 @@ const CALL_TIMEOUT_MS = 30_000;
  */
 export function createZitadelLoginPolicy(options) {
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
-    async function call(method, orgId, body) {
-        const path = '/management/v1/policies/login';
+    async function call(method, orgId, body, path = '/management/v1/policies/login') {
         const response = await fetchImpl(`${options.url}${path}`, {
             method,
             signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
@@ -67,7 +81,66 @@ export function createZitadelLoginPolicy(options) {
         }
         return data;
     }
+    /** Every setting of the policy in force, as the write bodies take them. */
+    const settingsOf = (policy) => {
+        const settings = {};
+        for (const key of LOGIN_POLICY_SETTINGS) {
+            if (policy[key] !== undefined)
+                settings[key] = policy[key];
+        }
+        return settings;
+    };
     return {
+        async enforceSecondFactor(orgId) {
+            if (!orgId)
+                throw new Error('enforceSecondFactor: orgId is required');
+            const data = await call('GET', orgId, undefined);
+            const policy = data.policy ?? {};
+            const isDefault = data.isDefault === true || policy.isDefault === true;
+            const secondFactors = stringList(policy.secondFactors);
+            const multiFactors = stringList(policy.multiFactors);
+            const want = SECOND_FACTOR_SETTINGS;
+            const settingsDiffer = (policy.forceMfa === true) !== want.forceMfa ||
+                (policy.allowRegister === true) !== want.allowRegister ||
+                (policy.allowExternalIdp === true) !== want.allowExternalIdp ||
+                (policy.allowUsernamePassword === true) !== want.allowUsernamePassword ||
+                policy.passwordlessType !== want.passwordlessType ||
+                !isZeroDuration(policy.mfaInitSkipLifetime);
+            const factorsDiffer = !sameSet(secondFactors, SECOND_FACTORS) || !sameSet(multiFactors, MULTI_FACTORS);
+            if (!isDefault && !settingsDiffer && !factorsDiffer)
+                return { changed: false };
+            const settings = { ...settingsOf(policy), ...want };
+            if (isDefault) {
+                // The org's own policy, written whole: the factor lists go in the same body.
+                await call('POST', orgId, {
+                    ...settings,
+                    secondFactors: SECOND_FACTORS,
+                    multiFactors: MULTI_FACTORS,
+                    idps: (policy.idps ?? []).map((idp) => ({
+                        idpId: idp.idpId,
+                        ownerType: 'IDP_OWNER_TYPE_SYSTEM',
+                    })),
+                });
+                return { changed: true };
+            }
+            if (settingsDiffer)
+                await call('PUT', orgId, settings);
+            // Add before remove, so the org is never left with no second factor.
+            const factorPath = '/management/v1/policies/login';
+            for (const type of SECOND_FACTORS.filter((t) => !secondFactors.includes(t))) {
+                await call('POST', orgId, { type }, `${factorPath}/second_factors`);
+            }
+            for (const type of MULTI_FACTORS.filter((t) => !multiFactors.includes(t))) {
+                await call('POST', orgId, { type }, `${factorPath}/multi_factors`);
+            }
+            for (const type of secondFactors.filter((t) => !SECOND_FACTORS.includes(t))) {
+                await call('DELETE', orgId, undefined, `${factorPath}/second_factors/${encodeURIComponent(type)}`);
+            }
+            for (const type of multiFactors.filter((t) => !MULTI_FACTORS.includes(t))) {
+                await call('DELETE', orgId, undefined, `${factorPath}/multi_factors/${encodeURIComponent(type)}`);
+            }
+            return { changed: true };
+        },
         async closeSelfRegistration(orgId) {
             if (!orgId)
                 throw new Error('closeSelfRegistration: orgId is required');
@@ -77,12 +150,7 @@ export function createZitadelLoginPolicy(options) {
             if (!isDefault && policy.allowRegister !== true) {
                 return { changed: false };
             }
-            const settings = {};
-            for (const key of LOGIN_POLICY_SETTINGS) {
-                if (policy[key] !== undefined)
-                    settings[key] = policy[key];
-            }
-            settings.allowRegister = false;
+            const settings = { ...settingsOf(policy), allowRegister: false };
             if (isDefault) {
                 await call('POST', orgId, {
                     ...settings,

package/dist/platform.d.ts

@@ -121,13 +121,44 @@ export interface DeclaredPlatform {
     coolify: PlatformService;
     /** foundry#542: the outside prober Worker; see {@link PlatformUptimeWorker}. */
     uptime: PlatformUptimeWorker;
+    /**
+     * foundry#544: which Healthchecks instance manages the heartbeat checks
+     * for every piece of scheduled work foundry sets up (the uptime Worker,
+     * each platform database backup), decoupled from whether foundry also
+     * deploys the self-hosted server ({@link hc} above). `'self-hosted'`
+     * (the default, and today's only behaviour before #544) still requires
+     * `hc.enabled` and reads the project API key under
+     * `PLATFORM_HC_API_KEY_REF`. `'hosted'` needs no self-hosted server at
+     * all -- not `hc.enabled`, not `hc` applied -- and reads its own API key
+     * under `PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF` instead; the host's own
+     * `HeartbeatsPort` implementation is what actually points at the outside
+     * service (healthchecks.io or otherwise) or the self-hosted instance --
+     * this field only says which one foundry expects behind it. Changing it
+     * re-plans `heartbeats:reconcile`, which creates every desired check
+     * fresh on the newly-chosen provider and delivers its ping URLs; a check
+     * left behind on the provider no longer chosen is not deleted (foundry
+     * never had it in view the moment the switch is declared) -- see
+     * issue #544's own "Human steps". Which to use at all, and whether the
+     * self-hosted server stays as a standing option, are both still open
+     * "Decide" items on issue #544's own thread, not settled by this field.
+     */
+    heartbeatsProvider: HeartbeatsProvider;
 }
+/**
+ * foundry#544: see {@link DeclaredPlatform.heartbeatsProvider}'s own doc
+ * comment.
+ */
+export type HeartbeatsProvider = 'self-hosted' | 'hosted';
+/** The only values {@link DeclaredPlatform.heartbeatsProvider} may hold. */
+export declare const HEARTBEATS_PROVIDERS: ReadonlySet<HeartbeatsProvider>;
 /** `<service>.<apex>` -- the default `hostname` for a platform service, before an operator overrides it. */
 export declare function defaultPlatformHostname(service: PlatformServiceKey, apex: string): string;
 /**
  * `null` when `platform` is valid; otherwise the reason it is not, same
  * shape as `org.ts`'s `validateBuyerIdentity`.
  *
+ * - `auth`, `mail`, `files`, `jobs` and `sfu` are not `enabled`: the owner company
+ *   runs them as its own services.
  * - `apex` is a valid domain (`org.ts`'s `validateDomain`).
  * - `serverIpv4`, when declared, is a dotted-quad IPv4 address.
  * - Every service's `hostname` is the apex itself or a subdomain of it -- a
@@ -137,4 +168,5 @@ export declare function defaultPlatformHostname(service: PlatformServiceKey, ape
  * - Every service's `gitRef` is non-empty once that service is `enabled` --
  *   an enabled service with nothing to deploy is not yet declared.
  */
+export declare const OWNER_RUNS_OWN_SERVICES_REASON = "auth, mail, files, jobs and sfu cannot be enabled on the platform: the owner company runs these as its own services";
 export declare function validatePlatform(platform: DeclaredPlatform): string | null;

package/dist/platform.js

@@ -17,6 +17,11 @@ export const PLATFORM_SERVICE_KEYS = [
     'hc',
     'coolify',
 ];
+/** The only values {@link DeclaredPlatform.heartbeatsProvider} may hold. */
+export const HEARTBEATS_PROVIDERS = new Set([
+    'self-hosted',
+    'hosted',
+]);
 /** `<service>.<apex>` -- the default `hostname` for a platform service, before an operator overrides it. */
 export function defaultPlatformHostname(service, apex) {
     return `${service}.${apex}`;
@@ -28,6 +33,8 @@ function serviceOf(platform, key) {
  * `null` when `platform` is valid; otherwise the reason it is not, same
  * shape as `org.ts`'s `validateBuyerIdentity`.
  *
+ * - `auth`, `mail`, `files`, `jobs` and `sfu` are not `enabled`: the owner company
+ *   runs them as its own services.
  * - `apex` is a valid domain (`org.ts`'s `validateDomain`).
  * - `serverIpv4`, when declared, is a dotted-quad IPv4 address.
  * - Every service's `hostname` is the apex itself or a subdomain of it -- a
@@ -37,7 +44,13 @@ function serviceOf(platform, key) {
  * - Every service's `gitRef` is non-empty once that service is `enabled` --
  *   an enabled service with nothing to deploy is not yet declared.
  */
+export const OWNER_RUNS_OWN_SERVICES_REASON = 'auth, mail, files, jobs and sfu cannot be enabled on the platform: the owner company runs these as its own services';
+/** The platform services the owner company runs as its own, which the platform keeps off. */
+const OWNER_RUN_SERVICE_KEYS = ['auth', 'mail', 'files', 'jobs', 'sfu'];
 export function validatePlatform(platform) {
+    if (OWNER_RUN_SERVICE_KEYS.some((key) => platform[key].enabled)) {
+        return OWNER_RUNS_OWN_SERVICES_REASON;
+    }
     const apexReason = validateDomain(platform.apex);
     if (apexReason)
         return `apex invalid: ${apexReason}`;
@@ -75,5 +88,8 @@ export function validatePlatform(platform) {
     if (platform.mail.lettermintProjectId != null && !platform.mail.lettermintProjectId.trim()) {
         return 'mail.lettermintProjectId must not be empty when set';
     }
+    if (!HEARTBEATS_PROVIDERS.has(platform.heartbeatsProvider)) {
+        return `heartbeatsProvider '${platform.heartbeatsProvider}' must be one of ${[...HEARTBEATS_PROVIDERS].join(', ')}`;
+    }
     return null;
 }

package/dist/provision.d.ts

@@ -10,6 +10,8 @@ export declare const DATABASE_NAME = "foundry";
  * still satisfied with no adapter.
  */
 export interface ProvisionCoolifyPort extends Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'listDatabases' | 'createPostgresDatabase'> {
+    /** With `raw`, the database is created on the platform destination (`plan/destinations.ts`). */
+    raw?: CoolifyPort['raw'];
     listEnvironments(projectUuid: string): Promise<Array<{
         id: number;
         uuid: string;

package/dist/provision.js

@@ -1,3 +1,4 @@
+import { placedOnPlatform } from './plan/destinations.js';
 // #R2 (map gap: foundry's own Postgres, two commands): find-or-create the
 // Postgres database `scripts/foundry-db-provision.mjs` migrates into.
 // Project, environment and database names are fixed here rather than taken
@@ -56,7 +57,8 @@ export async function applyProvision(coolify, plan) {
     // `createPostgresDatabase` also returns `internal_db_url` -- a live
     // credential -- which is deliberately never read off this result: only
     // `uuid` (and the `name` we already know) leaves this function.
-    const created = await coolify.createPostgresDatabase({
+    const creator = placedOnPlatform(coolify);
+    const created = await creator.createPostgresDatabase({
         project_uuid: project.uuid,
         server_uuid: server.uuid,
         environment_name: environment.name,

package/dist/slug.d.ts

@@ -1,11 +1,13 @@
 /** The flattened set {@link validateSlug} checks a candidate slug against. */
 export declare const RESERVED_SLUGS: ReadonlySet<string>;
+/** Every platform app, tunnel, project and database name starts `platform-`, so no company slug may. */
+export declare const RESERVED_SLUG_PREFIX = "platform-";
 /**
  * Why {@link validateSlug} refused a candidate slug, by name so a caller —
  * `store/postgres.ts`'s `DeclaredOrgError`, eventually the operator page —
  * can report it without parsing `message` text.
  */
-export type SlugRejectionReason = 'invalid-label' | 'reserved' | 'environment-suffix';
+export type SlugRejectionReason = 'invalid-label' | 'reserved' | 'environment-suffix' | 'reserved-prefix';
 export interface SlugRejection {
     reason: SlugRejectionReason;
     message: string;

package/dist/slug.js

@@ -105,6 +105,8 @@ export const RESERVED_SLUGS = new Set([
     ...RESERVED_INFRASTRUCTURE_AND_MAIL,
     ...RESERVED_AUTH_AND_ENVIRONMENTS,
 ]);
+/** Every platform app, tunnel, project and database name starts `platform-`, so no company slug may. */
+export const RESERVED_SLUG_PREFIX = 'platform-';
 /**
  * A DNS label: 1-63 characters, lowercase `a-z`, `0-9` and hyphen, no
  * leading or trailing hyphen. Consecutive hyphens are legal DNS (RFC 1035
@@ -136,6 +138,19 @@ const AGORA_SUFFIX = /-agora$/;
  * one that opts in.
  */
 const BOULE_SUFFIX = /-boule$/;
+/** `<something>-auth|-mail|-files|-sfu|-cms` — an own company's service hostnames on oikos.host (`plan/own-hostnames.ts`). */
+const OWN_SERVICE_SUFFIX = /-(auth|mail|files|sfu|cms)$/;
+/**
+ * `names` itself, or `names-<anything>` — foundry names the company tunnel
+ * `${slug}-tunnel` (`plan/executor.ts`), so a slug of `names` or starting
+ * `names-` produces a tunnel name starting `names-`. Edge refuses to create
+ * a platform tunnel whose name starts with `names-` and reads a live
+ * `names-*` tunnel as its own, not a company's (foundry#535; `edge`'s
+ * `packages/service/src/platform-tunnels.ts`). `namesake` is not a near
+ * miss: its tunnel name is `namesake-tunnel`, which does not start with
+ * `names-`.
+ */
+const NAMES_PREFIX = /^names(-|$)/;
 /**
  * Validates a candidate org slug against every rule #28 decided. Returns
  * `null` when the slug is acceptable, or a {@link SlugRejection} naming
@@ -150,20 +165,27 @@ export function validateSlug(slug) {
             message: `slug '${slug}' is not a valid DNS label: must be 1-63 characters, lowercase a-z, 0-9 and hyphen, and may not start or end with a hyphen`,
         };
     }
-    if (RESERVED_SLUGS.has(slug)) {
+    if (RESERVED_SLUGS.has(slug) || slug.startsWith(RESERVED_SLUG_PREFIX)) {
         return {
             reason: 'reserved',
             message: `slug '${slug}' is reserved by the estate (#28) and cannot be taken by an org`,
         };
     }
+    if (NAMES_PREFIX.test(slug)) {
+        return {
+            reason: 'reserved-prefix',
+            message: `slug '${slug}' is 'names' or starts with 'names-', a prefix edge reserves for its own platform tunnels and refuses to create a company tunnel under (#535)`,
+        };
+    }
     if (STAGE_SUFFIX.test(slug) ||
         PR_SUFFIX.test(slug) ||
         CALLS_SUFFIX.test(slug) ||
         AGORA_SUFFIX.test(slug) ||
-        BOULE_SUFFIX.test(slug)) {
+        BOULE_SUFFIX.test(slug) ||
+        OWN_SERVICE_SUFFIX.test(slug)) {
         return {
             reason: 'environment-suffix',
-            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls', '-agora' or '-boule') reserved for another org's own hostname (#28, #145, #164, #161) — 'acme-calls' is only legal as acme's calls hostname, 'acme-agora' only as acme's Agora hostname, 'acme-boule' only as acme's Boule hostname, never as an org slug in its own right`,
+            message: `slug '${slug}' ends with an environment suffix ('-stage', '-pr-<digits>', '-calls', '-agora', '-boule', '-auth', '-mail', '-files', '-sfu' or '-cms') reserved for another org's own hostname (#28, #145, #164, #161) — 'acme-calls' is only legal as acme's calls hostname, 'acme-agora' only as acme's Agora hostname, 'acme-boule' only as acme's Boule hostname, never as an org slug in its own right`,
         };
     }
     return null;