@wtfalch/foundry 0.8.0 → 0.9.0

package/dist/plan/index.d.ts

@@ -13,7 +13,7 @@ export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, Confirmatio
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
 export type { PlatformAuthDeps, PlatformAuthRuntime, PlatformFilesDeps, PlatformFilesRuntime, } from './platform-providers.js';
 export type { PlatformMailDeps, PlatformMailAdminPort, PlatformMailRuntime, } from './platform-providers.js';
-export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
 export type { AiManagementKeyMinter, PlatformAiDeps, PlatformAiRuntime, } from './platform-providers.js';
 export { createZitadelAdminMinter } from './zitadel-machine-user.js';

package/dist/plan/index.js

@@ -6,7 +6,7 @@ export { PlatformOrgBlockedError, PlatformOrgPorts } from './platform-org-ports.
 export { FoundryPlanApply, DeclaredOrgNotFoundError, StalePlanError, ConfirmationRequiredError, NotAuthorizedError, NotATestOrgError, DeclaredPlatformNotFoundError, PlatformStalePlanError, PlatformConfirmationRequiredError, planNeedsConfirmation, } from './plan-apply.js';
 export { FoundryPlatformStepExecutor, ProvidersPlatformCloudflareReader, ProvidersPlatformCoolifyReader, PLATFORM_MAIL_ADMIN_KEY_DESCRIPTION, } from './platform-providers.js';
 // #171: how a host signs files management requests with the delivered key.
-export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, } from './platform-providers.js';
+export { FILES_INTROSPECTION_SECRET_REF, FILES_MANAGEMENT_ISSUER, FILES_MANAGEMENT_KEY_ID, FILES_MANAGEMENT_KEY_REF, PLATFORM_AUTH_INSTANCE_BEARER_REF, } from './platform-providers.js';
 export { AI_MANAGEMENT_ISSUER, AI_MANAGEMENT_KEY_ID, AI_SIGNING_KEY_REF, AiManagementKeyExistsError, createAiManagementKeyMinter, PLATFORM_AI_MANAGEMENT_KEY_REF, PLATFORM_AI_MANAGEMENT_PERMISSIONS, } from './platform-providers.js';
 export { createZitadelAdminMinter } from './zitadel-machine-user.js';
 export { MissingCallsSfuConnectionError, applyCallsSfuPlatformStep } from './platform-sfu.js';

package/dist/plan/plan-apply.js

@@ -633,13 +633,12 @@ function stepField(action) {
  *
  * Three sources, in this order:
  * - fields no planner step exists for yet, so no apply can make them true:
- *   SSO, guests and solo when turned on, an adopted app in the `repo` form
- *   (#7's `#15` comment: "declared but refused by `apply`"), and calls or
- *   hosting on a domain the org has not recorded (#145: calls on the org's
- *   own domain now has a planner step, the same way hosting's own domain
- *   does, so it only fails for that one missing-domain reason, not
- *   unconditionally). `bespokeAppRepo` is not one of these: `coolify:app`
- *   reads it (#240), so it converges with that step like any other field;
+ *   SSO, guests and solo when turned on, and calls or hosting on a domain
+ *   the org has not recorded (#145: calls on the org's own domain now has a
+ *   planner step, the same way hosting's own domain does, so it only fails
+ *   for that one missing-domain reason, not unconditionally). An app repo is
+ *   not one of these: `coolify:app` reads the `app` entry's `repo`, so it
+ *   converges with that step like any other field;
  * - chat's reverse re-key, which the planner surfaces but which is not built
  *   (#7 amendment 3), so it counts as failed even when no step threw;
  * - on a failed apply, the field of every planned step from the one that
@@ -663,8 +662,6 @@ function failedFields(org, detail, completed, serviceIds) {
         failed.add('guests.enabled');
     if (org.solo.enabled)
         failed.add('solo.enabled');
-    if (org.adoptedApp?.form === 'repo')
-        failed.add('adoptedApp');
     // `planCallsService`/`planTunnel`/`planZone` all share this same domain
     // requirement (#145): a declared `usesDomain: true` with no recorded
     // domain plans no step for any of them either.

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

@@ -1,4 +1,4 @@
-import type { DeclaredOrg, OrgId } from '../org.js';
+import type { DeclaredOrg, HostingEntry, OrgId } from '../org.js';
 import { type Plan, type UnmanagedItem, type VersionChangeItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
@@ -118,6 +118,10 @@ export declare const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = "archon_applied_
 export declare const PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY = "archon_gate_closed";
 export declare const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = "zitadel_platform_admin_user_id";
 export declare const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = "zitadel_platform_admin_user_undelivered";
+/** #283: the created instance's id, recorded once its owner token is delivered. */
+export declare const PLATFORM_AUTH_INSTANCE_SCOPE_KEY = "zitadel_platform_instance_id";
+/** #283: an instance that may exist without a delivered owner token; blocks creating another. */
+export declare const PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY = "zitadel_platform_instance_undelivered";
 /**
  * #216 (building on #209/#215): the `IAM_LOGIN_CLIENT` machine user minted
  * for the login app and the broker, mirroring
@@ -312,24 +316,32 @@ export declare function platformMailMxHost(apex: string): string;
 export declare const ORG_MAIL_APPLIED_APEX_SCOPE_KEY = "mail_applied_apex";
 export declare const ORG_MAIL_APPLIED_HOST_SCOPE_KEY = "mail_applied_host";
 /**
- * #243: the org's `hosting.appEnv` values the last `coolify:app` apply pushed,
- * recorded as one JSON object (env name to value; ids and a domain, never a
- * secret). `planApp` plans the step again when {@link resolveAppEnv} differs
- * from it, so a changed map reaches an app that is already live.
+ * The key of an org's `app` hosting entry in a `coolify:app` or
+ * `cloudflare:access` step and in the ids recorded for it:
+ * `<orgId>:<entry key>`, so a second entry cannot collide with the first.
  */
-export declare const APP_ENV_APPLIED_SCOPE_KEY = "app_env_applied";
+export declare function appStepKey(org: DeclaredOrg): string;
+/**
+ * #243: the org's `app` entry's `env` values the last `coolify:app` apply
+ * pushed, recorded as one JSON object (env name to value; ids and a domain,
+ * never a secret). `planApp` plans the step again when {@link resolveAppEnv}
+ * differs from it, so a changed map reaches an app that is already live. The
+ * `.app` suffix is the entry key; a scope key holds no `:`, so
+ * `storeRecordedIds` still filters it out.
+ */
+export declare const APP_ENV_APPLIED_SCOPE_KEY = "app_env_applied.app";
 /**
  * #239: set to '1' once an app has been restarted after its database URLs
  * were pushed. Not a URL. Without it a crash between the push and the restart
  * would leave a stale container that no plan notices.
  */
-export declare const DB_ENV_APPLIED_SCOPE_KEY = "db_env_applied";
+export declare const DB_ENV_APPLIED_SCOPE_KEY = "db_env_applied.app";
 /**
- * The `hosting.appEnv` entries whose source has a recorded value, in env-name
- * order, and the env names whose source has none yet. Shared by `planApp` and
- * the executor's `pushAppEnv` so both read the same recorded ids.
+ * The entry's `env` values that have a value, in env-name order, and the env
+ * names whose source has none yet. Shared by `planApp` and the executor's
+ * `pushAppEnv` so both read the same recorded ids.
  */
-export declare function resolveAppEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): {
+export declare function resolveAppEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
     values: Record<string, string>;
     unresolved: Array<[string, string]>;
 };

package/dist/plan/platform-diff.js

@@ -1,4 +1,5 @@
 import { VERSIONS } from '../bootstrap/versions.js';
+import { APP_ENTRY_KEY } from '../org.js';
 import { VERSION_CHANGE_KIND, } from '../plan.js';
 /**
  * The `Plan` (#19's public contract) a {@link PlatformPlanDetail} carries,
@@ -136,6 +137,10 @@ export const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = 'archon_applied_broker_a
 export const PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY = 'archon_gate_closed';
 export const PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY = 'zitadel_platform_admin_user_id';
 export const PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_admin_user_undelivered';
+/** #283: the created instance's id, recorded once its owner token is delivered. */
+export const PLATFORM_AUTH_INSTANCE_SCOPE_KEY = 'zitadel_platform_instance_id';
+/** #283: an instance that may exist without a delivered owner token; blocks creating another. */
+export const PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY = 'zitadel_platform_instance_undelivered';
 /**
  * #216 (building on #209/#215): the `IAM_LOGIN_CLIENT` machine user minted
  * for the login app and the broker, mirroring
@@ -343,24 +348,34 @@ export function platformMailMxHost(apex) {
 export const ORG_MAIL_APPLIED_APEX_SCOPE_KEY = 'mail_applied_apex';
 export const ORG_MAIL_APPLIED_HOST_SCOPE_KEY = 'mail_applied_host';
 /**
- * #243: the org's `hosting.appEnv` values the last `coolify:app` apply pushed,
- * recorded as one JSON object (env name to value; ids and a domain, never a
- * secret). `planApp` plans the step again when {@link resolveAppEnv} differs
- * from it, so a changed map reaches an app that is already live.
+ * The key of an org's `app` hosting entry in a `coolify:app` or
+ * `cloudflare:access` step and in the ids recorded for it:
+ * `<orgId>:<entry key>`, so a second entry cannot collide with the first.
  */
-export const APP_ENV_APPLIED_SCOPE_KEY = 'app_env_applied';
+export function appStepKey(org) {
+    return `${org.id}:${APP_ENTRY_KEY}`;
+}
+/**
+ * #243: the org's `app` entry's `env` values the last `coolify:app` apply
+ * pushed, recorded as one JSON object (env name to value; ids and a domain,
+ * never a secret). `planApp` plans the step again when {@link resolveAppEnv}
+ * differs from it, so a changed map reaches an app that is already live. The
+ * `.app` suffix is the entry key; a scope key holds no `:`, so
+ * `storeRecordedIds` still filters it out.
+ */
+export const APP_ENV_APPLIED_SCOPE_KEY = `app_env_applied.${APP_ENTRY_KEY}`;
 /**
  * #239: set to '1' once an app has been restarted after its database URLs
  * were pushed. Not a URL. Without it a crash between the push and the restart
  * would leave a stale container that no plan notices.
  */
-export const DB_ENV_APPLIED_SCOPE_KEY = 'db_env_applied';
+export const DB_ENV_APPLIED_SCOPE_KEY = `db_env_applied.${APP_ENTRY_KEY}`;
 /**
- * The `hosting.appEnv` entries whose source has a recorded value, in env-name
- * order, and the env names whose source has none yet. Shared by `planApp` and
- * the executor's `pushAppEnv` so both read the same recorded ids.
+ * The entry's `env` values that have a value, in env-name order, and the env
+ * names whose source has none yet. Shared by `planApp` and the executor's
+ * `pushAppEnv` so both read the same recorded ids.
  */
-export function resolveAppEnv(org, recorded) {
+export function resolveAppEnv(org, entry, recorded) {
     const sources = {
         filesOrganisationId: recorded[`files:organisation:${org.id}`],
         aiOrganisationId: recorded[`ai:organisation:${org.id}`],
@@ -368,12 +383,12 @@ export function resolveAppEnv(org, recorded) {
     };
     const values = {};
     const unresolved = [];
-    for (const [name, source] of Object.entries(org.hosting.appEnv).sort(([a], [b]) => a < b ? -1 : 1)) {
-        const value = sources[source];
+    for (const [name, declared] of Object.entries(entry.env).sort(([a], [b]) => (a < b ? -1 : 1))) {
+        const value = typeof declared === 'string' ? declared : sources[declared.from];
         if (value)
             values[name] = value;
-        else
-            unresolved.push([name, source]);
+        else if (typeof declared !== 'string')
+            unresolved.push([name, declared.from]);
     }
     return { values, unresolved };
 }
@@ -999,6 +1014,16 @@ function planAuth(platform, recordedIds, executorBlocked, executorMissing, authD
             blocked: `the platform's sign-in is blocked, not planned: the admin key of ZITADEL machine user ${undelivered} was minted but never delivered and cannot be shown again; delete that user in ZITADEL and remove the recorded key ${PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`,
         };
     }
+    // #283: an instance may exist whose owner token never reached the host.
+    const instanceLost = recordedIds[PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY];
+    if (instanceLost &&
+        !recordedIds[PLATFORM_AUTH_INSTANCE_SCOPE_KEY] &&
+        !recordedIds[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) {
+        return {
+            step: null,
+            blocked: `the platform's sign-in is blocked, not planned: a ZITADEL instance (${instanceLost}) may exist without a delivered owner token; delete it with the system API (DELETE /system/v1/instances/{id}) or redeploy the ZITADEL database, then remove the recorded key ${PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY}`,
+        };
+    }
     // #211 round 6: the executor itself is unusable on this host -- nothing to
     // plan, whatever the broker's recorded state says.
     if (executorMissing)

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

@@ -223,6 +223,13 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
     private executeSfu;
     private coolifyJobs;
 }
+/**
+ * #283: the ref the new instance's IAM_OWNER machine token (a PAT) is
+ * delivered under, once. A host reads it back to build `zitadelForInstance`
+ * (see {@link provisionPlatformAuth}'s doc comment). Distinct from the admin
+ * key delivered under `zitadel:platform:admin`.
+ */
+export declare const PLATFORM_AUTH_INSTANCE_BEARER_REF = "zitadel:platform:instanceBearer";
 /**
  * The fixed description Stalwart's admin API key is minted under
  * (`StalwartClient.createApiKey`'s own signature returns only the secret,

package/dist/plan/platform-providers.js

@@ -4,8 +4,9 @@ import { VERSIONS, floatingTagBlocked } from '../bootstrap/versions.js';
 import { redactSecrets } from '../calls-sfu-deploy-support.js';
 import { ensureCloudflaredConnector } from './cloudflared-connector.js';
 import { ACCESS_POLICY_NAME, isNotFoundError, isRunningOrStarting } from './executor.js';
-import { JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
+import { JOBS_SCHEDULER_KEY, PLATFORM_AI_APPLIED_GITREF_SCOPE_KEY, PLATFORM_AI_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY, PLATFORM_AI_INTERNAL_URL_SCOPE_KEY, PLATFORM_AI_KEY, PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY, PLATFORM_AI_ORGANISATION_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY, PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY, PLATFORM_ARCHON_GATE_CLOSED_SCOPE_KEY, PLATFORM_ARCHON_KEY, PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF, PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF, PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY, PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_SCOPE_KEY, PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_KEY, PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY, PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY, PLATFORM_AUTH_ZITADEL_APPLIED_IMAGE_TAG_SCOPE_KEY, PLATFORM_BACKUP_DATABASE_SCOPE_KEYS, PLATFORM_BACKUP_SERVICE_KEYS, PLATFORM_FILES_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_FILES_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_FILES_INTERNAL_URL_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_SCOPE_KEY, PLATFORM_FILES_INTROSPECTION_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_KEY, PLATFORM_FILES_MANAGEMENT_KEY_SCOPE_KEY, PLATFORM_FILES_MANAGEMENT_UNDELIVERED_SCOPE_KEY, PLATFORM_FILES_ZITADEL_PROJECT_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_GITREF_SCOPE_KEY, PLATFORM_INTEGRATIONS_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY, PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY, PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_ADMIN_KEY_SCOPE_KEY, PLATFORM_MAIL_ADMIN_UNDELIVERED_SCOPE_KEY, PLATFORM_MAIL_APPLIED_GIT_REF_SCOPE_KEY, PLATFORM_MAIL_APPLIED_HOSTNAME_SCOPE_KEY, PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY, PLATFORM_MAIL_INTERNAL_URL_SCOPE_KEY, PLATFORM_MAIL_KEY, parseBrokerDeployRecord, parseLoginClientRecord, platformMailMxHost, } from './platform-diff.js';
 import { applyCallsSfuPlatformStep } from './platform-sfu.js';
+import { CreateInstanceError, createZitadelInstance, generateSystemApiKeypair, instanceWithoutBearerMessage, systemApiUsersEnv, } from './zitadel-system-api.js';
 /** The key `runPlatformSteps` records the apex zone's id under (`system:kind:key`). */
 function apexZoneKey(apex) {
     return `cloudflare:zone:${apex}`;
@@ -495,7 +496,7 @@ const AUTH_BROKER_PORT = '3000';
  * falls through to the login app's own ingress rule below (login v2 answers
  * everything else, including the root).
  */
-const AUTH_ZITADEL_PATH_PATTERN = '^/(oidc|oauth|saml|management|admin|system|auth|assets|ui/console|\\.well-known)(/|$)';
+const AUTH_ZITADEL_PATH_PATTERN = '^/(oidc|oauth|saml|management|admin|system|auth|assets|debug/healthz|ui/console|\\.well-known)(/|$)';
 /**
  * `@wtfalch/auth`'s own `brokerUrl` default, `<issuer>/api`
  * (`packages/auth/src/config.ts`) -- `deploy/proxy/Caddyfile`'s own
@@ -515,6 +516,14 @@ const PLATFORM_AUTH_ADMIN_USER_NAME = 'foundry-admin';
 /** #216 (building on #209/#215): the narrower `IAM_LOGIN_CLIENT` machine user for the login app and the broker. */
 const PLATFORM_AUTH_LOGIN_CLIENT_USER_NAME = 'foundry-login-client';
 const PLATFORM_AUTH_ORG_NAME = 'foundry';
+/**
+ * #283: the ref the new instance's IAM_OWNER machine token (a PAT) is
+ * delivered under, once. A host reads it back to build `zitadelForInstance`
+ * (see {@link provisionPlatformAuth}'s doc comment). Distinct from the admin
+ * key delivered under `zitadel:platform:admin`.
+ */
+export const PLATFORM_AUTH_INSTANCE_BEARER_REF = 'zitadel:platform:instanceBearer';
+const PLATFORM_AUTH_BEARER_USER_NAME = 'foundry-instance-owner';
 /**
  * Retries `action` up to `attempts` times, sleeping increasingly between
  * tries -- the same shape the admin machine user's own delivery retry (just
@@ -758,8 +767,24 @@ async function liveLoginClientTokenHash(coolify, appId) {
  *   first), so it will not start (`parseApps` throws on an empty list) until
  *   then either. Safe to run again: the next apply that registers an app
  *   redeploys the broker with a non-empty list.
- * - Whoever supplies `deps.zitadel` (or `zitadelForInstance`) must hold a
- *   bearer token for the new instance, which foundry cannot read from it.
+ * - ~~Whoever supplies `deps.zitadel` (or `zitadelForInstance`) must hold a
+ *   bearer token for the new instance, which foundry cannot read from it.~~
+ *   Closed by #283: see "The instance bearer" below.
+ *
+ * The instance bearer (#283): the container creates no instance of its own
+ * (`ZITADEL_FIRSTINSTANCE_SKIP`). foundry generates an RSA keypair, puts the
+ * public half in `ZITADEL_SYSTEMAPIUSERS` (a system API user with
+ * SYSTEM_OWNER only), and once the container answers calls ZITADEL's system
+ * API `CreateInstance` with a machine owner (IAM_OWNER of the new instance)
+ * signed by the private half, which lives in memory for that run only. The
+ * owner's PAT comes back once and is handed to
+ * {@link PlatformAuthDeps.deliverSecret} under
+ * {@link PLATFORM_AUTH_INSTANCE_BEARER_REF}, before anything else uses it. A
+ * host builds `zitadelForInstance` as `(url) => createZitadelAdminMinter({
+ * url, token: <the secret delivered under that ref> })` plus its own org
+ * calls; `zitadelForInstance` is first called after the delivery. No human
+ * admin is created: a person who needs console access is added by the host
+ * through that bearer.
  *
  * #197: a `cloudflared` connector for this tunnel is run
  * ({@link ensureCloudflaredConnector}), so `hostname` answers.
@@ -899,7 +924,19 @@ async function provisionPlatformAuth(context, deps) {
     // same rule `executor.ts`'s `ensureAuthCookieSecret` follows for a value
     // this package mints itself rather than receiving from a provider.
     const masterkey = await ensureMasterkey(deps.coolify, zitadelAppId, databaseInUse);
-    const adminPassword = await ensureGeneratedEnv(deps.coolify, zitadelAppId, 'ZITADEL_ADMIN_PASSWORD', generateAdminPassword);
+    // #283: the instance is created once, with the system API, by a platform
+    // whose admin machine user is not recorded yet (one that already has it was
+    // built from a first instance and keeps it). The keypair is regenerated on
+    // any run that still has to create it, so the private half never needs to
+    // be held anywhere between runs.
+    const lostInstance = recorded[PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY];
+    if (lostInstance &&
+        !recorded[PLATFORM_AUTH_INSTANCE_SCOPE_KEY] &&
+        !recorded[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY]) {
+        throw new Error(instanceWithoutBearerMessage(hostname, `instance ${lostInstance}`));
+    }
+    const needsInstance = !recorded[PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY] && !recorded[PLATFORM_AUTH_INSTANCE_SCOPE_KEY];
+    const systemKeys = needsInstance ? generateSystemApiKeypair() : undefined;
     const zitadelEnvs = [
         { key: 'ZITADEL_PORT', value: AUTH_ZITADEL_PORT },
         { key: 'ZITADEL_EXTERNALDOMAIN', value: hostname },
@@ -907,8 +944,7 @@ async function provisionPlatformAuth(context, deps) {
         { key: 'ZITADEL_EXTERNALSECURE', value: 'true' },
         { key: 'ZITADEL_TLS_ENABLED', value: 'false' },
         { key: 'ZITADEL_DATABASE_POSTGRES_DSN', value: db.internal_db_url },
-        { key: 'ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME', value: 'zitadel-admin' },
-        { key: 'ZITADEL_FIRSTINSTANCE_ORG_HUMAN_PASSWORDCHANGEREQUIRED', value: 'false' },
+        { key: 'ZITADEL_FIRSTINSTANCE_SKIP', value: 'true' },
         { key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_REQUIRED', value: 'true' },
         { key: 'ZITADEL_DEFAULTINSTANCE_FEATURES_LOGINV2_BASEURI', value: `https://${hostname}/` },
         { key: 'ZITADEL_OIDC_DEFAULTLOGINURLV2', value: `https://${hostname}/login?authRequest=` },
@@ -921,8 +957,12 @@ async function provisionPlatformAuth(context, deps) {
     ];
     if (masterkey)
         zitadelEnvs.push({ key: 'ZITADEL_MASTERKEY', value: masterkey });
-    if (adminPassword)
-        zitadelEnvs.push({ key: 'ZITADEL_ADMIN_PASSWORD', value: adminPassword });
+    if (systemKeys) {
+        zitadelEnvs.push({
+            key: 'ZITADEL_SYSTEMAPIUSERS',
+            value: systemApiUsersEnv(systemKeys.publicKey),
+        });
+    }
     const loginEnvs = [
         {
             key: 'ZITADEL_API_URL',
@@ -1051,6 +1091,50 @@ async function provisionPlatformAuth(context, deps) {
             // a caller that reaches the step anyway.
             throw new Error(`platform:auth: the admin key of ZITADEL machine user ${lost} was minted but never delivered; delete that user and the recorded key ${PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} to mint a new one`);
         }
+        if (systemKeys) {
+            // ZITADEL answers /debug/healthz without an instance; the openid
+            // document below only exists once the instance does.
+            await waitForInstance(`https://${hostname}/debug/healthz`, runtime, sleep);
+            // Sent exactly once. Anything that may have reached ZITADEL leaves a
+            // marker first, so the next run refuses instead of creating again.
+            let created;
+            try {
+                created = await createZitadelInstance({
+                    customDomain: hostname,
+                    privateKey: systemKeys.privateKey,
+                    instanceName: PLATFORM_AUTH_ORG_NAME,
+                    firstOrgName: PLATFORM_AUTH_ORG_NAME,
+                    owner: { userName: PLATFORM_AUTH_BEARER_USER_NAME, name: 'Foundry (instance owner)' },
+                }, { fetch: runtime.fetch, now: runtime.now ?? Date.now });
+            }
+            catch (error) {
+                if (error instanceof CreateInstanceError && error.kind !== 'rejected') {
+                    await record(PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, 'unknown');
+                }
+                throw error;
+            }
+            const { instanceId, pat } = created;
+            // Recorded before the PAT leaves this function, like the admin key below.
+            await record(PLATFORM_AUTH_INSTANCE_UNDELIVERED_SCOPE_KEY, instanceId);
+            const attempts = runtime.deliverAttempts ?? 3;
+            for (let attempt = 1;; attempt += 1) {
+                try {
+                    await deps.deliverSecret(PLATFORM_AUTH_INSTANCE_BEARER_REF, pat);
+                    break;
+                }
+                catch (error) {
+                    if (attempt >= attempts) {
+                        const reason = redactSecrets(error instanceof Error ? error.message : String(error), [
+                            pat,
+                        ]);
+                        throw new Error(`platform:auth: the owner token of ZITADEL instance ${instanceId} was created but could not be delivered after ${attempts} tries (${reason}); ${instanceWithoutBearerMessage(hostname, `instance ${instanceId}`)}`);
+                    }
+                    await sleep(1000 * attempt);
+                }
+            }
+            // The marker stays recorded but is ignored once this is set.
+            await record(PLATFORM_AUTH_INSTANCE_SCOPE_KEY, instanceId);
+        }
         // Minting needs a running instance behind the tunnel: the first apply
         // gets here right after the deploy.
         await waitForInstance(`https://${hostname}/.well-known/openid-configuration`, runtime, sleep);
@@ -3642,10 +3726,6 @@ async function ensureMasterkey(coolify, appId, databaseInUse) {
     }
     return randomBytes(24).toString('base64');
 }
-/** `docs/deploy.md`: "ZITADEL_ADMIN_PASSWORD: 8+, upper, lower, digit, symbol". */
-function generateAdminPassword() {
-    return `${randomBytes(18).toString('base64')}Aa1!`;
-}
 /**
  * #171: how the host signs a files management request with the key this step
  * delivers under {@link FILES_MANAGEMENT_KEY_REF} (files'

package/dist/plan/zitadel-system-api.d.ts

@@ -0,0 +1,64 @@
+/**
+ * #283: foundry's way into a brand-new ZITADEL instance. ZITADEL's system API
+ * (`POST /system/v1/instances/_create`, permission `system.instance.write`,
+ * https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
+ * creates the instance with a machine owner (IAM_OWNER of that instance) and
+ * returns that owner's personal access token (`pat`) once, inline. foundry
+ * authenticates to the system API with a short-lived RS256 JWT signed by a
+ * keypair it generates: the public half goes into the container as a system
+ * API user, the private half stays in memory for one run. The calls follow
+ * ZITADEL's source and proto and have not been run against a live instance.
+ */
+/** The system API user's name; it is the JWT's `iss` and `sub`. */
+export declare const SYSTEM_API_USER_NAME = "foundry";
+/** A fresh RSA keypair: the public key (PEM) for ZITADEL, the private key (PKCS#8 PEM) for signing. */
+export declare function generateSystemApiKeypair(): {
+    publicKey: string;
+    privateKey: string;
+};
+/**
+ * The value of `ZITADEL_SYSTEMAPIUSERS`: JSON in ZITADEL's `SystemAPIUsers`
+ * shape (`cmd/defaults.yaml`), `KeyData` being the base64 of the public key
+ * PEM. With no `Memberships` ZITADEL grants exactly System/SYSTEM_OWNER.
+ */
+export declare function systemApiUsersEnv(publicKeyPem: string): string;
+/** A 1-minute RS256 JWT for the system API: `iss` = `sub` = the user name, `aud` = the instance URL. */
+export declare function signSystemApiJwt(privateKeyPem: string, audience: string, nowMs: number): string;
+/**
+ * How a create failed. `rejected`: ZITADEL refused it for good before doing
+ * anything (bad key, bad request), so nothing exists. `exists`: an instance
+ * for the domain already exists. `uncertain`: the request may have reached
+ * ZITADEL (timeout, network error, 5xx, an unreadable answer), so an instance
+ * may exist. The caller records a marker for the last two.
+ */
+export declare class CreateInstanceError extends Error {
+    readonly kind: 'rejected' | 'exists' | 'uncertain';
+    constructor(kind: 'rejected' | 'exists' | 'uncertain', message: string);
+}
+/** What a person does when an instance exists without a delivered bearer. Nothing is deleted automatically. */
+export declare function instanceWithoutBearerMessage(hostname: string, detail: string): string;
+export interface CreateInstanceRuntime {
+    fetch?: typeof fetch;
+    now: () => number;
+    /** Fetch timeout for the one create call (default 30s). */
+    timeoutMs?: number;
+}
+/**
+ * Creates the platform's ZITADEL instance on `customDomain` with one machine
+ * owner and returns its id and the owner's PAT. Sends exactly one request,
+ * never retries, and signs a fresh 60-second JWT for it. The PAT is returned
+ * to the caller only, never logged or put in an error.
+ */
+export declare function createZitadelInstance(input: {
+    customDomain: string;
+    privateKey: string;
+    instanceName: string;
+    firstOrgName: string;
+    owner: {
+        userName: string;
+        name: string;
+    };
+}, runtime: CreateInstanceRuntime): Promise<{
+    instanceId: string;
+    pat: string;
+}>;

package/dist/plan/zitadel-system-api.js

@@ -0,0 +1,125 @@
+import { createSign, generateKeyPairSync } from 'node:crypto';
+/**
+ * #283: foundry's way into a brand-new ZITADEL instance. ZITADEL's system API
+ * (`POST /system/v1/instances/_create`, permission `system.instance.write`,
+ * https://github.com/zitadel/zitadel/blob/main/proto/zitadel/system.proto)
+ * creates the instance with a machine owner (IAM_OWNER of that instance) and
+ * returns that owner's personal access token (`pat`) once, inline. foundry
+ * authenticates to the system API with a short-lived RS256 JWT signed by a
+ * keypair it generates: the public half goes into the container as a system
+ * API user, the private half stays in memory for one run. The calls follow
+ * ZITADEL's source and proto and have not been run against a live instance.
+ */
+/** The system API user's name; it is the JWT's `iss` and `sub`. */
+export const SYSTEM_API_USER_NAME = 'foundry';
+/** A fresh RSA keypair: the public key (PEM) for ZITADEL, the private key (PKCS#8 PEM) for signing. */
+export function generateSystemApiKeypair() {
+    return generateKeyPairSync('rsa', {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: 'spki', format: 'pem' },
+        privateKeyEncoding: { type: 'pkcs8', format: 'pem' },
+    });
+}
+/**
+ * The value of `ZITADEL_SYSTEMAPIUSERS`: JSON in ZITADEL's `SystemAPIUsers`
+ * shape (`cmd/defaults.yaml`), `KeyData` being the base64 of the public key
+ * PEM. With no `Memberships` ZITADEL grants exactly System/SYSTEM_OWNER.
+ */
+export function systemApiUsersEnv(publicKeyPem) {
+    return JSON.stringify({
+        [SYSTEM_API_USER_NAME]: { KeyData: Buffer.from(publicKeyPem).toString('base64') },
+    });
+}
+const b64url = (input) => Buffer.from(input).toString('base64url');
+/** A 1-minute RS256 JWT for the system API: `iss` = `sub` = the user name, `aud` = the instance URL. */
+export function signSystemApiJwt(privateKeyPem, audience, nowMs) {
+    const iat = Math.floor(nowMs / 1000);
+    const head = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+    const body = b64url(JSON.stringify({
+        iss: SYSTEM_API_USER_NAME,
+        sub: SYSTEM_API_USER_NAME,
+        aud: audience,
+        iat,
+        exp: iat + 60,
+    }));
+    const signature = createSign('RSA-SHA256').update(`${head}.${body}`).sign(privateKeyPem);
+    return `${head}.${body}.${b64url(signature)}`;
+}
+/**
+ * How a create failed. `rejected`: ZITADEL refused it for good before doing
+ * anything (bad key, bad request), so nothing exists. `exists`: an instance
+ * for the domain already exists. `uncertain`: the request may have reached
+ * ZITADEL (timeout, network error, 5xx, an unreadable answer), so an instance
+ * may exist. The caller records a marker for the last two.
+ */
+export class CreateInstanceError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'CreateInstanceError';
+    }
+}
+/** What a person does when an instance exists without a delivered bearer. Nothing is deleted automatically. */
+export function instanceWithoutBearerMessage(hostname, detail) {
+    return `platform:auth: a ZITADEL instance may already exist for ${hostname} without a delivered bearer (${detail}). To recover, delete the instance with the system API (DELETE /system/v1/instances/{id}) or redeploy the ZITADEL database, remove the recorded key zitadel_platform_instance_undelivered, then apply again`;
+}
+/**
+ * Creates the platform's ZITADEL instance on `customDomain` with one machine
+ * owner and returns its id and the owner's PAT. Sends exactly one request,
+ * never retries, and signs a fresh 60-second JWT for it. The PAT is returned
+ * to the caller only, never logged or put in an error.
+ */
+export async function createZitadelInstance(input, runtime) {
+    const fetchImpl = runtime.fetch ?? globalThis.fetch;
+    const url = `https://${input.customDomain}`;
+    let response;
+    try {
+        response = await fetchImpl(`${url}/system/v1/instances/_create`, {
+            method: 'POST',
+            signal: AbortSignal.timeout(runtime.timeoutMs ?? 30_000),
+            headers: {
+                authorization: `Bearer ${signSystemApiJwt(input.privateKey, url, runtime.now())}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                instanceName: input.instanceName,
+                firstOrgName: input.firstOrgName,
+                customDomain: input.customDomain,
+                machine: {
+                    userName: input.owner.userName,
+                    name: input.owner.name,
+                    personalAccessToken: {
+                        expirationDate: new Date(runtime.now() + 10 * 365 * 86_400_000).toISOString(),
+                    },
+                },
+            }),
+        });
+    }
+    catch {
+        throw new CreateInstanceError('uncertain', instanceWithoutBearerMessage(input.customDomain, 'the create request timed out or failed'));
+    }
+    if (response.status === 401) {
+        throw new CreateInstanceError('rejected', 'platform:auth: system API key rejected (HTTP 401); nothing was created');
+    }
+    if (response.status === 409) {
+        throw new CreateInstanceError('exists', instanceWithoutBearerMessage(input.customDomain, 'ZITADEL answered 409, already exists'));
+    }
+    if (!response.ok) {
+        // A 4xx is a refusal before anything was created; a 5xx may not be.
+        throw new CreateInstanceError(response.status < 500 ? 'rejected' : 'uncertain', response.status < 500
+            ? `platform:auth: ZITADEL refused to create the instance (HTTP ${response.status}); nothing was created`
+            : instanceWithoutBearerMessage(input.customDomain, `ZITADEL answered HTTP ${response.status}`));
+    }
+    let body = {};
+    try {
+        body = (await response.json());
+    }
+    catch {
+        // Handled below.
+    }
+    if (!body.instanceId || !body.pat) {
+        throw new CreateInstanceError('uncertain', instanceWithoutBearerMessage(input.customDomain, 'the answer had no instance id or token'));
+    }
+    return { instanceId: body.instanceId, pat: body.pat };
+}

package/dist/platform.d.ts

@@ -4,7 +4,7 @@ import type { OrgId } from './org.js';
  * {@link DeclaredPlatform}. `enabled` turns the service's own provisioning
  * on; `hostname` is where it is served (default `<service>.<apex>`,
  * {@link defaultPlatformHostname}); `gitRef` is the release it runs, the
- * same "declared, not discovered" shape `HostingConfig.gitBranch` uses for
+ * same "declared, not discovered" shape `HostingEntry.branch` uses for
  * an org's own app (`org.ts`).
  */
 export interface PlatformService {

package/dist/store/postgres.js

@@ -79,13 +79,9 @@ function rowToOrg(row) {
         hosting: {
             enabled: row.hostingEnabled,
             usesDomain: row.hostingUsesDomain,
-            database: row.hostingDatabase,
             tunnel: row.hostingTunnel,
-            gitBranch: row.hostingGitBranch,
-            buildPack: row.hostingBuildPack,
             issuerApps: row.hostingIssuerApps,
-            accessEmails: row.hostingAccessEmails,
-            appEnv: row.hostingAppEnv,
+            entries: row.hostingEntries,
         },
         sso: { enabled: row.ssoEnabled },
         guests: { enabled: row.guestsEnabled },
@@ -122,13 +118,9 @@ function orgToRow(org) {
         siteUsesDomain: org.site.usesDomain,
         hostingEnabled: org.hosting.enabled,
         hostingUsesDomain: org.hosting.usesDomain,
-        hostingDatabase: org.hosting.database,
         hostingTunnel: org.hosting.tunnel,
-        hostingGitBranch: org.hosting.gitBranch,
-        hostingBuildPack: org.hosting.buildPack,
         hostingIssuerApps: org.hosting.issuerApps,
-        hostingAccessEmails: org.hosting.accessEmails,
-        hostingAppEnv: org.hosting.appEnv ?? {},
+        hostingEntries: org.hosting.entries,
         ssoEnabled: org.sso.enabled,
         guestsEnabled: org.guests.enabled,
         soloEnabled: org.solo.enabled,