@wtfalch/foundry 0.16.6 → 0.16.8

package/dist/plan/executor.js

@@ -143,6 +143,19 @@ function mailOrgFor(org, usesDomain, mode) {
 const COOLIFY_PROXY_ORIGIN = 'http://coolify-proxy:80';
 /** The one Access policy foundry puts on its own Access app (#84). */
 export const ACCESS_POLICY_NAME = 'foundry: allowed emails';
+/**
+ * The Access policy name for each `hosting.access` rule kind (#246),
+ * `cloudflareAccess`'s way of telling its own policy apart from a foreign
+ * one on the same app -- the same role {@link ACCESS_POLICY_NAME} plays for
+ * the `app` entry's own email gate, which keeps that exact name so a
+ * re-run against an org applied before #246 still recognises its own
+ * policy.
+ */
+const ACCESS_RULE_POLICY_NAMES = {
+    gate: ACCESS_POLICY_NAME,
+    bypass: 'foundry: bypass',
+    'service-token': 'foundry: service token',
+};
 /**
  * The sign-in broker's own route mount (`@wtfalch/auth`'s `NextAuth`,
  * `dist/next.d.ts`'s `handlers` doc comment: "`export const { GET, POST } =
@@ -635,7 +648,7 @@ export class FoundryStepExecutor {
             case 'cloudflare:zone':
                 return this.cloudflareZone(action, org);
             case 'cloudflare:access':
-                return this.cloudflareAccess(org);
+                return this.cloudflareAccess(action, org);
             case 'cloudflare:ratelimit':
                 return this.cloudflareRateLimit(org);
             case 'files:organisation':
@@ -677,40 +690,91 @@ export class FoundryStepExecutor {
         }
     }
     /**
-     * `plan/diff.ts`'s `planAccess` (#84): puts the org's app hostname behind a
-     * Cloudflare Access app that lets only the `app` entry's `accessEmails` through.
-     * foundry names its Access app `foundry:<orgId>` and reuses only an app with
-     * that name, so a re-run after a crash does not duplicate it. It refuses,
-     * rather than adopt, when another Access app already holds the hostname:
-     * destroy would later delete it. It also refuses when its own app carries
+     * `plan/diff.ts`'s `planAccess` (#84, widened by #246): puts a hostname
+     * behind a Cloudflare Access app. `action.key` tells the `app` entry's own
+     * gate (`accessEmails`, email-only) apart from a `hosting.access` rule on
+     * any other hostname -- `appStepKey` builds both, keyed by the entry's key
+     * or by the rule's hostname respectively, and the two never collide
+     * because an entry key never holds a `.` while a rule's hostname always
+     * does (`org.ts`'s `validateAccessRule`). The app-entry gate keeps the
+     * Access app name `foundry:<orgId>` it has always used, so a re-run
+     * against an org applied before #246 still finds the app it already
+     * created; a rule's own app is named `foundry:<orgId>:<hostname>` instead,
+     * since an org may declare more than one. Either way foundry reuses only
+     * an app with its own name (so a re-run after a crash does not duplicate
+     * it), refuses to adopt a hostname another Access app already holds
+     * (destroy would later delete it), and refuses when its own app carries
      * any policy but foundry's, since that policy could let others in.
      */
-    async cloudflareAccess(org) {
+    async cloudflareAccess(action, org) {
         // Only the `app` entry has a public name (`planAccess`); per-entry
         // hostnames are issue 309.
         const entry = appEntry(org.hosting);
         if (!entry)
             throw new Error(`cloudflare:access for ${org.slug}: no '${APP_ENTRY_KEY}' hosting entry`);
-        const domain = appHostname(org);
-        const name = `foundry:${org.id}`;
+        if (action.key === appStepKey(org, entry.key)) {
+            return this.cloudflareAccessApp(org, {
+                appName: `foundry:${org.id}`,
+                domain: appHostname(org),
+                policyName: ACCESS_POLICY_NAME,
+                policy: {
+                    decision: 'allow',
+                    include: entry.accessEmails.map((email) => ({ email: { email } })),
+                },
+            });
+        }
+        const rule = (org.hosting.access ?? []).find((r) => appStepKey(org, r.hostname) === action.key);
+        if (!rule) {
+            throw new Error(`cloudflare:access for ${org.slug}: no hosting.access rule matches step key '${action.key}'`);
+        }
+        return this.cloudflareAccessApp(org, {
+            appName: `foundry:${org.id}:${rule.hostname}`,
+            domain: rule.hostname,
+            policyName: ACCESS_RULE_POLICY_NAMES[rule.kind],
+            policy: await this.accessPolicyFor(org, rule),
+        });
+    }
+    /** The Cloudflare Access policy body for one `hosting.access` rule, by kind (#246). */
+    async accessPolicyFor(org, rule) {
+        switch (rule.kind) {
+            case 'gate':
+                return {
+                    decision: 'allow',
+                    include: rule.emails.map((email) => ({ email: { email } })),
+                };
+            case 'bypass':
+                // A bypass policy still needs an `include` rule to match against;
+                // `everyone` is Cloudflare's own shape for "match every visitor".
+                return { decision: 'bypass', include: [{ everyone: {} }] };
+            case 'service-token': {
+                const token = await this.ports.cloudflare.findServiceTokenByName(rule.serviceTokenName);
+                if (!token) {
+                    throw new Error(`cloudflare:access for ${org.slug}: no Cloudflare Access service token named '${rule.serviceTokenName}'`);
+                }
+                return { decision: 'non_identity', include: [{ service_token: { token_id: token.id } }] };
+            }
+        }
+    }
+    /**
+     * The create-or-adopt-refusal logic `cloudflareAccess` shares between the
+     * `app` entry's own gate and every `hosting.access` rule (#84, #246).
+     */
+    async cloudflareAccessApp(org, opts) {
+        const { appName, domain, policyName, policy } = opts;
         const cf = this.ports.cloudflare;
         const onDomain = (await cf.listAccessApps()).filter((a) => a.domain === domain);
-        const foreign = onDomain.find((a) => a.name !== name);
+        const foreign = onDomain.find((a) => a.name !== appName);
         if (foreign) {
             throw new Error(`cloudflare:access for ${org.slug}: Access app '${foreign.name}' already holds ${domain}; foundry does not adopt it`);
         }
-        const app = onDomain[0] ?? (await cf.createAccessApp({ name, domain, type: 'self_hosted' }));
+        const app = onDomain[0] ?? (await cf.createAccessApp({ name: appName, domain, type: 'self_hosted' }));
         const policies = await cf.listAccessPolicies(app.id);
-        const other = policies.find((p) => p.name !== ACCESS_POLICY_NAME);
+        const other = policies.find((p) => p.name !== policyName);
         if (other) {
             throw new Error(`cloudflare:access for ${org.slug}: Access app ${app.id} has policy '${other.name}' that foundry did not create`);
         }
         if (policies.length === 0) {
-            await cf.createAccessPolicy(app.id, {
-                name: ACCESS_POLICY_NAME,
-                decision: 'allow',
-                include: entry.accessEmails.map((email) => ({ email: { email } })),
-            });
+            await cf.createAccessPolicy(app.id, { name: policyName, ...policy });
         }
         return { resourceId: app.id };
     }
@@ -3055,10 +3119,11 @@ export class FoundryStepExecutor {
      * (`bouleBrokerEntry`).
      */
     async coolifyBoule(action, org, context) {
-        // The issuer the plan read, carried in the step: the env written is the
-        // env the plan showed.
+        // The issuer and Archon URL the plan read, carried in the step: the env
+        // written is the env the plan showed.
         const issuer = action.desired.issuer ?? null;
-        const { env, missing } = desiredBouleEnv(org, context.recordedIds(), issuer);
+        const archonUrl = action.desired.archonUrl ?? null;
+        const { env, missing } = desiredBouleEnv(org, context.recordedIds(), issuer, archonUrl);
         if (missing.length > 0) {
             throw new Error(`Boule for ${org.slug} cannot be configured: missing ${missing.join(', ')}. Nothing was written.`);
         }

package/dist/plan/index.d.ts

@@ -35,4 +35,6 @@ export type { MailAllowlistApp } from './mail-identity-allowlist.js';
 export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
 export type { CoolifyPort, CloudflarePort, ZitadelPort, CallsSfuPort, JobsSchedulerPort, FilesOrganisationPort, AiOrganisationPort, FoundryStepExecutorPorts, PlatformOrgPortSource, } from './executor.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
+export type { ZitadelListAppsRawApp } from './executor.js';
+export { adaptZitadelListApps } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/index.js

@@ -18,4 +18,5 @@ export { loginHostnameFor } from './login-host.js';
 export { checkMailIdentityAudience } from './mail-identity.js';
 export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
 export { FoundryStepExecutor, NotBuiltError, healthUrls } from './executor.js';
+export { adaptZitadelListApps } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';

package/dist/plan/plan-apply.d.ts

@@ -3,7 +3,7 @@ import type { DeclaredOrg, OrgId } from '../org.js';
 import type { Plan, PlanStep } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { AppliedState } from '../state.js';
-import type { DeclaredOrgStore, PlatformStore } from '../store.js';
+import type { AppliedVersionsStore, DeclaredOrgStore, PlatformStore } from '../store.js';
 import { type AgoraHostPort } from './agora.js';
 import { type StepAction } from './diff.js';
 import { type LiveReaders, type LiveResource, type PlatformLiveReaders } from './live.js';
@@ -204,6 +204,8 @@ export interface PlatformStepExecutor {
     driftedSteps?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<{
         archon?: boolean;
         auth?: boolean;
+        /** #380: see `PlanPlatformOptions.drifted.files` (`platform-diff.ts`). */
+        files?: boolean;
         backupStorage?: boolean;
         /** #257 fix round 4: see `PlanPlatformOptions.drifted.backupStorageBlocked` (`platform-diff.ts`). */
         backupStorageBlocked?: string;
@@ -315,6 +317,13 @@ export interface FoundryPlanApplyOptions {
     aiOrganisation?: boolean;
     /** Overridable for tests; defaults to `() => new Date()`. */
     now?: () => Date;
+    /**
+     * #253: appends a history row every time `runSteps` records a new
+     * version as applied, beside the single-snapshot `store.putAppliedState`
+     * write that already happens there. Optional, and a no-op without it --
+     * every existing caller of this constructor is unaffected.
+     */
+    appliedVersions?: AppliedVersionsStore;
     /**
      * #167: dependencies for planning/applying the shared platform (#166)
      * alongside an org. Optional so an org-only caller — every #19-era caller,
@@ -364,6 +373,7 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly hostFiles;
     private readonly hostAi;
     private readonly now;
+    private readonly appliedVersions;
     private readonly platformDeps;
     constructor(options: FoundryPlanApplyOptions);
     plan(id: OrgId): Promise<Plan>;
@@ -422,6 +432,16 @@ export declare class FoundryPlanApply implements PlanApply {
      * (perhaps not yet wired to this platform) keeps them.
      */
     private orgAgoraHost;
+    /**
+     * #374: the Archon that bills every org, written into each Boule as
+     * `ARCHON_URL` -- `https://` plus the declared platform's `archon.hostname`
+     * (today `archon.companyincluded.com`), the same `platformDeps`
+     * {@link orgAgoraHost} reads. `null` with no platform declared, Archon not
+     * enabled, or Archon not yet applied -- the same `enabled && applied` gate
+     * {@link agoraHostValuesFromPlatform} uses for `issuer`, so a Boule never
+     * points at an Archon that is not live yet.
+     */
+    private orgArchonUrl;
     /** #167: `FoundryPlanApplyOptions.platform`, or a plain `Error` naming what's missing. */
     private requirePlatformDeps;
     private computeFreshPlatformPlan;

package/dist/plan/plan-apply.js

@@ -8,7 +8,7 @@ import { entryAiUndeliveredScopeKey } from './entry-ai-key.js';
 import { FILES_ROOT_UNDELIVERED_SCOPE_KEY, entryFilesUndeliveredScopeKey, } from './entry-files-key.js';
 import { readLivePlatformResources, readLiveResources, } from './live.js';
 import { lockedHostnames } from './locked-hostnames.js';
-import { planPlatform as computePlatformPlanDetail, toPlatformPlan, } from './platform-diff.js';
+import { PLATFORM_ARCHON_KEY, planPlatform as computePlatformPlanDetail, toPlatformPlan, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export class DeclaredOrgNotFoundError extends Error {
     constructor(orgId) {
@@ -98,6 +98,7 @@ export class FoundryPlanApply {
     hostFiles;
     hostAi;
     now;
+    appliedVersions;
     platformDeps;
     constructor(options) {
         this.store = options.store;
@@ -114,6 +115,7 @@ export class FoundryPlanApply {
         this.hostFiles = options.filesOrganisation ?? false;
         this.hostAi = options.aiOrganisation ?? false;
         this.now = options.now ?? (() => new Date());
+        this.appliedVersions = options.appliedVersions;
         this.platformDeps = options.platform;
     }
     async plan(id) {
@@ -344,14 +346,25 @@ export class FoundryPlanApply {
             });
             throw e;
         }
+        const lastApplied = { at: this.now().toISOString(), declaredOrgVersion: hashOrg(org) };
         const applied = {
             orgId,
             serviceIds,
             checkpoints,
             failedFields: failedFields(org, detail, detail.plannedSteps.length, serviceIds),
-            lastApplied: { at: this.now().toISOString(), declaredOrgVersion: hashOrg(org) },
+            lastApplied,
         };
         await this.store.putAppliedState(applied);
+        // #253: the single-snapshot write just above replaces whatever
+        // `lastApplied` this org had; this is the point in today's code where a
+        // version is recorded as applied, so it's also where the appended
+        // history row goes. Optional, and a no-op without it, like every other
+        // host-supplied dependency on `FoundryPlanApplyOptions`.
+        await this.appliedVersions?.record({
+            service: orgId,
+            ref: lastApplied.declaredOrgVersion,
+            appliedAt: lastApplied.at,
+        });
         await this.audit.recordApply({
             actor: this.actor,
             orgId,
@@ -365,11 +378,12 @@ export class FoundryPlanApply {
         const org = await this.store.get(id);
         if (!org)
             throw new DeclaredOrgNotFoundError(id);
-        const [live, applied, platformReadiness, agoraHost] = await Promise.all([
+        const [live, applied, platformReadiness, agoraHost, archonUrl] = await Promise.all([
             readLiveResources(id, this.readers),
             this.store.getAppliedState(id),
             this.orgPlatformReadiness(),
             this.orgAgoraHost(id),
+            this.orgArchonUrl(),
         ]);
         const otherSlugs = (await this.store.list()).filter((o) => o.id !== id).map((o) => o.slug);
         const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness, {
@@ -377,6 +391,7 @@ export class FoundryPlanApply {
             broker: this.broker,
             otherSlugs,
             now: () => this.now().getTime(),
+            archonUrl,
         });
         const invalid = await this.invalidHosting(org);
         if (invalid) {
@@ -448,6 +463,26 @@ export class FoundryPlanApply {
         const recorded = await this.platformDeps.store.getServiceIds();
         return agoraHostValuesFromPlatform(platform, recorded);
     }
+    /**
+     * #374: the Archon that bills every org, written into each Boule as
+     * `ARCHON_URL` -- `https://` plus the declared platform's `archon.hostname`
+     * (today `archon.companyincluded.com`), the same `platformDeps`
+     * {@link orgAgoraHost} reads. `null` with no platform declared, Archon not
+     * enabled, or Archon not yet applied -- the same `enabled && applied` gate
+     * {@link agoraHostValuesFromPlatform} uses for `issuer`, so a Boule never
+     * points at an Archon that is not live yet.
+     */
+    async orgArchonUrl() {
+        if (!this.platformDeps)
+            return null;
+        const platform = await this.platformDeps.store.get();
+        if (!platform || !platform.archon.enabled)
+            return null;
+        const recorded = await this.platformDeps.store.getServiceIds();
+        if (!recorded[`coolify:app:${PLATFORM_ARCHON_KEY}`])
+            return null;
+        return `https://${platform.archon.hostname}`;
+    }
     /** #167: `FoundryPlanApplyOptions.platform`, or a plain `Error` naming what's missing. */
     requirePlatformDeps() {
         if (!this.platformDeps) {

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

@@ -579,11 +579,15 @@ export interface PlanPlatformOptions {
      * check itself failed (Coolify unreachable, credentials revoked) -- the
      * plan is never failed over it, but it is reported in `unmanaged` rather
      * than only logged, so a persistent failure is visible instead of silently
-     * retried forever.
+     * retried forever. `files` (#380): the runner's live env is missing a
+     * setting `ensureStarted()` requires -- see `filesRunnerEnvDrifted`
+     * (`platform-providers.ts`) -- which the recorded hostname/gitRef alone
+     * could never show.
      */
     drifted?: {
         archon?: boolean;
         auth?: boolean;
+        files?: boolean;
         backupStorage?: boolean;
         backupStorageBlocked?: string;
     };

package/dist/plan/platform-diff.js

@@ -625,7 +625,7 @@ export function planPlatform(platform, live, options = {}) {
     // #171: after auth, so a first apply builds the sign-in the files step
     // creates its ZITADEL project in before that step runs.
     const authReady = auth.step !== null || Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_AUTH_KEY)]);
-    const files = planFiles(platform, recordedIds, blocked.files, authReady);
+    const files = planFiles(platform, recordedIds, blocked.files, authReady, drifted.files);
     if (files.step)
         plannedSteps.push(files.step);
     // #169: the platform's own mail server. After auth, because its OIDC
@@ -1049,6 +1049,10 @@ function planSfu(platform) {
  * the broker's own token as part of running this step, and a step that is
  * never planned never runs. So this still plans the step -- surfacing
  * `executorBlocked` in `blocked` for visibility, not to stop planning.
+ * Exception (the auth-broker loop): once everything else is applied and
+ * `otherInputsMissing` is non-empty, nothing this step can do changes the
+ * missing inputs, so it is reported blocked and not planned -- else every
+ * `driveApply` round replans it until `maxRounds`.
  *
  * #211 round 6: round 3's `!brokerApplied` guard assumed "no executor" and
  * "broker not yet created" always coincide. They don't: a broker recorded on
@@ -1159,10 +1163,25 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
     // #211 round 3: a blocked reason with no broker yet created also means the
     // executor is unusable (no auth dependencies) -- nothing to plan.
     // A blocked reason with the broker already created means only its deploy
-    // is held back; plan the step anyway so it can keep retrying and, once
-    // #209/#210 land, deploy on the very next apply.
+    // is held back; plan the step anyway, so it can mint what it can (#209) and,
+    // once #210 lands, deploy on the very next apply.
     if (executorBlocked && !brokerApplied)
         return { step: null, blocked: executorBlocked };
+    // Loop fix: everything but the broker deploy is applied and that deploy
+    // waits on an input (`otherInputsMissing`, never the token this step mints)
+    // that another run supplies -- re-applying changes nothing, so the step
+    // planned and applied every `driveApply` round, with dozens of Coolify
+    // calls each, until `maxRounds`. Report it blocked and plan nothing; the
+    // next plan re-reads the live inputs, so it plans the step once they exist.
+    // The login client is not required here: `provisionPlatformAuth` mints it
+    // only once those same inputs exist, so it is never recorded before then.
+    if (executorBlocked &&
+        otherInputsMissing.length > 0 &&
+        recordedIds[key] &&
+        connectorApplied &&
+        recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS) {
+        return { step: null, blocked: executorBlocked };
+    }
     return {
         step: {
             action: {
@@ -1373,12 +1392,18 @@ function planIntegrations(platform, recordedIds, executorBlocked) {
  * `gitRef`, for the reason {@link planAuth} gives: no platform reader reports
  * these resources, so a live check would replan the step forever. A changed
  * hostname or `gitRef` plans the step again (a redeploy, no new secrets).
+ * `drifted` (#380, `FoundryPlatformStepExecutor.driftedSteps`'s own live
+ * check on the runner's env) replans it too, with neither changed: this is
+ * how a setting {@link provisionPlatformFiles} only started setting after
+ * the runner was already recorded applied -- `R2_BUCKET`, `R2_ENDPOINT` and
+ * `KEYS_VERIFY_KEYS` among them -- ever reaches a runner that deployed
+ * before.
  *
  * Blocked, not planned, while the platform's sign-in is neither recorded nor
  * planned in this same plan: the step creates its ZITADEL project and client
  * there, so it would throw on every apply.
  */
-function planFiles(platform, recordedIds, executorBlocked, authReady) {
+function planFiles(platform, recordedIds, executorBlocked, authReady, drifted) {
     if (!platform.files.enabled)
         return { step: null, blocked: null };
     // A secret minted but never delivered and written is lost (the private key
@@ -1404,11 +1429,17 @@ function planFiles(platform, recordedIds, executorBlocked, authReady) {
             };
         }
     }
-    if (recordedIds[resourceKey('coolify', 'app', PLATFORM_FILES_KEY)] &&
+    const applied = Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_FILES_KEY)]) &&
         recordedIds[PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY] === platform.files.hostname &&
-        recordedIds[PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY] === platform.files.gitRef) {
+        recordedIds[PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY] === platform.files.gitRef;
+    // #380: applied is not enough on its own -- the runner's live env can be
+    // missing a setting `ensureStarted()` requires (`driftedSteps`'s own
+    // `filesRunnerEnvDrifted`), the exact gap that left the platform's own
+    // files host recorded applied and `running:unhealthy` at once. Drifted
+    // replans the step so `provisionPlatformFiles` (which redeploys
+    // unconditionally on every run) fills in whatever is still missing.
+    if (applied && !drifted)
         return { step: null, blocked: null };
-    }
     if (executorBlocked)
         return { step: null, blocked: executorBlocked };
     if (!authReady) {

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

@@ -207,6 +207,7 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     driftedSteps(platform: DeclaredPlatform, recordedIds?: Readonly<Record<string, string>>): Promise<{
         archon?: boolean;
         auth?: boolean;
+        files?: boolean;
         backupStorage?: boolean;
         backupStorageBlocked?: string;
     }>;
@@ -645,13 +646,62 @@ export interface PlatformFilesDeps {
      * 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
+     * and the executor reports the step blocked while either is unset. Never
      * recorded or logged.
+     *
+     * #380: `verifyKeys` (`KEYS_VERIFY_KEYS`) is the same kind of requirement,
+     * but only on the `files` runner, not `files-migrate` -- the runner's own
+     * `ensureStarted()` (`apps/host/src/lib/authz/files-host.ts`) requires it
+     * with `requireEnv(...)` to build its keys issuer, and the step reports
+     * the whole thing blocked while it is unset, the same as a missing
+     * `workerUrl`/`credential`. `auditToken` (`KEYS_AUDIT_TOKEN`) is not: it
+     * gates only the keys repo's own reconcile job against
+     * `GET /v1/keys/audit`, so it is set on the runner only when supplied and
+     * never blocks the step.
      */
     keys?: {
         workerUrl: string;
         credential: string;
+        verifyKeys?: string;
+        auditToken?: string;
     };
+    /**
+     * #380: the object storage (Cloudflare R2) the `files` runner stores
+     * objects in -- `R2_BUCKET`/`R2_ENDPOINT`, both `required(...)` by
+     * `ensureStarted()`. The actual R2 access key and secret are not here:
+     * the host reads them back through the keys worker above at runtime
+     * (files' own `.env.example`), never a plaintext env var this step would
+     * set. Absent, the step reports the runner blocked the same way a
+     * missing `keys` already does -- issue #380's "Decide" leaves open
+     * whether foundry ever mints this bucket itself (today, only a host that
+     * already has one can supply it).
+     */
+    r2?: {
+        bucket: string;
+        endpoint: string;
+    };
+    /**
+     * #380: `FILES_CLAMD_HOST`/`FILES_CLAMD_PORT` -- a clamd daemon reachable
+     * on the Coolify network. Optional: unset keeps files' own default
+     * (`confirm()` runs unscanned), and never blocks the step. Issue #380's
+     * "Decide" leaves open which clamd this should point at.
+     */
+    clamd?: {
+        host: string;
+        port?: string;
+    };
+    /**
+     * #380: `FILES_PUBLIC_HOSTS`, the public share hosts this deployment
+     * answers on, comma-separated bare host names. Optional; unset keeps
+     * `/s/<token>` 404 everywhere, today's behaviour.
+     */
+    publicHosts?: string;
+    /**
+     * #380: `JOBS_SIGNING_SECRETS`, the scheduled-jobs project's own HMAC
+     * secret(s), comma-separated, current first. Optional; unset keeps every
+     * `/api/jobs/*` route answering 503 `not_configured`, today's behaviour.
+     */
+    jobsSigningSecrets?: string;
     /** Clock and sleep for the migration wait and delivery retries; real ones by default. */
     runtime?: PlatformFilesRuntime;
 }