@happyvertical/repos 0.84.0 → 0.85.1

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createHmac, createSign, timingSafeEqual } from "node:crypto";
 import { GraphQLClient } from "@happyvertical/graphql";
 import { readFile } from "node:fs/promises";
 import yaml from "js-yaml";
@@ -127,6 +128,704 @@ async function getRepository(options) {
 	}
 }
 //#endregion
+//#region src/forge/errors.ts
+var ForgeError = class extends Error {
+	provider;
+	code;
+	status;
+	requestId;
+	rateLimit;
+	details;
+	retryable;
+	constructor(message, code, options = {}) {
+		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+		this.name = "ForgeError";
+		this.code = code;
+		this.provider = options.provider;
+		this.status = options.status;
+		this.requestId = options.requestId;
+		this.rateLimit = options.rateLimit;
+		this.details = options.details;
+		this.retryable = options.retryable ?? false;
+	}
+};
+var ForgeSignatureError = class extends ForgeError {
+	constructor(message = "Forge webhook signature is invalid") {
+		super(message, "SIGNATURE_INVALID");
+		this.name = "ForgeSignatureError";
+	}
+};
+//#endregion
+//#region src/github/forge.ts
+function repositoryPath(owner, repo) {
+	return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+}
+function normalizeRepository(data) {
+	const owner = data.owner?.login ?? "";
+	const name = typeof data.name === "string" ? data.name : "";
+	return {
+		id: data.node_id === void 0 ? void 0 : String(data.node_id),
+		owner,
+		name,
+		fullName: typeof data.full_name === "string" ? data.full_name : `${owner}/${name}`,
+		defaultBranch: typeof data.default_branch === "string" ? data.default_branch : void 0,
+		private: typeof data.private === "boolean" ? data.private : void 0,
+		url: typeof data.html_url === "string" ? data.html_url : void 0
+	};
+}
+function normalizePullRequest(data) {
+	const head = data.head ?? {};
+	const base = data.base ?? {};
+	return {
+		id: data.node_id === void 0 ? void 0 : String(data.node_id),
+		number: Number(data.number),
+		state: data.state === "closed" ? "closed" : "open",
+		draft: typeof data.draft === "boolean" ? data.draft : void 0,
+		headSha: String(head.sha ?? ""),
+		headRef: typeof head.ref === "string" ? head.ref : void 0,
+		baseSha: typeof base.sha === "string" ? base.sha : void 0,
+		baseRef: typeof base.ref === "string" ? base.ref : void 0,
+		merged: typeof data.merged === "boolean" ? data.merged : void 0,
+		mergeCommitSha: typeof data.merge_commit_sha === "string" ? data.merge_commit_sha : void 0,
+		url: typeof data.html_url === "string" ? data.html_url : void 0
+	};
+}
+function normalizeStatus(data) {
+	return {
+		id: String(data.id ?? data.node_id ?? ""),
+		sha: String(data.sha ?? ""),
+		state: String(data.state ?? ""),
+		context: String(data.context ?? ""),
+		description: typeof data.description === "string" ? data.description : void 0,
+		targetUrl: typeof data.target_url === "string" ? data.target_url : void 0,
+		createdAt: typeof data.created_at === "string" ? new Date(data.created_at) : void 0,
+		raw: data
+	};
+}
+function normalizeCheck(data) {
+	return {
+		id: String(data.id ?? data.node_id ?? ""),
+		name: String(data.name ?? ""),
+		headSha: String(data.head_sha ?? ""),
+		status: data.status ?? "queued",
+		conclusion: typeof data.conclusion === "string" ? data.conclusion : void 0,
+		detailsUrl: typeof data.details_url === "string" ? data.details_url : void 0,
+		externalId: typeof data.external_id === "string" ? data.external_id : void 0,
+		startedAt: typeof data.started_at === "string" ? new Date(data.started_at) : void 0,
+		completedAt: typeof data.completed_at === "string" ? new Date(data.completed_at) : void 0,
+		raw: data
+	};
+}
+function checkInput(input) {
+	return {
+		..."name" in input ? { name: input.name } : {},
+		..."headSha" in input ? { head_sha: input.headSha } : {},
+		status: input.status,
+		conclusion: input.conclusion,
+		details_url: input.detailsUrl,
+		external_id: input.externalId,
+		started_at: input.startedAt instanceof Date ? input.startedAt.toISOString() : input.startedAt,
+		completed_at: input.completedAt instanceof Date ? input.completedAt.toISOString() : input.completedAt,
+		output: input.output
+	};
+}
+/**
+* Repository-scoped GitHub implementation of provider-neutral forge operations.
+* Every operation may throw `ForgeError` for transport or provider failures.
+*/
+var GitHubForgeProvider = class {
+	transport;
+	path;
+	/**
+	* Creates a repository-scoped GitHub forge provider.
+	* @param options Repository coordinates and authenticated transport.
+	*/
+	constructor(options) {
+		this.transport = options.transport;
+		this.path = repositoryPath(options.owner, options.repo);
+	}
+	/** @returns Normalized repository data and request metadata. */
+	async getRepository() {
+		const response = await this.transport.request({
+			method: "GET",
+			path: this.path
+		});
+		return {
+			...response,
+			data: normalizeRepository(response.data)
+		};
+	}
+	/**
+	* Returns one normalized pull request.
+	* @param number Repository-local pull-request number.
+	* @returns Pull-request data and request metadata.
+	* @throws {ForgeError} When GitHub rejects the request.
+	*/
+	async getPullRequest(number) {
+		const response = await this.transport.request({
+			method: "GET",
+			path: `${this.path}/pulls/${number}`
+		});
+		return {
+			...response,
+			data: normalizePullRequest(response.data)
+		};
+	}
+	/**
+	* Lists every raw provider review for one pull request.
+	* @param number Repository-local pull-request number.
+	* @returns All reviews and final-page request metadata.
+	*/
+	listPullRequestReviews(number) {
+		return this.paginate(`${this.path}/pulls/${number}/reviews`, (data) => data);
+	}
+	/**
+	* Returns one raw provider commit payload.
+	* @param sha Exact commit SHA.
+	* @returns Commit payload and request metadata.
+	*/
+	getCommit(sha) {
+		return this.transport.request({
+			method: "GET",
+			path: `${this.path}/commits/${encodeURIComponent(sha)}`
+		});
+	}
+	/**
+	* Returns complete normalized commit-status history.
+	* @param sha Exact commit SHA.
+	* @returns All status pages and final-page request metadata.
+	*/
+	async listCommitStatuses(sha) {
+		return this.paginate(`${this.path}/commits/${encodeURIComponent(sha)}/statuses`, (data) => data.map(normalizeStatus));
+	}
+	/**
+	* Publishes one commit status.
+	* @param input Exact SHA and status attributes.
+	* @returns Published status and request metadata.
+	*/
+	async createCommitStatus(input) {
+		const response = await this.transport.request({
+			method: "POST",
+			path: `${this.path}/statuses/${encodeURIComponent(input.sha)}`,
+			body: {
+				state: input.state,
+				context: input.context,
+				description: input.description,
+				target_url: input.targetUrl
+			}
+		});
+		return {
+			...response,
+			data: normalizeStatus(response.data)
+		};
+	}
+	/**
+	* Returns all normalized check runs, including reruns.
+	* @param sha Exact commit SHA.
+	* @returns All check pages and final-page request metadata.
+	*/
+	async listCheckRuns(sha) {
+		return this.paginate(`${this.path}/commits/${encodeURIComponent(sha)}/check-runs?filter=all`, (data) => (data.check_runs ?? []).map(normalizeCheck), (data) => data.total_count);
+	}
+	/**
+	* Publishes one check run.
+	* @param input Check identity, exact head SHA, state, and output.
+	* @returns Published check and request metadata.
+	*/
+	async createCheckRun(input) {
+		const response = await this.transport.request({
+			method: "POST",
+			path: `${this.path}/check-runs`,
+			body: checkInput(input)
+		});
+		return {
+			...response,
+			data: normalizeCheck(response.data)
+		};
+	}
+	/**
+	* Changes one check run by provider ID.
+	* @param id GitHub check-run ID.
+	* @param input Attributes to change.
+	* @returns Updated check and request metadata.
+	*/
+	async updateCheckRun(id, input) {
+		const response = await this.transport.request({
+			method: "PATCH",
+			path: `${this.path}/check-runs/${encodeURIComponent(id)}`,
+			body: checkInput(input)
+		});
+		return {
+			...response,
+			data: normalizeCheck(response.data)
+		};
+	}
+	/**
+	* Lists raw deployment payloads using narrow filters.
+	* @param options Optional SHA, environment, and result limit.
+	* @returns Matching deployments and request metadata.
+	*/
+	listDeployments(options = {}) {
+		const params = new URLSearchParams();
+		if (options.sha) params.set("sha", options.sha);
+		if (options.environment) params.set("environment", options.environment);
+		params.set("per_page", String(options.limit ?? 30));
+		return this.transport.request({
+			method: "GET",
+			path: `${this.path}/deployments?${params}`
+		});
+	}
+	/**
+	* Returns one raw deployment payload.
+	* @param id GitHub deployment ID.
+	* @returns Deployment payload and request metadata.
+	*/
+	getDeployment(id) {
+		return this.transport.request({
+			method: "GET",
+			path: `${this.path}/deployments/${encodeURIComponent(id)}`
+		});
+	}
+	async paginate(path, items, totalCount) {
+		const separator = path.includes("?") ? "&" : "?";
+		const collected = [];
+		let page = 1;
+		let response;
+		let providerTotal;
+		do {
+			response = await this.transport.request({
+				method: "GET",
+				path: `${path}${separator}per_page=100&page=${page}`
+			});
+			const pageItems = items(response.data);
+			collected.push(...pageItems);
+			providerTotal ??= totalCount?.(response.data);
+			page += 1;
+			if (pageItems.length < 100) break;
+		} while (providerTotal === void 0 || collected.length < providerTotal);
+		return {
+			data: collected,
+			metadata: {
+				...response.metadata,
+				pagination: {
+					pages: page - 1,
+					totalCount: providerTotal ?? collected.length
+				}
+			}
+		};
+	}
+};
+//#endregion
+//#region src/github/transport.ts
+function optionalInteger(value) {
+	if (value === null || value.trim() === "") return void 0;
+	const parsed = Number.parseInt(value, 10);
+	return Number.isFinite(parsed) ? parsed : void 0;
+}
+function responseRateLimit(headers) {
+	const limit = optionalInteger(headers.get("x-ratelimit-limit"));
+	const remaining = optionalInteger(headers.get("x-ratelimit-remaining"));
+	const used = optionalInteger(headers.get("x-ratelimit-used"));
+	const reset = optionalInteger(headers.get("x-ratelimit-reset"));
+	const retryAfter = optionalInteger(headers.get("retry-after"));
+	if (limit === void 0 && remaining === void 0 && used === void 0 && reset === void 0 && retryAfter === void 0) return;
+	return {
+		limit,
+		remaining,
+		used,
+		resetAt: reset === void 0 ? void 0 : /* @__PURE__ */ new Date(reset * 1e3),
+		retryAfterMs: retryAfter === void 0 ? void 0 : Math.max(0, retryAfter * 1e3)
+	};
+}
+function errorCode(status, rateLimit) {
+	if (status === 401) return "AUTHENTICATION_FAILED";
+	if (status === 404) return "NOT_FOUND";
+	if (status === 422) return "INVALID_INPUT";
+	if (status === 429 || status === 403 && (rateLimit?.remaining === 0 || rateLimit?.retryAfterMs !== void 0)) return "RATE_LIMITED";
+	return "PROVIDER_ERROR";
+}
+var GitHubTransport = class {
+	token;
+	baseUrl;
+	fetchImplementation;
+	/**
+	* Creates a GitHub REST transport with fixed or lazy credentials.
+	* @param options Token source, provider URL, and fetch override.
+	*/
+	constructor(options) {
+		this.token = options.token;
+		this.baseUrl = (options.baseUrl ?? "https://api.github.com").replace(/\/+$/, "");
+		this.fetchImplementation = options.fetch ?? globalThis.fetch;
+	}
+	/**
+	* Executes one GitHub REST request.
+	* @param request Method, provider-relative path, body, headers, and signal.
+	* @returns Parsed data and metadata for this exact request.
+	* @throws {ForgeError} For transport, authentication, rate, or provider failures.
+	*/
+	async request(request) {
+		const token = typeof this.token === "function" ? await this.token() : this.token;
+		let response;
+		try {
+			response = await this.fetchImplementation(`${this.baseUrl}${request.path}`, {
+				method: request.method,
+				headers: {
+					Accept: "application/vnd.github+json",
+					Authorization: `Bearer ${token}`,
+					"Content-Type": "application/json",
+					"X-GitHub-Api-Version": "2022-11-28",
+					...request.headers
+				},
+				body: request.body === void 0 ? void 0 : JSON.stringify(request.body),
+				signal: request.signal
+			});
+		} catch (cause) {
+			throw new ForgeError("GitHub transport request failed", "TRANSPORT_ERROR", {
+				cause,
+				provider: "github",
+				retryable: true
+			});
+		}
+		const requestId = response.headers.get("x-github-request-id") ?? void 0;
+		const rateLimit = responseRateLimit(response.headers);
+		const metadata = {
+			provider: "github",
+			requestId,
+			status: response.status,
+			rateLimit
+		};
+		let text;
+		try {
+			text = response.status === 204 ? "" : await response.text();
+		} catch (cause) {
+			throw new ForgeError("GitHub transport response body failed", "TRANSPORT_ERROR", {
+				cause,
+				provider: "github",
+				status: response.status,
+				requestId,
+				rateLimit,
+				retryable: true
+			});
+		}
+		let data;
+		try {
+			data = text === "" ? void 0 : JSON.parse(text);
+		} catch {
+			data = text;
+		}
+		if (!response.ok) {
+			const code = errorCode(response.status, rateLimit);
+			throw new ForgeError(`GitHub API error: ${typeof data === "object" && data !== null && "message" in data && typeof data.message === "string" ? data.message : response.statusText}`, code, {
+				provider: "github",
+				status: response.status,
+				requestId,
+				rateLimit,
+				details: data,
+				retryable: code === "RATE_LIMITED" || response.status >= 500
+			});
+		}
+		return {
+			data,
+			metadata
+		};
+	}
+};
+//#endregion
+//#region src/github/app.ts
+function base64UrlJson(value) {
+	return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+/**
+* Creates a short-lived GitHub App JWT without mutating process credentials.
+* @param credentials GitHub App ID and RSA private key.
+* @param now Clock value used for issued-at and expiry claims.
+* @returns Signed RS256 GitHub App JWT.
+* @throws {ForgeError} When credentials are missing or the key cannot sign.
+*/
+function createGitHubAppJwt(credentials, now = /* @__PURE__ */ new Date()) {
+	if (!credentials.appId || !credentials.privateKey) throw new ForgeError("GitHub App id and private key are required", "CONFIGURATION_ERROR", { provider: "github" });
+	const issuedAt = Math.floor(now.getTime() / 1e3) - 60;
+	const unsigned = `${base64UrlJson({
+		alg: "RS256",
+		typ: "JWT"
+	})}.${base64UrlJson({
+		iat: issuedAt,
+		exp: issuedAt + 600,
+		iss: String(credentials.appId)
+	})}`;
+	try {
+		const signer = createSign("RSA-SHA256");
+		signer.update(unsigned);
+		signer.end();
+		return `${unsigned}.${signer.sign(credentials.privateKey, "base64url")}`;
+	} catch (cause) {
+		throw new ForgeError("GitHub App private key could not sign a JWT", "CONFIGURATION_ERROR", {
+			cause,
+			provider: "github"
+		});
+	}
+}
+/**
+* Request/job-scoped GitHub App authority.
+*
+* Keep this object inside a single request or job. Its token cache and in-flight
+* acquisitions are instance fields, so installations cannot share credentials.
+*/
+var GitHubAppAuth = class {
+	credentials;
+	baseUrl;
+	fetchImplementation;
+	now;
+	expirySkewMs;
+	tokens = /* @__PURE__ */ new Map();
+	issuedTokens = /* @__PURE__ */ new Map();
+	tokenRequests = /* @__PURE__ */ new Map();
+	authorizationRequests = /* @__PURE__ */ new Map();
+	revokedInstallations = /* @__PURE__ */ new Set();
+	nextTokenGeneration = 1;
+	/**
+	* Creates isolated GitHub App authority from credentials and dependencies.
+	* @param options Credentials, clock, provider URL, and fetch override.
+	*/
+	constructor(options) {
+		this.credentials = {
+			appId: options.appId,
+			privateKey: options.privateKey
+		};
+		this.baseUrl = options.baseUrl;
+		this.fetchImplementation = options.fetch;
+		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+		this.expirySkewMs = options.expirySkewMs ?? 6e4;
+	}
+	/**
+	* Clears locally cached credentials without remote revocation.
+	* @param installationId Optional installation to clear; omitted clears all.
+	* @returns Nothing.
+	*/
+	clear(installationId) {
+		if (installationId === void 0) {
+			this.tokens.clear();
+			this.issuedTokens.clear();
+			this.tokenRequests.clear();
+			this.authorizationRequests.clear();
+			this.revokedInstallations.clear();
+			return;
+		}
+		const id = String(installationId);
+		this.clearCachedInstallation(id);
+		this.revokedInstallations.delete(id);
+	}
+	/**
+	* Acquires and verifies one installation/repository boundary.
+	* @param scope Installation ID and exact repository coordinates.
+	* @returns An isolated forge provider and revocation handle.
+	* @throws {ForgeError} When authentication, provider access, or scope fails.
+	*/
+	async createInstallationContext(scope) {
+		const installationId = String(scope.installationId);
+		const fullName = `${scope.owner}/${scope.repo}`.toLowerCase();
+		await this.getAuthorizedToken(installationId, fullName);
+		let active = true;
+		let revocationInFlight;
+		const token = () => {
+			if (!active) throw new ForgeError("GitHub installation context has been revoked", "AUTHENTICATION_FAILED", { provider: "github" });
+			return this.getAuthorizedToken(installationId, fullName);
+		};
+		const forge = new GitHubForgeProvider({
+			owner: scope.owner,
+			repo: scope.repo,
+			transport: new GitHubTransport({
+				token,
+				baseUrl: this.baseUrl,
+				fetch: this.fetchImplementation
+			})
+		});
+		return {
+			installation: { id: installationId },
+			repository: {
+				owner: scope.owner,
+				name: scope.repo,
+				fullName: `${scope.owner}/${scope.repo}`
+			},
+			forge,
+			revoke: async () => {
+				active = false;
+				if (!revocationInFlight) revocationInFlight = this.revokeInstallationTokens(installationId).finally(() => {
+					revocationInFlight = void 0;
+				});
+				await revocationInFlight;
+			}
+		};
+	}
+	async getAuthorizedToken(installationId, fullName) {
+		if (this.revokedInstallations.has(installationId)) throw new ForgeError("GitHub App installation authority has been revoked", "AUTHENTICATION_FAILED", { provider: "github" });
+		const cached = await this.getInstallationToken(installationId);
+		if (this.revokedInstallations.has(installationId)) throw new ForgeError("GitHub App installation authority has been revoked", "AUTHENTICATION_FAILED", { provider: "github" });
+		if (cached.authorizedRepositories.has(fullName)) return cached.token;
+		const key = `${installationId}:${cached.generation}:${fullName}`;
+		let pending = this.authorizationRequests.get(key);
+		if (!pending) {
+			pending = this.verifyRepositoryScope(cached, fullName).finally(() => {
+				this.authorizationRequests.delete(key);
+			});
+			this.authorizationRequests.set(key, pending);
+		}
+		await pending;
+		if (this.revokedInstallations.has(installationId)) throw new ForgeError("GitHub App installation authority has been revoked", "AUTHENTICATION_FAILED", { provider: "github" });
+		return cached.token;
+	}
+	async getInstallationToken(installationId) {
+		const cached = this.tokens.get(installationId);
+		if (cached && cached.expiresAt - this.expirySkewMs > this.now().getTime()) return cached;
+		let pending = this.tokenRequests.get(installationId);
+		if (!pending) {
+			pending = this.acquireInstallationToken(installationId).finally(() => {
+				this.tokenRequests.delete(installationId);
+			});
+			this.tokenRequests.set(installationId, pending);
+		}
+		return pending;
+	}
+	async acquireInstallationToken(installationId) {
+		const response = await new GitHubTransport({
+			token: () => createGitHubAppJwt(this.credentials, this.now()),
+			baseUrl: this.baseUrl,
+			fetch: this.fetchImplementation
+		}).request({
+			method: "POST",
+			path: `/app/installations/${encodeURIComponent(installationId)}/access_tokens`
+		});
+		const token = response.data.token;
+		const expiresAt = Date.parse(response.data.expires_at ?? "");
+		if (!token || !Number.isFinite(expiresAt)) throw new ForgeError("GitHub returned an invalid installation token", "AUTHENTICATION_FAILED", {
+			provider: "github",
+			requestId: response.metadata.requestId
+		});
+		const cached = {
+			token,
+			expiresAt,
+			generation: this.nextTokenGeneration,
+			authorizedRepositories: /* @__PURE__ */ new Set()
+		};
+		this.nextTokenGeneration += 1;
+		const issued = this.issuedTokens.get(installationId) ?? /* @__PURE__ */ new Map();
+		for (const [issuedToken, issuedExpiry] of issued) if (issuedExpiry <= this.now().getTime()) issued.delete(issuedToken);
+		issued.set(token, expiresAt);
+		this.issuedTokens.set(installationId, issued);
+		if (this.revokedInstallations.has(installationId)) {
+			try {
+				await this.revokeToken(token);
+				issued.delete(token);
+			} catch (cause) {
+				const providerError = cause instanceof ForgeError ? cause : void 0;
+				throw new ForgeError("A GitHub token acquired during revocation could not be revoked", "PROVIDER_ERROR", {
+					cause,
+					provider: "github",
+					status: providerError?.status,
+					requestId: providerError?.requestId,
+					rateLimit: providerError?.rateLimit,
+					retryable: providerError?.retryable
+				});
+			}
+			throw new ForgeError("GitHub App installation authority was revoked during token acquisition", "AUTHENTICATION_FAILED", { provider: "github" });
+		}
+		this.tokens.set(installationId, cached);
+		return cached;
+	}
+	async verifyRepositoryScope(cached, fullName) {
+		const transport = new GitHubTransport({
+			token: cached.token,
+			baseUrl: this.baseUrl,
+			fetch: this.fetchImplementation
+		});
+		const separator = fullName.indexOf("/");
+		const owner = fullName.slice(0, separator);
+		const repo = fullName.slice(separator + 1);
+		try {
+			await transport.request({
+				method: "GET",
+				path: `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`
+			});
+		} catch (cause) {
+			const providerError = cause instanceof ForgeError ? cause : void 0;
+			if (providerError?.retryable || providerError?.code === "AUTHENTICATION_FAILED" || providerError?.code === "TRANSPORT_ERROR" || providerError?.status !== 403 && providerError?.status !== 404) throw cause;
+			throw new ForgeError(`GitHub App installation is not authorized for ${fullName}`, "AUTHORITY_MISMATCH", {
+				cause,
+				provider: "github",
+				status: providerError?.status,
+				requestId: providerError?.requestId,
+				rateLimit: providerError?.rateLimit
+			});
+		}
+		cached.authorizedRepositories.add(fullName);
+	}
+	async revokeInstallationTokens(installationId) {
+		this.revokedInstallations.add(installationId);
+		const issued = [...this.issuedTokens.get(installationId)?.keys() ?? []];
+		this.clearCachedInstallation(installationId, false);
+		if (issued.length === 0) return;
+		const retained = this.issuedTokens.get(installationId) ?? /* @__PURE__ */ new Map();
+		const failures = [];
+		for (const token of issued) try {
+			await this.revokeToken(token);
+			retained.delete(token);
+		} catch (error) {
+			failures.push(error);
+		}
+		if (retained.size === 0) this.issuedTokens.delete(installationId);
+		else this.issuedTokens.set(installationId, retained);
+		if (failures.length > 0) {
+			const failure = failures[0];
+			const providerError = failure instanceof ForgeError ? failure : void 0;
+			throw new ForgeError("One or more GitHub installation tokens could not be revoked", "PROVIDER_ERROR", {
+				cause: failure,
+				provider: "github",
+				status: providerError?.status,
+				requestId: providerError?.requestId,
+				rateLimit: providerError?.rateLimit,
+				retryable: providerError?.retryable
+			});
+		}
+	}
+	async revokeToken(token) {
+		await new GitHubTransport({
+			token,
+			baseUrl: this.baseUrl,
+			fetch: this.fetchImplementation
+		}).request({
+			method: "DELETE",
+			path: "/installation/token"
+		});
+	}
+	clearCachedInstallation(installationId, clearIssued = true) {
+		this.tokens.delete(installationId);
+		if (clearIssued) this.issuedTokens.delete(installationId);
+		this.tokenRequests.delete(installationId);
+		for (const key of this.authorizationRequests.keys()) if (key.startsWith(`${installationId}:`)) this.authorizationRequests.delete(key);
+	}
+};
+//#endregion
+//#region src/github/fixtures.ts
+/**
+* Produces exact, repeatable webhook bytes and headers for integration suites.
+* Pass the same delivery id for duplicates, or a new id with the same payload
+* for a provider redelivery.
+* @param options Secret, delivery identity, event name, and payload.
+* @returns Exact bytes and matching GitHub delivery headers.
+*/
+function createGitHubWebhookFixture(options) {
+	const rawBody = new TextEncoder().encode(JSON.stringify(options.payload));
+	const signature = createHmac("sha256", options.secret).update(rawBody).digest("hex");
+	return {
+		rawBody,
+		headers: {
+			"x-github-delivery": options.deliveryId,
+			"x-github-event": options.event,
+			"x-hub-signature-256": `sha256=${signature}`
+		}
+	};
+}
+//#endregion
 //#region src/github/rest.ts
 /**
 * GitHub REST API client
@@ -488,6 +1187,111 @@ var GitHubRepository = class {
 		}
 	}
 	/**
+	* Publishes one GitHub commit status.
+	* @param input Exact commit SHA and status attributes.
+	* @returns Normalized published status.
+	*/
+	async createCommitStatus(input) {
+		const data = await this.rest.post(`/repos/${this.owner}/${this.repo}/statuses/${encodeURIComponent(input.sha)}`, {
+			state: input.state,
+			context: input.context,
+			description: input.description,
+			target_url: input.targetUrl
+		});
+		return this.mapCommitStatus(data);
+	}
+	/**
+	* Returns complete commit-status history across GitHub pages.
+	* @param sha Exact commit SHA.
+	* @returns Every normalized status for the commit.
+	*/
+	async listCommitStatuses(sha) {
+		const statuses = [];
+		let page = 1;
+		while (true) {
+			const data = await this.rest.get(`/repos/${this.owner}/${this.repo}/commits/${encodeURIComponent(sha)}/statuses?per_page=100&page=${page}`);
+			statuses.push(...data.map((status) => this.mapCommitStatus(status)));
+			if (data.length < 100) return statuses;
+			page += 1;
+		}
+	}
+	/**
+	* Publishes one GitHub check run.
+	* @param input Check identity, exact head SHA, state, and output.
+	* @returns Normalized published check run.
+	*/
+	async createCheckRun(input) {
+		const data = await this.rest.post(`/repos/${this.owner}/${this.repo}/check-runs`, this.mapCheckRunInput(input));
+		return this.mapCheckRun(data);
+	}
+	/**
+	* Changes one GitHub check run.
+	* @param id GitHub check-run ID.
+	* @param input Attributes to change.
+	* @returns Normalized updated check run.
+	*/
+	async updateCheckRun(id, input) {
+		const data = await this.rest.patch(`/repos/${this.owner}/${this.repo}/check-runs/${encodeURIComponent(id)}`, this.mapCheckRunInput(input));
+		return this.mapCheckRun(data);
+	}
+	/**
+	* Returns complete GitHub check history, including reruns.
+	* @param sha Exact commit SHA.
+	* @returns Every normalized check run for the commit.
+	*/
+	async listCheckRuns(sha) {
+		const checkRuns = [];
+		let page = 1;
+		let totalCount;
+		while (true) {
+			const data = await this.rest.get(`/repos/${this.owner}/${this.repo}/commits/${encodeURIComponent(sha)}/check-runs?filter=all&per_page=100&page=${page}`);
+			const pageRuns = data.check_runs ?? [];
+			totalCount ??= data.total_count;
+			checkRuns.push(...pageRuns.map((checkRun) => this.mapCheckRun(checkRun)));
+			if (pageRuns.length < 100 || totalCount !== void 0 && checkRuns.length >= totalCount) return checkRuns;
+			page += 1;
+		}
+	}
+	mapCommitStatus(data) {
+		return {
+			id: String(data.id ?? data.node_id ?? ""),
+			sha: String(data.sha ?? ""),
+			state: String(data.state ?? ""),
+			context: String(data.context ?? ""),
+			description: typeof data.description === "string" ? data.description : void 0,
+			targetUrl: typeof data.target_url === "string" ? data.target_url : void 0,
+			createdAt: typeof data.created_at === "string" ? new Date(data.created_at) : void 0,
+			raw: data
+		};
+	}
+	mapCheckRunInput(input) {
+		return {
+			..."name" in input ? { name: input.name } : {},
+			..."headSha" in input ? { head_sha: input.headSha } : {},
+			status: input.status,
+			conclusion: input.conclusion,
+			details_url: input.detailsUrl,
+			external_id: input.externalId,
+			started_at: input.startedAt instanceof Date ? input.startedAt.toISOString() : input.startedAt,
+			completed_at: input.completedAt instanceof Date ? input.completedAt.toISOString() : input.completedAt,
+			output: input.output
+		};
+	}
+	mapCheckRun(data) {
+		return {
+			id: String(data.id ?? data.node_id ?? ""),
+			name: String(data.name ?? ""),
+			headSha: String(data.head_sha ?? ""),
+			status: data.status ?? "queued",
+			conclusion: typeof data.conclusion === "string" ? data.conclusion : void 0,
+			detailsUrl: typeof data.details_url === "string" ? data.details_url : void 0,
+			externalId: typeof data.external_id === "string" ? data.external_id : void 0,
+			startedAt: typeof data.started_at === "string" ? new Date(data.started_at) : void 0,
+			completedAt: typeof data.completed_at === "string" ? new Date(data.completed_at) : void 0,
+			raw: data
+		};
+	}
+	/**
 	* Create a new repository from this repository as a template.
 	*
 	* Uses the GitHub "Generate" API: POST /repos/{template_owner}/{template_repo}/generate
@@ -512,6 +1316,298 @@ var GitHubRepository = class {
 	}
 };
 //#endregion
+//#region src/github/webhooks.ts
+function headerValue(headers, requestedName) {
+	if (headers instanceof Headers) return headers.get(requestedName) ?? void 0;
+	const requested = requestedName.toLowerCase();
+	for (const [name, value] of Object.entries(headers)) {
+		if (name.toLowerCase() !== requested) continue;
+		return typeof value === "string" ? value : value?.[0];
+	}
+}
+function object(value) {
+	return typeof value === "object" && value !== null ? value : {};
+}
+function optionalString(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+function actor(value) {
+	const data = object(value);
+	const login = optionalString(data.login);
+	if (!login) return void 0;
+	return {
+		id: data.id === void 0 ? void 0 : String(data.id),
+		login,
+		type: optionalString(data.type)
+	};
+}
+function repository(value) {
+	const data = object(value);
+	const ownerData = object(data.owner);
+	const fullName = optionalString(data.full_name);
+	const name = optionalString(data.name);
+	const owner = optionalString(ownerData.login);
+	if (!name || !owner && !fullName) return void 0;
+	const resolvedOwner = owner ?? fullName?.split("/")[0] ?? "";
+	return {
+		id: data.node_id === void 0 ? void 0 : String(data.node_id),
+		owner: resolvedOwner,
+		name,
+		fullName: fullName ?? `${resolvedOwner}/${name}`,
+		defaultBranch: optionalString(data.default_branch),
+		private: typeof data.private === "boolean" ? data.private : void 0,
+		url: optionalString(data.html_url)
+	};
+}
+function installation(value) {
+	const data = object(value);
+	if (data.id === void 0) return void 0;
+	const accountData = object(data.account);
+	return {
+		id: String(data.id),
+		account: optionalString(accountData.login),
+		repositorySelection: data.repository_selection === "all" || data.repository_selection === "selected" ? data.repository_selection : void 0
+	};
+}
+function pullRequest(value) {
+	const data = object(value);
+	const head = object(data.head);
+	const base = object(data.base);
+	return {
+		id: data.node_id === void 0 ? void 0 : String(data.node_id),
+		number: Number(data.number),
+		state: data.state === "closed" ? "closed" : "open",
+		draft: typeof data.draft === "boolean" ? data.draft : void 0,
+		headSha: String(head.sha ?? ""),
+		headRef: optionalString(head.ref),
+		baseSha: optionalString(base.sha),
+		baseRef: optionalString(base.ref),
+		merged: typeof data.merged === "boolean" ? data.merged : void 0,
+		mergeCommitSha: optionalString(data.merge_commit_sha),
+		url: optionalString(data.html_url)
+	};
+}
+function check(value) {
+	const data = object(value);
+	const app = object(data.app);
+	return {
+		id: String(data.id ?? data.node_id ?? ""),
+		name: String(data.name ?? app.name ?? "check_suite"),
+		headSha: String(data.head_sha ?? ""),
+		status: data.status ?? "queued",
+		conclusion: typeof data.conclusion === "string" ? data.conclusion : void 0,
+		detailsUrl: optionalString(data.details_url),
+		externalId: optionalString(data.external_id),
+		startedAt: optionalString(data.started_at) ? new Date(String(data.started_at)) : void 0,
+		completedAt: optionalString(data.completed_at) ? new Date(String(data.completed_at)) : void 0,
+		raw: data
+	};
+}
+function occurrence(payload) {
+	const candidates = [
+		object(payload.review).submitted_at,
+		object(payload.check_run).completed_at,
+		object(payload.check_run).started_at,
+		payload.created_at,
+		object(payload.status).created_at,
+		object(payload.deployment_status).created_at,
+		object(payload.deployment).created_at,
+		object(payload.pull_request).updated_at,
+		object(payload.head_commit).timestamp
+	];
+	for (const candidate of candidates) {
+		if (typeof candidate !== "string") continue;
+		const timestamp = new Date(candidate);
+		if (!Number.isNaN(timestamp.getTime())) return timestamp;
+	}
+}
+function normalizeObservation(event, payload, action) {
+	if (event === "ping") return {
+		kind: "availability",
+		available: true,
+		message: optionalString(payload.zen)
+	};
+	if (event === "installation" || event === "installation_repositories") {
+		const installationRef = installation(payload.installation);
+		if (!installationRef) return { kind: "unknown" };
+		return {
+			kind: "installation",
+			installation: installationRef,
+			repositories: [
+				...Array.isArray(payload.repositories) ? payload.repositories : [],
+				...Array.isArray(payload.repositories_added) ? payload.repositories_added : [],
+				...Array.isArray(payload.repositories_removed) ? payload.repositories_removed : []
+			].map(repository).filter((item) => item !== void 0)
+		};
+	}
+	if (event === "repository") {
+		const repositoryRef = repository(payload.repository);
+		return repositoryRef ? {
+			kind: "repository",
+			repository: repositoryRef
+		} : { kind: "unknown" };
+	}
+	if (event === "pull_request") {
+		const pullRequestRef = pullRequest(payload.pull_request);
+		return action === "closed" && pullRequestRef.merged ? {
+			kind: "merge",
+			pullRequest: pullRequestRef,
+			mergeCommitSha: pullRequestRef.mergeCommitSha
+		} : {
+			kind: "pull_request",
+			pullRequest: pullRequestRef
+		};
+	}
+	if (event === "pull_request_review") {
+		const review = object(payload.review);
+		return {
+			kind: "review",
+			pullRequest: pullRequest(payload.pull_request),
+			review: {
+				id: String(review.id ?? review.node_id ?? ""),
+				state: String(review.state ?? ""),
+				body: optionalString(review.body),
+				commitSha: optionalString(review.commit_id),
+				submittedAt: optionalString(review.submitted_at) ? new Date(String(review.submitted_at)) : void 0,
+				author: actor(review.user)
+			}
+		};
+	}
+	if (event === "push") return {
+		kind: "push",
+		ref: String(payload.ref ?? ""),
+		beforeSha: optionalString(payload.before),
+		afterSha: String(payload.after ?? ""),
+		forced: typeof payload.forced === "boolean" ? payload.forced : void 0,
+		created: typeof payload.created === "boolean" ? payload.created : void 0,
+		deleted: typeof payload.deleted === "boolean" ? payload.deleted : void 0
+	};
+	if (event === "status") return {
+		kind: "status",
+		status: {
+			id: String(payload.id ?? ""),
+			sha: String(payload.sha ?? ""),
+			state: String(payload.state ?? ""),
+			context: String(payload.context ?? ""),
+			description: optionalString(payload.description),
+			targetUrl: optionalString(payload.target_url),
+			createdAt: optionalString(payload.created_at) ? new Date(String(payload.created_at)) : void 0,
+			raw: payload
+		}
+	};
+	if (event === "check_run" || event === "check_suite") return {
+		kind: "check",
+		check: check(payload.check_run ?? payload.check_suite)
+	};
+	if (event === "merge_group") {
+		const mergeGroup = object(payload.merge_group);
+		return {
+			kind: "merge_group",
+			headSha: String(mergeGroup.head_sha ?? ""),
+			headRef: optionalString(mergeGroup.head_ref),
+			baseSha: optionalString(mergeGroup.base_sha),
+			baseRef: optionalString(mergeGroup.base_ref)
+		};
+	}
+	if (event === "deployment" || event === "deployment_status") {
+		const deployment = object(payload.deployment);
+		const deploymentStatus = object(payload.deployment_status);
+		return {
+			kind: "deployment",
+			deployment: {
+				id: String(deployment.id ?? ""),
+				sha: optionalString(deployment.sha),
+				ref: optionalString(deployment.ref),
+				environment: optionalString(deploymentStatus.environment) ?? optionalString(deployment.environment),
+				state: optionalString(deploymentStatus.state),
+				url: optionalString(deploymentStatus.environment_url) ?? optionalString(deploymentStatus.target_url)
+			}
+		};
+	}
+	return { kind: "unknown" };
+}
+/**
+* Normalizes one already-verified GitHub payload.
+* @param deliveryId Stable provider delivery identity.
+* @param event GitHub event header value.
+* @param raw Parsed provider payload.
+* @param receivedAt Local receipt timestamp.
+* @returns A provider-neutral event envelope preserving the parsed payload.
+*/
+function normalizeGitHubWebhook(deliveryId, event, raw, receivedAt = /* @__PURE__ */ new Date()) {
+	const payload = object(raw);
+	const action = optionalString(payload.action);
+	return {
+		provider: "github",
+		deliveryId,
+		event,
+		action,
+		occurredAt: occurrence(payload),
+		receivedAt,
+		installation: installation(payload.installation),
+		repository: repository(payload.repository),
+		actor: actor(payload.sender),
+		observation: normalizeObservation(event, payload, action),
+		raw
+	};
+}
+var GitHubWebhookVerifier = class {
+	secrets;
+	now;
+	/**
+	* Creates a verifier with a current secret and optional rotation secrets.
+	* @param options Current/rotation secrets and optional clock.
+	* @throws {ForgeError} When no non-empty secret is configured.
+	*/
+	constructor(options) {
+		this.secrets = typeof options.secrets === "string" ? [options.secrets] : [...options.secrets];
+		if (this.secrets.length === 0 || this.secrets.some((secret) => !secret)) throw new ForgeError("At least one non-empty GitHub webhook secret is required", "CONFIGURATION_ERROR", { provider: "github" });
+		this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+	}
+	/**
+	* Verifies unchanged provider bytes with constant-time comparisons.
+	* @param rawBody Exact bytes received from the HTTP server.
+	* @param signature GitHub SHA-256 signature header.
+	* @returns Index of the configured secret that matched.
+	* @throws {ForgeSignatureError} When the signature is missing or invalid.
+	*/
+	verify(rawBody, signature) {
+		if (!signature?.startsWith("sha256=")) throw new ForgeSignatureError();
+		const suppliedHex = signature.slice(7);
+		if (!/^[a-fA-F0-9]{64}$/.test(suppliedHex)) throw new ForgeSignatureError();
+		const supplied = Buffer.from(suppliedHex, "hex");
+		let matchedIndex = -1;
+		this.secrets.forEach((secret, index) => {
+			if (timingSafeEqual(createHmac("sha256", secret).update(rawBody).digest(), supplied)) matchedIndex = index;
+		});
+		if (matchedIndex === -1) throw new ForgeSignatureError();
+		return matchedIndex;
+	}
+	/**
+	* Verifies raw bytes before decoding and normalizes the delivery.
+	* @param rawBody Exact bytes received from the HTTP server.
+	* @param headers Case-insensitive GitHub delivery headers.
+	* @returns Verified normalized delivery.
+	* @throws {ForgeError} For invalid signatures, headers, UTF-8, or JSON.
+	*/
+	verifyAndNormalize(rawBody, headers) {
+		this.verify(rawBody, headerValue(headers, "x-hub-signature-256"));
+		const deliveryId = headerValue(headers, "x-github-delivery");
+		const event = headerValue(headers, "x-github-event");
+		if (!deliveryId || !event) throw new ForgeError("GitHub delivery identity and event headers are required", "INVALID_INPUT", { provider: "github" });
+		let payload;
+		try {
+			payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(rawBody));
+		} catch (cause) {
+			throw new ForgeError("GitHub webhook body is not valid UTF-8 JSON", "INVALID_INPUT", {
+				cause,
+				provider: "github"
+			});
+		}
+		return normalizeGitHubWebhook(deliveryId, event, payload, this.now());
+	}
+};
+//#endregion
 //#region src/parsing.ts
 /**
 * Issue body parsing and rendering utilities
@@ -738,6 +1834,6 @@ function detectTemplateFromLabels(labels, templates) {
 	return bestMatch;
 }
 //#endregion
-export { GitHubRepository, RepositoryError, RepositoryErrorCode, detectTemplateFromLabels, fetchIssueTemplates, getIssueField, getRepository, loadIssueTemplate, parseIssueBody, parseIssueTemplate, renderIssueBody, updateIssueField };
+export { ForgeError, ForgeSignatureError, GitHubAppAuth, GitHubForgeProvider, GitHubRepository, GitHubTransport, GitHubWebhookVerifier, RepositoryError, RepositoryErrorCode, createGitHubAppJwt, createGitHubWebhookFixture, detectTemplateFromLabels, fetchIssueTemplates, getIssueField, getRepository, loadIssueTemplate, normalizeGitHubWebhook, parseIssueBody, parseIssueTemplate, renderIssueBody, updateIssueField };
 
 //# sourceMappingURL=index.js.map