feat: support using a remote HSM or JWT signing service in lieu of private keys (#712)

To enable the use of Azure Key Vault keys, or other HSMs, this allows for a callback to be provided in lieu of a GitHub App's private certificate.

Part of octokit/octokit.js#2623

Author: jeffwilcox

README.md

@@ -107,6 +107,40 @@ resolves with
 }
 ```
 
+### Authenticate as GitHub App (remotely-signed JSON Web Token)
+
+If your app's private key is stored in a key management service or hardware security
+module, you can use the `createJwt` option instead of a private key to remotely sign a
+JWT. You provide an async callback to perform the token signing.
+
+```js
+const auth = createAppAuth({
+  appId: 1,
+  createJwt: async (clientId, timeDifference) => {
+    // ... sign the JWT remotely
+    // universal-github-app-jwt accounts for clock skew by issuing at -30s from now
+    // if a timeDifference is present, add that to the seconds
+    return { jwt, expiresAt };
+  }
+  clientId: "lv1.1234567890abcdef",
+  clientSecret: "1234567890abcdef12341234567890abcdef1234",
+});
+
+// Retrieve JSON Web Token (JWT) to authenticate as app
+const appAuthentication = await auth({ type: "app" });
+```
+
+resolves with
+
+```json
+{
+  "type": "app",
+  "token": "jsonwebtoken123",
+  "appId": 123,
+  "expiresAt": "2018-07-07T00:09:30.000Z"
+}
+```
+
 ### Authenticate as OAuth App (client ID/client secret)
 
 The [OAuth Application APIs](https://docs.github.com/en/rest/reference/apps#oauth-applications-api) require the app to authenticate using clientID/client as Basic Authentication
@@ -337,7 +371,7 @@ await installationOctokit.request("POST /repos/{owner}/{repo}/issues", {
         <code>string</code>
       </th>
       <td>
-        <strong>Required</strong>. Content of the <code>*.pem</code> file you downloaded from the app’s about page. You can generate a new private key if needed. If your private key contains escaped newlines (`\\n`), they will be automatically replaced with actual newlines.
+        <strong>Typically required</strong>. Content of the <code>*.pem</code> file you downloaded from the app’s about page. You can generate a new private key if needed. If your private key contains escaped newlines (`\\n`), they will be automatically replaced with actual newlines. Not required when using an external JWT signing service.
       </td>
     </tr>
     <tr>
@@ -479,7 +513,7 @@ Authenticate as the GitHub app to list installations, repositories, and create i
         <code>string</code>
       </th>
       <td>
-        <strong>Required</strong>. Must be either <code>"app"</code>.
+        <strong>Required</strong>. Must be <code>"app"</code>.
       </td>
     </tr>
   </tbody>

src/get-app-authentication.ts

@@ -6,13 +6,24 @@ export async function getAppAuthentication({
   appId,
   privateKey,
   timeDifference,
+  createJwt,
 }: State & {
   timeDifference?: number | undefined;
 }): Promise<AppAuthentication> {
   try {
+    if (createJwt) {
+      const { jwt, expiresAt } = await createJwt(appId, timeDifference);
+      return {
+        type: "app",
+        token: jwt,
+        appId,
+        expiresAt,
+      };
+    }
+
     const authOptions = {
       id: appId,
-      privateKey,
+      privateKey: privateKey as string,
     };
 
     if (timeDifference) {

src/index.ts

@@ -31,9 +31,12 @@ export function createAppAuth(options: StrategyOptions): AuthInterface {
   if (!options.appId) {
     throw new Error("[@octokit/auth-app] appId option is required");
   }
-
-  if (!options.privateKey) {
+  if (!options.privateKey && !options.createJwt) {
     throw new Error("[@octokit/auth-app] privateKey option is required");
+  } else if (options.privateKey && options.createJwt) {
+    throw new Error(
+      "[@octokit/auth-app] privateKey and createJwt options are mutually exclusive",
+    );
   }
   if ("installationId" in options && !options.installationId) {
     throw new Error(

src/types.ts

@@ -9,9 +9,19 @@ type OAuthStrategyOptions = {
   clientSecret?: string;
 };
 
+type AppAuthStrategyOptions = {
+  privateKey: string;
+};
+
+type AppAuthJwtSigningStrategyOptions = {
+  createJwt: (
+    clientIdOrAppId: string | number,
+    timeDifference?: number | undefined,
+  ) => Promise<{ jwt: string; expiresAt: string }>;
+};
+
 type CommonStrategyOptions = {
   appId: number | string;
-  privateKey: string;
   installationId?: number | string;
   request?: OctokitTypes.RequestInterface;
   cache?: Cache;
@@ -23,11 +33,12 @@ type CommonStrategyOptions = {
 
 export type StrategyOptions = OAuthStrategyOptions &
   CommonStrategyOptions &
+  (AppAuthStrategyOptions | AppAuthJwtSigningStrategyOptions) &
   Record<string, unknown>;
 
 // AUTH OPTIONS
 
-export type AppAuthOptions = {
+export type AppAuthOptions = Partial<AppAuthJwtSigningStrategyOptions> & {
   type: "app";
 };
 
@@ -87,7 +98,9 @@ export interface FactoryInstallation<T> {
 
 export interface AuthInterface {
   // app auth
-  (options: AppAuthOptions): Promise<AppAuthentication>;
+  (
+    options: AppAuthOptions | AppAuthJwtSigningStrategyOptions,
+  ): Promise<AppAuthentication>;
   (options: OAuthAppAuthOptions): Promise<OAuthAppAuthentication>;
 
   // installation auth without `factory` option
@@ -196,8 +209,10 @@ export type WithInstallationId = {
   installationId: number;
 };
 
-export type State = Required<Omit<CommonStrategyOptions, "installationId">> & {
-  installationId?: number;
-} & OAuthStrategyOptions & {
+export type State = Required<Omit<CommonStrategyOptions, "installationId">> &
+  Pick<Partial<AppAuthStrategyOptions>, "privateKey"> &
+  Pick<Partial<AppAuthJwtSigningStrategyOptions>, "createJwt"> & {
+    installationId?: number;
+  } & OAuthStrategyOptions & {
     oauthApp: OAuthAppAuth.GitHubAuthInterface;
   };

test/index.test.ts

@@ -39,6 +39,9 @@ x//0u+zd/R/QRUzLOw4N72/Hu+UG6MNt5iDZFCtapRaKt6OvSBwy8w==
 // see https://runkit.com/gr2m/reproducable-jwt
 const BEARER =
   "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOi0zMCwiZXhwIjo1NzAsImlzcyI6MX0.q3foRa78U3WegM5PrWLEh5N0bH1SD62OqW66ZYzArp95JBNiCbo8KAlGtiRENCIfBZT9ibDUWy82cI4g3F09mdTq3bD1xLavIfmTksIQCz5EymTWR5v6gL14LSmQdWY9lSqkgUG0XCFljWUglEP39H4yeHbFgdjvAYg3ifDS12z9oQz2ACdSpvxPiTuCC804HkPVw8Qoy0OSXvCkFU70l7VXCVUxnuhHnk8-oCGcKUspmeP6UdDnXk-Aus-eGwDfJbU2WritxxaXw6B4a3flTPojkYLSkPBr6Pi0H2-mBsW_Nvs0aLPVLKobQd4gqTkosX3967DoAG8luUMhrnxe8Q";
+const SIGN_JWT_CALLBACK = async (/* unused: clientId */) => {
+  return { jwt: BEARER, expiresAt: "1970-01-01T00:09:30.000Z" };
+};
 
 beforeEach(() => {
   vi.useFakeTimers().setSystemTime(0);
@@ -60,6 +63,22 @@ test("README example for app auth", async () => {
   });
 });
 
+test("README example for app auth via external JWT signing", async () => {
+  const auth = createAppAuth({
+    appId: APP_ID,
+    createJwt: SIGN_JWT_CALLBACK,
+  });
+
+  const authentication = await auth({ type: "app" });
+
+  expect(authentication).toEqual({
+    type: "app",
+    token: BEARER,
+    appId: 1,
+    expiresAt: "1970-01-01T00:09:30.000Z",
+  });
+});
+
 test("README example for OAuth app auth", async () => {
   const auth = createAppAuth({
     appId: APP_ID,
@@ -2429,11 +2448,36 @@ test("throws helpful error if `privateKey` is not set properly (#184)", async ()
     createAppAuth({
       appId: APP_ID,
       // @ts-ignore
-      privateKey: undefined,
+      privateKey: undefined as string,
     });
   }).toThrowError("[@octokit/auth-app] privateKey option is required");
 });
 
+test("throws helpful error if `privateKey` and `createJwt` are both set", async () => {
+  expect(() => {
+    createAppAuth({
+      appId: APP_ID,
+      // @ts-ignore
+      privateKey: PRIVATE_KEY,
+      // @ts-ignore
+      createJwt: SIGN_JWT_CALLBACK,
+    });
+  }).toThrowError(
+    "[@octokit/auth-app] privateKey and createJwt options are mutually exclusive",
+  );
+});
+
+test("does not throw an error if an `createJwt` callback is provided in lieu of a `privateKey`", async () => {
+  expect(() => {
+    createAppAuth({
+      appId: APP_ID,
+      createJwt: SIGN_JWT_CALLBACK,
+      // // @ts-ignore
+      // privateKey: undefined,
+    });
+  }).not.toThrow();
+});
+
 test("throws helpful error if `installationId` is set to a falsy value in createAppAuth() (#184)", async () => {
   expect(() => {
     createAppAuth({

test/typescript-validate.ts

@@ -22,6 +22,17 @@ export async function readmeExample() {
   await auth({ type: "oauth-user", code: "123456" });
 }
 
+export async function readmeJwtSigningExample() {
+  const auth = createAppAuth({
+    appId: 1,
+    createJwt: async (clientId: string | number) => {
+      return { jwt: "", expiresAt: "" };
+    },
+  });
+
+  await auth({ type: "app" });
+}
+
 // https://github.com/octokit/auth-app.js/issues/282
 export async function issue282() {
   const auth = createAppAuth({