Offer an option to specify a cache for conditionally fetching public keys

index.d.ts

@@ -6,6 +6,10 @@ type RequestInterface = typeof request;
 type RequestOptions = {
   request?: RequestInterface;
   token?: string;
+  cache?: {
+    id: string;
+    keys: VerificationPublicKey[];
+  };
 };
 export type VerificationPublicKey = {
   key_identifier: string;
@@ -18,7 +22,13 @@ interface VerifyRequestInterface {
 }
 
 interface FetchVerificationKeysInterface {
-  (requestOptions?: RequestOptions): Promise<VerificationPublicKey[]>;
+  (
+    requestOptions?: RequestOptions,
+  ): Promise<{ cacheId: string; keys: VerificationPublicKey[] }>;
+}
+
+interface VerifyRequest {
+  (rawBody: string, signature: string, keyId: string): boolean;
 }
 
 interface VerifyRequestByKeyIdInterface {
@@ -27,7 +37,7 @@ interface VerifyRequestByKeyIdInterface {
     signature: string,
     keyId: string,
     requestOptions?: RequestOptions,
-  ): Promise<boolean>;
+  ): Promise<{ isValid: boolean; cacheId: string }>;
 }
 
 // response types

index.test-d.ts

@@ -32,7 +32,7 @@ export async function verifyRequestByKeyIdTest(
   keyId: string,
 ) {
   const result = await verifyRequestByKeyId(rawBody, signature, keyId);
-  expectType<boolean>(result);
+  expectType<{ isValid: boolean; cacheId: string }>(result);
 
   // @ts-expect-error - first 3 arguments are required
   verifyRequestByKeyId(rawBody, signature);
@@ -76,13 +76,16 @@ export async function verifyRequestTest(
 
 export async function fetchVerificationKeysTest() {
   const result = await fetchVerificationKeys();
-  expectType<VerificationPublicKey[]>(result);
+  expectType<{ cacheId: string; keys: VerificationPublicKey[] }>(result);
 
   // accepts a token argument
   await fetchVerificationKeys({ token });
 
   // accepts a request argument
   await fetchVerificationKeys({ request });
+
+  // accepts a cache argument
+  await fetchVerificationKeys({ cache: { id: "test", keys: [] } });
 }
 
 export function createAckEventTest() {

lib/parse.js

@@ -22,15 +22,15 @@ export function transformPayloadForOpenAICompatibility(payload) {
 
 /** @type {import('..').VerifyAndParseRequestInterface} */
 export async function verifyAndParseRequest(body, signature, keyID, options) {
-  const isValidRequest = await verifyRequestByKeyId(
+  const { isValid } = await verifyRequestByKeyId(
     body,
     signature,
     keyID,
     options
   );
 
   return {
-    isValidRequest,
+    isValidRequest: isValid,
     payload: parseRequestBody(body),
   };
 }

lib/verification.js

@@ -4,36 +4,45 @@ import { createVerify } from "node:crypto";
 
 import { request as defaultRequest } from "@octokit/request";
 
-/** @type {import('..').VerifyRequestByKeyIdInterface} */
-export async function verifyRequest(rawBody, signature, key) {
+/** @type {import('..').VerifyRequest} */
+export async function verifyRequest(rawBody, signature, keyId) {
   // verify arguments
   assertValidString(rawBody, "Invalid payload");
   assertValidString(signature, "Invalid signature");
-  assertValidString(key, "Invalid key");
+  assertValidString(keyId, "Invalid key");
 
   // verify signature
   try {
     return createVerify("SHA256")
       .update(rawBody)
-      .verify(key, signature, "base64");
+      .verify(keyId, signature, "base64");
   } catch {
     return false;
   }
 }
 
 /** @type {import('..').FetchVerificationKeysInterface} */
 export async function fetchVerificationKeys(
-  { token = "", request = defaultRequest } = { request: defaultRequest }
+  { token = "", request = defaultRequest, cache = { id: "", keys: [] } } = { request: defaultRequest }
 ) {
-  const { data } = await request("GET /meta/public_keys/copilot_api", {
-    headers: token
-      ? {
-          Authorization: `token ${token}`,
-        }
-      : {},
+  const headers = token
+    ? {
+        Authorization: `token ${token}`,
+      }
+    : {};
+
+  if (cache.id) headers["If-None-Match"] = cache.id;
+
+  const response = await request("GET /meta/public_keys/copilot_api", {
+    headers,
   });
 
-  return data.public_keys;
+  if (response.status === 304) {
+    return { cacheId: cache.id, keys: cache.keys };
+  }
+
+  const cacheId = response.headers.etag || "";
+  return { cacheId, keys: response.data.public_keys };
 }
 
 /** @type {import('..').VerifyRequestByKeyIdInterface} */
@@ -49,7 +58,7 @@ export async function verifyRequestByKeyId(
   assertValidString(keyId, "Invalid keyId");
 
   // receive valid public keys from GitHub
-  const keys = await fetchVerificationKeys(requestOptions);
+  const { cacheId, keys } = await fetchVerificationKeys(requestOptions);
 
   // verify provided key Id
   const publicKey = keys.find((key) => key.key_identifier === keyId);
@@ -67,7 +76,8 @@ export async function verifyRequestByKeyId(
     throw keyNotFoundError;
   }
 
-  return verifyRequest(rawBody, signature, publicKey.key);
+  const isValid = await verifyRequest(rawBody, signature, publicKey.key);
+  return { isValid, cacheId };
 }
 
 function assertValidString(value, message) {

test/verification.test.js

@@ -67,7 +67,7 @@ test("verifyRequestByKeyId()", async (t) => {
     request: testRequest,
   });
 
-  t.deepEqual(result, true);
+  t.deepEqual(result, { isValid: true, cacheId: "" });
 });
 
 test("verifyRequestByKeyId() - invalid arguments", async (t) => {
@@ -132,7 +132,7 @@ test("verifyRequest() - invalid", async (t) => {
   t.deepEqual(result, false);
 });
 
-test("fetchVerificationKeys()", async (t) => {
+test("fetchVerificationKeys() - without cache", async (t) => {
   const mockAgent = new MockAgent();
   function fetchMock(url, opts) {
     opts ||= {};
@@ -180,5 +180,8 @@ test("fetchVerificationKeys()", async (t) => {
     request: testRequest,
   });
 
-  t.deepEqual(result, publicKeys);
+  t.deepEqual(result, { cacheId: "", keys: publicKeys });
 });
+
+// Up next: test the cache
+// test("fetchVerificationKeys() - with cache", async (t) => { });