canopycms 0.0.68-int.98 → 0.1.0

package/dist/worker/github-gateway.js

@@ -0,0 +1,726 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createCanopyOctokit, createOrUpdatePullRequest, } from '../github-service.js';
+import { getErrorMessage } from '../utils/error.js';
+import { isStaleLeaseRejection, workflowPushRefusalFile } from '../utils/git.js';
+import { isTransientAuthFailure } from './github-auth.js';
+import { GitHubMirror, GitHubTransientError, RefusedPushError, assertPlainBranchName, isObjectId, } from './github-mirror.js';
+import { BranchPolicy, GatewayRefusalError, assertPullRequestText } from './branch-policy.js';
+import { gatewayLog, gatewayLogError, gatewayLogWarn, redactEgress, redactError, redactValue, registerLiveSecret, } from './gateway-egress.js';
+import { GatewayInstance, untilAborted } from './gateway-instance.js';
+/** The most `have` IDs one fetch takes. */
+export const MAX_FETCH_HAVE = 10_000;
+/** How long a completed GitHub fetch is reused: one sync cycle's fetch, reconcile and settings push. */
+const FETCH_COALESCE_MS = 30_000;
+/**
+ * How long a fetched auth snapshot is answered again. Well under the default 15-minute auth-cache
+ * refresh interval, and a worker asking in a loop starts no fetch within it of a success.
+ */
+const AUTH_SNAPSHOT_REUSE_MS = 60_000;
+/**
+ * The longest an operation waits for a credential re-read in flight before it goes on with the
+ * credential it has. A provider can take 87 s for one `getSecret`, and an operation that waited it
+ * out would die at the task deadline for nothing; the task's retry still sees a rotated token, and
+ * a re-read a hostile worker armed cannot hold every push for its length.
+ */
+const REFRESH_JOIN_CAP_MS = 15_000;
+/** The most prerequisites one push names. */
+const MAX_PUSH_PREREQUISITES = 3;
+/** The default cap on a pushed bundle, in bytes. */
+const DEFAULT_MAX_BUNDLE_BYTES = 1024 * 1024 * 1024;
+/**
+ * A push to GitHub failed: `rejected` on the first attempt, `rejected-after-stale-lease` on the
+ * plain retry after GitHub refused a stale lease. The message is the failure's own: git's output,
+ * for a refusal, which the task runner classifies. A {@link RefusedPushError} from the first
+ * attempt is thrown as itself.
+ */
+export class GitHubPushError extends Error {
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = 'GitHubPushError';
+    }
+}
+/** A moved ref for a log line: `<old7>..<new7>`, or `new branch at <new7>`. */
+export function describeMove(update) {
+    const to = update.to.slice(0, 7);
+    return update.from === null ? `new branch at ${to}` : `${update.from.slice(0, 7)}..${to}`;
+}
+/** The in-process {@link GitHubGateway}. */
+export function createLocalGitHubGateway(options) {
+    return new LocalGitHubGateway(options);
+}
+class LocalGitHubGateway {
+    constructor(options) {
+        this.options = options;
+        /** The credential re-read in flight, which every credentialed operation joins. */
+        this.refreshing = null;
+        /** The GitHub fetch that operations join: in flight, or completed and still reusable. */
+        this.githubFetch = null;
+        /** Pushes about to run and branch deletions settled at GitHub: each ends reuse of an earlier fetch. */
+        this.pushes = 0;
+        this.preparing = null;
+        /** The auth snapshot being fetched, which every concurrent caller joins. */
+        this.snapshotFetch = null;
+        /** The last snapshot fetched, and when (`performance.now()`). */
+        this.lastSnapshot = null;
+        this.preflight = 'pending';
+        this.mirror = new GitHubMirror(options.stateDirectory, options.timeoutMs);
+        this.instance = new GatewayInstance(options);
+        this.octokit =
+            options.octokit ??
+                createCanopyOctokit(options.auth.octokitAuth, { warn: gatewayLogWarn, error: gatewayLogError }, 
+                // A token the credential provider rotated or an App minted is scrubbed from the first
+                // request that carries it, before any `credential()` call has registered it.
+                {
+                    onAuthorization: (value) => registerLiveSecret(value.replace(/^(?:token|bearer)\s+/i, '')),
+                });
+        this.policy = new BranchPolicy({
+            baseBranch: options.baseBranch,
+            protectedBranches: options.protectedBranches,
+        });
+    }
+    get repo() {
+        return { owner: this.options.githubOwner, repo: this.options.githubRepo };
+    }
+    /**
+     * Run one operation that uses the credential.
+     *
+     * It first JOINS a re-read in flight, bounded by its own `signal` and by
+     * {@link REFRESH_JOIN_CAP_MS}, so the 5s/10s/20s task retries see a rotated token. Then, if the
+     * operation fails after any of its GitHub-bound git commands or Octokit calls failed, it ARMS a
+     * re-read. Not gated on the failure looking
+     * auth-shaped: a dead token's git failure is a plain exit 128 with no HTTP status, and a token
+     * that lost access fails as a 404 or a 403. What never arms it: a refusal of the gateway's own
+     * (`GatewayRefusalError`, whatever came before it; an invalid object ID), anything else local, a lock file the mirror's own
+     * housekeeping holds (`isOwnLockFailure`), and an Octokit 422 (`api`). A 404 does arm it, the
+     * branch-already-gone one `deleteBranch` callers tolerate included. What bounds a caller that
+     * fails on purpose is the floors behind `auth.refreshCredential`:
+     * `refreshGitHubTokenMinIntervalMs` (github-auth.ts) and the provider's own. On the GitHub App
+     * path a re-read is a no-op.
+     *
+     * The re-read starts detached, after the failure has been delivered: a provider can take 87s for
+     * one `getSecret`, longer than a task's whole deadline.
+     *
+     * What it returns or throws leaves the gateway, so it is scrubbed here (worker/gateway-egress.ts).
+     */
+    async credentialed(signal, operation) {
+        try {
+            await this.joinRefresh(signal);
+            const reach = { failed: false };
+            try {
+                return redactValue(await operation(reach));
+            }
+            catch (err) {
+                if (reach.failed && !(err instanceof GatewayRefusalError))
+                    this.armRefresh();
+                throw err;
+            }
+        }
+        catch (err) {
+            throw redactError(err);
+        }
+    }
+    /**
+     * One Octokit call inside {@link credentialed}, whose failure arms a re-read unless it is a 422.
+     * A 422 is GitHub validating the request, never judging the credential, and the worker treats
+     * two as success: a head branch GitHub already deleted after a merge (`isRefAlreadyGoneError`),
+     * and a pull request with no commits between (`isNoCommitsBetweenError`). Arming on them would
+     * spend the provider's floor on routine traffic and hold off the re-read a real rotation needs.
+     */
+    async api(reach, call) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            if (!(typeof err === 'object' && err !== null && 'status' in err && err.status === 422)) {
+                reach.failed = true;
+            }
+            throw err;
+        }
+    }
+    /**
+     * The credential for one operation's GitHub-bound git, resolved ONCE per operation, so every
+     * command in it carries the same token and a resolution failure cannot replace a git failure
+     * being classified. Async because a GitHub App's installation token is minted on demand and
+     * lasts about an hour, so nothing may cache it. A mint failure propagates as thrown, carrying
+     * the `.status` `isPermanentTaskFailure` classifies on.
+     */
+    async credential(reach) {
+        const { remoteUrl, githubOwner, githubRepo } = this.options;
+        const url = remoteUrl === undefined
+            ? `https://github.com/${githubOwner}/${githubRepo}.git`
+            : typeof remoteUrl === 'string'
+                ? remoteUrl
+                : await remoteUrl();
+        const token = await this.api(reach, () => this.options.auth.resolveGitToken());
+        registerLiveSecret(token);
+        return {
+            url,
+            token,
+            onFailure: () => {
+                reach.failed = true;
+            },
+        };
+    }
+    /**
+     * Wait for a re-read in flight, for at most {@link REFRESH_JOIN_CAP_MS}, unless `signal` aborts
+     * first; past the cap the operation goes on with the credential as it stands.
+     */
+    async joinRefresh(signal) {
+        const inFlight = this.refreshing;
+        if (inFlight === null)
+            return;
+        let timer;
+        const capped = new Promise((resolve) => {
+            timer = setTimeout(resolve, this.options.refreshJoinCapMs ?? REFRESH_JOIN_CAP_MS);
+        });
+        try {
+            await untilAborted(Promise.race([inFlight, capped]), signal);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Bring the mirror up to GitHub, coalesced: join the GitHub fetch in flight, or reuse one that
+     * completed less than {@link FETCH_COALESCE_MS} ago and is still current ({@link isCurrent}), or
+     * else start one with the credential `resolve` gives, resolved only then, so a joining operation
+     * mints no token. A failed fetch is never joined or reused. The fetch is
+     * detached from every caller's `signal`, which ends only that caller's wait: a fetch of a whole
+     * repository can outlast any one caller, and killing it on an abort would start it over each
+     * time. Its own bound is the mirror's inactivity timeout. It runs in a mirror session of its
+     * own, which repairs a corrupt mirror first ({@link GitHubMirror.heal}), and its failure re-reads
+     * the credential when it reached GitHub, whoever started it.
+     */
+    async joinGitHubFetch(resolve, signal) {
+        const current = this.githubFetch;
+        const window = this.options.fetchCoalesceMs ?? FETCH_COALESCE_MS;
+        const reusable = current !== null &&
+            !current.failed &&
+            (current.completedAt === null ||
+                (Date.now() - current.completedAt < window && this.isCurrent(current.snapshot)));
+        const job = reusable ? current : this.startGitHubFetch(resolve);
+        return untilAborted(job.done, signal);
+    }
+    /** Whether the mirror still holds GitHub as the fetch that saw `snapshot` left it. */
+    isCurrent(snapshot) {
+        return (snapshot !== null &&
+            snapshot.generation === this.mirror.generation &&
+            snapshot.pushes === this.pushes);
+    }
+    /**
+     * Run `fn` in a mirror session over what a GitHub fetch put in the mirror: `join` one, and
+     * check inside the session that nothing has changed the mirror or GitHub since
+     * ({@link isCurrent}). A session between the two may have re-created the mirror, leaving no
+     * heads, which would read as GitHub having none, or pushed. When something has, `join` again,
+     * which then fetches afresh; a second miss is transient.
+     */
+    async afterGitHubFetch(join, fn) {
+        for (let attempt = 1;; attempt++) {
+            const snapshot = await join();
+            const result = await this.mirror.exclusive(async (session) => this.isCurrent(snapshot) ? { value: await fn(session) } : null);
+            if (result !== null)
+                return result.value;
+            if (attempt === 2) {
+                throw new GitHubTransientError('github-fetch-failed', 'The GitHub mirror or GitHub changed after each of two GitHub fetches');
+            }
+        }
+    }
+    /** Start a GitHub fetch, taking its place at once, before the credential resolves. */
+    startGitHubFetch(resolve) {
+        let reachedGitHub = false;
+        const run = async () => {
+            const credential = await resolve();
+            const own = {
+                url: credential.url,
+                token: credential.token,
+                onFailure: () => {
+                    reachedGitHub = true;
+                    credential.onFailure();
+                },
+            };
+            const snapshot = await this.mirror.exclusive(async (mirror) => {
+                const pushes = this.pushes;
+                await this.mirror.heal(mirror, own);
+                await this.mirror.fetchFromGitHub(mirror, own);
+                return { generation: this.mirror.generation, pushes };
+            });
+            await this.mirror.afterFetch();
+            return snapshot;
+        };
+        const job = { failed: false, completedAt: null, snapshot: null, done: run() };
+        job.done.then((snapshot) => {
+            job.completedAt = Date.now();
+            job.snapshot = snapshot;
+        }, () => {
+            job.failed = true;
+            if (reachedGitHub)
+                this.armRefresh();
+        });
+        this.githubFetch = job;
+        return job;
+    }
+    /** A push or branch deletion at GitHub: every later read must come from a fetch after it. */
+    invalidateGitHubFetch() {
+        this.pushes++;
+        this.githubFetch = null;
+    }
+    /** Start a re-read on the next turn of the event loop, unless one is already in flight. */
+    armRefresh() {
+        if (this.refreshing !== null)
+            return;
+        const refreshing = new Promise((resolve) => setImmediate(resolve))
+            .then(() => this.refreshCredential())
+            .finally(() => {
+            if (this.refreshing === refreshing)
+                this.refreshing = null;
+        });
+        this.refreshing = refreshing;
+    }
+    prepare() {
+        return (this.preparing ??= this.prepareOnce());
+    }
+    /**
+     * One fetch serves every caller: concurrent callers join it, and its result is answered again
+     * for {@link AUTH_SNAPSHOT_REUSE_MS}. A fetch is a request per user, so a worker asking in a loop
+     * would otherwise hold the provider's API at its rate limit. The fetch runs apart from every
+     * caller's signal, which ends only that caller's wait, so a retry after a timed-out wait joins it.
+     */
+    async authSnapshot(signal) {
+        const provider = this.options.authSnapshot;
+        if (provider === undefined) {
+            throw new Error('The GitHub gateway has no auth provider key configured');
+        }
+        // Before a fetch starts: one no caller waits on would leave its failure unhandled.
+        signal?.throwIfAborted();
+        const reuseMs = this.options.authSnapshotReuseMs ?? AUTH_SNAPSHOT_REUSE_MS;
+        const last = this.lastSnapshot;
+        if (last !== null && performance.now() - last.at < reuseMs)
+            return last.snapshot;
+        // Not `credentialed()`: this never touches GitHub, and a provider failure must not arm the
+        // GitHub credential re-read (the provider's own 401/403 re-read lives with the provider).
+        const fetching = (this.snapshotFetch ??= (async () => provider())()
+            .then((snapshot) => {
+            const scrubbed = redactValue(snapshot);
+            this.lastSnapshot = { snapshot: scrubbed, at: performance.now() };
+            return scrubbed;
+        })
+            .finally(() => {
+            this.snapshotFetch = null;
+        }));
+        try {
+            return await untilAborted(fetching, signal);
+        }
+        catch (err) {
+            throw redactError(err);
+        }
+    }
+    termination(signal) {
+        return this.instance.termination(signal);
+    }
+    completeLifecycle(signal) {
+        return this.instance.completeLifecycle(signal);
+    }
+    async health(signal) {
+        let ready = false;
+        let fatalError = null;
+        if (this.preparing !== null) {
+            try {
+                await untilAborted(this.preparing, signal);
+                ready = true;
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw err;
+                fatalError = redactEgress(getErrorMessage(err));
+            }
+        }
+        return {
+            ready,
+            fatalError,
+            preflight: this.preflight,
+            clerkConfigured: this.options.authSnapshot !== undefined,
+            protectedBranches: this.policy.describe(),
+        };
+    }
+    /**
+     * Fatal: a failed App preflight (unless it looks transient), a state directory inside the
+     * workspace, and one this process cannot create or does not own outright, since no later session
+     * could clear those and the credential is used in the mirror. Not fatal: creating the mirror,
+     * which every session retries ({@link GitHubMirror.exclusive}) while a failure memoized here
+     * would outlast a transient cause (a full disk, a failed git spawn) until the process restarted.
+     */
+    async prepareOnce() {
+        try {
+            // Before the mirror's first fetch, whose failure would otherwise blame the repository.
+            await this.preflightGitHubAppAuth();
+            if (this.options.workspacePath !== undefined) {
+                await this.ensureStateDirectoryIsPrivate(this.options.workspacePath);
+            }
+            await this.mirror.assertStateDirectory();
+        }
+        catch (err) {
+            throw redactError(err);
+        }
+        try {
+            await this.mirror.ensure();
+        }
+        catch (err) {
+            gatewayLogWarn(`Could not create the GitHub mirror at startup (${redactEgress(getErrorMessage(err))}); ` +
+                'the next operation tries again');
+        }
+        // The first GitHub fetch starts now, detached, so the first operation that needs one joins
+        // it under way. Its failure surfaces to whoever joins it.
+        if (this.options.prefetch === false)
+            return;
+        void this.credentialed(undefined, (reach) => this.joinGitHubFetch(() => this.credential(reach))).catch(() => undefined);
+    }
+    /**
+     * Prove a GitHub App credential works, failing startup UNLESS THE FAILURE POSITIVELY LOOKS
+     * TRANSIENT. Not always fatal, so the two credential paths degrade alike: on the token path a
+     * GitHub 502 at boot is absorbed and the loops retry, where rethrowing would crash-loop an App
+     * worker until GitHub recovered, each time telling the operator to check the key. Fail CLOSED,
+     * through `isTransientAuthFailure` rather than the inverse of `isPermanentTaskFailure`, which
+     * defaults a status-less error to transient: a key too mangled to sign with fails locally and
+     * status-lessly, and would otherwise boot a worker on a dead credential with no
+     * `lastFatalError`. No-op on the token path, where the first real request checks as much.
+     */
+    async preflightGitHubAppAuth() {
+        if (!this.options.githubApp) {
+            this.preflight = 'not-an-app';
+            return;
+        }
+        try {
+            registerLiveSecret(await this.options.auth.resolveGitToken());
+        }
+        catch (err) {
+            // [REDACT] Both messages below reach worker-status.json and the browser.
+            const detail = redactEgress(getErrorMessage(err));
+            if (isTransientAuthFailure(err)) {
+                this.preflight = 'unverified';
+                gatewayLogWarn(`Could not verify GitHub App authentication at startup: ${detail}. ` +
+                    'Continuing — this looks transient, and the credential is minted again on first use.');
+                return;
+            }
+            // Re-thrown with context, unlike credential(): nothing classifies a startup failure.
+            throw new Error(`GitHub App authentication failed: ${detail}. ` +
+                'Check the app id, the installation id, and that the private key belongs to that app.');
+        }
+        this.preflight = 'verified';
+        gatewayLog('GitHub App authentication verified');
+    }
+    /**
+     * Refuse a state directory on the shared filesystem: the mirror there would be as writable by
+     * the Lambda as remote.git is.
+     */
+    async ensureStateDirectoryIsPrivate(workspacePath) {
+        const workspace = await realpathOfNearest(workspacePath);
+        const state = await realpathOfNearest(this.options.stateDirectory);
+        const relative = path.relative(workspace, state);
+        if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) {
+            throw new Error(`The worker's state directory (${this.options.stateDirectory}) is inside its shared workspace ` +
+                `(${workspacePath}). It holds the repository the GitHub credential is used ` +
+                `in, so it must be somewhere the CMS Lambda cannot write.`);
+        }
+    }
+    defaultBranch(signal) {
+        return this.credentialed(signal, async (reach) => {
+            const name = await this.policy.recordGitHubDefault(() => this.readDefaultBranch(reach, signal));
+            if (name === null)
+                throw new Error('GitHub reported no default branch');
+            return name;
+        });
+    }
+    /** Reads GitHub's default branch with git, in a mirror session, never through Octokit. */
+    isProtectedBranch(branch, signal) {
+        return this.credentialed(signal, (reach) => this.policy.isProtected(branch, async () => {
+            const credential = await this.credential(reach);
+            // A session can wait behind a whole-repository fetch; an abort ends only this wait.
+            return untilAborted(this.mirror.exclusive((session) => session.githubDefaultBranch(credential, signal)), signal);
+        }));
+    }
+    /**
+     * GitHub's default branch, through the API, for the policy's operations outside a mirror
+     * session; a push reads it with git, inside its session (`MirrorSession.pushToGitHub`).
+     */
+    async readDefaultBranch(reach, signal) {
+        const { data } = await this.api(reach, () => this.octokit.repos.get({ ...this.repo, ...(signal ? { request: { signal } } : {}) }));
+        return data.default_branch;
+    }
+    /** Validate a pull request's head and base, and apply the policy to its head and text. */
+    async assertPullRequestAllowed(reach, request, signal) {
+        const git = await this.mirror.checkGit();
+        await assertPlainBranchName(request.head, git, 'pull-request');
+        // The base is GitHub's to validate and the policy's to leave alone (BranchPolicy), and may be
+        // a configured name outside branchNameProblem's narrower set: git's rules, the length cap and
+        // no leading `-` only.
+        await assertPlainBranchName(request.base, git, 'pull-request', false);
+        await this.policy.assertPullRequestAllowed(request, () => this.readDefaultBranch(reach, signal));
+    }
+    async fetch(request, signal, onProgress) {
+        const stopWatching = onProgress === undefined ? null : this.mirror.watchActivity(onProgress);
+        try {
+            return await this.fetchOnce(request, signal);
+        }
+        finally {
+            stopWatching?.();
+        }
+    }
+    fetchOnce(request, signal) {
+        const have = [...new Set(request.have)];
+        if (have.length > MAX_FETCH_HAVE) {
+            throw new Error(`A fetch takes at most ${MAX_FETCH_HAVE} have IDs, not ${have.length}`);
+        }
+        for (const id of have)
+            assertObjectId(id);
+        return this.credentialed(signal, (reach) => this.afterGitHubFetch(() => this.joinGitHubFetch(() => this.credential(reach), signal), async (mirror) => {
+            this.mirror.assertUsable();
+            const refs = await mirror.heads();
+            const file = await this.mirror.outgoingBundlePath();
+            const created = await mirror.createBundle(have, file, signal);
+            const bundleId = await this.mirror.setPendingBundle(created ? file : null);
+            return { refs, bundleId };
+        }));
+    }
+    openBundle(bundleId) {
+        return this.mirror.openBundle(bundleId);
+    }
+    push(request, bundle, signal) {
+        return this.credentialed(signal, (reach) => this.pushOnce(request, bundle, reach, signal)).finally(
+        // A refusal can come before the body is read: never leave its writer blocked.
+        () => bundle?.destroy());
+    }
+    async pushOnce(request, bundle, reach, signal) {
+        assertObjectId(request.sha, 'a commit ID');
+        if (request.lease !== undefined)
+            assertObjectId(request.lease, 'a commit ID');
+        if (request.prerequisites.length > MAX_PUSH_PREREQUISITES) {
+            throw new Error(`A push names at most ${MAX_PUSH_PREREQUISITES} prerequisites`);
+        }
+        for (const id of request.prerequisites)
+            assertObjectId(id, 'a commit ID');
+        // Before `branch` reaches anything else: the bundle's expected head, a refspec.
+        await assertPlainBranchName(request.branch, await this.mirror.checkGit());
+        // Every attempt, and a GitHub fetch this push starts, carries this one credential (see
+        // credential()), resolved once and only when first needed.
+        let resolved = null;
+        const credential = () => (resolved ??= this.credential(reach));
+        // The join comes before the session, never inside it: the fetch takes a session of its own,
+        // and sessions are not re-entrant. So does resolving the credential, so the session never
+        // waits on GitHub's API. A body is read first, so its writer is not left waiting.
+        const session = (received) => this.afterGitHubFetch(async () => {
+            const snapshot = await this.joinGitHubFetchForPush(credential, request.branch, signal);
+            await credential();
+            return snapshot;
+        }, async (mirror) => this.pushInSession(mirror, await credential(), request, received, signal));
+        return bundle === undefined
+            ? session(null)
+            : this.mirror.ingest(bundle, request, this.maxBundleBytes, session);
+    }
+    /**
+     * The plan's step 2 (§3.2): the push goes ahead only once a GitHub fetch has SUCCEEDED, fresh or
+     * reused, so the mirror's heads are GitHub's for the reachability test and the prerequisite
+     * check; otherwise it is transient. A token mint GitHub refuses is the exception: it carries its HTTP
+     * status through, so the task runner classifies it. That is the whole clause: a mirror with no heads after a
+     * successful fetch means GitHub has none, a first push.
+     */
+    async joinGitHubFetchForPush(credential, branch, signal) {
+        try {
+            return await this.joinGitHubFetch(credential, signal);
+        }
+        catch (err) {
+            // An HTTP failure is the credential's own (a mint refused), classified by its status.
+            if (err instanceof GitHubTransientError || hasHttpStatus(err))
+                throw err;
+            // [REDACT] The message reaches the task's lastError.
+            throw new GitHubTransientError('github-fetch-failed', `Could not fetch from GitHub before pushing ${branch}: ` +
+                redactEgress(getErrorMessage(err)).trim());
+        }
+    }
+    get maxBundleBytes() {
+        return this.options.maxBundleBytes ?? DEFAULT_MAX_BUNDLE_BYTES;
+    }
+    /**
+     * The push, in one mirror session, every call in it a plain call (the session is not
+     * re-entrant), over the mirror a GitHub fetch just filled ({@link afterGitHubFetch}), so its
+     * heads are GitHub's for the reachability test and the prerequisite check: find `sha`, in the
+     * mirror or in the quarantine `received` goes into; push from there, which refuses a protected
+     * branch first. The mirror kills its git when `signal` aborts, and GitHub moves the ref only
+     * after receiving the whole pack, so a killed push changes nothing or is found already done by
+     * the re-run, unless git's transport child outlives it
+     * (safeinsights/canopycms#907).
+     */
+    async pushInSession(mirror, credential, request, received, signal) {
+        const { branch, sha } = request;
+        // Never fires: finding corruption changes the generation, so afterGitHubFetch never runs this
+        // over a mirror found corrupt after its fetch. It refuses rather than push from a corrupt one.
+        this.mirror.assertUsable();
+        const heads = await mirror.heads();
+        let repo;
+        if (received === null) {
+            const type = (await mirror.objectTypes([sha])).get(sha);
+            if (type === 'missing')
+                return this.needObjects(mirror, request);
+            if (type !== 'commit')
+                throw new RefusedPushError(branch, 'not-a-commit', sha);
+            if (!(await mirror.reachableFromHeads(sha)))
+                return this.needObjects(mirror, request);
+        }
+        else {
+            repo = await mirror.quarantine(received, request, heads, signal);
+        }
+        const attempt = (lease) => mirror.pushToGitHub(credential, branch, sha, {
+            lease,
+            signal,
+            repo,
+            policy: this.policy,
+            // Whatever the push does to GitHub, a fetch reused from before it may not show it.
+            onPushing: () => this.invalidateGitHubFetch(),
+        });
+        try {
+            return { kind: 'pushed', ...(await attempt(request.lease)), pastStaleLease: false };
+        }
+        catch (err) {
+            if (err instanceof RefusedPushError || err instanceof GitHubTransientError)
+                throw err;
+            const message = getErrorMessage(err);
+            // A refused lease means GitHub is not at the commit the lease names, which is routine: a
+            // task re-runs after a crash, and the marker it came from survives any failure to clear
+            // it. So retry PLAIN and let git adjudicate: a non-forced push succeeds only as a
+            // fast-forward, so it can destroy nothing. git evaluates a lease only when it has an
+            // update to apply, so an up-to-date ref never gets here. A workflow refusal is final
+            // whatever the lease, so it is not retried.
+            if (request.lease &&
+                isStaleLeaseRejection(message) &&
+                workflowPushRefusalFile(message) === null) {
+                let update;
+                try {
+                    update = await attempt();
+                }
+                catch (retryErr) {
+                    throw new GitHubPushError('rejected-after-stale-lease', getErrorMessage(retryErr));
+                }
+                return { kind: 'pushed', ...update, pastStaleLease: true };
+            }
+            throw new GitHubPushError('rejected', message);
+        }
+    }
+    async needObjects(mirror, request) {
+        return { kind: 'need-objects', usable: await mirror.usablePrerequisites(request.prerequisites) };
+    }
+    createPullRequest(request, signal) {
+        return this.credentialed(signal, async (reach) => {
+            await this.assertPullRequestAllowed(reach, request, signal);
+            const { data } = await this.api(reach, () => this.octokit.pulls.create({ ...this.repo, ...request, request: { signal } }));
+            return { number: data.number, url: data.html_url };
+        });
+    }
+    updatePullRequest(number, update, signal) {
+        return this.credentialed(signal, async (reach) => {
+            assertPullRequestText(`Refusing to update pull request #${number}`, `#${number}`, update);
+            await this.api(reach, () => this.octokit.pulls.update({
+                ...this.repo,
+                pull_number: number,
+                ...update,
+                request: { signal },
+            }));
+        });
+    }
+    getPullRequest(number, signal) {
+        return this.credentialed(signal, (reach) => this.pullRequest(reach, number, signal));
+    }
+    async pullRequest(reach, number, signal) {
+        const { data } = await this.api(reach, () => this.octokit.pulls.get({ ...this.repo, pull_number: number, request: { signal } }));
+        return data;
+    }
+    createOrUpdatePullRequest(request, signal) {
+        return this.credentialed(signal, async (reach) => {
+            await this.assertPullRequestAllowed(reach, request, signal);
+            return this.api(reach, () => createOrUpdatePullRequest({
+                octokit: this.octokit,
+                ...this.repo,
+                ...request,
+                signal,
+                warn: gatewayLogWarn,
+            }));
+        });
+    }
+    convertPullRequestToDraft(number, signal) {
+        return this.credentialed(signal, async (reach) => {
+            // The REST API cannot convert a PR to a draft; GraphQL can.
+            const pr = await this.pullRequest(reach, number, signal);
+            await this.api(reach, () => this.octokit.graphql(`mutation($id: ID!) { convertPullRequestToDraft(input: { pullRequestId: $id }) { pullRequest { isDraft } } }`, { id: pr.node_id, request: { signal } }));
+        });
+    }
+    deleteBranch(branch, signal) {
+        return this.credentialed(signal, async (reach) => {
+            await assertPlainBranchName(branch, await this.mirror.checkGit(), 'delete');
+            await this.policy.assertDeleteAllowed(branch, () => this.readDefaultBranch(reach, signal));
+            // Once the call has settled, when GitHub may have acted: any fetch before then, a fetch whose
+            // session ran during the call included, may still show the branch.
+            try {
+                await this.api(reach, () => this.octokit.git.deleteRef({ ...this.repo, ref: `heads/${branch}`, request: { signal } }));
+            }
+            finally {
+                this.invalidateGitHubFetch();
+            }
+        });
+    }
+    /**
+     * Re-read the credential, for {@link armRefresh}. Every consumer reads the credential per use,
+     * so a re-read repairs all of them for their next use. Never throws: the failure that armed it
+     * has already been reported. Bounded by the timeout, because every credentialed operation joins
+     * it and a provider may have no bound of its own. A losing read is not cancelled, but
+     * `auth.refreshCredential` discards a result older than one already applied.
+     */
+    async refreshCredential() {
+        let timer;
+        const timedOut = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`the re-read did not settle within ${this.options.timeoutMs}ms`)), this.options.timeoutMs);
+        });
+        try {
+            await Promise.race([this.options.auth.refreshCredential(), timedOut]);
+            // The token path's rotated token is scrubbed before any operation uses it. On the App path
+            // the re-read is a no-op, so there is nothing new to scrub.
+            if (!this.options.githubApp)
+                registerLiveSecret(await this.options.auth.resolveGitToken());
+        }
+        catch (err) {
+            logFailedCredentialRefresh(err);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+function logFailedCredentialRefresh(err) {
+    // [REDACT] The message can name the secret and, on a malformed-secret path, quote what was read.
+    gatewayLogError('Failed to re-read the GitHub credential after a failure:', redactEgress(getErrorMessage(err)));
+}
+/** Refuse anything but a full object ID, before it can reach git. */
+function assertObjectId(value, what = 'an object ID') {
+    if (!isObjectId(value))
+        throw new Error(`Not ${what}: ${JSON.stringify(value.slice(0, 80))}`);
+}
+/** `target` with symlinks resolved as far as it exists, so a link cannot hide where it lands. */
+async function realpathOfNearest(target) {
+    const missing = [];
+    let current = path.resolve(target);
+    for (;;) {
+        try {
+            return path.join(await fs.realpath(current), ...missing.reverse());
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return path.resolve(target);
+            missing.push(path.basename(current));
+            current = parent;
+        }
+    }
+}
+/** Whether `err` carries an HTTP status, as an Octokit or a token mint's failure does. */
+function hasHttpStatus(err) {
+    return (typeof err === 'object' && err !== null && 'status' in err && typeof err.status === 'number');
+}