feat: universal-github-app-jwt is now a native ES Module (#65)

BREAKING CHANGE: `universal-github-app-jwt` is now a native ES Module

BREAKING CHANGE: `githubAppJwt` is now a default export.

Before

```js
import { githubAppJwt } from "universal-github-app-jwt";
```

now

```js
import githubAppJwt from "universal-github-app-jwt";
```

Author: gr2m

.github/workflows/test.yml

@@ -1,17 +1,33 @@
-"on":
-  - push
-  - pull_request
 name: Test
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, synchronize]
+
 jobs:
-  npmCi:
-    name: test
+  node:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-node@v3
         with:
-          node-version: lts/*
+          node-version: 18
           cache: npm
-      - uses: microsoft/playwright-github-action@v1
       - run: npm ci
       - run: npm test
+  deno:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          cache: npm
+      - uses: denoland/setup-deno@v1
+        with:
+          deno-version: v1.x
+      - run: npm ci
+      - run: npm run build:default
+      - run: npm run test:deno

.gitignore

@@ -1,3 +1,3 @@
+dist/
 coverage/
-node_modules/
-pkg/
+node_modules/

README.md

@@ -2,9 +2,8 @@
 
 > Calculate GitHub App bearer tokens for Node & modern browsers
 
-[![@latest](https://img.shields.io/npm/v/universal-github-app-jwt.svg)](https://www.npmjs.com/package/universal-github-app-jwt)
-![Build status](https://github.com/gr2m/universal-github-app-jwt/workflows/Test/badge.svg)
-[![Greenkeeper](https://badges.greenkeeper.io/gr2m/universal-github-app-jwt.svg)](https://greenkeeper.io/)
+[![@latest](https://img.shields.io/npm/vuniversal-github-app-jwt.svg)](https://www.npmjs.com/packageuniversal-github-app-jwt)
+[![Build Status](https://github.com/gr2m/universal-github-app-jwt/workflows/Test/badge.svg)](https://github.com/gr2m/universal-github-app-jwt/actions?query=workflow%3ATest+branch%3Amaster)
 
 ⚠ The private keys provide by GitHub are in `PKCS#1` format, but the WebCrypto API only supports `PKCS#8`. You can see the difference in the first line, `PKCS#1` format starts with `-----BEGIN RSA PRIVATE KEY-----` while `PKCS#8` starts with `-----BEGIN PRIVATE KEY-----`. You can convert one format to the other using `oppenssl`:
 
@@ -39,56 +38,54 @@ When using a node, a conversion is not necessary, the implementation is agnostic
 <tr><th>
 Browsers
 </th><td width=100%>
-
-Load `universal-github-app-jwt` directly from [cdn.skypack.dev](https://cdn.skypack.dev)
-
+Load <code>universal-github-app-jwt</code> directly from <a href="https://esm.sh">esm.sh</a>
+        
 ```html
 <script type="module">
-  import { githubAppJwt } from "https://cdn.skypack.dev/universal-github-app-jwt";
+import githubAppJwt from "https://esm.sh/universal-github-app-jwt";
 </script>
 ```
 
 </td></tr>
 <tr><th>
-Deno
+Node
 </th><td>
 
+Install with <code>npm install universal-github-app-jwt</code>
+
 ```js
-import { githubAppJwt } from "https://cdn.skypack.dev/universal-github-app-jwt";
+import githubAppJwt from "universal-github-app-jwt";
 ```
 
 </td></tr>
 <tr><th>
-Node
+Deno
 </th><td>
 
-Install with <code>npm install universal-github-app-jwt</code>
+Load <code>universal-github-app-jwt</code> directly from <a href="https://esm.sh">esm.sh</a>, including types.
 
 ```js
-const { githubAppJwt } = require("universal-github-app-jwt");
-// or: import { githubAppJwt } from "universal-github-app-jwt";
+import githubAppJwt from "https://esm.sh/universal-github-app-jwt";
 ```
 
 </td></tr>
 </tbody>
 </table>
 
 ```js
-(async () => {
-  const { token, appId, expiration } = await githubAppJwt({
-    id: APP_ID,
-    privateKey: PRIVATE_KEY
-  });
-})();
+const { token, appId, expiration } = await githubAppJwt({
+  id: APP_ID,
+  privateKey: PRIVATE_KEY,
+});
 ```
 
 The retrieved `token` can now be used in Authorization request header, e.g. with [`@octokit/request`](https://github.com/octokit/request.js/#readme):
 
 ```js
 request("GET /app", {
   headers: {
-    authorization: `bearer ${token}`
-  }
+    authorization: `bearer ${token}`,
+  },
 });
 ```
 

index.d.ts

@@ -0,0 +1,13 @@
+export type Options = {
+  id: number;
+  privateKey: string;
+  now?: number;
+};
+
+export type Result = {
+  appId: number;
+  expiration: number;
+  token: string;
+};
+
+export default function githubAppJwt(options: Options): Promise<Result>;

src/index.ts renamed to index.js

@@ -1,33 +1,38 @@
-import { getToken } from "./get-token";
+// @ts-check
 
-import { Options, Result } from "./types";
+// @ts-ignore - #get-token is defined in "imports" in package.json
+import { getToken } from "#get-token";
 
-export async function githubAppJwt({
+/**
+ * @param {import(".").Options} options
+ * @returns {Promise<import(".").Result>}
+ */
+export default async function githubAppJwt({
   id,
   privateKey,
   now = Math.floor(Date.now() / 1000),
-}: Options): Promise<Result> {
+}) {
   // When creating a JSON Web Token, it sets the "issued at time" (iat) to 30s
   // in the past as we have seen people running situations where the GitHub API
   // claimed the iat would be in future. It turned out the clocks on the
   // different machine were not in sync.
-  const nowWithSafetyMargin = now - 30
+  const nowWithSafetyMargin = now - 30;
   const expiration = nowWithSafetyMargin + 60 * 10; // JWT expiration time (10 minute maximum)
 
   const payload = {
     iat: nowWithSafetyMargin, // Issued at time
     exp: expiration,
-    iss: id
+    iss: id,
   };
 
   const token = await getToken({
     privateKey,
-    payload
+    payload,
   });
 
   return {
     appId: id,
     expiration,
-    token
+    token,
   };
 }

index.test-d.ts

@@ -0,0 +1,13 @@
+import { expectType } from "tsd";
+import githubAppJwt from ".";
+
+export async function test() {
+  const result = await githubAppJwt({
+    id: 123,
+    privateKey: "",
+  });
+
+  expectType<number>(result.appId);
+  expectType<number>(result.expiration);
+  expectType<string>(result.token);
+}

internals.d.ts

@@ -0,0 +1,16 @@
+export type Payload = {
+  iat: number;
+  exp: number;
+  iss: number;
+};
+
+export type Header = { alg: "RS256"; typ: "JWT" };
+
+export type GetTokenOptions = {
+  privateKey: string;
+  payload: Payload;
+};
+
+export interface GetToken {
+  (options: GetTokenOptions): Promise<string>;
+}

jsconfig.json

@@ -0,0 +1,5 @@
+{
+  "compilerOptions": {
+    "strictNullChecks": true
+  }
+}

lib/get-token-node.js

@@ -0,0 +1,13 @@
+// @ts-check
+
+import jsonwebtoken from "jsonwebtoken";
+
+/**
+ * @param {import('../internals').GetTokenOptions} options
+ * @returns {Promise<string>}
+ */
+export async function getToken({ privateKey, payload }) {
+  return jsonwebtoken.sign(payload, privateKey, {
+    algorithm: "RS256",
+  });
+}

src/get-token-browser.ts renamed to lib/get-token.js

@@ -1,15 +1,17 @@
-import { GetTokenOptions, Token } from "./types";
+// we don't @ts-check here because it chokes crypto which is a global API in modern JS runtime environments
+
 import {
   getEncodedMessage,
   getDERfromPEM,
   string2ArrayBuffer,
-  base64encode
-} from "./utils";
+  base64encode,
+} from "./utils.js";
 
-export const getToken = async ({
-  privateKey,
-  payload
-}: GetTokenOptions): Promise<Token> => {
+/**
+ * @param {import('../internals').GetTokenOptions} options
+ * @returns {Promise<string>}
+ */
+export async function getToken({ privateKey, payload }) {
   // WebCrypto only supports PKCS#8, unfortunately
   if (/BEGIN RSA PRIVATE KEY/.test(privateKey)) {
     throw new Error(
@@ -19,8 +21,10 @@ export const getToken = async ({
 
   const algorithm = {
     name: "RSASSA-PKCS1-v1_5",
-    hash: { name: "SHA-256" }
+    hash: { name: "SHA-256" },
   };
+
+  /** @type {import('../internals').Header} */
   const header = { alg: "RS256", typ: "JWT" };
 
   const privateKeyDER = getDERfromPEM(privateKey);
@@ -44,4 +48,4 @@ export const getToken = async ({
   const encodedSignature = base64encode(signatureArrBuf);
 
   return `${encodedMessage}.${encodedSignature}`;
-};
+}

lib/utils.js

@@ -0,0 +1,71 @@
+// we don't @ts-check here because it chokes on atob and btoa which are available in all modern JS runtime environments
+
+/**
+ * @param {string} str
+ * @returns {ArrayBuffer}
+ */
+export function string2ArrayBuffer(str) {
+  const buf = new ArrayBuffer(str.length);
+  const bufView = new Uint8Array(buf);
+  for (let i = 0, strLen = str.length; i < strLen; i++) {
+    bufView[i] = str.charCodeAt(i);
+  }
+  return buf;
+}
+
+/**
+ * @param {string} pem
+ * @returns {ArrayBuffer}
+ */
+export function getDERfromPEM(pem) {
+  const pemB64 = pem
+    .trim()
+    .split("\n")
+    .slice(1, -1) // Remove the --- BEGIN / END PRIVATE KEY ---
+    .join("");
+
+  const decoded = atob(pemB64);
+  return string2ArrayBuffer(decoded);
+}
+
+/**
+ *
+ * @param {import('../internals').Header} header
+ * @param {import('../internals').Payload} payload
+ * @returns {string}
+ */
+export function getEncodedMessage(header, payload) {
+  return `${base64encodeJSON(header)}.${base64encodeJSON(payload)}`;
+}
+
+/**
+ * @param {ArrayBuffer} buffer
+ * @returns {string}
+ */
+export function base64encode(buffer) {
+  var binary = "";
+  var bytes = new Uint8Array(buffer);
+  var len = bytes.byteLength;
+  for (var i = 0; i < len; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+
+  return fromBase64(btoa(binary));
+}
+
+/**
+ * @param {string} base64
+ * @returns {string}
+ */
+function fromBase64(base64) {
+  return base64.replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+
+/**
+ *
+ * @param {Record<string,unknown>} obj
+ * @returns {string}
+ */
+function base64encodeJSON(obj) {
+  return fromBase64(btoa(JSON.stringify(obj)));
+}