@wtfalch/foundry 0.16.11 → 0.16.13

package/dist/bootstrap/bootstrap.js

@@ -108,7 +108,7 @@ export function guardStepDeps(executor, redactor, deliverSecret, heldKeys) {
         // #201: ai's own default minter needs heldKeys too, to re-sign a mint
         // request against its signing key when an earlier run pinned it but
         // crashed before the management key itself was minted and delivered.
-        if (key === 'archon' || key === 'ai' || 'heldKeys' in copy)
+        if (key === 'archon' || key === 'ai' || key === 'auth' || 'heldKeys' in copy)
             copy.heldKeys = heldKeys;
         out[key] = copy;
     }

package/dist/plan/platform-diff.js

@@ -1021,7 +1021,7 @@ function planSfu(platform) {
  * #211 round 2: a recorded broker id is not the same as a *deployed* broker
  * ({@link PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY}) -- `provisionPlatformAuth`
  * creates and records the app before it has `ZITADEL_SERVICE_USER_TOKEN`/
- * `RESEND_API_TOKEN` to deploy it with (#209, #210). So this still plans the
+ * `LETTERMINT_API_TOKEN` to deploy it with (#209, #210). So this still plans the
  * step again while the broker sits undeployed: `executorBlocked` (from
  * `authBrokerBlockedReason`) reports it blocked, by name, for as long as the
  * inputs stay missing, and the moment they arrive the same replanned step

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

@@ -28,6 +28,19 @@ export interface PlatformAuthDeps {
      */
     zitadelForInstance?: (issuerUrl: string) => PlatformAuthDeps['zitadel'];
     deliverSecret: FoundryStepExecutorPorts['deliverSecret'];
+    /**
+     * #210: reads back the broker's Lettermint mail key, held under
+     * {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF}. Never minted here -- unlike
+     * the login-client token above, foundry has no Lettermint account of its
+     * own to mint one from, so this only ever reads back a value a human (or
+     * Archon's own onboarding) put there directly once Lettermint issued it.
+     * Absent, or with nothing held under that ref yet, `LETTERMINT_API_TOKEN`
+     * stays a gap `missingBrokerInputs` reports by name, the same "blocked,
+     * not failing" every other unmet broker input already follows.
+     */
+    heldKeys?: {
+        resolve(ref: string): Promise<string | null>;
+    };
     /** Clock, sleep and fetch for the readiness wait and delivery retries; real ones by default. */
     runtime?: PlatformAuthRuntime;
 }
@@ -234,6 +247,15 @@ export declare class FoundryPlatformStepExecutor implements PlatformStepExecutor
  * key delivered under `zitadel:platform:admin`.
  */
 export declare const PLATFORM_AUTH_INSTANCE_BEARER_REF = "zitadel:platform:instanceBearer";
+/**
+ * #210: the ref the broker's Lettermint mail key is held under. Unlike every
+ * other `_REF` in this file, nothing here ever delivers a value under it --
+ * {@link PlatformAuthDeps.heldKeys} only reads it back, once a human (or
+ * Archon's own onboarding) puts it there directly with the key Lettermint
+ * issued, on one allowed to send from every app's domain
+ * (`wtfalch/auth/docs/deploy.md`).
+ */
+export declare const PLATFORM_AUTH_BROKER_MAIL_KEY_REF = "lettermint:platform:apiToken";
 /**
  * The fixed description Stalwart's admin API key is minted under
  * (`StalwartClient.createApiKey`'s own signature returns only the secret,
@@ -591,13 +613,14 @@ export declare function createAiManagementKeyMinter(options: {
 }): AiManagementKeyMinter;
 /**
  * #211: names of the envs the platform's sign-in broker (`wtfalch/auth`'s
- * `broker/server.ts`) refuses to start without, that `provisionPlatformAuth`
- * itself has no way to supply yet -- `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`
- * (#209 mints and pushes this once it lands) and `RESEND_API_TOKEN` (#210,
- * blocked on `wtfalch/auth#138`). Read from the broker's own live env, not a
- * recorded scope id: whichever of #209/#210 lands first (or a human, setting
- * either directly on the app) is enough to clear that one input, in either
- * order, with no coupling to this step's own execution.
+ * `broker/server.ts`) refuses to start without -- `ZITADEL_SERVICE_USER_TOKEN`/
+ * `_FILE` (#209 mints and pushes this once it lands) and `LETTERMINT_API_TOKEN`
+ * (#210: `wtfalch/auth#138` moved the broker's account mail onto
+ * `@wtfalch/mailer`'s Lettermint transport, so this is the env name the
+ * broker actually reads now, not `RESEND_API_TOKEN`). Read from the broker's
+ * own live env, not a recorded scope id: whichever of #209/#210 lands first
+ * (or a human, setting either directly on the app) is enough to clear that
+ * one input, in either order, with no coupling to this step's own execution.
  *
  * #211 round 3: `AUTH_APPS` is a third required input -- the broker's own
  * `parseApps` refuses to start with no `AUTH_APPS` set or an empty array

package/dist/plan/platform-providers.js

@@ -577,6 +577,15 @@ const PLATFORM_AUTH_ORG_NAME = 'foundry';
  */
 export const PLATFORM_AUTH_INSTANCE_BEARER_REF = 'zitadel:platform:instanceBearer';
 const PLATFORM_AUTH_BEARER_USER_NAME = 'foundry-instance-owner';
+/**
+ * #210: the ref the broker's Lettermint mail key is held under. Unlike every
+ * other `_REF` in this file, nothing here ever delivers a value under it --
+ * {@link PlatformAuthDeps.heldKeys} only reads it back, once a human (or
+ * Archon's own onboarding) puts it there directly with the key Lettermint
+ * issued, on one allowed to send from every app's domain
+ * (`wtfalch/auth/docs/deploy.md`).
+ */
+export const PLATFORM_AUTH_BROKER_MAIL_KEY_REF = 'lettermint:platform:apiToken';
 /**
  * Retries `action` up to `attempts` times, sleeping increasingly between
  * tries -- the same shape the admin machine user's own delivery retry (just
@@ -811,10 +820,15 @@ async function liveLoginClientTokenHash(coolify, appId) {
  *   `IAM_LOGIN_CLIENT` machine user (never the admin one, which is
  *   `IAM_OWNER`) and delivers its token to both apps, once the broker's
  *   other required inputs are already met.
- * - The broker never receives `RESEND_API_TOKEN` either, so it will not start
- *   on `AUTH_APPS` alone. `wtfalch/auth#138` moves the broker's account mail
- *   onto held keys and `@wtfalch/mailer`; until that lands there is no held
- *   key to read here, so this stays a plain gap rather than a wired value.
+ * - ~~The broker never receives `RESEND_API_TOKEN` either, so it will not
+ *   start on `AUTH_APPS` alone.~~ Closed by #210, once `wtfalch/auth#138`
+ *   moved the broker's account mail onto `@wtfalch/mailer`'s Lettermint
+ *   transport: this function now reads the key back from
+ *   {@link PlatformAuthDeps.heldKeys} under
+ *   {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF} and pushes it as
+ *   `LETTERMINT_API_TOKEN`, once a human (or Archon's own onboarding) has
+ *   put one there. Still a gap until then, the same "blocked, not failing"
+ *   way an unset `AUTH_APPS` already is.
  * - `AUTH_APPS` starts unset: the broker has nothing to serve until a
  *   platform app registers with it ({@link provisionPlatformArchon} is the
  *   first), so it will not start (`parseApps` throws on an empty list) until
@@ -1043,14 +1057,24 @@ async function provisionPlatformAuth(context, deps) {
         { key: 'OTEL_NODE_RESOURCE_DETECTORS', value: 'none' },
         { key: 'API_CACHE_CONFIG', value: '{"defaultMinutes":2,"longMinutes":5}' },
     ];
-    // `AUTH_APPS`, `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `RESEND_API_TOKEN`
-    // are not pushed here -- this function's own doc comment, "Known gaps".
+    // #210: read back now, not inside the deploy-decision block below -- this
+    // push has to land before `missingBrokerInputs` is read a few lines down,
+    // the same way `envsDiffer`/`bulkUpsertEnvs` below already do for every
+    // other broker env, so a single apply that finds the key already held can
+    // also see `LETTERMINT_API_TOKEN` as met and deploy in that same run.
+    const heldMailKey = await deps.heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF);
+    // `AUTH_APPS` and `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` are not pushed here
+    // -- this function's own doc comment, "Known gaps". `LETTERMINT_API_TOKEN`
+    // is, once held (#210): pushing it costs nothing even while the broker
+    // still cannot start on the other two, and the deploy decision below stays
+    // gated on `missingBrokerInputs` regardless.
     const brokerEnvs = [
         {
             key: 'ZITADEL_API_URL',
             value: `http://${PLATFORM_AUTH_ZITADEL_INTERNAL_NAME}:${AUTH_ZITADEL_PORT}`,
         },
         { key: 'ZITADEL_DOMAIN', value: hostname },
+        ...(heldMailKey ? [{ key: 'LETTERMINT_API_TOKEN', value: heldMailKey }] : []),
     ];
     // Compared before the write: an env change only reaches a running
     // container on its next deploy (`diff.ts`'s `coolifyCalls` follows the
@@ -1074,11 +1098,11 @@ async function provisionPlatformAuth(context, deps) {
         await deps.coolify.deploy(loginAppId);
     }
     // #211: the broker's own `server.ts` refuses to start without
-    // `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `RESEND_API_TOKEN` -- deploying
-    // it without them only produces a container that crash-loops behind
-    // `/api`. The app is still created and recorded above either way, so #209
-    // and #210 (or a human, directly) have something to push the env onto;
-    // only the deploy waits.
+    // `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` and `LETTERMINT_API_TOKEN` --
+    // deploying it without them only produces a container that crash-loops
+    // behind `/api`. The app is still created and recorded above either way,
+    // so #209 and #210 (or a human, directly) have something to push the env
+    // onto; only the deploy waits.
     // #211 round 5: `brokerDeployNeeded` is its own reason to deploy (not only
     // alongside justCreated/running/envsChanged, none of which this function's
     // own `brokerEnvs` write above ever touches `AUTH_APPS`): it is what
@@ -1262,7 +1286,7 @@ async function provisionPlatformAuth(context, deps) {
     // envs, then redeploys both.
     //
     // Deferred, not blocked, while the broker's other required inputs
-    // (`RESEND_API_TOKEN`, `AUTH_APPS`) are still missing (composing with
+    // (`LETTERMINT_API_TOKEN`, `AUTH_APPS`) are still missing (composing with
     // #211's own gating): minting and delivering here would only redeploy a
     // broker that still refuses to start on the other missing input, spending
     // a mint and two deploys on nothing this apply can fix. `blockedSteps`'s
@@ -1967,12 +1991,12 @@ async function mailBlockedReason(platform, mail, recordedIds) {
 }
 /**
  * #211: the broker cannot start without `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`,
- * `RESEND_API_TOKEN` and `AUTH_APPS`. `provisionPlatformAuth` already skips
- * deploying the broker while any is missing ({@link missingBrokerInputs});
- * this is the same check surfaced through `blockedSteps`, so a plan says
- * why, by name, rather than the broker simply sitting undeployed with no
- * explanation. `null` while there is no broker app id recorded yet (nothing
- * to check) or every input is present.
+ * `LETTERMINT_API_TOKEN` and `AUTH_APPS`. `provisionPlatformAuth` already
+ * skips deploying the broker while any is missing
+ * ({@link missingBrokerInputs}); this is the same check surfaced through
+ * `blockedSteps`, so a plan says why, by name, rather than the broker simply
+ * sitting undeployed with no explanation. `null` while there is no broker
+ * app id recorded yet (nothing to check) or every input is present.
  *
  * #211 round 3: wraps the live read the way {@link mailBlockedReason} wraps
  * its own Coolify call -- a transient `listEnvs` failure must report a
@@ -1986,6 +2010,21 @@ async function mailBlockedReason(platform, mail, recordedIds) {
  * go fix an entry, not merely wait for one of #209/#210/Archon's own
  * registration to supply one), and reporting it identically hid which one
  * was true.
+ *
+ * #210: `LETTERMINT_API_TOKEN` joins `ZITADEL_SERVICE_USER_TOKEN` in being
+ * excluded from `otherInputsMissing` -- but only while `auth.heldKeys`
+ * actually resolves {@link PLATFORM_AUTH_BROKER_MAIL_KEY_REF} right now.
+ * `planAuth`'s own "loop fix" stops planning this step the moment every
+ * `otherInputsMissing` entry looks like something only another run can
+ * supply; excluding `LETTERMINT_API_TOKEN` unconditionally (the way
+ * `ZITADEL_SERVICE_USER_TOKEN` is, since foundry can always eventually mint
+ * that one) would keep the step planned, and `provisionPlatformAuth`
+ * running its full body, forever on a host that never wires `heldKeys` or
+ * whose operator has not put a Lettermint key there yet -- exactly the
+ * wasteful-replan bug #211 round 5 fixed for the broker deploy itself. Once
+ * the key *is* held, excluding it lets this run's `provisionPlatformAuth`
+ * push it (see that function's own `heldMailKey` read) and clears the gap
+ * for good.
  */
 async function authBrokerBlockedReason(auth, recordedIds) {
     const brokerAppId = recordedIds[PLATFORM_AUTH_BROKER_SCOPE_KEY];
@@ -1993,9 +2032,11 @@ async function authBrokerBlockedReason(auth, recordedIds) {
         return { reason: null, otherInputsMissing: [] };
     let missing;
     let authAppsRaw;
+    let heldMailKey;
     try {
         missing = await missingBrokerInputs(auth.coolify, brokerAppId);
         authAppsRaw = await currentEnvValue(auth.coolify, brokerAppId, 'AUTH_APPS');
+        heldMailKey = (await auth.heldKeys?.resolve(PLATFORM_AUTH_BROKER_MAIL_KEY_REF)) ?? null;
     }
     catch {
         return {
@@ -2007,13 +2048,19 @@ async function authBrokerBlockedReason(auth, recordedIds) {
     }
     // #216 round 5: what `provisionPlatformAuth`'s own `loginClientOtherInputsMissing`
     // gate is -- see `planAuth`'s own doc comment for why it needs this too.
-    const otherInputsMissing = missing.filter((m) => m !== 'ZITADEL_SERVICE_USER_TOKEN');
+    // #210: and `LETTERMINT_API_TOKEN`, once held -- see this function's own
+    // doc comment.
+    const otherInputsMissing = missing.filter((m) => m !== 'ZITADEL_SERVICE_USER_TOKEN' && !(m === 'LETTERMINT_API_TOKEN' && heldMailKey));
     if (missing.length === 0)
         return { reason: null, otherInputsMissing };
+    // #210: say where the operator seals the Lettermint key, not only its env name.
+    const named = (names) => names.map((m) => m === 'LETTERMINT_API_TOKEN'
+        ? `LETTERMINT_API_TOKEN (seal it under the held-key ref ${PLATFORM_AUTH_BROKER_MAIL_KEY_REF})`
+        : m);
     if (authAppsProblem(authAppsRaw, brokerAppId) === 'malformed') {
         const otherMissing = missing.filter((m) => m !== 'AUTH_APPS');
         const otherSuffix = otherMissing.length > 0
-            ? `, and it has no ${otherMissing.join(' and no ')} yet (#209, #210)`
+            ? `, and it has no ${named(otherMissing).join(' and no ')} yet (#209, #210)`
             : '';
         return {
             reason: `the platform's sign-in broker ${brokerAppId} is blocked, not deployed: its AUTH_APPS is malformed${otherSuffix}`,
@@ -2024,7 +2071,7 @@ async function authBrokerBlockedReason(auth, recordedIds) {
     // those issues when one of them is actually among what's missing.
     const suffix = missing.some((m) => m !== 'AUTH_APPS') ? ' (#209, #210)' : '';
     return {
-        reason: `the platform's sign-in broker is created but not deployed, blocked: it has no ${missing.join(' and no ')} yet${suffix}`,
+        reason: `the platform's sign-in broker is created but not deployed, blocked: it has no ${named(missing).join(' and no ')} yet${suffix}`,
         otherInputsMissing,
     };
 }
@@ -2197,8 +2244,8 @@ export const PLATFORM_ARCHON_CLIENT_ID_SCOPE_KEY = 'zitadel_platform_archon_clie
  * `provisionPlatformAuth` guarantees by the time this step is reachable (its
  * own resourceId records only once the broker app exists too). The broker
  * will not actually be able to serve a request with this key until
- * `provisionPlatformAuth`'s own "Known gaps" (`ZITADEL_SERVICE_USER_TOKEN`,
- * `RESEND_API_TOKEN`) are closed; wiring the key here is still correct and
+ * `provisionPlatformAuth`'s own `ZITADEL_SERVICE_USER_TOKEN` is minted and
+ * `LETTERMINT_API_TOKEN` is held; wiring the key here is still correct and
  * needed so the two apps agree the moment the broker can run.
  *
  * Known gaps, left for review:
@@ -2421,7 +2468,10 @@ async function provisionPlatformArchon(context, deps) {
         throw new Error(`platform:archon: app ${appId} lost its AUTH_APP_KEY between two reads`);
     }
     envs.push({ key: 'AUTH_APP_KEY', value: appKey });
-    envs.push(...inputs.envs);
+    // A value with a line break (the PEM management keys) must be flagged:
+    // unflagged, Coolify writes it into `.env` unquoted and the container never
+    // starts.
+    envs.push(...inputs.envs.map((e) => (e.value.includes('\n') ? { ...e, multiline: true } : e)));
     const changed = await envsDiffer(deps.coolify, appId, envs);
     await deps.coolify.bulkUpsertEnvs(appId, envs);
     // ---- register with the broker (#204) ---------------------------------------
@@ -2483,8 +2533,8 @@ async function provisionPlatformArchon(context, deps) {
         await deps.coolify.bulkUpsertEnvs(brokerAppId, desiredAuthApps);
     }
     // #211 round 2: deploying the broker before its own `server.ts` can start
-    // (missing `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` or `RESEND_API_TOKEN`, #209,
-    // #210) only produces a container that crash-loops behind `/api` -- the
+    // (missing `ZITADEL_SERVICE_USER_TOKEN`/`_FILE` or `LETTERMINT_API_TOKEN`,
+    // #209, #210) only produces a container that crash-loops behind `/api` -- the
     // same rule `provisionPlatformAuth` follows for its own deploy of this
     // app. The env is still written either way, so the broker serves the new
     // registration the moment it is next deployed, by either step.
@@ -3044,9 +3094,6 @@ async function collectArchonServiceInputs(platform, deps, recorded) {
             envs.push({ key: 'INTEGRATIONS_URL', value: url }, {
                 key: 'INTEGRATIONS_MANAGEMENT_PRIVATE_KEY',
                 value: held(INTEGRATIONS_MANAGEMENT_KEY_REF),
-                // A PEM spans lines; unflagged, Coolify writes it into `.env`
-                // unquoted and the container never starts.
-                multiline: true,
             }, {
                 key: 'INTEGRATIONS_MANAGEMENT_ISSUER',
                 value: INTEGRATIONS_MANAGEMENT_ISSUER,
@@ -3987,13 +4034,14 @@ async function findOrCreatePlatformApp(coolify, name, environment, create) {
 }
 /**
  * #211: names of the envs the platform's sign-in broker (`wtfalch/auth`'s
- * `broker/server.ts`) refuses to start without, that `provisionPlatformAuth`
- * itself has no way to supply yet -- `ZITADEL_SERVICE_USER_TOKEN`/`_FILE`
- * (#209 mints and pushes this once it lands) and `RESEND_API_TOKEN` (#210,
- * blocked on `wtfalch/auth#138`). Read from the broker's own live env, not a
- * recorded scope id: whichever of #209/#210 lands first (or a human, setting
- * either directly on the app) is enough to clear that one input, in either
- * order, with no coupling to this step's own execution.
+ * `broker/server.ts`) refuses to start without -- `ZITADEL_SERVICE_USER_TOKEN`/
+ * `_FILE` (#209 mints and pushes this once it lands) and `LETTERMINT_API_TOKEN`
+ * (#210: `wtfalch/auth#138` moved the broker's account mail onto
+ * `@wtfalch/mailer`'s Lettermint transport, so this is the env name the
+ * broker actually reads now, not `RESEND_API_TOKEN`). Read from the broker's
+ * own live env, not a recorded scope id: whichever of #209/#210 lands first
+ * (or a human, setting either directly on the app) is enough to clear that
+ * one input, in either order, with no coupling to this step's own execution.
  *
  * #211 round 3: `AUTH_APPS` is a third required input -- the broker's own
  * `parseApps` refuses to start with no `AUTH_APPS` set or an empty array
@@ -4011,8 +4059,8 @@ export async function missingBrokerInputs(coolify, brokerAppId) {
     if (!has('ZITADEL_SERVICE_USER_TOKEN') && !has('ZITADEL_SERVICE_USER_TOKEN_FILE')) {
         missing.push('ZITADEL_SERVICE_USER_TOKEN');
     }
-    if (!has('RESEND_API_TOKEN'))
-        missing.push('RESEND_API_TOKEN');
+    if (!has('LETTERMINT_API_TOKEN'))
+        missing.push('LETTERMINT_API_TOKEN');
     if (authAppsProblem(value('AUTH_APPS'), brokerAppId) !== null)
         missing.push('AUTH_APPS');
     return missing;

package/package.json

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