@wtfalch/foundry 0.69.0 → 0.70.1

package/dist/plan/executor.js

@@ -35,7 +35,7 @@ import { DESKTOP_AUTH_APP_SCOPE_KEY, DESKTOP_AUTH_DEPLOYED_SCOPE_KEY, DESKTOP_AU
 import { desktopCallbackUri, signInCallbackAppliedValue, signInRedirectUris, unionRedirectUris, zitadelAppDesktopCallbackAppliedScopeKey, } from './desktop-callback.js';
 import { PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, onPlatformNetwork, placed, placedByScope, placedOnPlatform, } from './destinations.js';
 import { DEFAULT_AI_LIMIT_MICROS } from './diff.js';
-import { createEdgeAccess, isNotFound as isEdgeNotFound, } from './edge-access.js';
+import { createEdgeAccess, edgeTooOld, isNotFound as isEdgeNotFound, } from './edge-access.js';
 import { EDGE_DNS_WRITE_CONCURRENCY, createEdgeDns, limiter, } from './edge-dns.js';
 import { createEdgeRateLimits, } from './edge-ratelimits.js';
 import { createEdgeTunnels } from './edge-tunnels.js';
@@ -43,6 +43,7 @@ import { createEdgeZones } from './edge-zones.js';
 import { AI_ENTRY_KEY_DAYS, AI_ENTRY_RENEW_WINDOW_DAYS, entryAiAppliedScopeKey, entryAiClampedScopeKey, entryAiExpiresScopeKey, entryAiPendingExpiresScopeKey, entryAiRetiredScopeKey, entryAiUndeliveredScopeKey, entryAiUnrevokedScopeKey, entryAiWebhookPendingScopeKey, entryAiWrittenScopeKey, parseIdList, } from './entry-ai-key.js';
 import { ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS, entryAnalyticsAppliedScopeKey, entryAnalyticsRetiredScopeKey, entryAnalyticsUndeliveredScopeKey, stageAnalyticsKeyName, } from './entry-analytics-key.js';
 import { applyEntryAudit } from './entry-audit.js';
+import { AUTH_EVENTS_ENV, authEventsAppliedScopeKey, authEventsMarker, authEventsWanted, ensureAuthEventsSecret, heldAuthEventsSecret, } from './entry-auth-events.js';
 import { CUSTOMER_GRANTS_CREDENTIAL_ENV, CUSTOMER_GRANTS_ENV, CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY, customerGrantsEntries, customerGrantsJson, customerGrantsMintedScopeKey, customerGrantsRef, customerGrantsToDrop, ensureCustomerGrantsCredential, wantedCustomerGrants, } from './entry-customer-grants.js';
 import { BOULE_EDGE_ENTRY_KEY, EDGE_ENTRY_KEY_DAYS, EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY, EDGE_SLUG_APPLIED_SCOPE_KEY, ENTRY_EDGE_KEY_DELIVERY_ATTEMPTS, bouleEdgeKeyWanted, edgeKeyAppRecordKey, edgeKeyDomain, entryEdgeMintedAtScopeKey, entryEdgeRetiredScopeKey, entryEdgeUndeliveredScopeKey, } from './entry-edge-key.js';
 import { FILES_AGORA_KEY_SCOPE_KEY, FILES_AGORA_UNDELIVERED_SCOPE_KEY, FILES_KEY_DAYS, FILES_KEY_RENEW_WINDOW_DAYS, FILES_ORG_OWNER_SCOPE_KEY, FILES_ROOT_EXPIRES_SCOPE_KEY, FILES_ROOT_PREVIOUS_SCOPE_KEY, FILES_ROOT_UNDELIVERED_SCOPE_KEY, FILES_ROOT_UNREVOKED_SCOPE_KEY, entryFilesAppliedScopeKey, entryFilesExpiresScopeKey, entryFilesMinterScopeKey, entryFilesPendingExpiresScopeKey, entryFilesRetiredScopeKey, entryFilesUndeliveredScopeKey, entryFilesUnrevokedScopeKey, entryFilesWrittenScopeKey, filesOwnerUserId, parseIdList as parseFilesIdList, } from './entry-files-key.js';
@@ -3485,6 +3486,21 @@ export class FoundryStepExecutor {
             });
             env.push({ key: 'WORKSPACES_API_KEY', value: workspacesKey });
         }
+        if (authEventsWanted(entry)) {
+            env.push({
+                key: AUTH_EVENTS_ENV,
+                value: await ensureAuthEventsSecret({
+                    orgId: org.id,
+                    slug: org.slug,
+                    entryKey: workspaceClientKey(entry.key),
+                    heldKeys,
+                    recorded: () => context.recordedIds(),
+                    record: (key, value) => context.recordScopeId(key, value),
+                    persist: () => context.persistScopeIds(),
+                    secret: (value) => void this.handledSecrets.add(value),
+                }),
+            });
+        }
         const workspacesKeys = [];
         for (const live of org.hosting.entries.filter((e) => e.uses?.auth?.workspaces)) {
             const value = await heldKeys?.resolve(workspacesKeyRef(org.id, live.key));
@@ -3537,7 +3553,10 @@ export class FoundryStepExecutor {
         }
         this.handledSecrets.add(appKey);
         const clientKey = workspaceClientKey(entry.key);
-        await this.writeAppBrokerEntry(org, broker, clientKey, wanted.want, appKey, context, wanted.want.workspaces ? await this.workspacesInputs(org, clientKey) : {});
+        await this.writeAppBrokerEntry(org, broker, clientKey, wanted.want, appKey, context, {
+            ...(wanted.want.workspaces ? await this.workspacesInputs(org, clientKey) : {}),
+            ...(await this.eventsInput(org, clientKey, wanted.want)),
+        });
         return {};
     }
     /**
@@ -4336,6 +4355,7 @@ export class FoundryStepExecutor {
         context.recordScopeId(appEnvAppliedScopeKey(entry.key), appEnv.applied);
         if (entry.uses?.auth) {
             context.recordScopeId(entryAuthEnvAppliedScopeKey(entry.key), appEnv.authApplied);
+            context.recordScopeId(authEventsAppliedScopeKey(entry.key), appEnv.eventsApplied);
         }
         if (dbPush.pushed)
             context.recordScopeId(dbEnvAppliedScopeKey(entry.key), '1');
@@ -4948,6 +4968,22 @@ export class FoundryStepExecutor {
                 });
                 envs.push({ key: 'WORKSPACES_API_KEY', value: workspacesKey });
             }
+            if (authEventsWanted(entry)) {
+                const eventsSecret = await ensureAuthEventsSecret({
+                    orgId: org.id,
+                    slug: org.slug,
+                    entryKey: entry.key,
+                    heldKeys: this.ports.heldKeys,
+                    recorded: () => context.recordedIds(),
+                    record: (key, value) => context.recordScopeId(key, value),
+                    persist: () => context.persistScopeIds(),
+                    secret: (value) => void this.handledSecrets.add(value),
+                });
+                envs.push({ key: AUTH_EVENTS_ENV, value: eventsSecret });
+            }
+            else if (recorded[authEventsAppliedScopeKey(entry.key)] === 'on') {
+                await this.dropAuthEventsEnv(appId);
+            }
         }
         else {
             const zitadelOrgId = recorded.zitadel_org;
@@ -5024,11 +5060,28 @@ export class FoundryStepExecutor {
             changed: applied !== (recorded[appEnvAppliedScopeKey(entry.key)] ?? '{}') ||
                 heldChanged ||
                 (Boolean(entry.uses?.auth) &&
-                    authApplied !== (recorded[entryAuthEnvAppliedScopeKey(entry.key)] ?? '{}')),
+                    (authApplied !== (recorded[entryAuthEnvAppliedScopeKey(entry.key)] ?? '{}') ||
+                        authEventsMarker(entry) !== (recorded[authEventsAppliedScopeKey(entry.key)] ?? ''))),
             applied,
             authApplied,
+            eventsApplied: authEventsMarker(entry),
         };
     }
+    /** Takes `AUTH_EVENTS_SECRET` out of the app's env once the entry stops declaring events. The held value stays: the held store has no delete. */
+    async dropAuthEventsEnv(appId) {
+        const rows = await this.ports.coolify.listEnvs(appId);
+        for (const row of rows) {
+            if (row.key !== AUTH_EVENTS_ENV || !row.uuid)
+                continue;
+            try {
+                await this.ports.coolify.deleteEnv(appId, row.uuid);
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+    }
     /**
      * The install's edge label token: read from the held keys, else minted and held first, so a crash
      * after the `put` hands the same value out on the next apply. Read once more after the `put`, so two
@@ -5133,7 +5186,9 @@ export class FoundryStepExecutor {
         if (entry.workerApp) {
             // No Coolify app: the key is the held AUTH_APP_KEY the Worker app was given.
             const heldKey = await heldBrokerKey(this.ports.heldKeys, org, entry.key);
-            await this.writeAppBrokerEntry(org, broker, entry.key, wanted.want, heldKey, context);
+            await this.writeAppBrokerEntry(org, broker, entry.key, wanted.want, heldKey, context, {
+                ...(await this.eventsInput(org, entry.key, wanted.want)),
+            });
             return {};
         }
         const appId = recorded[`coolify:app:${action.key}`];
@@ -5144,9 +5199,20 @@ export class FoundryStepExecutor {
         if (!appKey || appKey.length < 32) {
             throw new Error(`coolify:broker-entry for ${org.slug}: app ${appId} has no AUTH_APP_KEY yet`);
         }
-        await this.writeAppBrokerEntry(org, broker, entry.key, wanted.want, appKey, context, wanted.want.workspaces ? await this.workspacesInputs(org, entry.key) : {});
+        await this.writeAppBrokerEntry(org, broker, entry.key, wanted.want, appKey, context, {
+            ...(wanted.want.workspaces ? await this.workspacesInputs(org, entry.key) : {}),
+            ...(await this.eventsInput(org, entry.key, wanted.want)),
+        });
         return {};
     }
+    /** The held events secret of a broker entry that declares events, registered for redaction; nothing when it declares none. */
+    async eventsInput(org, entryKey, want) {
+        if (!want.mcp?.events)
+            return {};
+        const eventsSecret = await heldAuthEventsSecret(this.ports.heldKeys, org, entryKey);
+        this.handledSecrets.add(eventsSecret);
+        return { eventsSecret };
+    }
     /**
      * What the broker entry needs beyond its want when it declares workspaces: the hash of the held key (the key
      * itself is registered for redaction and goes no further) and the operator's held database connection string.
@@ -5234,13 +5300,13 @@ export class FoundryStepExecutor {
         return {};
     }
     /** The shared tail of both broker-entry steps: read the app's key, write the entry, record what was written. */
-    async writeAppBrokerEntry(_org, broker, entryKey, want, appKey, context, workspaces = {}) {
+    async writeAppBrokerEntry(_org, broker, entryKey, want, appKey, context, extra = {}) {
         const previousRaw = context.recordedIds()[brokerEntryAppliedScopeKey(entryKey)];
         const result = await writeBrokerEntry(broker, {
             want,
             appKey,
             previous: previousRaw ? JSON.parse(previousRaw) : null,
-            ...workspaces,
+            ...extra,
         });
         context.recordScopeId(brokerEntryWarningsScopeKey(entryKey), JSON.stringify(result.invalidForeign));
         // Last: a run that failed above plans the step again.
@@ -10787,6 +10853,7 @@ export class FoundryStepExecutor {
                     await edge.revokeKey(org.id, id);
                 }
                 catch (error) {
+                    edgeTooOld(error, at);
                     // A 404 means it is already gone -- recorded as retired below,
                     // the same as a successful revoke. Anything else is a real
                     // failure: thrown, not swallowed, so the key stays live and the
@@ -10856,18 +10923,26 @@ export class FoundryStepExecutor {
                 await edge.revokeKey(org.id, staleUndelivered);
             }
             catch (error) {
+                edgeTooOld(error, at);
                 if (!isNotFoundError(error))
                     throw error;
             }
             context.recordScopeId(entryEdgeUndeliveredScopeKey(entryKey), '');
             await context.persistScopeIds();
         }
-        const minted = await edge.mintKey({
-            organisationId: org.id,
-            domain: edgeKeyDomain(org),
-            name: desired.name,
-            expiresDays: EDGE_ENTRY_KEY_DAYS,
-        });
+        let minted;
+        try {
+            minted = await edge.mintKey({
+                organisationId: org.id,
+                domain: edgeKeyDomain(org),
+                name: desired.name,
+                expiresDays: EDGE_ENTRY_KEY_DAYS,
+            });
+        }
+        catch (e) {
+            edgeTooOld(e, at);
+            throw e;
+        }
         context.recordScopeId(entryEdgeUndeliveredScopeKey(entryKey), minted.id);
         await context.persistScopeIds();
         const envs = [
@@ -11028,6 +11103,7 @@ export class FoundryStepExecutor {
             await edge.setOrganisationSlug(org.id, slug);
         }
         catch (e) {
+            edgeTooOld(e, `edge:slug for ${org.slug}`);
             if (e instanceof EdgeApiError && e.code === 'conflict') {
                 throw new Error(`edge:slug for ${org.slug} is blocked: edge says another company already holds the slug '${slug}', so its platform hostnames cannot be accepted; change the slug`);
             }
@@ -11047,7 +11123,13 @@ export class FoundryStepExecutor {
             throw new Error(`edge:reserved-labels for ${org.slug}: this executor was built without an EdgePort (#317)`);
         }
         const labels = action.desired.labels;
-        await edge.setReservedLabels(org.id, labels);
+        try {
+            await edge.setReservedLabels(org.id, labels);
+        }
+        catch (e) {
+            edgeTooOld(e, `edge:reserved-labels for ${org.slug}`);
+            throw e;
+        }
         context.recordScopeId(EDGE_RESERVED_LABELS_APPLIED_SCOPE_KEY, JSON.stringify(labels));
         return {};
     }
@@ -11592,6 +11674,7 @@ export class FoundryStepExecutor {
                         await edge.revokeKey(org.id, target.id);
                     }
                     catch (error) {
+                        edgeTooOld(error, `edge:key '${target.key}' for ${org.slug}`);
                         // Already gone -- the same already-retired key a retire step
                         // handled before org destroy ever ran can still reach here
                         // (#317 review); a 404 is success, not a reason to block

package/dist/plan/machine-paths.d.ts

@@ -2,7 +2,7 @@ import { type DeclaredOrg, type HostingEntry } from '../org.js';
 import type { DraftStep } from './diff.js';
 /**
  * F11: the paths of a gated entry that a machine calls, not a person: the ai service posts to
- * `uses.ai.webhookPath`, Boule calls `/api/customer-grants`. A gate (`gates.ts`) stops a machine, so each of
+ * `uses.ai.webhookPath`, Boule calls `/api/customer-grants`, the broker posts signed assistant events to `uses.auth.mcp.events.path`. A gate (`gates.ts`) stops a machine, so each of
  * these paths on each gated host gets its own path-scoped Access application (`<host><path>`) with a bypass
  * policy, the opposite of a private page's path gate. Cloudflare applies the most specific application, so
  * the bypass wins over the host's whole-host gate. The app itself checks the machine's credential.

package/dist/plan/machine-paths.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { isEdgePath } from '../entry-rules.js';
 import { isLiveEntry } from '../org.js';
 import { resolveGateHostnames } from './gates.js';
 import { entryHostnames, workspaceHost } from './hostnames.js';
@@ -6,7 +7,7 @@ import { appStepKey } from './platform-diff.js';
 import { workspaceEntries } from './workspace.js';
 /**
  * F11: the paths of a gated entry that a machine calls, not a person: the ai service posts to
- * `uses.ai.webhookPath`, Boule calls `/api/customer-grants`. A gate (`gates.ts`) stops a machine, so each of
+ * `uses.ai.webhookPath`, Boule calls `/api/customer-grants`, the broker posts signed assistant events to `uses.auth.mcp.events.path`. A gate (`gates.ts`) stops a machine, so each of
  * these paths on each gated host gets its own path-scoped Access application (`<host><path>`) with a bypass
  * policy, the opposite of a private page's path gate. Cloudflare applies the most specific application, so
  * the bypass wins over the host's whole-host gate. The app itself checks the machine's credential.
@@ -21,17 +22,16 @@ export function entryMachinePaths(entry) {
         paths.push(webhook);
     if (entry.uses?.customerGrants)
         paths.push(CUSTOMER_GRANTS_PATH);
+    const events = entry.uses?.auth?.mcp?.events?.path;
+    if (events !== undefined)
+        paths.push(events);
     return [...new Set(paths)];
 }
 /** The step key stem of one machine bypass: a hash of host and path, so it fits a key and needs no escaping. */
 export function machineBypassKey(host, path) {
     return `mp-${createHash('sha256').update(`${host}\0${path}`).digest('hex').slice(0, 16)}`;
 }
-/** What edge accepts as the path of a destination: segments of `a-z 0-9 . _ ~ -`, none empty, `.` or `..`, at most 200 characters. */
-const EDGE_PATH = /^(\/[a-z0-9._~-]+)+$/;
-const edgeAccepts = (path) => path.length <= 200 &&
-    EDGE_PATH.test(path) &&
-    !path.split('/').some((s) => s === '.' || s === '..');
+const edgeAccepts = isEdgePath;
 /** The recorded `host/path` a machine bypass was made for, by its step key stem, read for the delete's wording. */
 export const machineBypassScopeKey = (stem) => `machine_bypass_${stem}`;
 /**

package/dist/plan/own-diff.js

@@ -11,7 +11,7 @@ import { ownHostnames } from './own-hostnames.js';
 import { JOBS_PUBLIC_URL_SCOPE_KEY, OWN_JOBS_ROUTE_TUNNEL_SCOPE_KEY } from './own-jobs-route.js';
 import { OWN_FILES_R2_SCOPE_KEY, OWN_SERVICES_APPLIED_SCOPE_KEY, orgTarget, } from './own-services.js';
 import { OWN_SFU_APPLIED_HOSTNAME_SCOPE_KEY, OWN_SFU_APPLIED_NODE_IP_SCOPE_KEY, OWN_SFU_APPLIED_SLOT_SCOPE_KEY, OWN_SFU_APPLIED_VERSION_SCOPE_KEY, OWN_SFU_DEPLOY_PENDING_SCOPE_KEY, OWN_SFU_KEYS_UNDELIVERED_SCOPE_KEY, SFU_INTERNAL_URL_SCOPE_KEY, SFU_PUBLIC_URL_SCOPE_KEY, } from './own-sfu.js';
-import { AUTH_TUNNEL_ROUTES_VERSION, AUTH_ZITADEL_RUN_OPTIONS, JOBS_DEPLOY_PENDING_SCOPE_KEY, JOBS_INTERNAL_URL_SCOPE_KEY, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_MCP_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, orgDeclaresMcp, platformMailMxHost, } from './platform-diff.js';
+import { AUTH_TUNNEL_ROUTES_VERSION, AUTH_ZITADEL_RUN_OPTIONS, JOBS_DEPLOY_PENDING_SCOPE_KEY, JOBS_INTERNAL_URL_SCOPE_KEY, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY, PLATFORM_AUTH_MCP_SCOPE_KEY, PLATFORM_AUTH_SMTP_SCOPE_KEY, PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, authLoginEnvMarker, orgDeclaresMcp, platformMailMxHost, } from './platform-diff.js';
 import { OWN_FILES_RUNNER_SCOPE_KEY } from './platform-org.js';
 import { JOBS_ADMIN_TOKEN_UNDELIVERED_SCOPE_KEY, JOBS_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_AUTH_DB_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_SCOPE_KEY, PLATFORM_FILES_SHARE_DOMAINS_SCOPE_KEY, filesShareDomains, } from './platform-providers.js';
 import { SIGN_IN_LOGIN_APP_SCOPE_KEY, inAppSignIn } from './sign-in.js';
@@ -217,6 +217,9 @@ export function planOwnAuth(options) {
         recordedIds[PLATFORM_AUTH_SMTP_SCOPE_KEY] &&
         recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS &&
         recordedIds[PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY] === AUTH_TUNNEL_ROUTES_VERSION &&
+        // The login apps' mail env (`LOGIN_MAIL_FROM`, the Lettermint key); a stack from before it is written again.
+        recordedIds[PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY] ===
+            authLoginEnvMarker(`noreply@${names.mailDomain}`) &&
         // The code mail carries the company's name and design; an older apply, or a renamed company, writes it again.
         (options.signinMailWritable === false ||
             recordedIds[PLATFORM_AUTH_SIGNIN_MAIL_SCOPE_KEY] === signinMailMarker(org.displayName)) &&

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

@@ -337,6 +337,8 @@ export interface PlatformStepExecutor {
         authExecutorMissing?: boolean;
         /** #216 round 5: see `PlanPlatformOptions.blocked.authOtherInputsMissing`. */
         authOtherInputsMissing?: string[];
+        /** The sealed mail key resolved: `planAuth` asks for the login env marker only when it did. */
+        authMailKeyHeld?: boolean;
         files?: string;
         integrations?: string;
         ai?: string;

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

@@ -68,6 +68,20 @@ export declare const PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY = "zitadel_plat
 export declare const AUTH_TUNNEL_ROUTES_VERSION = "2";
 /** The {@link AUTH_TUNNEL_ROUTES_VERSION} the sign-in tunnel was last written with. */
 export declare const PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY = "auth_tunnel_routes_applied";
+/**
+ * The version of the env `provisionAuthStack` writes to the login apps (`LOGIN_MAIL_FROM`,
+ * `LETTERMINT_API_TOKEN`). Raise it when a key is added or its meaning changes, so an applied
+ * sign-in plans its step once more and the apps get the env. Never holds a value.
+ * 1: the login apps send their own invite and verification mail (auth 0.35.0, foundry 0.68.0).
+ */
+export declare const AUTH_LOGIN_ENV_VERSION = "1";
+/**
+ * What the login apps' env is written for: the version and the sender address (`LOGIN_MAIL_FROM`).
+ * The address is no secret; a new mail domain gives a new marker, so the step is planned again.
+ */
+export declare function authLoginEnvMarker(smtpSender: string): string;
+/** The {@link authLoginEnvMarker} the login apps' env was last written with, once live on them. */
+export declare const PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY = "auth_login_env_applied";
 /**
  * `'1'` once the broker holds `MCP_DATABASE_URL` and `MCP_OAUTH_SECRET` (auth ADR 0002), recorded by the
  * sign-in step when an entry of that broker declares `uses.auth.mcp`. A broker entry with `mcp` is not
@@ -977,6 +991,8 @@ export declare const PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY = "edge_platform_k
  */
 export declare const PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY = "edge_applied_hostname";
 export declare const PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY = "edge_applied_git_ref";
+/** foundry#1024: what `provisionPlatformEdge` last wrote for {@link usageTailEdgeEnv}; see {@link usageTailEdgeEnvValue}. */
+export declare const PLATFORM_EDGE_APPLIED_USAGE_TAIL_SCOPE_KEY = "edge_applied_usage_tail";
 /**
  * F4.dns: where edge answers on the Coolify network
  * (`http://<custom_internal_name>:3000`), recorded by the edge step once the
@@ -1206,6 +1222,45 @@ export declare const PLATFORM_UPTIME_ACCESS_TOKEN_ID_SCOPE_KEY = "uptime_access_
 export declare function uptimeAccessTokenConflict(): string;
 /** Whether anything of the uptime Worker is recorded that disabling it must remove. */
 export declare function uptimeRecorded(recordedIds: Readonly<Record<string, string>>): boolean;
+/**
+ * foundry#1024: the usage tail Worker that meters every company Worker's
+ * use, one `cloudflare:worker` step keyed {@link PLATFORM_USAGE_TAIL_KEY}.
+ * `runPlatformSteps` records the script name under
+ * `cloudflare:worker:platform:usage-tail` once it succeeds, which is what
+ * stops `planUsageTail` planning it again.
+ */
+export declare const PLATFORM_USAGE_TAIL_KEY = "platform:usage-tail";
+/** The Worker script's name at Cloudflare. */
+export declare const PLATFORM_USAGE_TAIL_SCRIPT_NAME = "platform-usage-tail";
+/**
+ * The held ref of the Worker's one secret, `EDGE_USAGE_KEY` -- the narrow
+ * `usage:ingest` credential edge's ingest route accepts. Minted once (rule
+ * 1): the hash is never secret, so (the same pattern `provisionPlatformEdge`
+ * uses for `EDGE_PLATFORM_KEY_HASH`) it doubles as both the undelivered
+ * marker and the final recorded value, with nothing extra to compute or a
+ * live read that could fall back to a blank value.
+ */
+export declare const PLATFORM_USAGE_TAIL_KEY_REF = "usage-tail:worker:key";
+export declare const PLATFORM_USAGE_TAIL_KEY_UNDELIVERED_SCOPE_KEY = "usage_tail_key_undelivered";
+export declare const PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY = "usage_tail_key_set";
+export declare const PLATFORM_USAGE_TAIL_APPLIED_TAG_SCOPE_KEY = "usage_tail_applied_tag";
+export declare const PLATFORM_USAGE_TAIL_APPLIED_SHA256_SCOPE_KEY = "usage_tail_applied_sha256";
+export declare const PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY = "usage_tail_removed";
+/**
+ * What `platform:edge`'s own env should hold for the usage tail Worker
+ * (`USAGE_TAIL_WORKER`, `EDGE_USAGE_KEY_HASH`), or `null` while the Worker is
+ * not deployed or its key is not held yet. `provisionPlatformEdge` writes
+ * these two names on every run alongside `EDGE_PLATFORM_KEY_HASH`; `planEdge`
+ * reads {@link usageTailEdgeEnvValue} to replan edge once this changes.
+ */
+export declare function usageTailEdgeEnv(recordedIds: Readonly<Record<string, string>>): {
+    USAGE_TAIL_WORKER: string;
+    EDGE_USAGE_KEY_HASH: string;
+} | null;
+/** The value `provisionPlatformEdge` records once it has written {@link usageTailEdgeEnv} to edge's env; empty while there is nothing to write. */
+export declare function usageTailEdgeEnvValue(recordedIds: Readonly<Record<string, string>>): string;
+/** Whether anything of the usage tail Worker is recorded that disabling it must remove. */
+export declare function usageTailRecorded(recordedIds: Readonly<Record<string, string>>): boolean;
 /**
  * Options for {@link planPlatform}, replacing four positional arguments that
  * shifted on every merge that added a platform service (#186, #187, #188) --
@@ -1265,6 +1320,11 @@ export interface PlanPlatformOptions {
          * these. Default `[]`.
          */
         authOtherInputsMissing?: string[];
+        /**
+         * Whether the sealed Lettermint key resolved. `provisionAuthStack` records the login env marker only
+         * then, so `planAuth` asks for the marker only when this is not false. Unset: asked for.
+         */
+        authMailKeyHeld?: boolean;
         /** C3: why the owner's invite cannot be made (no work address, no mail port). The rest of the step still plans. */
         authOwnerInvite?: string;
         files?: string;
@@ -1341,6 +1401,8 @@ export interface PlanPlatformOptions {
             pending: boolean;
             blocked?: string;
         };
+        /** foundry#1024: why the usage tail Worker is blocked, or absent when it is not. */
+        usageTail?: string;
         /** Why the organisation's release webhook step cannot run (the token is not held), or absent. */
         githubReleaseHook?: string;
         /**

package/dist/plan/platform-diff.js

@@ -75,6 +75,22 @@ export const PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY = 'zitadel_platform_aut
 export const AUTH_TUNNEL_ROUTES_VERSION = '2';
 /** The {@link AUTH_TUNNEL_ROUTES_VERSION} the sign-in tunnel was last written with. */
 export const PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY = 'auth_tunnel_routes_applied';
+/**
+ * The version of the env `provisionAuthStack` writes to the login apps (`LOGIN_MAIL_FROM`,
+ * `LETTERMINT_API_TOKEN`). Raise it when a key is added or its meaning changes, so an applied
+ * sign-in plans its step once more and the apps get the env. Never holds a value.
+ * 1: the login apps send their own invite and verification mail (auth 0.35.0, foundry 0.68.0).
+ */
+export const AUTH_LOGIN_ENV_VERSION = '1';
+/**
+ * What the login apps' env is written for: the version and the sender address (`LOGIN_MAIL_FROM`).
+ * The address is no secret; a new mail domain gives a new marker, so the step is planned again.
+ */
+export function authLoginEnvMarker(smtpSender) {
+    return `${AUTH_LOGIN_ENV_VERSION}:${smtpSender}`;
+}
+/** The {@link authLoginEnvMarker} the login apps' env was last written with, once live on them. */
+export const PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY = 'auth_login_env_applied';
 /**
  * `'1'` once the broker holds `MCP_DATABASE_URL` and `MCP_OAUTH_SECRET` (auth ADR 0002), recorded by the
  * sign-in step when an entry of that broker declares `uses.auth.mcp`. A broker entry with `mcp` is not
@@ -1112,6 +1128,8 @@ export const PLATFORM_EDGE_PLATFORM_KEY_SET_SCOPE_KEY = 'edge_platform_key_set';
  */
 export const PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY = 'edge_applied_hostname';
 export const PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY = 'edge_applied_git_ref';
+/** foundry#1024: what `provisionPlatformEdge` last wrote for {@link usageTailEdgeEnv}; see {@link usageTailEdgeEnvValue}. */
+export const PLATFORM_EDGE_APPLIED_USAGE_TAIL_SCOPE_KEY = 'edge_applied_usage_tail';
 /**
  * F4.dns: where edge answers on the Coolify network
  * (`http://<custom_internal_name>:3000`), recorded by the edge step once the
@@ -1396,6 +1414,56 @@ export function uptimeRecorded(recordedIds) {
         Boolean(recordedIds[PLATFORM_UPTIME_ACCESS_TOKEN_ID_SCOPE_KEY]) ||
         Boolean(recordedIds[PLATFORM_UPTIME_ACCESS_UNDELIVERED_SCOPE_KEY]));
 }
+/**
+ * foundry#1024: the usage tail Worker that meters every company Worker's
+ * use, one `cloudflare:worker` step keyed {@link PLATFORM_USAGE_TAIL_KEY}.
+ * `runPlatformSteps` records the script name under
+ * `cloudflare:worker:platform:usage-tail` once it succeeds, which is what
+ * stops `planUsageTail` planning it again.
+ */
+export const PLATFORM_USAGE_TAIL_KEY = 'platform:usage-tail';
+/** The Worker script's name at Cloudflare. */
+export const PLATFORM_USAGE_TAIL_SCRIPT_NAME = 'platform-usage-tail';
+/**
+ * The held ref of the Worker's one secret, `EDGE_USAGE_KEY` -- the narrow
+ * `usage:ingest` credential edge's ingest route accepts. Minted once (rule
+ * 1): the hash is never secret, so (the same pattern `provisionPlatformEdge`
+ * uses for `EDGE_PLATFORM_KEY_HASH`) it doubles as both the undelivered
+ * marker and the final recorded value, with nothing extra to compute or a
+ * live read that could fall back to a blank value.
+ */
+export const PLATFORM_USAGE_TAIL_KEY_REF = 'usage-tail:worker:key';
+export const PLATFORM_USAGE_TAIL_KEY_UNDELIVERED_SCOPE_KEY = 'usage_tail_key_undelivered';
+export const PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY = 'usage_tail_key_set';
+export const PLATFORM_USAGE_TAIL_APPLIED_TAG_SCOPE_KEY = 'usage_tail_applied_tag';
+export const PLATFORM_USAGE_TAIL_APPLIED_SHA256_SCOPE_KEY = 'usage_tail_applied_sha256';
+export const PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY = 'usage_tail_removed';
+/**
+ * What `platform:edge`'s own env should hold for the usage tail Worker
+ * (`USAGE_TAIL_WORKER`, `EDGE_USAGE_KEY_HASH`), or `null` while the Worker is
+ * not deployed or its key is not held yet. `provisionPlatformEdge` writes
+ * these two names on every run alongside `EDGE_PLATFORM_KEY_HASH`; `planEdge`
+ * reads {@link usageTailEdgeEnvValue} to replan edge once this changes.
+ */
+export function usageTailEdgeEnv(recordedIds) {
+    const deployed = Boolean(recordedIds[resourceKey('cloudflare', 'worker', PLATFORM_USAGE_TAIL_KEY)]) &&
+        !recordedIds[PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY];
+    const hash = recordedIds[PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY];
+    if (!deployed || !hash)
+        return null;
+    return { USAGE_TAIL_WORKER: PLATFORM_USAGE_TAIL_SCRIPT_NAME, EDGE_USAGE_KEY_HASH: hash };
+}
+/** The value `provisionPlatformEdge` records once it has written {@link usageTailEdgeEnv} to edge's env; empty while there is nothing to write. */
+export function usageTailEdgeEnvValue(recordedIds) {
+    const env = usageTailEdgeEnv(recordedIds);
+    return env ? `${env.USAGE_TAIL_WORKER}|${env.EDGE_USAGE_KEY_HASH}` : '';
+}
+/** Whether anything of the usage tail Worker is recorded that disabling it must remove. */
+export function usageTailRecorded(recordedIds) {
+    return ((Boolean(recordedIds[resourceKey('cloudflare', 'worker', PLATFORM_USAGE_TAIL_KEY)]) &&
+        !recordedIds[PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY]) ||
+        Boolean(recordedIds[PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY]));
+}
 /**
  * #167: the platform's own diff engine, mirroring `diff.ts`'s
  * `computePlanDetail` for the one shared {@link DeclaredPlatform} record
@@ -1449,6 +1517,11 @@ export function planPlatform(platform, live, options = {}) {
     // write, so while edge is neither applied nor planned in this plan they are
     // blocked, not planned (rule 2), naming edge as the cause.
     const edgeApplied = Boolean(recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]);
+    // foundry#1024: after edge, which it uploads the script through and whose
+    // env takes the key's hash.
+    const usageTail = planUsageTail(platform, recordedIds, blocked.usageTail, edgeApplied);
+    if (usageTail.step)
+        plannedSteps.push(usageTail.step);
     const dnsBlocked = edgeApplied || edge.step
         ? undefined
         : (service) => `the platform's ${service} is blocked, not planned: every DNS record is written through edge, and edge is neither applied nor planned (${platform.edge.enabled
@@ -1480,7 +1553,7 @@ export function planPlatform(platform, live, options = {}) {
     // reconcile below can be planned in the *same* round hc first comes up,
     // the same way files/mail/archon are planned in auth's own first round.
     const hcReady = hc.step !== null || Boolean(recordedIds[resourceKey('coolify', 'app', PLATFORM_HC_KEY)]);
-    const auth = planAuth(platform, recordedIds, blocked.auth ?? dnsBlocked?.('sign-in'), blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? [], blocked.authOwnerInvite, drifted.authApps ?? false);
+    const auth = planAuth(platform, recordedIds, blocked.auth ?? dnsBlocked?.('sign-in'), blocked.authExecutorMissing ?? false, drifted.auth ?? false, blocked.authOtherInputsMissing ?? [], blocked.authOwnerInvite, drifted.authApps ?? false, blocked.authMailKeyHeld ?? true);
     if (auth.step)
         plannedSteps.push(auth.step);
     // #174: the integrations host. Planned after auth; neither step reads the
@@ -1718,6 +1791,9 @@ export function planPlatform(platform, live, options = {}) {
         unmanaged.push({ description: heartbeats.blocked, key: 'heartbeats' });
     for (const description of uptime.blocked)
         unmanaged.push({ description, key: 'uptime' });
+    for (const description of usageTail.blocked) {
+        unmanaged.push({ description, key: 'usage-tail' });
+    }
     if (releaseHook.blocked) {
         unmanaged.push({ description: releaseHook.blocked, key: 'github-release-hook' });
     }
@@ -2153,7 +2229,7 @@ function planSfu(platform, callsOrgSlugs, recordedIds) {
  * promising "this apply re-mints" while one of those is still missing would
  * be wrong the moment it is read.
  */
-function planAuth(platform, recordedIds, executorBlocked, executorMissing, authDrifted, otherInputsMissing = [], ownerInviteBlocked, appsDown = false) {
+function planAuth(platform, recordedIds, executorBlocked, executorMissing, authDrifted, otherInputsMissing = [], ownerInviteBlocked, appsDown = false, mailKeyHeld = true) {
     if (!platform.auth.enabled)
         return { step: null, blocked: null };
     // C3/S2: standing notes. The invite and the domain wait on a person; they hold nothing else back.
@@ -2211,6 +2287,11 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
         // step's redeploy, so a platform recorded before them still plans it.
         recordedIds[PLATFORM_AUTH_ZITADEL_RUN_OPTIONS_SCOPE_KEY] === AUTH_ZITADEL_RUN_OPTIONS &&
         recordedIds[PLATFORM_AUTH_TUNNEL_ROUTES_SCOPE_KEY] === AUTH_TUNNEL_ROUTES_VERSION &&
+        // The login apps' mail env: a platform from before it, or with a new apex, is written again.
+        // Without the held key the apply cannot record it, so it is asked for only once the key is held.
+        (!mailKeyHeld ||
+            recordedIds[PLATFORM_AUTH_LOGIN_ENV_SCOPE_KEY] ===
+                authLoginEnvMarker(`noreply@${platform.apex}`)) &&
         recordedIds[PLATFORM_AUTH_APPLIED_GIT_REF_SCOPE_KEY] === platform.auth.gitRef) {
         return { step: null, blocked: standingNote };
     }
@@ -2686,7 +2767,10 @@ function planFiles(platform, recordedIds, executorBlocked, authReady, drifted) {
  *
  * `drifted` (the host's own `driftedSteps`: edge holds an older Cloudflare
  * token) plans the same step on an applied edge. The step writes the held
- * token into edge's env and redeploys it.
+ * token into edge's env and redeploys it. foundry#1024: a usage tail Worker
+ * key minted after edge's last deploy plans the step again the same way,
+ * through {@link usageTailEdgeEnvValue} rather than a separate `drifted`
+ * flag, since the planner can read it straight from `recordedIds`.
  *
  * Blocked, not planned: a platform key minted but never delivered (lost,
  * `ServiceError`-free the way {@link planFiles}'s own management-key check
@@ -2708,7 +2792,11 @@ function planEdge(platform, recordedIds, executorBlocked, drifted) {
         recordedIds[PLATFORM_EDGE_APPLIED_HOSTNAME_SCOPE_KEY] === platform.edge.hostname &&
         recordedIds[PLATFORM_EDGE_APPLIED_GIT_REF_SCOPE_KEY] === platform.edge.gitRef &&
         // F4.dns: an edge applied before its address was recorded runs once more to record it.
-        Boolean(recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]);
+        Boolean(recordedIds[PLATFORM_EDGE_INTERNAL_URL_SCOPE_KEY]) &&
+        // foundry#1024: a usage tail Worker key minted after edge's last deploy
+        // has not reached edge's env yet; replan to write it and redeploy.
+        (recordedIds[PLATFORM_EDGE_APPLIED_USAGE_TAIL_SCOPE_KEY] ?? '') ===
+            usageTailEdgeEnvValue(recordedIds);
     if (applied && !drifted)
         return { step: null, blocked: null };
     if (executorBlocked)
@@ -3303,6 +3391,79 @@ function planUptime(platform, recordedIds, executorBlocked, heldOptional, archon
         notes,
     };
 }
+/**
+ * foundry#1024: the usage tail Worker, one `cloudflare:worker` step. Blocked,
+ * not planned (rule 2), while no artifact is pinned, edge is not applied, or
+ * the executor lacks its dependencies. Planned again when the pinned tag or
+ * sha256 changed, or a half-made deploy never recorded its applied values; it
+ * mints nothing that is already held. When the platform no longer enables
+ * the Worker, a destructive step removes whatever of it is recorded.
+ */
+function planUsageTail(platform, recordedIds, executorBlocked, edgeApplied) {
+    const { usageTail } = platform;
+    const deployed = Boolean(recordedIds[resourceKey('cloudflare', 'worker', PLATFORM_USAGE_TAIL_KEY)]) &&
+        !recordedIds[PLATFORM_USAGE_TAIL_REMOVED_SCOPE_KEY];
+    const action = (desired) => ({
+        system: 'cloudflare',
+        kind: 'worker',
+        key: PLATFORM_USAGE_TAIL_KEY,
+        desired,
+    });
+    if (!usageTail.enabled) {
+        if (!usageTailRecorded(recordedIds))
+            return { step: null, blocked: [] };
+        if (executorBlocked)
+            return { step: null, blocked: [executorBlocked] };
+        return {
+            step: {
+                action: action({ remove: true }),
+                step: {
+                    description: `remove the usage tail Worker ${PLATFORM_USAGE_TAIL_SCRIPT_NAME} and its held key`,
+                    destroys: true,
+                    migrates: false,
+                },
+            },
+            blocked: [],
+        };
+    }
+    if (!usageTail.tag || !usageTail.sha256) {
+        return {
+            step: null,
+            blocked: [
+                'the usage tail Worker is blocked, not planned: no artifact is pinned; declare usageTail.tag (an edge release tag) and usageTail.sha256 (the digest of usage-tail-worker.js at that tag)',
+            ],
+        };
+    }
+    if (!edgeApplied) {
+        return {
+            step: null,
+            blocked: [
+                'the usage tail Worker is blocked, not planned: platform:edge has not been applied yet',
+            ],
+        };
+    }
+    if (executorBlocked)
+        return { step: null, blocked: [executorBlocked] };
+    // Applied only once a run got to its end and recorded these: a Worker that
+    // was uploaded and then failed has its key but none of the applied values.
+    const applied = deployed &&
+        Boolean(recordedIds[PLATFORM_USAGE_TAIL_KEY_SET_SCOPE_KEY]) &&
+        recordedIds[PLATFORM_USAGE_TAIL_APPLIED_TAG_SCOPE_KEY] === usageTail.tag &&
+        recordedIds[PLATFORM_USAGE_TAIL_APPLIED_SHA256_SCOPE_KEY] === usageTail.sha256;
+    if (applied)
+        return { step: null, blocked: [] };
+    return {
+        step: {
+            action: action({ gitRef: usageTail.tag, sha256: usageTail.sha256 }),
+            step: {
+                description: `deploy the usage tail Worker ${PLATFORM_USAGE_TAIL_SCRIPT_NAME} from edge release ${usageTail.tag}, with its held key`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: [],
+    };
+}
 /**
  * #172: the platform's AI host (https://github.com/wtfalch/ai) -- a Coolify
  * Postgres plus three apps built from that repo's root Dockerfile, one per