@wtfalch/foundry 0.59.0 → 0.61.0

package/dist/plan/locked-hostnames.d.ts

@@ -1,6 +1,6 @@
 import { type DeclaredOrg } from '../org.js';
-/** The labels an own org's services answer on, so no hosting entry may take them. */
-export declare const OWN_SERVICE_LABELS: readonly ["auth", "mail", "files", "sfu"];
+import { OWN_SERVICE_LABELS } from '../service-labels.js';
+export { OWN_SERVICE_LABELS };
 /**
  * The names under the org's domain that foundry owns, so no hosting entry may
  * take one: Agora, Boule, the cms studio when the site is on, calls when it uses the

package/dist/plan/locked-hostnames.js

@@ -1,11 +1,11 @@
 import { ownsServices } from '../org.js';
+import { OWN_SERVICE_LABELS } from '../service-labels.js';
 import { agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
 import { cmsStudioHostnameFor, siteHostnameFor } from './hostnames.js';
 import { loginHostnameFor } from './login-host.js';
 import { ownHostnames } from './own-hostnames.js';
-/** The labels an own org's services answer on, so no hosting entry may take them. */
-export const OWN_SERVICE_LABELS = ['auth', 'mail', 'files', 'sfu'];
+export { OWN_SERVICE_LABELS };
 /**
  * The names under the org's domain that foundry owns, so no hosting entry may
  * take one: Agora, Boule, the cms studio when the site is on, calls when it uses the

package/dist/plan/login-host.js

@@ -2,6 +2,7 @@ import { ownsServices } from '../org.js';
 import { AGORA_CLIENT_ID_SCOPE_KEY, APP_CLIENT_ID_SCOPE_KEY, CMS_CLIENT_ID_SCOPE_KEY, ENTRY_CLIENT_ID_SCOPE_PREFIX, agoraHostnameFor, } from './agora.js';
 import { BOULE_CLIENT_ID_SCOPE_KEY, bouleHostnameFor } from './boule.js';
 import { SIGN_IN_IN_APP_SCOPE_KEY, inAppSignIn, inAppStatePairs, } from './sign-in.js';
+import { testCustomersEntries, testCustomersOrgKey, workspaceClientKey, } from './workspace-client.js';
 /**
  * #267: what both the planner (`diff.ts`) and the executor (`executor.ts`)
  * need to agree on for an org's own company login host -- the hostname and
@@ -168,7 +169,11 @@ export const LOGIN_BINDING_SCOPE_KEY = 'login_host_binding';
  * is no longer declared is not here, so it stays bound as before.
  */
 export function customersEntryKeys(org) {
-    return new Set(org.hosting.entries.filter((e) => e.uses?.auth?.users === 'customers').map((e) => e.key));
+    return new Set([
+        ...org.hosting.entries.filter((e) => e.uses?.auth?.users === 'customers').map((e) => e.key),
+        // A workspace's customers client signs in the test customers organisation, on the shared host as well.
+        ...testCustomersEntries(org).map((e) => workspaceClientKey(e.key)),
+    ]);
 }
 /**
  * The org's recorded app client ids (hosted app, each entry's own bar a customers entry, cms, agora, boule),
@@ -201,13 +206,14 @@ export const LOGIN_CLIENT_ORGS_SCOPE_KEY = 'login_client_orgs';
  */
 export function customersClientOrganizations(org, recorded) {
     const customersOrgId = recorded[`zitadel:customers:${org.id}`];
-    if (!customersOrgId)
-        return {};
+    const testOrgId = recorded[testCustomersOrgKey(org.id)];
     const map = {};
+    const workspaceKeys = new Set(testCustomersEntries(org).map((e) => workspaceClientKey(e.key)));
     for (const key of customersEntryKeys(org)) {
         const clientId = recorded[ENTRY_CLIENT_ID_SCOPE_PREFIX + key];
-        if (clientId)
-            map[clientId] = customersOrgId;
+        const orgId = workspaceKeys.has(key) ? testOrgId : customersOrgId;
+        if (clientId && orgId)
+            map[clientId] = orgId;
     }
     return map;
 }

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

@@ -0,0 +1,36 @@
+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
+ * 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.
+ */
+/** The path Boule's customer-grants routes live under (`uses.customerGrants`, F13). */
+export declare const CUSTOMER_GRANTS_PATH = "/api/customer-grants";
+/** The paths of `entry` that machines call, in a fixed order, without repeats. */
+export declare function entryMachinePaths(entry: Pick<HostingEntry, 'uses'>): string[];
+/** The step key stem of one machine bypass: a hash of host and path, so it fits a key and needs no escaping. */
+export declare function machineBypassKey(host: string, path: string): string;
+/** The recorded `host/path` a machine bypass was made for, by its step key stem, read for the delete's wording. */
+export declare const machineBypassScopeKey: (stem: string) => string;
+export interface MachineBypass {
+    entry: string;
+    host: string;
+    path: string;
+}
+/** Every machine bypass wanted, by step key stem, and a line for each case where an entry's machine path gets none. */
+export declare function declaredMachineBypasses(org: DeclaredOrg, declared?: DeclaredOrg): {
+    bypasses: Map<string, MachineBypass>;
+    notes: string[];
+};
+/**
+ * One step per wanted machine bypass with no recorded Access application, and one deleting step per recorded
+ * bypass no longer wanted (a removed path, a removed gate, a removed entry). A delete is not `destroys`: it
+ * loses no data and only closes a path again, so it needs no typed confirmation.
+ */
+export declare function planMachineBypasses(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, declared?: DeclaredOrg): {
+    steps: DraftStep[];
+    notes: string[];
+};

package/dist/plan/machine-paths.js

@@ -0,0 +1,137 @@
+import { createHash } from 'node:crypto';
+import { isLiveEntry } from '../org.js';
+import { resolveGateHostnames } from './gates.js';
+import { entryHostnames, workspaceHost } from './hostnames.js';
+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
+ * 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.
+ */
+/** The path Boule's customer-grants routes live under (`uses.customerGrants`, F13). */
+export const CUSTOMER_GRANTS_PATH = '/api/customer-grants';
+/** The paths of `entry` that machines call, in a fixed order, without repeats. */
+export function entryMachinePaths(entry) {
+    const paths = [];
+    const webhook = entry.uses?.ai?.webhookPath;
+    if (webhook !== undefined)
+        paths.push(webhook);
+    if (entry.uses?.customerGrants)
+        paths.push(CUSTOMER_GRANTS_PATH);
+    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 === '..');
+/** 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}`;
+/**
+ * The gated hosts an entry is served on: the exact names of its own gates, the entry's live names under a
+ * gated wildcard (`*.<domain>` cannot carry a path), and the entry's workspace host when `declared` gives it one.
+ */
+function gatedHosts(org, declared, entry) {
+    const hosts = new Set();
+    const live = org.hosting.entries.find((e) => e.key === entry.key);
+    if (live && org.hosting.enabled && org.domain) {
+        const names = resolveGateHostnames(org.domain, live.gates.flatMap((gate) => gate.hostnames));
+        for (const name of names) {
+            if (!name.startsWith('*.'))
+                hosts.add(name);
+        }
+        const wildcards = names.filter((name) => name.startsWith('*.')).map((name) => name.slice(1));
+        for (const host of entryHostnames(org, live)) {
+            if (wildcards.some((suffix) => host.endsWith(suffix)))
+                hosts.add(host);
+        }
+    }
+    if (workspaceEntries(declared).some((e) => e.key === entry.key)) {
+        hosts.add(workspaceHost(declared.slug, entry.key));
+    }
+    return [...hosts].sort();
+}
+/** Every machine bypass wanted, by step key stem, and a line for each case where an entry's machine path gets none. */
+export function declaredMachineBypasses(org, declared = org) {
+    const bypasses = new Map();
+    const notes = [];
+    if (!declared.hosting.enabled)
+        return { bypasses, notes };
+    for (const entry of declared.hosting.entries) {
+        const paths = entryMachinePaths(entry);
+        if (paths.length === 0)
+            continue;
+        const hosts = gatedHosts(org, declared, entry);
+        if (hosts.length === 0) {
+            notes.push(`${org.slug}'s ${entry.key} has machine paths (${paths.join(', ')}) but no gated host${isLiveEntry(entry) ? '' : ' and no workspace'}, so no Access bypass is planned for them`);
+            continue;
+        }
+        for (const path of paths) {
+            if (!edgeAccepts(path)) {
+                notes.push(`${org.slug}'s ${entry.key} machine path ${path} gets no Access bypass: edge accepts only lower-case a-z, 0-9, '.', '_', '~' and '-' in path segments`);
+                continue;
+            }
+            for (const host of hosts) {
+                bypasses.set(machineBypassKey(host, path), { entry: entry.key, host, path });
+            }
+        }
+    }
+    return { bypasses, notes };
+}
+const accessRecordKey = (org, stem) => `cloudflare:access:${org.id}:${stem}`;
+/**
+ * One step per wanted machine bypass with no recorded Access application, and one deleting step per recorded
+ * bypass no longer wanted (a removed path, a removed gate, a removed entry). A delete is not `destroys`: it
+ * loses no data and only closes a path again, so it needs no typed confirmation.
+ */
+export function planMachineBypasses(org, recordedIds, declared = org) {
+    const { bypasses, notes } = declaredMachineBypasses(org, declared);
+    const steps = [];
+    const prefix = accessRecordKey(org, 'mp-');
+    for (const [name, id] of Object.entries(recordedIds)) {
+        if (!id || !name.startsWith(prefix))
+            continue;
+        const stem = name.slice(accessRecordKey(org, '').length);
+        if (bypasses.has(stem))
+            continue;
+        const was = recordedIds[machineBypassScopeKey(stem)];
+        steps.push({
+            action: {
+                system: 'cloudflare',
+                kind: 'access',
+                key: appStepKey(org, stem),
+                desired: { machineBypass: 'delete' },
+            },
+            step: {
+                description: `remove the Access bypass ${was ? `on ${was} ` : ''}(${org.slug}'s ${stem}): the machine path is no longer declared`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    for (const [stem, { entry, host, path }] of [...bypasses].sort(([a], [b]) => a.localeCompare(b))) {
+        if (recordedIds[accessRecordKey(org, stem)])
+            continue;
+        steps.push({
+            action: {
+                system: 'cloudflare',
+                kind: 'access',
+                key: appStepKey(org, stem),
+                desired: { machineBypass: 'apply', entry, domain: `${host}${path}` },
+            },
+            step: {
+                description: `let machine callers through Cloudflare Access on ${host}${path} (${org.slug}'s ${entry}): a bypass for the path only`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, notes };
+}

package/dist/plan/mcp.d.ts

@@ -30,7 +30,7 @@ type Blocked = Array<{
 export declare const MCP_CALL_TIMEOUT_MS = 60000;
 /** The want of the access step, recorded when it is done. */
 export declare const mcpAccessWant: (org: DeclaredOrg) => string;
-export declare function planMcp(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], zitadelMcp: boolean): {
+export declare function planMcp(org: DeclaredOrg, recorded: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], zitadelMcp: boolean, declaredOrg?: DeclaredOrg): {
     steps: DraftStep[];
     blocked: Blocked;
 };

package/dist/plan/mcp.js

@@ -1,23 +1,44 @@
 import { ACCESS_TOKEN_LIFETIME_APPLIED_SCOPE_KEY, MCP_ACCESS_TOKEN_LIFETIME_SECONDS, entryMcpAccessAppliedScopeKey, entryMcpProjectScopeKey, mcpCallbackUri, } from './broker-entries.js';
 import { withCallTimeout } from './worker-app.js';
+import { testCustomersOrgKey, workspaceAuthEntries, workspaceAuthEntryOf, workspaceClientKey, } from './workspace-client.js';
 /** A ZITADEL call of the MCP steps that has not answered in this long fails the step; the next apply repeats it. */
 export const MCP_CALL_TIMEOUT_MS = 60_000;
 /** The want of the access step, recorded when it is done. */
 export const mcpAccessWant = (org) => JSON.stringify({ accessTokenType: 'jwt', redirectUri: mcpCallbackUri(org) });
-export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
+export function planMcp(org, recorded, plannedSteps, zitadelMcp, declaredOrg = org) {
     const steps = [];
     const blocked = [];
-    const entries = org.hosting.enabled
+    const live = org.hosting.enabled
         ? org.hosting.entries.filter((e) => Boolean(e.uses?.auth?.mcp))
         : [];
-    if (entries.length === 0)
+    const workspaces = workspaceAuthEntries(declaredOrg).filter((e) => e.uses?.auth?.mcp);
+    if (live.length === 0 && workspaces.length === 0)
         return { steps, blocked };
     const planned = (system, kind, key) => plannedSteps.some((p) => p.action.system === system &&
         p.action.kind === kind &&
         (key === undefined || p.action.key === key));
-    for (const entry of entries) {
-        const at = `${org.slug}'s ${entry.key} MCP`;
-        const stepKey = `${org.id}:${entry.key}`;
+    const targets = [
+        ...live.map((entry) => ({
+            clientKey: entry.key,
+            at: `${org.slug}'s ${entry.key} MCP`,
+            customersOrg: {
+                recorded: `zitadel:customers:${org.id}`,
+                kind: 'customers',
+                what: 'customers',
+            },
+        })),
+        ...workspaces.map((entry) => ({
+            clientKey: workspaceClientKey(entry.key),
+            at: `${org.slug}'s ${entry.key} workspace MCP`,
+            customersOrg: {
+                recorded: testCustomersOrgKey(org.id),
+                kind: 'customers-test',
+                what: 'test customers',
+            },
+        })),
+    ];
+    for (const { clientKey, at, customersOrg } of targets) {
+        const stepKey = `${org.id}:${clientKey}`;
         if (!zitadelMcp) {
             blocked.push({
                 description: `${at} is blocked, not planned: the host's ZITADEL client cannot set JWT access tokens or the access-token lifetime`,
@@ -25,10 +46,10 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
             });
             continue;
         }
-        if (!recorded[entryMcpProjectScopeKey(entry.key)]) {
-            if (!recorded[`zitadel:customers:${org.id}`] && !planned('zitadel', 'customers')) {
+        if (!recorded[entryMcpProjectScopeKey(clientKey)]) {
+            if (!recorded[customersOrg.recorded] && !planned('zitadel', customersOrg.kind)) {
                 blocked.push({
-                    description: `${at} project is blocked, not planned: the customers organisation id is not recorded yet`,
+                    description: `${at} project is blocked, not planned: the ${customersOrg.what} organisation id is not recorded yet`,
                     key: `zitadel:mcp-project:${stepKey}`,
                 });
             }
@@ -36,15 +57,15 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
                 steps.push({
                     action: { system: 'zitadel', kind: 'mcp-project', key: stepKey, desired: {} },
                     step: {
-                        description: `make the empty project that is ${org.slug}'s ${entry.key} MCP token audience`,
+                        description: `make the empty project that is ${org.slug}'s ${clientKey} MCP token audience`,
                         destroys: false,
                         migrates: false,
                     },
                 });
             }
         }
-        if (recorded[entryMcpAccessAppliedScopeKey(entry.key)] !== mcpAccessWant(org)) {
-            if (!recorded[`zitadel:app:${entry.key}`] && !planned('zitadel', 'app', entry.key)) {
+        if (recorded[entryMcpAccessAppliedScopeKey(clientKey)] !== mcpAccessWant(org)) {
+            if (!recorded[`zitadel:app:${clientKey}`] && !planned('zitadel', 'app', clientKey)) {
                 blocked.push({
                     description: `${at} access is blocked, not planned: the sign-in client is not recorded yet`,
                     key: `zitadel:mcp-access:${stepKey}`,
@@ -54,7 +75,7 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
                 steps.push({
                     action: { system: 'zitadel', kind: 'mcp-access', key: stepKey, desired: {} },
                     step: {
-                        description: `${org.slug}'s ${entry.key} sign-in client issues JWT access tokens and accepts ${mcpCallbackUri(org)}`,
+                        description: `${org.slug}'s ${clientKey} sign-in client issues JWT access tokens and accepts ${mcpCallbackUri(org)}`,
                         destroys: false,
                         migrates: false,
                     },
@@ -75,6 +96,17 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
     }
     return { steps, blocked };
 }
+/**
+ * The entry a step key names: a live entry by its key, or a workspace by its client name `<key>-work`. A
+ * workspace's client name cannot be another entry's key (`client_name_taken`), so the two never meet.
+ */
+function mcpTarget(org, clientKey) {
+    const live = org.hosting.entries.find((e) => e.key === clientKey && e.uses?.auth?.mcp);
+    if (live)
+        return { workspace: false, entry: live };
+    const entry = workspaceAuthEntryOf(org, clientKey);
+    return entry?.uses?.auth?.mcp ? { workspace: true, entry } : undefined;
+}
 // ---- the apply -------------------------------------------------------------
 /**
  * The empty project in the customers organisation that is an entry's MCP token
@@ -85,10 +117,10 @@ export function planMcp(org, recorded, plannedSteps, zitadelMcp) {
 export async function applyMcpProject(zitadel, org, action, context) {
     const entryKey = action.key.slice(org.id.length + 1);
     const at = `zitadel:mcp-project for ${org.slug} entry '${entryKey}'`;
-    if (!org.hosting.entries.some((e) => e.key === entryKey && e.uses?.auth?.mcp)) {
+    const target = mcpTarget(org, entryKey);
+    if (!target)
         throw new Error(`${at}: the entry no longer declares uses.auth.mcp`);
-    }
-    const customersOrgId = context.recordedIds()[`zitadel:customers:${org.id}`];
+    const customersOrgId = context.recordedIds()[target.workspace ? testCustomersOrgKey(org.id) : `zitadel:customers:${org.id}`];
     if (!customersOrgId)
         throw new Error(`${at}: the customers organisation is not recorded yet`);
     const { project } = await withCallTimeout(MCP_CALL_TIMEOUT_MS, `${at}: find or create the project`, () => zitadel.findOrCreateProject(customersOrgId, `${org.slug}-${entryKey}-mcp`));
@@ -105,7 +137,7 @@ export async function applyMcpAccess(zitadel, org, action, context) {
     const ensure = zitadel.ensureOidcAppMcpAccess?.bind(zitadel);
     if (!ensure)
         throw new Error(`${at}: the ZITADEL client cannot set JWT access tokens`);
-    if (!org.hosting.entries.some((e) => e.key === entryKey && e.uses?.auth?.mcp)) {
+    if (!mcpTarget(org, entryKey)) {
         throw new Error(`${at}: the entry no longer declares uses.auth.mcp`);
     }
     const recorded = context.recordedIds();

package/dist/plan/org-apps-admin.d.ts

@@ -0,0 +1,108 @@
+import { type DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+import type { CoolifyPort } from './executor.js';
+import { type JobRuntime } from './job-app.js';
+import type { StepScope } from './own-services.js';
+/** The role's name on the server: the org's slug plus `_apps_admin`. */
+export declare const appsAdminRoleName: (org: Pick<DeclaredOrg, "slug">) => string;
+/** The job app's name in Coolify. */
+export declare const appsAdminJobName: (org: Pick<DeclaredOrg, "slug">) => string;
+/** Recorded once the role is made, its password set, and the URL delivered. */
+export declare const ORG_APPS_ADMIN_SCOPE_KEY = "org_apps_admin";
+/**
+ * An opaque id, set once the password is minted and the job that sets it is about to run, until the URL is
+ * delivered. Never the password. A failure before that point leaves no id, so the next apply tries again.
+ */
+export declare const ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY = "org_apps_admin_undelivered";
+/** The job app's id while it exists. */
+export declare const ORG_APPS_ADMIN_JOB_APP_SCOPE_KEY = "org_apps_admin_job_app";
+/** Where the host holds the role's connection URL, once delivered -- `deliverSecret`'s own naming convention. */
+export declare const appsAdminUrlRef: (org: Pick<DeclaredOrg, "slug">) => string;
+/** How many times the URL is handed to `deliverSecret`. */
+export declare const ORG_APPS_ADMIN_DELIVERY_ATTEMPTS = 3;
+export interface PlanOrgAppsAdminOptions {
+    /** The host can store a secret under a ref (`deliverSecret`). Default true. */
+    canHoldSecrets?: boolean;
+}
+/**
+ * Pure. Plans `coolify:org-apps-admin` once, after the company's Postgres server is recorded
+ * (platform-step rule 2: blocked, not failing, while it is not). A lost mint -- an undelivered id
+ * with no done guard -- is reported blocked and never minted again (rule 1); the operator clears the
+ * recorded id once the role is confirmed gone from the server.
+ */
+export declare function planOrgAppsAdminStep(org: Pick<DeclaredOrg, 'id' | 'slug'>, recordedIds: Readonly<Record<string, string>>, options?: PlanOrgAppsAdminOptions): {
+    step: DraftStep | null;
+    blocked: string | null;
+};
+export interface PlanAppsAdminOptions {
+    canHoldSecrets: boolean;
+    /** `coolify:org-postgres` is planned in this same plan, ahead of this step. */
+    postgresPlanned: boolean;
+}
+/**
+ * Pure. F4 (#925): the wiring of {@link planOrgAppsAdminStep} to `org.boule.apps`. Apps on: the mint
+ * step, once Boule (which receives the URL) and the Postgres server are recorded or planned. Apps off with
+ * the role recorded (or a mint never delivered): the retire step, which needs no secret and drops nothing.
+ */
+export declare function planAppsAdmin(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], options: PlanAppsAdminOptions): {
+    steps: DraftStep[];
+    blocked: Array<{
+        description: string;
+        key: string;
+    }>;
+};
+/**
+ * The job's script: makes the role (idempotent, kept if it already exists), sets its password and grants
+ * it CONNECT on `postgres`. It revokes nothing from PUBLIC (see the file comment). Roles are made by
+ * `format('%I')` and the password by `format('%L')`, so no value is spliced into SQL by the shell. Setting
+ * the password again is harmless, so a mint that is repeated simply replaces it. It never prints a URL or a password: psql's output is discarded and the one
+ * error line names neither.
+ */
+export declare function orgAppsAdminScript(role: string, mode?: 'mint' | 'retire'): string[];
+/** The job: the same pinned image as the other Postgres jobs, so `psql` matches the server's major version. */
+export declare function orgAppsAdminDockerfile(role: string, mode?: 'mint' | 'retire'): string;
+type AppsAdminCoolify = Pick<CoolifyPort, 'findOrCreateEnvironment' | 'findApplicationByName' | 'getApplication' | 'createDockerfileApplication' | 'updateApplication' | 'bulkUpsertEnvs' | 'deploy' | 'raw'>;
+/** Everything the step takes from the executor. New ones go here, never as positional arguments. */
+export interface OrgAppsAdminDeps {
+    coolify: AppsAdminCoolify;
+    ensureProject(): Promise<string>;
+    serverUuid(): Promise<string>;
+    /** Starts the company's Postgres server when it is not running and returns its live record. */
+    startDatabase(uuid: string): Promise<{
+        internal_db_url?: string;
+        status?: string;
+    }>;
+    deliverSecret(ref: string, secret: string): Promise<void>;
+    /** Registers a value for redaction. */
+    onSecret?(value: string): void;
+    /** Test seam: a password. Default: 24 random bytes, base64url. */
+    mintPassword?(): string;
+    /** Test seam: an opaque id. */
+    mintId?(): string;
+    runtime?: JobRuntime;
+}
+/**
+ * Makes the role true and delivers its connection URL. The password is minted in memory. The opaque id
+ * {@link ORG_APPS_ADMIN_UNDELIVERED_SCOPE_KEY} is recorded and persisted only once the job that sets the
+ * password is about to be deployed ("password minted and role touched"); a failure before that leaves no
+ * id and the next apply simply retries, since setting a password again is harmless. The done guard is
+ * recorded only once the URL is delivered. A run that dies between the two finds the id and stops (the
+ * planner reports it blocked); retiring the role (apps off) clears it.
+ */
+export declare function provisionOrgAppsAdmin(scope: StepScope, deps: OrgAppsAdminDeps, org: DeclaredOrg): Promise<void>;
+/** What the retire form takes from the executor: the mint form's deps, and the held-key blanking. */
+export interface RetireOrgAppsAdminDeps extends Omit<OrgAppsAdminDeps, 'deliverSecret'> {
+    /** Blanks the held URL (the store has no delete: an empty value reads as not held). */
+    clearHeldUrl(ref: string): Promise<void>;
+    /** Takes `APPS_DATABASE_ADMIN_URL` out of Boule's env. A row already gone is not an error. */
+    removeBouleEnv(): Promise<void>;
+}
+/**
+ * Apps went off (F4, #925): the role stops logging in, the URL leaves Boule's env and the held store,
+ * and the recorded ids are cleared last so a failed run repeats. Never drops the role, a database or
+ * a role an app made (CLAUDE.md: never drop data); turning apps on again mints a new password for the
+ * same role. A recorded mint that was never delivered is retired the same way, which is also how an
+ * operator unblocks a lost mint. The job needs the server's admin URL and nothing else secret.
+ */
+export declare function retireOrgAppsAdmin(scope: StepScope, deps: RetireOrgAppsAdminDeps, org: DeclaredOrg): Promise<void>;
+export {};