@wtfalch/foundry 0.16.15 → 0.16.16

package/dist/plan/executor.d.ts

@@ -294,10 +294,13 @@ export interface CoolifyPort {
      * fresh Synapse/MAS config file, since a file-storage write alone does not
      * reach the running container until its next deploy (issue #128's "a
      * running app is redeployed when its config changed"). Fire-and-forget,
-     * like `restart` above: this executor does not poll a deployment to
-     * completion anywhere else, and `coolifyCalls` only calls this when the
-     * config it just wrote was actually freshly minted. Matches `CoolifyClient.
-     * deploy` method-for-method.
+     * like `restart` above: `coolifyCalls` only calls this when the config it
+     * just wrote was actually freshly minted, with nothing recorded afterward
+     * that depends on the new version actually being live. Matches
+     * `CoolifyClient.deploy` method-for-method. A step that records an applied
+     * hostname/gitRef after a deploy uses {@link CoolifyPort.deployAndWait}
+     * instead (#252) — `deploy-health.ts`'s `waitForNewDeployment` is the one
+     * shared helper every such step calls, never this method directly.
      */
     deploy(uuid: string, force?: boolean): Promise<unknown>;
     /**
@@ -361,6 +364,27 @@ export interface CoolifyPort {
     }): Promise<{
         uuid: string;
     }>;
+    /**
+     * Deploys and blocks until Coolify's own deployment record reaches a
+     * terminal state (#252) — matches `CoolifyClient.deployAndWait`
+     * method-for-method. Unlike `deploy` above, or unlike polling
+     * `getApplication`'s live `status`, this is the one honest answer to
+     * "did the new version actually land": a failed build leaves the previous
+     * container running and healthy, so `status` and a served request read
+     * identically whether the deploy succeeded or not (`CoolifyDeploymentRecord`'s
+     * own doc comment in `@wtfalch/providers`). `force` defaults to `true` on
+     * the real client for the same reason its own doc comment gives — every
+     * caller here is provisioning or releasing, where a wrong "it's applied"
+     * costs more than a warm build cache.
+     */
+    deployAndWait(uuid: string, options?: {
+        force?: boolean;
+        attempts?: number;
+        intervalMs?: number;
+    }): Promise<{
+        deploymentUuid: string;
+        status: string;
+    }>;
 }
 /**
  * The Cloudflare calls this executor makes, shaped to match
@@ -812,7 +836,7 @@ export interface ZitadelPort {
         givenName: string;
         familyName: string;
         email: string;
-    }): Promise<{
+    }, urlTemplate?: string): Promise<{
         userId: string;
         created: boolean;
     }>;
@@ -1341,6 +1365,16 @@ export interface FoundryStepExecutorPorts {
      * themselves.
      */
     deliverSecret(ref: string, secret: string): Promise<void>;
+    /**
+     * Archon's held keys, for an entry env from `sharedSecret` (read, else
+     * generate and `put`) and `platformMailKey` (read only). Optional: without
+     * it, or without `put`, such an env is omitted and the plan reports it
+     * blocked. A value goes to the entry's env and nowhere else.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null | undefined>;
+        put?(ref: string, value: string): Promise<void>;
+    };
     /**
      * Read access to the declared-org store, narrowed to the one query
      * `cloudflareZone` needs for its cross-org refusal check (#131) -- see that
@@ -1636,6 +1670,13 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * provisioned, where this one is unconditional (#239).
      */
     private pushAppEnv;
+    /**
+     * The org's shared secret `name`: read from the held keys, else generated
+     * and held first, so a crash after the `put` and before the env write
+     * hands the same value out on the next apply. Only called when `put` exists.
+     * An error here names the ref, never a value.
+     */
+    private ensureSharedSecret;
     /**
      * F5: the app's `AUTH_APP_KEY`, minted once and only when the app has none
      * of at least 32 characters (the broker refuses a shorter one). `null` once
@@ -2360,6 +2401,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * this is called every time regardless of whether it already ran --
      * idempotent by find-or-create, not by checking `recordedIds` first.
      *
+     * F6b: `action.desired.shareHost` (`diff.ts`'s `planFilesOrganisation`) is
+     * passed through every time, even though `entry-files-key.ts` reports the
+     * route itself as blocked until the platform's files host can serve
+     * `share.<domain>` -- this is the one place the name reaches files at all,
+     * so files can act on it the moment its own route exists.
+     *
      * #273: also ensures the org's Agora origin is on the files host's CORS
      * allowlist (`FilesOrganisationPort.ensureAllowedOrigin`), the same
      * repeat-is-a-no-op shape as `provisionOrganisation` itself -- every org

package/dist/plan/executor.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { URL } from 'node:url';
 import { CALLS_SFU_PRIVATE_URL, CALLS_SFU_PUBLIC_URL } from '../calls-sfu.js';
-import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, } from '../org.js';
+import { APP_ENTRY_KEY, appEntry, filesCollectionEnvName, ownerMailboxRecorded, ownerMailboxes, sharedSecretRef, } from '../org.js';
 import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CALLS_INTROSPECTION_SCOPE_KEY, CALLS_INTROSPECTION_UNDELIVERED_SCOPE_KEY, CALLS_SERVICE_NAME_SCOPE_KEY, CALLS_SERVICE_PORT, CALLS_SERVICE_TOKEN_ENV_SCOPE_KEY, CHAT_SERVICE_URL_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, ZITADEL_MESSAGING_PROJECT_SCOPE_KEY, ZITADEL_ORG_SCOPE_KEY, agoraHostnameFor, callsIntrospectionAppName, callsServiceHasName, callsServiceInternalName, callsTokenEnvMarker, callsTokenEnvMovedMessage, desiredAgoraEnv, entryClientIdScopeKey, } from './agora.js';
 import { BOULE_BROKER_ENTRY_KEY, BOULE_CLIENT_ID_SCOPE_KEY, BOULE_DATABASE_SCOPE_KEY, bouleEnvDrift, bouleHostnameFor, desiredBouleEnv, wantedBouleBrokerEntry, } from './boule.js';
 import { brokerEntryAppliedScopeKey, brokerEntryWarningsScopeKey, entryAuthEnv, entryAuthEnvAppliedScopeKey, wantedBrokerEntry, writeBrokerEntry, } from './broker-entries.js';
@@ -14,6 +14,7 @@ import { appHostname, coolifyDomains, entryHostnames, tunnelDnsHostnames, tunnel
 import { LOGIN_BINDING_SCOPE_KEY, LOGIN_HOST_PENDING_REMOVAL_SCOPE_KEY, loginBindingState, loginHostClientIds, pendingRemovalHosts, pendingRemovalState, } from './login-host.js';
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, runMailCopyStep, } from './mail-copy.js';
 import { CALLS_MAS_APPLIED_IMAGE_TAG_SCOPE_KEY, CALLS_SYNAPSE_APPLIED_IMAGE_TAG_SCOPE_KEY, ORG_MAIL_APPLIED_APEX_SCOPE_KEY, ORG_MAIL_APPLIED_HOST_SCOPE_KEY, appDomainsAppliedScopeKey, appEnvAppliedScopeKey, appNameFor, appSettingsAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, } from './platform-diff.js';
+import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec, entryProxyLabels, sameLabelSets, } from './proxy-labels.js';
 /**
  * #274 fix round 4: bridges `@wtfalch/providers`' real `ZitadelClient.
@@ -861,11 +862,16 @@ export class FoundryStepExecutor {
         if (!zitadelOrgId) {
             throw new Error(`zitadel:owner for ${org.slug}: no ZITADEL org recorded yet -- the issuer must be provisioned first`);
         }
+        // ZITADEL's default invite link (`/ui/v2/login/verify`) 404s; the platform's login app, which
+        // every org's users sign in through on this instance, serves `/verify` at the root.
+        const authIssuer = action.desired.authIssuer;
         const { userId } = await this.ports.zitadel.inviteOrgOwner(zitadelOrgId, {
             givenName: action.desired.givenName,
             familyName: action.desired.familyName,
             email: action.desired.email,
-        });
+        }, authIssuer
+            ? `${authIssuer}/verify?userId={{.UserID}}&code={{.Code}}&organization={{.OrgID}}&invite=true`
+            : undefined);
         // An owner invited after chat was built never reaches `coolifyChat`
         // again, so the role is granted here once the messaging project exists.
         const messagingProjectId = context.recordedIds()[ZITADEL_MESSAGING_PROJECT_SCOPE_KEY];
@@ -1424,7 +1430,13 @@ export class FoundryStepExecutor {
         // The app receives whatever it needs to sign in (gap P2). Unconditional,
         // unlike the database push above: every app has a hostname, and an
         // upsert of the same value on a later apply is a no-op, not a change.
-        const appEnv = await this.pushAppEnv(appId, org, entry, context, action.desired.authIssuer ?? null);
+        const appEnv = await this.pushAppEnv(appId, org, entry, context, action.desired.authIssuer ?? null, 
+        // What the plan decided is available (diff.ts `planApps`), so the marker
+        // recorded below is the one the plan compares against. Absent: none.
+        action.desired.secretSources ?? {
+            platformMailKey: false,
+            sharedSecret: false,
+        });
         // Rule 4 (#239, #243): a container reads its env only at start, so an app
         // that was already there is restarted, once, when its database URLs or its
         // declared appEnv changed.
@@ -1633,7 +1645,7 @@ export class FoundryStepExecutor {
      * that call runs only once the `app` entry's `database` is declared and
      * provisioned, where this one is unconditional (#239).
      */
-    async pushAppEnv(appId, org, entry, context, authIssuer) {
+    async pushAppEnv(appId, org, entry, context, authIssuer, secretSources) {
         const recorded = context.recordedIds();
         const envs = [
             // Only the `app` entry has a public name; the others are internal.
@@ -1691,14 +1703,44 @@ export class FoundryStepExecutor {
         // minted here; a source with no value yet (its own step has not run,
         // or has not run for this apply) is simply omitted, the same way every
         // other optional entry above is.
-        const appEnv = resolveAppEnv(org, entry, recorded).values;
+        // The secret sources (`sharedSecret`, `platformMailKey`) are filled here
+        // only, straight into `envs`: never recorded, returned or logged.
+        const heldKeys = this.ports.heldKeys;
+        // Availability is the plan's (`secretSources`). If the plan said a key is
+        // held and this port cannot read it, the host wired the two differently:
+        // fail by ref, never push a marker for an env that was not written.
+        let mailKey = null;
+        if (secretSources.platformMailKey) {
+            try {
+                mailKey = (await heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF)) || null;
+            }
+            catch {
+                // reported below, by ref
+            }
+            if (mailKey === null) {
+                throw new Error(`coolify:app for ${org.slug}: the plan found ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF} held but the executor's heldKeys cannot read it`);
+            }
+        }
+        if (secretSources.sharedSecret && typeof heldKeys?.put !== 'function') {
+            throw new Error(`coolify:app for ${org.slug}: the plan found held keys that can put but the executor's heldKeys cannot`);
+        }
+        const resolved = resolveAppEnv(org, entry, recorded, secretSources);
+        const appEnv = resolved.values;
         for (const [key, value] of Object.entries(appEnv))
             envs.push({ key, value });
+        for (const { name, source } of resolved.secrets) {
+            envs.push({
+                key: name,
+                value: source === 'platformMailKey'
+                    ? mailKey
+                    : await this.ensureSharedSecret(org, source.name, recorded),
+            });
+        }
         await this.ports.coolify.bulkUpsertEnvs(appId, envs);
         // `coolifyApp` records `applied` once the restart succeeded, so `planApp`
         // replans this step when the declared map changes (rule 3). Ids and a
         // domain, never a secret.
-        const applied = JSON.stringify(appEnv);
+        const applied = JSON.stringify(resolved.marker);
         // The sign-in values, recorded by `coolifyApp` the same way; the key is
         // never part of them.
         const authApplied = JSON.stringify(authEnv);
@@ -1710,6 +1752,28 @@ export class FoundryStepExecutor {
             authApplied,
         };
     }
+    /**
+     * The org's shared secret `name`: read from the held keys, else generated
+     * and held first, so a crash after the `put` and before the env write
+     * hands the same value out on the next apply. Only called when `put` exists.
+     * An error here names the ref, never a value.
+     */
+    async ensureSharedSecret(org, name, recorded) {
+        const heldKeys = this.ports.heldKeys;
+        const ref = sharedSecretRef(org.id, name);
+        const held = await heldKeys?.resolve(ref);
+        if (held)
+            return held;
+        // Another entry (or this one) already got a value. Generating again would
+        // split them, so a lost value needs a person, not a new mint.
+        const label = `"secret:sharedSecret:${name}"`;
+        if (Object.entries(recorded).some(([key, value]) => key.startsWith('app_env_applied.') && value.includes(label))) {
+            throw new Error(`coolify:app for ${org.slug}: shared secret ${name} was delivered but is no longer held (ref ${ref}); restore the held value, or clear it from every entry's env and applied marker to mint a new one`);
+        }
+        const value = randomBytes(32).toString('base64url');
+        await heldKeys?.put?.(ref, value);
+        return value;
+    }
     /**
      * F5: the app's `AUTH_APP_KEY`, minted once and only when the app has none
      * of at least 32 characters (the broker refuses a shorter one). `null` once
@@ -3971,6 +4035,12 @@ export class FoundryStepExecutor {
      * this is called every time regardless of whether it already ran --
      * idempotent by find-or-create, not by checking `recordedIds` first.
      *
+     * F6b: `action.desired.shareHost` (`diff.ts`'s `planFilesOrganisation`) is
+     * passed through every time, even though `entry-files-key.ts` reports the
+     * route itself as blocked until the platform's files host can serve
+     * `share.<domain>` -- this is the one place the name reaches files at all,
+     * so files can act on it the moment its own route exists.
+     *
      * #273: also ensures the org's Agora origin is on the files host's CORS
      * allowlist (`FilesOrganisationPort.ensureAllowedOrigin`), the same
      * repeat-is-a-no-op shape as `provisionOrganisation` itself -- every org
@@ -3989,6 +4059,7 @@ export class FoundryStepExecutor {
             organisationId: org.id,
             ceilingBytes: action.desired.ceilingBytes ?? null,
             ceilingMicros: action.desired.ceilingMicros ?? null,
+            shareHost: action.desired.shareHost ?? null,
             ...(owner ? { name: org.displayName, owner } : {}),
         });
         const agoraOrigin = action.desired.agoraOrigin;
@@ -4429,6 +4500,7 @@ export class FoundryStepExecutor {
             const envs = [
                 { key: 'FILES_URL', value: d.filesUrl },
                 { key: 'FILES_ORGANISATION_ID', value: org.id },
+                ...(d.shareOrigin ? [{ key: 'FILES_SHARE_ORIGIN', value: d.shareOrigin }] : []),
             ];
             for (const name of d.collections) {
                 let collection;
@@ -4495,6 +4567,7 @@ export class FoundryStepExecutor {
             permissions: d.permissions,
             collections: d.collections,
             filesUrl: d.filesUrl,
+            ...(d.shareOrigin ? { shareOrigin: d.shareOrigin } : {}),
         }));
         if (expiresAt && previousKeyId && previousKeyId !== resourceId) {
             await this.revokeFilesEntryKey(files, org, entryKey, previousKeyId, context);

package/dist/plan/hostnames.d.ts

@@ -26,6 +26,12 @@ export declare function appHostname(org: DeclaredOrg): string;
 export declare function coolifyDomains(names: readonly string[]): string;
 /** What `domains` held on an `app` entry's Coolify app before entries had hostnames. */
 export declare function legacyAppHostname(org: DeclaredOrg): string;
+/**
+ * `share.<domain>` when hosting is on and an entry declares
+ * `uses.files.shareHost`, else `null`. The files service answers public
+ * shares there; foundry never puts it behind Access.
+ */
+export declare function filesShareHostname(org: DeclaredOrg): string | null;
 /**
  * The hostnames `cloudflareTunnel` routes to Coolify's proxy (#115, #145,
  * #164): a site's two names, every entry's names, an own-domain calls name,

package/dist/plan/hostnames.js

@@ -47,6 +47,16 @@ export function coolifyDomains(names) {
 export function legacyAppHostname(org) {
     return org.hosting.usesDomain && org.domain ? org.domain : `${org.slug}.oikos.host`;
 }
+/**
+ * `share.<domain>` when hosting is on and an entry declares
+ * `uses.files.shareHost`, else `null`. The files service answers public
+ * shares there; foundry never puts it behind Access.
+ */
+export function filesShareHostname(org) {
+    if (!org.hosting.enabled || !org.domain)
+        return null;
+    return org.hosting.entries.some((e) => e.uses?.files?.shareHost) ? `share.${org.domain}` : null;
+}
 /**
  * The hostnames `cloudflareTunnel` routes to Coolify's proxy (#115, #145,
  * #164): a site's two names, every entry's names, an own-domain calls name,
@@ -71,6 +81,9 @@ export function tunnelIngressHostnames(org) {
         // #161: and Boule moves onto `boule.<domain>` the same way.
         hostnames.push(bouleHostnameFor(org));
     }
+    const share = filesShareHostname(org);
+    if (share)
+        hostnames.push(share);
     // The wildcard goes last: Cloudflare takes the first ingress rule that
     // matches, so every exact name above must come before `*.<domain>`.
     const wildcard = wildcardHostname(org);

package/dist/plan/index.d.ts

@@ -10,7 +10,7 @@ export type { PlatformOrgClientFactories } from './platform-org-ports.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
 export type { AuditActor, AuditLog, AuthzGate, StepExecutor, StepDestroyer, DestroyTarget, StepExecutionContext, PlatformStepExecutor, PlatformStepExecutionContext, FoundryPlanApplyOptions, } from './plan-apply.js';
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
-export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, filesPublicHostsValue, filesShareDomains, } from './platform-providers.js';
 export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './platform-providers.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';

package/dist/plan/index.js

@@ -4,7 +4,7 @@ export { planPlatform, toPlatformPlan, JOBS_SCHEDULER_KEY, PLATFORM_AI_KEY, PLAT
 export { DEFAULT_ORG_PLATFORM_READINESS, ORG_PLATFORM_KEY_REFS, agoraHostValuesFromPlatform, heldPlatformKeyRefs, orgPlatformReadinessFrom, } from './platform-org.js';
 export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.js';
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
-export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
+export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, filesPublicHostsValue, filesShareDomains, } from './platform-providers.js';
 // #171: how a host signs files management requests with the delivered key.
 export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';

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

@@ -210,6 +210,12 @@ export interface PlatformStepExecutor {
         /** #257 fix round 4: see `PlanPlatformOptions.drifted.backupStorageBlocked` (`platform-diff.ts`). */
         backupStorageBlocked?: string;
     }>;
+    /**
+     * Gives the platform files runner a changed share-domain set and touches
+     * nothing else. Returns the scope ids to record (only the share-domains
+     * one), or `null` when nothing changed.
+     */
+    refreshFilesShare?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<Record<string, string> | null>;
     execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
         resourceId?: string;
     } | undefined>;
@@ -378,6 +384,17 @@ export declare class FoundryPlanApply implements PlanApply {
     constructor(options: FoundryPlanApplyOptions);
     plan(id: OrgId): Promise<Plan>;
     apply(plan: Plan, confirmedOrgName: string): Promise<AppliedState>;
+    /**
+     * After an org apply: gives the platform files runner a changed share-domain
+     * set (its Coolify `domains` and `FILES_PUBLIC_HOSTS`, derived from the
+     * declared orgs) without a platform pass. Touches only the share hosts and
+     * redeploys the runner; the platform files step itself never runs here.
+     * Skips quietly for an actor who may not apply the platform, and when the
+     * platform files step was never applied. There is no platform lock, so the
+     * service ids are re-read just before the write and only the share-domains
+     * key is recorded. A failure is rethrown naming that the org part succeeded.
+     */
+    private refreshPlatformFilesShare;
     /**
      * #167: {@link plan}, for the shared platform (#166) rather than an org --
      * there is no id to pass, since `DeclaredPlatform` is one singleton record.

package/dist/plan/plan-apply.js

@@ -8,8 +8,9 @@ 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 { PLATFORM_ARCHON_KEY, planPlatform as computePlatformPlanDetail, toPlatformPlan, } from './platform-diff.js';
+import { PLATFORM_ARCHON_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_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';
+import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 export class DeclaredOrgNotFoundError extends Error {
     constructor(orgId) {
         super(`no declared org ${orgId}`);
@@ -139,7 +140,42 @@ export class FoundryPlanApply {
             await this.refuse(plan, "destructive or migrating step without the org's name typed correctly");
             throw new ConfirmationRequiredError(orgId);
         }
-        return this.runSteps(org, plan, detail);
+        const applied = await this.runSteps(org, plan, detail);
+        await this.refreshPlatformFilesShare();
+        return applied;
+    }
+    /**
+     * After an org apply: gives the platform files runner a changed share-domain
+     * set (its Coolify `domains` and `FILES_PUBLIC_HOSTS`, derived from the
+     * declared orgs) without a platform pass. Touches only the share hosts and
+     * redeploys the runner; the platform files step itself never runs here.
+     * Skips quietly for an actor who may not apply the platform, and when the
+     * platform files step was never applied. There is no platform lock, so the
+     * service ids are re-read just before the write and only the share-domains
+     * key is recorded. A failure is rethrown naming that the org part succeeded.
+     */
+    async refreshPlatformFilesShare() {
+        const deps = this.platformDeps;
+        if (!deps?.executor.refreshFilesShare)
+            return;
+        if ((await this.authz.canApplyPlatform?.(this.actor)) !== true)
+            return;
+        try {
+            const platform = await deps.store.get();
+            if (!platform?.files.enabled)
+                return;
+            const recorded = await deps.store.getServiceIds();
+            if (!recorded[`coolify:app:${PLATFORM_FILES_KEY}`] ||
+                !recorded[PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY])
+                return;
+            const scopeIds = await deps.executor.refreshFilesShare(platform, recorded);
+            if (scopeIds === null)
+                return;
+            await deps.store.putServiceIds({ ...(await deps.store.getServiceIds()), ...scopeIds });
+        }
+        catch (e) {
+            throw new Error(`org applied; platform files share refresh failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
     }
     /**
      * #167: {@link plan}, for the shared platform (#166) rather than an org --
@@ -443,7 +479,16 @@ export class FoundryPlanApply {
             refs.add(ORG_PLATFORM_KEY_REFS.ai);
         if (this.jobsScheduler)
             refs.add(ORG_PLATFORM_KEY_REFS.jobs);
-        return orgPlatformReadinessFrom(platform, recorded, refs, !heldKeys);
+        const readiness = orgPlatformReadinessFrom(platform, recorded, refs, !heldKeys);
+        // Entry env from the platform's mail key or a shared secret (#T8).
+        let mailKeyHeld = false;
+        try {
+            mailKeyHeld = Boolean(await heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF));
+        }
+        catch {
+            // not held
+        }
+        return { ...readiness, mailKeyHeld, canHoldSecrets: typeof heldKeys?.put === 'function' };
     }
     /**
      * #177: `AgoraHostValues` from the applied platform, the same

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

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, HostingEntry, OrgId } from '../org.js';
+import type { DeclaredOrg, EnvSharedSecret, HostingEntry, OrgId } from '../org.js';
 import { type Plan, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
@@ -107,6 +107,17 @@ export declare const PLATFORM_ARCHON_KEY = "platform:archon";
  */
 export declare const PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY = "archon_applied_hostname";
 export declare const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = "archon_applied_git_ref";
+/**
+ * #398: the integrations management key id Archon runs with, recorded by
+ * `provisionPlatformArchon` only after its deployment finished and its health
+ * check passed with that id in its env. `provisionPlatformIntegrations`'s
+ * rotation step reads this before dropping a previous key id from the
+ * runner's `MANAGEMENT_PUBLIC_KEYS`: the old key stays pinned until this
+ * matches the new id, so a request signed by an Archon container still
+ * running the old key is never refused. If Archon's deploy fails this stays
+ * unrecorded and the old key stays pinned.
+ */
+export declare const PLATFORM_ARCHON_INTEGRATIONS_KEY_SYNCED_SCOPE_KEY = "archon_integrations_key_synced";
 /**
  * #211 round 4: the broker app id Archon last registered its entry with.
  * `provisionPlatformArchon` reads the broker to register with from
@@ -118,6 +129,19 @@ export declare const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = "archon_applied
  * changed hostname or `gitRef` does.
  */
 export declare const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = "archon_applied_broker_app";
+/**
+ * The `AUTHZ_BOOTSTRAP_OPERATOR` the last Archon apply set (`none` when it set
+ * none). `planArchon` plans the step again when the owner's id recorded by
+ * `platform:auth` differs from it, so Archon picks the owner up once auth
+ * has recorded it.
+ */
+export declare const PLATFORM_ARCHON_APPLIED_OPERATOR_SCOPE_KEY = "archon_applied_bootstrap_operator";
+/**
+ * The owner's ZITADEL user id Archon takes as its first operator, from
+ * {@link PLATFORM_AUTH_OWNER_INVITE_SCOPE_KEY}. Undefined when none is
+ * recorded or the recorded value is `none` (no owner declared).
+ */
+export declare function archonBootstrapOperator(recorded: Readonly<Record<string, string>>): string | undefined;
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
  * (Access app rebuild), cleared to '' once the real ingress is written back.
@@ -400,14 +424,31 @@ export declare function appDomainsAppliedScopeKey(entryKey: string): string;
  * entry), so an app that runs today plans no change.
  */
 export declare function appliedAppDomains(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, entryKey: string): string[];
+/** Whether the secret sources can be filled right now: the mail key is held, and a new shared secret can be held. */
+export interface AppSecretAvailability {
+    platformMailKey: boolean;
+    sharedSecret: boolean;
+}
 /**
  * The entry's `env` values that have a value, in env-name order, and the env
  * names whose source has none yet. Shared by `planApp` and the executor's
  * `pushAppEnv` so both read the same recorded ids.
+ *
+ * A secret source is never a value here. `secrets` names each one that can be
+ * filled (`available`), `unresolvedSecrets` each that cannot, and `marker`
+ * is `values` plus a `secret:<source>` label per available secret: the JSON
+ * `coolifyApp` records as applied, so a declared change replans and no secret
+ * is written into it.
  */
-export declare function resolveAppEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+export declare function resolveAppEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, available?: AppSecretAvailability): {
     values: Record<string, string>;
     unresolved: Array<[string, string]>;
+    secrets: Array<{
+        name: string;
+        source: 'platformMailKey' | EnvSharedSecret;
+    }>;
+    unresolvedSecrets: Array<[string, string]>;
+    marker: Record<string, string>;
 };
 /**
  * #172: the resource key `planAi` plans under and `FoundryPlatformStepExecutor`
@@ -478,13 +519,6 @@ export declare const PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY = "ai_platform_migrat
  * that throws) is repaired by the next one.
  */
 export declare const PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY = "ai_platform_deploy_pending";
-/**
- * The Coolify deployment queued for the host (its `deployment_uuid`, or
- * `untracked` when the deploy answered none), set when that deploy is queued
- * and cleared once it finished. The mint waits for it, so a retry after a
- * failed wait still waits instead of minting against the old container.
- */
-export declare const PLATFORM_AI_RUNNER_DEPLOYMENT_SCOPE_KEY = "ai_platform_runner_deployment";
 /**
  * #171: the resource key `planFiles` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the {@link PLATFORM_AUTH_KEY} shape for the files host.
@@ -684,3 +718,49 @@ export declare const PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY = "integrations_man
 /** The hostname and gitRef the last successful apply put live; a difference from the declared ones plans the step again. */
 export declare const PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY = "integrations_applied_hostname";
 export declare const PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY = "integrations_applied_gitref";
+/**
+ * #398: the key id currently pinned on the runner as the active entry of
+ * `MANAGEMENT_PUBLIC_KEYS` -- `foundry-1` on the first mint, and whatever a
+ * rotation minted next after that. `collectArchonServiceInputs` reads this
+ * (falling back to the fixed `INTEGRATIONS_MANAGEMENT_KEY_ID` constant for a
+ * platform applied before this key existed) for Archon's own
+ * `INTEGRATIONS_MANAGEMENT_KEY_ID` env, so a rotated id reaches it without
+ * Archon's step needing to know anything happened on the integrations side.
+ */
+export declare const PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY = "integrations_management_key_id";
+/**
+ * #398: the key id the runner was last deployed with in its
+ * `MANAGEMENT_PUBLIC_KEYS`, recorded by `provisionPlatformIntegrations` only
+ * after the runner's deployment finished. Archon is not moved to a new key id
+ * until this equals the active id, so Archon never signs with a key the
+ * running runner does not yet hold.
+ */
+export declare const PLATFORM_INTEGRATIONS_RUNNER_KEYRING_DEPLOYED_SCOPE_KEY = "integrations_runner_keyring_deployed";
+/**
+ * #398: the same two-key discipline as
+ * {@link PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY}, for a rotation's
+ * new pair: recorded the moment it is minted, before delivery, and cleared
+ * by nothing -- {@link PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY} moving past it
+ * is what later runs read as "delivered and pinned", the same way the
+ * once-only mint's guard is a second key rather than removing the first.
+ * An id here that {@link PLATFORM_INTEGRATIONS_KEY_ID_SCOPE_KEY} has not
+ * caught up to means the pair may be lost or half-applied; the step reports
+ * it and mints no further pair.
+ */
+export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_UNDELIVERED_SCOPE_KEY = "integrations_management_key_rotation_undelivered";
+/**
+ * #398: the previous key id, still pinned in `MANAGEMENT_PUBLIC_KEYS` beside
+ * the new one, pending removal -- set the moment the new pair is pinned
+ * beside it, and cleared (to `''`, the {@link PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY}
+ * convention for "was set, now isn't") once the previous id is actually
+ * removed from the keyring. Its presence is the overlap window: both keys
+ * verify a request while it holds.
+ */
+export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_PREVIOUS_SCOPE_KEY = "integrations_management_key_rotation_previous";
+/**
+ * #398: how a rotation is requested. A person records any non-empty value
+ * under this scope key; `planIntegrations` then plans the step again and
+ * `provisionPlatformIntegrations` mints the new pair, clearing the key (to
+ * `''`) as soon as the mint is recorded, so one request is one rotation.
+ */
+export declare const PLATFORM_INTEGRATIONS_KEY_ROTATION_REQUESTED_SCOPE_KEY = "integrations_management_key_rotation_requested";