@wtfalch/foundry 0.68.3 → 0.70.0

package/dist/audit/seal.d.ts

@@ -28,6 +28,8 @@ export interface SealResult {
     treeSize?: number;
     /** How many checkpoints the authority stamped in this tick. */
     anchored: number;
+    /** How many erased rows this tick sealed the erasure of; on a sweep that failed part way, the rows sealed before the failure. */
+    erasures: number;
     /** Plain words on why a step did not happen. Present whenever `outcome` is not `sealed`, or anchoring did not run. */
     reason?: string;
     at: string;

package/dist/audit/seal.js

@@ -1,4 +1,5 @@
-import { anchorCheckpoints, sealCheckpoint } from '@wtfalch/audit-sealing';
+import { anchorCheckpoints, computeErasureHash, sealCheckpoint } from '@wtfalch/audit-sealing';
+import { sql } from 'drizzle-orm';
 import { isUnavailable } from './connector.js';
 /**
  * The sealing and anchoring tick (foundry#929, audit#56). The host calls {@link sealLedgers} on
@@ -51,6 +52,7 @@ async function sealOne(deps, ledger, now) {
             ...base,
             outcome: 'failed',
             anchored: 0,
+            erasures: 0,
             reason: `could not open the ledger: ${plainFailure(error)}`,
             at: now().toISOString(),
         };
@@ -60,6 +62,7 @@ async function sealOne(deps, ledger, now) {
             ...base,
             outcome: 'skipped',
             anchored: 0,
+            erasures: 0,
             reason: `not sealed, the ledger is not reachable: ${connection.unavailable}`,
             at: now().toISOString(),
         };
@@ -68,17 +71,33 @@ async function sealOne(deps, ledger, now) {
     let outcome = 'unchanged';
     let treeSize;
     let anchored = 0;
+    let erasures = 0;
     try {
+        const progress = { sealed: 0 };
+        try {
+            await sealErasures(connection.handle, progress);
+        }
+        catch (error) {
+            if (isMissingGrant(error)) {
+                notes.push("erasures not sealed yet: the sealing role gets the grant on the app's next apply");
+            }
+            else {
+                outcome = 'failed';
+                notes.push(`sealing erasures failed: ${plainFailure(error)}`);
+            }
+        }
+        erasures = progress.sealed;
         try {
             const checkpoint = await sealCheckpoint(connection.handle, {
                 ledger: ledger.ledger,
                 signer: deps.signer,
             });
             if (checkpoint) {
-                outcome = 'sealed';
+                if (outcome !== 'failed')
+                    outcome = 'sealed';
                 treeSize = checkpoint.tree_size;
             }
-            else {
+            else if (outcome !== 'failed') {
                 notes.push('nothing sealed, no entry since the last checkpoint');
             }
         }
@@ -87,7 +106,8 @@ async function sealOne(deps, ledger, now) {
                 ...base,
                 outcome: 'failed',
                 anchored: 0,
-                reason: `sealing failed: ${plainFailure(error)}`,
+                erasures,
+                reason: [`sealing failed: ${plainFailure(error)}`, ...notes].join('; '),
                 at: now().toISOString(),
             };
         }
@@ -125,7 +145,33 @@ async function sealOne(deps, ledger, now) {
         outcome,
         ...(treeSize === undefined ? {} : { treeSize }),
         anchored,
+        erasures,
         ...(notes.length > 0 ? { reason: notes.join('; ') } : {}),
         at: now().toISOString(),
     };
 }
+const rowsOf = (result) => Array.isArray(result) ? result : (result.rows ?? []);
+/**
+ * An existing sealing role gets the erasure grants only on its app's next apply, so 42501 (insufficient privilege)
+ * and 42883 (undefined function) mean "not yet", not broken. Read on the error or the driver error it wraps.
+ */
+function isMissingGrant(error) {
+    for (let e = error, depth = 0; e && depth < 3; depth++) {
+        const code = e.code;
+        if (code === '42501' || code === '42883')
+            return true;
+        e = e.cause;
+    }
+    return false;
+}
+async function sealErasures(handle, progress) {
+    const pending = rowsOf(await handle.execute(sql `select id, row_hash, erased_at from audit_pending_erasures()`));
+    for (const row of pending) {
+        if (!row.row_hash || row.erased_at === null || row.erased_at === undefined)
+            continue;
+        const erasedAt = row.erased_at instanceof Date ? row.erased_at : new Date(String(row.erased_at));
+        const erasureHash = await computeErasureHash(row.row_hash, erasedAt);
+        await handle.execute(sql `select audit_seal_erasure(${row.id}, ${erasureHash})`);
+        progress.sealed++;
+    }
+}

package/dist/audit/sealer-role.d.ts

@@ -26,7 +26,7 @@ export interface SealerRoleSql {
 }
 /**
  * Makes `user` true: it can log in with `password`, is no superuser and bypasses no row security, may read and
- * insert into the checkpoint, signing-key and anchor tables and run the two sealing functions, and holds nothing
+ * insert into the checkpoint, signing-key and anchor tables and run the sealing functions (leaves, key retirement, pending erasures, erasure sealing), and holds nothing
  * else. The grants are listed here and in `AUDIT_SEALER_GRANTS`; `audit/sealer-role.test.ts` runs a real
  * checkpoint as this role to prove the list is enough.
  */

package/dist/audit/sealer-role.js

@@ -36,7 +36,7 @@ const ident = (name) => `"${name.replace(/"/g, '""')}"`;
 const literal = (value) => `'${value.replace(/'/g, "''")}'`;
 /**
  * Makes `user` true: it can log in with `password`, is no superuser and bypasses no row security, may read and
- * insert into the checkpoint, signing-key and anchor tables and run the two sealing functions, and holds nothing
+ * insert into the checkpoint, signing-key and anchor tables and run the sealing functions (leaves, key retirement, pending erasures, erasure sealing), and holds nothing
  * else. The grants are listed here and in `AUDIT_SEALER_GRANTS`; `audit/sealer-role.test.ts` runs a real
  * checkpoint as this role to prove the list is enough.
  */

package/dist/audit/tick.js

@@ -15,6 +15,7 @@ export async function runAuditSealTick(deps) {
             entryKey: ledger.entryKey,
             outcome: 'skipped',
             anchored: 0,
+            erasures: 0,
             reason,
             at: now().toISOString(),
         };

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/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/modules/audit-ledger.d.ts

@@ -12,13 +12,15 @@ export declare const AUDIT_PACKAGE_VERSION = "0.14.0";
 /** Insert and read only: the runtime role has UPDATE, DELETE and TRUNCATE revoked on each. */
 export declare const AUDIT_APPEND_ONLY_TABLES: readonly string[];
 /**
- * What the app's runtime role may run: the two functions the chain is written through. Not granted: the erase
- * functions (`audit_erase_person`, `audit_seal_erasure`, `audit_pending_erasures`), because they change what the
- * ledger shows and whether the app may call them is an open decision (foundry#929 item 10); and the sealing
- * functions (`audit_chain_leaves`, `audit_retire_signing_key`), which only the platform's sealing role runs.
+ * What the app's runtime role may run: the two functions the chain is written through. Not granted: the sealing
+ * functions (`audit_chain_leaves`, `audit_retire_signing_key`) and the erasure sealing functions
+ * (`audit_pending_erasures`, `audit_seal_erasure`), which only the platform's sealing role runs. An app may list
+ * `audit_erase_person(text, text, text)` itself and nothing else from the erase set: it pseudonymises, and the
+ * sealing role seals each erasure in the next seal tick (William, 2026-10-26, settles foundry#929 item 10 for
+ * this case).
  */
 export declare const AUDIT_APP_GRANTS: readonly string[];
-/** What the platform's sealing role runs, beside the app's own: reads every leaf, retires a signing key. */
+/** What the platform's sealing role runs, beside the app's own: reads every leaf, retires a signing key, seals erasures. */
 export declare const AUDIT_SEALER_GRANTS: readonly string[];
 type Database = NonNullable<WorkerAppConfig['database']>;
 /**

package/dist/modules/audit-ledger.js

@@ -16,16 +16,20 @@ export const AUDIT_APPEND_ONLY_TABLES = [
     'audit_anchors',
 ];
 /**
- * What the app's runtime role may run: the two functions the chain is written through. Not granted: the erase
- * functions (`audit_erase_person`, `audit_seal_erasure`, `audit_pending_erasures`), because they change what the
- * ledger shows and whether the app may call them is an open decision (foundry#929 item 10); and the sealing
- * functions (`audit_chain_leaves`, `audit_retire_signing_key`), which only the platform's sealing role runs.
+ * What the app's runtime role may run: the two functions the chain is written through. Not granted: the sealing
+ * functions (`audit_chain_leaves`, `audit_retire_signing_key`) and the erasure sealing functions
+ * (`audit_pending_erasures`, `audit_seal_erasure`), which only the platform's sealing role runs. An app may list
+ * `audit_erase_person(text, text, text)` itself and nothing else from the erase set: it pseudonymises, and the
+ * sealing role seals each erasure in the next seal tick (William, 2026-10-26, settles foundry#929 item 10 for
+ * this case).
  */
 export const AUDIT_APP_GRANTS = ['audit_chain_tail()', 'audit_chain_tail_v2()'];
-/** What the platform's sealing role runs, beside the app's own: reads every leaf, retires a signing key. */
+/** What the platform's sealing role runs, beside the app's own: reads every leaf, retires a signing key, seals erasures. */
 export const AUDIT_SEALER_GRANTS = [
     'audit_chain_leaves(bigint, integer)',
     'audit_retire_signing_key(text)',
+    'audit_pending_erasures()',
+    'audit_seal_erasure(bigint, text)',
 ];
 const without = (list, drop) => (list ?? []).filter((item) => !drop.includes(item));
 /**

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';
@@ -1049,6 +1050,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);
@@ -3888,8 +3890,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,

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.

package/dist/plan/executor.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.

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/stage-env.js

@@ -19,6 +19,7 @@ export const STAGE_SIGN_IN_NAMES = [
     'AUTH_COOKIE_SECRET',
     'WORKSPACES_URL',
     'WORKSPACES_API_KEY',
+    'AUTH_EVENTS_SECRET',
     'MCP_AUDIENCE',
     'MCP_RESOURCE',
     'MCP_ISSUER',

package/dist/plan/stage-isolation.js

@@ -89,6 +89,7 @@ export const STAGE_ALLOWLIST = {
         'ANALYTICS_SITE_KEY',
         'WORKSPACES_URL',
         'WORKSPACES_API_KEY',
+        'AUTH_EVENTS_SECRET',
         'MCP_AUDIENCE',
         'MCP_RESOURCE',
         'MCP_ISSUER',

package/dist/plan/worker-app.d.ts

@@ -167,6 +167,8 @@ export interface WorkerAppWant {
         noDelete?: string[];
         grants?: string[];
         migrationsSha256?: string;
+        /** `uses.audit`: a hash of `AUDIT_SEALER_GRANTS`, so an applied app is planned again when the list changes and its sealing role gets the new grants. */
+        auditSealerGrants?: string;
     };
     /** `workerApp.triggers.crons`, sorted. Absent when none, so a Worker without cron keeps the marker it already has. */
     crons?: string[];
@@ -176,7 +178,7 @@ export interface WorkerAppWant {
      */
     secrets: {
         name: string;
-        source: 'generated' | 'keysCustody' | 'heldSecret';
+        source: 'generated' | 'keysCustody' | 'heldSecret' | 'authEvents';
         hostId?: string;
         version?: string;
     }[];

package/dist/plan/worker-app.js

@@ -1,8 +1,10 @@
 import { createHash, randomBytes } from 'node:crypto';
+import { AUDIT_SEALER_GRANTS } from '../modules/audit-ledger.js';
 import { APPS_DOMAIN, heldEnvRef } from '../org.js';
 import { WORKER_APP_KEYS_SECRET, WORKER_APP_KEYS_URL_VAR, workerAppHasBuild, workerAppHostId, } from '../worker-app-config.js';
 import { WORKER_APP_DNS_RECORD, pendingWorkerAppMigrations, strayContainerImage, withCallTimeout, workerAppRegistryPrefix, workerAppShape, workerAppUpload, } from '../worker-app-upload.js';
 import { entryAuthEnv } from './broker-entries.js';
+import { AUTH_EVENTS_ENV, ensureAuthEventsSecret } from './entry-auth-events.js';
 import { workerAppHostname } from './hostnames.js';
 import { workspaceWorkerParent } from './workspace-worker.js';
 import { appStepKey } from './platform-diff.js';
@@ -164,6 +166,9 @@ export function wantedWorkerApp(org, entry, recorded, input) {
                 missing.push(what);
         }
         secrets.push({ name: WORKER_APP_AUTH_KEY_SECRET, source: 'generated' });
+        // The signing secret of assistant events: made by rule 1 (`ensureAuthEventsSecret`), shared with the broker entry.
+        if (entry.uses?.auth?.mcp?.events)
+            secrets.push({ name: AUTH_EVENTS_ENV, source: 'authEvents' });
         if (entry.uses?.auth?.mcp) {
             for (const name of ['MCP_AUDIENCE', 'MCP_RESOURCE', 'MCP_ISSUER']) {
                 if (env[name])
@@ -203,6 +208,15 @@ export function wantedWorkerApp(org, entry, recorded, input) {
                         ...(app.database.migrationsSha256
                             ? { migrationsSha256: app.database.migrationsSha256 }
                             : {}),
+                        // The order of AUDIT_SEALER_GRANTS is part of the hash: a reorder plans every audit app once.
+                        ...(entry.uses?.audit === true
+                            ? {
+                                auditSealerGrants: createHash('sha256')
+                                    .update(JSON.stringify(AUDIT_SEALER_GRANTS))
+                                    .digest('hex')
+                                    .slice(0, 16),
+                            }
+                            : {}),
                     },
                 }
                 : {}),
@@ -567,6 +581,23 @@ async function deliverSecrets(deps, org, entryKey, want, context, at, call) {
         if (delivered[secret.name] !== version)
             generated.push({ name: secret.name, value, version });
     }
+    for (const secret of want.secrets) {
+        if (secret.source !== 'authEvents')
+            continue;
+        const value = await ensureAuthEventsSecret({
+            orgId: org.id,
+            slug: org.slug,
+            entryKey,
+            heldKeys,
+            recorded: () => context.recordedIds(),
+            record: (key, recordedValue) => context.recordScopeId(key, recordedValue),
+            persist: () => context.persistScopeIds(),
+            secret: (held) => deps.secret?.(held),
+        });
+        const version = secretVersion(value);
+        if (delivered[secret.name] !== version)
+            generated.push({ name: secret.name, value, version });
+    }
     // Held secrets: the company's value, read from the held-key store. The plan found each one held; a
     // value gone since stops the step, and the error names the ref, never a value.
     for (const secret of want.secrets) {

package/dist/plan/workspace-sign-in.d.ts

@@ -1,6 +1,6 @@
 import type { DeclaredOrg, HostingEntry } from '../org.js';
 import type { UnmanagedItem } from '../plan.js';
-import { type BrokerEntryInput, type BrokerEntryWant } from './broker-entries.js';
+import { type BrokerEntryInput, type BrokerEntryMcp, type BrokerEntryWant } from './broker-entries.js';
 import type { DraftStep } from './diff.js';
 import type { LiveResource } from './live.js';
 /** The step `coolify:workspace-broker-entry` and its action key, for the planner and the executor to share. */
@@ -10,12 +10,7 @@ export declare const WORKSPACE_BROKER_ENTRY_KIND = "workspace-broker-entry";
  * project in the test customers organisation (recorded by `zitadel:mcp-project` under the client's name), and the
  * onboarding page on the workspace host. `null` without `mcp` or until the project is recorded.
  */
-export declare function workspaceMcp(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
-    resource: string;
-    projectId: string;
-    loginHost: string;
-    onboardingUrl?: string;
-} | null;
+export declare function workspaceMcp(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): BrokerEntryMcp | null;
 /**
  * What the app's env says about who signs in at the workspace, as recorded so far, or `null` until the
  * organisation, client and issuer are all known. Non-secret values only.

package/dist/plan/workspace-sign-in.js

@@ -37,6 +37,8 @@ export function workspaceMcp(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}` } : {}),
     };
 }
 /**
@@ -90,7 +92,9 @@ export function liveClientIds(org, recorded) {
 /** What `ws.<key>.signin` records: the sign-in env above as JSON, or `null` while it is not all known. */
 export function workspaceSignInMarker(org, entry, recorded, issuer) {
     const env = workspaceAuthEnv(org, entry, recorded, issuer);
-    return env ? JSON.stringify(env) : null;
+    if (!env)
+        return null;
+    return entry.uses?.auth?.mcp?.events ? `${JSON.stringify(env)}+events` : JSON.stringify(env);
 }
 /**
  * The test customers organisation, planned once an entry's workspace signs in customers. Sign-up and the emailed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/foundry",
-  "version": "0.68.3",
+  "version": "0.70.0",
   "description": "Foundry's SDK: the declared org's types, the plan and apply contracts, and the state store's interface.",
   "repository": {
     "type": "git",