@wtfalch/foundry 0.60.0 → 0.61.0

package/dist/plan/github-source.js

@@ -0,0 +1,140 @@
+import { companyGithubFor } from '../org.js';
+import { withTimeout } from './call-timeout.js';
+import { PLATFORM_GITHUB_APP_REFS } from './held-key-refs.js';
+/** Recorded after the source is made: the installation id it is bound to, so a changed installation plans the step again. */
+export const GITHUB_SOURCE_INSTALLATION_SCOPE_KEY = 'github_source_installation';
+/** The Coolify private key every company source shares: the platform GitHub App's key, made once. */
+export const GITHUB_SOURCE_KEY_NAME = 'platform-github-app';
+/** Every Coolify call this module makes is cut off after this long. */
+export const GITHUB_SOURCE_TIMEOUT_MS = 20_000;
+const GITHUB_API_URL = 'https://api.github.com';
+const GITHUB_HTML_URL = 'https://github.com';
+/** The recorded resource id (`serviceIds` key) of a company's source: the step is keyed by the org id. */
+export function githubSourceResourceKey(orgId) {
+    return `coolify:github-source:${orgId}`;
+}
+/** The Coolify name of a company's GitHub source. */
+export function githubSourceName(slug) {
+    return `${slug}-github`;
+}
+/** True when an app of this company is built from the company's own account, so it needs the company's source. */
+export function needsCompanyGithubSource(org) {
+    return (org.hosting.enabled &&
+        org.hosting.entries.some((e) => !e.workerApp && companyGithubFor(org.hosting, e.repo)));
+}
+/**
+ * `coolify:github-source` (keyed by the org id): the company's own Coolify GitHub App source, bound to its
+ * installation id. Blocked, not planned, while a key of the platform's GitHub App is not held. Planned again
+ * when the recorded source is missing or was made for another installation.
+ */
+export function planGithubSource(org, recordedIds, keys) {
+    const github = org.hosting.github;
+    if (!github || !needsCompanyGithubSource(org))
+        return { step: null, blocked: [] };
+    const recorded = Boolean(recordedIds[githubSourceResourceKey(org.id)]) &&
+        recordedIds[GITHUB_SOURCE_INSTALLATION_SCOPE_KEY] === String(github.installationId);
+    if (recorded)
+        return { step: null, blocked: [] };
+    const blockedItem = (why) => ({
+        step: null,
+        blocked: [
+            {
+                description: `${org.slug}'s GitHub source is blocked, not planned: ${why}`,
+                key: 'github-source',
+            },
+        ],
+    });
+    if (!keys?.store) {
+        return blockedItem('the host gave no reader for the platform GitHub App keys');
+    }
+    if (keys.missing.length > 0) {
+        return blockedItem(`the platform GitHub App keys are not all held (${keys.missing.join(', ')})`);
+    }
+    return {
+        step: {
+            action: {
+                system: 'coolify',
+                kind: 'github-source',
+                key: org.id,
+                desired: { installationId: github.installationId, account: github.account },
+            },
+            step: {
+                description: `make ${org.slug}'s Coolify GitHub source for installation ${github.installationId} on ${github.account}`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+        blocked: [],
+    };
+}
+const isRecord = (v) => typeof v === 'object' && v !== null;
+/**
+ * The uuid of the company's Coolify GitHub source: found by name when it is bound to the company's installation,
+ * else made from the platform GitHub App's held keys (`PLATFORM_GITHUB_APP_REFS`) and the Coolify private key
+ * `platform-github-app` (found, else made). Every Coolify call has a timeout and a failure is fixed text: a
+ * Coolify error can echo the request body, which holds the App's secrets. A failure after the private key was
+ * made leaves that key (shared, found by name next run) and no source; the source is the last call.
+ */
+export async function ensureGithubSource(deps) {
+    const { label, github } = deps;
+    const timeout = deps.timeoutMs ?? GITHUB_SOURCE_TIMEOUT_MS;
+    const held = {
+        appId: '',
+        clientId: '',
+        clientSecret: '',
+        webhookSecret: '',
+        privateKey: '',
+    };
+    for (const [name, ref] of Object.entries(PLATFORM_GITHUB_APP_REFS)) {
+        const value = await deps.heldKeys.resolve(ref);
+        if (!value)
+            throw new Error(`${label}: held key ${ref} is not held`);
+        deps.secret(value);
+        held[name] = value;
+    }
+    const appId = Number(held.appId);
+    if (!Number.isSafeInteger(appId) || appId <= 0) {
+        throw new Error(`${label}: held key ${PLATFORM_GITHUB_APP_REFS.appId} is not a positive integer`);
+    }
+    const name = githubSourceName(deps.slug);
+    const sources = await withTimeout(`${label}: listing Coolify GitHub sources`, timeout, () => deps.coolify.raw('GET', '/github-apps'));
+    if (!Array.isArray(sources))
+        throw new Error(`${label}: Coolify's GitHub source list was not a list`);
+    const existing = sources.find((s) => isRecord(s) && s.name === name);
+    if (isRecord(existing) && typeof existing.uuid === 'string') {
+        if (existing.installation_id === github.installationId)
+            return { uuid: existing.uuid };
+        throw new Error(`${label}: Coolify already has a GitHub source named ${name} for another installation; remove it in Coolify and apply again`);
+    }
+    const keysList = await withTimeout(`${label}: listing Coolify private keys`, timeout, () => deps.coolify.raw('GET', '/security/keys'));
+    if (!Array.isArray(keysList))
+        throw new Error(`${label}: Coolify's private key list was not a list`);
+    const foundKey = keysList.find((k) => isRecord(k) && k.name === GITHUB_SOURCE_KEY_NAME);
+    let keyUuid = isRecord(foundKey) && typeof foundKey.uuid === 'string' ? foundKey.uuid : null;
+    if (!keyUuid) {
+        const madeKey = await withTimeout(`${label}: making the Coolify private key`, timeout, () => deps.coolify.raw('POST', '/security/keys', {
+            name: GITHUB_SOURCE_KEY_NAME,
+            description: "The platform's GitHub App private key, shared by every company source",
+            private_key: held.privateKey,
+        }));
+        keyUuid = isRecord(madeKey) && typeof madeKey.uuid === 'string' ? madeKey.uuid : null;
+        if (!keyUuid)
+            throw new Error(`${label}: Coolify gave no uuid for the private key`);
+    }
+    const made = await withTimeout(`${label}: making the Coolify GitHub source`, timeout, () => deps.coolify.raw('POST', '/github-apps', {
+        name,
+        api_url: GITHUB_API_URL,
+        html_url: GITHUB_HTML_URL,
+        app_id: appId,
+        installation_id: github.installationId,
+        client_id: held.clientId,
+        client_secret: held.clientSecret,
+        webhook_secret: held.webhookSecret,
+        private_key_uuid: keyUuid,
+        is_system_wide: false,
+    }));
+    if (!isRecord(made) || typeof made.uuid !== 'string') {
+        throw new Error(`${label}: Coolify gave no uuid for the GitHub source`);
+    }
+    return { uuid: made.uuid };
+}

package/dist/plan/held-key-refs.d.ts

@@ -13,3 +13,15 @@ export declare const PLATFORM_AI_MANAGEMENT_KEY_REF = "ai:platform:managementKey
 export declare const PROXY_LABEL_TOKEN_REF = "proxy:labels:token";
 /** The ref the management private key (PKCS#8 PEM) is delivered under. */
 export declare const FILES_MANAGEMENT_KEY_REF = "files:platform:managementKey";
+/**
+ * The platform's GitHub App, held by the operator (Archon's GitHub App setup), one ref per value. A company's
+ * Coolify GitHub source (`coolify:github-source`) is made from these and the company's installation id. All five
+ * must be held before that step is planned; a ref is never a value.
+ */
+export declare const PLATFORM_GITHUB_APP_REFS: {
+    readonly appId: "platform:github-app:app-id";
+    readonly clientId: "platform:github-app:client-id";
+    readonly clientSecret: "platform:github-app:client-secret";
+    readonly webhookSecret: "platform:github-app:webhook-secret";
+    readonly privateKey: "platform:github-app:private-key";
+};

package/dist/plan/held-key-refs.js

@@ -13,3 +13,15 @@ export const PLATFORM_AI_MANAGEMENT_KEY_REF = 'ai:platform:managementKey';
 export const PROXY_LABEL_TOKEN_REF = 'proxy:labels:token';
 /** The ref the management private key (PKCS#8 PEM) is delivered under. */
 export const FILES_MANAGEMENT_KEY_REF = 'files:platform:managementKey';
+/**
+ * The platform's GitHub App, held by the operator (Archon's GitHub App setup), one ref per value. A company's
+ * Coolify GitHub source (`coolify:github-source`) is made from these and the company's installation id. All five
+ * must be held before that step is planned; a ref is never a value.
+ */
+export const PLATFORM_GITHUB_APP_REFS = {
+    appId: 'platform:github-app:app-id',
+    clientId: 'platform:github-app:client-id',
+    clientSecret: 'platform:github-app:client-secret',
+    webhookSecret: 'platform:github-app:webhook-secret',
+    privateKey: 'platform:github-app:private-key',
+};

package/dist/plan/hostnames.d.ts

@@ -6,6 +6,11 @@ import type { DeclaredOrg, HostingEntry } from '../org.js';
  * acted on elsewhere.
  */
 export declare function entryHostnames(org: DeclaredOrg, entry: HostingEntry): string[];
+/**
+ * The host that actually serves an entry: its first live name, or, when it is not live (`live: false`, so it
+ * has none), its workspace host. `null` for an entry with neither. The ai webhook is registered here.
+ */
+export declare function entryServingHost(org: DeclaredOrg, entry: HostingEntry): string | null;
 /**
  * The one exact name a Worker app is served at (ADR 0002): `<host>.<domain>` or
  * the apex on the org's own domain, else `<slug>-<key>.oikos.host` (one label
@@ -13,6 +18,10 @@ export declare function entryHostnames(org: DeclaredOrg, entry: HostingEntry): s
  * `<slug>.oikos.host` for the main entry.
  */
 export declare function workerAppHostname(org: DeclaredOrg, entry: HostingEntry): string;
+/** An entry's private workspace address: `work-<slug>-<key>.companyincluded.app`, one label deep so the free certificate covers it. */
+export declare function workspaceHost(slug: string, key: string): string;
+/** The company's test inbox: the stage mail sink's web page, `inbox-<slug>.companyincluded.app`. */
+export declare function workspaceInboxHost(slug: string): string;
 /**
  * The wildcard name (`*.<domain>`) when an entry declares `'*'`, else `null`.
  * Like `entryHostnames`, it is read only while hosting is on, `usesDomain` is

package/dist/plan/hostnames.js

@@ -1,7 +1,9 @@
-import { isMainEntry, mainEntry } from '../org.js';
+import { INBOX_HOST_PREFIX, WORKSPACE_HOST_PREFIX } from '../hosted-label.js';
+import { APPS_DOMAIN, isMainEntry, mainEntry } from '../org.js';
 import { workerAppHostnameOf } from '../worker-app-config.js';
 import { agoraHostnameFor } from './agora.js';
 import { bouleHostnameFor } from './boule.js';
+import { workspaceWorkerParent } from './workspace-worker.js';
 /**
  * The full names an entry is served at. With `hosting.usesDomain` off, or no
  * domain, `hostnames` is not read: the main entry is at `<slug>.oikos.host`
@@ -10,13 +12,27 @@ import { bouleHostnameFor } from './boule.js';
  */
 export function entryHostnames(org, entry) {
     const { domain } = org;
+    if (entry.live === false)
+        return [];
     if (entry.workerApp)
         return [workerAppHostname(org, entry)];
+    if (entry.hostedName !== undefined)
+        return [`${entry.hostedName}.${APPS_DOMAIN}`];
     if (!org.hosting.usesDomain || !domain) {
         return isMainEntry(entry) ? [`${org.slug}.oikos.host`] : [];
     }
     return entry.hostnames.flatMap((name) => name === '*' ? [] : name === '@' ? [domain] : [`${name}.${domain}`]);
 }
+/**
+ * The host that actually serves an entry: its first live name, or, when it is not live (`live: false`, so it
+ * has none), its workspace host. `null` for an entry with neither. The ai webhook is registered here.
+ */
+export function entryServingHost(org, entry) {
+    const live = entryHostnames(org, entry)[0];
+    if (live)
+        return live;
+    return entry.workspace !== undefined ? workspaceHost(org.slug, entry.key) : null;
+}
 /**
  * The one exact name a Worker app is served at (ADR 0002): `<host>.<domain>` or
  * the apex on the org's own domain, else `<slug>-<key>.oikos.host` (one label
@@ -24,8 +40,19 @@ export function entryHostnames(org, entry) {
  * `<slug>.oikos.host` for the main entry.
  */
 export function workerAppHostname(org, entry) {
+    const parent = workspaceWorkerParent(entry);
+    if (parent !== null)
+        return workspaceHost(org.slug, parent);
     return workerAppHostnameOf({ slug: org.slug, domain: org.domain, usesDomain: org.hosting.usesDomain }, entry, entry.workerApp?.host ?? '@');
 }
+/** An entry's private workspace address: `work-<slug>-<key>.companyincluded.app`, one label deep so the free certificate covers it. */
+export function workspaceHost(slug, key) {
+    return `${WORKSPACE_HOST_PREFIX}${slug}-${key}.${APPS_DOMAIN}`;
+}
+/** The company's test inbox: the stage mail sink's web page, `inbox-<slug>.companyincluded.app`. */
+export function workspaceInboxHost(slug) {
+    return `${INBOX_HOST_PREFIX}${slug}.${APPS_DOMAIN}`;
+}
 /**
  * The wildcard name (`*.<domain>`) when an entry declares `'*'`, else `null`.
  * Like `entryHostnames`, it is read only while hosting is on, `usesDomain` is

package/dist/plan/index.d.ts

@@ -1,3 +1,4 @@
+export type { KeysRegistrarPort } from './keys-registrar.js';
 export type { LiveResource, ZitadelReader, CoolifyReader, CloudflareReader, FilesReader, AiReader, CmsReader, LiveReaders, PlatformCloudflareReader, PlatformCoolifyReader, PlatformLiveReaders, } from './live.js';
 export { readLiveResources, readLivePlatformResources } from './live.js';
 export type { StepAction, PlannedStep, PlanDetail, OrgPostgresPlan } from './diff.js';
@@ -57,6 +58,11 @@ export type { BrokerPort } from './broker-entries.js';
 export { PlatformBrokerPort } from './broker-entries.js';
 export type { LoginHostBinding, LoginHostBindingsPort, LoginHostDiscoveryPort, } from './login-host.js';
 export { loginHostnameFor } from './login-host.js';
+export { workspaceHost, workspaceInboxHost } from './hostnames.js';
+export { companyPeople, workspaceGateKey, workspacePeople } from './workspace.js';
+export { privatePageGateKey } from './private-pages.js';
+export { entryMachinePaths } from './machine-paths.js';
+export type { PrivatePageScope } from './private-pages.js';
 export { NO_DOMAIN_ZONE, ownHostnames } from './own-hostnames.js';
 export type { OwnHostnames } from './own-hostnames.js';
 export type { MailIdentityApp, MailIdentityAudienceCheck } from './mail-identity.js';
@@ -76,6 +82,8 @@ export type { AccessAppSummary, AccessDecision, AccessPolicyRule, AccessPort, Ed
 export { createEdgeWorkers } from './edge-workers.js';
 export type { EdgePlatformWorkers, EdgeWorkersOptions, PlatformWorkersPort, } from './edge-workers.js';
 export type { PlatformGithubReleaseHookDeps } from './github-release-hook.js';
+export { createGithubDeployKeys } from './github-deploy-keys.js';
+export type { DeployKeyTarget, GithubDeployKey, GithubDeployKeysPort, } from './github-deploy-keys.js';
 export type { PlatformUptimeAccessFactory, PlatformUptimeAccessPort, PlatformUptimeChatDeps, PlatformUptimeDeps, PlatformWorkersFactory, } from './uptime-worker.js';
 export { createEdgeRateLimits } from './edge-ratelimits.js';
 export type { EdgePlatformRateLimits, EdgeRateLimitsOptions, RateLimitPort, RateLimitRuleInput, } from './edge-ratelimits.js';
@@ -86,6 +94,7 @@ export type { EdgePlatformTunnels, TunnelIngress, TunnelPort, TunnelSummary, } f
 export type { ZitadelListAppsRawApp } from './executor.js';
 export { adaptZitadelListApps } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';
+export { httpKeysRegistrar, keysRegistrarFromConfig, KEYS_PLATFORM_TOKEN_ENV, KEYS_SERVICE_URL_ENV, } from './keys-registrar-http.js';
 export type { OrgAppVersionRef, OrgAppVersionStatus, WtfalchPackageDrift, PlatformVersionStatus, ReadPlatformVersionStatusOptions, StatusCoolifyPort, StatusGithubPort, GhExec as StatusGhExec, } from './version-status.js';
 export { readPlatformVersionStatus, wtfalchVersionsFromPnpmLockfile, providersStatusCoolifyPort, ghCliStatusGithubPort, } from './version-status.js';
 export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './destinations.js';

package/dist/plan/index.js

@@ -34,6 +34,10 @@ export { MAIL_COPY_COMPLETED_SCOPE_KEY, MAIL_COPY_DONE_SCOPE_KEY, MissingMailCop
 export { ProvidersAiReader, ProvidersCloudflareReader, ProvidersCmsReader, ProvidersCoolifyReader, ProvidersZitadelReader, storeLoginHostResolver, storeScopeResolver, storeRecordedIds, } from './providers-readers.js';
 export { PlatformBrokerPort } from './broker-entries.js';
 export { loginHostnameFor } from './login-host.js';
+export { workspaceHost, workspaceInboxHost } from './hostnames.js';
+export { companyPeople, workspaceGateKey, workspacePeople } from './workspace.js';
+export { privatePageGateKey } from './private-pages.js';
+export { entryMachinePaths } from './machine-paths.js';
 export { NO_DOMAIN_ZONE, ownHostnames } from './own-hostnames.js';
 export { checkMailIdentityAudience } from './mail-identity.js';
 export { checkMailAppsAllowlist } from './mail-identity-allowlist.js';
@@ -43,10 +47,12 @@ export { healthTargets, platformHealthTargets } from './health-targets.js';
 export { createEdgeDns, edgeDnsRecordOwners, EDGE_DNS_WRITE_CONCURRENCY } from './edge-dns.js';
 export { createEdgeAccess } from './edge-access.js';
 export { createEdgeWorkers } from './edge-workers.js';
+export { createGithubDeployKeys } from './github-deploy-keys.js';
 export { createEdgeRateLimits } from './edge-ratelimits.js';
 export { createEdgeZones } from './edge-zones.js';
 export { createEdgeTunnels } from './edge-tunnels.js';
 export { adaptZitadelListApps } from './executor.js';
 export { HttpJobsSchedulerClient } from './jobs-scheduler-http.js';
+export { httpKeysRegistrar, keysRegistrarFromConfig, KEYS_PLATFORM_TOKEN_ENV, KEYS_SERVICE_URL_ENV, } from './keys-registrar-http.js';
 export { readPlatformVersionStatus, wtfalchVersionsFromPnpmLockfile, providersStatusCoolifyPort, ghCliStatusGithubPort, } from './version-status.js';
 export { COMPANY_DESTINATION_NAME_PREFIX, COMPANY_NETWORKS, DEFAULT_MAX_DESTINATIONS, DestinationCapacityError, PLATFORM_NETWORK, companyNetworkName, ensureDestination, findDestination, placed, placedOnPlatform, validateNetworkName, } from './destinations.js';

package/dist/plan/jobs-scheduler-http.js

@@ -1,3 +1,5 @@
+/** How long the scheduler may take to answer an admin call. */
+const ADMIN_CALL_TIMEOUT_MS = 30_000;
 /**
  * #173: the real {@link JobsSchedulerPort}, a thin client over the jobs
  * scheduler's admin HTTP API (https://github.com/wtfalch/jobs README, "The
@@ -28,6 +30,7 @@ export class HttpJobsSchedulerClient {
                 'content-type': 'application/json',
             },
             body: JSON.stringify(input),
+            signal: AbortSignal.timeout(ADMIN_CALL_TIMEOUT_MS),
         });
         const body = await response.json().catch(() => undefined);
         const fields = typeof body === 'object' && body !== null ? body : {};

package/dist/plan/keys-registrar-http.d.ts

@@ -0,0 +1,32 @@
+import type { KeysRegistrarPort } from './keys-registrar.js';
+/** The name of the host config that holds the keys service's platform bearer token. */
+export declare const KEYS_PLATFORM_TOKEN_ENV = "KEYS_PLATFORM_TOKEN";
+/** The name of the host config that holds the keys service's public address. */
+export declare const KEYS_SERVICE_URL_ENV = "KEYS_SERVICE_URL";
+/**
+ * F7: the real {@link KeysRegistrarPort}, over the keys service's platform route
+ * (`@wtfalch/keys` `platformRegistrarEndpoint`):
+ *
+ * - `POST <url>/v1/keys/platform/registrars` with `{ organisationId, name, expiresDays }`, 200 `{ id, secret }`.
+ * - `DELETE <url>/v1/keys/platform/registrars/<organisationId>/<id>`, any 200 is success (`revoked: false` is a key already gone).
+ * - `DELETE <url>/v1/keys/platform/registrars/<organisationId>`, 200 `{ revoked: number }`: every registrar key of the company.
+ *
+ * Both carry `Authorization: Bearer <platform token>`. An error carries the service's own plain `message` and
+ * the status, never the token, the secret or a response body that is not that message.
+ */
+export declare function httpKeysRegistrar(options: {
+    url: string;
+    token: string;
+    fetch?: typeof fetch;
+}): KeysRegistrarPort;
+/**
+ * Builds the port from host config (`KEYS_SERVICE_URL`, `KEYS_PLATFORM_TOKEN`). When either is missing there is
+ * no port and `reason` names which, so the host can log why the plan reports Boule's registrar key blocked.
+ */
+export declare function keysRegistrarFromConfig(config: Readonly<Record<string, string | undefined>>, fetchImpl?: typeof fetch): {
+    port: KeysRegistrarPort;
+    reason?: undefined;
+} | {
+    port?: undefined;
+    reason: string;
+};

package/dist/plan/keys-registrar-http.js

@@ -0,0 +1,105 @@
+/** The name of the host config that holds the keys service's platform bearer token. */
+export const KEYS_PLATFORM_TOKEN_ENV = 'KEYS_PLATFORM_TOKEN';
+/** The name of the host config that holds the keys service's public address. */
+export const KEYS_SERVICE_URL_ENV = 'KEYS_SERVICE_URL';
+/** The keys route accepts `[A-Za-z0-9_-]{1,128}` for the company id, the key name and the key id. */
+const ID_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+const CALL_TIMEOUT_MS = 30_000;
+/**
+ * F7: the real {@link KeysRegistrarPort}, over the keys service's platform route
+ * (`@wtfalch/keys` `platformRegistrarEndpoint`):
+ *
+ * - `POST <url>/v1/keys/platform/registrars` with `{ organisationId, name, expiresDays }`, 200 `{ id, secret }`.
+ * - `DELETE <url>/v1/keys/platform/registrars/<organisationId>/<id>`, any 200 is success (`revoked: false` is a key already gone).
+ * - `DELETE <url>/v1/keys/platform/registrars/<organisationId>`, 200 `{ revoked: number }`: every registrar key of the company.
+ *
+ * Both carry `Authorization: Bearer <platform token>`. An error carries the service's own plain `message` and
+ * the status, never the token, the secret or a response body that is not that message.
+ */
+export function httpKeysRegistrar(options) {
+    const url = options.url.replace(/\/+$/, '');
+    const fetchImpl = options.fetch ?? fetch;
+    const headers = { authorization: `Bearer ${options.token}` };
+    const refuse = async (what, response) => {
+        const body = await response.json().catch(() => undefined);
+        const message = typeof body === 'object' &&
+            body !== null &&
+            typeof body.message === 'string'
+            ? body.message
+            : 'the service gave no reason';
+        throw new Error(`the keys service refused to ${what} (status ${response.status}): ${message}`);
+    };
+    const call = async (what, path, init) => {
+        try {
+            return await fetchImpl(`${url}${path}`, {
+                ...init,
+                redirect: 'error',
+                signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+            });
+        }
+        catch {
+            throw new Error(`the keys service did not answer when asked to ${what}; check that it is running and try again`);
+        }
+    };
+    return {
+        url,
+        async mintCompanyKey({ organisationId, name, expiresDays }) {
+            if (!ID_PATTERN.test(organisationId)) {
+                throw new Error(`the registrar key was not requested: the company id "${organisationId}" must be 1 to 128 letters, digits, dashes or underscores`);
+            }
+            if (!ID_PATTERN.test(name)) {
+                throw new Error(`the registrar key was not requested: the key name "${name}" must be 1 to 128 letters, digits, dashes or underscores`);
+            }
+            const response = await call('mint the registrar key', '/v1/keys/platform/registrars', {
+                method: 'POST',
+                headers: { ...headers, 'content-type': 'application/json' },
+                body: JSON.stringify({ organisationId, name, expiresDays }),
+            });
+            if (response.status !== 200)
+                return refuse('mint the registrar key', response);
+            const body = await response.json().catch(() => undefined);
+            const fields = typeof body === 'object' && body !== null ? body : {};
+            if (typeof fields.id !== 'string' ||
+                fields.id.length === 0 ||
+                typeof fields.secret !== 'string' ||
+                fields.secret.length === 0) {
+                throw new Error('the keys service answered 200 to the registrar key request but sent no key id and secret');
+            }
+            return { id: fields.id, secret: fields.secret };
+        },
+        async revokeCompanyKey(organisationId, id) {
+            const response = await call('revoke the registrar key', `/v1/keys/platform/registrars/${encodeURIComponent(organisationId)}/${encodeURIComponent(id)}`, { method: 'DELETE', headers });
+            if (response.status !== 200)
+                await refuse('revoke the registrar key', response);
+        },
+        async revokeAllCompanyKeys(organisationId) {
+            if (!ID_PATTERN.test(organisationId)) {
+                throw new Error(`the registrar keys were not revoked: the company id "${organisationId}" must be 1 to 128 letters, digits, dashes or underscores`);
+            }
+            const response = await call('revoke the registrar keys', `/v1/keys/platform/registrars/${encodeURIComponent(organisationId)}`, { method: 'DELETE', headers });
+            if (response.status !== 200)
+                return refuse('revoke the registrar keys', response);
+            const body = await response.json().catch(() => undefined);
+            const revoked = typeof body === 'object' && body !== null
+                ? body.revoked
+                : undefined;
+            if (typeof revoked !== 'number' || !Number.isInteger(revoked) || revoked < 0) {
+                throw new Error('the keys service answered 200 to the revoke-all request but did not say how many keys it revoked');
+            }
+            return revoked;
+        },
+    };
+}
+/**
+ * Builds the port from host config (`KEYS_SERVICE_URL`, `KEYS_PLATFORM_TOKEN`). When either is missing there is
+ * no port and `reason` names which, so the host can log why the plan reports Boule's registrar key blocked.
+ */
+export function keysRegistrarFromConfig(config, fetchImpl) {
+    const url = config[KEYS_SERVICE_URL_ENV];
+    const token = config[KEYS_PLATFORM_TOKEN_ENV];
+    if (!url)
+        return { reason: `no keys registrar port: ${KEYS_SERVICE_URL_ENV} is not set` };
+    if (!token)
+        return { reason: `no keys registrar port: ${KEYS_PLATFORM_TOKEN_ENV} is not set` };
+    return { port: httpKeysRegistrar({ url, token, ...(fetchImpl ? { fetch: fetchImpl } : {}) }) };
+}

package/dist/plan/keys-registrar.d.ts

@@ -0,0 +1,67 @@
+import { type DeclaredOrg } from '../org.js';
+import type { DraftStep } from './diff.js';
+/**
+ * F7 (#928): a company whose Boule runs apps (`org.boule.apps`) gets one registrar key at the signed-records
+ * (keys) service. Boule calls the service directly with it: `PUT` or `DELETE
+ * <KEYS_REGISTRAR_URL>/v1/keys/registrar/apps/<appName>` with `Authorization: Bearer <KEYS_REGISTRAR_KEY>`
+ * (`@wtfalch/keys/host` `registrarEndpoint`). The key is an ordinary credential of the keys issuer carrying the
+ * host's registrar grant; every app credential registered through it is its child, so it reaches only its own
+ * company's apps.
+ *
+ * Same shape as Boule's edge key (F3): one `coolify:keys-registrar` step mints the key through
+ * {@link KeysRegistrarPort}, records its id as undelivered and persists before anything is written, writes
+ * `KEYS_REGISTRAR_URL` and `KEYS_REGISTRAR_KEY` to Boule's env and restarts it. The key is held nowhere but
+ * Boule's env. A failed delivery is repaired by the next apply, which revokes the undelivered key and mints
+ * one. Mints once and never renews (the key lives {@link KEYS_REGISTRAR_KEY_DAYS} days; a row warns 30 days
+ * before). Turning the switch off revokes the key and takes both env rows away.
+ */
+export declare const KEYS_REGISTRAR_URL_ENV = "KEYS_REGISTRAR_URL";
+export declare const KEYS_REGISTRAR_KEY_ENV = "KEYS_REGISTRAR_KEY";
+export declare const KEYS_REGISTRAR_KEY_DAYS = 365;
+export declare const KEYS_REGISTRAR_WARN_DAYS = 30;
+export declare const KEYS_REGISTRAR_DELIVERY_ATTEMPTS = 3;
+/** The id of the live key (never the key). */
+export declare const KEYS_REGISTRAR_SCOPE_KEY = "keys_registrar_id";
+/** The id of a key minted and not yet delivered. */
+export declare const KEYS_REGISTRAR_UNDELIVERED_SCOPE_KEY = "keys_registrar_undelivered";
+/** ISO time of the mint, the only trace of the key's age. */
+/**
+ * Set (and persisted) just before the mint call and cleared once the new key's id is recorded. Found set on a
+ * later run it means a mint whose answer was lost: the key may exist with no id on record, so every registrar
+ * key of the company is revoked before minting again.
+ */
+export declare const KEYS_REGISTRAR_MINT_STARTED_SCOPE_KEY = "keys_registrar_mint_started";
+export declare const KEYS_REGISTRAR_MINTED_AT_SCOPE_KEY = "keys_registrar_minted_at";
+/** The service address last written to Boule. */
+export declare const KEYS_REGISTRAR_URL_APPLIED_SCOPE_KEY = "keys_registrar_url_applied";
+/** The keys service's per-company registrar, as the host wires it. */
+export interface KeysRegistrarPort {
+    /** The public address of the service that serves the registrar route, delivered as `KEYS_REGISTRAR_URL`. */
+    readonly url: string;
+    /** Mints the company's registrar credential. The secret is shown once. */
+    mintCompanyKey(input: {
+        organisationId: string;
+        name: string;
+        expiresDays: number;
+    }): Promise<{
+        id: string;
+        secret: string;
+    }>;
+    /** Revokes it (and, by lineage, every app credential it registered). A key already gone is not an error. */
+    revokeCompanyKey(organisationId: string, id: string): Promise<void>;
+    /**
+     * Revokes every registrar key the company has, however many, and returns how many were revoked. For a key
+     * whose id was never recorded (a mint whose answer was lost), and for org destroy.
+     */
+    revokeAllCompanyKeys(organisationId: string): Promise<number>;
+}
+export declare const keysRegistrarName: (org: Pick<DeclaredOrg, "slug">) => string;
+export declare function planKeysRegistrar(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, plannedSteps: readonly DraftStep[], host: {
+    url?: string;
+}, now?: number): {
+    steps: DraftStep[];
+    blocked: Array<{
+        description: string;
+        key: string;
+    }>;
+};

package/dist/plan/keys-registrar.js

@@ -0,0 +1,103 @@
+import { appsOn } from '../org.js';
+/**
+ * F7 (#928): a company whose Boule runs apps (`org.boule.apps`) gets one registrar key at the signed-records
+ * (keys) service. Boule calls the service directly with it: `PUT` or `DELETE
+ * <KEYS_REGISTRAR_URL>/v1/keys/registrar/apps/<appName>` with `Authorization: Bearer <KEYS_REGISTRAR_KEY>`
+ * (`@wtfalch/keys/host` `registrarEndpoint`). The key is an ordinary credential of the keys issuer carrying the
+ * host's registrar grant; every app credential registered through it is its child, so it reaches only its own
+ * company's apps.
+ *
+ * Same shape as Boule's edge key (F3): one `coolify:keys-registrar` step mints the key through
+ * {@link KeysRegistrarPort}, records its id as undelivered and persists before anything is written, writes
+ * `KEYS_REGISTRAR_URL` and `KEYS_REGISTRAR_KEY` to Boule's env and restarts it. The key is held nowhere but
+ * Boule's env. A failed delivery is repaired by the next apply, which revokes the undelivered key and mints
+ * one. Mints once and never renews (the key lives {@link KEYS_REGISTRAR_KEY_DAYS} days; a row warns 30 days
+ * before). Turning the switch off revokes the key and takes both env rows away.
+ */
+export const KEYS_REGISTRAR_URL_ENV = 'KEYS_REGISTRAR_URL';
+export const KEYS_REGISTRAR_KEY_ENV = 'KEYS_REGISTRAR_KEY';
+export const KEYS_REGISTRAR_KEY_DAYS = 365;
+export const KEYS_REGISTRAR_WARN_DAYS = 30;
+export const KEYS_REGISTRAR_DELIVERY_ATTEMPTS = 3;
+/** The id of the live key (never the key). */
+export const KEYS_REGISTRAR_SCOPE_KEY = 'keys_registrar_id';
+/** The id of a key minted and not yet delivered. */
+export const KEYS_REGISTRAR_UNDELIVERED_SCOPE_KEY = 'keys_registrar_undelivered';
+/** ISO time of the mint, the only trace of the key's age. */
+/**
+ * Set (and persisted) just before the mint call and cleared once the new key's id is recorded. Found set on a
+ * later run it means a mint whose answer was lost: the key may exist with no id on record, so every registrar
+ * key of the company is revoked before minting again.
+ */
+export const KEYS_REGISTRAR_MINT_STARTED_SCOPE_KEY = 'keys_registrar_mint_started';
+export const KEYS_REGISTRAR_MINTED_AT_SCOPE_KEY = 'keys_registrar_minted_at';
+/** The service address last written to Boule. */
+export const KEYS_REGISTRAR_URL_APPLIED_SCOPE_KEY = 'keys_registrar_url_applied';
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const keysRegistrarName = (org) => `${org.slug}-registrar`;
+export function planKeysRegistrar(org, recordedIds, plannedSteps, host, now = Date.now()) {
+    const at = `${org.slug}'s signed-records registrar key`;
+    const key = `coolify:keys-registrar:${org.id}`;
+    const blocked = [];
+    const draft = (desired, description) => ({
+        action: { system: 'coolify', kind: 'keys-registrar', key: org.id, desired },
+        step: { description, destroys: desired.mode === 'retire', migrates: false },
+    });
+    const liveId = recordedIds[KEYS_REGISTRAR_SCOPE_KEY];
+    const leftover = recordedIds[KEYS_REGISTRAR_UNDELIVERED_SCOPE_KEY];
+    if (!appsOn(org)) {
+        if (!liveId && !leftover)
+            return { steps: [], blocked };
+        if (!host.url) {
+            blocked.push({
+                description: `${at} is not revoked, not planned: the host supplies no keys registrar port`,
+                key,
+            });
+            return { steps: [], blocked };
+        }
+        return {
+            steps: [
+                draft({ mode: 'retire' }, `revoke ${org.slug}'s signed-records registrar key and take it out of Boule's env (the company's Boule runs no apps)`),
+            ],
+            blocked,
+        };
+    }
+    if (!host.url) {
+        blocked.push({
+            description: `${at} is blocked, not planned: the host supplies no keys registrar port`,
+            key,
+        });
+        return { steps: [], blocked };
+    }
+    if (liveId) {
+        const mintedAt = Date.parse(recordedIds[KEYS_REGISTRAR_MINTED_AT_SCOPE_KEY] ?? '');
+        if (!Number.isNaN(mintedAt)) {
+            const left = Math.floor((mintedAt + KEYS_REGISTRAR_KEY_DAYS * DAY_MS - now) / DAY_MS);
+            if (left < KEYS_REGISTRAR_WARN_DAYS) {
+                blocked.push({
+                    description: `warning: ${at} ${left < 0 ? 'has expired' : `expires in ${left} days`} and is never renewed: turn apps off and on again to make a new one`,
+                    key,
+                });
+            }
+        }
+        if (recordedIds[KEYS_REGISTRAR_URL_APPLIED_SCOPE_KEY] !== host.url) {
+            return {
+                steps: [
+                    draft({ mode: 'url', keysUrl: host.url }, `write ${org.slug}'s signed-records service address to Boule's env`),
+                ],
+                blocked,
+            };
+        }
+        return { steps: [], blocked };
+    }
+    const bouleRecorded = Boolean(recordedIds[`coolify:boule:${org.id}`]);
+    const boulePlanned = plannedSteps.some((p) => p.action.system === 'coolify' && p.action.kind === 'boule' && p.action.key === org.id);
+    if (!bouleRecorded && !boulePlanned)
+        return { steps: [], blocked };
+    return {
+        steps: [
+            draft({ mode: 'mint', name: keysRegistrarName(org), keysUrl: host.url }, `mint ${org.slug}'s signed-records registrar key, write KEYS_REGISTRAR_* to Boule's env, restart Boule`),
+        ],
+        blocked,
+    };
+}

package/dist/plan/live.d.ts

@@ -42,7 +42,7 @@ export interface LiveResource {
      * see that function's own doc comment for why "always planned" broke
      * `bootstrapPlatform`.
      */
-    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats' | 'github';
+    system: 'zitadel' | 'coolify' | 'cloudflare' | 'files' | 'ai' | 'cms' | 'jobs' | 'sfu' | 'edge' | 'heartbeats' | 'github' | 'audit';
     kind: string;
     key: string;
     config: Record<string, unknown>;