@wtfalch/foundry 0.41.2 → 0.43.0

package/dist/plan/remote-database.js

@@ -0,0 +1,373 @@
+import { pinnedRef } from '../bootstrap/versions.js';
+import { PRIMARY_SERVER_SCOPE_KEY, splitServers } from './blue-green.js';
+import { isNotFoundError } from './executor.js';
+import { appNameFor } from './platform-diff.js';
+/**
+ * A blue/green app on a server other than the database's reaches its one database through a
+ * Cloudflare tunnel TCP route behind an Access service token (William, 2026-10-15). The tunnel has a
+ * `tcp://<org>-db:5432` rule on an internal hostname; Access lets only the service token in; a
+ * `cloudflared access tcp` sidecar on each other server listens on 5432 under the name
+ * {@link remoteDatabaseHost}.
+ */
+export const REMOTE_DATABASE_PORT = 5432;
+const DELIVERY_ATTEMPTS = 3;
+/** The sidecar's name on the Docker network of `serverUuid`, or `null` on the database's own server. */
+export function remoteDatabaseHost(entryKey, serverUuid, primaryUuid) {
+    return serverUuid === primaryUuid ? null : `${entryKey}-db-access`;
+}
+/** The `host:port` a color on a server other than the database's connects to. */
+export const remoteDatabaseAddress = (host) => `${host}:${REMOTE_DATABASE_PORT}`;
+/**
+ * The facts for {@link planRemoteDatabase}, from what the planner already read. The zone is the one the org's
+ * tunnel names live in (`org.domain`); `access` says the host can reach Access, tunnels, DNS and zones.
+ */
+export function remoteDatabaseFactsFrom(input) {
+    const { up } = splitServers(input.servers);
+    return {
+        serverUuids: up,
+        primaryUuid: input.recorded[PRIMARY_SERVER_SCOPE_KEY] ?? up[0] ?? null,
+        zone: input.org.domain ?? null,
+        access: input.access,
+    };
+}
+/** The scope ids one entry's step keeps. None holds a secret. */
+export const remoteDatabaseKeys = (entryKey) => ({
+    /** The service token's id, from its mint until its secret reached every sidecar. No `:`. */
+    undelivered: `bgdb.${entryKey}.undelivered`,
+    /** The service token's id once delivered. */
+    token: `bgdb.${entryKey}.token`,
+    access: `bgdb.${entryKey}.access`,
+    route: `bgdb.${entryKey}.route`,
+    applied: `bgdb.${entryKey}.applied`,
+    sidecar: (serverUuid) => `bgdb.${entryKey}.sidecar.${serverUuid}`,
+});
+/** The tunnel's HTTP rules as the org tunnel step last wrote them (JSON), so a later write keeps them. */
+export const TUNNEL_HTTP_INGRESS_SCOPE_KEY = 'cloudflare_tunnel_http_ingress';
+const ROUTE_KEY = /^bgdb\.[^.:]+\.route$/;
+/** Every TCP route recorded for the org, in key order. */
+export function recordedTcpRoutes(recorded) {
+    const routes = [];
+    for (const key of Object.keys(recorded).sort()) {
+        if (!ROUTE_KEY.test(key) || !recorded[key])
+            continue;
+        try {
+            const parsed = JSON.parse(recorded[key]);
+            if (typeof parsed.hostname === 'string' && typeof parsed.service === 'string') {
+                routes.push({ hostname: parsed.hostname, service: parsed.service });
+            }
+        }
+        catch {
+            // A record that is not JSON is ignored; the next apply of the step writes it again.
+        }
+    }
+    return routes;
+}
+/** The HTTP rules recorded by the tunnel step, catch-all included; `[]` if none or unreadable. */
+export function recordedHttpIngress(recorded) {
+    try {
+        const parsed = JSON.parse(recorded[TUNNEL_HTTP_INGRESS_SCOPE_KEY] ?? '[]');
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * The tunnel's whole ingress: the TCP rules first (their names are exact), then every HTTP rule, the
+ * catch-all last. `putTunnelConfig` replaces the whole list, so every writer builds it through this.
+ */
+export function mergeTcpIngress(http, tcp) {
+    const names = new Set(tcp.map((r) => r.hostname));
+    const rules = http.filter((r) => !(r.hostname && names.has(r.hostname)));
+    const catchAll = rules.filter((r) => !r.hostname);
+    return [
+        ...tcp.map((r) => ({ hostname: r.hostname, service: r.service })),
+        ...rules.filter((r) => r.hostname),
+        ...(catchAll.length > 0 ? catchAll : [{ service: 'http_status:404' }]),
+    ];
+}
+/** The entry that gets a remote route: blue/green with the org's database. */
+function routedEntry(org) {
+    if (!org.hosting.enabled)
+        return undefined;
+    return org.hosting.entries.find((e) => e.database && e.blueGreen);
+}
+const appliedMarker = (d) => JSON.stringify({ hostname: d.hostname, database: d.database, servers: d.servers });
+/** Whether the route step has been applied for `serverUuid`: its marker names the server. */
+export function remoteDatabaseAppliedFor(recorded, entryKey, serverUuid) {
+    try {
+        const marker = JSON.parse(recorded[remoteDatabaseKeys(entryKey).applied] ?? 'null');
+        return Array.isArray(marker?.servers) && marker.servers.includes(serverUuid);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Plans the remote database route for the org's blue/green database entry. One server, or no facts,
+ * plans nothing. A missing zone, port, tunnel or primary is a blocked line (rule 2), and so is a token
+ * that was minted and never delivered (rule 1): it is never minted again.
+ */
+export function planRemoteDatabase(org, facts, recorded) {
+    const entry = routedEntry(org);
+    if (!entry || !facts || facts.serverUuids.length < 2)
+        return { step: null, blocked: null };
+    const key = `cloudflare:db-route:${org.id}`;
+    const block = (reason) => ({
+        step: null,
+        blocked: {
+            description: `${org.slug}'s remote database route for ${entry.key} is blocked, not planned: ${reason}`,
+            key,
+        },
+    });
+    const keys = remoteDatabaseKeys(entry.key);
+    const lost = recorded[keys.undelivered];
+    if (lost) {
+        return block(`its Access service token ${lost} was minted and its secret never reached every sidecar; delete the token in Cloudflare and clear the recorded id before minting again`);
+    }
+    if (!facts.access)
+        return block('the host supplies no Access, tunnel, DNS or zone port');
+    if (!facts.zone)
+        return block("the platform's edge has no internal zone");
+    if (!facts.primaryUuid)
+        return block('no primary server is recorded');
+    if (!recorded[`cloudflare:tunnel:${org.id}`]) {
+        return block(`${org.slug}'s Cloudflare tunnel is not applied yet`);
+    }
+    const database = recorded[`coolify:database:${org.id}`];
+    if (!database)
+        return block(`${org.slug}'s database is not applied yet`);
+    const app = appNameFor(org, entry);
+    const desired = {
+        entry: entry.key,
+        app,
+        hostname: `${app}-db.${facts.zone}`,
+        database,
+        primary: facts.primaryUuid,
+        servers: facts.serverUuids.filter((s) => s !== facts.primaryUuid).sort(),
+        zone: facts.zone,
+    };
+    // A server added after the token was minted gets its sidecar's secret copied from another sidecar;
+    // with no sidecar to copy from there is nothing to give it.
+    if (recorded[keys.token] && desired.servers.every((server) => !recorded[keys.sidecar(server)])) {
+        return block(`service token ${recorded[keys.token]} cannot be shown again and no sidecar holds it to copy; delete the token in Cloudflare and clear the recorded ids to mint it again`);
+    }
+    if (recorded[keys.applied] === appliedMarker(desired))
+        return { step: null, blocked: null };
+    return {
+        blocked: null,
+        step: {
+            action: {
+                system: 'cloudflare',
+                kind: 'db-route',
+                key: org.id,
+                desired: { ...desired },
+            },
+            step: {
+                description: `reach ${org.slug}'s database from ${desired.servers.length} other server(s) through a tunnel route behind an Access service token`,
+                destroys: false,
+                migrates: false,
+            },
+        },
+    };
+}
+/** The Dockerfile of the sidecar: the pinned `cloudflared`, listening on 5432 for the Access-protected route. */
+export function remoteDatabaseDockerfile(hostname) {
+    return [
+        `FROM cloudflare/cloudflared:${pinnedRef('cloudflared')}`,
+        `CMD ["access", "tcp", "--hostname", "${hostname}", "--url", "0.0.0.0:${REMOTE_DATABASE_PORT}"]`,
+        // The image is distroless (no shell, no nc): the exec-form check proves only that the binary runs.
+        'HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 CMD ["cloudflared", "version"]',
+        '',
+    ].join('\n');
+}
+const TOKEN_ID_ENV = 'TUNNEL_SERVICE_TOKEN_ID';
+const TOKEN_SECRET_ENV = 'TUNNEL_SERVICE_TOKEN_SECRET';
+/**
+ * Applies one entry's route. The Access app and its service-token policy come first, so the tunnel route
+ * and the DNS record never exist without the gate in front of them. The service token is minted once
+ * (rule 1): its id is recorded and persisted before delivery, the secret goes only to the sidecars' env
+ * (rule 6), the delivered id replaces it, and the applied marker is the last write. A failure halfway
+ * leaves a repair for the next run: the Access app, sidecars, route and DNS are found again; a minted
+ * token is never minted again. A sidecar made after the mint takes its secret from an existing sidecar's
+ * env. Every outside call is bounded by the ports' own timeouts (edge SDK and Coolify client).
+ */
+export async function applyRemoteDatabase(deps, run) {
+    const { desired, org } = run;
+    const keys = remoteDatabaseKeys(desired.entry);
+    const tunnelId = run.recorded()[`cloudflare:tunnel:${org.id}`];
+    if (!tunnelId)
+        throw new Error(`remote database for ${org.slug}: the Cloudflare tunnel is not applied`);
+    const zone = await deps.zones.findZoneByApex(desired.zone);
+    if (!zone)
+        throw new Error(`remote database for ${org.slug}: zone ${desired.zone} is not live`);
+    let accessAppId = run.recorded()[keys.access];
+    if (!accessAppId) {
+        const live = (await deps.access.listAccessApps()).find((a) => a.domain === desired.hostname);
+        accessAppId = (live ??
+            (await deps.access.createAccessApp({
+                name: `${desired.app}-db-access`,
+                domain: desired.hostname,
+                type: 'self_hosted',
+            }))).id;
+        run.record(keys.access, accessAppId);
+        await run.persist();
+    }
+    // Sidecars exist before the secret does, so the secret has somewhere to go the moment it is minted.
+    const { environment } = await deps.coolify.findOrCreateEnvironment(run.projectUuid, 'production');
+    const sidecars = [];
+    for (const server of desired.servers) {
+        const host = remoteDatabaseHost(desired.app, server, desired.primary);
+        if (!host)
+            continue;
+        const recordedId = run.recorded()[keys.sidecar(server)];
+        let appId = null;
+        if (recordedId) {
+            try {
+                await deps.coolify.getApplication(recordedId);
+                appId = recordedId;
+            }
+            catch (error) {
+                if (!isNotFoundError(error))
+                    throw error;
+            }
+        }
+        let fresh = false;
+        if (!appId) {
+            const created = await deps.coolify.createDockerfileApplication({
+                project_uuid: run.projectUuid,
+                server_uuid: server,
+                environment_name: environment.name,
+                environment_uuid: environment.uuid,
+                dockerfile: remoteDatabaseDockerfile(desired.hostname),
+                name: host,
+                description: `cloudflared access sidecar: ${org.slug}'s database over the tunnel`,
+                instant_deploy: false,
+                autogenerate_domain: false,
+            });
+            appId = created.uuid;
+            fresh = true;
+            // The internal name is what `<app>-db-access` resolves to on the server's Docker network.
+            await deps.coolify.updateApplication(appId, {
+                custom_internal_name: host,
+                health_check_enabled: false,
+            });
+            run.record(keys.sidecar(server), appId);
+            await run.persist();
+        }
+        sidecars.push({ server, appId, fresh });
+    }
+    // The token: found by recorded id first. A token of the name that foundry has no id for is not
+    // minted over; the step fails with fixed text.
+    const lost = run.recorded()[keys.undelivered];
+    if (lost) {
+        throw new Error(`remote database for ${org.slug}: service token ${lost} was minted and not delivered; delete it in Cloudflare and clear the recorded id before minting again`);
+    }
+    let tokenId = run.recorded()[keys.token];
+    let secrets = null;
+    let deliverTo = sidecars;
+    if (!tokenId) {
+        const name = `${desired.app}-db-access`;
+        if (await deps.access.findServiceTokenByName(name)) {
+            throw new Error(`remote database for ${org.slug}: a service token named ${name} exists and foundry holds no id for it; delete it in Cloudflare before applying again`);
+        }
+        const minted = await deps.access.createServiceToken(name);
+        deps.secret(minted.clientSecret);
+        deps.secret(minted.clientId);
+        run.record(keys.undelivered, minted.id);
+        await run.persist();
+        tokenId = minted.id;
+        secrets = { clientId: minted.clientId, clientSecret: minted.clientSecret };
+    }
+    else {
+        // A sidecar made after the token was minted takes the secret from a sidecar that already holds it.
+        deliverTo = sidecars.filter((sidecar) => sidecar.fresh);
+        if (deliverTo.length > 0) {
+            secrets = await secretsOf(deps, sidecars.filter((sidecar) => !sidecar.fresh));
+            if (!secrets) {
+                throw new Error(`remote database for ${org.slug}: the sidecar on server ${deliverTo[0]?.server} is new and no existing sidecar holds service token ${tokenId} to copy; delete the token in Cloudflare and clear the recorded ids to mint it again`);
+            }
+        }
+    }
+    if (secrets) {
+        const failed = [];
+        for (const sidecar of deliverTo) {
+            if (!(await deliver(deps, sidecar.appId, secrets)))
+                failed.push(sidecar.server);
+        }
+        if (failed.length > 0) {
+            // Ids only: the cause of a failed write can echo the request body.
+            throw new Error(`remote database for ${org.slug}: service token ${tokenId} could not be delivered to the sidecar on server ${failed.join(', ')} after ${DELIVERY_ATTEMPTS} attempts; delete the token in Cloudflare and clear the recorded id before minting again`);
+        }
+        if (run.recorded()[keys.undelivered]) {
+            run.record(keys.token, tokenId);
+            run.record(keys.undelivered, '');
+            await run.persist();
+        }
+    }
+    const policies = await deps.access.listAccessPolicies(accessAppId);
+    const hasPolicy = policies.some((p) => p.decision === 'non_identity' &&
+        (p.include ?? []).some((r) => r.service_token?.token_id === tokenId));
+    if (!hasPolicy) {
+        await deps.access.createAccessPolicy(accessAppId, {
+            name: 'database sidecars',
+            decision: 'non_identity',
+            include: [{ service_token: { token_id: tokenId } }],
+        });
+    }
+    // The gate exists: now the route and the name that reach the database.
+    run.record(keys.route, JSON.stringify({
+        hostname: desired.hostname,
+        service: `tcp://${run.databaseHost}:${REMOTE_DATABASE_PORT}`,
+    }));
+    await deps.tunnels.putTunnelConfig(tunnelId, {
+        ingress: mergeTcpIngress(recordedHttpIngress(run.recorded()), recordedTcpRoutes(run.recorded())),
+    });
+    if ((await deps.dns.findDnsRecord(zone.name, desired.hostname, 'CNAME')).length === 0) {
+        await deps.dns.createDnsRecord(zone.name, {
+            type: 'CNAME',
+            name: desired.hostname,
+            content: `${tunnelId}.cfargotunnel.com`,
+            proxied: true,
+        });
+    }
+    for (const sidecar of sidecars) {
+        const live = await deps.coolify.getApplication(sidecar.appId);
+        const up = Boolean(live.status?.startsWith('running') || live.status?.startsWith('starting'));
+        if (secrets || sidecar.fresh || !up)
+            await deps.coolify.deploy(sidecar.appId);
+    }
+    run.record(keys.applied, appliedMarker(desired));
+    await run.persist();
+}
+/** The service token an existing sidecar already holds in its env, registered for redaction; `null` when none does. */
+async function secretsOf(deps, sidecars) {
+    for (const sidecar of sidecars) {
+        const envs = await deps.coolify.listEnvs(sidecar.appId);
+        const envValue = (key) => envs.find((e) => e.key === key && !e.is_preview)?.value;
+        const clientId = envValue(TOKEN_ID_ENV);
+        const clientSecret = envValue(TOKEN_SECRET_ENV);
+        if (clientId && clientSecret) {
+            deps.secret(clientId);
+            deps.secret(clientSecret);
+            return { clientId, clientSecret };
+        }
+    }
+    return null;
+}
+/** Writes the token to one sidecar's env, up to {@link DELIVERY_ATTEMPTS} times; the error is dropped. */
+async function deliver(deps, appId, secrets) {
+    for (let attempt = 1; attempt <= DELIVERY_ATTEMPTS; attempt++) {
+        try {
+            await deps.coolify.bulkUpsertEnvs(appId, [
+                { key: TOKEN_ID_ENV, value: secrets.clientId, literal: true },
+                { key: TOKEN_SECRET_ENV, value: secrets.clientSecret, literal: true },
+            ]);
+            return true;
+        }
+        catch {
+            // Retried; the error is dropped in case it echoes the secret.
+        }
+    }
+    return false;
+}

package/dist/plan/sign-in-archon.d.ts

@@ -0,0 +1,46 @@
+import type { CoolifyPort, ZitadelPort } from './executor.js';
+/**
+ * Archon in-app sign-in: Archon signs people in on its own address under `/sign-in`, through the owner
+ * company's in-app login app. Its sign-in client lives in the owner company's ZITADEL, in Archon's own
+ * organisation, so this is the platform's step and not the company's login-host step.
+ */
+/** Recorded `<host>=<clientId>` once Archon's address is trusted, bound, proxied by the app and pointed at; `''` once given up again, in the reverse order. */
+export declare const PLATFORM_ARCHON_IN_APP_SCOPE_KEY = "platform_archon_in_app";
+/** The host a recorded {@link PLATFORM_ARCHON_IN_APP_SCOPE_KEY} names; `''` when none. */
+export declare function archonInAppHost(recorded: Readonly<Record<string, string>>): string;
+/** The ZITADEL calls Archon's in-app sign-in makes, on the owner company's own instance. */
+export type ArchonInAppZitadel = Pick<ZitadelPort, 'ensureTrustedDomain' | 'deleteTrustedDomain' | 'updateOidcAppLoginBaseUri'> & Partial<Pick<ZitadelPort, 'allowPerAppLoginBaseUri'>>;
+interface ArchonInAppInput {
+    zitadel: ArchonInAppZitadel;
+    coolify: Pick<CoolifyPort, 'listEnvs' | 'bulkUpsertEnvs' | 'deploy'>;
+    /** The owner company's in-app login app, whose host table holds Archon's binding. Giving the address up without it leaves no table to edit. */
+    loginAppId?: string;
+    /** The owner company's login host, the instance's own: Archon's default base URI. */
+    loginHost: string;
+    /** Archon's address. */
+    host: string;
+    /** Archon's ZITADEL organisation, project and sign-in client (app id and client id). */
+    organisationId: string;
+    projectId: string;
+    appId: string;
+}
+/**
+ * Archon's address becomes one the login serves, in two halves with the app's own env between them
+ * (`SIGNIN_UPSTREAM`, written and deployed by the step): first trusted in the company's ZITADEL and bound
+ * to Archon's organisation and client in the in-app login's host table; only after the app proxies
+ * `/sign-in/*`, the client's Login V2 base URI is set to the address ({@link archonInAppPoint}).
+ */
+export declare function archonInAppBind(input: ArchonInAppInput & {
+    clientId: string;
+    loginAppId: string;
+}): Promise<void>;
+/** Sets the client's Login V2 base URI to Archon's address. Only after the app proxies `/sign-in/*`. */
+export declare function archonInAppPoint(input: ArchonInAppInput): Promise<void>;
+/** First half of giving the address up: the client goes back to the company's login host. */
+export declare function archonInAppBack(input: ArchonInAppInput): Promise<void>;
+/**
+ * Last half: the binding and the trusted domain are removed, after the app stopped proxying. A domain or
+ * binding already gone counts as done.
+ */
+export declare function archonInAppUnbind(input: ArchonInAppInput): Promise<void>;
+export {};

package/dist/plan/sign-in-archon.js

@@ -0,0 +1,71 @@
+import { isNotFoundError, setOidcAppLoginBaseUri } from './executor.js';
+import { editSignInBindings } from './sign-in-bindings.js';
+import { SIGN_IN_BASE_PATH } from './sign-in.js';
+/**
+ * Archon in-app sign-in: Archon signs people in on its own address under `/sign-in`, through the owner
+ * company's in-app login app. Its sign-in client lives in the owner company's ZITADEL, in Archon's own
+ * organisation, so this is the platform's step and not the company's login-host step.
+ */
+/** Recorded `<host>=<clientId>` once Archon's address is trusted, bound, proxied by the app and pointed at; `''` once given up again, in the reverse order. */
+export const PLATFORM_ARCHON_IN_APP_SCOPE_KEY = 'platform_archon_in_app';
+/** The host a recorded {@link PLATFORM_ARCHON_IN_APP_SCOPE_KEY} names; `''` when none. */
+export function archonInAppHost(recorded) {
+    return (recorded[PLATFORM_ARCHON_IN_APP_SCOPE_KEY] ?? '').split('=')[0] ?? '';
+}
+/**
+ * Archon's address becomes one the login serves, in two halves with the app's own env between them
+ * (`SIGNIN_UPSTREAM`, written and deployed by the step): first trusted in the company's ZITADEL and bound
+ * to Archon's organisation and client in the in-app login's host table; only after the app proxies
+ * `/sign-in/*`, the client's Login V2 base URI is set to the address ({@link archonInAppPoint}).
+ */
+export async function archonInAppBind(input) {
+    const { zitadel, host } = input;
+    await zitadel.ensureTrustedDomain(host);
+    await editSignInBindings(input.coolify, {
+        appId: input.loginAppId,
+        instanceHost: input.loginHost,
+        upsert: [
+            {
+                host,
+                organizationId: input.organisationId,
+                clientIds: [input.clientId],
+                apps: { [input.clientId]: 'archon' },
+                basePath: SIGN_IN_BASE_PATH,
+            },
+        ],
+    });
+}
+/** Sets the client's Login V2 base URI to Archon's address. Only after the app proxies `/sign-in/*`. */
+export async function archonInAppPoint(input) {
+    const { zitadel, host } = input;
+    if (!zitadel.allowPerAppLoginBaseUri) {
+        throw new Error("platform:archon: the owner company's ZITADEL port cannot allow a per-app login base URI, so Archon cannot sign in on its own address");
+    }
+    await zitadel.allowPerAppLoginBaseUri(`https://${input.loginHost}/`);
+    await setOidcAppLoginBaseUri(zitadel, input.organisationId, input.projectId, input.appId, `https://${host}${SIGN_IN_BASE_PATH}/`);
+}
+/** First half of giving the address up: the client goes back to the company's login host. */
+export async function archonInAppBack(input) {
+    await setOidcAppLoginBaseUri(input.zitadel, input.organisationId, input.projectId, input.appId, `https://${input.loginHost}/`);
+}
+/**
+ * Last half: the binding and the trusted domain are removed, after the app stopped proxying. A domain or
+ * binding already gone counts as done.
+ */
+export async function archonInAppUnbind(input) {
+    const { zitadel, host } = input;
+    if (input.loginAppId) {
+        await editSignInBindings(input.coolify, {
+            appId: input.loginAppId,
+            instanceHost: input.loginHost,
+            remove: [host],
+        });
+    }
+    try {
+        await zitadel.deleteTrustedDomain(host);
+    }
+    catch (error) {
+        if (!isNotFoundError(error))
+            throw error;
+    }
+}

package/dist/plan/sign-in-bindings.d.ts

@@ -0,0 +1,16 @@
+import type { CoolifyPort } from './executor.js';
+import type { LoginHostBinding } from './login-host.js';
+/** The login's host table env, and the document it holds (`auth/docs/company-login-hosts.md`). */
+export declare const LOGIN_HOST_BINDINGS_ENV = "LOGIN_HOST_BINDINGS";
+/**
+ * Adds, replaces and removes hosts in the host table of one in-app login app, then redeploys it when the
+ * document changed. Hosts not named stay as they are, so two steps that each own some hosts (the
+ * company's login-host step, Archon's step) never undo each other. Entries are sorted by host and the
+ * document is written compact, so a repeat writes the same text and deploys nothing.
+ */
+export declare function editSignInBindings(coolify: Pick<CoolifyPort, 'listEnvs' | 'bulkUpsertEnvs' | 'deploy'>, input: {
+    appId: string;
+    instanceHost: string;
+    upsert?: readonly LoginHostBinding[];
+    remove?: readonly string[];
+}): Promise<void>;

package/dist/plan/sign-in-bindings.js

@@ -0,0 +1,44 @@
+/** The login's host table env, and the document it holds (`auth/docs/company-login-hosts.md`). */
+export const LOGIN_HOST_BINDINGS_ENV = 'LOGIN_HOST_BINDINGS';
+/**
+ * The host table on a company's in-app login app. The company's own login stack has none of its own:
+ * its login host is the instance host, every in-app host is a binding. Parsed with a fixed error that
+ * never echoes the live value.
+ */
+function readDoc(raw, instanceHost, appId) {
+    if (!raw)
+        return { version: 1, instanceHost, sharedHosts: [instanceHost], bindings: [] };
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${LOGIN_HOST_BINDINGS_ENV} on app ${appId} is not JSON; left as it is`);
+    }
+    const d = doc;
+    if (!d || d.version !== 1 || !Array.isArray(d.bindings) || !Array.isArray(d.sharedHosts)) {
+        throw new Error(`${LOGIN_HOST_BINDINGS_ENV} on app ${appId} has an unknown shape; left as it is`);
+    }
+    return d;
+}
+/**
+ * Adds, replaces and removes hosts in the host table of one in-app login app, then redeploys it when the
+ * document changed. Hosts not named stay as they are, so two steps that each own some hosts (the
+ * company's login-host step, Archon's step) never undo each other. Entries are sorted by host and the
+ * document is written compact, so a repeat writes the same text and deploys nothing.
+ */
+export async function editSignInBindings(coolify, input) {
+    const { appId, instanceHost } = input;
+    const live = (await coolify.listEnvs(appId)).find((e) => e.key === LOGIN_HOST_BINDINGS_ENV && !e.is_preview);
+    const doc = readDoc(live?.value || undefined, instanceHost, appId);
+    const touched = new Set([...(input.upsert ?? []).map((b) => b.host), ...(input.remove ?? [])]);
+    doc.bindings = [
+        ...doc.bindings.filter((b) => !touched.has(b.host)),
+        ...(input.upsert ?? []).map((b) => ({ ...b, clientIds: [...b.clientIds].sort() })),
+    ].sort((a, b) => (a.host < b.host ? -1 : 1));
+    const next = JSON.stringify(doc);
+    if (live?.value === next)
+        return;
+    await coolify.bulkUpsertEnvs(appId, [{ key: LOGIN_HOST_BINDINGS_ENV, value: next }]);
+    await coolify.deploy(appId);
+}