@wtfalch/foundry 0.33.1 → 0.35.1

package/dist/plan/platform-diff.d.ts

@@ -3,6 +3,8 @@ import { type Plan, type PlanNote, type UnmanagedItem, type VersionChangeItem }
 import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
 import type { LiveResource } from './live.js';
+import { type MailRoute, PLATFORM_MAIL_RELAY_KEY } from './mail-relay.js';
+import type { OwnerFiles, OwnerSignIn, PlatformOwnerInput } from './platform-org.js';
 /**
  * The platform's own diff result, the {@link DeclaredPlatform} counterpart to
  * `diff.ts`'s `PlanDetail` -- everything the same, minus the `orgId` an org's
@@ -184,11 +186,15 @@ export declare const PLATFORM_ARCHON_APPLIED_AUTH_ORG_SCOPE_KEY = "archon_applie
  */
 export declare const PLATFORM_ARCHON_APPLIED_ROLLING_UPDATE_SCOPE_KEY = "archon_applied_rolling_update";
 /**
- * The sign-in org Archon accepts: the platform owner company's own
- * ({@link PLATFORM_OWNER_ORG_SCOPE_KEY}), else the platform's `foundry` org for
- * a platform with no owner company declared. Undefined when neither is recorded.
+ * The owner company's sign-in hostname Archon was last registered under, and
+ * the owner's files host (`<internalUrl>|<audience>`, or `none`) its env was
+ * last written with. `planArchon` plans the step again when either differs
+ * from the owner's current ones (a marker never recorded reads as `none`).
  */
-export declare function archonAuthOrganizationId(recorded: Readonly<Record<string, string>>): string | undefined;
+export declare const PLATFORM_ARCHON_APPLIED_AUTH_HOSTNAME_SCOPE_KEY = "archon_applied_auth_hostname";
+export declare const PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY = "archon_applied_files";
+/** The value {@link PLATFORM_ARCHON_APPLIED_FILES_SCOPE_KEY} records for the owner's files host. */
+export declare function archonFilesMarker(files: OwnerFiles | null | undefined): string;
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
  * (Access app rebuild), cleared to '' once the real ingress is written back.
@@ -432,6 +438,18 @@ export declare const PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY = "mail_applied_git
  * no key and creates nothing in the sign-in server.
  */
 export declare const PLATFORM_MAIL_ROUTE_SCOPE_KEY = "mail_route_applied";
+/**
+ * The host ports the platform Stalwart publishes, as the mapping string the
+ * last apply set on its app. Without the shared relay it binds SMTP port 25
+ * itself; with `mail.relay` it keeps only submission, because the relay owns
+ * port 25. A missing record means the mapping it was created with, `25:25,...`.
+ */
+export declare const PLATFORM_MAIL_HOST_PORTS_SCOPE_KEY = "mail_host_ports_applied";
+export declare const PLATFORM_MAIL_HOST_PORTS_DIRECT = "25:25,465:465,587:587";
+export declare const PLATFORM_MAIL_HOST_PORTS_RELAY = "465:465,587:587";
+export declare function platformMailHostPorts(platform: DeclaredPlatform): string;
+export { PLATFORM_MAIL_RELAY_KEY };
+export { PLATFORM_MAIL_RELAY_ROUTES_SCOPE_KEY, type MailRoute, } from './mail-relay.js';
 export declare const PLATFORM_MAIL_ROUTE_WANTED = "local-first";
 /**
  * #177: where the mail server answers on the Coolify network
@@ -524,8 +542,68 @@ export declare function serviceDbEnvAppliedScopeKey(service: 'chat' | 'calls-ser
  * made again under a new id, is repaired once.
  */
 export declare function zitadelAppIdTokenUserinfoAppliedScopeKey(appKey: string): string;
-/** The ZITADEL app id of Archon's sign-in client in the platform's own ZITADEL. */
+/**
+ * Archon's own sign-in organisation, in the owner company's ZITADEL instance
+ * and apart from the organisation that holds the company's people (and Boule's
+ * sign-in). Made by the `zitadel:archon-org` step, which runs before
+ * `platform:archon`. The first six keys below are the step's own progress:
+ * each is recorded only after its call succeeded.
+ */
+export declare const PLATFORM_ARCHON_ORG_SCOPE_KEY = "zitadel_platform_archon_org";
+/** The primary domain registered on Archon's sign-in organisation. */
+export declare const PLATFORM_ARCHON_ORG_DOMAIN_SCOPE_KEY = "zitadel_platform_archon_org_domain";
+/** The domain the sign-in server refused to make primary; set instead of failing, reported as blocked. */
+export declare const PLATFORM_ARCHON_ORG_DOMAIN_BLOCKED_SCOPE_KEY = "zitadel_platform_archon_org_domain_blocked";
+/** The Archon org id once self-registration is closed on it. */
+export declare const PLATFORM_ARCHON_ORG_REGISTRATION_CLOSED_SCOPE_KEY = "zitadel_platform_archon_org_registration_closed";
+/** The Archon org id once its login policy forces a second factor. */
+export declare const PLATFORM_ARCHON_ORG_POLICY_SCOPE_KEY = "zitadel_platform_archon_org_policy";
+/** The first person's user id in the Archon org (`none` when no owner is declared), recorded once the invite was mailed. */
+export declare const PLATFORM_ARCHON_OWNER_INVITE_SCOPE_KEY = "zitadel_platform_archon_owner_invite";
+/** The Archon org the recorded invite was made in. */
+export declare const PLATFORM_ARCHON_OWNER_INVITE_ORG_SCOPE_KEY = "zitadel_platform_archon_owner_invite_org";
+/** The name of the Archon sign-in organisation: `<owner slug>-archon`. */
+export declare function archonOrgName(ownerSlug: string): string;
+/** The primary domain of the Archon sign-in organisation: `archon.` before the owner's own sign-in domain. */
+export declare function archonOrgDomain(ownerSignInDomain: string): string;
+/**
+ * The CI organisation id the last Archon apply wrote as `CI_ORGANIZATION_ID`,
+ * and the `ARCHON_FIRST_OWNER_LINK` value it wrote (empty when none).
+ * `planArchon` plans the step again when either differs from what is wanted.
+ */
+export declare const PLATFORM_ARCHON_APPLIED_CI_ORG_SCOPE_KEY = "archon_applied_ci_org";
+export declare const PLATFORM_ARCHON_APPLIED_FIRST_OWNER_LINK_SCOPE_KEY = "archon_applied_first_owner_link";
+/**
+ * `<archonUserId>:<ciUserId>`: the first person in both organisations, which
+ * Archon seeds its link table from. Empty when either id is not known (no
+ * owner declared, or the CI-side account not recorded yet).
+ */
+export declare function archonFirstOwnerLink(recordedIds: Readonly<Record<string, string>>, ownerSignIn: OwnerSignIn | null): string;
+/**
+ * The one-time-PIN provider id the Archon Access app was last made with.
+ * Drift is read against it, because a plan must not ask edge to find or make
+ * the provider.
+ */
+export declare const PLATFORM_ARCHON_ACCESS_PIN_SCOPE_KEY = "cloudflare_platform_archon_access_pin";
+/**
+ * The Archon org the `AUTH_APP_KEY` in Archon's env was minted for. A key
+ * minted for another org (the CI org, before the move) is replaced by a fresh
+ * one, so the key the CI-org broker entry held stops being Archon's.
+ */
+export declare const PLATFORM_ARCHON_APP_KEY_ORG_SCOPE_KEY = "archon_app_key_org";
+/**
+ * `<org>|<project>|<app>` of Archon's old sign-in client while it still waits
+ * to be deleted. Set before the new client's ids overwrite the recorded ones,
+ * cleared once the old client is gone.
+ */
+export declare const PLATFORM_ARCHON_RETIRED_CLIENT_SCOPE_KEY = "zitadel_platform_archon_retired_client";
+/** The ZITADEL app id of Archon's sign-in client in the owner company's ZITADEL. */
 export declare const PLATFORM_ARCHON_ZITADEL_APP_SCOPE_KEY = "zitadel_platform_archon_app";
+/** The ZITADEL project id Archon's sign-in client lives in. */
+export declare const PLATFORM_ARCHON_ZITADEL_PROJECT_SCOPE_KEY = "zitadel_platform_archon_project";
+/** The ZITADEL project and client ids of the Access sign-in provider, in the owner company's ZITADEL. */
+export declare const PLATFORM_ACCESS_ZITADEL_PROJECT_SCOPE_KEY = "zitadel_platform_access_project";
+export declare const PLATFORM_ACCESS_ZITADEL_APP_SCOPE_KEY = "zitadel_platform_access_app";
 /**
  * The ZITADEL app id of Archon's sign-in client once "user info inside the
  * ID token" was switched on for it. `planArchonIdTokenUserinfo` plans the
@@ -574,9 +652,8 @@ export declare function appDomainsAppliedScopeKey(entryKey: string): string;
  * unknown, bare before 4b2380f and `https://` after it.
  */
 export declare function appliedAppDomains(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, entryKey: string): string[];
-/** Whether the secret sources can be filled right now: the mail key is held, and a new shared secret can be held. */
+/** Whether the secret sources can be filled right now: a new shared secret can be held. */
 export interface AppSecretAvailability {
-    platformMailKey: boolean;
     sharedSecret: boolean;
 }
 /**
@@ -595,7 +672,7 @@ export declare function resolveAppEnv(org: DeclaredOrg, entry: HostingEntry, rec
     unresolved: Array<[string, string]>;
     secrets: Array<{
         name: string;
-        source: 'platformMailKey' | EnvSharedSecret;
+        source: EnvSharedSecret;
     }>;
     unresolvedSecrets: Array<[string, string]>;
     marker: Record<string, string>;
@@ -614,6 +691,13 @@ export declare const PLATFORM_AI_KEY = "platform:ai";
  * public hostname. Holds whichever way the public-hostname decision goes.
  */
 export declare const PLATFORM_AI_INTERNAL_URL_SCOPE_KEY = "ai_platform_internal_url";
+/**
+ * The id of the tunnel that carries the AI host's public hostname. Recorded once the tunnel, its
+ * connector and the DNS record are in place; an entry is given `AI_URL` only after it.
+ */
+export declare const PLATFORM_AI_TUNNEL_SCOPE_KEY = "cloudflare_platform_ai_tunnel";
+/** The one Coolify app that runs `cloudflared` for the AI tunnel. */
+export declare const PLATFORM_AI_CONNECTOR_APP_SCOPE_KEY = "coolify_platform_ai_connector_app";
 /**
  * #172: the same two-key discipline as the ZITADEL admin key above, for
  * foundry's AI management key (the bearer key `ai:organisation`, `ai:budget`
@@ -820,6 +904,18 @@ export declare const PLATFORM_HC_APPLIED_GIT_REF_SCOPE_KEY = "hc_applied_git_ref
  * and that implementation is where the key is actually used.
  */
 export declare const PLATFORM_HC_API_KEY_REF = "hc:platform:apiKey";
+/**
+ * foundry#544: the held-key ref a human puts the *outside* Healthchecks
+ * account's project API key under, read only while
+ * `platform.heartbeatsProvider` is `'hosted'` -- {@link PLATFORM_HC_API_KEY_REF}'s
+ * own ref is for the self-hosted instance only, and the two are never
+ * conflated: switching provider needs its own key held under its own ref,
+ * never the other one silently reused. Same "this package never reads the
+ * value back" rule as {@link PLATFORM_HC_API_KEY_REF}'s own doc comment --
+ * whoever implements {@link HeartbeatsPort} against the outside service is
+ * the host.
+ */
+export declare const PLATFORM_HEARTBEATS_HOSTED_API_KEY_REF = "heartbeats:platform:hostedApiKey";
 /**
  * #540: the heartbeat check named after the uptime Worker (foundry#542,
  * which is what actually pings it -- blocked today on edge#26, so nothing
@@ -971,8 +1067,19 @@ export interface PlanPlatformOptions {
      * only when the recorded fingerprint differs; absent, it always plans it.
      */
     callsOrgSlugs?: readonly string[];
+    /**
+     * Which company domain goes to which company mail server. Used only when
+     * `platform.mail.relay` is true (default `[]`).
+     */
+    mailRoutes?: readonly MailRoute[];
+    /** One line per company route left out of `mailRoutes`; each is reported blocked and the relay still plans without it. */
+    mailRoutesBlocked?: readonly string[];
+    /** The owner company's own sign-in and files host; Archon and the Access provider read them (default: neither applied). */
+    owner?: PlatformOwnerInput;
     /** The platform's recorded resource/scope ids (default `{}`). */
     recordedIds?: Readonly<Record<string, string>>;
+    /** The commit each recorded app runs now, by app name; a differing one gives a `build-drift:<name>` note (default `{}`). */
+    liveBuilds?: Readonly<Record<string, string>>;
     /** Per-step block reasons the executor reports (default `{}`). */
     blocked?: {
         auth?: string;
@@ -1000,10 +1107,14 @@ export interface PlanPlatformOptions {
         ai?: string;
         archon?: string;
         mail?: string;
+        /** Why the shared mail relay cannot run: the executor lacks the mail dependencies or the base image tag floats. */
+        relay?: string;
         /** #478: why the edge host is blocked, or absent when it is not. */
         edge?: string;
         /** #604: why the Access sign-in provider cannot be made yet (no dependencies, or edge cannot confirm Access is ready), or absent. */
         accessProvider?: string;
+        /** Why the shared oikos.host ingress cannot be made (no dependencies, or its zone is not on edge's account), or absent. */
+        oikosIngress?: string;
         /**
          * #257: true once a service's database exists but the host built the
          * platform executor with no backup dependencies -- every such service's
@@ -1067,6 +1178,10 @@ export interface PlanPlatformOptions {
          * step is not planned.
          */
         authSignInPolicy?: boolean;
+        /** Why Archon's own sign-in organisation cannot be made (no dependencies, no ZITADEL client for the instance), or absent. */
+        archonOrg?: string;
+        /** Why the first person cannot be invited into Archon's organisation yet (no work address, no mail port). The rest of the step still plans. */
+        archonOrgInvite?: string;
     };
     /**
      * Steps whose live state differs from the declared one in a way the recorded
@@ -1161,11 +1276,8 @@ export declare const JOBS_INTERNAL_URL_SCOPE_KEY = "jobs_internal_url";
  * never a wrong step.
  */
 export declare const PLATFORM_BACKUP_DATABASE_SCOPE_KEYS: {
-    readonly jobs: "coolify_jobs_database";
-    readonly auth: "coolify_platform_auth_database";
     readonly archon: "coolify_platform_archon_database";
     readonly ai: "coolify_platform_ai_database";
-    readonly files: "coolify_platform_files_database";
     readonly integrations: "coolify_integrations_database";
 };
 export type PlatformBackupServiceKey = keyof typeof PLATFORM_BACKUP_DATABASE_SCOPE_KEYS;
@@ -1237,3 +1349,35 @@ export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY = "in
  * `''`) as soon as the mint is recorded, so one request is one rotation.
  */
 export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY = "integrations_management_key_rotation_requested";
+/**
+ * #175: Archon (https://github.com/wtfalch/archon), the one shared console,
+ * built fresh at `platform.archon.hostname` (`archon.<apex>`) rather than the
+ * hand-deployed `operator` app it replaces (#165). One step,
+ * `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, covers the app, its
+ * database, its Cloudflare tunnel, Access app and DNS record, and its sign-in
+ * client in the platform's own ZITADEL -- the same bundling {@link planAuth}
+ * does, for the same reason.
+ *
+ * Idempotent on the recorded resource id plus the applied hostname and
+ * `gitRef`, for the reason {@link planAuth} gives: no platform reader reports
+ * these resources, so a live check would replan the step forever. A changed
+ * hostname or `gitRef` plans the step again, and so does `drifted` (the Access
+ * policy's include list is not the declared one). A re-run mints nothing.
+ *
+ * Blocked, not planned, while the platform's sign-in is neither recorded nor
+ * planned in this same plan: Archon's sign-in client is created inside it, so
+ * the step could only throw.
+ *
+ * #213: also puts {@link PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF},
+ * {@link PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF} and
+ * {@link PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF} as held keys, before
+ * the app deploys -- `putArchonMasterKeys` in `platform-providers.ts`.
+ *
+ * #197: a recorded app with no recorded `cloudflared` connector
+ * ({@link PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY}) plans the step again, as
+ * {@link planAuth} does.
+ */
+/** Archon signs its operators in through the owner company's own sign-in; fixed text, part of the stale-plan comparison. */
+export declare const ARCHON_OWNER_SIGN_IN_BLOCKED = "Archon is blocked, not planned: the owner company's sign-in is not applied yet";
+/** Archon signs in from its own organisation, which the `zitadel:archon-org` step makes; fixed text, part of the stale-plan comparison. */
+export declare const ARCHON_ORG_BLOCKED = "Archon is blocked, not planned: its own sign-in organisation is not applied yet";