@wtfalch/foundry 0.16.15 → 0.16.16

package/dist/org.d.ts

@@ -333,8 +333,10 @@ export declare const AI_ENTRY_ENV_NAMES: readonly ["AI_URL", "AI_ORGANISATION_ID
  * env and one collection per name in `collections`. A name is uppercase
  * `[A-Z0-9_]`; its id is delivered as `FILES_COLLECTION_<NAME>_ID`.
  * `permissions` is a subset of {@link FILES_ENTRY_PERMISSIONS}, which is also
- * the default. `shareHost` asks for `share.<domain>`; it is reported blocked
- * until the platform files host serves that name.
+ * the default. `shareHost` asks for `share.<domain>`: foundry routes and
+ * publishes that name through the org's tunnel, delivers `FILES_SHARE_ORIGIN`
+ * and passes it to files. The platform files runner must still serve the
+ * host (a Coolify domain and `FILES_PUBLIC_HOSTS`); the plan warns of that.
  */
 export interface EntryFiles {
     collections: string[];
@@ -356,8 +358,18 @@ export interface HostingEntryUses {
  * looks like a secret. `{ from }` names a value the plan already mints.
  */
 export type EnvValue = string | {
-    from: AppEnvSource;
-};
+    from: Exclude<AppEnvSource, 'sharedSecret'>;
+} | EnvSharedSecret;
+/**
+ * A secret foundry generates once and holds under an org-scoped ref. Every
+ * entry of the same org that names the same `name` gets the same value; an
+ * entry of another org never does. It is written to the entry's env only, and
+ * never reaches a plan, a log or an error.
+ */
+export interface EnvSharedSecret {
+    from: 'sharedSecret';
+    name: string;
+}
 /** The org's `app` entry: today's one app. */
 export declare function appEntry(hosting: HostingConfig): HostingEntry | undefined;
 /**
@@ -367,8 +379,19 @@ export declare function appEntry(hosting: HostingConfig): HostingEntry | undefin
  * sends from. Each is read from `StepExecutionContext.recordedIds()` in
  * `executor.ts`'s `pushAppEnv`, never minted again there.
  */
-export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain';
+export type AppEnvSource = 'filesOrganisationId' | 'aiOrganisationId' | 'mailDomain' | 'sharedSecret' | 'platformMailKey';
+/**
+ * Two sources are secrets. `sharedSecret` is {@link EnvSharedSecret}.
+ * `platformMailKey` is the platform's held Lettermint key, handed over as the
+ * value of the declared env name (the platform's own apps call it
+ * `LETTERMINT_API_TOKEN`). Any hosting entry of any customer org may name it
+ * (William, 2026-10-04): mail is Lettermint, and the key is the platform's.
+ */
 export declare const APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
+/** The sources whose value is a secret: resolved at apply time, never recorded. */
+export declare const SECRET_APP_ENV_SOURCES: ReadonlySet<AppEnvSource>;
+/** The held-key ref of an org's shared secret. */
+export declare const sharedSecretRef: (orgId: string, name: string) => string;
 /**
  * `null` when `hosting` is valid; otherwise the reason it is not (#71), same
  * shape as `validateBuyerIdentity` below.

package/dist/org.js

@@ -39,11 +39,27 @@ export const filesCollectionEnvName = (name) => `FILES_COLLECTION_${name}_ID`;
 export function appEntry(hosting) {
     return hosting.entries.find((entry) => entry.key === APP_ENTRY_KEY);
 }
+/**
+ * Two sources are secrets. `sharedSecret` is {@link EnvSharedSecret}.
+ * `platformMailKey` is the platform's held Lettermint key, handed over as the
+ * value of the declared env name (the platform's own apps call it
+ * `LETTERMINT_API_TOKEN`). Any hosting entry of any customer org may name it
+ * (William, 2026-10-04): mail is Lettermint, and the key is the platform's.
+ */
 export const APP_ENV_SOURCES = new Set([
     'filesOrganisationId',
     'aiOrganisationId',
     'mailDomain',
+    'sharedSecret',
+    'platformMailKey',
 ]);
+/** The sources whose value is a secret: resolved at apply time, never recorded. */
+export const SECRET_APP_ENV_SOURCES = new Set([
+    'sharedSecret',
+    'platformMailKey',
+]);
+/** The held-key ref of an org's shared secret. */
+export const sharedSecretRef = (orgId, name) => `foundry:shared-secret:${orgId}:${name}`;
 const ISSUER_APP_KINDS = new Set(['web', 'native', 'api']);
 const HOSTING_BUILD_PACKS = new Set([
     'dockerfile',
@@ -267,6 +283,9 @@ function validateHostingEntry(entry, enabled) {
             if (!APP_ENV_SOURCES.has(value?.from)) {
                 return `${at} env '${name}' has an unknown source '${value?.from}'`;
             }
+            if (value.from === 'sharedSecret' && !ENTRY_KEY.test(value.name ?? '')) {
+                return `${at} env '${name}' sharedSecret needs a name (lowercase letters, digits and hyphens)`;
+            }
         }
         else if (SECRET_ENV_NAME.test(name) || (name.endsWith('_URL') && urlHasPassword(value))) {
             return `${at} env '${name}' looks like a secret: ${HELD_SECRETS}`;

package/dist/plan/deploy-health.d.ts

@@ -0,0 +1,136 @@
+/**
+ * #252: the one shared helper every platform step calls between deploying a
+ * new version and recording it as the applied ref.
+ *
+ * Before this, a step that records `platform:*`'s applied hostname/gitRef
+ * called `CoolifyPort.deploy` -- fire-and-forget by design (see its own doc
+ * comment) -- and recorded the new ref right after, with nothing in between
+ * proving the new version had actually landed. A failed deploy leaves the
+ * previous container running and healthy (`@wtfalch/providers`'
+ * `CoolifyDeploymentRecord` doc comment: "`status` reports on the container
+ * that is *running*, and a failed build leaves the previous one running and
+ * healthy"), so the old container's healthy status was being read as the
+ * new deployment's -- exactly what `CLAUDE.md`'s platform-step rule 5 ("no
+ * waiting forever... an old healthy status is never read as the new one")
+ * exists to forbid.
+ *
+ * {@link waitForNewDeployment} closes that gap in two steps, always in this
+ * order:
+ *
+ * 1. `coolify.deployAndWait` -- blocks until *Coolify's own deployment
+ *    record* (not `getApplication`'s live container status) reaches a
+ *    terminal state. Anything but `'finished'` throws immediately: a build
+ *    or deploy failure is a hard stop no health check below could ever
+ *    paper over, and it is the step that actually catches "the old
+ *    container stays healthy while the deployment fails" -- the container's
+ *    own status never moves in that scenario, so only the deployment record
+ *    itself tells the two apart.
+ * 2. The health check named by `health.kind`, decided per call site and
+ *    stated there (#252's own decision):
+ *    - `'version'` -- the service's health response carries a version
+ *      string this service actually exposes; polled until it matches
+ *      `health.expected` exactly. Unambiguous proof it is the *new*
+ *      version specifically, but only usable where the service has one.
+ *    - `'ready'` -- the health url answers 2xx. Works for every service
+ *      with a url this helper's caller can actually reach, including ones
+ *      with no version field (the fallback, not the preferred mode), and
+ *      the old-container loophole this mode alone cannot close ("can be
+ *      fooled by the old container staying up") is already closed by step
+ *      1 having confirmed Coolify's own deployment record finished first.
+ *    - `'deployment-only'` -- no health check at all; step 1 is the whole
+ *      answer. For a step whose app has nothing public wired (no Coolify
+ *      `domains`, tunnel, DNS record -- `platform:ai`/`platform:files`'
+ *      own doc comments say so explicitly) there is no url this helper's
+ *      caller, running outside that app's own Docker network, could ever
+ *      reach, so inventing one to poll would just be a slower, flakier way
+ *      of saying "I called deployAndWait". A step that can only use this
+ *      mode is not unverified the way `'ready'` is *within* `'ready'`'s own
+ *      guarantee -- it is strictly weaker than the other two (a deployment
+ *      that "finished" with a crash-looping container is read as success),
+ *      but it is the one honest answer this helper can give it, and it is
+ *      still what catches #252's named failure (the old container staying
+ *      healthy while the deployment record itself fails), since that
+ *      record is exactly what step 1 reads.
+ *
+ * Throws on any failure -- the deployment itself, or the health check
+ * timing out -- naming `appliedRefDescription` (what is still live, for
+ * whoever reads the error) so the caller's own "record applied ref" line is
+ * never reached. Rule 1 from `CLAUDE.md` applies here too: never call this
+ * from inside a retry loop that could mint a one-time secret again, since a
+ * failed wait is meant to be repaired by re-running the whole step, not
+ * silently retried from inside it.
+ */
+export interface DeployAndWaitPort {
+    deployAndWait(uuid: string, options?: {
+        force?: boolean;
+        attempts?: number;
+        intervalMs?: number;
+    }): Promise<{
+        deploymentUuid: string;
+        status: string;
+    }>;
+}
+/**
+ * How a call site proves the new version is the one that answers (or that
+ * there is nothing for it to reach at all). See this module's own doc
+ * comment for why there are exactly three and no "pick one per call"
+ * default.
+ */
+export type DeployHealthCheck = {
+    readonly kind: 'version';
+    readonly url: string;
+    /** Exact match against the health body's version field. */
+    readonly expected: string;
+    /** Field name in the parsed JSON body (default `'version'`). */
+    readonly field?: string;
+} | {
+    readonly kind: 'ready';
+    readonly url: string;
+} | {
+    /** No reachable url; `coolify.deployAndWait` alone is the check. See this module's doc comment. */
+    readonly kind: 'deployment-only';
+};
+export interface DeployHealthRuntime {
+    fetch?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Passed through to `deployAndWait` (default: its own, 90 * 10s = 15 minutes). */
+    deployAttempts?: number;
+    deployIntervalMs?: number;
+    /** `deployAndWait`'s own `force` (default `true` -- see this module's doc comment). */
+    deployForce?: boolean;
+    /** How long to wait for the health check to confirm the new version (default 5 minutes). */
+    readyTimeoutMs?: number;
+    /** Pause between health polls (default 5 seconds). */
+    readyIntervalMs?: number;
+}
+/**
+ * Phase 1 alone: deploys `appId` and blocks until Coolify's own deployment
+ * record reaches a terminal state, throwing unless it is `'finished'`. Split
+ * out of {@link waitForNewDeployment} for a step whose health url only
+ * resolves once *later* work in the same step (archon's/mail's own tunnel
+ * and DNS wiring) has run -- that work must happen between this call and
+ * {@link waitForHealthyVersion}, so the two cannot be one call there. A step
+ * with no such ordering constraint calls {@link waitForNewDeployment}
+ * instead, never this plus {@link waitForHealthyVersion} by hand.
+ */
+export declare function waitForDeploymentFinished(coolify: DeployAndWaitPort, appId: string, runtime: DeployHealthRuntime, label: string, appliedRefDescription: string): Promise<void>;
+/**
+ * Phase 2 alone: the health check named by `health.kind`, with no deploy and
+ * no Coolify polling -- see {@link waitForDeploymentFinished}'s own doc
+ * comment for when a step calls this separately instead of
+ * {@link waitForNewDeployment}. A `'deployment-only'` check is a no-op here
+ * by design: phase 1 was already the whole answer for it.
+ */
+export declare function waitForHealthyVersion(appId: string, health: DeployHealthCheck, runtime: DeployHealthRuntime, sleep: (ms: number) => Promise<void>, label: string, appliedRefDescription: string): Promise<void>;
+/**
+ * Deploys `appId` and does not return until Coolify's own deployment record
+ * says it finished *and* `health` confirms the new version is answering --
+ * {@link waitForDeploymentFinished} then {@link waitForHealthyVersion}, in
+ * that order, for a step with no reason to run anything between them. See
+ * this module's own doc comment for why each half exists; `label` names the
+ * step in every error (`platform:mail`, …) and `appliedRefDescription` names
+ * what is still live so a caller's error is actionable without the helper
+ * itself knowing any step's scope keys.
+ */
+export declare function waitForNewDeployment(coolify: DeployAndWaitPort, appId: string, health: DeployHealthCheck, runtime: DeployHealthRuntime, sleep: (ms: number) => Promise<void>, label: string, appliedRefDescription: string): Promise<void>;

package/dist/plan/deploy-health.js

@@ -0,0 +1,153 @@
+/**
+ * #252: the one shared helper every platform step calls between deploying a
+ * new version and recording it as the applied ref.
+ *
+ * Before this, a step that records `platform:*`'s applied hostname/gitRef
+ * called `CoolifyPort.deploy` -- fire-and-forget by design (see its own doc
+ * comment) -- and recorded the new ref right after, with nothing in between
+ * proving the new version had actually landed. A failed deploy leaves the
+ * previous container running and healthy (`@wtfalch/providers`'
+ * `CoolifyDeploymentRecord` doc comment: "`status` reports on the container
+ * that is *running*, and a failed build leaves the previous one running and
+ * healthy"), so the old container's healthy status was being read as the
+ * new deployment's -- exactly what `CLAUDE.md`'s platform-step rule 5 ("no
+ * waiting forever... an old healthy status is never read as the new one")
+ * exists to forbid.
+ *
+ * {@link waitForNewDeployment} closes that gap in two steps, always in this
+ * order:
+ *
+ * 1. `coolify.deployAndWait` -- blocks until *Coolify's own deployment
+ *    record* (not `getApplication`'s live container status) reaches a
+ *    terminal state. Anything but `'finished'` throws immediately: a build
+ *    or deploy failure is a hard stop no health check below could ever
+ *    paper over, and it is the step that actually catches "the old
+ *    container stays healthy while the deployment fails" -- the container's
+ *    own status never moves in that scenario, so only the deployment record
+ *    itself tells the two apart.
+ * 2. The health check named by `health.kind`, decided per call site and
+ *    stated there (#252's own decision):
+ *    - `'version'` -- the service's health response carries a version
+ *      string this service actually exposes; polled until it matches
+ *      `health.expected` exactly. Unambiguous proof it is the *new*
+ *      version specifically, but only usable where the service has one.
+ *    - `'ready'` -- the health url answers 2xx. Works for every service
+ *      with a url this helper's caller can actually reach, including ones
+ *      with no version field (the fallback, not the preferred mode), and
+ *      the old-container loophole this mode alone cannot close ("can be
+ *      fooled by the old container staying up") is already closed by step
+ *      1 having confirmed Coolify's own deployment record finished first.
+ *    - `'deployment-only'` -- no health check at all; step 1 is the whole
+ *      answer. For a step whose app has nothing public wired (no Coolify
+ *      `domains`, tunnel, DNS record -- `platform:ai`/`platform:files`'
+ *      own doc comments say so explicitly) there is no url this helper's
+ *      caller, running outside that app's own Docker network, could ever
+ *      reach, so inventing one to poll would just be a slower, flakier way
+ *      of saying "I called deployAndWait". A step that can only use this
+ *      mode is not unverified the way `'ready'` is *within* `'ready'`'s own
+ *      guarantee -- it is strictly weaker than the other two (a deployment
+ *      that "finished" with a crash-looping container is read as success),
+ *      but it is the one honest answer this helper can give it, and it is
+ *      still what catches #252's named failure (the old container staying
+ *      healthy while the deployment record itself fails), since that
+ *      record is exactly what step 1 reads.
+ *
+ * Throws on any failure -- the deployment itself, or the health check
+ * timing out -- naming `appliedRefDescription` (what is still live, for
+ * whoever reads the error) so the caller's own "record applied ref" line is
+ * never reached. Rule 1 from `CLAUDE.md` applies here too: never call this
+ * from inside a retry loop that could mint a one-time secret again, since a
+ * failed wait is meant to be repaired by re-running the whole step, not
+ * silently retried from inside it.
+ */
+const DEFAULT_READY_TIMEOUT_MS = 300_000;
+const DEFAULT_READY_INTERVAL_MS = 5_000;
+/** The one terminal `CoolifyDeploymentStatus` that means the new version landed. */
+const DEPLOYMENT_SUCCEEDED = 'finished';
+/**
+ * Phase 1 alone: deploys `appId` and blocks until Coolify's own deployment
+ * record reaches a terminal state, throwing unless it is `'finished'`. Split
+ * out of {@link waitForNewDeployment} for a step whose health url only
+ * resolves once *later* work in the same step (archon's/mail's own tunnel
+ * and DNS wiring) has run -- that work must happen between this call and
+ * {@link waitForHealthyVersion}, so the two cannot be one call there. A step
+ * with no such ordering constraint calls {@link waitForNewDeployment}
+ * instead, never this plus {@link waitForHealthyVersion} by hand.
+ */
+export async function waitForDeploymentFinished(coolify, appId, runtime, label, appliedRefDescription) {
+    let result;
+    try {
+        result = await coolify.deployAndWait(appId, {
+            force: runtime.deployForce ?? true,
+            attempts: runtime.deployAttempts,
+            intervalMs: runtime.deployIntervalMs,
+        });
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`${label}: the deployment of ${appId} did not finish (${reason}); ${appliedRefDescription}. Apply again`);
+    }
+    const { status, deploymentUuid } = result;
+    if (status !== DEPLOYMENT_SUCCEEDED) {
+        throw new Error(`${label}: the deployment (${deploymentUuid}) of ${appId} did not finish (status: ${status}); ${appliedRefDescription}. Apply again`);
+    }
+}
+/**
+ * Phase 2 alone: the health check named by `health.kind`, with no deploy and
+ * no Coolify polling -- see {@link waitForDeploymentFinished}'s own doc
+ * comment for when a step calls this separately instead of
+ * {@link waitForNewDeployment}. A `'deployment-only'` check is a no-op here
+ * by design: phase 1 was already the whole answer for it.
+ */
+export async function waitForHealthyVersion(appId, health, runtime, sleep, label, appliedRefDescription) {
+    if (health.kind === 'deployment-only')
+        return;
+    const fetchImpl = runtime.fetch ?? globalThis.fetch;
+    const now = runtime.now ?? Date.now;
+    const timeout = runtime.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    const interval = runtime.readyIntervalMs ?? DEFAULT_READY_INTERVAL_MS;
+    const deadline = now() + timeout;
+    for (;;) {
+        if (await matchesHealth(fetchImpl, health))
+            return;
+        if (now() >= deadline) {
+            const detail = health.kind === 'version'
+                ? `never answered version "${health.expected}" at ${health.url}`
+                : `never answered 2xx at ${health.url}`;
+            throw new Error(`${label}: ${appId} ${detail} within ${Math.round(timeout / 1000)}s; ${appliedRefDescription}. Apply again`);
+        }
+        await sleep(interval);
+    }
+}
+/**
+ * Deploys `appId` and does not return until Coolify's own deployment record
+ * says it finished *and* `health` confirms the new version is answering --
+ * {@link waitForDeploymentFinished} then {@link waitForHealthyVersion}, in
+ * that order, for a step with no reason to run anything between them. See
+ * this module's own doc comment for why each half exists; `label` names the
+ * step in every error (`platform:mail`, …) and `appliedRefDescription` names
+ * what is still live so a caller's error is actionable without the helper
+ * itself knowing any step's scope keys.
+ */
+export async function waitForNewDeployment(coolify, appId, health, runtime, sleep, label, appliedRefDescription) {
+    await waitForDeploymentFinished(coolify, appId, runtime, label, appliedRefDescription);
+    await waitForHealthyVersion(appId, health, runtime, sleep, label, appliedRefDescription);
+}
+async function matchesHealth(fetchImpl, health) {
+    try {
+        const response = await fetchImpl(health.url);
+        if (!response.ok)
+            return false;
+        if (health.kind === 'ready')
+            return true;
+        const body = await response.json().catch(() => undefined);
+        const value = body && typeof body === 'object'
+            ? body[health.field ?? 'version']
+            : undefined;
+        return value === health.expected;
+    }
+    catch {
+        // Not up yet: DNS, the tunnel, the container, or a transient network error.
+        return false;
+    }
+}

package/dist/plan/diff.js

@@ -10,6 +10,7 @@ import { LOGIN_BINDING_SCOPE_KEY, loginBindingState, loginHostClientIds, loginHo
 import { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, parseMailCopyCompleted, } 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, appEnvAppliedScopeKey, appSettingsOf, appStepKey, appliedAppDomains, appliedAppSettings, dbEnvAppliedScopeKey, resolveAppEnv, versionNotAppliedLine, } from './platform-diff.js';
 import { DEFAULT_ORG_PLATFORM_READINESS } from './platform-org.js';
+import { PLATFORM_AUTH_BROKER_MAIL_KEY_REF } from './platform-providers.js';
 import { appLabelsAppliedScopeKey, entryLabelHash, entryLabelSpec } from './proxy-labels.js';
 /** The `Plan` (#19's public contract) a `PlanDetail` carries. */
 export function toPlan(detail) {
@@ -82,7 +83,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     const issuer = planIssuer(org, byKey, claimed, platformReadiness.authReady);
     if (issuer.step)
         plannedSteps.push(issuer.step);
-    plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady));
+    plannedSteps.push(...planOwners(org, recordedIds, platformReadiness.authReady, 'error' in agoraHost ? null : agoraHost.issuer));
     // #267: after the ZITADEL org step, before any app's own issuer
     // application. Apps created later in this run are not in the binding yet;
     // the next run replans this step and repoints them.
@@ -188,7 +189,7 @@ export function computePlanDetail(org, live, recordedIds = {}, agoraHost = NO_AG
     if (database)
         plannedSteps.push(database);
     const authIssuer = 'error' in agoraHost ? null : agoraHost.issuer;
-    const app = planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer);
+    const app = planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, platformReadiness);
     plannedSteps.push(...app.steps);
     // After the apps: the broker entry's key is minted into each app's env.
     const brokerEntries = planBrokerEntries(org, recordedIds, plannedSteps, options.broker ?? false);
@@ -433,7 +434,7 @@ function planIssuer(org, byKey, claimed, authReady) {
  * nothing here puts it anywhere beyond what audit already records for the
  * org.
  */
-function planOwners(org, recordedIds, authReady) {
+function planOwners(org, recordedIds, authReady, authIssuer) {
     // #177: nothing to invite into yet -- `planIssuer` already reports the
     // platform's sign-in as blocked, so these steps stay silent rather than
     // repeating it.
@@ -455,6 +456,8 @@ function planOwners(org, recordedIds, authReady) {
                     email: owner.email,
                     givenName: owner.givenName,
                     familyName: owner.familyName,
+                    // The platform's login app, where the invite link must land (it serves `/verify`).
+                    ...(authIssuer ? { authIssuer } : {}),
                 },
             },
             step: {
@@ -1004,6 +1007,16 @@ function notReadyReason(service, keyName, missingKeyRef, noKeyReader) {
  * own files host (#171) is off or not yet applied, so there is nothing here
  * for `FilesOrganisationPort.provisionOrganisation` to reach.
  *
+ * F6b: `shareHost` is `share.<domain>` when any entry declares
+ * `uses.files.shareHost`, else `null`. It is passed to the provision call
+ * every time, so files always knows the name an org wants. The route and
+ * DNS come from `tunnelIngressHostnames`; `planFilesKeys` warns that the
+ * platform files runner must serve the host too. Computed once, at the only point `provisionOrganisation`
+ * is ever planned (nothing to diff once the organisation is live, same as
+ * `ceilingBytes`/`ceilingMicros` above): a `shareHost` declared after the
+ * organisation already exists needs its own follow-up, matching every other
+ * field on this singleton step.
+ *
  * #273: `desired.agoraOrigin` is every org's own Agora origin (#164's
  * `agoraHostnameFor`, always on, never blocked on anything this step
  * doesn't already wait for) -- `executor.ts`'s `filesOrganisation` adds it
@@ -1026,6 +1039,9 @@ function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, n
             blocked: `${org.slug}'s Files organisation is blocked, not planned: ${notReadyReason('files', 'files management key', missingKeyRef, noKeyReader)}`,
         };
     }
+    const shareHost = org.domain && org.hosting.entries.some((e) => e.uses?.files?.shareHost)
+        ? `share.${org.domain}`
+        : null;
     return {
         step: {
             action: {
@@ -1036,6 +1052,7 @@ function planFilesOrganisation(org, byKey, claimed, filesReady, missingKeyRef, n
                     provision: true,
                     ceilingBytes: null,
                     ceilingMicros: null,
+                    shareHost,
                     agoraOrigin: `https://${agoraHostnameFor(org)}`,
                 },
             },
@@ -1636,7 +1653,7 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
  * resource's `enabled` field -- a live resource nothing has actually
  * checked yet is assumed fine rather than replanned every time.
  */
-function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
+function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authIssuer, readiness) {
     // #243: an `appEnv` source with no recorded value and no step planned to
     // record one this run has nothing to push, now or after this apply.
     const sourceStep = {
@@ -1651,9 +1668,12 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
     // other entry is named in them.
     const label = entryKey === APP_ENTRY_KEY ? 'app' : `${entryKey} app`;
     const blockedKey = (rest) => entryKey === APP_ENTRY_KEY ? `coolify:app:${rest}` : `coolify:app:${entryKey}:${rest}`;
-    const { values: wantedEnv, unresolved } = entry
-        ? resolveAppEnv(org, entry, recordedIds)
-        : { values: {}, unresolved: [] };
+    const { marker: wantedEnv, unresolved, unresolvedSecrets, } = entry
+        ? resolveAppEnv(org, entry, recordedIds, {
+            platformMailKey: readiness.mailKeyHeld === true,
+            sharedSecret: readiness.canHoldSecrets === true,
+        })
+        : { marker: {}, unresolved: [], unresolvedSecrets: [] };
     const stepKey = appStepKey(org, entryKey);
     const blocked = entry
         ? unresolved
@@ -1663,6 +1683,14 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
             description: `${org.slug}'s ${label} env ${name} is blocked, not planned: its source ${source} has no recorded value yet`,
             key: blockedKey(`env:${name}`),
         }))
+            .concat(
+        // Never a value: the ref of the missing key, or what the host lacks.
+        unresolvedSecrets.map(([name, source]) => ({
+            description: `${org.slug}'s ${label} env ${name} is blocked, not planned: ${source === 'platformMailKey'
+                ? `the platform's Lettermint key is not held yet (held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`
+                : `its source ${source} needs a held-key store that can put, and the host has none`}`,
+            key: blockedKey(`env:${name}`),
+        })))
         : [];
     const toggled = planHostingToggle('coolify', 'app', entry !== undefined, org, byKey, claimed, () => `provision ${org.slug}'s ${label}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
     if (toggled)
@@ -1825,7 +1853,7 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
  * {@link planApp} once per hosting entry. A key with no declared entry still
  * runs for `app`, so an org that turns hosting off parks the app it has live.
  */
-function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
+function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer, readiness) {
     const steps = [];
     const blocked = [];
     // An entry removed from the list while its app is recorded is parked like a
@@ -1846,8 +1874,21 @@ function planApps(org, byKey, claimed, recordedIds, plannedSteps, authIssuer) {
             if (!resource || (typeof status === 'string' && /^(exited|stopped)/.test(status)))
                 continue;
         }
-        const app = planApp(org, key, byKey, claimed, recordedIds, plannedSteps, authIssuer);
+        const app = planApp(org, key, byKey, claimed, recordedIds, plannedSteps, authIssuer, readiness);
         // The executor pushes the issuer the plan read, the way Agora gets its host values.
+        // The same availability the plan's marker used: the executor records its
+        // marker from this, never from its own port, so the two cannot disagree.
+        const usesSecrets = org.hosting.entries.some((e) => e.key === key &&
+            Object.values(e.env).some((v) => typeof v !== 'string' && (v.from === 'sharedSecret' || v.from === 'platformMailKey')));
+        if (usesSecrets && app.step && app.step.action.desired.enabled !== false) {
+            app.step.action.desired = {
+                ...app.step.action.desired,
+                secretSources: {
+                    platformMailKey: readiness.mailKeyHeld === true,
+                    sharedSecret: readiness.canHoldSecrets === true,
+                },
+            };
+        }
         if (app.step && app.step.action.desired.enabled !== false) {
             const signsIn = org.hosting.entries.some((e) => e.key === key && e.uses?.auth);
             if (signsIn)

package/dist/plan/entry-files-key.d.ts

@@ -56,8 +56,10 @@ export interface EntryFilesWant {
     permissions: string[];
     collections: string[];
     filesUrl: string;
+    /** `https://share.<domain>`, set only when the entry declares `shareHost`. */
+    shareOrigin?: string;
 }
-export declare function wantedEntryFiles(entry: HostingEntry, filesUrl: string): EntryFilesWant;
+export declare function wantedEntryFiles(entry: HostingEntry, filesUrl: string, shareHostname?: string | null): EntryFilesWant;
 export type EntryFilesMode = 'mint' | 'renew' | 'settings' | 'finish' | 'retire';
 type Blocked = Array<{
     description: string;

package/dist/plan/entry-files-key.js

@@ -1,4 +1,5 @@
 import { FILES_ENTRY_PERMISSIONS } from '../org.js';
+import { filesShareHostname } from './hostnames.js';
 import { appStepKey } from './platform-diff.js';
 /**
  * F6b: the org's own files key, minted below the files organisation's
@@ -67,12 +68,13 @@ export function filesOwnerUserId(org, recordedIds) {
     const first = org.owners[0];
     return first ? recordedIds[`zitadel:owner:${org.id}:${first.email.toLowerCase()}`] : undefined;
 }
-export function wantedEntryFiles(entry, filesUrl) {
+export function wantedEntryFiles(entry, filesUrl, shareHostname = null) {
     const files = entry.uses?.files;
     return {
         permissions: [...(files?.permissions ?? FILES_ENTRY_PERMISSIONS)],
         collections: [...(files?.collections ?? [])],
         filesUrl,
+        ...(files?.shareHost && shareHostname ? { shareOrigin: `https://${shareHostname}` } : {}),
     };
 }
 /**
@@ -157,14 +159,9 @@ export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
     }
     if (entries.length === 0 || !readiness.filesReady)
         return { steps, blocked };
-    for (const entry of entries) {
-        if (entry.uses?.files?.shareHost) {
-            blocked.push({
-                description: `${org.slug}'s ${entry.key} share host is blocked: the platform's files host has no route for share.<domain> yet, so FILES_SHARE_ORIGIN is not delivered`,
-                key: `files:share:${org.id}:${entry.key}`,
-            });
-        }
-    }
+    // The route and DNS for share.<domain> are planned with the tunnel; the org
+    // apply then gives the platform files runner the host (`FoundryPlanApply.apply`).
+    const shareHostname = filesShareHostname(org);
     // The org's own key: minted, or renewed when it is short or its expiry is unknown.
     const rootBlock = (why) => blocked.push({
         description: `${org.slug}'s own files key is blocked: ${why}`,
@@ -244,7 +241,7 @@ export function planFilesKeys(org, recordedIds, plannedSteps, readiness, now) {
             block("the entry's app is not recorded yet");
             continue;
         }
-        const want = wantedEntryFiles(entry, readiness.filesUrl);
+        const want = wantedEntryFiles(entry, readiness.filesUrl, shareHostname);
         const applied = recordedIds[entryFilesAppliedScopeKey(entry.key)];
         const wantJson = JSON.stringify(want);
         let mode = null;