@wtfalch/foundry 0.59.0 → 0.61.0

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

@@ -0,0 +1,235 @@
+import { companyGithubFor } from '../org.js';
+import { DeployKeysBlocked, deployKeysBlockedLine, sameSshKey, } from './github-deploy-keys.js';
+import { appStepKey } from './platform-diff.js';
+/**
+ * `uses.repo` (F12): the entry's app gets credentials for its own `entry.repo`. One `github:deploy-key` step per
+ * entry, keyed `<orgId>:<entry>`:
+ *
+ * 1. makes an ed25519 keypair and registers the public half on GitHub as a deploy key titled
+ *    `foundry <org slug> <entry key>`, read-only unless `access` is `write`;
+ * 2. holds the private half at {@link repoKeyRef} and records the key's GitHub id (`repo_key.<entry>`);
+ * 3. writes `GIT_REPO_URL` (`git@github.com:<owner>/<name>.git`) and `GIT_SSH_KEY` to the entry's env, restarts
+ *    the app, records `repo_key_applied.<entry>` last;
+ * 4. deletes every other key of that title (an older key after a change of access, or a key a failed run made).
+ *
+ * Halfway failures, and what the next apply does: a key made on GitHub whose private half was not held is found by
+ * its title and deleted, and another is made; a key held and on GitHub but not in the env is written; an env written
+ * and an old key not yet deleted is finished by step 4. No step leaves a key that nothing uses once an apply has
+ * run to its end. Removing the entry or `uses.repo` plans the same step in removal form: delete the recorded key and
+ * every key of the title, drop both env names, forget the held value, clear both markers.
+ *
+ * The private key reaches the held keys and the app's env and nothing else: not a plan, a log, a note, an error or a
+ * recorded id. A workspace copy (stage) is given none.
+ *
+ * Blocked, not failing (a plan line each): GitHub cannot be asked (no client wired), the credential is not held or
+ * lacks "Administration: Read and write" (the line names it and says it is William's step), no held key store that
+ * can put, the app is not recorded yet.
+ */
+export const GIT_REPO_URL_ENV = 'GIT_REPO_URL';
+export const GIT_SSH_KEY_ENV = 'GIT_SSH_KEY';
+/** What GitHub made for the entry: `{repo, id, access, pub}` as JSON. No secret. Cleared when the key is removed. */
+export const repoKeyScopeKey = (entryKey) => `repo_key.${entryKey}`;
+export const REPO_KEY_PREFIX = 'repo_key.';
+/** What the env was last written with (repo, access, key id); a change replans the step. */
+export const repoKeyAppliedScopeKey = (entryKey) => `repo_key_applied.${entryKey}`;
+/** The held-key ref of an entry's private key. */
+export const repoKeyRef = (orgId, entryKey) => `foundry:repo-key:${orgId}:${entryKey}`;
+/** GitHub's title for the entry's key. */
+export const repoKeyTitle = (org, entryKey) => `foundry ${org.slug} ${entryKey}`;
+/** `git@github.com:<owner>/<name>.git`. */
+export const repoGitUrl = (repo) => `git@github.com:${repo}.git`;
+export function parseRecordedRepoKey(value) {
+    if (!value)
+        return null;
+    try {
+        const v = JSON.parse(value);
+        if (typeof v.repo === 'string' &&
+            typeof v.id === 'number' &&
+            (v.access === 'read' || v.access === 'write') &&
+            typeof v.pub === 'string') {
+            return { repo: v.repo, id: v.id, access: v.access, pub: v.pub };
+        }
+    }
+    catch {
+        // Not ours: treated as not recorded.
+    }
+    return null;
+}
+export const repoKeyAppliedMarker = (repo, access, id) => JSON.stringify([repo, access, id]);
+/** The repo and, under the company's installation, its id. */
+export function repoKeyTarget(org, repo) {
+    const github = companyGithubFor(org.hosting, repo);
+    return github ? { repo, installationId: github.installationId } : { repo };
+}
+/**
+ * The entries that declare `uses.repo` with a repo, in declared order. An entry that is not live (`live: false`)
+ * has no app, so it counts as none: a key it had is removed, and made again when it goes live.
+ */
+export const repoKeyEntries = (org) => org.hosting.enabled
+    ? org.hosting.entries.filter((e) => e.uses?.repo && e.repo !== null && e.live !== false)
+    : [];
+/** Entry keys that were given a key and no longer declare `uses.repo` (or are gone, or hosting is off). */
+export function repoKeysToRemove(org, recorded) {
+    const wanted = new Set(repoKeyEntries(org).map((e) => e.key));
+    return Object.keys(recorded)
+        .filter((k) => k.startsWith(REPO_KEY_PREFIX) && recorded[k])
+        .map((k) => k.slice(REPO_KEY_PREFIX.length))
+        .filter((key) => !wanted.has(key));
+}
+/** Asks GitHub for the repo's deploy keys; a refusal or silence becomes a plain line. Never throws. */
+export async function probeRepoKeys(port, target) {
+    try {
+        return { ok: true, keys: await port.list(target) };
+    }
+    catch (error) {
+        const reason = error instanceof DeployKeysBlocked ? error.reason : 'unreachable';
+        return { ok: false, line: deployKeysBlockedLine(target, reason) };
+    }
+}
+/**
+ * One step per `uses.repo` entry whose key is not made, held and written yet (or is gone from GitHub, or has the
+ * wrong access), and one removal step per recorded key whose entry no longer declares it. Every other path says why
+ * in `blocked` (reported in `unmanaged`).
+ */
+export function planEntryRepoKeys(org, recorded, plannedSteps, readiness) {
+    const steps = [];
+    const blocked = [];
+    const reads = readiness.repoKeys;
+    const appPlanned = (stepKey) => plannedSteps.some((p) => p.action.system === 'coolify' && p.action.kind === 'app' && p.action.key === stepKey);
+    for (const entry of org.hosting.enabled ? org.hosting.entries : []) {
+        const use = entry.uses?.repo;
+        if (!use)
+            continue;
+        const stepKey = appStepKey(org, entry.key);
+        const key = `github:deploy-key:${stepKey}`;
+        const at = `${org.slug}'s ${entry.key} repo access`;
+        const note = (why) => blocked.push({ description: `${at} is not planned: ${why}`, key });
+        if (entry.repo === null) {
+            note('the entry has no repo');
+            continue;
+        }
+        if (entry.live === false) {
+            note('the entry is not live, so it has no app to give a key to; it gets one once it is live');
+            continue;
+        }
+        const rk = parseRecordedRepoKey(recorded[repoKeyScopeKey(entry.key)]);
+        const title = repoKeyTitle(org, entry.key);
+        const probe = reads?.probes[entry.key];
+        const inPlace = rk !== null &&
+            rk.repo === entry.repo &&
+            rk.access === use.access &&
+            recorded[repoKeyAppliedScopeKey(entry.key)] ===
+                repoKeyAppliedMarker(rk.repo, rk.access, rk.id);
+        const onGithub = inPlace &&
+            probe?.ok === true &&
+            probe.keys.some((k) => k.id === rk.id &&
+                k.title === title &&
+                k.readOnly === (use.access === 'read') &&
+                sameSshKey(k.key, rk.pub));
+        if (onGithub)
+            continue;
+        if (!reads?.store) {
+            note('the host gave no GitHub client for deploy keys');
+            continue;
+        }
+        if (probe && !probe.ok) {
+            if (inPlace) {
+                note(`its key is in place but GitHub could not be asked about it (${probe.line}); it is left as it is`);
+            }
+            else {
+                note(`GitHub cannot make its deploy key yet: ${probe.line}`);
+            }
+            continue;
+        }
+        if (!probe) {
+            note('GitHub was not asked about its deploy keys');
+            continue;
+        }
+        if (readiness.canHoldSecrets !== true) {
+            note("the host's held keys cannot hold the key's private half");
+            continue;
+        }
+        if (!recorded[`coolify:app:${stepKey}`] && !appPlanned(stepKey)) {
+            note("the entry's app is not recorded yet");
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'github',
+                kind: 'deploy-key',
+                key: stepKey,
+                desired: {
+                    repo: entry.repo,
+                    access: use.access,
+                    ...(companyGithubFor(org.hosting, entry.repo)
+                        ? { installationId: companyGithubFor(org.hosting, entry.repo)?.installationId }
+                        : {}),
+                },
+            },
+            step: {
+                description: `make a ${use.access === 'read' ? 'read-only' : 'read and write'} deploy key for ${entry.repo} as '${title}', hold its private half, write ${GIT_REPO_URL_ENV} and ${GIT_SSH_KEY_ENV} to ${org.slug}'s ${entry.key} env, restart the app`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    for (const entryKey of repoKeysToRemove(org, recorded)) {
+        const rk = parseRecordedRepoKey(recorded[repoKeyScopeKey(entryKey)]);
+        const stepKey = appStepKey(org, entryKey);
+        const key = `github:deploy-key:${stepKey}`;
+        const at = `${org.slug}'s ${entryKey} repo access`;
+        if (!rk) {
+            blocked.push({
+                description: `${at} is not removed: the recorded key '${repoKeyScopeKey(entryKey)}' is not readable, so its GitHub key id is unknown; delete the deploy key titled '${repoKeyTitle(org, entryKey)}' by hand and clear the record`,
+                key,
+            });
+            continue;
+        }
+        if (!reads?.store) {
+            blocked.push({
+                description: `${at} is not removed: the host gave no GitHub client for deploy keys, so key ${rk.id} on ${rk.repo} stays`,
+                key,
+            });
+            continue;
+        }
+        const probe = reads.probes[entryKey];
+        if (probe && !probe.ok) {
+            blocked.push({
+                description: `${at} is not removed: key ${rk.id} on ${rk.repo} stays because ${probe.line}`,
+                key,
+            });
+            continue;
+        }
+        steps.push({
+            action: {
+                system: 'github',
+                kind: 'deploy-key',
+                key: stepKey,
+                desired: { remove: true, repo: rk.repo },
+            },
+            step: {
+                description: `delete the deploy key ${rk.id} of ${rk.repo} made for ${org.slug}'s ${entryKey}, drop ${GIT_REPO_URL_ENV} and ${GIT_SSH_KEY_ENV}, forget the held private half`,
+                destroys: false,
+                migrates: false,
+            },
+        });
+    }
+    return { steps, blocked };
+}
+/** The entries whose repo GitHub should be asked about now: those that declare the flag and those with a key to remove. */
+export function repoKeyProbeTargets(org, recorded) {
+    const out = [];
+    for (const entry of repoKeyEntries(org)) {
+        if (!entry.repo)
+            continue;
+        out.push({ entryKey: entry.key, target: repoKeyTarget(org, entry.repo) });
+    }
+    for (const entryKey of repoKeysToRemove(org, recorded)) {
+        const rk = parseRecordedRepoKey(recorded[repoKeyScopeKey(entryKey)]);
+        if (rk)
+            out.push({ entryKey, target: repoKeyTarget(org, rk.repo) });
+    }
+    return out;
+}
+/** True when an entry of the org needs anything from GitHub: a key to make, check or remove. */
+export const repoKeysInPlay = (org, recorded) => repoKeyProbeTargets(org, recorded).length > 0;

package/dist/plan/entry-workspaces.d.ts

@@ -0,0 +1,55 @@
+import { type DeclaredOrg, type HostingEntry } from '../org.js';
+/**
+ * `uses.auth.workspaces`: the entry's own customers get workspaces in the broker. Foundry makes one key per
+ * entry, holds it, and gives it to two places: the app's env (`WORKSPACES_API_KEY`) and, as a sha256, the
+ * broker entry (`workspacesKey`). The broker never sees the key and the plan never holds it.
+ */
+/** The marker that the entry's key was put in the held-key store: its ref, never the key. */
+export declare const entryWorkspacesMintedScopeKey: (entryKey: string) => string;
+/** The held-key ref of an entry's workspaces key. At most 123 characters: a UUID and an entry key of up to 63. */
+export declare const workspacesKeyRef: (orgId: string, entryKey: string) => string;
+/** The broker's env that must be set before an entry may declare workspaces. */
+export declare const BROKER_WORKSPACES_DATABASE_ENV = "WORKSPACES_DATABASE_URL";
+/** The held ref of the connection string for the database of the broker the org's entries are written to. The operator makes the database and holds it here. */
+export declare const workspacesDatabaseRef: (org: Pick<DeclaredOrg, "slug" | "services">) => string;
+/** The key as the broker holds it: sha256, lowercase hex. */
+export declare const workspacesKeyHash: (key: string) => string;
+/** The broker's public base URL as an app reaches it: the company's login host, where the broker answers under `/api`. */
+export declare const workspacesUrl: (org: Pick<DeclaredOrg, "slug" | "domain" | "issuer">) => string;
+/**
+ * What the broker entry says about the entry's workspaces, or `null` until the entry has an address. The invite
+ * link is on the entry's first public host: an entry that is not live has none (`entryHostnames`) and no
+ * broker entry either, so the link never points at a private workspace address.
+ */
+export declare function wantedWorkspaces(org: DeclaredOrg, entry: HostingEntry): {
+    roles: string[];
+    inviteUrl: string;
+} | null;
+interface HeldKeys {
+    resolve(ref: string): Promise<string | null | undefined>;
+    put?(ref: string, value: string): Promise<void>;
+}
+/**
+ * The entry's key: read from the held keys, else made and held first. The held ref is recorded and persisted
+ * before the key goes anywhere else, so a crash after the `put` hands the same key out on the next apply. A
+ * ref that is recorded but no longer held stops here and mints nothing: a second key would leave the broker
+ * and the app disagreeing. Errors name the ref, never the key. `secret` registers the key for redaction.
+ */
+export declare function ensureWorkspacesKey(input: {
+    orgId: string;
+    slug: string;
+    entryKey: string;
+    heldKeys: HeldKeys | undefined;
+    recorded: () => Readonly<Record<string, string>>;
+    record: (key: string, value: string) => void;
+    persist: () => Promise<void>;
+    secret: (value: string) => void;
+}): Promise<string>;
+/** The key as already held, or an error that names the ref. The broker-entry step only reads; the app step made it. */
+export declare function heldWorkspacesKey(heldKeys: Pick<HeldKeys, 'resolve'> | undefined, org: Pick<DeclaredOrg, 'id' | 'slug'>, entryKey: string): Promise<string>;
+/**
+ * The connection string the operator holds at `ref` for the broker's workspaces database: `undefined` when
+ * nothing is held, an error naming the ref (never the value) when what is held is not a postgres URL.
+ */
+export declare function heldWorkspacesDatabase(heldKeys: Pick<HeldKeys, 'resolve'> | undefined, ref: string): Promise<string | undefined>;
+export {};

package/dist/plan/entry-workspaces.js

@@ -0,0 +1,90 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { ownsServices } from '../org.js';
+import { entryHostnames } from './hostnames.js';
+import { loginHostnameFor } from './login-host.js';
+import { orgTarget, platformTarget } from './own-services.js';
+/**
+ * `uses.auth.workspaces`: the entry's own customers get workspaces in the broker. Foundry makes one key per
+ * entry, holds it, and gives it to two places: the app's env (`WORKSPACES_API_KEY`) and, as a sha256, the
+ * broker entry (`workspacesKey`). The broker never sees the key and the plan never holds it.
+ */
+/** The marker that the entry's key was put in the held-key store: its ref, never the key. */
+export const entryWorkspacesMintedScopeKey = (entryKey) => `workspaces_key_minted.${entryKey}`;
+/** The held-key ref of an entry's workspaces key. At most 123 characters: a UUID and an entry key of up to 63. */
+export const workspacesKeyRef = (orgId, entryKey) => `foundry:workspaces-key:${orgId}:${entryKey}`;
+/** The broker's env that must be set before an entry may declare workspaces. */
+export const BROKER_WORKSPACES_DATABASE_ENV = 'WORKSPACES_DATABASE_URL';
+/** The held ref of the connection string for the database of the broker the org's entries are written to. The operator makes the database and holds it here. */
+export const workspacesDatabaseRef = (org) => (ownsServices(org) ? orgTarget(org) : platformTarget()).refs.brokerWorkspacesDatabase;
+/** The key as the broker holds it: sha256, lowercase hex. */
+export const workspacesKeyHash = (key) => createHash('sha256').update(key).digest('hex');
+/** The broker's public base URL as an app reaches it: the company's login host, where the broker answers under `/api`. */
+export const workspacesUrl = (org) => `https://${loginHostnameFor(org)}/api`;
+/**
+ * What the broker entry says about the entry's workspaces, or `null` until the entry has an address. The invite
+ * link is on the entry's first public host: an entry that is not live has none (`entryHostnames`) and no
+ * broker entry either, so the link never points at a private workspace address.
+ */
+export function wantedWorkspaces(org, entry) {
+    const workspaces = entry.uses?.auth?.workspaces;
+    const host = entryHostnames(org, entry)[0];
+    if (!workspaces || !host)
+        return null;
+    return { roles: [...workspaces.roles], inviteUrl: `https://${host}${workspaces.invitePath}` };
+}
+/**
+ * The entry's key: read from the held keys, else made and held first. The held ref is recorded and persisted
+ * before the key goes anywhere else, so a crash after the `put` hands the same key out on the next apply. A
+ * ref that is recorded but no longer held stops here and mints nothing: a second key would leave the broker
+ * and the app disagreeing. Errors name the ref, never the key. `secret` registers the key for redaction.
+ */
+export async function ensureWorkspacesKey(input) {
+    const ref = workspacesKeyRef(input.orgId, input.entryKey);
+    const at = `coolify:app for ${input.slug}`;
+    const held = await input.heldKeys?.resolve(ref);
+    if (held) {
+        input.secret(held);
+        return held;
+    }
+    if (input.recorded()[entryWorkspacesMintedScopeKey(input.entryKey)]) {
+        throw new Error(`${at}: the workspaces key of entry '${input.entryKey}' was made but is no longer held (ref ${ref}); restore the held value`);
+    }
+    if (typeof input.heldKeys?.put !== 'function') {
+        throw new Error(`${at}: the held keys cannot put the workspaces key of entry '${input.entryKey}'`);
+    }
+    const key = randomBytes(32).toString('base64url');
+    input.secret(key);
+    await input.heldKeys.put(ref, key);
+    input.record(entryWorkspacesMintedScopeKey(input.entryKey), ref);
+    await input.persist();
+    return key;
+}
+/** The key as already held, or an error that names the ref. The broker-entry step only reads; the app step made it. */
+export async function heldWorkspacesKey(heldKeys, org, entryKey) {
+    const ref = workspacesKeyRef(org.id, entryKey);
+    const key = await heldKeys?.resolve(ref);
+    if (!key) {
+        throw new Error(`coolify:broker-entry for ${org.slug}: the workspaces key of entry '${entryKey}' is not held yet (ref ${ref}); the app step makes it`);
+    }
+    return key;
+}
+/**
+ * The connection string the operator holds at `ref` for the broker's workspaces database: `undefined` when
+ * nothing is held, an error naming the ref (never the value) when what is held is not a postgres URL.
+ */
+export async function heldWorkspacesDatabase(heldKeys, ref) {
+    const value = await heldKeys?.resolve(ref);
+    if (!value)
+        return undefined;
+    let protocol = '';
+    try {
+        protocol = new URL(value).protocol;
+    }
+    catch {
+        protocol = '';
+    }
+    if (protocol !== 'postgres:' && protocol !== 'postgresql:') {
+        throw new Error(`the held key ${ref} is not a postgres:// connection string`);
+    }
+    return value;
+}