github-app-auth-kit 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emeka Orji
+
+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.

package/README.md

@@ -0,0 +1,193 @@
+# github-app-auth-kit
+
+A minimal, dependency-free TypeScript toolkit for GitHub App authentication.
+
+Use it to:
+
+- mint short-lived GitHub App JWTs
+- resolve installation IDs from `owner/repo`
+- create installation access tokens
+- work in Node, edge runtimes, and GitHub Enterprise
+
+## Why this library
+
+- Small surface area with strong types
+- Works in three styles: one-shot, client instance, or low-level calls
+- Runtime-agnostic (bring your own `fetch` if needed)
+- Designed for clear errors and predictable behavior
+
+## Install
+
+```bash
+pnpm add github-app-auth-kit
+```
+
+## Quick start
+
+```ts
+import { GitHubAppAuth } from 'github-app-auth-kit';
+
+const auth = new GitHubAppAuth({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+});
+
+const jwt = auth.createJwt();
+```
+
+## Usage
+
+### Client instance (recommended for multiple calls)
+
+```ts
+import { GitHubAppAuth } from 'github-app-auth-kit';
+
+const auth = new GitHubAppAuth({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+  owner: 'acme',
+  repo: 'platform',
+});
+
+const installationId = await auth.resolveInstallationId();
+const token = await auth.createAccessToken();
+```
+
+### Resolve installation id for any repo
+
+```ts
+import { GitHubAppAuth } from 'github-app-auth-kit';
+
+const auth = new GitHubAppAuth({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+});
+
+const installationId = await auth.resolveInstallationId({
+  owner: 'acme',
+  repo: 'platform',
+});
+```
+
+### Create access token with a known installation id
+
+```ts
+import { GitHubAppAuth } from 'github-app-auth-kit';
+
+const auth = new GitHubAppAuth({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+  installationId: 12345678,
+});
+
+const token = await auth.createAccessToken();
+```
+
+### One-shot access token
+
+```ts
+import { GitHubAppAuth } from 'github-app-auth-kit';
+
+const token = await GitHubAppAuth.createAccessToken({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+  installationId: 12345678,
+  permissions: {
+    contents: 'read',
+  },
+});
+```
+
+### GitHub Enterprise
+
+```ts
+import { GitHubAppAuth } from 'github-app-auth-kit';
+
+const auth = new GitHubAppAuth({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+  apiBaseUrl: 'https://github.example.com/api/v3',
+  installationId: 12345678,
+});
+
+const token = await auth.createAccessToken();
+```
+
+### Custom fetch (edge runtimes or Node <18)
+
+```ts
+import { GitHubAppAuth } from 'github-app-auth-kit';
+import { fetch as undiciFetch } from 'undici';
+
+const auth = new GitHubAppAuth({
+  appId: process.env.GITHUB_APP_ID!,
+  privateKey: process.env.GITHUB_PRIVATE_KEY!,
+  installationId: 12345678,
+  fetch: undiciFetch,
+});
+
+const token = await auth.createAccessToken();
+```
+
+## API
+
+### `new GitHubAppAuth(options)`
+
+| Option           | Type               | Required | Description                                       |
+| ---------------- | ------------------ | -------- | ------------------------------------------------- |
+| `appId`          | `number \| string` | Yes      | GitHub App id.                                    |
+| `privateKey`     | `string`           | Yes      | PEM private key (supports `\n` escaped newlines). |
+| `owner`          | `string`           | No       | Default repository owner.                         |
+| `repo`           | `string`           | No       | Default repository name.                          |
+| `installationId` | `number \| string` | No       | Default installation id for tokens.               |
+| `apiBaseUrl`     | `string`           | No       | Override REST API base URL (GitHub Enterprise).   |
+| `fetch`          | `typeof fetch`     | No       | Provide `fetch` for non-standard runtimes.        |
+
+### `auth.createJwt()`
+
+Returns a short-lived GitHub App JWT. JWTs are valid for 10 minutes maximum; this library issues 9-minute tokens with a 60-second clock skew.
+
+### `auth.resolveInstallationId({ owner, repo })`
+
+Resolves the installation id for the given repository. Uses the default `owner`/`repo` if set on the constructor.
+
+### `auth.createAccessToken(options)`
+
+Creates an installation access token. You can provide:
+
+- `installationId` to skip repository lookup
+- `owner` and `repo` to look up installation id on demand
+- optional `permissions`, `repositories`, and `repositoryIds` for fine-grained tokens
+
+### `GitHubAppAuth.createAccessToken(options)`
+
+Convenience one-call helper that creates a client and returns an access token.
+
+## Error handling
+
+All network errors and non-2xx GitHub API responses throw descriptive errors that include the HTTP status and response body.
+
+## Security notes
+
+- Treat `privateKey`, JWTs, and access tokens as secrets.
+- Do not log tokens or private keys.
+- Issue JWTs only when needed; they expire quickly.
+
+## Runtime support
+
+- Node.js 18+ (native `fetch`)
+- Other runtimes: pass a `fetch` implementation in the constructor
+
+## Troubleshooting
+
+- If you see "`fetch` is not available in this runtime", pass a `fetch` implementation.
+- If you see "Missing repository target", provide both `owner` and `repo`, or use `installationId`.
+
+## Related links
+
+- [GitHub Apps documentation](https://docs.github.com/en/apps/creating-github-apps)
+- [GitHub REST API](https://docs.github.com/en/rest)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+type FetchLike = typeof fetch;
+type PermissionLevel = 'read' | 'write';
+type InstallationTokenPermissions = Record<string, PermissionLevel>;
+type GitHubRepoRef = {
+    owner: string;
+    repo: string;
+};
+type ResolveInstallationIdOptions = Partial<GitHubRepoRef>;
+type CreateAccessTokenOptions = ResolveInstallationIdOptions & {
+    installationId?: number | undefined;
+    permissions?: InstallationTokenPermissions | undefined;
+    repositories?: string[] | undefined;
+    repositoryIds?: number[] | undefined;
+};
+type GitHubAppAuthOptions = {
+    appId: number | string;
+    privateKey?: string | undefined;
+    privateKeyRaw?: string | undefined;
+    owner?: string | undefined;
+    repo?: string | undefined;
+    installationId?: number | undefined;
+    apiBaseUrl?: string | undefined;
+    fetch?: FetchLike | undefined;
+};
+declare function generateGitHubAppJwt(appId: number | string, privateKeyRaw: string): string;
+declare class GitHubAppAuth {
+    private readonly appId;
+    private readonly privateKey;
+    private readonly owner;
+    private readonly repo;
+    private readonly installationId;
+    private readonly apiBaseUrl;
+    private readonly fetchImpl;
+    constructor({ appId, privateKey, privateKeyRaw, owner, repo, installationId, apiBaseUrl, fetch, }: GitHubAppAuthOptions);
+    createJwt(): string;
+    resolveInstallationId(options?: ResolveInstallationIdOptions): Promise<number>;
+    createAccessToken(options?: CreateAccessTokenOptions): Promise<string>;
+    withContext(context: Partial<Pick<GitHubAppAuthOptions, 'owner' | 'repo' | 'installationId'>>): GitHubAppAuth;
+    static createAccessToken(options: GitHubAppAuthOptions & CreateAccessTokenOptions): Promise<string>;
+}
+
+export { type CreateAccessTokenOptions, GitHubAppAuth, type GitHubAppAuthOptions, type GitHubRepoRef, type InstallationTokenPermissions, type ResolveInstallationIdOptions, generateGitHubAppJwt };

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,MAAM,CAyBR;AAED,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,EACrB,iBAAiB,EAAE,MAAM,GACxB,OAAO,CAAC,MAAM,CAAC,CAuBjB"}

package/dist/index.js

@@ -0,0 +1,290 @@
+// src/index.ts
+import crypto from "crypto";
+
+// src/utils.ts
+function toBase64UrlJson(value) {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+
+// src/index.ts
+var DEFAULT_GITHUB_API_BASE_URL = "https://api.github.com";
+function normalizePrivateKey(privateKeyRaw) {
+  return privateKeyRaw.replace(/\\n/g, "\n");
+}
+function requireNonEmptyString(value, fieldName) {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    throw new Error(`\`${fieldName}\` must be a non-empty string.`);
+  }
+  return trimmed;
+}
+function normalizeOptionalNonEmptyString(value, fieldName) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return requireNonEmptyString(value, fieldName);
+}
+function resolvePrivateKey({
+  privateKey,
+  privateKeyRaw
+}) {
+  const key = privateKey ?? privateKeyRaw;
+  if (key === void 0) {
+    throw new Error("Either `privateKey` or `privateKeyRaw` is required.");
+  }
+  return requireNonEmptyString(key, "privateKey");
+}
+function resolveFetch(fetchOverride) {
+  const fetchImpl = fetchOverride ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error(
+      "A fetch implementation is required. Pass `fetch` in options when global fetch is unavailable."
+    );
+  }
+  return fetchImpl;
+}
+function resolveApiBaseUrl(apiBaseUrl) {
+  return apiBaseUrl ? requireNonEmptyString(apiBaseUrl, "apiBaseUrl") : DEFAULT_GITHUB_API_BASE_URL;
+}
+function parsePositiveInteger(value, fieldName) {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`\`${fieldName}\` must be a positive integer.`);
+  }
+  return parsed;
+}
+function parseOptionalInstallationId(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return parsePositiveInteger(value, "installationId");
+}
+function resolveRepoRef({
+  defaultOwner,
+  defaultRepo,
+  owner,
+  repo
+}) {
+  const resolvedOwner = owner ?? defaultOwner;
+  const resolvedRepo = repo ?? defaultRepo;
+  if (!resolvedOwner || !resolvedRepo) {
+    throw new Error(
+      "Missing repository target. Provide both `owner` and `repo` in the constructor or method call."
+    );
+  }
+  return {
+    owner: resolvedOwner,
+    repo: resolvedRepo
+  };
+}
+function buildAccessTokenRequestBody({
+  permissions,
+  repositories,
+  repositoryIds
+}) {
+  const body = {};
+  if (permissions) {
+    body.permissions = permissions;
+  }
+  if (repositories?.length) {
+    body.repositories = repositories;
+  }
+  if (repositoryIds?.length) {
+    body.repository_ids = repositoryIds;
+  }
+  if (Object.keys(body).length === 0) {
+    return void 0;
+  }
+  return JSON.stringify(body);
+}
+async function throwGitHubApiError(response, context) {
+  const responseBodyRaw = await response.text();
+  const responseBody = responseBodyRaw.trim().length > 0 ? responseBodyRaw : "(empty response body)";
+  throw new Error(
+    `${context} (${response.status} ${response.statusText}): ${responseBody}`
+  );
+}
+async function requestInstallationId({
+  owner,
+  repo,
+  appJwt,
+  apiBaseUrl,
+  fetchImpl
+}) {
+  const encodedOwner = encodeURIComponent(owner);
+  const encodedRepo = encodeURIComponent(repo);
+  const response = await fetchImpl(
+    `${apiBaseUrl}/repos/${encodedOwner}/${encodedRepo}/installation`,
+    {
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${appJwt}`
+      }
+    }
+  );
+  if (!response.ok) {
+    return throwGitHubApiError(
+      response,
+      `Failed to read installation for ${owner}/${repo}`
+    );
+  }
+  const payload = await response.json();
+  if (!payload.id) {
+    throw new Error("GitHub response did not include an installation id.");
+  }
+  return payload.id;
+}
+async function requestAccessToken({
+  installationId,
+  appJwt,
+  apiBaseUrl,
+  fetchImpl,
+  tokenOptions
+}) {
+  const body = buildAccessTokenRequestBody(tokenOptions);
+  const headers = {
+    Accept: "application/vnd.github+json",
+    Authorization: `Bearer ${appJwt}`
+  };
+  if (body) {
+    headers["Content-Type"] = "application/json";
+  }
+  const response = await fetchImpl(
+    `${apiBaseUrl}/app/installations/${installationId}/access_tokens`,
+    body ? {
+      method: "POST",
+      headers,
+      body
+    } : {
+      method: "POST",
+      headers
+    }
+  );
+  if (!response.ok) {
+    return throwGitHubApiError(
+      response,
+      `Failed to create installation access token for installation ${installationId}`
+    );
+  }
+  const payload = await response.json();
+  if (!payload.token) {
+    throw new Error("GitHub response did not include an installation token.");
+  }
+  return payload.token;
+}
+function generateGitHubAppJwt(appId, privateKeyRaw) {
+  const normalizedAppId = parsePositiveInteger(appId, "appId");
+  const privateKey = normalizePrivateKey(privateKeyRaw);
+  const now = Math.floor(Date.now() / 1e3);
+  const payload = {
+    iat: now - 60,
+    exp: now + 9 * 60,
+    iss: normalizedAppId
+  };
+  const header = {
+    alg: "RS256",
+    typ: "JWT"
+  };
+  const encodedHeader = toBase64UrlJson(header);
+  const encodedPayload = toBase64UrlJson(payload);
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+  const signer = crypto.createSign("RSA-SHA256");
+  signer.update(signingInput);
+  signer.end();
+  const signature = signer.sign(privateKey, "base64url");
+  return `${signingInput}.${signature}`;
+}
+var GitHubAppAuth = class _GitHubAppAuth {
+  appId;
+  privateKey;
+  owner;
+  repo;
+  installationId;
+  apiBaseUrl;
+  fetchImpl;
+  constructor({
+    appId,
+    privateKey,
+    privateKeyRaw,
+    owner,
+    repo,
+    installationId,
+    apiBaseUrl,
+    fetch
+  }) {
+    this.appId = parsePositiveInteger(appId, "appId");
+    this.privateKey = normalizePrivateKey(
+      resolvePrivateKey({
+        privateKey,
+        privateKeyRaw
+      })
+    );
+    this.owner = normalizeOptionalNonEmptyString(owner, "owner");
+    this.repo = normalizeOptionalNonEmptyString(repo, "repo");
+    this.installationId = parseOptionalInstallationId(installationId);
+    this.apiBaseUrl = resolveApiBaseUrl(apiBaseUrl);
+    this.fetchImpl = resolveFetch(fetch);
+    if (this.owner && !this.repo || !this.owner && this.repo) {
+      throw new Error(
+        "Both `owner` and `repo` must be provided together when setting a default repository target."
+      );
+    }
+  }
+  createJwt() {
+    return generateGitHubAppJwt(this.appId, this.privateKey);
+  }
+  async resolveInstallationId(options = {}) {
+    const repoRef = resolveRepoRef({
+      defaultOwner: this.owner,
+      defaultRepo: this.repo,
+      owner: normalizeOptionalNonEmptyString(options.owner, "owner"),
+      repo: normalizeOptionalNonEmptyString(options.repo, "repo")
+    });
+    return requestInstallationId({
+      ...repoRef,
+      appJwt: this.createJwt(),
+      apiBaseUrl: this.apiBaseUrl,
+      fetchImpl: this.fetchImpl
+    });
+  }
+  async createAccessToken(options = {}) {
+    const installationId = parseOptionalInstallationId(
+      options.installationId ?? this.installationId
+    );
+    const resolveOptions = {};
+    if (options.owner !== void 0) {
+      resolveOptions.owner = options.owner;
+    }
+    if (options.repo !== void 0) {
+      resolveOptions.repo = options.repo;
+    }
+    const resolvedInstallationId = installationId ?? await this.resolveInstallationId(resolveOptions);
+    return requestAccessToken({
+      installationId: resolvedInstallationId,
+      appJwt: this.createJwt(),
+      apiBaseUrl: this.apiBaseUrl,
+      fetchImpl: this.fetchImpl,
+      tokenOptions: options
+    });
+  }
+  withContext(context) {
+    return new _GitHubAppAuth({
+      appId: this.appId,
+      privateKey: this.privateKey,
+      owner: context.owner ?? this.owner,
+      repo: context.repo ?? this.repo,
+      installationId: context.installationId ?? this.installationId,
+      apiBaseUrl: this.apiBaseUrl,
+      fetch: this.fetchImpl
+    });
+  }
+  static async createAccessToken(options) {
+    const auth = new _GitHubAppAuth(options);
+    return auth.createAccessToken(options);
+  }
+};
+export {
+  GitHubAppAuth,
+  generateGitHubAppJwt
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/utils.ts"],"sourcesContent":["import crypto from 'node:crypto';\n\nimport { toBase64UrlJson } from './utils';\n\nconst DEFAULT_GITHUB_API_BASE_URL = 'https://api.github.com';\n\ntype FetchLike = typeof fetch;\n\ntype PermissionLevel = 'read' | 'write';\n\nexport type InstallationTokenPermissions = Record<string, PermissionLevel>;\n\nexport type GitHubRepoRef = {\n  owner: string;\n  repo: string;\n};\n\nexport type ResolveInstallationIdOptions = Partial<GitHubRepoRef>;\n\nexport type CreateAccessTokenOptions = ResolveInstallationIdOptions & {\n  installationId?: number | undefined;\n  permissions?: InstallationTokenPermissions | undefined;\n  repositories?: string[] | undefined;\n  repositoryIds?: number[] | undefined;\n};\n\nexport type GitHubAppAuthOptions = {\n  appId: number | string;\n  privateKey?: string | undefined;\n  privateKeyRaw?: string | undefined;\n  owner?: string | undefined;\n  repo?: string | undefined;\n  installationId?: number | undefined;\n  apiBaseUrl?: string | undefined;\n  fetch?: FetchLike | undefined;\n};\n\ntype InstallationLookupResponse = {\n  id?: number;\n};\n\ntype AccessTokenResponse = {\n  token?: string;\n};\n\ntype AccessTokenRequestBody = {\n  permissions?: InstallationTokenPermissions;\n  repositories?: string[];\n  repository_ids?: number[];\n};\n\nfunction normalizePrivateKey(privateKeyRaw: string): string {\n  return privateKeyRaw.replace(/\\\\n/g, '\\n');\n}\n\nfunction requireNonEmptyString(value: string, fieldName: string): string {\n  const trimmed = value.trim();\n  if (!trimmed) {\n    throw new Error(`\\`${fieldName}\\` must be a non-empty string.`);\n  }\n\n  return trimmed;\n}\n\nfunction normalizeOptionalNonEmptyString(\n  value: string | undefined,\n  fieldName: string\n): string | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n\n  return requireNonEmptyString(value, fieldName);\n}\n\nfunction resolvePrivateKey({\n  privateKey,\n  privateKeyRaw,\n}: {\n  privateKey?: string | undefined;\n  privateKeyRaw?: string | undefined;\n}): string {\n  const key = privateKey ?? privateKeyRaw;\n  if (key === undefined) {\n    throw new Error('Either `privateKey` or `privateKeyRaw` is required.');\n  }\n\n  return requireNonEmptyString(key, 'privateKey');\n}\n\nfunction resolveFetch(fetchOverride?: FetchLike): FetchLike {\n  const fetchImpl = fetchOverride ?? globalThis.fetch;\n  if (typeof fetchImpl !== 'function') {\n    throw new Error(\n      'A fetch implementation is required. Pass `fetch` in options when global fetch is unavailable.'\n    );\n  }\n\n  return fetchImpl;\n}\n\nfunction resolveApiBaseUrl(apiBaseUrl?: string): string {\n  return apiBaseUrl\n    ? requireNonEmptyString(apiBaseUrl, 'apiBaseUrl')\n    : DEFAULT_GITHUB_API_BASE_URL;\n}\n\nfunction parsePositiveInteger(\n  value: number | string,\n  fieldName: string\n): number {\n  const parsed = typeof value === 'number' ? value : Number(value);\n  if (!Number.isInteger(parsed) || parsed <= 0) {\n    throw new Error(`\\`${fieldName}\\` must be a positive integer.`);\n  }\n\n  return parsed;\n}\n\nfunction parseOptionalInstallationId(\n  value: number | undefined\n): number | undefined {\n  if (value === undefined) {\n    return undefined;\n  }\n\n  return parsePositiveInteger(value, 'installationId');\n}\n\nfunction resolveRepoRef({\n  defaultOwner,\n  defaultRepo,\n  owner,\n  repo,\n}: {\n  defaultOwner: string | undefined;\n  defaultRepo: string | undefined;\n  owner: string | undefined;\n  repo: string | undefined;\n}): GitHubRepoRef {\n  const resolvedOwner = owner ?? defaultOwner;\n  const resolvedRepo = repo ?? defaultRepo;\n\n  if (!resolvedOwner || !resolvedRepo) {\n    throw new Error(\n      'Missing repository target. Provide both `owner` and `repo` in the constructor or method call.'\n    );\n  }\n\n  return {\n    owner: resolvedOwner,\n    repo: resolvedRepo,\n  };\n}\n\nfunction buildAccessTokenRequestBody({\n  permissions,\n  repositories,\n  repositoryIds,\n}: CreateAccessTokenOptions): string | undefined {\n  const body: AccessTokenRequestBody = {};\n\n  if (permissions) {\n    body.permissions = permissions;\n  }\n\n  if (repositories?.length) {\n    body.repositories = repositories;\n  }\n\n  if (repositoryIds?.length) {\n    body.repository_ids = repositoryIds;\n  }\n\n  if (Object.keys(body).length === 0) {\n    return undefined;\n  }\n\n  return JSON.stringify(body);\n}\n\nasync function throwGitHubApiError(\n  response: Response,\n  context: string\n): Promise<never> {\n  const responseBodyRaw = await response.text();\n  const responseBody =\n    responseBodyRaw.trim().length > 0 ? responseBodyRaw : '(empty response body)';\n\n  throw new Error(\n    `${context} (${response.status} ${response.statusText}): ${responseBody}`\n  );\n}\n\nasync function requestInstallationId({\n  owner,\n  repo,\n  appJwt,\n  apiBaseUrl,\n  fetchImpl,\n}: {\n  owner: string;\n  repo: string;\n  appJwt: string;\n  apiBaseUrl: string;\n  fetchImpl: FetchLike;\n}): Promise<number> {\n  const encodedOwner = encodeURIComponent(owner);\n  const encodedRepo = encodeURIComponent(repo);\n  const response = await fetchImpl(\n    `${apiBaseUrl}/repos/${encodedOwner}/${encodedRepo}/installation`,\n    {\n      headers: {\n        Accept: 'application/vnd.github+json',\n        Authorization: `Bearer ${appJwt}`,\n      },\n    }\n  );\n\n  if (!response.ok) {\n    return throwGitHubApiError(\n      response,\n      `Failed to read installation for ${owner}/${repo}`\n    );\n  }\n\n  const payload = (await response.json()) as InstallationLookupResponse;\n  if (!payload.id) {\n    throw new Error('GitHub response did not include an installation id.');\n  }\n\n  return payload.id;\n}\n\nasync function requestAccessToken({\n  installationId,\n  appJwt,\n  apiBaseUrl,\n  fetchImpl,\n  tokenOptions,\n}: {\n  installationId: number;\n  appJwt: string;\n  apiBaseUrl: string;\n  fetchImpl: FetchLike;\n  tokenOptions: CreateAccessTokenOptions;\n}): Promise<string> {\n  const body = buildAccessTokenRequestBody(tokenOptions);\n  const headers: Record<string, string> = {\n    Accept: 'application/vnd.github+json',\n    Authorization: `Bearer ${appJwt}`,\n  };\n\n  if (body) {\n    headers['Content-Type'] = 'application/json';\n  }\n\n  const response = await fetchImpl(\n    `${apiBaseUrl}/app/installations/${installationId}/access_tokens`,\n    body\n      ? {\n          method: 'POST',\n          headers,\n          body,\n        }\n      : {\n          method: 'POST',\n          headers,\n        }\n  );\n\n  if (!response.ok) {\n    return throwGitHubApiError(\n      response,\n      `Failed to create installation access token for installation ${installationId}`\n    );\n  }\n\n  const payload = (await response.json()) as AccessTokenResponse;\n  if (!payload.token) {\n    throw new Error('GitHub response did not include an installation token.');\n  }\n\n  return payload.token;\n}\n\nexport function generateGitHubAppJwt(\n  appId: number | string,\n  privateKeyRaw: string\n): string {\n  const normalizedAppId = parsePositiveInteger(appId, 'appId');\n  const privateKey = normalizePrivateKey(privateKeyRaw);\n\n  const now = Math.floor(Date.now() / 1000);\n  const payload = {\n    iat: now - 60,\n    exp: now + 9 * 60,\n    iss: normalizedAppId,\n  };\n\n  const header = {\n    alg: 'RS256',\n    typ: 'JWT',\n  };\n\n  const encodedHeader = toBase64UrlJson(header);\n  const encodedPayload = toBase64UrlJson(payload);\n  const signingInput = `${encodedHeader}.${encodedPayload}`;\n\n  const signer = crypto.createSign('RSA-SHA256');\n  signer.update(signingInput);\n  signer.end();\n\n  const signature = signer.sign(privateKey, 'base64url');\n  return `${signingInput}.${signature}`;\n}\n\nexport class GitHubAppAuth {\n  private readonly appId: number;\n  private readonly privateKey: string;\n  private readonly owner: string | undefined;\n  private readonly repo: string | undefined;\n  private readonly installationId: number | undefined;\n  private readonly apiBaseUrl: string;\n  private readonly fetchImpl: FetchLike;\n\n  constructor({\n    appId,\n    privateKey,\n    privateKeyRaw,\n    owner,\n    repo,\n    installationId,\n    apiBaseUrl,\n    fetch,\n  }: GitHubAppAuthOptions) {\n    this.appId = parsePositiveInteger(appId, 'appId');\n    this.privateKey = normalizePrivateKey(\n      resolvePrivateKey({\n        privateKey,\n        privateKeyRaw,\n      })\n    );\n    this.owner = normalizeOptionalNonEmptyString(owner, 'owner');\n    this.repo = normalizeOptionalNonEmptyString(repo, 'repo');\n    this.installationId = parseOptionalInstallationId(installationId);\n    this.apiBaseUrl = resolveApiBaseUrl(apiBaseUrl);\n    this.fetchImpl = resolveFetch(fetch);\n\n    if ((this.owner && !this.repo) || (!this.owner && this.repo)) {\n      throw new Error(\n        'Both `owner` and `repo` must be provided together when setting a default repository target.'\n      );\n    }\n  }\n\n  createJwt(): string {\n    return generateGitHubAppJwt(this.appId, this.privateKey);\n  }\n\n  async resolveInstallationId(\n    options: ResolveInstallationIdOptions = {}\n  ): Promise<number> {\n    const repoRef = resolveRepoRef({\n      defaultOwner: this.owner,\n      defaultRepo: this.repo,\n      owner: normalizeOptionalNonEmptyString(options.owner, 'owner'),\n      repo: normalizeOptionalNonEmptyString(options.repo, 'repo'),\n    });\n\n    return requestInstallationId({\n      ...repoRef,\n      appJwt: this.createJwt(),\n      apiBaseUrl: this.apiBaseUrl,\n      fetchImpl: this.fetchImpl,\n    });\n  }\n\n  async createAccessToken(options: CreateAccessTokenOptions = {}): Promise<string> {\n    const installationId = parseOptionalInstallationId(\n      options.installationId ?? this.installationId\n    );\n\n    const resolveOptions: ResolveInstallationIdOptions = {};\n    if (options.owner !== undefined) {\n      resolveOptions.owner = options.owner;\n    }\n\n    if (options.repo !== undefined) {\n      resolveOptions.repo = options.repo;\n    }\n\n    const resolvedInstallationId =\n      installationId ?? (await this.resolveInstallationId(resolveOptions));\n\n    return requestAccessToken({\n      installationId: resolvedInstallationId,\n      appJwt: this.createJwt(),\n      apiBaseUrl: this.apiBaseUrl,\n      fetchImpl: this.fetchImpl,\n      tokenOptions: options,\n    });\n  }\n\n  withContext(\n    context: Partial<Pick<GitHubAppAuthOptions, 'owner' | 'repo' | 'installationId'>>\n  ): GitHubAppAuth {\n    return new GitHubAppAuth({\n      appId: this.appId,\n      privateKey: this.privateKey,\n      owner: context.owner ?? this.owner,\n      repo: context.repo ?? this.repo,\n      installationId: context.installationId ?? this.installationId,\n      apiBaseUrl: this.apiBaseUrl,\n      fetch: this.fetchImpl,\n    });\n  }\n\n  static async createAccessToken(\n    options: GitHubAppAuthOptions & CreateAccessTokenOptions\n  ): Promise<string> {\n    const auth = new GitHubAppAuth(options);\n    return auth.createAccessToken(options);\n  }\n}\n","export function toBase64UrlJson(value: Record<string, unknown>): string {\n  return Buffer.from(JSON.stringify(value)).toString('base64url');\n}\n"],"mappings":"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","names":[]}

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function toBase64UrlJson(value: Record<string, unknown>): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAEtE"}

package/dist/utils.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toBase64UrlJson = toBase64UrlJson;
+function toBase64UrlJson(value) {
+    return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":";;AAAA,0CAEC;AAFD,SAAgB,eAAe,CAAC,KAA8B;IAC5D,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAClE,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "github-app-auth-kit",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "TypeScript helpers for GitHub App JWTs and installation access tokens.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "github-app",
+    "installation-token",
+    "jwt",
+    "typescript"
+  ],
+  "author": "Emeka Orji",
+  "license": "ISC",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.2",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}