jg-github 0.0.0-stage → 0.2.0

package/API.md

@@ -0,0 +1,648 @@
+# <a id="api-reference"></a>jg-github API reference
+
+Every export of `jg-github@0.2.0`, 30 in all, with its signature, its errors, and an example. It's generated from the package's TSDoc.
+
+- Functions: [`assertGithubAppPrivateKey`](#api-assertGithubAppPrivateKey), [`buildGithubApiUrl`](#api-buildGithubApiUrl), [`buildGithubRawContentUrl`](#api-buildGithubRawContentUrl), [`createGithubAppJwt`](#api-createGithubAppJwt), [`createGithubHeaders`](#api-createGithubHeaders), [`createInstallationToken`](#api-createInstallationToken), [`getGithubRateLimitDeadline`](#api-getGithubRateLimitDeadline), [`revokeInstallationToken`](#api-revokeInstallationToken), [`verifyGithubWebhookSignature`](#api-verifyGithubWebhookSignature)
+- Constants: [`DEFAULT_GITHUB_MAX_RESPONSE_BYTES`](#api-DEFAULT_GITHUB_MAX_RESPONSE_BYTES), [`DEFAULT_GITHUB_TIMEOUT_SECONDS`](#api-DEFAULT_GITHUB_TIMEOUT_SECONDS), [`ERRORS`](#api-ERRORS), [`GITHUB_API_ORIGIN`](#api-GITHUB_API_ORIGIN), [`GITHUB_API_VERSION`](#api-GITHUB_API_VERSION), [`GITHUB_RAW_CONTENT_ORIGIN`](#api-GITHUB_RAW_CONTENT_ORIGIN)
+- Types: [`ICreateGithubAppJwtOptions`](#api-ICreateGithubAppJwtOptions), [`ICreateInstallationTokenOptions`](#api-ICreateInstallationTokenOptions), [`IGithubApiUrlOptions`](#api-IGithubApiUrlOptions), [`IGithubHeadersOptions`](#api-IGithubHeadersOptions), [`IGithubPermissionLevel`](#api-IGithubPermissionLevel), [`IGithubPermissions`](#api-IGithubPermissions), [`IGithubQuery`](#api-IGithubQuery), [`IGithubRateLimitDeadlineOptions`](#api-IGithubRateLimitDeadlineOptions), [`IGithubRawContentLocation`](#api-IGithubRawContentLocation), [`IGithubRawContentUrlOptions`](#api-IGithubRawContentUrlOptions), [`IGithubRepository`](#api-IGithubRepository), [`IGithubRequestOptions`](#api-IGithubRequestOptions), [`IGithubResponseHeaders`](#api-IGithubResponseHeaders), [`IInstallationToken`](#api-IInstallationToken), [`IInstallationTokenRepositories`](#api-IInstallationTokenRepositories)
+
+## <a id="api-functions"></a>Functions
+
+### <a id="api-assertGithubAppPrivateKey"></a>`assertGithubAppPrivateKey`
+
+*Function*
+
+Checks that a GitHub App's private key can sign its JWTs: an unencrypted RSA key, PEM-encoded as PKCS#1, the `RSA PRIVATE KEY` GitHub downloads, or PKCS#8, the `PRIVATE KEY` it converts to. Run it at startup, so a bad key fails before the first request. The error never holds the key.
+
+```ts
+assertGithubAppPrivateKey(pem: string): void
+```
+
+**Parameters**
+
+- `pem` `string`: The key.
+
+**Throws**
+
+- `GITHUB_PRIVATE_KEY_INVALID`: The GitHub App's private key isn't an unencrypted RSA private key.
+
+**Example**
+
+```ts
+import { assertGithubAppPrivateKey } from 'jg-github';
+
+declare const privateKey: string;
+
+assertGithubAppPrivateKey(privateKey);
+```
+
+### <a id="api-buildGithubApiUrl"></a>`buildGithubApiUrl`
+
+*Function*
+
+Builds a REST API URL from its path segments, each encoded on its own, so a branch's `/` becomes `%2F` and no value can climb out of the path, plus the query parameters.
+
+```ts
+buildGithubApiUrl(
+  segments: readonly (string | number)[],
+  query?: IGithubQuery,
+  options?: IGithubApiUrlOptions,
+): string
+```
+
+**Parameters**
+
+- `segments` `readonly (string | number)[]`: The path's segments, such as `['repos', owner, repository, 'branches', branch]`.
+- `query?` `IGithubQuery`: The query parameters; undefined ones are left out. Defaults to `{}`.
+- `options?` `IGithubApiUrlOptions`: The API's base URL, for GitHub Enterprise Server or a test server. Defaults to `{}`.
+
+**Returns** `string`: The URL.
+
+**Throws**
+
+- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
+
+**Example**
+
+```ts
+import { buildGithubApiUrl } from 'jg-github';
+
+buildGithubApiUrl(['repos', 'acme', 'app', 'branches', 'feature/login'], { per_page: 100 });
+// 'https://api.github.com/repos/acme/app/branches/feature%2Flogin?per_page=100'
+```
+
+### <a id="api-buildGithubRawContentUrl"></a>`buildGithubRawContentUrl`
+
+*Function*
+
+Builds the URL of a file's raw content at a ref, with the owner and the repository encoded as one segment each, and the ref's and the path's `/`s kept.
+
+```ts
+buildGithubRawContentUrl(
+  location: IGithubRawContentLocation,
+  options?: IGithubRawContentUrlOptions,
+): string
+```
+
+**Parameters**
+
+- `location` `IGithubRawContentLocation`: The repository, the ref, and the file's path.
+- `options?` `IGithubRawContentUrlOptions`: The raw content's base URL, for a test server. Defaults to `{}`.
+
+**Returns** `string`: The URL.
+
+**Throws**
+
+- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
+
+**Example**
+
+```ts
+import { buildGithubRawContentUrl } from 'jg-github';
+
+buildGithubRawContentUrl({ owner: 'acme', repository: 'app', ref: 'main', path: 'docs/setup.md' });
+// 'https://raw.githubusercontent.com/acme/app/main/docs/setup.md'
+```
+
+### <a id="api-createGithubAppJwt"></a>`createGithubAppJwt`
+
+*Function*
+
+Creates the JWT a GitHub App authenticates as itself with, signed with RS256: issued 60 seconds back, for a GitHub clock behind this one, and expiring 540 seconds ahead, inside GitHub's ten-minute limit even with this clock a minute ahead.
+
+```ts
+createGithubAppJwt(options: ICreateGithubAppJwtOptions): string
+```
+
+**Parameters**
+
+- `options` `ICreateGithubAppJwtOptions`: The App's ID, its private key, and the time.
+
+**Returns** `string`: The JWT.
+
+**Throws**
+
+- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
+- `GITHUB_PRIVATE_KEY_INVALID`: The GitHub App's private key isn't an unencrypted RSA private key.
+
+**Example**
+
+```ts
+import { createGithubAppJwt } from 'jg-github';
+
+declare const privateKey: string;
+
+const jwt = createGithubAppJwt({ appId: 123456, privateKey });
+```
+
+### <a id="api-createGithubHeaders"></a>`createGithubHeaders`
+
+*Function*
+
+Builds the headers a request to GitHub's REST API sends: the media type, the token as a bearer credential, the User-Agent GitHub requires, and the API version.
+
+```ts
+createGithubHeaders(
+  token: string,
+  options: IGithubHeadersOptions,
+): Record<string, string>
+```
+
+**Parameters**
+
+- `token` `string`: The token, such as an installation token or an App JWT.
+- `options` `IGithubHeadersOptions`: The User-Agent and the API version.
+
+**Returns** `Record<string, string>`: The headers, with lowercase names.
+
+**Throws**
+
+- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
+
+**Example**
+
+```ts
+import { createGithubHeaders } from 'jg-github';
+
+declare const token: string;
+
+const response = await fetch('https://api.github.com/installation/repositories', {
+  headers: createGithubHeaders(token, { userAgent: 'acme-deploy-bot' }),
+});
+```
+
+### <a id="api-createInstallationToken"></a>`createInstallationToken`
+
+*Function*
+
+Creates an installation token for exactly the repositories and the permissions asked for, with `POST /app/installations/{id}/access_tokens`, authenticated as the App. `permissions` is required, because GitHub grants every permission of the installation without it, and the repositories are named by name or by ID, never both. The granted token must reach exactly those repositories, only the selected ones, with exactly those permissions, plus `metadata: 'read'`, and must not have expired; otherwise it's revoked before the error is thrown, and the error's data says whether that worked. Nothing is retried, and no error holds the token or the App's JWT.
+
+```ts
+createInstallationToken(
+  options: ICreateInstallationTokenOptions,
+): Promise<IInstallationToken>
+```
+
+**Parameters**
+
+- `options` `ICreateInstallationTokenOptions`: The App, the installation, the scope, and the request's limits.
+
+**Returns** `Promise<IInstallationToken>`: A promise that resolves to the token, when it expires, and what it reaches.
+
+**Throws**
+
+- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
+- `GITHUB_PRIVATE_KEY_INVALID`: The GitHub App's private key isn't an unencrypted RSA private key.
+- `GITHUB_REQUEST_FAILED`: The GitHub request failed.
+- `GITHUB_RESPONSE_INVALID`: GitHub's response isn't in the expected format.
+- `GITHUB_TOKEN_SCOPE_MISMATCH`: The installation token's scope isn't the one requested.
+- `GITHUB_TOKEN_EXPIRED`: The installation token had already expired.
+
+**Example**
+
+```ts
+import { createInstallationToken, revokeInstallationToken } from 'jg-github';
+
+declare const privateKey: string;
+
+const { token } = await createInstallationToken({
+  appId: 123456,
+  privateKey,
+  installationId: 12345678,
+  repositories: ['app'],
+  permissions: { contents: 'read' },
+  userAgent: 'acme-deploy-bot',
+});
+try {
+  // read the repository's contents with the token
+} finally {
+  await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });
+}
+```
+
+### <a id="api-getGithubRateLimitDeadline"></a>`getGithubRateLimitDeadline`
+
+*Function*
+
+Gives the time to retry a GitHub request at after a rate limit, or null when the response isn't rate limited. A 429 is, and so is a 403 with Retry-After, with no requests remaining, or with a rate-limit message, and a success that used the last remaining request. The deadline is the latest of Retry-After, as whole seconds or a strict IMF-fixdate, and `x-ratelimit-reset` when no requests remain, counting only future times; without one, it's a minute from now, doubled for each retry already made.
+
+```ts
+getGithubRateLimitDeadline(
+  options: IGithubRateLimitDeadlineOptions,
+): Date | null
+```
+
+**Parameters**
+
+- `options` `IGithubRateLimitDeadlineOptions`: The response's status and headers, the retries made, and the time.
+
+**Returns** `Date | null`: The time to retry at, or null.
+
+**Throws**
+
+- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
+
+**Example**
+
+```ts
+import { getGithubRateLimitDeadline } from 'jg-github';
+
+declare const response: Response;
+
+const deadline = getGithubRateLimitDeadline({
+  status: response.status,
+  headers: response.headers,
+  retryCount: 0,
+});
+```
+
+### <a id="api-revokeInstallationToken"></a>`revokeInstallationToken`
+
+*Function*
+
+Revokes an installation token before it expires, such as when the work it was for is done, with `DELETE /installation/token`, which GitHub answers with 204. It never retries. The error never holds the token.
+
+```ts
+revokeInstallationToken(
+  token: string,
+  options: IGithubRequestOptions,
+): Promise<void>
+```
+
+**Parameters**
+
+- `token` `string`: The installation token.
+- `options` `IGithubRequestOptions`: The User-Agent, the API's base URL and version, and the limits.
+
+**Returns** `Promise<void>`: A promise that resolves once GitHub has revoked it.
+
+**Throws**
+
+- `GITHUB_INVALID_ARGUMENT`: An argument isn't valid.
+- `GITHUB_TOKEN_REVOKE_FAILED`: The installation token couldn't be revoked.
+
+**Example**
+
+```ts
+import { revokeInstallationToken } from 'jg-github';
+
+declare const token: string;
+
+await revokeInstallationToken(token, { userAgent: 'acme-deploy-bot' });
+```
+
+### <a id="api-verifyGithubWebhookSignature"></a>`verifyGithubWebhookSignature`
+
+*Function*
+
+Verifies a GitHub webhook delivery's X-Hub-Signature-256 header against the body's exact bytes, in constant time. A header that's missing, repeated, longer than 71 characters, or not `sha256=` and 64 lowercase hexadecimal characters is false, like a wrong signature. Verify the raw body before parsing it, because parsing and serializing can change its bytes.
+
+```ts
+verifyGithubWebhookSignature(
+  rawBody: string | Uint8Array<ArrayBufferLike>,
+  header: unknown,
+  secret: string | Uint8Array<ArrayBufferLike>,
+): boolean
+```
+
+**Parameters**
+
+- `rawBody` `string | Uint8Array<ArrayBufferLike>`: The request's body, as received.
+- `header` `unknown`: The X-Hub-Signature-256 header, as the framework gives it.
+- `secret` `string | Uint8Array<ArrayBufferLike>`: The webhook's secret.
+
+**Returns** `boolean`: Whether the signature is the body's.
+
+**Throws**
+
+- `INVALID_HMAC_SECRET`: The HMAC secret must be a non-empty string or byte array.
+
+**Example**
+
+```ts
+import { verifyGithubWebhookSignature } from 'jg-github';
+
+declare const rawBody: Buffer;
+declare const headers: Record<string, string | string[] | undefined>;
+declare const webhookSecret: string;
+
+if (!verifyGithubWebhookSignature(rawBody, headers['x-hub-signature-256'], webhookSecret)) {
+  // answer 401
+}
+```
+
+## <a id="api-constants"></a>Constants
+
+### <a id="api-DEFAULT_GITHUB_MAX_RESPONSE_BYTES"></a>`DEFAULT_GITHUB_MAX_RESPONSE_BYTES`
+
+*Constant*
+
+the bytes a response from GitHub may take when the options don't say (128 KiB)
+
+```ts
+const DEFAULT_GITHUB_MAX_RESPONSE_BYTES: 131072
+```
+
+### <a id="api-DEFAULT_GITHUB_TIMEOUT_SECONDS"></a>`DEFAULT_GITHUB_TIMEOUT_SECONDS`
+
+*Constant*
+
+the seconds a request to GitHub may take when the options don't say
+
+```ts
+const DEFAULT_GITHUB_TIMEOUT_SECONDS: 10
+```
+
+### <a id="api-ERRORS"></a>`ERRORS`
+
+*Constant*
+
+the codes for every error thrown by the package
+
+```ts
+const ERRORS: { GITHUB_PRIVATE_KEY_INVALID: "GITHUB_PRIVATE_KEY_INVALID"; GITHUB_INVALID_ARGUMENT: "GITHUB_INVALID_ARGUMENT"; GITHUB_REQUEST_FAILED: "GITHUB_REQUEST_FAILED"; GITHUB_RESPONSE_INVALID: "GITHUB_RESPONSE_INVALID"; GITHUB_TOKEN_SCOPE_MISMATCH: "GITHUB_TOKEN_SCOPE_MISMATCH"; GITHUB_TOKEN_EXPIRED: "GITHUB_TOKEN_EXPIRED"; GITHUB_TOKEN_REVOKE_FAILED: "GITHUB_TOKEN_REVOKE_FAILED" }
+```
+
+### <a id="api-GITHUB_API_ORIGIN"></a>`GITHUB_API_ORIGIN`
+
+*Constant*
+
+the origin of GitHub's REST API on github.com
+
+```ts
+const GITHUB_API_ORIGIN: "https://api.github.com"
+```
+
+### <a id="api-GITHUB_API_VERSION"></a>`GITHUB_API_VERSION`
+
+*Constant*
+
+the REST API version every request asks for, in the X-GitHub-Api-Version header
+
+```ts
+const GITHUB_API_VERSION: "2026-03-10"
+```
+
+### <a id="api-GITHUB_RAW_CONTENT_ORIGIN"></a>`GITHUB_RAW_CONTENT_ORIGIN`
+
+*Constant*
+
+the origin GitHub serves a repository's raw files from
+
+```ts
+const GITHUB_RAW_CONTENT_ORIGIN: "https://raw.githubusercontent.com"
+```
+
+## <a id="api-types"></a>Types
+
+### <a id="api-ICreateGithubAppJwtOptions"></a>`ICreateGithubAppJwtOptions`
+
+*Type*
+
+what createGithubAppJwt takes
+
+```ts
+type ICreateGithubAppJwtOptions = {
+    appId: string | number;
+    privateKey: string;
+    now?: Date | undefined;
+};
+```
+
+**Members**
+
+- `appId: string | number` (property): the App's ID, such as 123456, or its client ID
+- `privateKey: string` (property): the App's private key, PEM-encoded, as GitHub downloads it
+- `now: Date` (property): the time the JWT is issued at. Defaults to now
+
+### <a id="api-ICreateInstallationTokenOptions"></a>`ICreateInstallationTokenOptions`
+
+*Type*
+
+what createInstallationToken takes
+
+```ts
+type ICreateInstallationTokenOptions = IGithubRequestOptions & IInstallationTokenRepositories & {
+    appId: string | number;
+    privateKey: string;
+    installationId: string | number;
+    permissions: IGithubPermissions;
+    maxResponseBytes?: number | undefined;
+};
+```
+
+### <a id="api-IGithubApiUrlOptions"></a>`IGithubApiUrlOptions`
+
+*Type*
+
+what buildGithubApiUrl takes
+
+```ts
+type IGithubApiUrlOptions = {
+    apiOrigin?: string | undefined;
+};
+```
+
+**Members**
+
+- `apiOrigin: string` (property): the API's base URL, such as `https://ghe.example.com/api/v3` for GitHub Enterprise Server. Defaults to GITHUB_API_ORIGIN
+
+### <a id="api-IGithubHeadersOptions"></a>`IGithubHeadersOptions`
+
+*Type*
+
+what createGithubHeaders takes
+
+```ts
+type IGithubHeadersOptions = {
+    userAgent: string;
+    apiVersion?: string | undefined;
+};
+```
+
+**Members**
+
+- `userAgent: string` (property): the User-Agent GitHub requires on every request, such as the app's name
+- `apiVersion: string` (property): the REST API version. Defaults to GITHUB_API_VERSION
+
+### <a id="api-IGithubPermissionLevel"></a>`IGithubPermissionLevel`
+
+*Type*
+
+the access a GitHub App permission grants
+
+```ts
+type IGithubPermissionLevel = 'read' | 'write' | 'admin';
+```
+
+### <a id="api-IGithubPermissions"></a>`IGithubPermissions`
+
+*Type*
+
+the permissions of an installation token, by GitHub's names, such as { contents: 'read' }
+
+```ts
+type IGithubPermissions = Record<string, IGithubPermissionLevel>;
+```
+
+### <a id="api-IGithubQuery"></a>`IGithubQuery`
+
+*Type*
+
+the query parameters a URL builder appends; undefined ones are left out
+
+```ts
+type IGithubQuery = Record<string, string | number | boolean | undefined>;
+```
+
+### <a id="api-IGithubRateLimitDeadlineOptions"></a>`IGithubRateLimitDeadlineOptions`
+
+*Type*
+
+what getGithubRateLimitDeadline takes
+
+```ts
+type IGithubRateLimitDeadlineOptions = {
+    status: number;
+    headers: IGithubResponseHeaders;
+    retryCount: number;
+    hasRateLimitMessage?: boolean | undefined;
+    now?: Date | undefined;
+};
+```
+
+**Members**
+
+- `status: number` (property): the response's HTTP status
+- `headers: IGithubResponseHeaders` (property): the response's headers
+- `retryCount: number` (property): the retries already made for this request, from 0, which doubles the fallback wait
+- `hasRateLimitMessage: boolean` (property): whether the response's message says a rate limit was hit, which makes a bare 403 count. Defaults to false
+- `now: Date` (property): the current time. Defaults to now
+
+### <a id="api-IGithubRawContentLocation"></a>`IGithubRawContentLocation`
+
+*Type*
+
+a file in a repository, at a ref
+
+```ts
+type IGithubRawContentLocation = {
+    owner: string;
+    repository: string;
+    ref: string;
+    path: string;
+};
+```
+
+**Members**
+
+- `owner: string` (property): the account that owns the repository
+- `repository: string` (property): the repository's name
+- `ref: string` (property): the branch, tag, or commit, such as `main` or `feature/login`
+- `path: string` (property): the file's path from the repository's root, such as `docs/setup.md`
+
+### <a id="api-IGithubRawContentUrlOptions"></a>`IGithubRawContentUrlOptions`
+
+*Type*
+
+what buildGithubRawContentUrl takes
+
+```ts
+type IGithubRawContentUrlOptions = {
+    rawContentOrigin?: string | undefined;
+};
+```
+
+**Members**
+
+- `rawContentOrigin: string` (property): the raw content's base URL. Defaults to GITHUB_RAW_CONTENT_ORIGIN
+
+### <a id="api-IGithubRepository"></a>`IGithubRepository`
+
+*Type*
+
+a repository an installation token can reach
+
+```ts
+type IGithubRepository = {
+    id: number;
+    fullName: string;
+};
+```
+
+**Members**
+
+- `id: number` (property): the repository's ID
+- `fullName: string` (property): the repository's owner and name, such as 'acme/app'
+
+### <a id="api-IGithubRequestOptions"></a>`IGithubRequestOptions`
+
+*Type*
+
+what every request to GitHub's REST API takes
+
+```ts
+type IGithubRequestOptions = {
+    userAgent: string;
+    apiOrigin?: string | undefined;
+    apiVersion?: string | undefined;
+    timeoutSeconds?: number | undefined;
+    signal?: AbortSignal | undefined;
+};
+```
+
+**Members**
+
+- `userAgent: string` (property): the User-Agent GitHub requires on every request, such as the app's name
+- `apiOrigin: string` (property): the API's base URL, such as `https://ghe.example.com/api/v3` for GitHub Enterprise Server. Defaults to GITHUB_API_ORIGIN
+- `apiVersion: string` (property): the REST API version. Defaults to GITHUB_API_VERSION
+- `timeoutSeconds: number` (property): the seconds the request may take. Defaults to 10
+- `signal: AbortSignal` (property): stops the request when it aborts
+
+### <a id="api-IGithubResponseHeaders"></a>`IGithubResponseHeaders`
+
+*Type*
+
+a response's headers: a Headers object, or a record with lowercase names, as Node.js's IncomingHttpHeaders has
+
+```ts
+type IGithubResponseHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+```
+
+### <a id="api-IInstallationToken"></a>`IInstallationToken`
+
+*Type*
+
+an installation token, scoped as requested
+
+```ts
+type IInstallationToken = {
+    token: string;
+    expiresAt: Date;
+    permissions: Record<string, string>;
+    repositories: IGithubRepository[];
+};
+```
+
+**Members**
+
+- `token: string` (property): the token, sent as a bearer credential
+- `expiresAt: Date` (property): when it expires, an hour after it was created
+- `permissions: Record<string, string>` (property): the permissions it grants: the ones requested, and `metadata: 'read'` when GitHub adds it
+- `repositories: IGithubRepository[]` (property): the repositories it reaches, exactly the ones requested
+
+### <a id="api-IInstallationTokenRepositories"></a>`IInstallationTokenRepositories`
+
+*Type*
+
+the repositories an installation token is for: by name or by ID, never both
+
+```ts
+type IInstallationTokenRepositories = {
+    repositories: readonly string[];
+    repositoryIds?: undefined;
+} | {
+    repositoryIds: readonly number[];
+    repositories?: undefined;
+};
+```

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0
+
+### Changed
+
+- Supports Node.js 22.17.0 and later, down from 24.
+
+## 0.1.0
+
+### Added
+
+- `createInstallationToken(options)`, an installation token for exactly the repositories, by name or by ID, and the permissions asked for. `permissions` is required and non-empty, and a granted token whose repositories, permissions, or repository selection differ, or that has expired, is revoked before `GITHUB_TOKEN_SCOPE_MISMATCH` or `GITHUB_TOKEN_EXPIRED` is thrown. `revokeInstallationToken(token, options)` revokes one, expecting 204.
+- `createGithubAppJwt({ appId, privateKey, now })`, the App's RS256 JWT, issued 60 seconds back and expiring 540 seconds ahead, and `assertGithubAppPrivateKey(pem)`, which accepts an unencrypted RSA key as PKCS#1 or PKCS#8.
+- `verifyGithubWebhookSignature(rawBody, header, secret)`, which checks `X-Hub-Signature-256` in constant time through jg-crypto, refusing a malformed or repeated header.
+- `getGithubRateLimitDeadline(options)`, when to retry a rate limited request, from `Retry-After` and `x-ratelimit-reset`, with an exponential fallback.
+- `createGithubHeaders`, `buildGithubApiUrl`, and `buildGithubRawContentUrl`, with `GITHUB_API_ORIGIN`, `GITHUB_RAW_CONTENT_ORIGIN`, and `GITHUB_API_VERSION`.
+- Requests through jg-fetch with no redirects, no retries, a 10-second timeout, and a 128 KiB response limit, whose errors never hold a token or a response body.
+- Recipes for a scoped installation token revoked when done, and a webhook route.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jesus Graterol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.