@wtfalch/foundry 0.4.0 → 0.6.0

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

@@ -0,0 +1,615 @@
+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' | 'mintLoginClientMachineUser' | 'listLoginClientPats'>;
+    /**
+     * 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.
+ * #152: the step mints one LiveKit key per org with calls enabled rather
+ * than one shared pair, so it also needs `declaredOrgStore.list()` -- the
+ * same store this class already takes for `findOrgIdForZone`.
+ *
+ * #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' | 'list'>, options?: FoundryPlatformStepExecutorOptions);
+    blockedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
+        auth?: string;
+        authExecutorMissing?: boolean;
+        authOtherInputsMissing?: string[];
+        files?: string;
+        integrations?: string;
+        ai?: string;
+        archon?: string;
+        mail?: string;
+    }>;
+    /**
+     * Whether Archon's live Access policy lets through anyone but the declared
+     * emails, or (#211 round 4) the broker it last registered with no longer
+     * carries its entry; or (#216 round 4) the platform's recorded
+     * login-client token is no longer the sole live PAT on its ZITADEL machine
+     * user.
+     */
+    driftedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
+        archon?: boolean;
+        auth?: boolean;
+    }>;
+    execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
+        resourceId?: string;
+    } | undefined>;
+    private cloudflareZone;
+    /**
+     * #152: the platform `sfu` step owns the shared LiveKit config, so it
+     * lists every org with calls enabled itself -- `DeclaredOrgStore.list()`,
+     * filtered the same way an org's own `calls.enabled` flag gates its
+     * `coolify:calls-service` step (`executor.ts`'s `coolifyCallsService`) --
+     * rather than taking the list as an argument nothing else would supply.
+     * Sorted by slug so a re-run with the same set of enabled orgs is a no-op
+     * even before `applyCallsSfuPlatformStep`'s own sort (its doc comment).
+     */
+    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.
+     *
+     * `put` (#213) writes a value under `ref`, once -- see
+     * {@link putArchonMasterKeys}. Also optional, and also blocking: while
+     * {@link masterKeys} is given but this cannot put, Archon is blocked, not
+     * skipped, the same rule.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+        put?(ref: string, value: string): Promise<void>;
+    };
+    /**
+     * #213: the credentials Archon's own onboarding reads back as held keys
+     * before it can start (archon#101 round 3, archon#104) -- the Coolify URL
+     * and token this package already deploys with, and a Cloudflare parent
+     * token with "API Tokens Write" a human creates by hand (#213 "Human
+     * steps"), so Archon can mint its own scoped child token from it. Put
+     * once, under tenant `platform`, before Archon's app deploys
+     * ({@link putArchonMasterKeys}); optional so a host without it still
+     * compiles, and Archon is blocked, not skipped, while it (or
+     * {@link heldKeys}'s `put`) is missing.
+     */
+    masterKeys?: {
+        coolifyUrl: string;
+        coolifyToken: string;
+        cloudflareParentToken: string;
+    };
+}
+/**
+ * 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/#201: mints Archon's own 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, named `archon` (the key is Archon's; foundry only mints
+ * it while provisioning -- see {@link provisionPlatformAi}). The secret comes
+ * back once; {@link provisionPlatformAi} hands it to `deliverSecret` and
+ * records only the credential id.
+ *
+ * {@link createAiManagementKeyMinter} is the real implementation
+ * {@link provisionPlatformAi} builds by default, signing with the Ed25519
+ * pair it mints and pins on the runner and calling ai's own
+ * `POST /v1/platform/keys` (github.com/wtfalch/ai/issues/141). That route is
+ * idempotent by name: a repeat call with the same permissions and expiry
+ * returns the live key's id with no secret rather than a second key, so
+ * `mintManagementKey` throws {@link AiManagementKeyExistsError} for that
+ * case -- {@link provisionPlatformAi} only ever calls it once there is no
+ * delivered record, so a 200 here means an earlier mint's secret was lost,
+ * never a fresh one to hand back.
+ *
+ * A test may still inject a different {@link AiManagementKeyMinter} in
+ * {@link PlatformAiDeps.managementKeyMinter}, which skips building the
+ * default one and its signing-key machinery entirely.
+ */
+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;
+    }>;
+}
+/**
+ * Thrown by {@link createAiManagementKeyMinter} (never by a test's own
+ * injected minter, unless it chooses to) when ai's `POST /v1/platform/keys`
+ * answers 200: a live `archon` key already exists and no secret comes back.
+ * See {@link PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY}.
+ */
+export declare class AiManagementKeyExistsError extends Error {
+    readonly credentialId: string;
+    readonly organisationId: string;
+    constructor(credentialId: string, organisationId: string);
+}
+/**
+ * Thrown by {@link createAiManagementKeyMinter} on a 409: a live `archon` key
+ * already exists with different permissions or expiry than this request
+ * asked for. ai never overwrites it, so this is never retried under another
+ * name -- an operator revokes the live key in ai first.
+ */
+export declare class AiManagementKeyConflictError extends Error {
+    constructor();
+}
+/**
+ * Thrown by {@link createAiManagementKeyMinter} on a 401 or 403: ai does not
+ * trust foundry's signing key yet for this request. Most likely the runner
+ * has not redeployed since {@link AI_SIGNING_KEY_REF}'s public half was
+ * pinned as `MANAGEMENT_PUBLIC_KEYS`/`MANAGEMENT_ISSUER` -- a Coolify env
+ * change reaches the container only on its next deploy.
+ */
+export declare class AiManagementKeyUntrustedError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+/** #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'];
+    /**
+     * Reads back a secret this step delivered on an earlier apply -- needed
+     * only to re-sign a mint request when the signing pair was pinned on a
+     * run that crashed before the management key itself was minted and
+     * delivered (#201). Not needed on the common path, where both happen in
+     * the same run.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+    };
+    /** Injected for tests. Absent, {@link provisionPlatformAi} builds the real {@link createAiManagementKeyMinter} from the signing key it mints. */
+    managementKeyMinter?: AiManagementKeyMinter;
+    /** Injected for tests, e.g. against a fake ai host. Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    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 a secret to the host (default 3): the management key and the signing key both use this. */
+    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 Archon's management key may do in ai: exactly `ai`'s own
+ * `ARCHON_AI_PERMISSIONS` (`apps/host/scripts/authz/bootstrap-archon.ts`) --
+ * configuration only (offerings, provisioning, offers, budgets, usage, cost)
+ * plus deleting (archiving) an organisation, never connections, runs or
+ * webhooks. ai's `/v1/platform/keys` route refuses any permission outside
+ * this same list, so a request for more than this is a 403, not a wider key.
+ */
+export declare const PLATFORM_AI_MANAGEMENT_PERMISSIONS: readonly string[];
+/** The ref the AI signing key's private half (PKCS#8 PEM) is delivered under -- the {@link INTEGRATIONS_MANAGEMENT_KEY_REF} pattern, for ai instead of integrations. */
+export declare const AI_SIGNING_KEY_REF = "ai:platform:signingPrivateKey";
+/** `MANAGEMENT_ISSUER` on the ai runner: whoever signs with the delivered key signs as this issuer. */
+export declare const AI_MANAGEMENT_ISSUER = "foundry";
+/** The key id the public half is pinned under in `MANAGEMENT_PUBLIC_KEYS` (ai's keyring allows `^[A-Za-z0-9_-]{1,100}$`). Fixed, since there is one key until rotation is built. */
+export declare const AI_MANAGEMENT_KEY_ID = "foundry-1";
+/**
+ * The real {@link AiManagementKeyMinter}: signs a management assertion with
+ * `privateKeyPem` (the PKCS#8 PEM {@link provisionPlatformAi} delivers under
+ * {@link AI_SIGNING_KEY_REF} and pins on the runner under `keyId`) and calls
+ * ai's `POST /v1/platform/keys`. `audience` must be the exact origin ai's own
+ * `APP_URL` resolves to (`https://<platform.ai.hostname>`), since ai checks
+ * the claim against that env var, not against the internal address the
+ * request itself is sent to.
+ */
+export declare function createAiManagementKeyMinter(options: {
+    privateKeyPem: string;
+    keyId: string;
+    issuer: string;
+    audience: string;
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}): AiManagementKeyMinter;
+/**
+ * #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 {};