gcb-host 0.0.0 → 0.0.1

package/lib/providers/github-app.js

@@ -0,0 +1,901 @@
+/**
+ * GitHub App provider: the broker mints a short-lived installation access token with
+ * `node:crypto` only, so the host needs no `openssl`, no SDK and no runtime dependency.
+ *
+ * Everything GitHub documents as a prerequisite for a successful mint is implemented
+ * explicitly, because each omission fails in a way that is painful to diagnose:
+ *  - `RS256` signature;
+ *  - `iat` one minute in the past (clock drift);
+ *  - `exp` at most ten minutes after `iat`;
+ *  - `iss` set to the client ID when configured, otherwise the app ID;
+ *  - the account's installation is resolved by matching `account.login` case-insensitively,
+ *    which is what makes multiple owners work;
+ *  - the token is scoped to exactly one repository by name (`repositories` takes the
+ *    repository name, not `owner/name`) and to explicitly narrowed permissions;
+ *  - a minted token is cached and reused until shortly before it expires, instead of being
+ *    re-minted on every helper invocation.
+ *
+ * Reference: https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-json-web-token-jwt-for-a-github-app
+ */
+import { userTokenPath } from '../config.js';
+import { currentProxyKey, proxyFetch } from '../http.js';
+import { createSign } from 'node:crypto';
+import { getGhAction, ProviderConfigError, tokenFingerprint } from 'gcb-core';
+import { runGhAction } from '../gh.js';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { refreshUserToken } from '../device-flow.js';
+/** REST API origin. Overridable for GitHub Enterprise. */
+const DEFAULT_API = 'https://api.github.com';
+/** GitHub refuses a JWT whose `exp` is more than this many seconds after `iat`. */
+const MAX_JWT_LIFETIME_SECONDS = 600;
+/** Access levels, ordered, so a requested level can be compared against the granted one. */
+const ACCESS_LEVELS = { read: 1, write: 2, admin: 3 };
+/**
+ * Base64url-encode a string or buffer, without padding, as JWS requires.
+ *
+ * @param input - the value to encode.
+ * @returns the base64url encoding.
+ */
+export function base64url(input) {
+    return Buffer.from(input).toString('base64url');
+}
+/**
+ * Sign a GitHub App JWT.
+ *
+ * @param options - signing options.
+ * @returns the compact JWS.
+ * @throws {Error} when required inputs are missing or the lifetime exceeds GitHub's limit.
+ */
+export function signAppJwt(options) {
+    const { privateKeyPem, iss, nowMs, lifetimeSeconds = MAX_JWT_LIFETIME_SECONDS, skewSeconds = 60 } = options;
+    if (!privateKeyPem)
+        throw new Error('signAppJwt: privateKeyPem is required');
+    if (iss === undefined || iss === null || iss === '') {
+        throw new Error('signAppJwt: iss (client ID or app ID) is required');
+    }
+    if (lifetimeSeconds > MAX_JWT_LIFETIME_SECONDS) {
+        throw new Error(`signAppJwt: exp must be at most ${MAX_JWT_LIFETIME_SECONDS} seconds after iat (GitHub rejects anything longer)`);
+    }
+    const nowSeconds = Math.floor(nowMs / 1000);
+    const header = { typ: 'JWT', alg: 'RS256' };
+    const payload = {
+        iat: nowSeconds - skewSeconds,
+        exp: nowSeconds + lifetimeSeconds,
+        iss: String(iss),
+    };
+    const signingInput = `${base64url(JSON.stringify(header))}.${base64url(JSON.stringify(payload))}`;
+    const signature = createSign('RSA-SHA256').update(signingInput).sign(privateKeyPem);
+    return `${signingInput}.${base64url(signature)}`;
+}
+/**
+ * Extract the `rel="next"` URL from a `Link` header.
+ *
+ * @param linkHeader - the raw header value.
+ * @returns the next page URL, or null when there is none.
+ */
+export function nextLink(linkHeader) {
+    if (typeof linkHeader !== 'string')
+        return null;
+    for (const part of linkHeader.split(',')) {
+        const match = /<([^>]+)>\s*;\s*rel="next"/.exec(part);
+        const url = match?.[1];
+        if (url)
+            return url;
+    }
+    return null;
+}
+/**
+ * Build a GitHub App provider for one host.
+ *
+ * @param options - provider options.
+ * @returns the provider.
+ * @throws {Error} when the private key or app identity is missing (fail fast).
+ */
+export function createGithubAppProvider(options) {
+    const { host, cfg, skewSeconds = 300, fetchImpl = proxyFetch, now = () => Date.now(), ghPath, log = () => { }, } = options;
+    const privateKeyPem = cfg.privateKeyPem
+        ? cfg.privateKeyPem
+        : cfg.privateKeyPath
+            ? readFileSync(cfg.privateKeyPath, 'utf8')
+            : null;
+    if (!privateKeyPem) {
+        throw new Error(`github-app provider for ${host}: privateKeyPath (or privateKeyPem) is required`);
+    }
+    const keyPem = privateKeyPem;
+    // Captured as an explicitly-typed local so the narrowing survives into `call`, which is
+    // invoked later: `cfg.clientId ?? cfg.appId` is `string | number | undefined`.
+    const issuer = cfg.clientId ?? cfg.appId;
+    if (issuer === undefined || issuer === null || issuer === '') {
+        throw new Error(`github-app provider for ${host}: clientId (preferred) or appId is required`);
+    }
+    const iss = issuer;
+    const api = cfg.apiBaseUrl ?? DEFAULT_API;
+    const apiVersion = cfg.apiVersion ?? '2022-11-28';
+    const permissions = cfg.permissions ?? { contents: 'write' };
+    const checkPermissions = cfg.verifyAppPermissions !== false;
+    const installationTtlMs = (typeof cfg.installationCacheSeconds === 'number' ? cfg.installationCacheSeconds : 600) * 1000;
+    /**
+     * What a log read asks for: nothing but the log.
+     *
+     * Deliberately not the configured `permissions`, which describe the credential git needs. A token
+     * minted for those should not also be able to read CI logs, so a log read gets its own token,
+     * narrowed to `actions: read`. Whether the agent may read logs at all is then a question about the
+     * app's grant, not about anything running in the container.
+     */
+    const LOG_PERMISSIONS = { actions: 'read' };
+    /** How much of one log to return: enough to diagnose, bounded so one response stays sane. */
+    const LOG_LIMIT_CHARS = 200_000;
+    /**
+     * What opening a pull request asks for: the permission the operation needs, plus read access to
+     * the branches it names. Not the configured `permissions`, for the same reason a log read is not:
+     * a token minted for git should not also be able to open a pull request.
+     */
+    const PULL_REQUEST_PERMISSIONS = { pull_requests: 'write', contents: 'read' };
+    /** The result of an action that never reached the executor. */
+    const NO_RUN = { stdout: '', stderr: '', code: null, signal: null, truncated: false, timedOut: false };
+    const REVOKE_WARNING = 'the action token could not be revoked; it expires on its own';
+    /** owner login (lowercased) -> installation */
+    const installations = new Map();
+    /** owner/repo -> minted credential */
+    const tokens = new Map();
+    /** Cached pre-flight result, per owner: installations differ, so the answer does too. */
+    const permissionsChecked = new Map();
+    /**
+     * Name every configured permission a grant does not cover.
+     *
+     * @param granted - the permission map to check against.
+     * @param from - how to refer to that map in the message.
+     * @param absent - how to describe a permission that is missing entirely.
+     * @returns one message per problem; empty when the grant covers the configuration.
+     */
+    function missingPermissions(wantedPermissions, granted, from, absent) {
+        const problems = [];
+        for (const [name, wanted] of Object.entries(wantedPermissions)) {
+            const have = granted[name];
+            if (!have) {
+                problems.push(`${name}: ${absent}`);
+                continue;
+            }
+            if ((ACCESS_LEVELS[wanted] ?? 0) > (ACCESS_LEVELS[have] ?? 0)) {
+                problems.push(`${name}: requested "${wanted}" but ${from} only has "${have}"`);
+            }
+        }
+        return problems;
+    }
+    /**
+     * Call the REST API with a freshly signed app JWT.
+     *
+     * @param method - HTTP method.
+     * @param url - absolute URL.
+     * @param body - optional JSON body.
+     * @returns the parsed body and the Link header.
+     * @throws {Error} for a non-2xx response.
+     */
+    async function call(method, url, body) {
+        const jwt = signAppJwt({ privateKeyPem: keyPem, iss, nowMs: now() });
+        const headers = {
+            accept: 'application/vnd.github+json',
+            authorization: `Bearer ${jwt}`,
+            'x-github-api-version': apiVersion,
+            'user-agent': 'gcb',
+        };
+        if (body)
+            headers['content-type'] = 'application/json';
+        const response = await fetchImpl(url, {
+            method,
+            headers,
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await response.text();
+        let json = null;
+        try {
+            json = JSON.parse(text);
+        }
+        catch {
+            json = null;
+        }
+        if (!response.ok) {
+            const message = json !== null && typeof json === 'object' && 'message' in json
+                ? String(json.message)
+                : text.slice(0, 200);
+            // The URL is safe to log (no secret); neither the JWT nor any token is included.
+            throw new Error(`GitHub API ${method} ${url.replace(api, '')} failed with ${response.status}: ${message}`);
+        }
+        return { json, link: response.headers.get('link') };
+    }
+    /**
+     * Call the REST API with one installation token, returning the body as text.
+     *
+     * Used for job logs, whose response is plain text behind a redirect to a signed URL that needs no
+     * authorization — fetch drops the header across origins, which is what GitHub intends.
+     *
+     * @param method - HTTP method.
+     * @param url - absolute URL.
+     * @param token - the installation token to authenticate with.
+     * @returns the status and the body text.
+     * @throws {Error} for a non-2xx response.
+     */
+    async function callWithToken(method, url, token, body) {
+        const headers = {
+            accept: 'application/vnd.github+json',
+            authorization: `Bearer ${token}`,
+            'x-github-api-version': apiVersion,
+            'user-agent': 'gcb',
+        };
+        if (body)
+            headers['content-type'] = 'application/json';
+        const response = await fetchImpl(url, {
+            method,
+            headers,
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await response.text();
+        if (!response.ok) {
+            // The URL is safe to name — the token is a header, not part of it — but the body is not: it can quote
+            // the request, and it must never reach the container. So the message carries the endpoint and the
+            // status, which is what a pusher may see, and the body rides beside it where only the host log looks.
+            // The decision to write it there belongs to the broker, which owns that boundary; an error class
+            // cannot make it, because a caller that re-wraps this to name a permission wraps it in the same class.
+            const detail = text.replace(/\s+/g, ' ').trim().slice(0, 400);
+            const failure = new ProviderConfigError(`GitHub API ${method} ${url.replace(api, '')} answered ${response.status} for that request`);
+            if (detail !== '')
+                Object.assign(failure, { hostDetail: detail });
+            throw failure;
+        }
+        return { status: response.status, text };
+    }
+    /**
+     * Resolve the installation id for an account, cached per owner.
+     *
+     * @param owner - the repository owner as it appeared in the path.
+     * @returns the installation id.
+     * @throws {Error} when this app is not installed for that account.
+     */
+    async function resolveInstallationId(owner) {
+        const key = owner.toLowerCase();
+        const cached = installations.get(key);
+        if (cached && cached.expiresAt > now())
+            return cached.id;
+        let url = `${api}/app/installations?per_page=100`;
+        for (let page = 0; page < 10 && url; page += 1) {
+            const { json, link } = await call('GET', url);
+            if (Array.isArray(json)) {
+                for (const entry of json) {
+                    const installation = entry;
+                    const login = installation.account?.login;
+                    if (typeof login === 'string' && login.toLowerCase() === key && typeof installation.id === 'number') {
+                        installations.set(key, { id: installation.id, expiresAt: now() + installationTtlMs });
+                        return installation.id;
+                    }
+                }
+            }
+            url = nextLink(link);
+        }
+        throw new Error(`no installation of this app has access to account "${owner}"`);
+    }
+    /**
+     * Confirm both grants cover every permission the token request will ask for.
+     *
+     * Two checks, because there are two ceilings. The app's permissions are what the app may ask for at
+     * all; the **installation's** are what it actually has, and a permission can be granted on the app
+     * while an installation has not approved the update. Checking only the app passes in that case and
+     * then fails at the token request, where the message is GitHub's and so cannot be handed to the
+     * container — which is how a permission problem became "see the broker log".
+     *
+     * Cached per owner, since installations differ; a failed check is not cached, so fixing the
+     * settings does not require restarting the broker.
+     *
+     * @param owner - the account whose installation will be asked for a token.
+     * @returns resolves when the configured permissions are a subset of both grants.
+     * @throws {ProviderConfigError} naming each permission that is missing or granted at a lower level.
+     */
+    function ensurePermissions(owner, wantedPermissions = permissions) {
+        if (!checkPermissions)
+            return Promise.resolve();
+        // Keyed by both, because a log read checks a different set than a credential does.
+        const key = `${owner.toLowerCase()}|${currentProxyKey()}|${Object.entries(wantedPermissions)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([name, level]) => `${name}=${level}`)
+            .join(',')}`;
+        const cached = permissionsChecked.get(key);
+        if (cached)
+            return cached;
+        const pending = (async () => {
+            const { json } = await call('GET', `${api}/app`);
+            const appGranted = json?.permissions ?? {};
+            const problems = missingPermissions(wantedPermissions, appGranted, 'the app', 'the app is not granted this permission at all');
+            const installationId = await resolveInstallationId(owner);
+            const { json: installation } = await call('GET', `${api}/app/installations/${installationId}`);
+            const installationGranted = installation?.permissions ?? {};
+            problems.push(...missingPermissions(wantedPermissions, installationGranted, 'this installation', 'this installation has not approved it'));
+            if (problems.length > 0) {
+                throw new ProviderConfigError(`the configured permissions for ${host} are not available (${problems.join('; ')}); ` +
+                    'grant them on the app, approve the update on the installation, or lower `permissions` ' +
+                    'in the broker config, or set "verifyAppPermissions": false to skip this check');
+            }
+        })().catch((error) => {
+            permissionsChecked.delete(key);
+            throw error;
+        });
+        permissionsChecked.set(key, pending);
+        return pending;
+    }
+    /**
+     * Report what a pull request is, and how its commit is doing.
+     *
+     * Two reads: the pull request itself, which carries `mergeable_state`, and the workflow runs for
+     * its head commit — the second is what separates "the checks are red" from "the ruleset wants a
+     * review", which `mergeable_state: blocked` alone cannot. Both are repository-scoped, so the
+     * allowlist binds them.
+     *
+     * @param request - which pull request.
+     * @param token - the installation token.
+     * @param collection - the repository's pull request route.
+     * @returns the number, URL, state and a short report.
+     */
+    async function readPullRequestStatus(request, token, collection) {
+        const { text } = await callWithToken('GET', `${collection}/${request.number}`, token);
+        let parsed = null;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = null;
+        }
+        const payload = (parsed ?? {});
+        if (typeof payload.number !== 'number' || typeof payload.html_url !== 'string') {
+            throw new ProviderConfigError('GitHub did not answer with a pull request');
+        }
+        const lines = [
+            `#${payload.number} ${String(payload.state ?? '?')}${payload.merged === true ? ' (merged)' : ''}${payload.draft === true ? ' (draft)' : ''}`,
+            payload.html_url,
+        ];
+        if (typeof payload.mergeable_state === 'string') {
+            lines.push(`mergeable: ${payload.mergeable_state}`);
+        }
+        const sha = (payload.head ?? {}).sha;
+        if (typeof sha === 'string' && sha !== '') {
+            const { text: listed } = await callWithToken('GET', `${api}/repos/${request.owner}/${request.repo}/actions/runs?head_sha=${sha}&per_page=20`, token);
+            let runs = null;
+            try {
+                runs = JSON.parse(listed);
+            }
+            catch {
+                runs = null;
+            }
+            const batch = (runs ?? {}).workflow_runs;
+            if (Array.isArray(batch) && batch.length > 0) {
+                for (const run of batch) {
+                    lines.push(`run ${String(run.name ?? '?')}: ${String(run.conclusion ?? run.status ?? '?')}`);
+                }
+            }
+            else {
+                lines.push('no workflow run for that commit yet');
+            }
+        }
+        return {
+            number: payload.number,
+            url: payload.html_url,
+            state: typeof payload.state === 'string' ? payload.state : undefined,
+            merged: payload.merged === true,
+            status: lines.join('\n'),
+        };
+    }
+    let cachedPersonToken;
+    // One renewal at a time. GitHub documents neither what happens to a refresh token used twice nor a
+    // grace period for it, so the honest reason is the failure that is certain rather than the one that is
+    // documented: two exchanges racing means one of them renews from a token the other has already
+    // replaced, and whichever write-back runs last decides what is on disk for the next renewal.
+    // The refresh token on disk is one shared value; two renewals racing can invalidate it. Serialize
+    // the exchange even when the commands selected different proxy routes, then let the waiter re-read
+    // the cache the winner wrote. Each exchange still uses its own command's fetch.
+    let renewingPersonToken;
+    /**
+     * One more sentence about a failure, when there is one worth having.
+     *
+     * `fetch failed` is the whole message undici gives for a connection problem and it names nothing useful;
+     * the reason is on `cause`. This is for the host log, so it is allowed to carry detail.
+     *
+     * @param error - whatever was thrown.
+     * @returns an empty string, or ` (the reason)`.
+     */
+    function describeCause(error) {
+        const cause = error?.cause?.message;
+        return typeof cause === 'string' && cause !== '' ? ` (${cause})` : '';
+    }
+    /**
+     * The pull request number in the URL GitHub returns for a pull request.
+     *
+     * A review comment carries the pull request it belongs to as `pull_request_url`, which is how a comment
+     * id — one for the whole repository, not one per pull request — is tied back to the pull request named
+     * on the command line.
+     *
+     * @param value - an `.../pulls/{number}` URL, as GitHub returns it.
+     * @returns the number, or undefined when the value names none.
+     */
+    function pullRequestNumber(value) {
+        if (typeof value !== 'string')
+            return undefined;
+        const match = /\/pulls\/(\d+)\/?$/.exec(value);
+        if (match?.[1] === undefined)
+            return undefined;
+        const number = Number(match[1]);
+        return Number.isInteger(number) && number > 0 ? number : undefined;
+    }
+    return {
+        name: 'github-app',
+        async runAction(request) {
+            const spec = getGhAction(request.action);
+            const wanted = { ...spec.permissions };
+            await ensurePermissions(request.owner, wanted);
+            const installationId = await resolveInstallationId(request.owner);
+            const { json } = await call('POST', `${api}/app/installations/${installationId}/access_tokens`, {
+                repositories: [request.repo],
+                permissions: wanted,
+            });
+            const token = json?.token;
+            if (typeof token !== 'string' || !token) {
+                throw new ProviderConfigError('GitHub returned no installation token for the action');
+            }
+            let result;
+            let warning;
+            try {
+                result = await runGhAction({
+                    action: request.action,
+                    values: request.values,
+                    repo: request.full,
+                    token,
+                    host: request.host,
+                    ghPath,
+                    env: process.env,
+                    proxy: request.proxy,
+                });
+            }
+            catch (error) {
+                result = { ...NO_RUN, error: error instanceof Error ? error.message : String(error) };
+            }
+            finally {
+                try {
+                    const response = await fetchImpl(`${api}/installation/token`, {
+                        method: 'DELETE',
+                        headers: {
+                            accept: 'application/vnd.github+json',
+                            authorization: `Bearer ${token}`,
+                            'x-github-api-version': apiVersion,
+                            'user-agent': 'gcb',
+                        },
+                    });
+                    if (!response.ok) {
+                        let detail = '';
+                        try {
+                            detail = (await response.text()).replace(/\s+/g, ' ').trim().slice(0, 200);
+                        }
+                        catch {
+                            // The status is enough; a body that cannot be read is still not a successful revoke.
+                        }
+                        log(`could not revoke the action token: GitHub answered ${response.status}${detail ? ` ${detail}` : ''}`);
+                        warning = REVOKE_WARNING;
+                    }
+                }
+                catch (error) {
+                    log(`could not revoke the action token: ${String(error.message ?? error)}`);
+                    warning = REVOKE_WARNING;
+                }
+            }
+            return { ...result, tokenFingerprint: tokenFingerprint(token), ...(warning === undefined ? {} : { warning }) };
+        },
+        async getCredential(request) {
+            const cached = tokens.get(request.full);
+            if (cached && cached.expiresAt - now() > skewSeconds * 1000) {
+                return { ...cached, cached: true };
+            }
+            await ensurePermissions(request.owner);
+            const installationId = await resolveInstallationId(request.owner);
+            const { json } = await call('POST', `${api}/app/installations/${installationId}/access_tokens`, {
+                repositories: [request.repo],
+                permissions,
+            });
+            const payload = (json ?? {});
+            if (typeof payload.token !== 'string' || !payload.token) {
+                throw new Error('GitHub API returned no token for the installation access token request');
+            }
+            const expiresAt = typeof payload.expires_at === 'string' ? Date.parse(payload.expires_at) : now() + 3_600_000;
+            const credential = {
+                username: 'x-access-token',
+                password: payload.token,
+                expiresAt,
+            };
+            tokens.set(request.full, credential);
+            return { ...credential, cached: false };
+        },
+        /**
+         * Read one workflow job's log.
+         *
+         * One call, to the repository-scoped route: the repository is part of the URL, so the allowlist
+         * binds the job id by construction. The global route is keyed by job id alone — an allowlisted
+         * repository could name any job this app can see — and it is the one that answers "Must have
+         * admin rights", which is a permission this broker should never want.
+         *
+         * @param request - the job to read.
+         * @returns the log text, bounded.
+         */
+        async getJobLog(request) {
+            await ensurePermissions(request.owner, LOG_PERMISSIONS);
+            const installationId = await resolveInstallationId(request.owner);
+            const { json } = await call('POST', `${api}/app/installations/${installationId}/access_tokens`, {
+                repositories: [request.repo],
+                permissions: LOG_PERMISSIONS,
+            });
+            const token = json?.token;
+            if (typeof token !== 'string' || !token) {
+                throw new ProviderConfigError('GitHub returned no installation token for the log request');
+            }
+            let text;
+            try {
+                const body = await callWithToken('GET', `${api}/repos/${request.owner}/${request.repo}/actions/jobs/${request.jobId}/logs`, token);
+                text = body.text;
+            }
+            catch (error) {
+                // A 404 here has two ordinary causes, and neither is a broker fault: the job is not in that
+                // repository, or the run it belongs to has not finished — the endpoint serves no log at all
+                // while a job is still running.
+                throw new ProviderConfigError(`${error.message}; the job has to exist in that repository, and a run that is still in progress has no log yet`);
+            }
+            if (text.length <= LOG_LIMIT_CHARS)
+                return { text, truncated: false };
+            return {
+                text: `${text.slice(0, LOG_LIMIT_CHARS)}\n… log truncated at ${LOG_LIMIT_CHARS} characters\n`,
+                truncated: true,
+            };
+        },
+        /**
+         * Open one pull request.
+         *
+         * The same shape as a log read: its own token, narrowed to what the operation needs, and the
+         * repository-scoped route, so the allowlist binds it by construction.
+         *
+         * @param request - the branches and the text.
+         * @returns the number and the URL GitHub answered with.
+         */
+        async pullRequest(request) {
+            // The two actions a person may perform are decided first: when somebody has authorized this
+            // deployment, their token is the whole authority for them, and requiring an installation as well
+            // would refuse a repository the app was never installed on — the fork-to-upstream case the allowlist
+            // exists to permit. Everything else still acts as the app, and only ever could.
+            const personalForThis = request.action === 'open' || request.action === 'resolve';
+            const personToken = personalForThis ? await personalToken() : undefined;
+            // `--status` also reads /actions/runs, which is checked against actions: read. Pre-flighting
+            // pull_requests alone passed a grant that could not make that call, which is the opposite of what a
+            // pre-flight is for.
+            const wanted = request.action === 'status' ? { ...PULL_REQUEST_PERMISSIONS, actions: 'read' } : PULL_REQUEST_PERMISSIONS;
+            // One variable, so every branch below holds a token without having to ask which kind it is.
+            let token;
+            // A token per owner is the other way a person acts. It counts exactly as the authorized token does:
+            // whoever is acting, requiring an installation as well would refuse a repository the app was never
+            // installed on — the fork-to-upstream case the allowlist exists to permit.
+            const fileToken = request.action === 'open' || request.action === 'resolve'
+                ? cfg.userTokens?.[request.owner]
+                : undefined;
+            const actingToken = personToken ?? (fileToken === undefined ? undefined : readFileSync(fileToken, 'utf8').trim());
+            if (actingToken === undefined) {
+                await ensurePermissions(request.owner, wanted);
+                const installationId = await resolveInstallationId(request.owner);
+                const { json: minted } = await call('POST', `${api}/app/installations/${installationId}/access_tokens`, {
+                    repositories: [request.repo],
+                    permissions: wanted,
+                });
+                const mintedToken = minted?.token;
+                if (typeof mintedToken !== 'string' || !mintedToken) {
+                    throw new ProviderConfigError('GitHub returned no installation token for the pull request');
+                }
+                token = mintedToken;
+            }
+            else {
+                token = actingToken;
+            }
+            const collection = `${api}/repos/${request.owner}/${request.repo}/pulls`;
+            /**
+             * The token of the person this deployment authorized, when there is one.
+      
+             * Only two actions may use it, and both because an installation token cannot: GitHub will not
+             * author a pull request as a person for an app, and refuses to resolve a review thread for one.
+             * The refresh token lives beside the private key, and GitHub rotates it on every use, so the new
+             * one is written back — keeping the old would work once and then stop.
+             *
+             * @returns the user token, or `undefined` when nobody has authorized one.
+             */
+            async function personalToken() {
+                while (renewingPersonToken !== undefined) {
+                    try {
+                        await renewingPersonToken;
+                    }
+                    catch {
+                        // The winner failed; this command retries after the lock is released.
+                    }
+                }
+                const pending = renewPersonToken();
+                renewingPersonToken = pending;
+                try {
+                    return await pending;
+                }
+                finally {
+                    if (renewingPersonToken === pending)
+                        renewingPersonToken = undefined;
+                }
+            }
+            async function renewPersonToken() {
+                if (cfg.clientId === undefined || cfg.privateKeyPath === undefined)
+                    return undefined;
+                const path = userTokenPath(cfg.privateKeyPath);
+                if (!existsSync(path))
+                    return undefined;
+                const now = Date.now();
+                // The file is the only thing that says who the broker may act as, so it is read before the cache is
+                // trusted: running `authorize` again — the documented way to change that person, and the only one —
+                // has to take effect now rather than when the cached token happens to expire.
+                const held = readFileSync(path, 'utf8').trim();
+                if (cachedPersonToken !== undefined &&
+                    cachedPersonToken.until > now + 60_000 &&
+                    cachedPersonToken.source === held) {
+                    return cachedPersonToken.token;
+                }
+                let next;
+                try {
+                    next = await refreshUserToken(cfg.clientId, held, (url, init) => fetchImpl(url, init));
+                }
+                catch (error) {
+                    // This is the one place a renewal failure is explained: the caller is an action that failed,
+                    // and "fetch failed" on its own names neither the host nor the reason.
+                    throw new Error(`could not renew the authorized token from ${path}: ${error.message}${describeCause(error)}`);
+                }
+                if (next.refreshToken !== undefined) {
+                    try {
+                        writeFileSync(path, `${next.refreshToken}\n`, { mode: 0o600 });
+                    }
+                    catch (error) {
+                        // GitHub invalidated the token on disk the moment it answered, so this is not transient and not
+                        // recoverable: the next renewal reads a dead token. Nothing else in the log would say so.
+                        throw new Error(`could not store the new refresh token in ${path}: ${error.message}; the previous ` +
+                            'one is no longer valid, so run authorize again');
+                    }
+                }
+                cachedPersonToken = {
+                    token: next.token,
+                    until: now + (next.expiresInSeconds ?? 28_800) * 1_000,
+                    source: next.refreshToken ?? held,
+                };
+                return cachedPersonToken.token;
+            }
+            if (request.action === 'resolve') {
+                // Resolving has no REST endpoint either. The thread id is the one `--threads` prints.
+                // The thread id is a global node id, and the person token is not narrowed to a repository the way
+                // an installation token is. Ask whose thread it is before changing it: the allowlist decided which
+                // repositories this broker may touch, and a mutation is the wrong place to discover it did not.
+                const { text: scoped } = await callWithToken('POST', `${api}/graphql`, personToken ?? token, {
+                    query: 'query($threadId:ID!){node(id:$threadId){... on PullRequestReviewThread{pullRequest{repository{nameWithOwner}}}}}',
+                    variables: { threadId: request.threadId },
+                });
+                let belongsTo;
+                try {
+                    const parsed = JSON.parse(scoped);
+                    belongsTo = parsed.data?.node?.pullRequest?.repository?.nameWithOwner;
+                }
+                catch {
+                    belongsTo = undefined;
+                }
+                if (typeof belongsTo !== 'string' ||
+                    belongsTo.toLowerCase() !== `${request.owner}/${request.repo}`.toLowerCase()) {
+                    // A plain Error on purpose: this is the host log's business, not the container's.
+                    throw new Error(`refusing to resolve ${request.threadId}: it is not a review thread of ${request.owner}/${request.repo}` +
+                        (typeof belongsTo === 'string' ? ` (it belongs to ${belongsTo})` : ' (or it could not be read)'));
+                }
+                const { text: raw } = await callWithToken('POST', `${api}/graphql`, personToken ?? token, {
+                    query: 'mutation($threadId:ID!){resolveReviewThread(input:{threadId:$threadId}){thread{isResolved}}}',
+                    variables: { threadId: request.threadId ?? '' },
+                });
+                let answer = null;
+                try {
+                    answer = JSON.parse(raw);
+                }
+                catch {
+                    answer = null;
+                }
+                const state = (answer ?? {});
+                // A plain Error, not a ProviderConfigError: GraphQL answers in a response body, and those
+                // are not passed to the container.
+                if (Array.isArray(state.errors) && state.errors.length > 0) {
+                    // The reason belongs in the host log, which is where a plain Error goes: the broker answers
+                    // the container generically for one, so nothing from a response body crosses the socket.
+                    throw new Error(`GitHub refused to resolve that review thread: ${JSON.stringify(state.errors).slice(0, 300)}`);
+                }
+                return {
+                    number: request.number ?? 0,
+                    url: '',
+                    status: state.data?.resolveReviewThread?.thread?.isResolved === true ? 'resolved' : 'still open',
+                };
+            }
+            if (request.action === 'reply') {
+                // A reply belongs in the thread it answers. The issues API would need `issues: write` and
+                // would start a new conversation instead of joining one.
+                await callWithToken('POST', `${collection}/${request.number}/comments/${String(request.commentId ?? 0)}/replies`, token, { body: request.body ?? '' });
+                return { number: request.number ?? 0, url: '' };
+            }
+            if (request.action === 'edit') {
+                // A review comment is addressed by its own id, and that id is one for the whole repository, not
+                // one per pull request. The route therefore carries no pull request number and the CLI asks for
+                // none: the number to report is the one the comment itself names, read back from the answer
+                // rather than echoed from the request. The repository in the path is what the allowlist binds.
+                const endpoint = `${api}/repos/${request.owner}/${request.repo}/pulls/comments/${String(request.commentId ?? 0)}`;
+                const { text: edited } = await callWithToken('PATCH', endpoint, token, { body: request.body ?? '' });
+                let changed = null;
+                try {
+                    changed = JSON.parse(edited);
+                }
+                catch {
+                    changed = null;
+                }
+                const html = (changed ?? {});
+                return {
+                    number: pullRequestNumber(html.pull_request_url) ?? request.number ?? 0,
+                    url: typeof html.html_url === 'string' ? html.html_url : '',
+                };
+            }
+            if (request.action === 'threads') {
+                // GraphQL, because review threads have no REST list. The repository and the number are
+                // named here, so the allowlist still decides what can be reached.
+                const { text: raw } = await callWithToken('POST', `${api}/graphql`, token, {
+                    query: 'query($owner:String!,$name:String!,$number:Int!){repository(owner:$owner,name:$name){pullRequest(number:$number){reviewThreads(first:50){totalCount nodes{id isResolved path line comments(first:10){nodes{databaseId author{login} body}}}}}}}',
+                    variables: { owner: request.owner, name: request.repo, number: request.number },
+                });
+                let listed = null;
+                try {
+                    listed = JSON.parse(raw);
+                }
+                catch {
+                    listed = null;
+                }
+                // Nothing from a response body reaches the container — the broker answers with a generic
+                // message for an ordinary Error — but the host log is where a reason belongs, and a refusal
+                // that reads as "no threads" is worse than one that reads as a refusal.
+                const refused = (listed ?? {});
+                if (Array.isArray(refused.errors) && refused.errors.length > 0) {
+                    throw new Error(`GitHub refused to list the review threads: ${JSON.stringify(refused.errors).slice(0, 300)}`);
+                }
+                const data = (listed ?? {});
+                const nodes = data.data?.repository?.pullRequest?.reviewThreads?.nodes;
+                const report = [];
+                if (Array.isArray(nodes)) {
+                    for (const node of nodes) {
+                        report.push(`${node.isResolved === true ? 'resolved' : 'open    '} ${String(node.id ?? '')}  ${String(node.path ?? '')}:${String(node.line ?? '')}`);
+                        const comments = node.comments?.nodes;
+                        if (!Array.isArray(comments))
+                            continue;
+                        for (const comment of comments) {
+                            // The whole comment, not its first line and not 120 characters of it: a review bot puts the finding
+                            // in the lines below the header, and a report that drops them sends the reader to the web UI for the
+                            // one thing this command exists to show.
+                            const body = String(comment.body ?? '');
+                            // The prose, not the first twelve lines of the comment: a review bot prefixes its finding with the
+                            // commands it ran and a fence of their output, so counting raw lines reads the preamble and never
+                            // reaches the claim. Fences and the bot's own metadata lines are dropped, and the cap then applies to
+                            // what is left, which is what the reader wants and what the writer meant.
+                            const bodyLines = body.split('\n');
+                            const kept = [];
+                            let inFence = false;
+                            for (const raw of bodyLines) {
+                                const line = raw.trim();
+                                if (line.startsWith('```')) {
+                                    inFence = !inFence;
+                                    continue;
+                                }
+                                if (inFence)
+                                    continue;
+                                if (/^(🏁|🔎|⚙️|🌐|💡|💬|🔗|Repository:|Length of output:|Proposed fix$|---$|_?\s*[🔒📐🎯🩺🟡🟠])/u.test(line))
+                                    continue;
+                                kept.push(line.replace(/<\/?[a-z][^>]*>/gi, '').trim());
+                            }
+                            const shown = kept.filter((line) => line !== '').slice(0, 14);
+                            const more = kept.length > shown.length ? ` (+${kept.length - shown.length} more lines)` : '';
+                            report.push(`    ${String(comment.databaseId ?? '')} @${String(comment.author?.login ?? '?')}:${more}`);
+                            for (const line of shown)
+                                report.push(`      ${line.slice(0, 300)}`);
+                        }
+                    }
+                }
+                // A page is not the whole list. Saying which it is is the difference between a report and a guess.
+                const shown = Array.isArray(nodes) ? nodes.length : 0;
+                const counted = data.data?.repository?.pullRequest?.reviewThreads
+                    ?.totalCount;
+                const total = typeof counted === 'number' ? counted : shown;
+                if (total > shown) {
+                    report.push(`... and ${total - shown} more: this asks for the first 50 threads, and the first 10 comments of each`);
+                }
+                return {
+                    number: request.number ?? 0,
+                    url: '',
+                    status: report.length > 0 ? report.join('\n') : 'no review threads on this pull request',
+                };
+            }
+            if (request.action === 'comment') {
+                // A review with no verdict: GitHub shows it as a comment on the pull request, and it needs
+                // only the pull request permission the app already has. A *conversation* comment would be the
+                // issues API, which needs `issues: write` — see the README.
+                await callWithToken('POST', `${collection}/${request.number}/reviews`, token, {
+                    body: request.body ?? '',
+                    event: 'COMMENT',
+                    // An inline comment rides on the same review, so a body-only comment stays one code path.
+                    ...(request.filePath === undefined || request.line === undefined
+                        ? {}
+                        : {
+                            comments: [
+                                {
+                                    path: request.filePath,
+                                    line: request.line,
+                                    // GitHub spells the side in capitals on this endpoint; ours is the readable one.
+                                    side: (request.side ?? 'right').toUpperCase(),
+                                    body: request.body ?? '',
+                                },
+                            ],
+                        }),
+                });
+                const { text: after } = await callWithToken('GET', `${collection}/${request.number}`, token);
+                let read = null;
+                try {
+                    read = JSON.parse(after);
+                }
+                catch {
+                    read = null;
+                }
+                const html = (read ?? {});
+                return {
+                    number: request.number ?? 0,
+                    url: typeof html.html_url === 'string' ? html.html_url : '',
+                };
+            }
+            if (request.action === 'status') {
+                return readPullRequestStatus(request, token, collection);
+            }
+            let text;
+            const method = 'POST';
+            const url = collection;
+            const body = { title: request.title, body: request.body, head: request.head, base: request.base, draft: request.draft === true };
+            try {
+                // as theirs, which is what automated reviewers recognise. The token itself is as wide as that person —
+                // it carries the app permissions and could push and merge — and what is narrow is this code: it is
+                // used for creating and resolving, and every other action stays on the app's installation token.
+                // Creating a pull request as a person, and resolving a review thread: the two things an
+                // installation token is refused for. A token per owner is the older, narrower way and is still
+                // used when there is one; the authorized token answers for every owner at once.
+                // Resolved above, where it also decided whether the app had to be asked at all.
+                ({ text } = await callWithToken(method, url, actingToken ?? token, body));
+            }
+            catch (error) {
+                // A permission sentence is composed here and is worth passing through; the host-only detail, if
+                // the failure carried any, is carried across rather than put in the message the pusher sees.
+                const wrapped = new ProviderConfigError(`${error.message}${describeCause(error)}; this needs the pull_requests: write permission on both the app and this installation`);
+                const detail = error.hostDetail;
+                if (detail !== undefined)
+                    Object.assign(wrapped, { hostDetail: detail });
+                throw wrapped;
+            }
+            let parsed = null;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = null;
+            }
+            const payload = (parsed ?? {});
+            if (typeof payload.number !== 'number' || typeof payload.html_url !== 'string') {
+                throw new ProviderConfigError('GitHub did not answer with a pull request');
+            }
+            return {
+                number: payload.number,
+                url: payload.html_url,
+                state: typeof payload.state === 'string' ? payload.state : undefined,
+                merged: payload.merged === true,
+            };
+        },
+    };
+}
+//# sourceMappingURL=github-app.js.map