@wtfalch/foundry 0.33.1 → 0.34.0

package/dist/plan/platform-org.js

@@ -1,6 +1,8 @@
+import { ownsServices } from '../org.js';
 import { ACCESS_PROVIDER_RECORD_KEY } from './gates.js';
-import { JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AUTH_KEY, PLATFORM_EDGE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, platformMailMxHost, } from './platform-diff.js';
-import { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+import { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './held-key-refs.js';
+import { OWN_SERVICES_APPLIED_SCOPE_KEY, orgTarget } from './own-services.js';
+import { JOBS_INTERNAL_URL_SCOPE_KEY, JOBS_SCHEDULER_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY, PLATFORM_EDGE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY, platformMailMxHost, } from './platform-diff.js';
 /**
  * #443: the no-domain company mail apex -- `<slug>.oikos.host`, the same
  * fixed suffix `agora.ts`'s `agoraHostnameFor`, `boule.ts`'s
@@ -126,6 +128,7 @@ edgePortPresent = false) {
         // enabled or applied.
         platformApex: platform.apex,
         platformOwnerOrgId: platform.ownerOrgId || null,
+        platformOwnerUserId: platformRecordedIds[PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY] || null,
         platformLettermintProjectId: platform.mail.lettermintProjectId ?? null,
         filesReady: filesApplied && missingKeys.files === null,
         filesUrl: filesApplied
@@ -147,6 +150,95 @@ edgePortPresent = false) {
         ...(noKeyReader ? { noKeyReader } : {}),
     };
 }
+/** The git refs the platform declares for the services an own org deploys. */
+export function serviceGitRefsOf(platform) {
+    return {
+        auth: platform.auth.gitRef,
+        mail: platform.mail.gitRef,
+        files: platform.files.gitRef,
+        jobs: platform.jobs.gitRef,
+    };
+}
+/** The runner app both the platform's and an own org's files step record. */
+export const OWN_FILES_RUNNER_SCOPE_KEY = 'coolify_platform_files_runner_app';
+const OWN_MAIL_APP_SCOPE_KEY = 'coolify_platform_mail_app';
+/** Resource id of an own-service step, in `AppliedState.serviceIds`' `system:kind:key` form. */
+function ownStepRecorded(ids, org, kind) {
+    return Boolean(ids[`coolify:${kind}:${org.id}`]);
+}
+/**
+ * The own org's sign-in is up: applied, so its ZITADEL answers. The broker and the login client
+ * come after the org's first broker entry, as the platform's do after its first registration, so
+ * waiting for them here would wait for the very steps this gate lets run.
+ */
+function ownAuthReady(ids) {
+    return Boolean(ids[OWN_SERVICES_APPLIED_SCOPE_KEY]);
+}
+/**
+ * An own org (`services.own`) plans against its own services, so its readiness
+ * reads only its own recorded ids and its own held keys; nothing the shared
+ * services recorded reaches it. AI, edge and Access stay shared and come from
+ * `base`. Any other org gets `base` back unchanged.
+ */
+export function orgPlatformReadinessFor(org, base, orgRecordedIds, heldRefs) {
+    if (!ownsServices(org))
+        return base;
+    const refs = orgTarget(org).refs;
+    const authReady = ownAuthReady(orgRecordedIds);
+    const filesApplied = ownStepRecorded(orgRecordedIds, org, 'own-files') &&
+        Boolean(orgRecordedIds[OWN_FILES_RUNNER_SCOPE_KEY]);
+    const jobsApplied = ownStepRecorded(orgRecordedIds, org, 'own-jobs');
+    const mailApplied = ownStepRecorded(orgRecordedIds, org, 'own-mail') &&
+        Boolean(orgRecordedIds[OWN_MAIL_APP_SCOPE_KEY]);
+    const filesUrl = orgRecordedIds[PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY];
+    const jobsUrl = orgRecordedIds[JOBS_INTERNAL_URL_SCOPE_KEY];
+    const missing = (applied, ref) => applied && !heldRefs.has(ref) ? ref : null;
+    const missingKeys = {
+        files: missing(filesApplied, refs.filesManagement),
+        ai: base.missingKeys.ai,
+        jobs: missing(jobsApplied, refs.jobsAdminToken),
+    };
+    const { jobsUrlMissing: _shared, ...rest } = base;
+    return {
+        ...rest,
+        authReady,
+        authIssuer: authReady && org.domain ? `https://auth.${org.domain}` : null,
+        filesReady: filesApplied && filesUrl !== undefined && missingKeys.files === null,
+        filesUrl: filesApplied ? (filesUrl ?? null) : null,
+        jobsReady: jobsApplied && jobsUrl !== undefined && missingKeys.jobs === null,
+        ...(jobsApplied && jobsUrl === undefined ? { jobsUrlMissing: true } : {}),
+        callsReady: ownStepRecorded(orgRecordedIds, org, 'own-sfu'),
+        mailHost: mailApplied && org.domain && base.mailHost
+            ? { apex: org.domain, mailHost: base.mailHost.mailHost }
+            : null,
+        missingKeys,
+    };
+}
+/** The own org's held-key refs `heldKeys` resolves right now. A resolver that throws counts as not held, and its error goes nowhere. */
+export async function heldOwnKeyRefs(heldKeys, org) {
+    const held = new Set();
+    for (const ref of Object.values(orgTarget(org).refs)) {
+        try {
+            if (await heldKeys.resolve(ref))
+                held.add(ref);
+        }
+        catch {
+            // not held
+        }
+    }
+    return held;
+}
+/** {@link agoraHostValuesFromPlatform}'s counterpart for an own org: every value is the org's own, null until recorded. */
+export function agoraHostValuesForOwn(org, orgRecordedIds) {
+    const authReady = ownAuthReady(orgRecordedIds);
+    return {
+        issuer: authReady && org.domain ? `https://auth.${org.domain}` : null,
+        mailProjectId: orgRecordedIds[PLATFORM_MAIL_ZITADEL_PROJECT_SCOPE_KEY] ?? null,
+        messagingProjectId: null,
+        mailUpstream: orgRecordedIds[PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY] ?? null,
+        filesUpstream: orgRecordedIds[PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY] ?? null,
+    };
+}
 /**
  * #177: {@link AgoraHostValues} derived from the same platform state, rather
  * than requiring a bespoke host-supplied `AgoraHostPort` for values the

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

@@ -8,12 +8,16 @@ import type { AccessPort } from './edge-access.js';
 import type { DnsPort } from './edge-dns.js';
 import type { TunnelPort } from './edge-tunnels.js';
 import type { CloudflarePort, CoolifyPort, FoundryStepExecutorPorts, ZitadelPort } from './executor.js';
+export { FILES_MANAGEMENT_KEY_REF, JOBS_ADMIN_TOKEN_REF, PLATFORM_AI_MANAGEMENT_KEY_REF, } from './held-key-refs.js';
 import type { LiveResource, PlatformCloudflareReader, PlatformCoolifyReader } from './live.js';
+import { type FilesKeysMinted, type ProjectSource, type ServiceNetwork, type ServiceTarget, type StepScope } from './own-services.js';
 import type { PlatformDriftedSteps, PlatformStepExecutionContext, PlatformStepExecutor } from './plan-apply.js';
 import { type BrokerDeployRecord, PLATFORM_ZITADEL_ORG_SCOPE_KEY } from './platform-diff.js';
 export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 import { type CallsSfuPlatformDeps } from './platform-sfu.js';
 import { type PlatformUptimeDeps } from './uptime-worker.js';
+/** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
+export declare function apexZoneKey(apex: string): string;
 /**
  * #168: everything {@link provisionPlatformAuth} needs beyond
  * {@link PlatformStepExecutionContext} -- a bundle, not more constructor
@@ -28,6 +32,15 @@ import { type PlatformUptimeDeps } from './uptime-worker.js';
  * being the platform key held under {@link PLATFORM_EDGE_KEY_REF}.
  */
 export type PlatformDnsFactory = (edgeUrl: string) => DnsPort | Promise<DnsPort>;
+/**
+ * The DNS port for a platform step: edge's recorded address, never a public
+ * hostname, because auth, mail and archon write their records before any of
+ * those exist. Edge's step runs first and records the address
+ * (`planPlatform`), so a missing one means that step has not finished.
+ */
+export declare function platformDns(deps: {
+    dns: PlatformDnsFactory;
+}, recorded: Readonly<Record<string, string>>, step: string): Promise<DnsPort>;
 /**
  * F4.tunnels: builds the {@link TunnelPort} a platform step creates, configures
  * and reads the connector token of its tunnel through, given the same address
@@ -38,6 +51,10 @@ export type PlatformDnsFactory = (edgeUrl: string) => DnsPort | Promise<DnsPort>
 export type PlatformTunnelsFactory = (edgeUrl: string) => PlatformTunnelPort | Promise<PlatformTunnelPort>;
 /** The tunnel calls a platform step makes; it never deletes one. */
 export type PlatformTunnelPort = Pick<TunnelPort, 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken'>;
+/** The tunnel port for a platform step; same address and same reason as {@link platformDns}. */
+export declare function platformTunnels(deps: {
+    tunnels: PlatformTunnelsFactory;
+}, recorded: Readonly<Record<string, string>>, step: string): Promise<PlatformTunnelPort>;
 /**
  * F4.access: builds the {@link AccessPort} a platform step finds, creates and
  * deletes its Access app through, given the same address as
@@ -105,7 +122,7 @@ export interface PlatformAuthDeps {
      * {@link zitadel}, so the mint always hits the instance this step just
      * built. See `createZitadelAdminMinter` for the mint half.
      */
-    zitadelForInstance?: (issuerUrl: string) => PlatformAuthDeps['zitadel'];
+    zitadelForInstance?: (issuerUrl: string, bearerRef?: string) => PlatformAuthDeps['zitadel'];
     deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
     /**
      * #210: reads back the broker's Lettermint mail key, held under
@@ -133,9 +150,19 @@ export interface PlatformAuthRuntime {
     readyIntervalMs?: number;
     /** Tries at handing the admin key to the host (default 3). */
     deliverAttempts?: number;
+    /** Timeout of each readiness poll request (default 10 seconds). */
+    readyRequestTimeoutMs?: number;
+    /** Told of every secret the sign-in step reads or mints, so the host can scrub it from logs and audit rows. */
+    onSecret?: (value: string) => void;
 }
-/** The ref the scheduler's admin token is delivered under: the host's real `JobsSchedulerPort` adapter reads it back. */
-export declare const JOBS_ADMIN_TOKEN_REF = "jobs:scheduler:adminToken";
+/**
+ * An own org's scheduler only: the app's uuid, recorded and persisted before
+ * the admin token leaves and cleared once the token is delivered and written.
+ * Left set, the planner reports the scheduler blocked and never mints again.
+ */
+export declare const JOBS_ADMIN_TOKEN_UNDELIVERED_SCOPE_KEY = "jobs_admin_token_undelivered";
+/** An own org's scheduler only: the git ref its app last deployed, so a changed declared ref plans the step again. */
+export declare const JOBS_APPLIED_GIT_REF_SCOPE_KEY = "jobs_applied_git_ref";
 /**
  * The narrow slice of {@link CoolifyPort} {@link FoundryPlatformStepExecutor}
  * needs for `coolify:jobs` (#173) -- the same project/environment/server/app/
@@ -143,7 +170,7 @@ export declare const JOBS_ADMIN_TOKEN_REF = "jobs:scheduler:adminToken";
  * org's own app, reused here for the platform's one scheduler instead of once
  * per org.
  */
-type JobsCoolifyPort = Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'getApplication' | 'updateApplication' | 'deployAndWait'>;
+export type JobsCoolifyPort = Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'getApplication' | 'updateApplication' | 'deployAndWait'>;
 /**
  * Options for {@link FoundryPlatformStepExecutor}'s constructor, replacing
  * four positional arguments that shifted on every merge that added a
@@ -330,6 +357,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         edge?: string;
         archon?: string;
         mail?: string;
+        relay?: string;
         accessProvider?: string;
         backupExecutorMissing?: boolean;
         hc?: string;
@@ -386,7 +414,51 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private executeSfu;
     private coolifyJobs;
 }
+export interface JobsHostDeps {
+    coolify: JobsCoolifyPort;
+    /** `FoundryStepExecutorPorts.deliverSecret`'s contract: never returned, recorded, logged or put in an error. */
+    deliverSecret: (ref: string, secret: string) => Promise<void>;
+    /** Reads a delivered secret back from the host. Without it, an org's undelivered marker cannot be resumed. */
+    readSecret?: (ref: string) => Promise<string | null>;
+    runtime: DeployHealthRuntime;
+}
+export interface JobsHostInput {
+    /** The scheduler's public domain; null leaves the app on Coolify's own, for a scheduler only containers reach. */
+    hostname: string | null;
+    gitRef: string;
+    project: ProjectSource;
+}
+/**
+ * Provisions one jobs scheduler (database, app, admin token) for `target`:
+ * the platform's, or an own org's. Every name and the held-key ref come from
+ * the target.
+ *
+ * An org target also guards the mint (`CLAUDE.md`, "Platform steps" rules 1
+ * and 3): the token's id is recorded as undelivered and persisted before the
+ * token leaves, the delivered guard is recorded after the env write, and the
+ * applied git ref is recorded so a changed ref plans the step again. The
+ * platform's step keeps its provision-only behaviour.
+ */
+export declare function provisionJobsHost(scope: StepScope, deps: JobsHostDeps, target: ServiceTarget, input: JobsHostInput): Promise<{
+    resourceId?: string;
+}>;
+/**
+ * Fixed `custom_internal_name`s (`diff.ts`'s `coolifyCalls` sets the same
+ * kind of name on Synapse/MAS) so the Cloudflare tunnel below can address
+ * each app directly, by container name, on the shared Coolify Docker network
+ * -- bypassing Coolify's own Traefik, which dispatches purely by `Host`
+ * header and so cannot give two different apps the same public hostname.
+ */
 export declare const PLATFORM_AUTH_LOGIN_INTERNAL_NAME = "platform-auth-login";
+/**
+ * The inline Dockerfile of the ZITADEL app. The published image is distroless (no shell, no `curl`) and has no
+ * HEALTHCHECK, and Coolify runs its own check as `sh -c`. So the app is a Dockerfile app: the image's own `ready`
+ * command is its exec-form HEALTHCHECK, which Coolify keeps while its own check is off. `ready` asks the port and
+ * TLS mode from the same `ZITADEL_*` settings the server reads. The start period covers the first run, which sets
+ * up the database and the first instance before it listens. The start command is the one
+ * {@link AUTH_ZITADEL_RUN_OPTIONS} names.
+ */
+export declare function zitadelDockerfile(): string;
 export declare const AUTH_LOGIN_PORT = "3000";
 /**
  * Every ZITADEL OIDC/management/console/asset path -- `deploy/proxy/Caddyfile`'s
@@ -396,6 +468,8 @@ export declare const AUTH_LOGIN_PORT = "3000";
  * everything else, including the root).
  */
 export declare const AUTH_ZITADEL_PATH_PATTERN = "^/(oidc|oauth|saml|management|admin|system|auth|assets|debug/healthz|ui/console|\\.well-known|v2|v2beta|zitadel\\.[A-Za-z0-9.]+)(/|$)";
+export declare const PLATFORM_AUTH_ZITADEL_SCOPE_KEY = "coolify_platform_auth_zitadel_app";
+export declare const PLATFORM_AUTH_LOGIN_SCOPE_KEY = "coolify_platform_auth_login_app";
 /**
  * #283: the ref the new instance's IAM_OWNER machine token (a PAT) is
  * delivered under, once. A host reads it back to build `zitadelForInstance`
@@ -412,6 +486,98 @@ export declare const PLATFORM_AUTH_INSTANCE_BEARER_REF = "zitadel:platform:insta
  * (`wtfalch/auth/docs/deploy.md`).
  */
 export declare const PLATFORM_AUTH_BROKER_MAIL_KEY_REF = "lettermint:platform:apiToken";
+/** What {@link provisionAuthStack} reads besides its {@link ServiceTarget}: the platform's values, or one company's. */
+export interface AuthStackInput {
+    hostname: string;
+    apex: string;
+    gitRef: string;
+    project: ProjectSource;
+    network: ServiceNetwork;
+    /** The ZITADEL SMTP sender address. */
+    smtpSender: string;
+    /** Where the login app sends a user with no sign-in request in flight, or null to leave it unset. */
+    defaultRedirectUri: string | null;
+    /** The company whose owner is invited into its own sign-in org; null for a company's own stack. */
+    ownerCompany: DeclaredOrg | null;
+}
+/**
+ * #168: makes `coolify:app` keyed {@link PLATFORM_AUTH_KEY} true -- a Coolify
+ * Postgres, the ZITADEL app itself, the zitadel-login app and (#204) the
+ * sign-in broker, reached through one Cloudflare tunnel and DNS record at
+ * `platform.auth.hostname`, then (only the first time) foundry's own admin
+ * machine user, handed to {@link PlatformAuthDeps.deliverSecret}. Env values
+ * and instance settings are `wtfalch/auth`'s own `docker-compose.yml`
+ * (checked 2026-09-29), with `ZITADEL_DOMAIN`/`companyincluded.com` replaced by this
+ * platform's own `apex`/`auth.hostname` wherever the compose named one --
+ * every other setting it leaves open (login v2 required, external port 443,
+ * TLS terminated at Cloudflare, `PASSWORDCHANGEREQUIRED` false) is kept
+ * exactly as that compose has it (#168's "Decide"). The estate's old, shared
+ * sign-in host carries nothing once this runs (#204, `WTFALCH-DEV-EXIT.md`
+ * row A4).
+ *
+ * Every part is safe to run again after a throw partway: each id is recorded
+ * (and persisted) as soon as its resource exists, each app is named and
+ * deployed on every run that needs it, and the admin key is delivered before
+ * the guard that skips the mint is recorded.
+ *
+ * Three apps, one public hostname, no separate `proxy` app: `wtfalch/auth`
+ * splits ZITADEL's API, its login UI and its broker with a built Caddy proxy
+ * container inside one docker-compose stack; foundry instead gives each app a
+ * fixed `custom_internal_name` and lets the Cloudflare tunnel itself
+ * path-route between them (`AUTH_ZITADEL_PATH_PATTERN`,
+ * `AUTH_BROKER_PATH_PATTERN`), skipping Coolify's own Traefik (which can only
+ * dispatch by `Host`, not by path) rather than provisioning a fourth Coolify
+ * resource to do the same job. No app is created with a Coolify `domains`
+ * binding for the same reason -- the tunnel reaches each one directly by its
+ * `custom_internal_name`, never through Traefik.
+ *
+ * Known gaps, left for review (#168's own "the PR stays open for William's
+ * review"):
+ * - ~~Neither the login app nor the broker ever receives
+ *   `ZITADEL_SERVICE_USER_TOKEN`.~~ Closed by #216 (building on #209/#215):
+ *   this function's own login-client block below mints a dedicated
+ *   `IAM_LOGIN_CLIENT` machine user (never the admin one, which is
+ *   `IAM_OWNER`) and delivers its token to both apps, once the broker's
+ *   other required inputs are already met.
+ * - ~~The broker never receives the earlier mail provider's token either, so it will not
+ *   start on `AUTH_APPS` alone.~~ Closed by #210, once `wtfalch/auth#138`
+ *   moved the broker's account mail onto `@wtfalch/mailer`'s Lettermint
+ *   transport: this function now reads the key back from
+ *   {@link PlatformAuthDeps.heldKeys} under
+ *   {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF} and pushes it as
+ *   `LETTERMINT_API_TOKEN`, once a human (or Archon's own onboarding) has
+ *   put one there. Still a gap until then, the same "blocked, not failing"
+ *   way an unset `AUTH_APPS` already is.
+ * - `AUTH_APPS` starts unset: the broker has nothing to serve until a
+ *   platform app registers with it ({@link provisionPlatformArchon} is the
+ *   first), so it will not start (`parseApps` throws on an empty list) until
+ *   then either. Safe to run again: the next apply that registers an app
+ *   redeploys the broker with a non-empty list.
+ * - ~~Whoever supplies `deps.zitadel` (or `zitadelForInstance`) must hold a
+ *   bearer token for the new instance, which foundry cannot read from it.~~
+ *   Closed by #283: see "The instance bearer" below.
+ *
+ * The instance bearer (#283): the container creates no instance of its own
+ * (`ZITADEL_FIRSTINSTANCE_SKIP`). foundry generates an RSA keypair, puts the
+ * public half in `ZITADEL_SYSTEMAPIUSERS` (a system API user with
+ * SYSTEM_OWNER only), and once the container answers calls ZITADEL's system
+ * API `CreateInstance` with a machine owner (IAM_OWNER of the new instance)
+ * signed by the private half, which lives in memory for that run only. The
+ * owner's PAT comes back once and is handed to
+ * {@link PlatformAuthDeps.deliverSecret} under
+ * {@link PLATFORM_AUTH_INSTANCE_BEARER_REF}, before anything else uses it. A
+ * host builds `zitadelForInstance` as `(url) => createZitadelAdminMinter({
+ * url, token: <the secret delivered under that ref> })` plus its own org
+ * calls; `zitadelForInstance` is first called after the delivery. No human
+ * admin is created: a person who needs console access is added by the host
+ * through that bearer.
+ *
+ * #197: a `cloudflared` connector for this tunnel is run
+ * ({@link ensureCloudflaredConnector}), so `hostname` answers.
+ */
+export declare function provisionAuthStack(scope: StepScope, deps: PlatformAuthDeps, target: ServiceTarget, input: AuthStackInput): Promise<{
+    resourceId?: string;
+}>;
 /**
  * The fixed description Stalwart's admin API key is minted under
  * (`StalwartClient.createApiKey`'s own signature returns only the secret,
@@ -443,6 +609,7 @@ export interface PlatformMailAdminPort {
      * written nothing else. The caller restarts the app and calls again.
      */
     applySettings(input: {
+        /** The name the server announces on SMTP: its own hostname, never the relay's MX name. */
         mailHost: string;
         /** The platform's own apex domain, `platformMailSettingsObjects`'s `usernameDomain`. */
         apex: string;
@@ -529,6 +696,99 @@ export interface PlatformMailRuntime {
     /** Tries at handing the admin key to the host (default 3). */
     deliverAttempts?: number;
 }
+/**
+ * What {@link provisionMailServer} reads besides the target's names: the
+ * platform's declared values for the platform's server, the company's for a
+ * company's.
+ */
+export interface MailServerInput {
+    /** Where the server's web, JMAP and management API answer: `mail.<domain>`. */
+    hostname: string;
+    /** The domain the server's admin account and default domain belong to. */
+    apex: string;
+    /** The MX name: the A record `mxRecord` publishes. The server announces `hostname`, not this. */
+    mailHost: string;
+    /** The Stalwart image tag. */
+    imageTag: string;
+    /** `host:container` list; empty publishes no host port. */
+    hostPorts: string;
+    /** The sign-in the server's directory trusts; its `mail` project's id is the audience. */
+    issuerUrl: string;
+    /** Publish `mailHost` as an unproxied A record at the server's address. `null`: someone else's record serves it. */
+    mxRecord: {
+        serverIpv4?: string | null;
+    } | null;
+    project: ProjectSource;
+    network: ServiceNetwork;
+}
+/**
+ * #169: makes `coolify:app` keyed {@link PLATFORM_MAIL_KEY} true -- Stalwart
+ * on Coolify with its own persistent storage, reached at
+ * `platform.mail.hostname` through a Cloudflare tunnel for web, JMAP and its
+ * management API (mirroring #168's ZITADEL/login apps: TLS terminated at
+ * Cloudflare, plain HTTP behind the tunnel) and at `mx.<apex>` over a direct,
+ * unproxied `A` record to the Coolify server's own address for SMTP -- raw
+ * SMTP cannot ride Cloudflare's HTTP-only tunnel the way a web app does,
+ * which is exactly why #169's own "Human steps" asks a person to open ports
+ * 25, 465 and 587 on that server's host firewall. Then, once the instance
+ * answers, the OIDC directory against the platform's own sign-in and
+ * foundry's admin API key, minted once and handed to
+ * {@link PlatformMailDeps.deliverSecret}.
+ *
+ * Every part is safe to run again after a throw partway, the same rules
+ * {@link provisionPlatformAuth} follows: each id is recorded (and persisted)
+ * as soon as its resource exists, the app is deployed on every run that
+ * needs it, and the admin key is delivered before the guard that skips the
+ * mint is recorded. Unlike ZITADEL's `ZITADEL_ADMIN_PASSWORD`, the recovery
+ * credential this step generates (`STALWART_RECOVERY_ADMIN`) is read back
+ * from Coolify's own env store on every run rather than held only in memory
+ * -- `CoolifyPort.listEnvs`'s own doc comment says these values come back
+ * live -- so a retry after a delivery failure re-authenticates with the same
+ * credential instead of losing it.
+ *
+ * **Why not `@wtfalch/email/postmaster`'s `mailObjects`/`applyObjects`**, the
+ * instance-bootstrap helper `wtfalch-manage` already uses for the hand-built
+ * `mail.companyincluded.com`: that plan also wires an `AcmeProvider` and `DnsServer`
+ * for Stalwart's own DNS-01 ACME challenge, and an `MtaRoute` that relays
+ * every outbound message through the earlier mail provider -- the estate moved transactional
+ * mail off it onto Lettermint before this issue (`@wtfalch/mailer` ADR
+ * 0006), and this step provisions no Cloudflare DNS token for Stalwart's own
+ * ACME either. Calling it as-is would mint an outbound relay this platform
+ * does not want and a credential requirement this issue does not cover, so
+ * {@link PlatformMailAdminPort.applySettings} is a narrower settings write
+ * instead, through `platformMailSettingsObjects`: the default hostname and
+ * the OIDC directory only.
+ *
+ * Known gaps, left for review (like #168's own "the PR stays open for
+ * William's review"):
+ * - **No ACME/TLS for the SMTP listener.** `mx.<apex>` answers with
+ *   Stalwart's own self-signed certificate until a follow-up wires a real
+ *   one (`mailObjects`'s `AcmeProvider`/`DnsServer` shape, minus the earlier relay
+ *   relay it also carries).
+ * - **The Lettermint team token the org app step reads still comes from
+ *   wherever the host already reads it, not held keys.** Needs
+ *   `StepExecutionContext` to carry the platform, which `plan-apply.ts`'s
+ *   own doc comment already scoped out of #167 as more than a small change
+ *   -- a follow-up issue, not this one. (#205 removed the org step
+ *   `coolify:mail`'s own fallback to the hand-built mail
+ *   instance -- `diff.ts`'s `planMail` already blocks the step until the
+ *   platform's own mail is applied, so the fallback only ever served a
+ *   plan recorded before that, and now fails loudly instead.)
+ * - **A ZITADEL client's token may not carry the mail project's id in
+ *   `aud` by default.** #346's own "Human steps": confirm this on the first
+ *   live run, and if it does not, the client must request the mail
+ *   project's audience scope.
+ * - **The admin API key is minted with `'inherit'` permissions**, not a
+ *   narrower set scoped to only what `applySettings` needs.
+ * - **The undelivered-key guard records before `createApiKey` mints**, not
+ *   after -- so a crash between the two records an id (`admin.createApiKey`
+ *   has not even run) that no key was ever minted for. Harmless today
+ *   (the guard only ever blocks a retry and names an id to revoke by), but
+ *   worth tightening if `createApiKey` ever starts returning its own id.
+ */
+export declare function provisionMailServer(scope: StepScope, deps: PlatformMailDeps, target: ServiceTarget, input: MailServerInput): Promise<{
+    resourceId?: string;
+}>;
 /**
  * #211: the broker cannot start without `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`,
  * `LETTERMINT_API_TOKEN` and `AUTH_APPS`. `provisionPlatformAuth` already
@@ -811,8 +1071,6 @@ export interface PlatformAiRuntime {
     /** Pause between readiness polls (default 5 seconds). */
     readyIntervalMs?: number;
 }
-/** The ref the AI management key is delivered under; the host's `AiOrganisationPort` adapter reads it back. */
-export declare const PLATFORM_AI_MANAGEMENT_KEY_REF = "ai:platform:managementKey";
 /**
  * What Archon's management key may do in ai: exactly `ai`'s own
  * `ARCHON_AI_PERMISSIONS` (`apps/host/scripts/authz/bootstrap-archon.ts`) --
@@ -994,6 +1252,8 @@ export interface PlatformFilesRuntime {
     readyTimeoutMs?: number;
     /** Pause between readiness polls (default 5 seconds). */
     readyIntervalMs?: number;
+    /** Called with every secret this step reads or mints, so the host's run can redact it. */
+    onSecret?: (value: string) => void;
 }
 /**
  * #171: how the host signs a files management request with the key this step
@@ -1007,10 +1267,74 @@ export interface PlatformFilesRuntime {
  */
 export declare const FILES_MANAGEMENT_ISSUER = "foundry";
 export declare const FILES_MANAGEMENT_KEY_ID = "foundry-1";
-/** The ref the management private key (PKCS#8 PEM) is delivered under. */
-export declare const FILES_MANAGEMENT_KEY_REF = "files:platform:managementKey";
 /** The ref the files host's introspection client secret is delivered under. */
 export declare const FILES_INTROSPECTION_SECRET_REF = "zitadel:platform:files:introspection";
+export declare const PLATFORM_FILES_DB_NAME = "platform-files-db";
+/** The two Coolify apps files' `apps/host/README.md` ("Deploying on Coolify") names. */
+export declare const FILES_MIGRATE_APP_NAME = "files-migrate";
+export declare const FILES_RUNNER_APP_NAME = "files";
+/**
+ * The runner's fixed `custom_internal_name`: the name another container on
+ * the Coolify network reaches it by, and so the host part of
+ * {@link PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY}'s recorded address.
+ */
+export declare const FILES_RUNNER_INTERNAL_NAME = "platform-files";
+export interface FilesHostInput {
+    /** The runner's `APP_URL` host, the management verifier's audience. */
+    hostname: string;
+    gitRef: string;
+    project: ProjectSource;
+    /** `AUTH_ISSUER`, and the sign-in instance the files ZITADEL project is made in. */
+    issuer: string;
+    /** The ZITADEL organisation the files project lives in: found or made by name, or already known by id. */
+    zitadelOrg: {
+        name: string;
+    } | {
+        id: string;
+    };
+    /** The files ZITADEL project (its id is the person-token audience) and the scope key its id is recorded under. */
+    zitadelProject: {
+        name: string;
+        scopeKey: string;
+    };
+    /** {@link filesShareDomains} of the orgs this host serves: each is a runner domain and a public host. */
+    shareDomains: readonly string[];
+    /** An own org's `AUTHZ_BOOTSTRAP_OPERATOR`: the platform owner's id, from the platform's recorded state. */
+    bootstrapOperator?: string;
+    /** An own org's keys credential id: recorded as the guard once both apps carry the keyring. */
+    keysGuardId?: string;
+}
+/** The credential id of the keyring an own files host runs on; recorded once both apps carry it. */
+export declare const OWN_FILES_KEYS_SCOPE_KEY = "files_keys_id";
+/** The credential id minted and not yet confirmed delivered. */
+export declare const OWN_FILES_KEYS_UNDELIVERED_SCOPE_KEY = "files_keys_undelivered";
+/**
+ * An own files host's keyring, before its env writes. Both refs held: those values, no mint (a rerun
+ * after a failed run resumes here). Nothing held: one mint, which is checked, registered as a
+ * secret, recorded by id as undelivered, then delivered to both refs. A re-mint is harmless: it
+ * yields an equivalent credential. Returns the guard id for {@link FilesHostInput.keysGuardId}.
+ */
+export declare function resolveOwnFilesKeys(scope: StepScope, deps: {
+    deliverSecret: PlatformFilesDeps['deliverSecret'];
+    readSecret?: (ref: string) => Promise<string | null>;
+    runtime?: PlatformFilesDeps['runtime'];
+}, target: ServiceTarget, mint: () => Promise<FilesKeysMinted>, workerUrl: string, label: string): Promise<{
+    keys: {
+        workerUrl: string;
+        credential: string;
+        verifyKeys: string;
+    };
+    guardId: string;
+}>;
+/**
+ * The body of {@link provisionPlatformFiles} for any files host: the
+ * platform's, or an own org's. Every name, the internal name and the two
+ * held-key refs come from `target`; the project, sign-in and ZITADEL home
+ * come from `input`. See {@link provisionPlatformFiles} for what the step does.
+ */
+export declare function provisionFilesHost(scope: StepScope, deps: PlatformFilesDeps, target: ServiceTarget, input: FilesHostInput): Promise<{
+    resourceId?: string;
+}>;
 export interface PlatformEdgeRuntime {
     fetch?: typeof fetch;
     sleep?: (ms: number) => Promise<void>;
@@ -1088,6 +1412,20 @@ export interface PlatformHcDeps {
     /** Clock, sleep and fetch for the readiness wait; real ones by default. */
     runtime?: PlatformHcRuntime;
 }
+export declare function filesKeys(deps: PlatformFilesDeps | undefined): {
+    workerUrl: string;
+    credential: string;
+    verifyKeys: string;
+} | null;
+/**
+ * #380: the files host's own checks on what the host supplies, mirrored from
+ * `apps/host/src/lib/authz/files-host.ts` (`R2_ENDPOINT`: a bare https origin)
+ * and `src/lib/keys/config.ts` (`KEYS_VERIFY_KEYS`: 1 or 2 comma-separated
+ * base64url values, each exactly 32 bytes), so a bad value blocks the step
+ * naming the field instead of deploying a host that never turns healthy.
+ * Never echoes the value.
+ */
+export declare function filesDepsInvalid(deps: PlatformFilesDeps | undefined): string | null;
 /**
  * #174: everything {@link provisionPlatformIntegrations} needs beyond
  * {@link PlatformStepExecutionContext} -- a bundle, like
@@ -1279,6 +1617,16 @@ export declare class ProvidersPlatformCoolifyReader implements PlatformCoolifyRe
     constructor(client: Pick<CoolifyPort, 'getApplication' | 'getDatabase' | 'listDatabaseBackups' | 'listEnvs' | 'raw'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
     listResources(): Promise<LiveResource[]>;
 }
+/**
+ * `findZoneByApex` returns the longest suffix match, so for a subdomain it
+ * answers with the parent zone. The platform's zone is its apex exactly;
+ * any other zone is never adopted or reported as the platform's.
+ */
+export declare function exactZone<Z extends {
+    name: string;
+}>(client: {
+    findZoneByApex(domain: string): Promise<Z | undefined>;
+}, apex: string): Promise<Z | undefined>;
 /** Scope id (no `:`): the share domains the runner's Coolify `domains` was last set to, comma-joined. */
 export declare const PLATFORM_FILES_SHARE_DOMAINS_SCOPE_KEY = "platform_files_share_domains";
 /**