@wtfalch/foundry 0.60.0 → 0.61.0

package/dist/plan/gates.d.ts

@@ -36,7 +36,7 @@ export declare function isBehindGate(org: DeclaredOrg, hostname: string): boolea
  * owner with an email: when one is missing no create is planned and
  * `blocked` says why (CLAUDE.md rule 2).
  */
-export declare function planGates(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, providerId: string | null): {
+export declare function planGates(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, providerId: string | null, declaredOrg?: DeclaredOrg): {
     steps: DraftStep[];
     blocked: string | null;
 };

package/dist/plan/gates.js

@@ -1,6 +1,9 @@
 import { ZITADEL_ORG_SCOPE_KEY } from './agora.js';
+import { workspaceHost, workspaceInboxHost } from './hostnames.js';
 import { lockedHostnames } from './locked-hostnames.js';
 import { appStepKey } from './platform-diff.js';
+import { privatePageGates } from './private-pages.js';
+import { INBOX_GATE_KEY, companyPeople, gatePeopleScopeKey, hasInbox, isServerWorkspace, peopleHash, workspaceEntries, workspaceGateKey, workspacePeople, } from './workspace.js';
 /**
  * A company's declared gates (`HostingEntry.gates`) as Cloudflare Access gates
  * made through edge. Foundry sets who passes once, on create, from the
@@ -25,8 +28,8 @@ export function resolveGateHostnames(domain, names) {
         .map((name) => (name === '@' ? domain : name === '*' ? `*.${domain}` : `${name}.${domain}`))
         .sort();
 }
-/** Every declared gate's key with its entry's key and resolved hostnames; none without hosting or a domain. */
-function declaredGates(org) {
+/** Every gate an entry declares on its own hostnames, by key; none without hosting or a domain. */
+function entryGates(org) {
     const gates = new Map();
     if (!org.hosting.enabled || !org.domain)
         return gates;
@@ -40,9 +43,34 @@ function declaredGates(org) {
     }
     return gates;
 }
+/**
+ * The entry gates, the private page gates (`private-pages.ts`) and one gate per workspace (`ws-<entry key>`, over the workspace host, whose people are the
+ * company's and the entry's testers). Workspaces are read from `declared`, the org with its dark entries.
+ */
+function declaredGates(org, declared) {
+    const gates = entryGates(org);
+    for (const entry of workspaceEntries(declared)) {
+        gates.set(workspaceGateKey(entry.key), {
+            entry: entry.key,
+            hostnames: [workspaceHost(declared.slug, entry.key)],
+            people: workspacePeople(declared, entry),
+        });
+    }
+    const first = workspaceEntries(declared).find(isServerWorkspace);
+    if (first && hasInbox(declared)) {
+        gates.set(INBOX_GATE_KEY, {
+            entry: first.key,
+            hostnames: [workspaceInboxHost(declared.slug)],
+            people: companyPeople(declared),
+        });
+    }
+    for (const [key, gate] of privatePageGates(org, declared))
+        gates.set(key, gate);
+    return gates;
+}
 /** True when a declared gate resolves to `*.<domain>`. */
 export function hasWildcardGate(org) {
-    return [...declaredGates(org).values()].some(({ hostnames }) => hostnames.some((name) => name.startsWith('*.')));
+    return [...entryGates(org).values()].some(({ hostnames }) => hostnames.some((name) => name.startsWith('*.')));
 }
 /**
  * True when a declared gate covers `hostname`, exactly or through a gated
@@ -55,7 +83,7 @@ export function isBehindGate(org, hostname) {
     if ((org.hosting.access ?? []).some((r) => r.kind === 'bypass' && r.hostname === hostname)) {
         return false;
     }
-    return [...declaredGates(org).values()].some(({ hostnames }) => hostnames.some((name) => name.startsWith('*.') ? hostname.endsWith(name.slice(1)) : name === hostname));
+    return [...entryGates(org).values()].some(({ hostnames }) => hostnames.some((name) => name.startsWith('*.') ? hostname.endsWith(name.slice(1)) : name === hostname));
 }
 /**
  * One step per declared gate whose recorded id or hostnames differ from what
@@ -65,7 +93,7 @@ export function isBehindGate(org, hostname) {
  * owner with an email: when one is missing no create is planned and
  * `blocked` says why (CLAUDE.md rule 2).
  */
-export function planGates(org, recordedIds, providerId) {
+export function planGates(org, recordedIds, providerId, declaredOrg = org) {
     const steps = [];
     let blocked = null;
     const missing = !providerId
@@ -75,7 +103,7 @@ export function planGates(org, recordedIds, providerId) {
             : org.owners.length === 0
                 ? `${org.slug} declares no owner with an email, and a gate nobody can pass is a mistake`
                 : null;
-    const declared = declaredGates(org);
+    const declared = declaredGates(org, declaredOrg);
     const prefix = gateIdRecordKey(org.id, '');
     for (const [name, id] of Object.entries(recordedIds)) {
         if (!id || !name.startsWith(prefix))
@@ -97,11 +125,30 @@ export function planGates(org, recordedIds, providerId) {
             },
         });
     }
-    for (const [gateKey, { entry, hostnames }] of declared) {
+    for (const [gateKey, { entry, hostnames, people }] of declared) {
         const recorded = recordedIds[gateIdRecordKey(org.id, gateKey)];
-        if (recorded && recordedIds[gateHostnamesScopeKey(gateKey)] === JSON.stringify(hostnames)) {
+        const hostnamesSame = Boolean(recorded) &&
+            recordedIds[gateHostnamesScopeKey(gateKey)] === JSON.stringify(hostnames);
+        if (hostnamesSame && people) {
+            if (recordedIds[gatePeopleScopeKey(gateKey)] !== peopleHash(people)) {
+                steps.push({
+                    action: {
+                        system: 'cloudflare',
+                        kind: 'gate',
+                        key: appStepKey(org, gateKey),
+                        desired: { mode: 'people', entry, emails: people },
+                    },
+                    step: {
+                        description: `change who may open ${org.slug}'s '${gateKey}' Cloudflare Access gate to ${people.length} people`,
+                        destroys: false,
+                        migrates: false,
+                    },
+                });
+            }
             continue;
         }
+        if (hostnamesSame)
+            continue;
         if (!recorded && missing) {
             blocked = missing;
             continue;
@@ -111,7 +158,13 @@ export function planGates(org, recordedIds, providerId) {
                 system: 'cloudflare',
                 kind: 'gate',
                 key: appStepKey(org, gateKey),
-                desired: { mode: 'apply', entry, hostnames, providerId },
+                desired: {
+                    mode: 'apply',
+                    entry,
+                    hostnames,
+                    providerId,
+                    ...(people ? { emails: people } : {}),
+                },
             },
             step: {
                 description: recorded

package/dist/plan/github-deploy-keys.d.ts

@@ -0,0 +1,78 @@
+/**
+ * F12: GitHub deploy keys for an entry's own repo, and the ed25519 keypair behind one.
+ *
+ * Which GitHub credential makes the key:
+ * - a repo under the company's installation (`hosting.github`): an installation token of the platform GitHub App
+ *   (`PLATFORM_GITHUB_APP_REFS`), asked for `administration: write` on that one repo;
+ * - a repo under `wtfalch`: the same App's installation on that account, found with `GET /orgs/<owner>/installation`
+ *   (cached for the life of the client) and asked for the same token.
+ * Both need the repository permission "Administration: Read and write"; creating a deploy key, even a read-only
+ * one, is refused without it. Neither is documented to hold it today, so a refusal is a plain blocked line, not a
+ * failure.
+ */
+/** Every GitHub call is cut off after this long. */
+export declare const GITHUB_DEPLOY_KEYS_TIMEOUT_MS = 20000;
+/** A repo and, for one under the company's installation, that installation's id. */
+export interface DeployKeyTarget {
+    /** `<owner>/<name>`. */
+    repo: string;
+    installationId?: number;
+}
+/** What GitHub says about a deploy key. */
+export interface GithubDeployKey {
+    id: number;
+    title: string;
+    /** `ssh-ed25519 <base64>` (GitHub drops any comment). */
+    key: string;
+    readOnly: boolean;
+}
+export interface GithubDeployKeysPort {
+    list(target: DeployKeyTarget): Promise<GithubDeployKey[]>;
+    create(target: DeployKeyTarget, key: {
+        title: string;
+        key: string;
+        readOnly: boolean;
+    }): Promise<GithubDeployKey>;
+    /** A key that is already gone counts as deleted. */
+    remove(target: DeployKeyTarget, id: number): Promise<void>;
+}
+/** Why foundry cannot make deploy keys for a repo. The text is plain and fixed; it holds no credential. */
+export declare class DeployKeysBlocked extends Error {
+    readonly reason: 'no-credential' | 'permission' | 'unreachable';
+    constructor(reason: 'no-credential' | 'permission' | 'unreachable', message: string);
+}
+/** The line for a blocked repo: what is missing, and whose step it is. */
+export declare function deployKeysBlockedLine(target: DeployKeyTarget, reason: DeployKeysBlocked['reason']): string;
+/** A 9-minute RS256 JWT for the App, as GitHub asks for before an installation token. */
+export declare function githubAppJwt(appId: string, privateKeyPem: string, nowMs: number): string;
+export interface GithubDeployKeysOptions {
+    heldKeys: {
+        resolve(ref: string): Promise<string | null | undefined>;
+    };
+    /** Global fetch by default; tests give their own. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    now?: () => number;
+    /** Told of every token before it is used, so the host can scrub it from logs and audit rows. */
+    onSecret?: (value: string) => void;
+}
+/**
+ * The GitHub REST deploy-key calls over `fetchImpl`, a timeout on each. Errors are fixed text: never a token, a key
+ * or a response body. A 401, 403, 404 or 422 from the credential or the key call is a {@link DeployKeysBlocked}
+ * `permission`; no answer is `unreachable`.
+ */
+export declare function createGithubDeployKeys(options: GithubDeployKeysOptions): GithubDeployKeysPort;
+/** The OpenSSH public key line (`ssh-ed25519 <base64>`) and private key file text of a fresh ed25519 pair. */
+export interface RepoKeyPair {
+    publicKey: string;
+    privateKey: string;
+}
+/** A new ed25519 keypair; the private key is an unencrypted `-----BEGIN OPENSSH PRIVATE KEY-----` file, as ssh and git read it. */
+export declare function generateRepoKeyPair(): RepoKeyPair;
+/**
+ * The public key line (`ssh-ed25519 <base64>`) inside an unencrypted OpenSSH private key file, or `null` when the
+ * text is not one (so a held value that is not a usable key is replaced, not trusted).
+ */
+export declare function publicKeyOfPrivate(privateKey: string): string | null;
+/** True when two `type base64` lines name the same key (a trailing comment is ignored). */
+export declare const sameSshKey: (a: string, b: string) => boolean;

package/dist/plan/github-deploy-keys.js

@@ -0,0 +1,305 @@
+import { createSign, generateKeyPairSync } from 'node:crypto';
+import { PLATFORM_GITHUB_APP_REFS } from './held-key-refs.js';
+/**
+ * F12: GitHub deploy keys for an entry's own repo, and the ed25519 keypair behind one.
+ *
+ * Which GitHub credential makes the key:
+ * - a repo under the company's installation (`hosting.github`): an installation token of the platform GitHub App
+ *   (`PLATFORM_GITHUB_APP_REFS`), asked for `administration: write` on that one repo;
+ * - a repo under `wtfalch`: the same App's installation on that account, found with `GET /orgs/<owner>/installation`
+ *   (cached for the life of the client) and asked for the same token.
+ * Both need the repository permission "Administration: Read and write"; creating a deploy key, even a read-only
+ * one, is refused without it. Neither is documented to hold it today, so a refusal is a plain blocked line, not a
+ * failure.
+ */
+/** Every GitHub call is cut off after this long. */
+export const GITHUB_DEPLOY_KEYS_TIMEOUT_MS = 20_000;
+const GITHUB_API = 'https://api.github.com';
+const MAX_PAGES = 10;
+const PAGE_SIZE = 100;
+/** Why foundry cannot make deploy keys for a repo. The text is plain and fixed; it holds no credential. */
+export class DeployKeysBlocked extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+        this.name = 'DeployKeysBlocked';
+    }
+}
+/** The line for a blocked repo: what is missing, and whose step it is. */
+export function deployKeysBlockedLine(target, reason) {
+    if (reason === 'unreachable') {
+        return `GitHub did not answer for ${target.repo}, so its deploy key could not be checked; the next plan tries again`;
+    }
+    if (reason === 'no-credential') {
+        return `the platform GitHub App keys (${Object.values(PLATFORM_GITHUB_APP_REFS).join(', ')}) are not all held, so ${target.repo} cannot get a deploy key; William's step: hold them in Archon, Shared, Keys`;
+    }
+    if (target.installationId === undefined) {
+        return `the platform GitHub App needs Administration: Read and write and an installation on ${target.repo.split('/')[0]} (William's step, once for the platform)`;
+    }
+    return `GitHub refused deploy keys on ${target.repo}: the platform GitHub App needs the repository permission "Administration: Read and write"; William's step: grant it in the App's settings, then the owner of the installation accepts the new permission on GitHub`;
+}
+const b64url = (value) => Buffer.from(value).toString('base64url');
+/** A 9-minute RS256 JWT for the App, as GitHub asks for before an installation token. */
+export function githubAppJwt(appId, privateKeyPem, nowMs) {
+    const iat = Math.floor(nowMs / 1000) - 60;
+    const head = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+    const body = b64url(JSON.stringify({ iat, exp: iat + 600, iss: appId }));
+    const signature = createSign('RSA-SHA256').update(`${head}.${body}`).sign(privateKeyPem);
+    return `${head}.${body}.${b64url(signature)}`;
+}
+/**
+ * The GitHub REST deploy-key calls over `fetchImpl`, a timeout on each. Errors are fixed text: never a token, a key
+ * or a response body. A 401, 403, 404 or 422 from the credential or the key call is a {@link DeployKeysBlocked}
+ * `permission`; no answer is `unreachable`.
+ */
+export function createGithubDeployKeys(options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? GITHUB_DEPLOY_KEYS_TIMEOUT_MS;
+    const now = options.now ?? Date.now;
+    const secret = (value) => options.onSecret?.(value);
+    const send = async (token, method, path, body) => {
+        let response;
+        try {
+            response = await doFetch(`${GITHUB_API}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    Accept: 'application/vnd.github+json',
+                    'X-GitHub-Api-Version': '2022-11-28',
+                    ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+                },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch {
+            throw new DeployKeysBlocked('unreachable', 'GitHub did not answer');
+        }
+        let json = null;
+        try {
+            json = await response.json();
+        }
+        catch {
+            // Empty body (a delete) or not JSON: the status decides.
+        }
+        return { status: response.status, json };
+    };
+    const installations = new Map();
+    const credential = async (target) => {
+        const appId = await options.heldKeys.resolve(PLATFORM_GITHUB_APP_REFS.appId);
+        const pem = await options.heldKeys.resolve(PLATFORM_GITHUB_APP_REFS.privateKey);
+        if (!appId || !pem)
+            throw new DeployKeysBlocked('no-credential', 'App keys not held');
+        secret(pem);
+        let jwt;
+        try {
+            jwt = githubAppJwt(appId, pem, now());
+        }
+        catch {
+            throw new DeployKeysBlocked('no-credential', 'App key unusable');
+        }
+        secret(jwt);
+        const owner = target.repo.slice(0, target.repo.indexOf('/'));
+        const name = target.repo.slice(target.repo.indexOf('/') + 1);
+        let installationId = target.installationId ?? installations.get(owner);
+        if (installationId === undefined) {
+            const found = await send(jwt, 'GET', `/orgs/${owner}/installation`);
+            const id = found.json?.id;
+            if (found.status === 200 && typeof id === 'number') {
+                installationId = id;
+                installations.set(owner, id);
+            }
+            else if (refused(found.status)) {
+                throw new DeployKeysBlocked('permission', 'no installation');
+            }
+            else {
+                throw new DeployKeysBlocked('unreachable', 'installation not found');
+            }
+        }
+        const { status, json } = await send(jwt, 'POST', `/app/installations/${installationId}/access_tokens`, { repositories: [name], permissions: { administration: 'write' } });
+        const token = json?.token;
+        if (status >= 200 && status < 300 && typeof token === 'string' && token) {
+            secret(token);
+            return token;
+        }
+        if (status === 401 || status === 403 || status === 404 || status === 422) {
+            throw new DeployKeysBlocked('permission', 'installation token refused');
+        }
+        throw new DeployKeysBlocked('unreachable', 'installation token not given');
+    };
+    const refused = (status) => status === 401 || status === 403 || status === 404 || status === 422;
+    const asKey = (value) => {
+        const v = value;
+        if (!v || typeof v.id !== 'number' || typeof v.key !== 'string')
+            return null;
+        return {
+            id: v.id,
+            title: typeof v.title === 'string' ? v.title : '',
+            key: v.key.trim(),
+            readOnly: v.read_only === true,
+        };
+    };
+    return {
+        async list(target) {
+            const token = await credential(target);
+            const keys = [];
+            for (let page = 1; page <= MAX_PAGES; page++) {
+                const { status, json } = await send(token, 'GET', `/repos/${target.repo}/keys?per_page=${PAGE_SIZE}&page=${page}`);
+                if (refused(status))
+                    throw new DeployKeysBlocked('permission', 'listing refused');
+                if (status !== 200 || !Array.isArray(json)) {
+                    throw new DeployKeysBlocked('unreachable', 'listing failed');
+                }
+                for (const raw of json) {
+                    const key = asKey(raw);
+                    if (key)
+                        keys.push(key);
+                }
+                if (json.length < PAGE_SIZE)
+                    break;
+            }
+            return keys;
+        },
+        async create(target, key) {
+            const token = await credential(target);
+            const { status, json } = await send(token, 'POST', `/repos/${target.repo}/keys`, {
+                title: key.title,
+                key: key.key,
+                read_only: key.readOnly,
+            });
+            if (refused(status) && status !== 422) {
+                throw new DeployKeysBlocked('permission', 'creating refused');
+            }
+            const made = status === 201 ? asKey(json) : null;
+            if (!made)
+                throw new DeployKeysBlocked('unreachable', 'creating failed');
+            return made;
+        },
+        async remove(target, id) {
+            const token = await credential(target);
+            const { status } = await send(token, 'DELETE', `/repos/${target.repo}/keys/${id}`);
+            if (status === 204 || status === 404)
+                return;
+            if (refused(status))
+                throw new DeployKeysBlocked('permission', 'deleting refused');
+            throw new DeployKeysBlocked('unreachable', 'deleting failed');
+        },
+    };
+}
+const sshString = (data) => {
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    return Buffer.concat([length, data]);
+};
+const uint32 = (n) => {
+    const out = Buffer.alloc(4);
+    out.writeUInt32BE(n);
+    return out;
+};
+/** A new ed25519 keypair; the private key is an unencrypted `-----BEGIN OPENSSH PRIVATE KEY-----` file, as ssh and git read it. */
+export function generateRepoKeyPair() {
+    const { privateKey } = generateKeyPairSync('ed25519');
+    const jwk = privateKey.export({ format: 'jwk' });
+    const seed = Buffer.from(jwk.d, 'base64url');
+    const pub = Buffer.from(jwk.x, 'base64url');
+    const type = sshString(Buffer.from('ssh-ed25519'));
+    const publicBlob = Buffer.concat([type, sshString(pub)]);
+    const check = Buffer.from(globalThis.crypto.getRandomValues(new Uint8Array(4)));
+    const inner = Buffer.concat([
+        check,
+        check,
+        type,
+        sshString(pub),
+        sshString(Buffer.concat([seed, pub])),
+        sshString(Buffer.alloc(0)),
+    ]);
+    const pad = (8 - (inner.length % 8)) % 8;
+    const padding = Buffer.from(Array.from({ length: pad }, (_, i) => i + 1));
+    const file = Buffer.concat([
+        Buffer.from('openssh-key-v1\0'),
+        sshString(Buffer.from('none')),
+        sshString(Buffer.from('none')),
+        sshString(Buffer.alloc(0)),
+        uint32(1),
+        sshString(publicBlob),
+        sshString(Buffer.concat([inner, padding])),
+    ]);
+    const body = file.toString('base64').replace(/(.{70})/g, '$1\n');
+    return {
+        publicKey: `ssh-ed25519 ${publicBlob.toString('base64')}`,
+        privateKey: `-----BEGIN OPENSSH PRIVATE KEY-----\n${body.endsWith('\n') ? body : `${body}\n`}-----END OPENSSH PRIVATE KEY-----\n`,
+    };
+}
+/**
+ * The public key line (`ssh-ed25519 <base64>`) inside an unencrypted OpenSSH private key file, or `null` when the
+ * text is not one (so a held value that is not a usable key is replaced, not trusted).
+ */
+export function publicKeyOfPrivate(privateKey) {
+    const match = /-----BEGIN OPENSSH PRIVATE KEY-----([\s\S]*?)-----END OPENSSH PRIVATE KEY-----/.exec(privateKey);
+    if (!match)
+        return null;
+    try {
+        const raw = Buffer.from((match[1] ?? '').replace(/\s+/g, ''), 'base64');
+        const magic = Buffer.from('openssh-key-v1\0');
+        if (!raw.subarray(0, magic.length).equals(magic))
+            return null;
+        let at = magic.length;
+        const readString = () => {
+            const length = raw.readUInt32BE(at);
+            const out = raw.subarray(at + 4, at + 4 + length);
+            if (out.length !== length)
+                throw new Error('short');
+            at += 4 + length;
+            return out;
+        };
+        if (readString().toString() !== 'none')
+            return null;
+        if (readString().toString() !== 'none')
+            return null;
+        readString();
+        if (raw.readUInt32BE(at) !== 1)
+            return null;
+        at += 4;
+        const blob = readString();
+        if (blob.length === 0)
+            return null;
+        const typeLength = blob.readUInt32BE(0);
+        if (blob.subarray(4, 4 + typeLength).toString() !== 'ssh-ed25519')
+            return null;
+        // The private section must be whole too: a key cut short, or one whose public half is not the blob's, is not
+        // one ssh can use.
+        const priv = readString();
+        if (priv.length % 8 !== 0 || priv.length < 8)
+            return null;
+        if (priv.readUInt32BE(0) !== priv.readUInt32BE(4))
+            return null;
+        let p = 8;
+        const privString = () => {
+            const length = priv.readUInt32BE(p);
+            const out = priv.subarray(p + 4, p + 4 + length);
+            if (out.length !== length)
+                throw new Error('short');
+            p += 4 + length;
+            return out;
+        };
+        if (privString().toString() !== 'ssh-ed25519')
+            return null;
+        const inner = privString();
+        if (!inner.equals(blob.subarray(blob.length - 32)) || inner.length !== 32)
+            return null;
+        const secret = privString();
+        if (secret.length !== 64 || !secret.subarray(32).equals(inner))
+            return null;
+        return `ssh-ed25519 ${blob.toString('base64')}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when two `type base64` lines name the same key (a trailing comment is ignored). */
+export const sameSshKey = (a, b) => {
+    const [typeA, bodyA] = a.trim().split(/\s+/);
+    const [typeB, bodyB] = b.trim().split(/\s+/);
+    return Boolean(typeA && bodyA) && typeA === typeB && bodyA === bodyB;
+};

package/dist/plan/github-source.d.ts

@@ -0,0 +1,53 @@
+import { type HostingGithub } from '../org.js';
+import type { DeclaredOrg } from '../org.js';
+import type { UnmanagedItem } from '../plan.js';
+import type { DraftStep } from './diff.js';
+/** Recorded after the source is made: the installation id it is bound to, so a changed installation plans the step again. */
+export declare const GITHUB_SOURCE_INSTALLATION_SCOPE_KEY = "github_source_installation";
+/** The Coolify private key every company source shares: the platform GitHub App's key, made once. */
+export declare const GITHUB_SOURCE_KEY_NAME = "platform-github-app";
+/** Every Coolify call this module makes is cut off after this long. */
+export declare const GITHUB_SOURCE_TIMEOUT_MS = 20000;
+/** The recorded resource id (`serviceIds` key) of a company's source: the step is keyed by the org id. */
+export declare function githubSourceResourceKey(orgId: string): string;
+/** The Coolify name of a company's GitHub source. */
+export declare function githubSourceName(slug: string): string;
+/** True when an app of this company is built from the company's own account, so it needs the company's source. */
+export declare function needsCompanyGithubSource(org: DeclaredOrg): boolean;
+/**
+ * `coolify:github-source` (keyed by the org id): the company's own Coolify GitHub App source, bound to its
+ * installation id. Blocked, not planned, while a key of the platform's GitHub App is not held. Planned again
+ * when the recorded source is missing or was made for another installation.
+ */
+export declare function planGithubSource(org: DeclaredOrg, recordedIds: Readonly<Record<string, string>>, keys: {
+    store: boolean;
+    missing: readonly string[];
+} | undefined): {
+    step: DraftStep | null;
+    blocked: UnmanagedItem[];
+};
+export interface GithubSourceDeps {
+    coolify: {
+        raw(method: string, path: string, body?: unknown): Promise<unknown>;
+    };
+    heldKeys: {
+        resolve(ref: string): Promise<string | null | undefined>;
+    };
+    /** Registers a value for redaction before anything else can see it. */
+    secret(value: string): void;
+    /** The step's name, for errors. */
+    label: string;
+    slug: string;
+    github: HostingGithub;
+    timeoutMs?: number;
+}
+/**
+ * The uuid of the company's Coolify GitHub source: found by name when it is bound to the company's installation,
+ * else made from the platform GitHub App's held keys (`PLATFORM_GITHUB_APP_REFS`) and the Coolify private key
+ * `platform-github-app` (found, else made). Every Coolify call has a timeout and a failure is fixed text: a
+ * Coolify error can echo the request body, which holds the App's secrets. A failure after the private key was
+ * made leaves that key (shared, found by name next run) and no source; the source is the last call.
+ */
+export declare function ensureGithubSource(deps: GithubSourceDeps): Promise<{
+    uuid: string;
+}>;