@wtfalch/foundry 0.5.0 → 0.7.1

package/dist/plan/plan-apply.d.ts

@@ -17,14 +17,19 @@ export interface AuditActor {
 /**
  * The seam onto `@wtfalch/audit`.
  *
- * #19 asks for `@wtfalch/audit` itself, but that package's `record`/`ledger`
- * (see `app-template/src/lib/authz/audit.ts`) is bound to one app's Drizzle
- * table, session model and closed `EventName`/`ActorClass` vocabulary — none
- * of which foundry's SDK package has (it has no database of its own; #18
- * owns the store). Adopting it here is more than a small change, so this is
- * the interface instead, logged as a Finding on #19 rather than a half
- * adoption. A real implementation binds `@wtfalch/audit`'s `ledger.sign` to
- * foundry's own vocabulary and table once foundry has one.
+ * #19 asked for `@wtfalch/audit` itself, but at the time that package's
+ * `record`/`ledger` were bound to one app's Drizzle table, session model and
+ * closed `EventName`/`ActorClass` vocabulary -- none of which foundry's SDK
+ * package had. This interface was the stand-in, logged as a Finding on #19
+ * rather than a half adoption.
+ *
+ * #232: `@wtfalch/audit` now supports a service with no tenant database of
+ * its own (`ledgerVocabulary`, `tenantId: null`, the org as `target`) -- see
+ * `store/audit.ts`'s `createPostgresAuditLog`, which binds `ledger.sign` to
+ * foundry's own closed vocabulary and `foundry_audit_events`' replacement,
+ * `audit_events` (`@wtfalch/audit`'s own table, through migrations
+ * 0022-0026). This interface itself is unchanged -- `bootstrap.ts` and
+ * `redactingAudit` need no change either.
  */
 export interface AuditLog {
     recordPlan(entry: {
@@ -178,6 +183,10 @@ export interface PlatformStepExecutor {
      */
     blockedSteps?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<{
         auth?: string;
+        /** #211 round 6: see `PlanPlatformOptions.blocked.authExecutorMissing`. */
+        authExecutorMissing?: boolean;
+        /** #216 round 5: see `PlanPlatformOptions.blocked.authOtherInputsMissing`. */
+        authOtherInputsMissing?: string[];
         files?: string;
         integrations?: string;
         ai?: string;
@@ -190,6 +199,7 @@ export interface PlatformStepExecutor {
      */
     driftedSteps?(platform: DeclaredPlatform, recordedIds: Readonly<Record<string, string>>): Promise<{
         archon?: boolean;
+        auth?: boolean;
     }>;
     execute(action: StepAction, context: PlatformStepExecutionContext): Promise<{
         resourceId?: string;
@@ -276,6 +286,13 @@ export interface FoundryPlanApplyOptions {
      * step never runs (and fails) where no scheduler is deployed.
      */
     jobsScheduler?: boolean;
+    /**
+     * #267: true when the host's executor was built with a `loginHostBindings`
+     * port. Optional, and false without it: each org's login host is then
+     * reported blocked instead of planned, so nothing is trusted or repointed
+     * before zitadel-login's binding can be written.
+     */
+    loginHostBindings?: boolean;
     /**
      * #177: true when the host's executor was built with its own `filesOrganisation`
      * / `aiOrganisation` port. Without one, the org step needs the platform's
@@ -329,6 +346,7 @@ export declare class FoundryPlanApply implements PlanApply {
     private readonly actor;
     private readonly agora;
     private readonly jobsScheduler;
+    private readonly loginHostBindings;
     private readonly hostFiles;
     private readonly hostAi;
     private readonly now;

package/dist/plan/plan-apply.js

@@ -78,6 +78,7 @@ export class FoundryPlanApply {
     actor;
     agora;
     jobsScheduler;
+    loginHostBindings;
     hostFiles;
     hostAi;
     now;
@@ -92,6 +93,7 @@ export class FoundryPlanApply {
         this.actor = options.actor;
         this.agora = options.agora;
         this.jobsScheduler = options.jobsScheduler ?? false;
+        this.loginHostBindings = options.loginHostBindings ?? false;
         this.hostFiles = options.filesOrganisation ?? false;
         this.hostAi = options.aiOrganisation ?? false;
         this.now = options.now ?? (() => new Date());
@@ -351,7 +353,7 @@ export class FoundryPlanApply {
             this.orgPlatformReadiness(),
             this.orgAgoraHost(id),
         ]);
-        const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness);
+        const detail = computePlanDetail(org, live, applied?.serviceIds ?? {}, agoraHost, this.jobsScheduler, platformReadiness, { loginHostBindings: this.loginHostBindings });
         return { org, plan: toPlan(detail), detail };
     }
     /**
@@ -617,12 +619,13 @@ 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, a bespoke app repo, 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);
+ *   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;
  * - 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
@@ -646,8 +649,6 @@ function failedFields(org, detail, completed, serviceIds) {
         failed.add('guests.enabled');
     if (org.solo.enabled)
         failed.add('solo.enabled');
-    if (org.bespokeAppRepo !== null)
-        failed.add('bespokeAppRepo');
     if (org.adoptedApp?.form === 'repo')
         failed.add('adoptedApp');
     // `planCallsService`/`planTunnel`/`planZone` all share this same domain

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

@@ -1,4 +1,4 @@
-import type { OrgId } from '../org.js';
+import type { DeclaredOrg, OrgId } from '../org.js';
 import type { Plan, UnmanagedItem } from '../plan.js';
 import type { DeclaredPlatform } from '../platform.js';
 import type { PlannedStep } from './diff.js';
@@ -55,6 +55,17 @@ export declare const PLATFORM_ARCHON_KEY = "platform:archon";
  */
 export declare const PLATFORM_ARCHON_APPLIED_HOSTNAME_SCOPE_KEY = "archon_applied_hostname";
 export declare const PLATFORM_ARCHON_APPLIED_GIT_REF_SCOPE_KEY = "archon_applied_git_ref";
+/**
+ * #211 round 4: the broker app id Archon last registered its entry with.
+ * `provisionPlatformArchon` reads the broker to register with from
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} alone, so a broker recreated under a
+ * new app id (the old one deleted by hand, or `platform:auth` minting a fresh
+ * one) leaves Archon "applied" against a broker that no longer holds its
+ * entry. `planArchon` plans the step again whenever this differs from the
+ * currently recorded {@link PLATFORM_AUTH_BROKER_SCOPE_KEY}, the same way a
+ * changed hostname or `gitRef` does.
+ */
+export declare const PLATFORM_ARCHON_APPLIED_BROKER_SCOPE_KEY = "archon_applied_broker_app";
 /**
  * #175: set to '1' before the step points the tunnel at `http_status:404`
  * (Access app rebuild), cleared to '' once the real ingress is written back.
@@ -64,6 +75,121 @@ export declare const PLATFORM_ARCHON_APPLIED_GIT_REF_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";
+/**
+ * #216 (building on #209/#215): the `IAM_LOGIN_CLIENT` machine user minted
+ * for the login app and the broker, mirroring
+ * {@link PLATFORM_AUTH_ADMIN_USER_SCOPE_KEY}/
+ * {@link PLATFORM_AUTH_ADMIN_UNDELIVERED_SCOPE_KEY} in shape -- a recorded
+ * id once delivered, an undelivered id recorded first, the moment the user
+ * is minted.
+ *
+ * Unlike the admin pair, an undelivered login-client key never blocks
+ * {@link planAuth} from planning the step again -- #216 round 2: `planAuth`
+ * below does read it, but only to surface a non-blocking note (alongside a
+ * planned step, the way #211 round 3's broker-deploy block already is)
+ * rather than to hold the step back. Revoking a stale login-client PAT
+ * destroys nothing -- unlike the admin user's, whose loss the admin pair's
+ * own "delete that user by hand" message exists for because nothing else
+ * here re-derives the ZITADEL masterkey a lost admin PAT might have been the
+ * only record of -- so `mintLoginClientMachineUser` (`zitadel-machine-user.ts`)
+ * always lists and deletes every PAT the user already holds before minting a
+ * fresh one. That is what lets `provisionPlatformAuth` simply re-mint on the
+ * next run, with no manual step, which is #216's whole fix for the bug PR
+ * #215 shipped with: PR #215 mirrored the admin pair's forever-blocking
+ * behaviour for this key too, which meant one failed Coolify call lost the
+ * login-client token for good.
+ *
+ * #216 round 4: the value recorded here is JSON ({@link
+ * PlatformAuthLoginClientRecord}, parsed back by
+ * {@link parseLoginClientRecord}), not the bare user id round 2-3 wrote --
+ * the user id alone can never tell a healthy delivery from one a concurrent
+ * apply has since clobbered, because `mintLoginClientMachineUser` reuses the
+ * same user on every mint. The PAT id travels alongside it so {@link
+ * planAuth} can ask ZITADEL, on every plan, whether that exact PAT is still
+ * the sole live one.
+ *
+ * #216 round 5: that alone is still not enough -- a recorded PAT can be the
+ * sole live one in ZITADEL while Coolify holds a *different*, already-dead
+ * token, when two concurrent applies interleave their own writes and
+ * records in the right (wrong) order (see `authLoginClientDrifted`'s own
+ * doc comment in `platform-providers.ts` for the exact ordering). So the
+ * record also carries `tokenHash`, a sha256 of the exact token that was
+ * delivered -- never the token itself -- which `authLoginClientDrifted`
+ * compares against what is actually live in both apps' Coolify envs.
+ */
+export declare const PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY = "zitadel_platform_login_client_user_id";
+export declare const PLATFORM_AUTH_LOGIN_CLIENT_UNDELIVERED_SCOPE_KEY = "zitadel_platform_login_client_user_undelivered";
+/**
+ * #216 round 4/5: what {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY}
+ * records once delivery succeeds -- the minted machine user's id, the exact
+ * PAT id that was handed to the login app and the broker, and (round 5) a
+ * sha256 of the exact token value, never the value itself.
+ */
+export interface PlatformAuthLoginClientRecord {
+    readonly userId: string;
+    readonly patId: string;
+    readonly tokenHash: string;
+}
+/**
+ * Parses a {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY} scope id back
+ * into a {@link PlatformAuthLoginClientRecord}. `null` for anything that is
+ * not one -- absent, the pre-round-4 plain user-id string, the round 2-4
+ * `{userId, patId}` shape with no `tokenHash`, or corrupt JSON -- the same
+ * "malformed reads as unapplied, never throws" rule
+ * {@link parseBrokerDeployRecord} follows and for the same reason: this is a
+ * planning read, not a validation boundary. A pre-round-5 record reading as
+ * unapplied is the intended migration: the next apply's fresh mint recomputes
+ * it in the new shape, the same way a pre-round-4 plain-string record already
+ * did.
+ */
+export declare function parseLoginClientRecord(raw: string | undefined): PlatformAuthLoginClientRecord | null;
+/**
+ * #204/#211: the sign-in broker app `provisionPlatformAuth` creates alongside
+ * ZITADEL and the login app. Defined here, not in `platform-providers.ts`
+ * (which imports it), because `planAuth` below needs it too -- a recorded
+ * `coolify:app:platform:auth` key with no recorded broker id is a platform
+ * provisioned before #204 shipped, and must still plan the step again so the
+ * broker gets created rather than being read as fully applied.
+ */
+export declare const PLATFORM_AUTH_BROKER_SCOPE_KEY = "coolify_platform_auth_broker_app";
+/**
+ * #211: recorded once the broker has actually been deployed -- distinct from
+ * {@link PLATFORM_AUTH_BROKER_SCOPE_KEY} (the app exists) precisely because
+ * the app can exist for a while before it is ever deployed (see
+ * `missingBrokerInputs` in `platform-providers.ts`). Defined here, not there,
+ * for the same reason as {@link PLATFORM_AUTH_BROKER_SCOPE_KEY}: `planAuth`
+ * below needs it too, so a broker that is created but not yet deployed still
+ * plans the step again instead of reading as fully applied for good.
+ */
+export declare const PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY = "coolify_platform_auth_broker_deployed";
+/**
+ * #211 round 5: what {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} records
+ * once a deploy succeeds -- the broker app id that was deployed, and a sha256
+ * of the exact `AUTH_APPS` value that was live at that deploy, never the
+ * value itself (`platform-providers.ts`'s `hashAuthApps`: a secret must never
+ * reach a recorded scope id). Round 2-4 recorded a plain broker-id string
+ * there, which could only ever mean "deployed at least once" -- it could not
+ * tell a broker recreated under a new app id, or a crash between writing
+ * `AUTH_APPS` and deploying, from one still fully applied. This record is
+ * what lets `brokerDeployNeeded` (`platform-providers.ts`) and {@link planAuth}
+ * below answer both, from one mechanism instead of two ad hoc booleans.
+ */
+export interface BrokerDeployRecord {
+    readonly brokerAppId: string;
+    readonly authAppsHash: string;
+}
+/**
+ * Parses a {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} scope id back into
+ * a {@link BrokerDeployRecord}. `null` for anything that is not one --
+ * absent, the pre-round-5 plain broker-id string, or corrupt JSON -- because
+ * this is a planning read, not a validation boundary: a malformed record
+ * must read as "not deployed" so the step plans (and overwrites it) again,
+ * never throw and take the rest of the plan down with it. Exported here
+ * rather than defined in `platform-providers.ts` for the same reason
+ * {@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY} itself was moved here in
+ * round 2 -- {@link planAuth} below needs it too, without a circular import.
+ */
+export declare function parseBrokerDeployRecord(raw: string | undefined): BrokerDeployRecord | null;
 /**
  * #197: the `cloudflared` connector app `provisionPlatformAuth` runs for its
  * own tunnel. Consulted by `planAuth` below so that a tunnel recorded with no
@@ -76,6 +202,21 @@ export declare const PLATFORM_AUTH_CONNECTOR_APP_SCOPE_KEY = "coolify_platform_a
 export declare const PLATFORM_MAIL_CONNECTOR_APP_SCOPE_KEY = "coolify_platform_mail_connector_app";
 /** #197: the same connector scope id for the Archon step's own tunnel, read by `planArchon`. */
 export declare const PLATFORM_ARCHON_CONNECTOR_APP_SCOPE_KEY = "coolify_platform_archon_connector_app";
+/**
+ * #213: the three held-key refs, under tenant `platform`, Archon's own
+ * onboarding reads before it can start (archon#101 round 3, archon#104).
+ * `planArchon`'s step puts each one, once, before Archon's app deploys; an
+ * entry already held is left alone, never overwritten
+ * (`putArchonMasterKeys` in `platform-providers.ts`). The Coolify URL and
+ * token are values this package already deploys with; the Cloudflare
+ * parent token ("API Tokens Write", so Archon can mint its own scoped
+ * child tokens from it) is a human-created credential the host supplies --
+ * neither Coolify nor Cloudflare lets either be minted over an API (#213
+ * "Human steps").
+ */
+export declare const PLATFORM_ARCHON_MASTER_COOLIFY_URL_REF = "platform:master:coolify-url";
+export declare const PLATFORM_ARCHON_MASTER_COOLIFY_TOKEN_REF = "platform:master:coolify-token";
+export declare const PLATFORM_ARCHON_MASTER_CLOUDFLARE_TOKEN_REF = "platform:master:cloudflare-token";
 /**
  * #169: `platform:<service>` for the platform's own mail server (Stalwart),
  * mirroring {@link PLATFORM_AUTH_KEY} exactly.
@@ -127,6 +268,28 @@ 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.
+ */
+export declare const APP_ENV_APPLIED_SCOPE_KEY = "app_env_applied";
+/**
+ * #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";
+/**
+ * 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.
+ */
+export declare function resolveAppEnv(org: DeclaredOrg, recorded: Readonly<Record<string, string>>): {
+    values: Record<string, string>;
+    unresolved: Array<[string, string]>;
+};
 /**
  * #172: the resource key `planAi` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the same `platform:<service>` shape as
@@ -150,6 +313,27 @@ export declare const PLATFORM_AI_INTERNAL_URL_SCOPE_KEY = "ai_platform_internal_
  */
 export declare const PLATFORM_AI_MANAGEMENT_KEY_SCOPE_KEY = "ai_platform_management_key_id";
 export declare const PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY = "ai_platform_management_key_undelivered";
+/**
+ * #201: set when ai's `POST /v1/platform/keys` reports its `archon` key
+ * already exists but returns no secret -- a mint this record never learned
+ * about (most likely the crash window {@link PLATFORM_AI_MANAGEMENT_KEY_UNDELIVERED_SCOPE_KEY}'s
+ * own comment describes: the secret returned once and was never recorded).
+ * ai shows a credential's secret only at mint time, so it cannot be
+ * recovered; the planner reports this instead of minting under another
+ * name. A person revokes the live `archon` key in ai and removes this
+ * recorded key to let the step mint a fresh one.
+ */
+export declare const PLATFORM_AI_MANAGEMENT_KEY_CONFLICT_SCOPE_KEY = "ai_platform_management_key_conflict";
+/**
+ * #201: the same two-key discipline as {@link PLATFORM_INTEGRATIONS_KEY_UNDELIVERED_SCOPE_KEY}
+ * and {@link PLATFORM_INTEGRATIONS_KEY_SET_SCOPE_KEY}, for the Ed25519 pair
+ * foundry mints to sign its calls to ai's `POST /v1/platform/keys`. The
+ * undelivered key is recorded the moment the pair is minted; the set key,
+ * only once the private half was delivered and the public half pinned on
+ * the runner as `MANAGEMENT_PUBLIC_KEYS`.
+ */
+export declare const PLATFORM_AI_SIGNING_KEY_UNDELIVERED_SCOPE_KEY = "ai_platform_signing_key_undelivered";
+export declare const PLATFORM_AI_SIGNING_KEY_SET_SCOPE_KEY = "ai_platform_signing_key_set";
 /**
  * #172: ai's platform (operator) tenant id, which the management key belongs
  * to -- what ai's own README calls `AI_ORGANISATION_ID`. Not a secret.
@@ -175,14 +359,6 @@ export declare const PLATFORM_AI_MIGRATE_BLOCKED_SCOPE_KEY = "ai_platform_migrat
  * that throws) is repaired by the next one.
  */
 export declare const PLATFORM_AI_DEPLOY_PENDING_SCOPE_KEY = "ai_platform_deploy_pending";
-/**
- * #172: what the planner says while no AI management key minter is supplied.
- * A fixed text: it is part of the stale-plan comparison. ai issues its first
- * platform credential only through its `keys:issue-archon` script, run
- * against its database with its keys worker credential; it has no HTTP route
- * for that, so foundry cannot build a minter over ai's admin API yet.
- */
-export declare const PLATFORM_AI_MINTER_BLOCKED = "the platform's AI host is blocked, not planned: no AI management key minter was supplied. ai mints its first platform key only through its keys:issue-archon script against its database, so the host must supply PlatformAiDeps.managementKeyMinter";
 /**
  * #171: the resource key `planFiles` plans under and `FoundryPlatformStepExecutor`
  * dispatches on, the {@link PLATFORM_AUTH_KEY} shape for the files host.
@@ -243,6 +419,23 @@ export interface PlanPlatformOptions {
     /** Per-step block reasons the executor reports (default `{}`). */
     blocked?: {
         auth?: string;
+        /**
+         * #211 round 6: set once the auth block is "the host built the platform
+         * executor without its auth dependencies" -- distinct from `auth` itself,
+         * which also covers "the broker exists but cannot deploy yet" (#209/#210
+         * still pending). `planAuth` must withhold the step for the former
+         * whatever the recorded ids say; it must not for the latter.
+         */
+        authExecutorMissing?: boolean;
+        /**
+         * #216 round 5: the broker's required inputs other than
+         * `ZITADEL_SERVICE_USER_TOKEN` that are still missing (a subset of what
+         * `auth`'s own text already names, filtered) -- {@link planAuth} reads
+         * this to say, accurately, whether a needed login-client re-mint can
+         * actually happen on the next apply or is itself waiting on one of
+         * these. Default `[]`.
+         */
+        authOtherInputsMissing?: string[];
         files?: string;
         integrations?: string;
         ai?: string;
@@ -252,10 +445,14 @@ export interface PlanPlatformOptions {
     /**
      * Steps whose live state differs from the declared one in a way the recorded
      * ids cannot show (default `{}`). `archon`: the Cloudflare Access policy's
-     * include list is not the declared one.
+     * include list is not the declared one. `auth` (#216 round 4): the
+     * login-client PAT recorded under
+     * {@link PLATFORM_AUTH_LOGIN_CLIENT_USER_SCOPE_KEY} is no longer the sole
+     * live PAT on that ZITADEL machine user.
      */
     drifted?: {
         archon?: boolean;
+        auth?: boolean;
     };
 }
 /**