@wtfalch/foundry 0.69.0 → 0.70.1

package/dist/bootstrap/declare.js

@@ -170,6 +170,8 @@ export function declaredPlatformFor(apex, serverIpv4) {
         // only after Archon runs. Declared on with no pin, it would be reported
         // blocked and the bootstrap would never be complete.
         uptime: { enabled: false, tag: '', sha256: '' },
+        // foundry#1024: off until a human pins an edge release tag and digest, the same reason as uptime.
+        usageTail: { enabled: false, tag: '', sha256: '' },
         heartbeatsProvider: 'self-hosted',
     };
 }

package/dist/entry-rules.d.ts

@@ -11,6 +11,8 @@ export declare const ONBOARDING_PATH_MAX_LENGTH = 200;
  * at most {@link ONBOARDING_PATH_MAX_LENGTH} characters.
  */
 export declare function isPagePath(value: unknown): value is string;
+/** A path the gate can open for a machine caller: the same rule edge applies, so a declared path is always one a bypass can be made for. */
+export declare const isEdgePath: (path: string) => boolean;
 /** The most roles an entry may offer, as the broker allows. */
 export declare const WORKSPACE_ROLES_MAX = 20;
 /** A role name is the role's key in the broker's store. */

package/dist/entry-rules.js

@@ -21,6 +21,12 @@ export function isPagePath(value) {
         !/[\s\p{Cc}]/u.test(value) &&
         value.length <= ONBOARDING_PATH_MAX_LENGTH);
 }
+/** 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._~-]+)+$/;
+/** A path the gate can open for a machine caller: the same rule edge applies, so a declared path is always one a bypass can be made for. */
+export const isEdgePath = (path) => path.length <= ONBOARDING_PATH_MAX_LENGTH &&
+    EDGE_PATH.test(path) &&
+    !path.split('/').some((s) => s === '.' || s === '..');
 /** The most roles an entry may offer, as the broker allows. */
 export const WORKSPACE_ROLES_MAX = 20;
 /** A role name is the role's key in the broker's store. */

package/dist/migrations/0070_platform_usage_tail.sql

@@ -0,0 +1,12 @@
+-- @wtfalch/foundry: the usage tail Worker on the declared platform (foundry#1024).
+-- Mirrors `src/store/schema.ts`'s `foundryDeclaredPlatform` additions.
+-- `usage_tail_tag` and `usage_tail_sha256` are the pin of the edge release
+-- whose built Worker foundry deploys; both empty means nothing is pinned
+-- yet, and the planner reports that instead of planning the step. Unlike the
+-- uptime Worker, this one is off by default: nothing has pinned a release
+-- yet on any existing platform.
+
+alter table foundry_declared_platform
+  add column if not exists usage_tail_enabled boolean not null default false,
+  add column if not exists usage_tail_tag text not null default '',
+  add column if not exists usage_tail_sha256 text not null default '';

package/dist/modules/assistants.js

@@ -1,4 +1,4 @@
-import { MCP_PATH, isPagePath } from '../entry-rules.js';
+import { MCP_PATH, isEdgePath, isPagePath } from '../entry-rules.js';
 import { problem, setAuthPart, text } from './entry-parts.js';
 /** `uses.auth.mcp`: the app serves AI assistants (MCP clients) that sign the customer in. */
 export const assistants = {
@@ -29,6 +29,21 @@ export const assistants = {
                 kind: 'path',
                 advanced: true,
             },
+            {
+                key: 'eventsPath',
+                label: 'Where we tell your app about assistants',
+                help: 'Set an address on your app, such as /api/auth/events, and we tell your app when people connect or disconnect assistants, so it can keep its own records. Leave it empty and we send nothing.',
+                kind: 'path',
+                advanced: true,
+            },
+            {
+                key: 'managePath',
+                label: 'Page where people see their assistants',
+                help: 'The page on your app where each person sees their connected assistants. We link to it from the mail we send when one connects.',
+                kind: 'path',
+                advanced: true,
+                default: '/',
+            },
         ],
         adds: [
             {
@@ -46,6 +61,14 @@ export const assistants = {
         if (onboarding !== undefined && !isPagePath(onboarding)) {
             return problem('onboardingPath', 'The page must start with "/", such as /onboarding, with no spaces, "?", "#" or "..".');
         }
+        const events = text(values, 'eventsPath');
+        if (events !== undefined && !isEdgePath(events)) {
+            return problem('eventsPath', 'The address must start with "/" and use only lower-case letters, digits, ".", "_", "~" and "-" in each part, such as /api/auth/events.');
+        }
+        const manage = text(values, 'managePath');
+        if (manage !== undefined && !isPagePath(manage)) {
+            return problem('managePath', 'The page must start with "/", with no spaces, "?", "#" or "..".');
+        }
         return null;
     },
     toEntry(entry, values) {
@@ -55,9 +78,13 @@ export const assistants = {
             return problem(null, 'Help for AI assistants needs Sign-in. Turn on Sign-in first.');
         }
         const onboardingPath = text(values, 'onboardingPath');
+        const eventsPath = text(values, 'eventsPath');
+        const managePath = text(values, 'managePath');
         return setAuthPart(entry, 'mcp', {
             path: values.path,
             ...(onboardingPath !== undefined ? { onboardingPath } : {}),
+            ...(eventsPath !== undefined ? { events: { path: eventsPath } } : {}),
+            ...(managePath !== undefined ? { managePath } : {}),
         });
     },
     fromEntry(entry) {
@@ -67,6 +94,10 @@ export const assistants = {
         const values = { path: mcp.path };
         if (mcp.onboardingPath !== undefined)
             values.onboardingPath = mcp.onboardingPath;
+        if (mcp.events !== undefined)
+            values.eventsPath = mcp.events.path;
+        if (mcp.managePath !== undefined)
+            values.managePath = mcp.managePath;
         return values;
     },
 };

package/dist/org.d.ts

@@ -301,7 +301,7 @@ export type AccessRule = {
 /** The key of the entry that is today's one app: the Coolify app named `<slug>`. */
 export declare const APP_ENTRY_KEY = "app";
 /** Why a validator refused. `code` is stable and never reworded; `message` is for people. */
-export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'entry_image_invalid' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'analytics_not_true' | 'analytics_needs_hosting' | 'analytics_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
+export type OrgRefusalCode = 'hosting_tunnel_needs_hosting' | 'issuer_app_name_missing' | 'issuer_app_name_not_unique' | 'issuer_app_kind_unknown' | 'issuer_app_name_reserved_agora' | 'issuer_app_name_reserved_boule' | 'issuer_app_name_reserved_kosmos' | 'hosting_needs_entry' | 'hosting_main_count' | 'entry_key_not_unique' | 'entry_image_invalid' | 'ai_webhook_path_not_unique' | 'worker_route_not_unique' | 'database_not_unique' | 'access_hostname_not_unique' | 'access_hostname_invalid' | 'access_needs_hosting' | 'access_kind_unknown' | 'access_service_token_name_missing' | 'access_hostname_locked' | 'access_hostname_not_served' | 'gate_limit_invalid' | 'hosting_repo_invalid' | 'hosting_github_invalid' | 'gate_needs_domain' | 'gate_key_invalid' | 'gate_key_not_unique' | 'gate_needs_hostname' | 'gate_hostname_not_entry_hostname' | 'gate_hostname_held_twice' | 'gate_hostname_locked' | 'gate_limit_exceeded' | 'wildcard_needs_domain' | 'wildcard_held_twice' | 'hostnames_need_domain' | 'hostname_needed' | 'hostname_invalid' | 'hostname_not_unique' | 'hostname_locked' | 'hosted_name_invalid' | 'hosted_name_not_unique' | 'hosted_name_worker_app' | 'entry_workspace_invalid' | 'entry_workspace_unsupported' | 'entry_live_needs_workspace' | 'entry_live_commit_invalid' | 'gate_key_taken_by_workspace' | 'gate_key_taken_by_private_page' | 'private_page_invalid' | 'private_page_path_invalid' | 'private_page_duplicate' | 'private_page_limit' | 'private_page_needs_hosting' | 'private_page_roles_invalid' | 'private_page_people_invalid' | 'entry_key_invalid' | 'entry_key_reserved' | 'entry_repo_invalid' | 'entry_folder_invalid' | 'entry_branch_empty' | 'entry_build_pack_unknown' | 'entry_build_pack_unavailable' | 'entry_port_invalid' | 'entry_health_path_invalid' | 'entry_capabilities_invalid' | 'entry_database_needs_hosting' | 'blue_green_needs_hostname' | 'env_name_empty' | 'env_name_reserved' | 'env_source_platform_mail_key' | 'env_source_unknown' | 'env_shared_secret_name_invalid' | 'env_held_secret_name_mismatch' | 'env_held_secret_name_invalid' | 'env_looks_like_secret' | 'builtin_app_invalid' | 'blue_green_not_object' | 'blue_green_steps_length' | 'blue_green_steps_range' | 'blue_green_steps_order' | 'blue_green_steps_end' | 'blue_green_hold_invalid' | 'blue_green_advance_invalid' | 'blue_green_min_requests_invalid' | 'blue_green_error_margin_invalid' | 'blue_green_staff_first_invalid' | 'volumes_not_list' | 'volumes_too_many' | 'volume_name_invalid' | 'volume_name_logs' | 'volume_name_not_unique' | 'volume_mount_path_invalid' | 'volume_mount_path_too_long' | 'volume_mount_path_log_dir' | 'volume_mount_path_forbidden' | 'volume_mount_path_not_unique' | 'auth_needs_hosting' | 'auth_users_invalid' | 'auth_registration_invalid' | 'registration_open_needs_customers' | 'auth_replaces_broker_entry_invalid' | 'auth_replaces_broker_entry_owned' | 'auth_needs_exact_hostname' | 'mcp_needs_open_customers' | 'mcp_path_invalid' | 'mcp_onboarding_path_invalid' | 'mcp_events_path_invalid' | 'mcp_manage_path_invalid' | 'auth_sign_in_invalid' | 'email_code_needs_customers' | 'auth_room_invalid' | 'auth_room_needs_customers' | 'auth_room_not_unique' | 'client_name_taken' | 'workspaces_needs_customers' | 'workspaces_needs_server' | 'workspaces_roles_invalid' | 'workspaces_role_reserved' | 'workspaces_invite_path_invalid' | 'workspaces_env_clash' | 'ai_needs_hosting' | 'ai_offerings_invalid' | 'ai_permissions_invalid' | 'ai_webhook_path_invalid' | 'ai_webhook_needs_exact_hostname' | 'ai_env_clash' | 'files_needs_hosting' | 'files_collections_invalid' | 'files_permissions_invalid' | 'files_share_host_invalid' | 'files_share_host_needs_domain' | 'files_env_clash' | 'worker_needs_hosting' | 'worker_needs_repo' | 'worker_needs_own_repo' | 'worker_key_too_long' | 'worker_artifact_invalid' | 'worker_route_invalid' | 'worker_route_off_domain' | 'worker_rate_limit_name_missing' | 'worker_rate_limit_namespace_missing' | 'worker_rate_limit_invalid' | 'worker_rate_limit_period_invalid' | 'worker_app_invalid' | 'edge_not_true' | 'edge_needs_hosting' | 'edge_needs_domain' | 'edge_env_clash' | 'mail_not_true' | 'mail_needs_hosting' | 'mail_env_clash' | 'jobs_not_true' | 'jobs_needs_hosting' | 'jobs_env_clash' | 'analytics_not_true' | 'analytics_needs_hosting' | 'analytics_env_clash' | 'customer_grants_not_true' | 'customer_grants_needs_customers' | 'customer_grants_env_clash' | 'repo_use_invalid' | 'repo_use_needs_repo' | 'repo_use_env_clash' | 'audit_not_true' | 'audit_needs_hosting' | 'audit_needs_worker_database' | 'customers_invalid' | 'customers_sign_up_needs_enabled' | 'registration_open_needs_sign_up';
 /**
  * One refusal: a stable `code`, the dotted `path` into {@link DeclaredOrg} it is about
  * (`hosting.entries.terminal.uses.auth.registration`) and the sentence for people.
@@ -620,11 +620,18 @@ export interface EntryAuth {
      * broker is the authorization server, ZITADEL signs the person in. `path` is
      * the MCP endpoint on the entry's host; the resource is
      * `https://<the entry's host><path>`, derived and never declared. Needs
-     * `users: 'customers'` and `registration: 'open'`.
+     * `users: 'customers'` and `registration: 'open'`. `events.path` is where
+     * the broker posts signed assistant events; foundry mints the signing secret
+     * once and gives it to the broker entry and the app as `AUTH_EVENTS_SECRET`.
+     * `managePath` is the page where people see their assistants.
      */
     mcp?: {
         path: string;
         onboardingPath?: string;
+        events?: {
+            path: string;
+        };
+        managePath?: string;
     };
     /**
      * How the customer proves who they are. `password` is the default.

package/dist/org.js

@@ -1,6 +1,6 @@
 import { DEFAULT_RULES, checkName, explain } from '@wtfalch/auth/names';
 import { floatingRefBlocked, floatingTagBlocked } from './bootstrap/versions.js';
-import { AI_ENTRY_PERMISSIONS, AI_WEBHOOK_PATH, FILES_COLLECTION_NAME, FILES_ENTRY_PERMISSIONS, MCP_PATH, ONBOARDING_PATH_MAX_LENGTH, ROOM_STEPS_MAX, ROOM_STEPS_MIN, ROOM_TEXT_MAX, ROOM_UNSAFE_TEXT, WORKSPACE_ROLE, WORKSPACE_ROLES_MAX, isPagePath, } from './entry-rules.js';
+import { AI_ENTRY_PERMISSIONS, AI_WEBHOOK_PATH, FILES_COLLECTION_NAME, FILES_ENTRY_PERMISSIONS, MCP_PATH, ONBOARDING_PATH_MAX_LENGTH, ROOM_STEPS_MAX, ROOM_STEPS_MIN, ROOM_TEXT_MAX, ROOM_UNSAFE_TEXT, WORKSPACE_ROLE, WORKSPACE_ROLES_MAX, isEdgePath, isPagePath, } from './entry-rules.js';
 import { hostedLabelRefusal } from './hosted-label.js';
 import { entryHasDatabase, validateArtifact, validateEntryWorkerApp, } from './worker-app-config.js';
 export { AI_ENTRY_PERMISSIONS, FILES_ENTRY_PERMISSIONS, MCP_PATH, ONBOARDING_PATH_MAX_LENGTH, ROOM_STEPS_MAX, ROOM_STEPS_MIN, ROOM_TEXT_MAX, WORKSPACE_ROLE, WORKSPACE_ROLES_MAX, } from './entry-rules.js';
@@ -948,6 +948,19 @@ function validateEntryAuth(entry, hosting, domain) {
         if (onboarding !== undefined && !isPagePath(onboarding)) {
             return refusal('mcp_onboarding_path_invalid', `hosting.entries.${entry.key}.uses.auth.mcp.onboardingPath`, `${at} mcp.onboardingPath must be an absolute path that starts with '/', such as '/onboarding', with no '..', '?', '#' or spaces, and at most ${ONBOARDING_PATH_MAX_LENGTH} characters`);
         }
+        const events = auth.mcp.events;
+        if (events !== undefined &&
+            (typeof events !== 'object' ||
+                events === null ||
+                Array.isArray(events) ||
+                typeof events.path !== 'string' ||
+                !isEdgePath(events.path))) {
+            return refusal('mcp_events_path_invalid', `hosting.entries.${entry.key}.uses.auth.mcp.events.path`, `${at} mcp.events.path must be an absolute path that starts with '/', such as '/api/auth/events', made of lower-case a-z, 0-9, '.', '_', '~' and '-' with no empty or '..' part, and at most ${ONBOARDING_PATH_MAX_LENGTH} characters`);
+        }
+        const manage = auth.mcp.managePath;
+        if (manage !== undefined && !isPagePath(manage)) {
+            return refusal('mcp_manage_path_invalid', `hosting.entries.${entry.key}.uses.auth.mcp.managePath`, `${at} mcp.managePath must be an absolute path that starts with '/', such as '/settings', with no '..', '?', '#' or spaces, and at most ${ONBOARDING_PATH_MAX_LENGTH} characters`);
+        }
     }
     if (auth.workspaces !== undefined) {
         const refused = validateEntryWorkspaces(entry, auth.workspaces, at);

package/dist/plan/blue-green-apply.js

@@ -710,6 +710,14 @@ export async function ensureStage(deps, subject, serverUuid) {
     else {
         console.info(`${deps.label}: stage sign-in was not set up: the host gave no sign-in for this subject, so ${bgKey.stageSignIn(subject.id)} stays unrecorded`);
     }
+    // A workspace whose entry stopped declaring events drops the secret; the held value stays.
+    if (deps.signIn && !stageEnv.some((e) => e.key === 'AUTH_EVENTS_SECRET')) {
+        for (const row of await deps.coolify.listEnvs(appId)) {
+            if (row.key === 'AUTH_EVENTS_SECRET' && row.uuid) {
+                await deps.coolify.deleteEnv(appId, row.uuid);
+            }
+        }
+    }
     await upsertEnv(deps, appId, stageEnv);
     if (signInGuard)
         deps.record(bgKey.stageSignIn(subject.id), signInGuard);

package/dist/plan/broker-entries.d.ts

@@ -36,12 +36,21 @@ export declare const mcpCallbackUri: (org: DeclaredOrg) => string;
  * compares are the same value. `null` without `mcp`, or until the project
  * exists.
  */
-export declare function entryMcp(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+export declare function entryMcp(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): BrokerEntryMcp | null;
+/**
+ * What a broker entry says about its MCP resource. `events` carries the address only: the signing secret is
+ * held, and `writeBrokerEntry` adds it when it writes the entry, so the recorded want never holds it.
+ */
+export interface BrokerEntryMcp {
     resource: string;
     projectId: string;
     loginHost: string;
     onboardingUrl?: string;
-} | null;
+    events?: {
+        url: string;
+    };
+    manageUrl?: string;
+}
 /** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
 export declare function entryAuthEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string>;
 /** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
@@ -56,12 +65,7 @@ export interface BrokerEntryWant {
     registration: boolean;
     replaces: string | null;
     /** Present only for an entry with `uses.auth.mcp`: what the broker needs to be its authorization server. */
-    mcp?: {
-        resource: string;
-        projectId: string;
-        loginHost: string;
-        onboardingUrl?: string;
-    };
+    mcp?: BrokerEntryMcp;
     /** Present only for an entry with `uses.auth.workspaces`. The key's hash is not part of it: see {@link writeBrokerEntry}. */
     workspaces?: {
         roles: string[];
@@ -174,6 +178,8 @@ export declare function writeBrokerEntry(broker: BrokerPort, input: {
     workspacesKeyHash?: string;
     /** The operator's held connection string for the broker's workspaces database, written to the broker when it differs. */
     workspacesDatabaseUrl?: string;
+    /** The held events secret. Required with `want.mcp.events`; it goes into the entry and nowhere else. */
+    eventsSecret?: string;
 }): Promise<{
     invalidForeign: string[];
     replaced: string | null;

package/dist/plan/broker-entries.js

@@ -59,6 +59,8 @@ export function entryMcp(org, entry, recorded) {
         projectId,
         loginHost: loginHostnameFor(org),
         ...(mcp.onboardingPath ? { onboardingUrl: `https://${host}${mcp.onboardingPath}` } : {}),
+        ...(mcp.events ? { events: { url: `https://${host}${mcp.events.path}` } } : {}),
+        ...(mcp.managePath ? { manageUrl: `https://${host}${mcp.managePath}` } : {}),
     };
 }
 /** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
@@ -286,8 +288,18 @@ export async function writeBrokerEntry(broker, input) {
         registration: want.registration,
     };
     // The previous write's `mcp` goes when the entry no longer declares it.
-    if (want.mcp)
-        entry.mcp = want.mcp;
+    if (want.mcp) {
+        const { events, ...mcp } = want.mcp;
+        if (events && !input.eventsSecret) {
+            throw new Error(`${label}: the events secret is missing, so nothing was written`);
+        }
+        entry.mcp = {
+            ...mcp,
+            ...(events && input.eventsSecret
+                ? { events: { url: events.url, secret: input.eventsSecret } }
+                : {}),
+        };
+    }
     else
         entry.mcp = undefined;
     // The previous write's `workspaces` goes when the entry no longer declares it; the key hash goes with it.

package/dist/plan/diff.js

@@ -21,6 +21,7 @@ import { onPlatformNetwork } from './destinations.js';
 import { planEntryAiKeys } from './entry-ai-key.js';
 import { planEntryAnalyticsKeys } from './entry-analytics-key.js';
 import { planEntryAudit } from './entry-audit.js';
+import { authEventsAppliedScopeKey, authEventsBlocked, authEventsMarker, } from './entry-auth-events.js';
 import { CUSTOMER_GRANTS_ENV, CUSTOMER_GRANTS_WRITTEN_SCOPE_KEY, customerGrantsEntries, customerGrantsShapeMatches, customerGrantsToDrop, wantedCustomerGrants, } from './entry-customer-grants.js';
 import { planEdgeReservedLabels, planEdgeSlug, planEntryEdgeKeys } from './entry-edge-key.js';
 import { planFilesKeys } from './entry-files-key.js';
@@ -175,6 +176,18 @@ function liveResourceName(r) {
     const type = r.kind === 'dns_record' && typeof r.config.type === 'string' ? `${r.config.type} ` : '';
     return `${type}${name}, ${r.key}`;
 }
+/**
+ * The provider's own name for a live resource, for a park or provision
+ * step's own prose (#1062, pain point 3): an operator told to "park the
+ * database" acted on the company's Coolify server, named after the same
+ * company, instead of the database resource the step meant. `null` when
+ * there is no live resource yet, or it carries no name -- unlike
+ * {@link liveResourceName} above, this never falls back to the bare key,
+ * since an id is not a name a step's own text should ever show.
+ */
+function liveName(live) {
+    return typeof live?.config.name === 'string' && live.config.name !== '' ? live.config.name : null;
+}
 /**
  * The diff engine: #19's "a plan reads live state from Zitadel, Coolify and
  * Cloudflare and diffs it against the declared org", built on #10's rule
@@ -1049,6 +1062,7 @@ export function computePlanDetail(declaredOrg, live, recordedIds = {}, agoraHost
     unmanaged.push(...appsDbRoute.blocked);
     unmanaged.push(...appsZones.blocked);
     unmanaged.push(...entryJobs.blocked);
+    unmanaged.push(...authEventsBlocked(org, recordedIds));
     unmanaged.push(...entryAudit.blocked);
     unmanaged.push(...entryRepoKeys.blocked);
     unmanaged.push(...edgeReservedLabels.blocked);
@@ -3164,7 +3178,7 @@ function planKosmos(org, byKey, claimed, recordedIds, issuer, otherSlugs) {
     if (!kosmosOn(org)) {
         // Switched off: park a live app (stop it, keep the database), like CMS and calls. A stopped app is
         // already parked, so the plan reaches empty.
-        const parked = planHostingToggle('coolify', 'kosmos', false, org, byKey, claimed, () => `provision ${org.slug}'s kosmos`, () => `park ${org.slug}'s kosmos (stops serving; its database is retained, not deleted)`, org.id, (live) => !/^(exited|stopped)/.test(String(live.config.status ?? '')));
+        const parked = planHostingToggle('coolify', 'kosmos', false, org, byKey, claimed, () => `provision ${org.slug}'s kosmos`, (live) => `park ${org.slug}'s kosmos${liveName(live) ? ` ${liveName(live)}` : ''} (stops serving; its database is retained, not deleted)`, org.id, (live) => !/^(exited|stopped)/.test(String(live.config.status ?? '')));
         return { step: parked, blocked: null };
     }
     const key = resourceKey('coolify', 'kosmos', org.id);
@@ -3531,7 +3545,11 @@ function planBoule(org, byKey, claimed, recordedIds, issuer, otherSlugs, archonU
  * park-not-delete rule (#7 corrections 1) -- turning it off never deletes
  * the org's own app, database or tunnel configuration, it parks it.
  */
-function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, describeProvision, describePark, stepKey = org.id, isOn = (live) => live.config.enabled !== false) {
+function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, 
+// #1062: takes the live resource so a caller can name it (Coolify's own
+// name for it, from `config.name`), rather than a generic noun a park or
+// provision step's own text can be told apart from the server it runs on.
+describeProvision, describePark, stepKey = org.id, isOn = (live) => live.config.enabled !== false) {
     const key = resourceKey(system, kind, stepKey);
     const live = byKey.get(key);
     // A live resource is on unless it says it is parked. Providers' own
@@ -3549,7 +3567,7 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
             return null;
         return {
             action: { system, kind, key: stepKey, desired: { enabled: false } },
-            step: { description: describePark(), destroys: true, migrates: false },
+            step: { description: describePark(live), destroys: true, migrates: false },
         };
     }
     if (live)
@@ -3560,7 +3578,7 @@ function planHostingToggle(system, kind, desiredEnabled, org, byKey, claimed, de
         return null;
     return {
         action: { system, kind, key: stepKey, desired: { enabled: true } },
-        step: { description: describeProvision(), destroys: false, migrates: false },
+        step: { description: describeProvision(live), destroys: false, migrates: false },
     };
 }
 /**
@@ -3699,7 +3717,7 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
         });
     }
     const refused = noRepo || composeBuilt;
-    const toggled = planHostingToggle('coolify', 'app', entry !== undefined && !refused, org, byKey, claimed, () => `provision ${org.slug}'s ${label}${volumesNote(entry)}`, () => `park ${org.slug}'s ${label} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
+    const toggled = planHostingToggle('coolify', 'app', entry !== undefined && !refused, org, byKey, claimed, () => `provision ${org.slug}'s ${label}${volumesNote(entry)}`, (live) => `park ${org.slug}'s ${label}${liveName(live) ? ` ${liveName(live)}` : ''} (stops serving; app data is retained, not deleted -- #7 corrections 1)`, stepKey);
     // #447: only the live app's own `git_repository` decides, never the
     // declared entry (a `repo: null` entry can sit over a bespoke app, which is
     // parked as before). Only the `app` key ever held the default app, and an
@@ -3888,8 +3906,9 @@ function planApp(org, entryKey, byKey, claimed, recordedIds, plannedSteps, authI
     // F5 (rule 3): who signs in, which client and which issuer reach an app
     // that is already live. `pushAppEnv` records what it pushed.
     if (entry.uses?.auth &&
-        JSON.stringify(entryAuthEnv(org, entry, recordedIds, authIssuer)) !==
-            (recordedIds[entryAuthEnvAppliedScopeKey(entryKey)] ?? '{}')) {
+        (JSON.stringify(entryAuthEnv(org, entry, recordedIds, authIssuer)) !==
+            (recordedIds[entryAuthEnvAppliedScopeKey(entryKey)] ?? '{}') ||
+            authEventsMarker(entry) !== (recordedIds[authEventsAppliedScopeKey(entryKey)] ?? ''))) {
         return {
             step: {
                 action,
@@ -4250,7 +4269,7 @@ function planDatabase(org, byKey, claimed, recordedIds) {
     if (!appHome || !legacy || !recordedIds[legacy] || serviceOnServer(org, appHome, recordedIds)) {
         return null;
     }
-    return planHostingToggle('coolify', 'database', org.hosting.entries.some(entryHasDatabase), org, byKey, claimed, () => `provision a database for ${org.slug}'s app`, () => `park ${org.slug}'s database (data is retained, not deleted -- #7 corrections 1)`, org.id, (live) => !/^(exited|stopped)/.test(String(live.config.status ?? '')));
+    return planHostingToggle('coolify', 'database', org.hosting.entries.some(entryHasDatabase), org, byKey, claimed, () => `provision a database for ${org.slug}'s app`, (live) => `park ${org.slug}'s database${liveName(live) ? ` ${liveName(live)}` : ''} (data is retained, not deleted -- #7 corrections 1)`, org.id, (live) => !/^(exited|stopped)/.test(String(live.config.status ?? '')));
 }
 function sortedNames(names) {
     return names.filter(Boolean).sort().join(',');
@@ -4295,7 +4314,7 @@ function planTunnel(org, byKey, claimed, recordedIds, platformApex) {
         appsOn(org) ||
         // A company without a domain still gets a tunnel of its own for an entry at `<slug>.oikos.host`.
         entryRoutes(org, recordedIds).length > 0;
-    const toggled = planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, () => `park ${org.slug}'s Cloudflare tunnel (configuration is retained, not deleted -- #7 corrections 1)`, org.id, 
+    const toggled = planHostingToggle('cloudflare', 'tunnel', desired, org, byKey, claimed, () => `provision a Cloudflare tunnel for ${org.slug}'s app`, (live) => `park ${org.slug}'s Cloudflare tunnel${liveName(live) ? ` ${liveName(live)}` : ''} (configuration is retained, not deleted -- #7 corrections 1)`, org.id, 
     // Cloudflare's status, read against what is declared: a park cannot change
     // it, so judging on/off by status alone would never let the plan empty.
     // Wanted on: only `down` needs a repair (`inactive` is a fresh tunnel

package/dist/plan/edge-access.d.ts

@@ -115,6 +115,15 @@ export interface AccessGateInput {
     emails: string[];
 }
 export declare const isNotFound: (error: unknown) => boolean;
+/**
+ * Throws the operator-facing message when `error` is edge's generic 404 for
+ * a route this SDK expects but the running release predates (#1061, pain
+ * point 12: production edge six days behind the SDK failed foundry's first
+ * apps step with the raw "Route not found" and no hint why). Returns
+ * otherwise, so the caller's own handling of `error` -- a conflict branch,
+ * an `isNotFound`/`isNotFoundError` "already gone" check -- still runs.
+ */
+export declare function edgeTooOld(error: unknown, what: string): void;
 /**
  * Edge answers a policy, delete or create call for a live Access app with no
  * edge row `not_found` or 409 `exists` ("create or adopt it first"). So the

package/dist/plan/edge-access.js

@@ -3,6 +3,26 @@ import { EDGE_DNS_WRITE_CONCURRENCY, limiter, rateLimitRetrier, } from './edge-d
 export const isNotFound = (error) => error instanceof EdgeApiError && error.code === 'not_found';
 /** Edge's 409 for a live app on the domain with no edge row. */
 const isExists = (error) => error instanceof EdgeApiError && error.code === 'conflict' && error.reason === 'exists';
+/**
+ * Edge's generic 404 fallback for a route no release of it answers yet
+ * (`service.ts`'s `errorResponse('not_found', 'Route not found')`), as
+ * opposed to a resource-specific 404 ("Key not found" and the like), which
+ * never carries this exact message.
+ */
+const isRouteMissing = (error) => error instanceof EdgeApiError && error.status === 404 && error.message === 'Route not found';
+/**
+ * Throws the operator-facing message when `error` is edge's generic 404 for
+ * a route this SDK expects but the running release predates (#1061, pain
+ * point 12: production edge six days behind the SDK failed foundry's first
+ * apps step with the raw "Route not found" and no hint why). Returns
+ * otherwise, so the caller's own handling of `error` -- a conflict branch,
+ * an `isNotFound`/`isNotFoundError` "already gone" check -- still runs.
+ */
+export function edgeTooOld(error, what) {
+    if (isRouteMissing(error)) {
+        throw new Error(`${what} is blocked: the running edge has no route for this step; deploy edge to the release foundry expects`);
+    }
+}
 /**
  * Edge answers a policy, delete or create call for a live Access app with no
  * edge row `not_found` or 409 `exists` ("create or adopt it first"). So the

package/dist/plan/entry-auth-events.d.ts

@@ -0,0 +1,53 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+/**
+ * `uses.auth.mcp.events`: the broker posts signed assistant events to the app. Foundry makes one signing secret
+ * per broker entry (`<entry>` and `<entry>-work` each have their own), holds it, and gives it to two places: the
+ * broker entry (`mcp.events.secret`) and the app (`AUTH_EVENTS_SECRET`). The plan and the recorded markers carry
+ * only whether events are on and the address, never the secret.
+ */
+/** The app's env name, and the Worker app's secret name. */
+export declare const AUTH_EVENTS_ENV = "AUTH_EVENTS_SECRET";
+/** The secret was made and is not held yet: the ref, never the secret (CLAUDE.md, Platform steps, rule 1). */
+export declare const authEventsUndeliveredScopeKey: (entryKey: string) => string;
+/** What the app's env was last written with for events: `on` or empty. A change replans the app step. */
+export declare const authEventsAppliedScopeKey: (entryKey: string) => string;
+/** The held-key ref of an entry's events secret. At most 127 characters for an entry key of up to 63. */
+export declare const authEventsSecretRef: (orgId: string, entryKey: string) => string;
+/** The hold is tried this many times (rule 1). */
+export declare const AUTH_EVENTS_HOLD_TRIES = 3;
+/** Every held-key read and write is one outside call. */
+export declare const AUTH_EVENTS_HELD_TIMEOUT_MS = 15000;
+/** `whsec_` and the base64 of 32 random bytes: the Standard Webhooks secret format. */
+export declare const newAuthEventsSecret: () => string;
+/** The entry declares `uses.auth.mcp.events`. */
+export declare const authEventsWanted: (entry: HostingEntry) => boolean;
+/** What `auth_events_applied.<entry>` holds for an entry. */
+export declare const authEventsMarker: (entry: HostingEntry) => string;
+interface HeldKeys {
+    resolve(ref: string): Promise<string | null | undefined>;
+    put?(ref: string, value: string): Promise<void>;
+}
+/**
+ * The entry's events secret: read from the held keys, else made and held. The marker is recorded and persisted
+ * before the hold, so a crash after the mint never mints again: a recorded marker with nothing held stops here
+ * and names the ref. The hold is tried 3 times with the same secret and the marker is cleared after it. Errors
+ * name the entry and the ref, never the secret or the cause. `secret` registers the value for redaction first.
+ */
+export declare function ensureAuthEventsSecret(input: {
+    orgId: string;
+    slug: string;
+    entryKey: string;
+    heldKeys: HeldKeys | undefined;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    secret: (value: string) => void;
+}): Promise<string>;
+/** The secret as already held, or an error that names the ref. A broker-entry step only reads. */
+export declare function heldAuthEventsSecret(heldKeys: Pick<HeldKeys, 'resolve'> | undefined, org: Pick<DeclaredOrg, 'id' | 'slug'>, entryKey: string, step?: string): Promise<string>;
+/** One blocked line per recorded marker, for the planner to show. */
+export declare function authEventsBlocked(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): Array<{
+    description: string;
+    key: string;
+}>;
+export {};

package/dist/plan/entry-auth-events.js

@@ -0,0 +1,112 @@
+import { randomBytes } from 'node:crypto';
+import { withTimeout } from './call-timeout.js';
+/**
+ * `uses.auth.mcp.events`: the broker posts signed assistant events to the app. Foundry makes one signing secret
+ * per broker entry (`<entry>` and `<entry>-work` each have their own), holds it, and gives it to two places: the
+ * broker entry (`mcp.events.secret`) and the app (`AUTH_EVENTS_SECRET`). The plan and the recorded markers carry
+ * only whether events are on and the address, never the secret.
+ */
+/** The app's env name, and the Worker app's secret name. */
+export const AUTH_EVENTS_ENV = 'AUTH_EVENTS_SECRET';
+/** The secret was made and is not held yet: the ref, never the secret (CLAUDE.md, Platform steps, rule 1). */
+export const authEventsUndeliveredScopeKey = (entryKey) => `auth_events_secret_undelivered.${entryKey}`;
+/** What the app's env was last written with for events: `on` or empty. A change replans the app step. */
+export const authEventsAppliedScopeKey = (entryKey) => `auth_events_applied.${entryKey}`;
+/** The held-key ref of an entry's events secret. At most 127 characters for an entry key of up to 63. */
+export const authEventsSecretRef = (orgId, entryKey) => `foundry:auth-events-secret:${orgId}:${entryKey}`;
+/** The hold is tried this many times (rule 1). */
+export const AUTH_EVENTS_HOLD_TRIES = 3;
+/** Every held-key read and write is one outside call. */
+export const AUTH_EVENTS_HELD_TIMEOUT_MS = 15_000;
+/** `whsec_` and the base64 of 32 random bytes: the Standard Webhooks secret format. */
+export const newAuthEventsSecret = () => `whsec_${randomBytes(32).toString('base64')}`;
+/** The entry declares `uses.auth.mcp.events`. */
+export const authEventsWanted = (entry) => entry.uses?.auth?.mcp?.events !== undefined;
+/** What `auth_events_applied.<entry>` holds for an entry. */
+export const authEventsMarker = (entry) => authEventsWanted(entry) ? 'on' : '';
+/**
+ * The entry's events secret: read from the held keys, else made and held. The marker is recorded and persisted
+ * before the hold, so a crash after the mint never mints again: a recorded marker with nothing held stops here
+ * and names the ref. The hold is tried 3 times with the same secret and the marker is cleared after it. Errors
+ * name the entry and the ref, never the secret or the cause. `secret` registers the value for redaction first.
+ */
+export async function ensureAuthEventsSecret(input) {
+    const { entryKey } = input;
+    const ref = authEventsSecretRef(input.orgId, entryKey);
+    const marker = authEventsUndeliveredScopeKey(entryKey);
+    const at = `coolify:app for ${input.slug}`;
+    const heldKeys = input.heldKeys;
+    const held = await withTimeout('held key read', AUTH_EVENTS_HELD_TIMEOUT_MS, async () => heldKeys?.resolve(ref));
+    if (held) {
+        input.secret(held);
+        if (input.recorded()[marker]) {
+            input.record(marker, '');
+            await input.persist();
+        }
+        return held;
+    }
+    if (input.recorded()[marker]) {
+        throw new Error(`${at}: the events secret of entry '${entryKey}' was made but never held (ref ${ref}); it is not made again. Hold a value at that ref, or remove the recorded key ${marker}`);
+    }
+    const put = heldKeys?.put;
+    if (typeof put !== 'function') {
+        throw new Error(`${at}: the held keys cannot put the events secret of entry '${entryKey}'`);
+    }
+    const value = newAuthEventsSecret();
+    input.secret(value);
+    input.record(marker, ref);
+    await input.persist();
+    for (let attempt = 1; attempt <= AUTH_EVENTS_HOLD_TRIES; attempt++) {
+        let stored = false;
+        try {
+            await withTimeout('held key write', AUTH_EVENTS_HELD_TIMEOUT_MS, () => put.call(heldKeys, ref, value));
+            stored = true;
+        }
+        catch {
+            // The cause can echo the value; the ref is all a reader needs.
+        }
+        if (!stored)
+            continue;
+        input.record(marker, '');
+        await input.persist();
+        // Two applies that both found nothing held both mint and the later put wins: let a put that is
+        // landing finish, then end on what is held. A put that lands later than that is not seen here.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        let final = value;
+        try {
+            final =
+                (await withTimeout('held key read', AUTH_EVENTS_HELD_TIMEOUT_MS, async () => heldKeys?.resolve(ref))) || value;
+        }
+        catch (error) {
+            // The put went through, so the apply goes on with the value just put; the cause can echo a value.
+            console.warn(`${at}: the events secret of entry '${entryKey}' could not be read back after it was held (${error?.name ?? 'Error'})`);
+        }
+        input.secret(final);
+        return final;
+    }
+    throw new Error(`${at}: the events secret of entry '${entryKey}' was made but could not be held after ${AUTH_EVENTS_HOLD_TRIES} tries (ref ${ref})`);
+}
+/** The secret as already held, or an error that names the ref. A broker-entry step only reads. */
+export async function heldAuthEventsSecret(heldKeys, org, entryKey, step = 'coolify:broker-entry') {
+    const ref = authEventsSecretRef(org.id, entryKey);
+    const value = await withTimeout('held key read', AUTH_EVENTS_HELD_TIMEOUT_MS, async () => heldKeys?.resolve(ref));
+    if (!value) {
+        throw new Error(`${step} for ${org.slug}: the events secret of entry '${entryKey}' is not held yet (ref ${ref}); the app step makes it`);
+    }
+    return value;
+}
+/** One blocked line per recorded marker, for the planner to show. */
+export function authEventsBlocked(org, recorded) {
+    return Object.entries(recorded).flatMap(([key, id]) => {
+        const prefix = authEventsUndeliveredScopeKey('');
+        if (!id || !key.startsWith(prefix))
+            return [];
+        const entryKey = key.slice(prefix.length);
+        return [
+            {
+                description: `${org.slug}'s ${entryKey} events secret was made but never held (ref ${id}); it is not made again. Hold a value at that ref, or remove the recorded key ${key}`,
+                key: `coolify:auth-events:${entryKey}`,
+            },
+        ];
+    });
+}

package/dist/plan/executor.d.ts

@@ -2736,6 +2736,8 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * provisioned, where this one is unconditional (#239).
      */
     private pushAppEnv;
+    /** 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. */
+    private dropAuthEventsEnv;
     /**
      * 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
@@ -2777,6 +2779,8 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * broker would drop.
      */
     private coolifyBrokerEntry;
+    /** The held events secret of a broker entry that declares events, registered for redaction; nothing when it declares none. */
+    private eventsInput;
     /**
      * 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.