@wtfalch/foundry 0.8.0 → 0.10.0

package/dist/plan/broker-entries.d.ts

@@ -0,0 +1,104 @@
+import type { DeclaredOrg, HostingEntry } from '../org.js';
+import type { PlatformStore } from '../store.js';
+import type { CoolifyPort } from './executor.js';
+/**
+ * F5 (https://github.com/wtfalch/foundry/issues/314): an entry with
+ * `uses.auth` gets one entry in the broker's `AUTH_APPS`. The org executor has
+ * no way to reach the broker, so it takes a {@link BrokerPort}; the host wires
+ * one (Archon, row AR2).
+ *
+ * Foundry tells its own entry from a hand-written one by `name`
+ * (`<slug>-<entry key>`) and the `organizationId` the entry signs in, plus the
+ * names it recorded when it last wrote. Every other entry is copied back as it
+ * was. No marker field is written: the broker's parser drops unknown fields,
+ * and the name match plus the recorded names is enough.
+ */
+/** The `AUTH_APPS` name of an entry's broker entry. */
+export declare function brokerEntryName(org: DeclaredOrg, entry: HostingEntry): string;
+/** What the last successful broker write for an entry wrote (JSON of {@link BrokerEntryWant}). Ids, names and origins; never the key. */
+export declare function brokerEntryAppliedScopeKey(entryKey: string): string;
+/** The foreign entries the last write found invalid, as a JSON array of names. */
+export declare function brokerEntryWarningsScopeKey(entryKey: string): string;
+/** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
+export declare function entryAuthEnv(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>, issuer: string | null): Record<string, string>;
+/** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
+export declare function entryAuthEnvAppliedScopeKey(entryKey: string): string;
+/** What a broker entry must say, without its key. */
+export interface BrokerEntryWant {
+    name: string;
+    organizationId: string;
+    clientId: string;
+    origins: string[];
+    from: string;
+    registration: boolean;
+    replaces: string | null;
+}
+/**
+ * Each value a broker entry needs and the step that records it, so the
+ * planner can tell "not yet" (a step in this plan records it) from "blocked".
+ */
+export type BrokerEntryInput = {
+    what: string;
+    producedBy: [system: string, kind: string];
+};
+export declare function wantedBrokerEntry(org: DeclaredOrg, entry: HostingEntry, recorded: Readonly<Record<string, string>>): {
+    want: BrokerEntryWant;
+} | {
+    missing: BrokerEntryInput[];
+};
+/**
+ * The broker app, as the org executor sees it: Coolify env read, env write
+ * and deploy on the broker's app, and the platform's record of the last broker
+ * deploy. Foundry defines the port; Archon wires it (AR2).
+ */
+export interface BrokerPort {
+    /** The broker app's Coolify id; throws when the platform has none recorded. */
+    appId(): Promise<string>;
+    listEnvs(): Promise<Array<{
+        key: string;
+        value: string;
+        is_preview: boolean;
+    }>>;
+    setAuthApps(raw: string): Promise<void>;
+    deploy(): Promise<void>;
+    /** The platform's `PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY` value, if any. */
+    recordedDeploy(): Promise<string | undefined>;
+    recordDeploy(value: string): Promise<void>;
+}
+/** {@link BrokerPort} over the platform's recorded ids and a Coolify client. */
+export declare class PlatformBrokerPort implements BrokerPort {
+    private readonly options;
+    constructor(options: {
+        store: Pick<PlatformStore, 'getServiceIds' | 'putServiceIds'>;
+        coolify: Pick<CoolifyPort, 'listEnvs' | 'bulkUpsertEnvs' | 'deploy'>;
+    });
+    appId(): Promise<string>;
+    listEnvs(): Promise<{
+        key: string;
+        value: string;
+        is_preview: boolean;
+    }[]>;
+    setAuthApps(raw: string): Promise<void>;
+    deploy(): Promise<void>;
+    recordedDeploy(): Promise<string | undefined>;
+    recordDeploy(value: string): Promise<void>;
+}
+/**
+ * Writes one entry's broker entry beside the others and deploys the broker
+ * when its `AUTH_APPS` changed. Foundry's own entry is updated in place, a
+ * hand-written entry the entry declares it replaces is removed, and every
+ * other entry is copied back as it was, an invalid one included: the broker
+ * drops it, and one bad hand-written entry must not block sign-in. Errors
+ * name the entry, never a key.
+ *
+ * Returns the names of foreign entries the broker would drop, and the JSON
+ * of a replaced entry (what the F4a snapshot is handed).
+ */
+export declare function writeBrokerEntry(broker: BrokerPort, input: {
+    want: BrokerEntryWant;
+    appKey: string;
+    previous: BrokerEntryWant | null;
+}): Promise<{
+    invalidForeign: string[];
+    replaced: string | null;
+}>;

package/dist/plan/broker-entries.js

@@ -0,0 +1,214 @@
+import { entryClientIdScopeKey } from './agora.js';
+import { entryHostnames } from './hostnames.js';
+import { PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY, PLATFORM_AUTH_BROKER_SCOPE_KEY, parseBrokerDeployRecord, } from './platform-diff.js';
+import { brokerDeployNeeded, brokerDeployRecordValue, missingBrokerInputs, validateBrokerAppEntry, } from './platform-providers.js';
+/**
+ * F5 (https://github.com/wtfalch/foundry/issues/314): an entry with
+ * `uses.auth` gets one entry in the broker's `AUTH_APPS`. The org executor has
+ * no way to reach the broker, so it takes a {@link BrokerPort}; the host wires
+ * one (Archon, row AR2).
+ *
+ * Foundry tells its own entry from a hand-written one by `name`
+ * (`<slug>-<entry key>`) and the `organizationId` the entry signs in, plus the
+ * names it recorded when it last wrote. Every other entry is copied back as it
+ * was. No marker field is written: the broker's parser drops unknown fields,
+ * and the name match plus the recorded names is enough.
+ */
+/** The `AUTH_APPS` name of an entry's broker entry. */
+export function brokerEntryName(org, entry) {
+    return `${org.slug}-${entry.key}`;
+}
+/** What the last successful broker write for an entry wrote (JSON of {@link BrokerEntryWant}). Ids, names and origins; never the key. */
+export function brokerEntryAppliedScopeKey(entryKey) {
+    return `broker_entry_applied.${entryKey}`;
+}
+/** The foreign entries the last write found invalid, as a JSON array of names. */
+export function brokerEntryWarningsScopeKey(entryKey) {
+    return `broker_entry_warnings.${entryKey}`;
+}
+/** What the app's env says about who signs in, as recorded so far. Missing values are left out. */
+export function entryAuthEnv(org, entry, recorded, issuer) {
+    const auth = entry.uses?.auth;
+    if (!auth)
+        return {};
+    const organizationId = auth.users === 'customers' ? recorded[`zitadel:customers:${org.id}`] : recorded.zitadel_org;
+    const values = {
+        AUTH_ORGANIZATION_ID: organizationId,
+        AUTH_CLIENT_ID: recorded[entryClientIdScopeKey(entry.key)],
+        AUTH_ISSUER: issuer ?? undefined,
+    };
+    return Object.fromEntries(Object.entries(values).filter(([, value]) => Boolean(value)));
+}
+/** The marker `pushAppEnv` records for an entry's sign-in env; the planner compares against it. */
+export function entryAuthEnvAppliedScopeKey(entryKey) {
+    return `auth_env_applied.${entryKey}`;
+}
+export function wantedBrokerEntry(org, entry, recorded) {
+    const auth = entry.uses?.auth;
+    const organizationId = auth.users === 'customers' ? recorded[`zitadel:customers:${org.id}`] : recorded.zitadel_org;
+    const clientId = recorded[entryClientIdScopeKey(entry.key)];
+    const mailDomain = recorded.mail_domain;
+    const missing = [];
+    if (!organizationId) {
+        missing.push(auth.users === 'customers'
+            ? { what: 'the customers organisation id', producedBy: ['zitadel', 'customers'] }
+            : { what: "the org's ZITADEL org id", producedBy: ['zitadel', 'issuer'] });
+    }
+    if (!clientId)
+        missing.push({ what: 'its sign-in client id', producedBy: ['zitadel', 'app'] });
+    if (!mailDomain)
+        missing.push({ what: 'the org mail domain', producedBy: ['coolify', 'mail'] });
+    if (!organizationId || !clientId || !mailDomain)
+        return { missing };
+    return {
+        want: {
+            name: brokerEntryName(org, entry),
+            organizationId,
+            clientId,
+            origins: entryHostnames(org, entry).map((host) => `https://${host}`),
+            from: `${org.mail.noReplyLocalPart || 'noreply'}@${mailDomain}`,
+            registration: auth.registration === 'open',
+            replaces: auth.replacesBrokerEntry ?? null,
+        },
+    };
+}
+/** {@link BrokerPort} over the platform's recorded ids and a Coolify client. */
+export class PlatformBrokerPort {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async appId() {
+        const id = (await this.options.store.getServiceIds())[PLATFORM_AUTH_BROKER_SCOPE_KEY];
+        if (!id)
+            throw new Error('the platform has not recorded its broker app yet');
+        return id;
+    }
+    async listEnvs() {
+        return this.options.coolify.listEnvs(await this.appId());
+    }
+    async setAuthApps(raw) {
+        await this.options.coolify.bulkUpsertEnvs(await this.appId(), [
+            { key: 'AUTH_APPS', value: raw },
+        ]);
+    }
+    async deploy() {
+        await this.options.coolify.deploy(await this.appId());
+    }
+    async recordedDeploy() {
+        return (await this.options.store.getServiceIds())[PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY];
+    }
+    async recordDeploy(value) {
+        const ids = await this.options.store.getServiceIds();
+        await this.options.store.putServiceIds({
+            ...ids,
+            [PLATFORM_AUTH_BROKER_DEPLOYED_SCOPE_KEY]: value,
+        });
+    }
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Writes one entry's broker entry beside the others and deploys the broker
+ * when its `AUTH_APPS` changed. Foundry's own entry is updated in place, a
+ * hand-written entry the entry declares it replaces is removed, and every
+ * other entry is copied back as it was, an invalid one included: the broker
+ * drops it, and one bad hand-written entry must not block sign-in. Errors
+ * name the entry, never a key.
+ *
+ * Returns the names of foreign entries the broker would drop, and the JSON
+ * of a replaced entry (what the F4a snapshot is handed).
+ */
+export async function writeBrokerEntry(broker, input) {
+    const { want, appKey, previous } = input;
+    const label = `broker entry '${want.name}'`;
+    const brokerAppId = await broker.appId();
+    const env = (await broker.listEnvs()).find((e) => e.key === 'AUTH_APPS' && !e.is_preview);
+    // A value that reads back empty is not an empty list: writing over it
+    // would drop every hand-written entry.
+    if (env && !env.value) {
+        throw new Error(`${label}: the broker's AUTH_APPS read back empty, so nothing was written`);
+    }
+    const raw = env?.value;
+    let parsed = [];
+    if (raw) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`${label}: the broker's AUTH_APPS is not JSON, so nothing was written`);
+        }
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error(`${label}: the broker's AUTH_APPS is not a JSON array, so nothing was written`);
+    }
+    const current = parsed;
+    const isOwn = (entry) => isObject(entry) &&
+        entry.name === want.name &&
+        (entry.organizationId === want.organizationId ||
+            (previous !== null && entry.organizationId === previous.organizationId));
+    const isReplaced = (entry) => want.replaces !== null && isObject(entry) && entry.name === want.replaces && !isOwn(entry);
+    const entry = {
+        ...(current.find(isOwn) ?? {}),
+        organizationId: want.organizationId,
+        key: appKey,
+        name: want.name,
+        clientIds: [want.clientId],
+        origins: want.origins,
+        from: want.from,
+        registration: want.registration,
+    };
+    try {
+        validateBrokerAppEntry(entry, brokerAppId, 0);
+    }
+    catch (error) {
+        // The validator's message names the broker app and the entry's place in
+        // the list, never a value; keep only what is wrong with it.
+        const why = error.message.replace(/^.*AUTH_APPS\[\d+\] /, '');
+        throw new Error(`${label} would be dropped by the broker: it ${why}`);
+    }
+    const invalidForeign = [];
+    const replaced = [];
+    const next = [];
+    let placed = false;
+    const place = () => {
+        if (!placed)
+            next.push(entry);
+        placed = true;
+    };
+    current.forEach((existing, index) => {
+        if (isOwn(existing))
+            return place();
+        if (isReplaced(existing)) {
+            replaced.push(existing);
+            return place();
+        }
+        try {
+            validateBrokerAppEntry(existing, brokerAppId, index);
+        }
+        catch {
+            const name = isObject(existing) && typeof existing.name === 'string' ? existing.name : null;
+            invalidForeign.push(name === null ? `AUTH_APPS[${index}]` : name.slice(0, 100));
+        }
+        next.push(existing);
+    });
+    place();
+    const nextRaw = JSON.stringify(next);
+    const changed = JSON.stringify(current) !== nextRaw;
+    if (changed)
+        await broker.setAuthApps(nextRaw);
+    // The platform's own check of the broker's inputs also refuses a broker
+    // whose AUTH_APPS holds an invalid entry; the broker itself only drops it,
+    // so that one does not hold back the deploy.
+    const missing = (await missingBrokerInputs({ listEnvs: () => broker.listEnvs() }, brokerAppId)).filter((input) => input !== 'AUTH_APPS');
+    const live = changed ? nextRaw : raw;
+    if (brokerDeployNeeded(missing, brokerAppId, live, parseBrokerDeployRecord(await broker.recordedDeploy()))) {
+        await broker.deploy();
+        // The platform's record of what the broker last deployed, so its next
+        // apply does not read this write as drift and deploy the broker again.
+        await broker.recordDeploy(brokerDeployRecordValue(brokerAppId, live));
+    }
+    return {
+        invalidForeign,
+        replaced: replaced.length > 0 ? JSON.stringify(replaced) : null,
+    };
+}

package/dist/plan/diff.d.ts

@@ -34,6 +34,8 @@ export interface PlannedStep {
 export interface PlanOrgOptions {
     /** #267: the executor was built with a `loginHostBindings` port. */
     loginHostBindings?: boolean;
+    /** F5: the executor was built with a `broker` port. */
+    broker?: boolean;
 }
 export interface PlanDetail {
     orgId: OrgId;