@wtfalch/foundry 0.4.0 → 0.5.0

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

@@ -0,0 +1,501 @@
+import type { CloudflareClient } from '@wtfalch/providers/cloudflare';
+import type { DeclaredPlatform } from '../platform.js';
+import type { DeclaredOrgStore, PlatformStore } from '../store.js';
+import type { StepAction } from './diff.js';
+import type { CloudflarePort, CoolifyPort, FoundryStepExecutorPorts, ZitadelPort } from './executor.js';
+import type { LiveResource, PlatformCloudflareReader, PlatformCoolifyReader } from './live.js';
+import type { PlatformStepExecutionContext, PlatformStepExecutor } from './plan-apply.js';
+import { type CallsSfuPlatformDeps } from './platform-sfu.js';
+/**
+ * #168: everything {@link provisionPlatformAuth} needs beyond
+ * {@link PlatformStepExecutionContext} -- a bundle, not more constructor
+ * positions, so every #167-era caller of {@link FoundryPlatformStepExecutor}
+ * (zone only) keeps compiling with this third argument simply omitted.
+ */
+export interface PlatformAuthDeps {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'>;
+    cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'
+    /** #197: fetches the tunnel's connector token for {@link ensureCloudflaredConnector}. */
+     | 'getTunnelToken'>;
+    /** Must target the platform's own new instance (its issuer), or `zitadelForInstance` must be set. */
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'mintAdminMachineUser'>;
+    /**
+     * 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'];
+    deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
+    /** Clock, sleep and fetch for the readiness wait and delivery retries; real ones by default. */
+    runtime?: PlatformAuthRuntime;
+}
+export interface PlatformAuthRuntime {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** How long to wait for the new instance to answer (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between readiness polls (default 5 seconds). */
+    readyIntervalMs?: number;
+    /** Tries at handing the admin key to the host (default 3). */
+    deliverAttempts?: number;
+}
+/** 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";
+/**
+ * The narrow slice of {@link CoolifyPort} {@link FoundryPlatformStepExecutor}
+ * needs for `coolify:jobs` (#173) -- the same project/environment/server/app/
+ * database calls `executor.ts`'s `coolifyApp`/`coolifyDatabase` make for an
+ * 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' | 'bulkUpsertEnvs' | 'getApplication' | 'deploy'>;
+/**
+ * Options for {@link FoundryPlatformStepExecutor}'s constructor, replacing
+ * four positional arguments that shifted on every merge that added a
+ * platform service (#186, #187, #188) -- see
+ * https://github.com/wtfalch/foundry/pull/188#issuecomment-5895935971, the
+ * merge comment that named this shape (#189).
+ */
+export interface FoundryPlatformStepExecutorOptions {
+    coolify?: JobsCoolifyPort;
+    /**
+     * Hands a just-generated secret to the host (`FoundryStepExecutorPorts.
+     * deliverSecret`'s contract: never returned, recorded, logged or put in
+     * an error). Needed by `coolify:jobs` for the scheduler's admin token.
+     */
+    deliverSecret?: (ref: string, secret: string) => Promise<void>;
+    sfu?: CallsSfuPlatformDeps;
+    /**
+     * #168: dependencies for `coolify:app` keyed {@link PLATFORM_AUTH_KEY} --
+     * optional so every #167-era caller (zone only) keeps compiling; a host
+     * that declares `platform.auth.enabled` must construct this with it set,
+     * or `execute` throws naming what's missing.
+     */
+    auth?: PlatformAuthDeps;
+    /**
+     * #169: dependencies for `coolify:app` keyed {@link PLATFORM_MAIL_KEY} --
+     * the same optionality as {@link auth}, for the identical reason.
+     */
+    mail?: PlatformMailDeps;
+    /**
+     * #174: dependencies for the integrations host, `coolify:app` keyed
+     * {@link PLATFORM_INTEGRATIONS_KEY}. Without it, an enabled integrations
+     * host is reported blocked by `blockedSteps` rather than planned.
+     */
+    integrations?: PlatformIntegrationsDeps;
+    /**
+     * #171: dependencies for `coolify:app` keyed {@link PLATFORM_FILES_KEY} --
+     * optional for the same reason as `auth`; a host that declares
+     * `platform.files.enabled` without them has the step reported blocked.
+     */
+    files?: PlatformFilesDeps;
+    /**
+     * #172: dependencies for `coolify:app` keyed {@link PLATFORM_AI_KEY} --
+     * optional for the same reason as `auth`; a host that declares
+     * `platform.ai.enabled` without it gets the step reported as blocked.
+     */
+    ai?: PlatformAiDeps;
+    /**
+     * #175: dependencies for `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}
+     * -- optional for the same reason as {@link auth}.
+     */
+    archon?: PlatformArchonDeps;
+}
+/**
+ * The real {@link PlatformStepExecutor} for the two steps built so far:
+ * `cloudflare:zone` for the platform's apex (#167) and `coolify:jobs` for the
+ * jobs scheduler (#173). `coolify` is optional so every #167-era caller --
+ * anything that only ever plans the apex zone -- keeps constructing this with
+ * two arguments; a `coolify:jobs` step reaching this executor with no
+ * `coolify` port configured throws, naming what is missing, rather than
+ * silently doing nothing.
+ *
+ * `cloudflareZone` mirrors `executor.ts`'s `cloudflareZone`: find the zone by
+ * apex and adopt it, create it only when absent. companyincluded.com already
+ * exists on Cloudflare, empty, so the first apply adopts it. The owner org
+ * (Company Included, whose own domain is the apex) may record the same zone
+ * under its own applied state, so that owner is allowed. Any other org that
+ * recorded it makes this refuse to adopt. There is no delete here and
+ * `PlatformStepExecutor` has none: neither path ever removes the zone.
+ *
+ * `coolifyJobs` mirrors `executor.ts`'s `coolifyApp`/`coolifyDatabase`,
+ * simplified for one platform-level singleton rather than one per org: find
+ * or create a dedicated `platform` Coolify project, find or create the
+ * scheduler's own database, find or create the scheduler app itself (from
+ * https://github.com/wtfalch/jobs, one Dockerfile at its repo root, on the
+ * declared `gitRef`), then push the database's `internal_db_url` in as
+ * `DATABASE_URL`. There is no park branch yet, matching `planJobs`'s own
+ * scope note -- `platform.jobs.enabled` going from true to false plans
+ * nothing, so this method is never asked to stop or delete anything.
+ *
+ * #170 adds `sfu:livekit`, the platform's shared calls SFU. `sfu` is
+ * optional: an existing host that constructs this executor for the zone step
+ * alone keeps compiling, and a plan that includes an `sfu:livekit` step
+ * without it configured refuses clearly rather than silently doing nothing.
+ *
+ * #168 adds `coolify:app` keyed {@link PLATFORM_AUTH_KEY}, the platform's own
+ * sign-in ({@link provisionPlatformAuth}), once a host passes
+ * {@link PlatformAuthDeps}.
+ *
+ * #169 adds `coolify:app` keyed {@link PLATFORM_MAIL_KEY}, the platform's own
+ * mail server ({@link provisionPlatformMail}), once a host passes
+ * {@link PlatformMailDeps}.
+ *
+ * #174 adds `coolify:app` keyed {@link PLATFORM_INTEGRATIONS_KEY},
+ * the integrations host ({@link provisionPlatformIntegrations}), once a host
+ * passes {@link PlatformIntegrationsDeps}.
+ *
+ * #171 adds `coolify:app` keyed {@link PLATFORM_FILES_KEY}, the files host
+ * ({@link provisionPlatformFiles}), once a host passes {@link PlatformFilesDeps}.
+ *
+ * #172 adds `coolify:app` keyed {@link PLATFORM_AI_KEY}, the platform's AI
+ * host ({@link provisionPlatformAi}), once a host passes {@link PlatformAiDeps}.
+ *
+ * #175 adds `coolify:app` keyed {@link PLATFORM_ARCHON_KEY}, Archon itself
+ * ({@link provisionPlatformArchon}), once a host passes
+ * {@link PlatformArchonDeps}.
+ */
+export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor {
+    private readonly cloudflare;
+    private readonly declaredOrgStore;
+    private readonly coolify?;
+    private readonly deliverSecret?;
+    private readonly sfu?;
+    private readonly auth?;
+    private readonly mail?;
+    private readonly integrations?;
+    private readonly files?;
+    private readonly ai?;
+    private readonly archon?;
+    constructor(cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'createZone'>, declaredOrgStore: Pick<DeclaredOrgStore, 'findOrgIdForZone'>, options?: FoundryPlatformStepExecutorOptions);
+    blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
+        auth?: string;
+        files?: string;
+        integrations?: string;
+        ai?: string;
+        archon?: string;
+        mail?: string;
+    }>;
+    /** Whether Archon's live Access policy lets through anyone but the declared emails. */
+    driftedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
+        archon?: boolean;
+    }>;
+    execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
+        resourceId?: string;
+    } | undefined>;
+    private cloudflareZone;
+    private executeSfu;
+    private coolifyJobs;
+}
+/**
+ * The fixed description Stalwart's admin API key is minted under
+ * (`StalwartClient.createApiKey`'s own signature returns only the secret,
+ * never an id) -- what a human revokes it by in Stalwart's own admin UI if
+ * it is ever lost between mint and delivery, and what
+ * {@link PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY} records in that case.
+ */
+export declare const PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION = "foundry:platform:admin";
+/**
+ * Stalwart's own management API, scoped to exactly what this step needs from
+ * the instance it just deployed -- mirrors {@link PlatformAuthDeps}'s
+ * `zitadel`/`zitadelForInstance` split: a host builds this from the
+ * instance's own URL and the recovery-admin credential this step generated
+ * ({@link PlatformMailDeps.stalwartForInstance}), the same way
+ * `zitadelForInstance` is built from a freshly issued instance's issuer URL.
+ * The real implementation wraps `@wtfalch/email/postmaster`'s `openInstance`
+ * (for the `StalwartClient`), a hand-built settings write (see
+ * `provisionPlatformMail`'s own doc comment for why not `mailObjects`) and
+ * `StalwartClient.createApiKey`.
+ */
+export interface PlatformMailAdminPort {
+    /**
+     * Sets the instance's default hostname and its OIDC directory
+     * (`x:SystemSettings`/`x:Directory`/`x:Domain`/`x:Authentication`) --
+     * idempotent, safe to call on every apply once the instance is up.
+     */
+    applySettings(input: {
+        mailHost: string;
+        oidc: {
+            issuerUrl: string;
+            audience: string;
+        };
+    }): Promise<void>;
+    /** `StalwartClient.createApiKey`'s own signature. */
+    createApiKey(description: string, permissions: readonly string[] | 'inherit'): Promise<string>;
+}
+/**
+ * #169: everything {@link provisionPlatformMail} needs beyond
+ * {@link PlatformStepExecutionContext}, mirroring {@link PlatformAuthDeps}'s
+ * own shape.
+ */
+export interface PlatformMailDeps {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'createDockerImageApplication' | 'createDockerfileApplication' | 'raw' | 'listStorages' | 'createPersistentStorage' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy'>;
+    cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord'>;
+    /**
+     * The ZITADEL resource id an access token's `aud` claim must carry for
+     * Stalwart's OIDC directory to accept it -- a resource API registered
+     * against the platform's own sign-in (#168), which neither that step nor
+     * this one creates. See `provisionPlatformMail`'s own doc comment, "Known
+     * gaps".
+     */
+    oidcAudience: string;
+    /**
+     * {@link PlatformMailAdminPort}, built from the instance this step just
+     * deployed and the recovery credential it just read back.
+     */
+    stalwartForInstance(input: {
+        url: string;
+        user: string;
+        password: string;
+    }): PlatformMailAdminPort;
+    deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
+    /** Clock, sleep and fetch for the readiness wait and delivery retries; real ones by default. */
+    runtime?: PlatformMailRuntime;
+}
+export interface PlatformMailRuntime {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** How long to wait for the new instance to answer (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between readiness polls (default 5 seconds). */
+    readyIntervalMs?: number;
+    /** Tries at handing the admin key to the host (default 3). */
+    deliverAttempts?: number;
+}
+/**
+ * #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' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy'>;
+    cloudflare: Pick<CloudflarePort, 'findZoneByApex' | 'findTunnelByName' | 'createTunnel' | 'putTunnelConfig' | 'getTunnelToken' | 'findDnsRecord' | 'createDnsRecord' | 'updateDnsRecord' | 'listAccessApps' | 'createAccessApp' | 'listAccessPolicies' | 'createAccessPolicy' | 'deleteAccessApp'>;
+    /** Must target the platform's own ZITADEL instance, or `zitadelForInstance` must be set. */
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'findOrCreateProject' | 'createOidcApp' | 'listApps' | 'deleteApp'>;
+    /** {@link PlatformAuthDeps.zitadelForInstance}, for Archon's sign-in client. */
+    zitadelForInstance?: (issuerUrl: string) => PlatformArchonDeps['zitadel'];
+    /**
+     * Who the Cloudflare Access app in front of Archon lets through. Host
+     * config, not `DeclaredPlatform`: the platform record names services, not
+     * people. Empty blocks the step (`blockedSteps`) rather than building an
+     * Access app nobody can pass.
+     */
+    accessEmails: readonly string[];
+    /**
+     * Reads a secret an earlier step handed to the host through
+     * `deliverSecret`, or `null` when none is held under `ref` yet -- the same
+     * direction `CallsSfuPort.resolveCredentials` reads held keys back. Every
+     * value it returns goes straight to `bulkUpsertEnvs` and nowhere else.
+     * Optional so a host without it still compiles; while a service is enabled
+     * without it (or without a key it holds) Archon is blocked, not skipped.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+    };
+}
+/**
+ * The name of foundry's own Cloudflare Access app in front of Archon. Same
+ * `foundry:<key>` convention `executor.ts`'s `cloudflareAccess` uses for an
+ * 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";
+/** The platform's own ZITADEL org (`foundry`, the one `provisionPlatformAuth` mints its admin user in). */
+export declare const PLATFORM_ZITADEL_ORG_SCOPE_KEY = "zitadel_platform_org";
+/** 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";
+/**
+ * #172: mints foundry's AI management key -- the plain bearer key
+ * (`wtfk_...`) `AiOrganisationPort` (`executor.ts`) authenticates with,
+ * holding {@link PLATFORM_AI_MANAGEMENT_PERMISSIONS} in ai's platform
+ * (operator) tenant. The secret comes back once; {@link provisionPlatformAi}
+ * hands it to `deliverSecret` and records only the credential id.
+ *
+ * No implementation ships with this package, because none can be built from
+ * it today: see {@link provisionPlatformAi}'s "Known gaps". A host that has
+ * a way to run ai's `keys:issue-archon` (or a future HTTP bootstrap route)
+ * supplies one; without it the planner reports the step as blocked
+ * ({@link PLATFORM_AI_MINTER_BLOCKED}) and plans nothing.
+ *
+ * Requirement: before issuing anything, a minter must look up an existing
+ * management key named `foundry` in the platform tenant and return that one
+ * instead of issuing a new one. A crash after `mintManagementKey` returns and
+ * before the caller records the credential id leaves a live key nobody knows
+ * about; only the minter can find it again, so without this lookup the next
+ * apply mints a second key.
+ */
+export interface AiManagementKeyMinter {
+    mintManagementKey(input: {
+        /** Where the ai host answers on the Coolify network, e.g. `http://platform-ai:3000`. */
+        internalUrl: string;
+        name: string;
+        expiresDays: number;
+        permissions: readonly string[];
+    }): Promise<{
+        credentialId: string;
+        organisationId: string;
+        secret: string;
+    }>;
+}
+/** #172: everything {@link provisionPlatformAi} needs beyond {@link PlatformStepExecutionContext}. */
+export interface PlatformAiDeps {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'findApplicationByName' | 'getApplication' | 'requireGithubApp' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'>;
+    deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
+    /** Optional: see {@link AiManagementKeyMinter}. Absent, the planner blocks the step until the key is delivered. */
+    managementKeyMinter?: AiManagementKeyMinter;
+    runtime?: PlatformAiRuntime;
+}
+export interface PlatformAiRuntime {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** How long to wait for the migrate job to report healthy (default 10 minutes). */
+    migrateTimeoutMs?: number;
+    /** Pause between migrate-job status polls (default 5 seconds). */
+    migrateIntervalMs?: number;
+    /** Tries at handing the management key to the host (default 3). */
+    deliverAttempts?: 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 foundry's management key may do: exactly the grants `ai`'s README
+ * ("Archon's first key", by-hand form) gives archon's key, which are the
+ * ones `ai:organisation`, `ai:budget`, `ai:key` and the org destroy call.
+ */
+export declare const PLATFORM_AI_MANAGEMENT_PERMISSIONS: readonly string[];
+/** The message {@link provisionPlatformAi} throws when no {@link AiManagementKeyMinter} was supplied. */
+export declare const PLATFORM_AI_MINTER_MISSING = "platform:ai: the AI host is deployed but foundry's AI management key cannot be minted: no AiManagementKeyMinter was supplied (PlatformAiDeps.managementKeyMinter). ai mints its first platform credential only through its keys:issue-archon script run against the database (apps/host/scripts/authz/bootstrap-archon.ts); it has no HTTP route for that, and CoolifyPort cannot run a command inside a container (#172)";
+/**
+ * #171: everything {@link provisionPlatformFiles} needs beyond
+ * {@link PlatformStepExecutionContext}, bundled for the same reason as
+ * {@link PlatformAuthDeps}.
+ */
+export interface PlatformFilesDeps {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'updateApplication' | 'deploy' | 'raw'>;
+    /**
+     * Must target the platform's own sign-in (the instance `platform:auth`
+     * built), or {@link zitadelForInstance} must be set.
+     */
+    zitadel: Pick<ZitadelPort, 'findOrCreateOrg' | 'findOrCreateProject' | 'createApiApp' | 'listApps' | 'deleteApp'>;
+    /**
+     * Builds the ZITADEL port for the platform's sign-in from its issuer URL
+     * (`https://<auth.hostname>`); used instead of {@link zitadel} when set, the
+     * same seam {@link PlatformAuthDeps.zitadelForInstance} is.
+     */
+    zitadelForInstance?: (issuerUrl: string) => PlatformFilesDeps['zitadel'];
+    deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
+    /**
+     * The keys worker the files host verifies and seals with, from the host's
+     * held keys (`KEYS_WORKER_URL`, `KEYS_CREDENTIAL`). The `files-migrate` app
+     * never becomes healthy without them, so the step sets both on both apps,
+     * and the executor reports the step blocked while this is unset. Never
+     * recorded or logged.
+     */
+    keys?: {
+        workerUrl: string;
+        credential: string;
+    };
+    /** Clock and sleep for the migration wait and delivery retries; real ones by default. */
+    runtime?: PlatformFilesRuntime;
+}
+export interface PlatformFilesRuntime {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** How long to wait for `files-migrate` to report healthy (default 15 minutes: it builds first). */
+    migrateTimeoutMs?: number;
+    /** Pause between `files-migrate` status polls (default 10 seconds). */
+    migrateIntervalMs?: number;
+    /** Tries at handing each secret to the host (default 3). */
+    deliverAttempts?: number;
+}
+/**
+ * #171: how the host signs a files management request with the key this step
+ * delivers under {@link FILES_MANAGEMENT_KEY_REF} (files'
+ * `signManagementRequest`'s `SigningIdentity`): `issuer` is
+ * {@link FILES_MANAGEMENT_ISSUER}, `keyId` is {@link FILES_MANAGEMENT_KEY_ID},
+ * `audience` is `https://<platform.files.hostname>` (the files host's
+ * `APP_URL`, which this step sets), and `privateKey` is the delivered PKCS#8
+ * PEM. Neither constant is a secret. The files host pins the public half
+ * through `MANAGEMENT_ISSUER`/`MANAGEMENT_PUBLIC_KEYS`, which this step sets.
+ */
+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";
+/**
+ * #174: everything {@link provisionPlatformIntegrations} needs beyond
+ * {@link PlatformStepExecutionContext} -- a bundle, like
+ * {@link PlatformAuthDeps}, so every earlier caller of
+ * {@link FoundryPlatformStepExecutor} keeps compiling with it omitted.
+ */
+export interface PlatformIntegrationsDeps {
+    coolify: Pick<CoolifyPort, 'findProjectByName' | 'createProject' | 'findOrCreateEnvironment' | 'listServers' | 'requireGithubApp' | 'findApplicationByName' | 'getApplication' | 'createGithubAppApplication' | 'updateApplication' | 'listDatabases' | 'createPostgresDatabase' | 'getDatabase' | 'bulkUpsertEnvs' | 'listEnvs' | 'deploy' | 'raw'>;
+    /** Hands the management private key to the host, once (`FoundryStepExecutorPorts.deliverSecret`'s contract). */
+    deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
+    /**
+     * The host's own `@wtfalch/keys` settings, written to the apps' env (the
+     * migrate app takes the first two). Without every value the planner reports
+     * the step blocked: the runner's health check needs them, so the step would
+     * never finish. Secrets: only ever passed to `bulkUpsertEnvs`.
+     */
+    keysEnv: Readonly<Partial<Record<IntegrationsKeysEnvName, string>>>;
+    runtime?: PlatformIntegrationsRuntime;
+}
+export declare const INTEGRATIONS_KEYS_ENV_NAMES: readonly ["KEYS_WORKER_URL", "KEYS_CREDENTIAL", "KEYS_VERIFY_KEYS", "KEYS_AUDIT_TOKEN"];
+export type IntegrationsKeysEnvName = (typeof INTEGRATIONS_KEYS_ENV_NAMES)[number];
+export interface PlatformIntegrationsRuntime {
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** How long to wait for the migrate app to report healthy (default 20 minutes: it builds the whole repo first). */
+    migrateTimeoutMs?: number;
+    /** Pause between polls of the migrate app's status (default 10 seconds). */
+    migratePollMs?: number;
+    /** Tries at handing the management key to the host (default 3). */
+    deliverAttempts?: number;
+}
+/** The ref the management private key (PKCS#8 PEM) is delivered under. */
+export declare const INTEGRATIONS_MANAGEMENT_KEY_REF = "integrations:management:privateKey";
+/** `MANAGEMENT_ISSUER` on the integrations host: whoever signs with the delivered key signs as this issuer. */
+export declare const INTEGRATIONS_MANAGEMENT_ISSUER = "foundry";
+/**
+ * The key id the public half is pinned under in `MANAGEMENT_PUBLIC_KEYS`
+ * (the host's keyring allows `^[A-Za-z0-9_-]{1,100}$`). A signer names it in
+ * its signed request; fixed, since there is one key until rotation is built.
+ */
+export declare const INTEGRATIONS_MANAGEMENT_KEY_ID = "foundry-1";
+/**
+ * The real {@link PlatformCloudflareReader}: the platform's apex zone as
+ * `planApexZone` expects to see it, and nothing else. The zone's DNS records
+ * and tunnels belong to no declared platform step yet, so listing them would
+ * only report them unmanaged.
+ *
+ * The zone is fetched by the id the last apply recorded when there is one,
+ * because Cloudflare's zone list can lag a create; with no recorded id it is
+ * found by apex.
+ */
+export declare class ProvidersPlatformCloudflareReader implements PlatformCloudflareReader {
+    private readonly client;
+    private readonly platformStore;
+    constructor(client: Pick<CloudflareClient, 'findZoneByApex' | 'getZone'>, platformStore: Pick<PlatformStore, 'get' | 'getServiceIds'>);
+    listResources(): Promise<LiveResource[]>;
+}
+/**
+ * #173: the real {@link PlatformCoolifyReader} for the jobs scheduler app --
+ * the recorded-id half of `ProvidersPlatformCloudflareReader`'s own strategy
+ * above, with no list-by-name fallback: unlike a Cloudflare zone (which
+ * exists before foundry ever touches it), the scheduler app has no identity
+ * to adopt until this package creates it, so "nothing recorded yet" and
+ * "nothing live yet" are the same state here. A recorded id Coolify no
+ * longer has (deleted, or moved) reads as not-live, the same "stale id never
+ * blocks planning for good" rule {@link recordedZone} follows.
+ */
+export declare class ProvidersPlatformCoolifyReader implements PlatformCoolifyReader {
+    private readonly client;
+    private readonly platformStore;
+    constructor(client: Pick<CoolifyPort, 'getApplication'>, platformStore: Pick<PlatformStore, 'getServiceIds'>);
+    listResources(): Promise<LiveResource[]>;
+}
+export {};