Add verify with fallback

README.md

@@ -14,6 +14,7 @@
 - [Methods](#methods)
   - [`sign()`](#sign)
   - [`verify()`](#verify)
+  - [`verifyWithFallback()`](#verifyWithFallback)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -40,6 +41,7 @@ Load `@octokit/webhooks-methods` directly from [cdn.skypack.dev](https://cdn.sky
   import {
     sign,
     verify,
+    verifyWithFallback,
   } from "https://cdn.skypack.dev/@octokit/webhooks-methods";
 </script>
 ```
@@ -54,7 +56,11 @@ Node
 Install with `npm install @octokit/core @octokit/webhooks-methods`
 
 ```js
-const { sign, verify } = require("@octokit/webhooks-methods");
+const {
+  sign,
+  verify,
+  verifyWithFallback,
+} = require("@octokit/webhooks-methods");
 ```
 
 </td></tr>
@@ -70,6 +76,9 @@ await sign({ secret: "mysecret", algorithm: "sha1" }, eventPayloadString);
 
 await verify("mysecret", eventPayloadString, "sha256=486d27...");
 // resolves with true or false
+
+await verifyWithFallback("mysecret", eventPayloadString, "sha256=486d27...", ["oldsecret", ...]);
+// resolves with true or false
 ```
 
 ## Methods
@@ -184,6 +193,78 @@ await verify(secret, eventPayloadString, signature);
 
 Resolves with `true` or `false`. Throws error if an argument is missing.
 
+### `verifyWithFallback()`
+
+```js
+await verifyWithFallback(
+  secret,
+  eventPayloadString,
+  signature,
+  additionalSecrets
+);
+```
+
+<table width="100%">
+  <tr>
+    <td>
+      <code>
+        secret
+      </code>
+      <em>(String)</em>
+    </td>
+    <td>
+      <strong>Required.</strong>
+      Secret as configured in GitHub Settings.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>
+        eventPayloadString
+      </code>
+      <em>
+        (String)
+      </em>
+    </td>
+    <td>
+      <strong>Required.</strong>
+      Webhook request payload as received from GitHub.<br>
+      <br>
+      If you have only access to an already parsed object, stringify it with <code>JSON.stringify(payload)</code>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>
+        signature
+      </code>
+      <em>
+        (String)
+      </em>
+    </td>
+    <td>
+      <strong>Required.</strong>
+      Signature string as calculated by <code><a href="../sign">sign()</a></code>.
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <code>
+        additionalSecrets
+      </code>
+      <em>
+        (Array of String)
+      </em>
+    </td>
+    <td>
+        If given, each additional secret will be tried in turn.
+    </td>
+  </tr>
+</table>
+
+This is a thin wrapper around [`verify()`](#verify) that is intended to ease callers' support for key rotation.
+Resolves with `true` or `false`. Throws error if a required argument is missing.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md)

src/index.ts

@@ -1,2 +1,27 @@
 export { sign } from "./node/sign";
-export { verify } from "./node/verify";
+import { verify } from "./node/verify";
+export { verify };
+
+export async function verifyWithFallback(
+  secret: string,
+  payload: string,
+  signature: string,
+  additionalSecrets: undefined | string[]
+): Promise<any> {
+  const firstPass = await verify(secret, payload, signature);
+
+  if (firstPass) {
+    return true;
+  }
+
+  if (additionalSecrets !== undefined) {
+    for (const s of additionalSecrets) {
+      const v: boolean = await verify(s, payload, signature);
+      if (v) {
+        return v;
+      }
+    }
+  }
+
+  return false;
+}

test/verify.test.ts

@@ -1,4 +1,4 @@
-import { verify } from "../src";
+import { verify, verifyWithFallback } from "../src";
 
 function toNormalizedJsonString(payload: object) {
   // GitHub sends its JSON with an indentation of 2 spaces and a line break at the end
@@ -108,7 +108,7 @@ describe("verify", () => {
     expect(signatureMatches).toBe(false);
   });
 
-  test("verify(secret, eventPayload, signatureSHA256) returns false for correct secret", async () => {
+  test("verify(secret, eventPayload, signatureSHA256) returns false for incorrect secret", async () => {
     const signatureMatches = await verify("foo", eventPayload, signatureSHA256);
     expect(signatureMatches).toBe(false);
   });
@@ -141,3 +141,39 @@ describe("verify", () => {
     expect(signatureMatchesEscapedSequence).toBe(true);
   });
 });
+
+describe("verifyWithFallback", () => {
+  it("is a function", () => {
+    expect(verifyWithFallback).toBeInstanceOf(Function);
+  });
+
+  test("verifyWithFallback(secret, eventPayload, signatureSHA256, [bogus]) returns true", async () => {
+    const signatureMatches = await verifyWithFallback(
+      secret,
+      eventPayload,
+      signatureSHA256,
+      ["foo"]
+    );
+    expect(signatureMatches).toBe(true);
+  });
+
+  test("verifyWithFallback(bogus, eventPayload, signatureSHA256, [secret]) returns true", async () => {
+    const signatureMatches = await verifyWithFallback(
+      "foo",
+      eventPayload,
+      signatureSHA256,
+      [secret]
+    );
+    expect(signatureMatches).toBe(true);
+  });
+
+  test("verify(bogus, eventPayload, signatureSHA256, [bogus]) returns false", async () => {
+    const signatureMatches = await verifyWithFallback(
+      "foo",
+      eventPayload,
+      signatureSHA256,
+      ["foo"]
+    );
+    expect(signatureMatches).toBe(false);
+  });
+});