@wtfalch/foundry 0.9.0 → 0.11.0

package/dist/plan/adopt.js

@@ -0,0 +1,252 @@
+import { appStepKey } from './platform-diff.js';
+/** The `foundry_adoptions.resource_key` of the org's adopted tunnel: also its `serviceIds` key (#312). */
+export const adoptedTunnelKey = (org) => `cloudflare:tunnel:${org.id}`;
+/** The `foundry_adoptions.resource_key` of the org's adopted connector app (#312). */
+export const adoptedConnectorKey = (org) => `cloudflare:connector:${org.id}`;
+/** Every resource the org adopts, the database first, then the apps, the tunnel and its connector. */
+export function adoptedResources(org) {
+    if (!org.hosting.enabled)
+        return [];
+    const database = org.hosting.adopt?.database;
+    const resources = [];
+    if (database) {
+        resources.push({ resourceKey: `coolify:database:${org.id}`, kind: 'database', uuid: database });
+    }
+    for (const entry of org.hosting.entries) {
+        if (!entry.adopt)
+            continue;
+        resources.push({
+            resourceKey: `coolify:app:${appStepKey(org, entry.key)}`,
+            kind: 'app',
+            uuid: entry.adopt.app,
+            entry,
+        });
+    }
+    const { tunnel, connectorApp } = org.hosting.adopt ?? {};
+    if (tunnel)
+        resources.push({ resourceKey: adoptedTunnelKey(org), kind: 'tunnel', uuid: tunnel });
+    if (connectorApp) {
+        resources.push({
+            resourceKey: adoptedConnectorKey(org),
+            kind: 'connector',
+            uuid: connectorApp,
+        });
+    }
+    return resources;
+}
+/**
+ * Every uuid the org declares as adopted, whether or not hosting is enabled
+ * now: a uuid in this set is never stopped or deleted by foundry (#311).
+ */
+export function declaredAdoptUuids(org) {
+    const uuids = new Set();
+    if (org.hosting.adopt?.database)
+        uuids.add(org.hosting.adopt.database);
+    if (org.hosting.adopt?.tunnel)
+        uuids.add(org.hosting.adopt.tunnel);
+    if (org.hosting.adopt?.connectorApp)
+        uuids.add(org.hosting.adopt.connectorApp);
+    for (const entry of org.hosting.entries)
+        if (entry.adopt)
+            uuids.add(entry.adopt.app);
+    return uuids;
+}
+/**
+ * A snapshot is ACTIVE when its row is `adopted` or `confirmed` and the uuid
+ * it recorded is the uuid the org declares now (#311). Only then may foundry
+ * write to the live resource.
+ */
+export function isActiveSnapshot(row, uuid) {
+    return (row !== null &&
+        row !== undefined &&
+        (row.state === 'adopted' || row.state === 'confirmed') &&
+        row.settings.uuid === uuid);
+}
+/**
+ * A row in `adopted`, `confirmed` or `restored` protects its key: foundry never
+ * manages, stops or deletes that resource as its own. Only `released` lets go (#311).
+ */
+export function protectsKey(row) {
+    return row?.state === 'adopted' || row?.state === 'confirmed' || row?.state === 'restored';
+}
+/** Where the secret part of a snapshot lives in the `AdoptionVault`. */
+export function adoptionVaultRef(org, resource) {
+    return `foundry:adopt:${org.id}:${resource.kind === 'app' ? `app:${resource.entry.key}` : resource.kind}`;
+}
+/** Coolify's field names for the non-secret settings an app snapshot keeps. */
+const APP_SETTING_FIELDS = [
+    'fqdn',
+    'git_branch',
+    'base_directory',
+    'publish_directory',
+    'build_pack',
+    'ports_exposes',
+    'health_check_enabled',
+    'health_check_path',
+    'health_check_port',
+    'health_check_method',
+    'health_check_return_code',
+    'health_check_scheme',
+    'health_check_interval',
+    'health_check_timeout',
+    'health_check_retries',
+    'health_check_start_period',
+    'custom_network_aliases',
+    'is_auto_deploy_enabled',
+    'limits_memory',
+    'limits_memory_swap',
+    'limits_memory_swappiness',
+    'limits_memory_reservation',
+    'limits_cpus',
+    'limits_cpuset',
+    'limits_cpu_shares',
+];
+export function snapshotAppSettings(live) {
+    return Object.fromEntries(APP_SETTING_FIELDS.map((field) => [field, live[field] ?? null]));
+}
+export const bareName = (name) => name.trim().replace(/^https?:\/\//, '');
+export const liveNames = (live) => typeof live.fqdn === 'string' ? live.fqdn.split(',').filter(Boolean).map(bareName) : [];
+/**
+ * What an adopted entry changes on its live app: only a setting it declares
+ * that differs from live. The entry cannot tell a declared `branch`,
+ * `buildPack` or `autoDeploy` from its default, so those stay as they are; a
+ * `null` folder or port and an empty name list declare nothing. Never
+ * `custom_network_aliases`.
+ */
+export function adoptedAppPatch(entry, names, live) {
+    const patch = {};
+    const folderField = entry.buildPack === 'static' ? 'publish_directory' : 'base_directory';
+    if (entry.folder !== null && (live[folderField] ?? '/') !== `/${entry.folder}`) {
+        patch[folderField] = `/${entry.folder}`;
+    }
+    if (entry.port !== null &&
+        entry.buildPack !== 'static' &&
+        `${live.ports_exposes}` !== `${entry.port}`) {
+        patch.ports_exposes = String(entry.port);
+    }
+    if (names.length > 0 && [...names].sort().join() !== liveNames(live).sort().join()) {
+        patch.domains = names.join(',');
+    }
+    return patch;
+}
+/** One line per setting the patch changes, old value beside new. */
+export function adoptedPatchDetails(patch, live) {
+    return Object.entries(patch).map(([field, value]) => {
+        const old = field === 'domains' ? live.fqdn : live[field];
+        return `${field}: ${old ?? 'unset'} -> ${value}`;
+    });
+}
+/**
+ * The PATCH body that puts an app's snapshot settings back. A field is sent
+ * only when the entry's declaration would have changed it from the snapshot
+ * (`adoptedAppPatch`), so a setting foundry never touched, or a person edited
+ * later, stays. With no entry, a field is sent when `live` differs from the
+ * snapshot. Coolify reads `fqdn` but takes `domains`. A field the snapshot had
+ * as null is cleared the way the plain app path clears it: a folder back to
+ * `/`, domains to the empty list. A port is never cleared, as on that path.
+ */
+export function restoreAppPatch(entry, names, settings, live) {
+    const isStatic = (entry?.buildPack ?? settings.build_pack) === 'static';
+    const folderField = isStatic ? 'publish_directory' : 'base_directory';
+    const changed = new Set(Object.keys(entry ? adoptedAppPatch(entry, names, settings) : {}));
+    if (!entry) {
+        if ((live[folderField] ?? '/') !== (settings[folderField] ?? '/'))
+            changed.add(folderField);
+        if (`${live.ports_exposes}` !== `${settings.ports_exposes}`)
+            changed.add('ports_exposes');
+        if (liveNames(settings).sort().join() !== liveNames(live).sort().join())
+            changed.add('domains');
+    }
+    const patch = {};
+    if (changed.has(folderField))
+        patch[folderField] = settings[folderField] ?? '/';
+    if (changed.has('domains'))
+        patch.domains = settings.fqdn ?? '';
+    if (!isStatic && settings.ports_exposes != null && changed.has('ports_exposes')) {
+        patch.ports_exposes = settings.ports_exposes;
+    }
+    return patch;
+}
+const isWildcard = (route) => route.hostname?.startsWith('*') ?? false;
+const isCatchAll = (route) => route !== undefined && route.hostname === undefined && route.path === undefined;
+/** A hostname as compared: lower case, no trailing dot (DNS names ignore both). */
+export const normalizeHostname = (hostname) => hostname.toLowerCase().replace(/\.$/, '');
+const sameName = (a, b) => a !== undefined && normalizeHostname(a) === normalizeHostname(b);
+const hasName = (names, hostname) => hostname !== undefined && [...names].some((name) => sameName(hostname, name));
+/** The route foundry writes for a name: nothing but the hostname and the service. */
+const isFoundryRoute = (route, service) => route.service === service && Object.keys(route).length === 2;
+/** Puts `back` before the first wildcard or hostname-less route of `rest`, so a person's order stays. */
+function putBack(rest, back) {
+    const at = rest.findIndex((route) => route.hostname === undefined || isWildcard(route));
+    return at < 0 ? [...rest, ...back] : [...rest.slice(0, at), ...back, ...rest.slice(at)];
+}
+/** A live route foundry wrote for a name it dropped: written, no longer declared, exactly foundry's own. */
+const isDroppedRoute = (route, declared, service, written) => hasName(written, route.hostname) &&
+    !hasName(declared, route.hostname) &&
+    isFoundryRoute(route, service);
+/**
+ * What the merge leaves alone: every live route that is not for a declared
+ * name and not foundry's own route for a name it dropped. Whatever its shape:
+ * a hostname, only a `path`, or neither.
+ */
+export function foreignRoutes(live, declared, service, written) {
+    return live.filter((route) => !hasName(declared, route.hostname) && !isDroppedRoute(route, declared, service, written));
+}
+/** The declared names whose live routes the merge replaces: there are some, and they are not already foundry's one route. */
+export function replacedNames(live, declared, service) {
+    return declared.filter((hostname) => {
+        const same = live.filter((route) => sameName(route.hostname, hostname));
+        const [only] = same;
+        return only !== undefined && !(same.length === 1 && isFoundryRoute(only, service));
+    });
+}
+/** The names foundry removes from `live`: written, no longer declared, still its own route. */
+export const removedNames = (live, declared, service, written) => [
+    ...new Set(live
+        .filter((route) => isDroppedRoute(route, declared, service, written))
+        .map((route) => route.hostname)),
+];
+/**
+ * The ingress list an adopted tunnel gets (#312): the declared exact names,
+ * then every foreign live route in its live order and unchanged, with the
+ * snapshot's routes for a name foundry dropped put back among them, then the
+ * declared wildcards, then the live catch-all as it is. Only a live list that
+ * does not end in a catch-all gets `http_status:404`.
+ */
+export function mergeIngress(live, declared, service, written, snapshot) {
+    const dropped = removedNames(live, declared, service, written);
+    const tail = live.at(-1);
+    const foreign = foreignRoutes(live, declared, service, written);
+    const catchAll = isCatchAll(tail) ? tail : { service: 'http_status:404' };
+    const middle = isCatchAll(tail) ? foreign.slice(0, -1) : foreign;
+    const back = snapshot.filter((route) => hasName(dropped, route.hostname));
+    const route = (hostname) => ({ hostname, service });
+    return [
+        ...declared.filter((hostname) => !hostname.startsWith('*')).map(route),
+        ...putBack(middle, back),
+        ...declared.filter((hostname) => hostname.startsWith('*')).map(route),
+        catchAll,
+    ];
+}
+/**
+ * The ingress list restore writes (#312): the live list without foundry's own
+ * route for a name it wrote (`written` accumulates for the life of the
+ * snapshot), plus the snapshot's routes for that name. A name with no live
+ * route that is exactly foundry's is left alone, as is a route a person added
+ * or edited, and the live catch-all. The `http_status:404` foundry appended is
+ * removed only while it is still last and the snapshot had no catch-all; an
+ * empty snapshot keeps the live catch-all, or gets one.
+ */
+export function restoreIngress(live, snapshot, service, written) {
+    const isOurs = (route) => hasName(written, route.hostname) && isFoundryRoute(route, service);
+    const swapped = (route) => hasName(live.filter(isOurs).map((r) => r.hostname), route.hostname);
+    const appended = snapshot.length > 0 &&
+        !isCatchAll(snapshot.at(-1)) &&
+        isCatchAll(live.at(-1)) &&
+        live.at(-1)?.service === 'http_status:404';
+    const rest = live.filter((route, index) => !isOurs(route) && !(appended && index === live.length - 1));
+    const restored = putBack(rest, snapshot.filter(swapped));
+    return snapshot.length === 0 && !isCatchAll(restored.at(-1))
+        ? [...restored, { service: 'http_status:404' }]
+        : restored;
+}

package/dist/plan/adoption-vault.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Where an adoption keeps the secret part of its snapshot (#311): the live
+ * app's env values. The row in `foundry_adoptions` holds only the ref. Same
+ * shape as the `heldKeys` port (`../bootstrap/bootstrap.ts`).
+ */
+export interface AdoptionVault {
+    put(ref: string, value: string): Promise<void>;
+    resolve(ref: string): Promise<string | null>;
+}

package/dist/plan/adoption-vault.js

@@ -0,0 +1 @@
+export {};

package/dist/plan/agora.d.ts

@@ -24,6 +24,13 @@ export declare const AGORA_CLIENT_ID_SCOPE_KEY = "agora_client_id";
  * report).
  */
 export declare const APP_CLIENT_ID_SCOPE_KEY = "zitadel_app_client_id";
+/**
+ * An entry with `uses.auth` has its own client, recorded under
+ * `zitadel_app_client_id.<entry key>` (a scope key holds no `:`). Not a
+ * secret. The entry key is also the client's name in the org's project.
+ */
+export declare const ENTRY_CLIENT_ID_SCOPE_PREFIX = "zitadel_app_client_id.";
+export declare function entryClientIdScopeKey(entryKey: string): string;
 /**
  * #139: the `cms` app's own ZITADEL web client's `clientId`, recorded
  * separately from {@link APP_CLIENT_ID_SCOPE_KEY} -- that key belongs to the

package/dist/plan/agora.js

@@ -23,6 +23,15 @@ export const AGORA_CLIENT_ID_SCOPE_KEY = 'agora_client_id';
  * report).
  */
 export const APP_CLIENT_ID_SCOPE_KEY = 'zitadel_app_client_id';
+/**
+ * An entry with `uses.auth` has its own client, recorded under
+ * `zitadel_app_client_id.<entry key>` (a scope key holds no `:`). Not a
+ * secret. The entry key is also the client's name in the org's project.
+ */
+export const ENTRY_CLIENT_ID_SCOPE_PREFIX = `${APP_CLIENT_ID_SCOPE_KEY}.`;
+export function entryClientIdScopeKey(entryKey) {
+    return `${ENTRY_CLIENT_ID_SCOPE_PREFIX}${entryKey}`;
+}
 /**
  * #139: the `cms` app's own ZITADEL web client's `clientId`, recorded
  * separately from {@link APP_CLIENT_ID_SCOPE_KEY} -- that key belongs to the

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

@@ -0,0 +1,108 @@
+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: Pick<HostingEntry, 'key' | 'uses'>, 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<{
+        uuid?: string;
+        key: string;
+        value: string;
+        is_preview: boolean;
+        is_buildtime?: boolean;
+        is_literal?: boolean;
+        is_multiline?: 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/cloudflared-connector.d.ts

@@ -29,12 +29,20 @@ export interface EnsureCloudflaredConnectorInput {
     tunnelId: string;
     /** Fixed name, found before created -- so a second apply reuses this app rather than making a second one. */
     appName: string;
-    projectUuid: string;
-    environment: {
+    /** Needed to find the app by name or create it; an `adopted` connector needs neither. */
+    projectUuid?: string;
+    environment?: {
         id: number;
         name: string;
         uuid: string;
     };
+    /**
+     * #312: `recordedConnectorAppId` is a live app foundry adopted. It is never
+     * looked up by name or created; one that cannot be found is an error.
+     */
+    adopted?: boolean;
+    /** #312: called with the token just before `TUNNEL_TOKEN` is rewritten, so a later restore knows foundry wrote it. */
+    beforeTokenWrite?: (token: string) => Promise<void>;
     /** Called only when the app must be created -- never on the found-by-name or found-by-id paths. */
     resolveServer: () => Promise<{
         uuid: string;