merge-steward 0.27.1 → 0.28.0

package/dist/exec.js

@@ -58,6 +58,25 @@ function shouldRetryWithoutRuntimeGitHubAuth(command, githubEnv, failure) {
     }
     return (failure.stderr ?? "").includes(WORKFLOW_PERMISSION_REJECTION);
 }
+// Markers that indicate GitHub rejected our credentials (stale/expired installation token).
+const AUTH_FAILURE_MARKERS = [
+    "Bad credentials",
+    "Invalid username or token",
+    "Authentication failed",
+    "could not read Username",
+    "401 Unauthorized",
+    "HTTP 401",
+];
+function isGitHubAuthFailure(command, githubEnv, failure) {
+    if (command !== "git" && command !== "gh")
+        return false;
+    if (Object.keys(githubEnv).length === 0)
+        return false;
+    if (failure.timedOut)
+        return false;
+    const text = `${failure.stderr ?? ""}\n${failure.stdout ?? ""}\n${failure.message ?? ""}`;
+    return AUTH_FAILURE_MARKERS.some((marker) => text.includes(marker));
+}
 async function runExecFile(command, args, env, options) {
     return await new Promise((resolve, reject) => {
         execFile(command, args, {
@@ -118,6 +137,25 @@ export async function exec(command, args, options) {
     }
     catch (error) {
         const failure = error;
+        // Self-heal on broken auth: record the failure, proactively re-mint the installation
+        // token, and retry once with a fresh credential before giving up.
+        const repoFullName = options?.githubRepoFullName;
+        if (repoFullName
+            && isGitHubAuthFailure(command, githubEnv, failure)
+            && runtimeGitHubAuthProvider?.refreshTokenForRepo) {
+            runtimeGitHubAuthProvider.recordAuthFailure?.(repoFullName, (failure.stderr ?? failure.message ?? "").slice(0, 200));
+            try {
+                await runtimeGitHubAuthProvider.refreshTokenForRepo(repoFullName, "github_401");
+                const refreshedGithubEnv = resolveGitHubCommandEnv(command, baseEnv, {
+                    githubRepoFullName: repoFullName,
+                    runtimeAuthProvider: runtimeGitHubAuthProvider,
+                });
+                return await runExecFile(command, args, { ...baseEnv, ...refreshedGithubEnv }, options);
+            }
+            catch {
+                // Fall through to the original error / workflow-permission fallback below.
+            }
+        }
         if (!shouldRetryWithoutRuntimeGitHubAuth(command, githubEnv, failure)) {
             throw error;
         }

package/dist/github-auth.d.ts

@@ -14,12 +14,35 @@ export type GitHubAuthConfig = {
 } | {
     mode: "none";
 };
+export type GitHubAuthRefreshReason = "startup" | "scheduled" | "before_use" | "github_401" | "manual";
+export interface GitHubInstallationAuthStatus {
+    installationId: string;
+    repoFullNames: string[];
+    hasToken: boolean;
+    expiresAt: string | null;
+    lastRefreshAt: string | null;
+    lastRefreshError: string | null;
+    fresh: boolean;
+}
+export interface GitHubAuthRuntimeStatus {
+    ready: boolean;
+    lastRefreshAt: string | null;
+    lastRefreshError: string | null;
+    recentAuthFailureCount: number;
+    lastAuthFailureAt: string | null;
+    installations: GitHubInstallationAuthStatus[];
+}
 export interface RuntimeGitHubAuthProvider {
     currentTokenForRepo(repoFullName?: string): string | undefined;
+    refreshTokenForRepo?(repoFullName: string, reason: GitHubAuthRefreshReason): Promise<void>;
+    recordAuthFailure?(repoFullName: string, message: string): void;
 }
 export interface GitHubAppTokenManager extends RuntimeGitHubAuthProvider {
     start(): Promise<void>;
     stop(): void;
+    refreshTokenForRepo(repoFullName: string, reason: GitHubAuthRefreshReason): Promise<void>;
+    recordAuthFailure(repoFullName: string, message: string): void;
+    authStatus(): GitHubAuthRuntimeStatus;
 }
 export declare function generateJwt(appId: string, privateKey: string): string;
 export declare function resolveAppSlug(credentials: GitHubAppCredentials): Promise<string>;

package/dist/github-auth.js

@@ -2,6 +2,9 @@ import { Buffer } from "node:buffer";
 import { createSign } from "node:crypto";
 import { resolveSecretWithSource } from "./resolve-secret.js";
 const TOKEN_REFRESH_MS = 30 * 60_000;
+const TOKEN_EXPIRY_MARGIN_MS = 5 * 60_000;
+const RECENT_AUTH_FAILURE_WINDOW_MS = 15 * 60_000;
+const MAX_AUTH_FAILURES_TO_KEEP = 50;
 export function generateJwt(appId, privateKey) {
     const now = Math.floor(Date.now() / 1000);
     const header = Buffer.from(JSON.stringify({ alg: "RS256", typ: "JWT" })).toString("base64url");
@@ -36,10 +39,7 @@ export async function resolveAppSlug(credentials) {
     return data.slug;
 }
 async function resolveInstallationIdForRepo(jwt, repoFullName) {
-    const encodedRepo = repoFullName
-        .split("/")
-        .map((segment) => encodeURIComponent(segment))
-        .join("/");
+    const encodedRepo = repoFullName.split("/").map((segment) => encodeURIComponent(segment)).join("/");
     const data = await fetchJson(`https://api.github.com/repos/${encodedRepo}/installation`, { headers: githubHeaders(jwt) });
     return String(data.id);
 }
@@ -52,11 +52,11 @@ async function resolveFirstInstallationId(jwt) {
     return String(first.id);
 }
 async function fetchInstallationToken(jwt, installationId) {
-    const data = await fetchJson(`https://api.github.com/app/installations/${installationId}/access_tokens`, {
-        method: "POST",
-        headers: githubHeaders(jwt),
-    });
-    return data.token;
+    const data = await fetchJson(`https://api.github.com/app/installations/${installationId}/access_tokens`, { method: "POST", headers: githubHeaders(jwt) });
+    return {
+        token: data.token,
+        ...(typeof data.expires_at === "string" ? { expiresAt: data.expires_at } : {}),
+    };
 }
 export async function issueGitHubAppToken(credentials, options) {
     const jwt = generateJwt(credentials.appId, credentials.privateKey);
@@ -64,7 +64,7 @@ export async function issueGitHubAppToken(credentials, options) {
         ?? (options?.repoFullName
             ? await resolveInstallationIdForRepo(jwt, options.repoFullName)
             : await resolveFirstInstallationId(jwt));
-    const token = await fetchInstallationToken(jwt, installationId);
+    const { token } = await fetchInstallationToken(jwt, installationId);
     return { installationId, token };
 }
 export function resolveGitHubAppCredentials(env = process.env) {
@@ -85,10 +85,7 @@ export function resolveGitHubAppCredentials(env = process.env) {
 }
 export function resolveGitHubAuthConfig(env = process.env) {
     const app = resolveGitHubAppCredentials(env);
-    if (app) {
-        return { mode: "app", credentials: app };
-    }
-    return { mode: "none" };
+    return app ? { mode: "app", credentials: app } : { mode: "none" };
 }
 function unique(values) {
     return [...new Set(values)];
@@ -97,38 +94,120 @@ export function createGitHubAppTokenManager(credentials, repoFullNames, logger)
     let timer;
     const repoInstallationIds = new Map();
     const installationTokens = new Map();
+    const installationRefreshErrors = new Map();
+    const authFailures = [];
+    let lastRefreshAt = null;
+    let lastRefreshError = null;
+    function rememberInstallationRepo(installationId, repoFullName) {
+        repoInstallationIds.set(repoFullName, installationId);
+    }
+    function reposForInstallation(installationId) {
+        return repoFullNames.filter((repoFullName) => (repoInstallationIds.get(repoFullName) ?? credentials.installationId) === installationId);
+    }
+    function isTokenFresh(token) {
+        if (!token)
+            return false;
+        if (!token.expiresAt)
+            return true;
+        const expiresAtMs = Date.parse(token.expiresAt);
+        if (!Number.isFinite(expiresAtMs))
+            return false;
+        return expiresAtMs - Date.now() > TOKEN_EXPIRY_MARGIN_MS;
+    }
+    function recordRefreshSuccess(installationId, token) {
+        const refreshedAt = new Date().toISOString();
+        installationTokens.set(installationId, {
+            token: token.token,
+            ...(token.expiresAt ? { expiresAt: token.expiresAt } : {}),
+            lastRefreshAt: refreshedAt,
+            lastRefreshError: null,
+        });
+        installationRefreshErrors.delete(installationId);
+        lastRefreshAt = refreshedAt;
+        lastRefreshError = null;
+    }
+    function recordRefreshFailure(installationId, message) {
+        lastRefreshError = message;
+        if (!installationId)
+            return;
+        installationRefreshErrors.set(installationId, message);
+        const existing = installationTokens.get(installationId);
+        if (existing) {
+            installationTokens.set(installationId, { ...existing, lastRefreshError: message });
+        }
+    }
+    async function resolveInstallationForRepo(jwt, repoFullName) {
+        const existing = repoInstallationIds.get(repoFullName) ?? credentials.installationId;
+        if (existing) {
+            rememberInstallationRepo(existing, repoFullName);
+            return existing;
+        }
+        const installationId = await resolveInstallationIdForRepo(jwt, repoFullName);
+        rememberInstallationRepo(installationId, repoFullName);
+        logger.info({ repoFullName, installationId }, "Resolved GitHub App installation for repo");
+        return installationId;
+    }
+    async function refreshInstallation(installationId, jwt, reason) {
+        const token = await fetchInstallationToken(jwt, installationId);
+        recordRefreshSuccess(installationId, token);
+        // Transparency: every rotation is logged so operators can see gh/git auth staying fresh.
+        logger.info({ installationId, expiresAt: token.expiresAt ?? null, reason }, "Rotated GitHub App installation token (gh + git authenticate as the bot with a fresh token)");
+    }
+    function escalateIfDegraded() {
+        const status = authStatus();
+        if (!status.ready) {
+            logger.error({ lastRefreshError: status.lastRefreshError, installations: status.installations }, "GitHub App auth is degraded — gh/git operations will fail until a fresh token is minted");
+        }
+    }
     async function refresh(options) {
         const throwOnError = options?.throwOnError ?? false;
+        const reason = options?.reason ?? "scheduled";
         try {
             const jwt = generateJwt(credentials.appId, credentials.privateKey);
             const installationIds = new Set();
-            if (credentials.installationId) {
+            if (credentials.installationId)
                 installationIds.add(credentials.installationId);
-            }
             for (const repoFullName of repoFullNames) {
-                let installationId = repoInstallationIds.get(repoFullName) ?? credentials.installationId;
-                if (!installationId) {
-                    installationId = await resolveInstallationIdForRepo(jwt, repoFullName);
-                    repoInstallationIds.set(repoFullName, installationId);
-                    logger.info({ repoFullName, installationId }, "Resolved GitHub App installation for repo");
-                }
+                const installationId = await resolveInstallationForRepo(jwt, repoFullName);
                 installationIds.add(installationId);
             }
             for (const installationId of unique(installationIds)) {
-                const token = await fetchInstallationToken(jwt, installationId);
-                installationTokens.set(installationId, token);
-            }
-            if (installationTokens.size === 0 && !credentials.installationId && repoFullNames.length === 0) {
-                logger.warn("GitHub App auth configured, but no repositories are attached yet");
+                try {
+                    await refreshInstallation(installationId, jwt, reason);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    recordRefreshFailure(installationId, message);
+                    if (throwOnError)
+                        throw error;
+                    logger.warn({ installationId, error: message }, "Failed to refresh GitHub App installation token");
+                }
             }
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            if (throwOnError) {
+            recordRefreshFailure(undefined, message);
+            if (throwOnError)
                 throw new Error(`Failed to initialize GitHub App auth: ${message}`);
-            }
             logger.warn({ error: message }, "Failed to refresh GitHub App installation token");
         }
+        finally {
+            escalateIfDegraded();
+        }
+    }
+    async function refreshTokenForRepo(repoFullName, reason) {
+        const jwt = generateJwt(credentials.appId, credentials.privateKey);
+        let installationId;
+        try {
+            installationId = await resolveInstallationForRepo(jwt, repoFullName);
+            await refreshInstallation(installationId, jwt, reason);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            recordRefreshFailure(installationId, message);
+            logger.warn({ repoFullName, installationId, reason, error: message }, "Failed to refresh GitHub App installation token");
+            throw error;
+        }
     }
     function schedule() {
         timer = setTimeout(() => {
@@ -136,29 +215,83 @@ export function createGitHubAppTokenManager(credentials, repoFullNames, logger)
         }, TOKEN_REFRESH_MS);
         timer.unref?.();
     }
+    function recentAuthFailures() {
+        const cutoff = Date.now() - RECENT_AUTH_FAILURE_WINDOW_MS;
+        return authFailures.filter((entry) => Date.parse(entry.at) >= cutoff);
+    }
+    function currentTokenForRepo(repoFullName) {
+        if (repoFullName) {
+            const installationId = repoInstallationIds.get(repoFullName) ?? credentials.installationId;
+            if (installationId) {
+                const token = installationTokens.get(installationId);
+                return token && isTokenFresh(token) ? token.token : undefined;
+            }
+        }
+        if (credentials.installationId) {
+            const token = installationTokens.get(credentials.installationId);
+            return token && isTokenFresh(token) ? token.token : undefined;
+        }
+        const first = installationTokens.values().next();
+        if (first.done)
+            return undefined;
+        const token = first.value;
+        return isTokenFresh(token) ? token.token : undefined;
+    }
+    function authStatus() {
+        const installationIds = unique([
+            ...installationTokens.keys(),
+            ...installationRefreshErrors.keys(),
+            ...(credentials.installationId ? [credentials.installationId] : []),
+            ...repoFullNames.flatMap((repoFullName) => {
+                const installationId = repoInstallationIds.get(repoFullName);
+                return installationId ? [installationId] : [];
+            }),
+        ]);
+        const installations = installationIds.map((installationId) => {
+            const token = installationTokens.get(installationId);
+            const refreshError = token?.lastRefreshError ?? installationRefreshErrors.get(installationId) ?? null;
+            return {
+                installationId,
+                repoFullNames: reposForInstallation(installationId),
+                hasToken: Boolean(token),
+                expiresAt: token?.expiresAt ?? null,
+                lastRefreshAt: token?.lastRefreshAt ?? null,
+                lastRefreshError: refreshError,
+                fresh: isTokenFresh(token) && !refreshError,
+            };
+        });
+        const failures = recentAuthFailures();
+        const missingRepoToken = repoFullNames.some((repoFullName) => !currentTokenForRepo(repoFullName));
+        const tokenRefreshFailing = installations.some((installation) => installation.lastRefreshError !== null && !installation.fresh);
+        return {
+            ready: !missingRepoToken && !tokenRefreshFailing,
+            lastRefreshAt,
+            lastRefreshError,
+            recentAuthFailureCount: failures.length,
+            lastAuthFailureAt: failures.at(-1)?.at ?? null,
+            installations,
+        };
+    }
     return {
         async start() {
-            await refresh({ throwOnError: true });
+            await refresh({ throwOnError: true, reason: "startup" });
             schedule();
         },
         stop() {
-            if (timer) {
+            if (timer)
                 clearTimeout(timer);
-                timer = undefined;
-            }
+            timer = undefined;
         },
-        currentTokenForRepo(repoFullName) {
-            if (repoFullName) {
-                const installationId = repoInstallationIds.get(repoFullName) ?? credentials.installationId;
-                if (installationId) {
-                    return installationTokens.get(installationId);
-                }
-            }
-            if (credentials.installationId) {
-                return installationTokens.get(credentials.installationId);
+        currentTokenForRepo,
+        async refreshTokenForRepo(repoFullName, reason) {
+            await refreshTokenForRepo(repoFullName, reason);
+        },
+        recordAuthFailure(repoFullName, message) {
+            authFailures.push({ repoFullName, message, at: new Date().toISOString() });
+            if (authFailures.length > MAX_AUTH_FAILURES_TO_KEEP) {
+                authFailures.splice(0, authFailures.length - MAX_AUTH_FAILURES_TO_KEEP);
             }
-            const first = installationTokens.values().next();
-            return first.done ? undefined : first.value;
         },
+        authStatus,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "merge-steward",
-  "version": "0.27.1",
+  "version": "0.28.0",
   "description": "Serial merge queue for GitHub — rebase, CI-gate, and merge PRs one at a time",
   "type": "module",
   "repository": {