@wtfalch/foundry 0.32.0 → 0.34.0

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

@@ -1,5 +1,5 @@
 import type { CloudflareClient } from '@wtfalch/providers/cloudflare';
-import type { DeclaredOrg } from '../org.js';
+import { type DeclaredOrg } from '../org.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { DeclaredOrgStore, PlatformStore } from '../store.js';
 import { type DeployHealthRuntime } from './deploy-health.js';
@@ -8,11 +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
@@ -27,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
@@ -37,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
@@ -90,14 +108,21 @@ export interface PlatformAuthDeps {
     tunnels: PlatformTunnelsFactory;
     cloudflare: Pick<CloudflarePort, 'findZoneByApex'>;
     /** Must target the platform's own new instance (its issuer), or `zitadelForInstance` must be set. */
-    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'closeSelfRegistration' | 'inviteOrgOwner'> & PlatformZitadelSmtp;
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser' | 'mintLoginClientMachineUser' | 'listLoginClientPats' | 'reserveUserName' | 'closeSelfRegistration' | 'inviteOrgOwner' | 'addOrgDomain' | 'setPrimaryOrgDomain' | 'setUserMetadata' | 'getUserMetadata'> & PlatformZitadelSmtp;
+    /**
+     * Mails the owner's first-sign-in link to their personal address (the same
+     * port as `FoundryStepExecutorPorts.ownerInviteMail`). The link carries the
+     * invite code, so `send` must not log it or put it in an error. Without it
+     * the owner invite cannot run and the step stops there with a fixed message.
+     */
+    ownerInviteMail?: FoundryStepExecutorPorts['ownerInviteMail'];
     /**
      * Builds the ZITADEL port for the new instance from its issuer URL
      * (`https://<auth.hostname>`). When set it is used instead of
      * {@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
@@ -125,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/
@@ -135,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
@@ -315,12 +350,14 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
         auth?: string;
         authExecutorMissing?: boolean;
         authOtherInputsMissing?: string[];
+        authOwnerInvite?: string;
         files?: string;
         integrations?: string;
         ai?: string;
         edge?: string;
         archon?: string;
         mail?: string;
+        relay?: string;
         accessProvider?: string;
         backupExecutorMissing?: boolean;
         hc?: string;
@@ -377,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
@@ -387,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`
@@ -403,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,
@@ -434,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;
@@ -520,12 +696,144 @@ 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
+ * skips deploying the broker while any is missing
+ * ({@link missingBrokerInputs}); this is the same check surfaced through
+ * `blockedSteps`, so a plan says why, by name, rather than the broker simply
+ * sitting undeployed with no explanation. `null` while there is no broker
+ * app id recorded yet (nothing to check) or every input is present.
+ *
+ * #211 round 3: wraps the live read the way {@link mailBlockedReason} wraps
+ * its own Coolify call -- a transient `listEnvs` failure must report a
+ * blocked reason naming the broker app id, never throw out of
+ * `blockedSteps` and take the rest of the plan down with it.
+ *
+ * #211 round 5 addendum: when `AUTH_APPS` is the reason, names which problem
+ * it actually is ({@link authAppsProblem}) instead of always saying "it has
+ * no ... AUTH_APPS yet" -- that wording is only true when nothing has been
+ * set; a present-but-invalid value is a different failure (a person needs to
+ * go fix an entry, not merely wait for one of #209/#210/Archon's own
+ * registration to supply one), and reporting it identically hid which one
+ * was true.
+ *
+ * #210: `LETTERMINT_API_TOKEN` joins `ZITADEL_SERVICE_USER_TOKEN` in being
+ * excluded from `otherInputsMissing` -- but only while `auth.heldKeys`
+ * actually resolves {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF} right now.
+ * `planAuth`'s own "loop fix" stops planning this step the moment every
+ * `otherInputsMissing` entry looks like something only another run can
+ * supply; excluding `LETTERMINT_API_TOKEN` unconditionally (the way
+ * `ZITADEL_SERVICE_USER_TOKEN` is, since foundry can always eventually mint
+ * that one) would keep the step planned, and `provisionPlatformAuth`
+ * running its full body, forever on a host that never wires `heldKeys` or
+ * whose operator has not put a Lettermint key there yet -- exactly the
+ * wasteful-replan bug #211 round 5 fixed for the broker deploy itself. Once
+ * the key *is* held, excluding it lets this run's `provisionPlatformAuth`
+ * push it (see that function's own `heldMailKey` read) and clears the gap
+ * for good.
+ */
+/** Why the platform owner cannot be invited yet, or `null`. Fixed text: names no address. */
+export declare function ownerInviteBlockedReason(ownerCompany: DeclaredOrg | null, hasInviteMail: boolean): string | null;
 /**
  * #175: everything {@link provisionPlatformArchon} needs beyond
  * {@link PlatformStepExecutionContext}, bundled like {@link PlatformAuthDeps}.
  */
 export interface PlatformArchonDeps {
-    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'deleteEnv' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'getDeployment'>;
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'listEnvironments' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerfileApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'raw' | 'bulkUpsertEnvs' | 'listEnvs' | 'deleteEnv' | 'updateApplication' | 'deploy' | 'deployAndWait' | 'getDeployment'>;
     /** F4.dns: every DNS record call, through edge at its recorded address (see {@link PlatformDnsFactory}). */
     dns: PlatformDnsFactory;
     /** F4.tunnels: every tunnel call, through edge at its recorded address (see {@link PlatformTunnelsFactory}). */
@@ -604,7 +912,6 @@ export interface PlatformArchonRuntime {
  * org (`foundry:<orgId>`), with the platform's step key in the org id's place.
  */
 export declare const PLATFORM_ARCHON_ACCESS_APP_NAME = "foundry:platform:archon";
-export { PLATFORM_ZITADEL_ORG_SCOPE_KEY };
 /** Archon's OIDC client id: public, not a secret, so a plain scope id. */
 export declare const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = "zitadel_platform_archon_client_id";
 /**
@@ -764,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`) --
@@ -947,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
@@ -960,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>;
@@ -1041,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
@@ -1232,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";
 /**