@theholocron/github-client 1.17.0 → 1.18.0

package/README.md

@@ -51,3 +51,41 @@ const blob = await client.git.createBlob("owner/name", "file contents");
 | `topics`       | `setTopics`                                                                                                                                                                                             |
 | `properties`   | `setProperties`                                                                                                                                                                                         |
 | `git`          | `getRef`, `getCommit`, `getTree`, `getContents`, `createBlob`, `createTree`, `createCommit`, `createRef`, `updateRef`, `createPull`                                                                     |
+
+## Webhooks
+
+GitHub's own inbound-webhook mechanics — signature verification and
+header/payload shapes — as standalone functions, not part of
+`createGitHubClient()`: these verify a _delivery this package's consumer
+received_, not an outbound REST call, so they need a webhook secret
+instead of an API token.
+
+```ts
+import {
+  parseGitHubWebhookHeaders,
+  verifyGitHubWebhookSignature,
+  type GitHubPushWebhookPayload,
+} from "@theholocron/github-client";
+
+const { event, delivery, signature } = parseGitHubWebhookHeaders(req.headers);
+const ok = verifyGitHubWebhookSignature({ body: rawBody, signature, secret: webhookSecret });
+```
+
+`verifyGitHubWebhookSignature({ body, signature, secret })` — `X-Hub-
+Signature-256` verification (HMAC-SHA256 over the raw body,
+`timingSafeEqual`-compared). Returns `false` for any failure to verify
+(empty secret, missing/malformed signature, mismatch) — never throws;
+the caller decides how to surface that.
+
+`parseGitHubWebhookHeaders(headers)` — extracts `event`, `delivery`, and
+`signature` from GitHub's three webhook headers, case-insensitively.
+
+`GitHubInstallationWebhookPayload`, `GitHubPushWebhookPayload`,
+`GitHubPullRequestWebhookPayload` — the delivery body shapes, scoped to
+the fields a consumer reads today (not a full re-typing of every field
+GitHub sends).
+
+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.

package/dist/index.d.mts

@@ -228,6 +228,73 @@ interface WorkflowRunFilter {
   status?: string;
 }
 //#endregion
+//#region src/webhooks/webhooks.d.ts
+/**
+ * GitHub's own webhook mechanics — signature verification and header/
+ * payload shapes. Pure functions, no REST call, no auth token: these
+ * operate on an *inbound* delivery, the mirror of everything else this
+ * package does (outbound REST calls), so they're standalone exports
+ * rather than part of `createGitHubClient()`'s returned object.
+ *
+ * A consumer (a GitHub App receiving webhooks) owns what to *do* with a
+ * verified delivery — which event categories matter, how to normalize
+ * them — the same split `holocron-plugin-clerk`'s `parseWebhook` draws
+ * between Svix verification and Clerk-specific `AuthEvent` normalization,
+ * just with the verification half living here instead of inline, since
+ * "how GitHub signs and shapes a webhook" is vendor knowledge this
+ * package already owns for every other GitHub API surface.
+ */
+/**
+ * Verifies a GitHub webhook delivery's `X-Hub-Signature-256` header —
+ * HMAC-SHA256 over the raw body, keyed by the webhook's configured
+ * secret, `timingSafeEqual`-compared.
+ * https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
+ *
+ * Returns `false` (never throws) for any failure to verify — a missing/
+ * empty secret, a missing/malformed signature header, or a mismatch —
+ * so the caller decides how to surface that (e.g. as its own error type).
+ */
+declare function verifyGitHubWebhookSignature(input: {
+  body: string | Buffer;
+  signature: string | undefined;
+  secret: string;
+}): boolean;
+interface GitHubWebhookHeaders {
+  /** `X-GitHub-Event` — the event category, e.g. `"push"`, `"pull_request"`. */
+  event: string | undefined;
+  /** `X-GitHub-Delivery` — GitHub's per-delivery id, useful for idempotency/logging. */
+  delivery: string | undefined;
+  /** `X-Hub-Signature-256` — pass straight to `verifyGitHubWebhookSignature`. */
+  signature: string | undefined;
+}
+/** Extracts GitHub's three webhook headers, case-insensitively (Node's raw headers may arrive lower-cased, or as an array when a header repeats). */
+declare function parseGitHubWebhookHeaders(headers: Record<string, string | string[] | undefined>): GitHubWebhookHeaders;
+interface GitHubInstallationWebhookPayload {
+  action: string;
+  installation: {
+    id: number;
+  };
+}
+interface GitHubPushWebhookPayload {
+  ref: string;
+  installation?: {
+    id: number;
+  };
+  repository: {
+    full_name: string;
+    default_branch: string;
+  };
+}
+interface GitHubPullRequestWebhookPayload {
+  action: string;
+  installation?: {
+    id: number;
+  };
+  repository: {
+    full_name: string;
+  };
+}
+//#endregion
 //#region src/index.d.ts
 declare function createGitHubClient(opts: GitHubClientOptions): {
   branches: {
@@ -332,4 +399,4 @@ declare function createGitHubClient(opts: GitHubClientOptions): {
 };
 type GitHubClient = ReturnType<typeof createGitHubClient>;
 //#endregion
-export { type CodeScanningSetupResult, type CreatePagesPayload, type CreatePullInput, type GitBlob, type GitCommit, type GitContents, GitHubClient, type GitHubClientOptions, type GitHubContents, type GitHubEnvironment, type GitHubIssue, type GitHubLabel, type GitHubMilestone, type GitHubPages, type GitHubPublicKey, type GitHubPullRequest, type GitHubRepo, type GitHubRuleset, type GitHubUser, 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 };
+export { type CodeScanningSetupResult, type CreatePagesPayload, type CreatePullInput, type GitBlob, type GitCommit, type GitContents, 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 };

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { ProviderApiError, createRestClient } from "@theholocron/http-client";
+import { createHmac, timingSafeEqual } from "node:crypto";
 //#region src/utils.ts
 function createGitHubRestClient(opts) {
 	return createRestClient({
@@ -344,6 +345,52 @@ function workflows(rest) {
 	};
 }
 //#endregion
+//#region src/webhooks/webhooks.ts
+/**
+* GitHub's own webhook mechanics — signature verification and header/
+* payload shapes. Pure functions, no REST call, no auth token: these
+* operate on an *inbound* delivery, the mirror of everything else this
+* package does (outbound REST calls), so they're standalone exports
+* rather than part of `createGitHubClient()`'s returned object.
+*
+* A consumer (a GitHub App receiving webhooks) owns what to *do* with a
+* verified delivery — which event categories matter, how to normalize
+* them — the same split `holocron-plugin-clerk`'s `parseWebhook` draws
+* between Svix verification and Clerk-specific `AuthEvent` normalization,
+* just with the verification half living here instead of inline, since
+* "how GitHub signs and shapes a webhook" is vendor knowledge this
+* package already owns for every other GitHub API surface.
+*/
+/**
+* Verifies a GitHub webhook delivery's `X-Hub-Signature-256` header —
+* HMAC-SHA256 over the raw body, keyed by the webhook's configured
+* secret, `timingSafeEqual`-compared.
+* https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
+*
+* Returns `false` (never throws) for any failure to verify — a missing/
+* empty secret, a missing/malformed signature header, or a mismatch —
+* so the caller decides how to surface that (e.g. as its own error type).
+*/
+function verifyGitHubWebhookSignature(input) {
+	if (!input.secret || !input.signature || !input.signature.startsWith("sha256=")) return false;
+	const bodyStr = typeof input.body === "string" ? input.body : input.body.toString("utf8");
+	const provided = Buffer.from(input.signature.slice(7), "hex");
+	const computed = createHmac("sha256", input.secret).update(bodyStr).digest();
+	return provided.length === computed.length && timingSafeEqual(provided, computed);
+}
+/** Extracts GitHub's three webhook headers, case-insensitively (Node's raw headers may arrive lower-cased, or as an array when a header repeats). */
+function parseGitHubWebhookHeaders(headers) {
+	const find = (name) => {
+		const target = name.toLowerCase();
+		for (const [k, v] of Object.entries(headers)) if (k.toLowerCase() === target) return Array.isArray(v) ? v[0] : v;
+	};
+	return {
+		event: find("x-github-event"),
+		delivery: find("x-github-delivery"),
+		signature: find("x-hub-signature-256")
+	};
+}
+//#endregion
 //#region src/index.ts
 function createGitHubClient(opts) {
 	const rest = createGitHubRestClient(opts);
@@ -367,4 +414,4 @@ function createGitHubClient(opts) {
 	};
 }
 //#endregion
-export { createGitHubClient };
+export { createGitHubClient, parseGitHubWebhookHeaders, verifyGitHubWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/github-client",
-  "version": "1.17.0",
+  "version": "1.18.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.17.0"
+    "@theholocron/http-client": "^1.18.0"
   },
   "devDependencies": {
     "@theholocron/cli": "5.0.0-alpha.3",