@theholocron/github-client 1.19.0 → 1.21.0

package/README.md

@@ -90,3 +90,37 @@ A consumer owns what to _do_ with a verified delivery — which event
 categories matter, how to normalize them into its own domain shape.
 `@theholocron/sentinel`'s `parseWebhookEvent()` is the reference
 consumer.
+
+## GitHub App authentication
+
+A signed App JWT, exchanged for a short-lived installation access token,
+exchanged for a ready-to-use `GitHubClient` — Web Crypto only
+(`globalThis.crypto`/`CryptoKey`, no `node:crypto`), so it runs unchanged
+on Cloudflare Workers (no `nodejs_compat` flag needed) and in Node.
+
+```ts
+import { createInstallationClient } from "@theholocron/github-client";
+
+const client = await createInstallationClient(
+  { appId: process.env.GITHUB_APP_ID!, privateKey: process.env.GITHUB_APP_PRIVATE_KEY! },
+  installationId // from the webhook payload that triggered this — never hardcoded (D10)
+);
+const repo = await client.repos.getRepo("owner/name");
+```
+
+`privateKey` accepts either PEM format GitHub hands out — PKCS#1 (an
+`RSA PRIVATE KEY`-headered PEM block, the default download) or PKCS#8
+(a plain `PRIVATE KEY`-headered PEM block); `importRsaPrivateKey`
+(internal) wraps a PKCS#1 key in the PKCS#8 DER structure
+`SubtleCrypto.importKey()` requires — Web Crypto only accepts PKCS#8
+directly.
+
+Lower-level pieces, if you need to manage the installation token's
+lifetime yourself (it lasts about an hour) rather than fetching one per
+call:
+
+- `createAppJWT(creds)` — signs the App-level JWT (not installation-scoped; only good for requesting an installation token, never for calling the REST API directly).
+- `getInstallationAccessToken(creds, installationId)` — exchanges that JWT for `{ token, expiresAt }`.
+
+`@theholocron/sentinel`'s webhook handler is the reference consumer —
+one App, N installations across N orgs/accounts, the same registration.

package/dist/index.d.mts

@@ -255,6 +255,34 @@ interface WorkflowRunFilter {
   status?: string;
 }
 //#endregion
+//#region src/app-auth/app-auth.d.ts
+interface GitHubAppCredentials {
+  /** The App's numeric id (not the client id). */
+  appId: string;
+  /** PEM-encoded RSA private key — PKCS#1 (GitHub's default download format) or PKCS#8, either works. */
+  privateKey: string;
+}
+interface InstallationAccessToken {
+  token: string;
+  /** ISO 8601 — installation tokens are short-lived, about an hour. */
+  expiresAt: string;
+}
+/**
+ * Signs a JWT identifying this App (not a specific installation) — the
+ * credential used only to request an installation access token, never
+ * to call the REST API directly.
+ */
+declare function createAppJWT(creds: GitHubAppCredentials, now?: number): Promise<string>;
+/**
+ * Exchanges an App JWT for an installation access token — the credential
+ * that actually authenticates REST calls, scoped to exactly one
+ * installation (D10: never a hardcoded org — the caller supplies which
+ * installation, from the webhook payload that triggered this).
+ */
+declare function getInstallationAccessToken(creds: GitHubAppCredentials, installationId: number, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<InstallationAccessToken>;
+/** The whole flow in one call — an already-authenticated `GitHubClient` scoped to one installation. */
+declare function createInstallationClient(creds: GitHubAppCredentials, installationId: number, opts?: Pick<GitHubClientOptions, "baseUrl" | "fetch">): Promise<GitHubClient>;
+//#endregion
 //#region src/webhooks/webhooks.d.ts
 /**
  * GitHub's own webhook mechanics — signature verification and header/
@@ -429,4 +457,4 @@ declare function createGitHubClient(opts: GitHubClientOptions): {
 };
 type GitHubClient = ReturnType<typeof createGitHubClient>;
 //#endregion
-export { type CheckRunConclusion, type CheckRunOutput, type CheckRunStatus, type CodeScanningSetupResult, type CreateCheckRunInput, type CreatePagesPayload, type CreatePullInput, type GitBlob, type GitCommit, type GitContents, type GitHubCheckRun, GitHubClient, type GitHubClientOptions, type GitHubContents, type GitHubEnvironment, type GitHubInstallationWebhookPayload, type GitHubIssue, type GitHubLabel, type GitHubMilestone, type GitHubPages, type GitHubPublicKey, type GitHubPullRequest, type GitHubPullRequestWebhookPayload, type GitHubPushWebhookPayload, type GitHubRepo, type GitHubRuleset, type GitHubUser, type GitHubWebhookHeaders, type GitHubWorkflowRun, type GitPull, type GitRef, type GitTree, type GitTreeItem, type IssueSearchParams, type PagesBuildStatus, type PagesBuildType, type SecretScope, type TeamPermission, type UpdatePagesPayload, type WorkflowRunFilter, createGitHubClient, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };
+export { type CheckRunConclusion, type CheckRunOutput, type CheckRunStatus, type CodeScanningSetupResult, type CreateCheckRunInput, type CreatePagesPayload, type CreatePullInput, type GitBlob, type GitCommit, type GitContents, type GitHubAppCredentials, type GitHubCheckRun, GitHubClient, type GitHubClientOptions, type GitHubContents, type GitHubEnvironment, type GitHubInstallationWebhookPayload, type GitHubIssue, type GitHubLabel, type GitHubMilestone, type GitHubPages, type GitHubPublicKey, type GitHubPullRequest, type GitHubPullRequestWebhookPayload, type GitHubPushWebhookPayload, type GitHubRepo, type GitHubRuleset, type GitHubUser, type GitHubWebhookHeaders, type GitHubWorkflowRun, type GitPull, type GitRef, type GitTree, type GitTreeItem, type InstallationAccessToken, type IssueSearchParams, type PagesBuildStatus, type PagesBuildType, type SecretScope, type TeamPermission, type UpdatePagesPayload, type WorkflowRunFilter, createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };

package/dist/index.mjs

@@ -353,6 +353,164 @@ function workflows(rest) {
 	};
 }
 //#endregion
+//#region src/app-auth/pem.ts
+/**
+* PEM/DER handling for GitHub App private keys — Web Crypto only (no
+* `node:crypto`), so this runs unchanged on Cloudflare Workers (no
+* `nodejs_compat` needed) and in Node.
+*
+* GitHub hands out App private keys in PKCS#1 ("-----BEGIN RSA PRIVATE
+* KEY-----") by default; `SubtleCrypto.importKey("pkcs8", …)` only
+* accepts PKCS#8 ("-----BEGIN PRIVATE KEY-----"). `pkcs1ToPkcs8` wraps a
+* PKCS#1 `RSAPrivateKey` DER in the fixed `PrivateKeyInfo` DER structure
+* PKCS#8 requires — a fixed `AlgorithmIdentifier` prefix for
+* `rsaEncryption` (OID 1.2.840.113549.1.1.1) around the unchanged
+* PKCS#1 bytes. Verified against a real generated key pair: imported,
+* signed, and checked against `node:crypto`'s `verify()` on the
+* original key's public half.
+*/
+function pemToDer(pem) {
+	const base64 = pem.replace(/-----BEGIN [^-]+-----/, "").replace(/-----END [^-]+-----/, "").replace(/\s/g, "");
+	return Uint8Array.from(atob(base64), (c) => c.charCodeAt(0));
+}
+function concat(...arrays) {
+	const total = arrays.reduce((sum, a) => sum + a.length, 0);
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const a of arrays) {
+		out.set(a, offset);
+		offset += a.length;
+	}
+	return out;
+}
+function encodeDerLength(len) {
+	/* istanbul ignore next -- see comment above */
+	if (len < 128) return new Uint8Array([len]);
+	const bytes = [];
+	let n = len;
+	while (n > 0) {
+		bytes.unshift(n & 255);
+		n >>= 8;
+	}
+	return new Uint8Array([128 | bytes.length, ...bytes]);
+}
+function derEncode(tag, content) {
+	return concat(new Uint8Array([tag]), encodeDerLength(content.length), content);
+}
+/** SEQUENCE { OID rsaEncryption, NULL } — the fixed PKCS#8 AlgorithmIdentifier for RSA. */
+const RSA_ALGORITHM_IDENTIFIER = new Uint8Array([
+	48,
+	13,
+	6,
+	9,
+	42,
+	134,
+	72,
+	134,
+	247,
+	13,
+	1,
+	1,
+	1,
+	5,
+	0
+]);
+function pkcs1ToPkcs8(pkcs1) {
+	const version = new Uint8Array([
+		2,
+		1,
+		0
+	]);
+	const octetString = derEncode(4, pkcs1);
+	return derEncode(48, concat(version, RSA_ALGORITHM_IDENTIFIER, octetString));
+}
+/** Imports a PEM-encoded RSA private key — PKCS#1 or PKCS#8, either works — for RS256 signing. */
+async function importRsaPrivateKey(pem) {
+	const der = pemToDer(pem);
+	const pkcs8Der = (pem.includes("BEGIN RSA PRIVATE KEY") ? pkcs1ToPkcs8(der) : der).slice();
+	return crypto.subtle.importKey("pkcs8", pkcs8Der, {
+		name: "RSASSA-PKCS1-v1_5",
+		hash: "SHA-256"
+	}, false, ["sign"]);
+}
+/** Base64url (no padding) — the encoding both JWT segments and the signature use. */
+function base64UrlEncode(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+//#endregion
+//#region src/app-auth/app-auth.ts
+/**
+* GitHub App authentication — a signed App JWT, exchanged for a
+* short-lived installation access token, exchanged for a ready-to-use
+* `GitHubClient`. Web Crypto only (see `pem.ts`), so this runs unchanged
+* on Cloudflare Workers and in Node — no vendor-specific JWT library, no
+* `nodejs_compat` flag.
+*
+* https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app
+* https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation
+*/
+const CLOCK_DRIFT_BUFFER_SECONDS = 60;
+/** GitHub rejects an App JWT with more than 10 minutes between iat and exp. */
+const JWT_LIFETIME_SECONDS = 600;
+/**
+* Signs a JWT identifying this App (not a specific installation) — the
+* credential used only to request an installation access token, never
+* to call the REST API directly.
+*/
+async function createAppJWT(creds, now = Date.now()) {
+	const key = await importRsaPrivateKey(creds.privateKey);
+	const iat = Math.floor(now / 1e3) - CLOCK_DRIFT_BUFFER_SECONDS;
+	const exp = iat + JWT_LIFETIME_SECONDS;
+	const signingInput = `${base64UrlEncode(new TextEncoder().encode(JSON.stringify({
+		alg: "RS256",
+		typ: "JWT"
+	})))}.${base64UrlEncode(new TextEncoder().encode(JSON.stringify({
+		iat,
+		exp,
+		iss: creds.appId
+	})))}`;
+	const signature = await crypto.subtle.sign("RSASSA-PKCS1-v1_5", key, new TextEncoder().encode(signingInput));
+	return `${signingInput}.${base64UrlEncode(new Uint8Array(signature))}`;
+}
+/**
+* Exchanges an App JWT for an installation access token — the credential
+* that actually authenticates REST calls, scoped to exactly one
+* installation (D10: never a hardcoded org — the caller supplies which
+* installation, from the webhook payload that triggered this).
+*/
+async function getInstallationAccessToken(creds, installationId, opts = {}) {
+	const jwt = await createAppJWT(creds);
+	const baseUrl = opts.baseUrl ?? "https://api.github.com";
+	const res = await (opts.fetch ?? globalThis.fetch)(`${baseUrl}/app/installations/${installationId}/access_tokens`, {
+		method: "POST",
+		headers: {
+			authorization: `Bearer ${jwt}`,
+			accept: "application/vnd.github+json",
+			"x-github-api-version": "2022-11-28"
+		}
+	});
+	if (!res.ok) {
+		const body = await res.text().catch(() => "");
+		throw new ProviderApiError(`GitHub POST /app/installations/${installationId}/access_tokens → ${res.status}`, res.status, body);
+	}
+	const json = await res.json();
+	return {
+		token: json.token,
+		expiresAt: json.expires_at
+	};
+}
+/** The whole flow in one call — an already-authenticated `GitHubClient` scoped to one installation. */
+async function createInstallationClient(creds, installationId, opts = {}) {
+	const { token } = await getInstallationAccessToken(creds, installationId, opts);
+	return createGitHubClient({
+		token,
+		baseUrl: opts.baseUrl,
+		fetch: opts.fetch
+	});
+}
+//#endregion
 //#region src/webhooks/webhooks.ts
 /**
 * GitHub's own webhook mechanics — signature verification and header/
@@ -423,4 +581,4 @@ function createGitHubClient(opts) {
 	};
 }
 //#endregion
-export { createGitHubClient, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };
+export { createAppJWT, createGitHubClient, createInstallationClient, getInstallationAccessToken, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "1.19.0",
+  "version": "1.21.0",
   "description": "A TypeScript client for the GitHub REST API",
   "keywords": [
     "github",
@@ -33,7 +33,7 @@
   ],
   "dependencies": {
     "@theholocron/observability": "^0.3.0",
-    "@theholocron/http-client": "^1.19.0"
+    "@theholocron/http-client": "^1.21.0"
   },
   "devDependencies": {
     "@theholocron/cli": "5.0.0-alpha.3",