Registry / auth-security / universal-github-app-jwt

universal-github-app-jwt

library2.2.2jsnpmunverified

universal-github-app-jwt is a JavaScript/TypeScript library designed to securely generate JSON Web Tokens (JWTs) for GitHub Apps. It supports various JavaScript runtimes including Node.js, Deno, and modern web browsers by leveraging the Web Crypto API features or Node's `crypto` module. The current stable version is 2.2.2, with releases occurring as needed for bug fixes and minor features, often multiple times a month, indicating active maintenance and responsiveness. Its key differentiator is its universal compatibility across different environments, simplifying GitHub App authentication by abstracting away the underlying cryptographic implementations. It focuses specifically on generating the app installation token, which is often used in conjunction with other Octokit libraries like `@octokit/auth-app.js` for complete GitHub App authentication flows.

auth-security http-networking

npm install universal-github-app-jwt

github ↗package ↗

INSTALL

IMPORT

SIG · UNIVERSAL-GITHUB-A

universal-github-app-jwt

auth-securityjavascriptv2.2.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

githubAppJwt

✓ import githubAppJwt from 'universal-github-app-jwt';

✗ import { githubAppJwt } from 'universal-github-app-jwt';

The `githubAppJwt` function is the default export. Use the default import syntax for Node.js or bundled browser environments.

githubAppJwt (Deno/Browser CDN)

✓ import githubAppJwt from 'https://esm.sh/universal-github-app-jwt';

✗ import githubAppJwt from './node_modules/universal-github-app-jwt';

For Deno and direct browser usage, import directly from a CDN like esm.sh.

githubAppJwt (CommonJS)

✓ const githubAppJwt = require('universal-github-app-jwt').default;

✗ const githubAppJwt = require('universal-github-app-jwt');

While primarily an ESM package, if CommonJS is strictly necessary, access the default export via `.default`. ESM `import` is strongly recommended.

Demonstrates how to generate a GitHub App JWT using an application ID and private key, then using it to authenticate an `@octokit/request`.

import githubAppJwt from 'universal-github-app-jwt'; import { request } from '@octokit/request'; const APP_ID = process.env.GITHUB_APP_ID ?? ''; const PRIVATE_KEY = process.env.GITHUB_APP_PRIVATE_KEY ?? ''; async function authenticateApp() { if (!APP_ID || !PRIVATE_KEY) { throw new Error('GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY environment variables must be set.'); } try { const { token, appId, expiration } = await githubAppJwt({ id: APP_ID, privateKey: PRIVATE_KEY, }); console.log(`Generated GitHub App JWT for App ID ${appId}. Expires at: ${new Date(expiration * 1000).toISOString()}`); console.log(`Token: ${token.substring(0, 10)}...${token.substring(token.length - 10)}`); // Example usage with @octokit/request const appDetails = await request('GET /app', { headers: { authorization: `bearer ${token}`, }, }); console.log('Successfully fetched App details:', appDetails.data.name); } catch (error) { console.error('Error generating or using JWT:', error); } } authenticateApp();

Debug

Known issues

gotchaPrivate keys must be in PKCS#8 format and maintain original line breaks. Incorrect formatting (e.g., missing newlines, wrong encryption standard) is a common source of errors. Recent versions (>=2.1.1) automatically handle escaped newlines (`\n`) within the string, but the underlying requirement for a correctly formatted key persists. Consult the package's README for correct `ssh-keygen` options to convert keys to PKCS#8 format.

fix

Ensure your private key is in PKCS#8 format. If generated via `ssh-keygen`, convert it using `ssh-keygen -p -m PKCS8 -f app-private-key.pem`. When setting it as an environment variable, ensure line breaks are preserved or correctly escaped if in a single line (though direct file reading is safer).

affects: >=1.0.0

gotchaThe `options.id` parameter can accept either the GitHub App's numerical ID or its Client ID. For `github.com` and GitHub Enterprise Server (GHES) versions 3.14 and newer, it is recommended to use the Client ID for better alignment with GitHub's authentication practices. Using the App's numerical ID will still work on older or unsupported environments.

fix

For new applications or those targeting `github.com` or modern GHES (3.14+), prioritize using the GitHub App's Client ID for the `options.id` parameter.

affects: >=1.2.0

gotchaWhen running in Node.js, this library relies on the `node:crypto` module, specifically its `subtle` interface. In Bun, previous versions of this library had issues with `subtle` exports. Ensure you are using a compatible runtime version for full functionality.

fix

If encountering crypto-related errors in Bun, upgrade to `universal-github-app-jwt@2.2.1` or newer. For other runtimes, ensure Web Crypto API or Node.js `crypto` module is available and properly configured.

affects: <2.2.1 (Bun)

Errors

Common errors & fixes

Error: Malformed private key

The provided private key string is not in the expected PKCS#8 format or has incorrect line endings, preventing successful parsing.

fix

Verify that your private key starts with `-----BEGIN PRIVATE KEY-----` and ends with `-----END PRIVATE KEY-----`. Ensure all line breaks are preserved exactly as in the `.pem` file. If using an environment variable, ensure proper escaping of newlines or read from a file directly. Convert the key to PKCS#8 if necessary (e.g., `ssh-keygen -p -m PKCS8 -f original-key.pem > new-pkcs8-key.pem`).

TypeError: githubAppJwt is not a function

This error typically occurs when attempting to import the `githubAppJwt` function using an incorrect import style, such as trying to destructure a default export (`import { githubAppJwt } from '...'`) or using `require()` without accessing `.default` in a CommonJS context.

fix

Use the correct ESM default import: `import githubAppJwt from 'universal-github-app-jwt';`. If you must use CommonJS, ensure you access the default export: `const githubAppJwt = require('universal-github-app-jwt').default;`.

ReferenceError: subtle is not defined

The JavaScript runtime environment (browser, Node.js, Deno, Bun) does not expose the `crypto.subtle` API, which is essential for the cryptographic operations performed by this library.

fix

Ensure you are running in a modern browser with Web Crypto API support, a recent Node.js version (15.0.0+ for `crypto.subtle`), Deno, or Bun (>=2.2.1 for specific fixes). If in a browser, ensure it's not an older or highly restricted environment. No polyfills are officially supported by this library.

Upgrade

Version history

2.2.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

24 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/gr2m/universal-github-app-jwt ↗

packagehttps://www.npmjs.com/package/universal-github-app-jwt ↗