@wtfalch/foundry 0.65.0 → 0.67.0

package/dist/plan/entry-analytics-key.js

@@ -0,0 +1,134 @@
+import { analyticsUrlFor } from './analytics.js';
+import { appStepKey } from './platform-diff.js';
+/**
+ * `uses.analytics` on a server entry: one site key of its own at the company's analytics backend, minted
+ * through `POST /v1/site-keys` with the operator key and written as `ANALYTICS_URL` and `ANALYTICS_SITE_KEY` to
+ * the entry's env. The backend shows the secret once, so this follows rule 1 of CLAUDE.md "Platform steps":
+ *
+ * 1. the key's id is recorded as `analytics_key_undelivered.<entry>` and persisted before the env is written;
+ * 2. the env write is tried 3 times with the same secret; the id is the main id `analytics:key:<orgId>:<entry>`
+ *    and the applied marker only after it worked, and the undelivered marker is cleared then;
+ * 3. a marker left behind (every try failed) is reported blocked and never minted again.
+ *
+ * A Worker app entry is skipped: Boule installs its keys per copy. The entry's stage gets its own key through
+ * `plan/stage-services.ts` (service `analytics`, environment `stage`), so the two differ. Removing
+ * `uses.analytics` or the entry plans the retire form: revoke the key, take both env names away.
+ */
+export const entryAnalyticsUndeliveredScopeKey = (entryKey) => `analytics_key_undelivered.${entryKey}`;
+/** The address the entry's env was last written with; a change rewrites the address only. */
+export const entryAnalyticsAppliedScopeKey = (entryKey) => `analytics_key_applied.${entryKey}`;
+/** The id of a key that was revoked, so a stale main id is not revoked again. */
+export const entryAnalyticsRetiredScopeKey = (entryKey) => `analytics_key_retired.${entryKey}`;
+export const ENTRY_ANALYTICS_KEY_DELIVERY_ATTEMPTS = 3;
+/** The name the backend knows the key by; its site derives from it. */
+export const entryAnalyticsKeyName = (org, entryKey) => `${org.slug}-${entryKey}-analytics`;
+/** The stage copy's key name: the backend reads the `-stage` suffix as the stage environment. */
+export const stageAnalyticsKeyName = (org, entryKey) => `${org.slug}-${entryKey}-stage-analytics`;
+const servesKey = (entry) => entry.uses?.analytics === true && !entry.workerApp && entry.live !== false;
+export function planEntryAnalyticsKeys(org, recordedIds, plannedSteps, analyticsPort) {
+    const steps = [];
+    const blocked = [];
+    if (!org.hosting.enabled)
+        return { steps, blocked };
+    const planned = (system, kind, key) => plannedSteps.some((p) => p.action.system === system && p.action.kind === kind && p.action.key === key);
+    const wanted = new Map(org.hosting.entries.filter(servesKey).map((e) => [e.key, e]));
+    const mainPrefix = `analytics:key:${org.id}:`;
+    // Keys whose entry stopped using analytics or is gone: a delivered key (main id) or one minted and never
+    // delivered (undelivered marker), so the retire clears the marker and the entry can mint again later.
+    const undeliveredPrefix = entryAnalyticsUndeliveredScopeKey('');
+    const retiring = new Set();
+    for (const [name, id] of Object.entries(recordedIds)) {
+        if (!id)
+            continue;
+        const prefix = name.startsWith(mainPrefix)
+            ? mainPrefix
+            : name.startsWith(undeliveredPrefix)
+                ? undeliveredPrefix
+                : null;
+        if (!prefix)
+            continue;
+        const entryKey = name.slice(prefix.length);
+        if (wanted.has(entryKey) ||
+            retiring.has(entryKey) ||
+            recordedIds[entryAnalyticsRetiredScopeKey(entryKey)] === id) {
+            continue;
+        }
+        retiring.add(entryKey);
+        const key = `${mainPrefix}${entryKey}`;
+        if (!analyticsPort) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} analytics key is not revoked, not planned: the host supplies no analytics port`,
+                key,
+            });
+        }
+        else if (!recordedIds[`coolify:analytics:${org.id}`]) {
+            blocked.push({
+                description: `${org.slug}'s ${entryKey} analytics key is not revoked, not planned: the analytics backend is not recorded`,
+                key,
+            });
+        }
+        else {
+            steps.push({
+                action: {
+                    system: 'analytics',
+                    kind: 'key',
+                    key: `${org.id}:${entryKey}`,
+                    desired: { mode: 'retire' },
+                },
+                step: {
+                    description: `revoke ${org.slug}'s ${entryKey} analytics key and take ANALYTICS_* out of its env: the entry no longer uses analytics`,
+                    destroys: true,
+                    migrates: false,
+                },
+            });
+        }
+    }
+    for (const entry of wanted.values()) {
+        const stepKey = appStepKey(org, entry.key);
+        const key = `analytics:key:${stepKey}`;
+        const at = `${org.slug}'s ${entry.key} analytics key`;
+        const block = (why) => blocked.push({ description: `${at} is blocked: ${why}`, key });
+        const url = analyticsUrlFor(org);
+        const undelivered = recordedIds[entryAnalyticsUndeliveredScopeKey(entry.key)];
+        if (undelivered) {
+            block(`key ${undelivered} was minted but never written to the app, and the backend shows a key once; remove the recorded id ${entryAnalyticsUndeliveredScopeKey(entry.key)} to mint a new key, which replaces that one`);
+            continue;
+        }
+        const live = recordedIds[key] &&
+            recordedIds[entryAnalyticsRetiredScopeKey(entry.key)] !== recordedIds[key];
+        if (live && recordedIds[entryAnalyticsAppliedScopeKey(entry.key)] === url)
+            continue;
+        if (!analyticsPort) {
+            block('the host supplies no analytics port');
+            continue;
+        }
+        if (!recordedIds[`coolify:analytics:${org.id}`] && !planned('coolify', 'analytics', org.id)) {
+            block("the company's analytics backend is not recorded or planned yet");
+            continue;
+        }
+        if (!recordedIds[`coolify:app:${stepKey}`] && !planned('coolify', 'app', stepKey)) {
+            block("the entry's app is not recorded yet");
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'analytics',
+                kind: 'key',
+                key: stepKey,
+                desired: {
+                    mode: live ? 'url' : 'mint',
+                    name: entryAnalyticsKeyName(org, entry.key),
+                    analyticsUrl: url,
+                },
+            },
+            step: {
+                description: live
+                    ? `write the analytics address to ${org.slug}'s ${entry.key} env`
+                    : `mint ${at}, write ANALYTICS_URL and ANALYTICS_SITE_KEY to its env, restart the app`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}

package/dist/plan/executor.d.ts

@@ -2,6 +2,7 @@ import type { OrgMailOptions, OrgMailOrg, OrgMailResult } from '@wtfalch/email/p
 import { type CallsSfuUrls } from '../calls-sfu.js';
 import type { DeclaredOrg, HostingBuildPack, OrgId } from '../org.js';
 import type { DeclaredOrgStore } from '../store.js';
+import { type AnalyticsPort } from './analytics.js';
 import { type BlueGreenServer, type BlueGreenSubject } from './blue-green.js';
 import { type BouleOwnerSeed } from './boule.js';
 import { type BrokerPort } from './broker-entries.js';
@@ -844,6 +845,11 @@ export interface ZitadelPort {
         postLogoutRedirectUris: string[];
         /** `jwt` for an entry with `uses.auth.mcp` (providers 0.11.0). Omitted: opaque. */
         accessTokenType?: 'jwt' | 'opaque';
+        /**
+         * The instance's login host. With `loginV2.required` off an app with no base URI of its own lands on
+         * the v1 login, so every app foundry makes carries one from the start; a `required` instance ignores it.
+         */
+        loginBaseUri?: string;
     }): Promise<{
         appId: string;
         clientId: string;
@@ -1183,12 +1189,24 @@ export interface ZitadelPort {
     updateOidcAppLoginBaseUri(orgId: string, projectId: string, appId: string, loginBaseUri: string): Promise<void>;
     /**
      * Lets each app's own Login V2 base URI count: foundry starts ZITADEL with `LOGINV2_REQUIRED=true`,
-     * which makes the instance ignore it. The host sets the instance feature (`PUT /v2/features/instance`
+     * which makes the instance ignore it (`internal/query/oidc_client.go` in ZITADEL v4.17.3, lines 88-92:
+     * with `required` the app's own base URI is overwritten by the instance's). Call it through
+     * {@link allowPerAppLoginBaseUris}, which first gives every app a base URI. The host sets the instance feature (`PUT /v2/features/instance`
      * with `loginV2.required` false and the instance default as `baseUri`). Called before an app is
      * pointed at its own `/sign-in/` on a company that runs its own ZITADEL; the shared instance's
      * bindings port does the same for the platform's. Optional: absent, nothing is called.
      */
     allowPerAppLoginBaseUri?(instanceBaseUri: string): Promise<void>;
+    /** Every organisation of the instance. Optional: {@link allowPerAppLoginBaseUris} refuses without it. */
+    listOrgs?(): Promise<Array<{
+        id: string;
+        state?: string;
+    }>>;
+    /** Every project of an organisation. Optional: {@link allowPerAppLoginBaseUris} refuses without it. */
+    listProjects?(orgId: string): Promise<Array<{
+        id: string;
+        state?: string;
+    }>>;
     /**
      * Occupies `userName` in `orgId` with a machine user that has no role and
      * no token, so nobody can register under that name. Idempotent: a user
@@ -1824,6 +1842,8 @@ export interface FoundryStepExecutorPorts {
     workerAppKeys?: KeysCustodyPort;
     /** F7: the keys service's per-company registrar. Without it the plan reports Boule's registrar key blocked (the host also sets `FoundryPlanApplyOptions.keysRegistrarUrl`). */
     keysRegistrar?: KeysRegistrarPort;
+    /** The company's analytics backend operator API: mints and revokes site keys. Without it the plan reports each `uses.analytics` key blocked (the host also sets `FoundryPlanApplyOptions.analyticsPort`). */
+    analytics?: AnalyticsPort;
     /**
      * C3: mints the credential an org's Boule reaches Archon with (org-scoped; `orgs:request` and
      * `orgs:read` for that org). Archon implements it. Every call rotates the credential (the old secret
@@ -2003,6 +2023,10 @@ export declare const BOULE_PORT = 3000;
 export declare const KOSMOS_REPO = "wtfalch/kosmos";
 export declare const KOSMOS_APP_DOCKERFILE = "/Dockerfile";
 export declare const KOSMOS_PORT = 3000;
+/** The company's analytics backend (https://github.com/wtfalch/analytics): root Dockerfile, serves on 3000, migrates in its own start script. */
+export declare const ANALYTICS_REPO = "wtfalch/analytics";
+export declare const ANALYTICS_APP_DOCKERFILE = "/Dockerfile";
+export declare const ANALYTICS_PORT = 3000;
 export declare const LOG_DIR = "/app/logs";
 /** The company's Coolify destination (its Docker network `co-<slug>`), recorded when its first resource is created. */
 export declare const COOLIFY_DESTINATION_SCOPE_KEY = "coolify_destination";
@@ -2377,6 +2401,12 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      *    the snapshot taken before the repoint still named it.
      */
     private zitadelLoginHost;
+    /**
+     * `{ loginBaseUri }` for an app made in the org's ZITADEL: the instance's own login host (a company's own
+     * `auth.` host, else the shared one). Nothing when the shared host is not known. See
+     * {@link FoundryStepExecutorPorts}' `createOidcApp` `loginBaseUri`.
+     */
+    private instanceLoginBaseUriFor;
     /**
      * The host table of a company's own in-app login app as a bindings port that collects its edits and
      * writes them once on `flush` (one redeploy, none when nothing changed). Used for a company that runs
@@ -2776,12 +2806,14 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      */
     private mintIfAbsent;
     /**
-     * Every company's Boule, F3/#970: `NATIVE_BUILD_KEY` is what Boule presents to Archon's
-     * native-build route (estate#262) to ask it to dispatch `build-app.yml`. Minted once, like
-     * {@link ensureAuthAppKey}, and never rotated; a present-but-empty value (the bug
-     * `mintNativeBuildKey`'s own read-then-generate had, see #957) is treated as not set.
+     * foundry#987: nothing reads `NATIVE_BUILD_KEY` any more -- Boule calls Archon's org build
+     * route (`/api/orgs/{orgId}/native/builds`) with its own org credential instead
+     * (`BOULE_ARCHON_CREDENTIAL_ENV`, archon#706, boule#432). This takes the env row away from
+     * every Boule that still has one from #970/#971; `NATIVE_BUILD_KEY_ENV` and
+     * `NATIVE_BUILD_KEY_BYTES` are deprecated and go in the next release (the two-release removal
+     * rule), once no live Boule holds the row any more.
      */
-    private ensureNativeBuildKey;
+    private dropNativeBuildKeyEnv;
     /**
      * `null` once the app already has one -- `AUTH_COOKIE_SECRET` is generated
      * only the first time (task brief), never regenerated or overwritten, so a
@@ -3400,6 +3432,35 @@ export declare class FoundryStepExecutor implements StepExecutor, StepDestroyer
      * shape {@link coolifyAgora}'s own doc comment explains.
      */
     private coolifyBoule;
+    /**
+     * `plan/diff.ts`'s `planAnalyticsBackend`: the company's analytics backend as one more Coolify application
+     * from https://github.com/wtfalch/analytics's root Dockerfile ({@link ANALYTICS_REPO}), with a database of its
+     * own, shaped like {@link coolifyKosmos}. Its start script migrates as the owner role and then serves as the
+     * runtime role, so `pushDatabaseUrl` gives it both URLs. It needs no sign-in client: it reads only
+     * `AUTH_ORGANIZATION_ID` (the tenant id derives from it), `APP_URL` and the operator key.
+     *
+     * `ANALYTICS_OPERATOR_KEY` is made once here (`mintIfAbsent`) and written only to this app's env. No outside
+     * service shows it once, so no undelivered marker is needed: a failed write leaves nothing live to mint twice.
+     * Steps that call the backend's operator API read it back from this env.
+     *
+     * A brand new app is deployed once ({@link ANALYTICS_DEPLOYED_SCOPE_KEY}), as for Boule (#504).
+     */
+    private coolifyAnalytics;
+    /** The backend's operator key, read from its own env. Fixed text when the backend or the key is not there. */
+    private analyticsOperatorKey;
+    /**
+     * C2 `coolify:analytics-boule` (`plan/analytics-boule.ts`): the backend's address and operator key into
+     * Boule's env, then Boule restarts. `analytics_boule_applied` is recorded last. Retire takes both names away.
+     */
+    private analyticsBoule;
+    /**
+     * `plan/entry-analytics-key.ts`: one server entry's site key (CLAUDE.md "Platform steps" rule 1). Mint: the
+     * key's id is recorded as undelivered and persisted before anything is written; the env write is tried 3
+     * times with the same secret; the applied address and the cleared marker come last; every try failing leaves
+     * the marker, and the error names the id only. `url` rewrites the address. Retire revokes the key and the
+     * env names. The operator key is read from the backend's env and never recorded.
+     */
+    private analyticsEntryKey;
     /**
      * `plan/diff.ts`'s `planKosmos`: provisions the org's own kosmos
      * (https://github.com/wtfalch/kosmos) as one more Coolify application, from
@@ -4103,4 +4164,16 @@ export declare function isNoChangesError(error: unknown): boolean;
  * {@link ZitadelPort.updateOidcAppLoginBaseUri} that counts an app already holding the wanted base URI as
  * done: ZITADEL answers that write with "No changes" and a repeat apply must not fail on it.
  */
+/**
+ * Turns the instance feature `loginV2.required` off so each app's own base URI counts, and makes sure no
+ * app can then land on ZITADEL's v1 login: with `required` off an app without a base URI of its own
+ * (ZITADEL's own console app, an app foundry did not make, an app made later) falls back to v1, and
+ * ZITADEL v4.17.3 gives a `required` instance's base URI to every app but ignores an app's own
+ * (`internal/query/oidc_client.go:88-92`), so the only way is a base URI on every app. Every live OIDC
+ * app of every organisation and project gets `instanceBaseUri` when it has none; an app that has one
+ * keeps it. The apps are set first, while `required` still makes the instance ignore them, so no sign-in
+ * passes through a gap. Without a way to list every app, or with a listing that may be cut short, it
+ * throws before the feature is touched.
+ */
+export declare function allowPerAppLoginBaseUris(zitadel: Pick<ZitadelPort, 'allowPerAppLoginBaseUri' | 'listOrgs' | 'listProjects' | 'listApps' | 'updateOidcAppLoginBaseUri'>, instanceBaseUri: string): Promise<void>;
 export declare function setOidcAppLoginBaseUri(zitadel: Pick<ZitadelPort, 'updateOidcAppLoginBaseUri'>, orgId: string, projectId: string, appId: string, loginBaseUri: string): Promise<void>;