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

index.d.ts

@@ -3,9 +3,14 @@ import { request } from "@octokit/request";
 // verification types
 
 type RequestInterface = typeof request;
+export type VerificationKeysCache = {
+  id: string;
+  keys: VerificationPublicKey[];
+};
 type RequestOptions = {
   request?: RequestInterface;
   token?: string;
+  cache?: VerificationKeysCache;
 };
 export type VerificationPublicKey = {
   key_identifier: string;
@@ -14,11 +19,11 @@ export type VerificationPublicKey = {
 };
 
 interface VerifyRequestInterface {
-  (rawBody: string, signature: string, key: string): Promise<boolean>;
+  (rawBody: string, signature: string, key: string): boolean;
 }
 
 interface FetchVerificationKeysInterface {
-  (requestOptions?: RequestOptions): Promise<VerificationPublicKey[]>;
+  (requestOptions?: RequestOptions): Promise<VerificationKeysCache>;
 }
 
 interface VerifyRequestByKeyIdInterface {
@@ -27,7 +32,10 @@ interface VerifyRequestByKeyIdInterface {
     signature: string,
     keyId: string,
     requestOptions?: RequestOptions,
-  ): Promise<boolean>;
+  ): Promise<{
+    isValid: boolean;
+    cache: VerificationKeysCache;
+  }>;
 }
 
 // response types

index.test-d.ts

@@ -22,6 +22,7 @@ import {
   prompt,
   PromptResult,
   getFunctionCalls,
+  VerificationKeysCache,
 } from "./index.js";
 
 const token = "";
@@ -32,7 +33,10 @@ export async function verifyRequestByKeyIdTest(
   keyId: string,
 ) {
   const result = await verifyRequestByKeyId(rawBody, signature, keyId);
-  expectType<boolean>(result);
+  expectType<{
+    isValid: boolean;
+    cache: { id: string; keys: VerificationPublicKey[] };
+  }>(result);
 
   // @ts-expect-error - first 3 arguments are required
   verifyRequestByKeyId(rawBody, signature);
@@ -76,13 +80,16 @@ export async function verifyRequestTest(
 
 export async function fetchVerificationKeysTest() {
   const result = await fetchVerificationKeys();
-  expectType<VerificationPublicKey[]>(result);
+  expectType<{ id: 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,7 +4,7 @@ import { createVerify } from "node:crypto";
 
 import { request as defaultRequest } from "@octokit/request";
 
-/** @type {import('..').VerifyRequestByKeyIdInterface} */
+/** @type {import('..').VerifyRequestInterface} */
 export async function verifyRequest(rawBody, signature, key) {
   // verify arguments
   assertValidString(rawBody, "Invalid payload");
@@ -23,17 +23,35 @@ export async function verifyRequest(rawBody, signature, key) {
 
 /** @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
+    try {
+    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,
+    });
+
+    if (response.status === 304) {
+      return cache;
+    }
+
+    const cacheId = response.headers.etag || "";
+    return { id: cacheId, keys: response.data.public_keys };
+  } catch (error) {
+    if (error.status === 304) {
+      return cache;
+    }
+
+    throw error;
+  }
 
-  return data.public_keys;
 }
 
 /** @type {import('..').VerifyRequestByKeyIdInterface} */
@@ -49,7 +67,7 @@ export async function verifyRequestByKeyId(
   assertValidString(keyId, "Invalid keyId");
 
   // receive valid public keys from GitHub
-  const keys = await fetchVerificationKeys(requestOptions);
+  const { id, keys } = await fetchVerificationKeys(requestOptions);
 
   // verify provided key Id
   const publicKey = keys.find((key) => key.key_identifier === keyId);
@@ -67,7 +85,8 @@ export async function verifyRequestByKeyId(
     throw keyNotFoundError;
   }
 
-  return verifyRequest(rawBody, signature, publicKey.key);
+  const isValid = await verifyRequest(rawBody, signature, publicKey.key);
+  return { isValid, cache: { id: id, keys } };
 }
 
 function assertValidString(value, message) {

test/verification.test.js

@@ -34,6 +34,14 @@ test("verifyRequestByKeyId()", async (t) => {
     return fetch(url, opts);
   }
 
+  const publicKeys = [
+    {
+      key: CURRENT_PUBLIC_KEY,
+      key_identifier: KEY_ID,
+      is_current: true,
+    },
+  ];
+
   mockAgent.disableNetConnect();
   const mockPool = mockAgent.get("https://api.github.com");
   mockPool
@@ -44,13 +52,7 @@ test("verifyRequestByKeyId()", async (t) => {
     .reply(
       200,
       {
-        public_keys: [
-          {
-            key: CURRENT_PUBLIC_KEY,
-            key_identifier: KEY_ID,
-            is_current: true,
-          },
-        ],
+        public_keys: publicKeys,
       },
       {
         headers: {
@@ -67,7 +69,7 @@ test("verifyRequestByKeyId()", async (t) => {
     request: testRequest,
   });
 
-  t.deepEqual(result, true);
+  t.deepEqual(result, { isValid: true, cache: { id: "", keys: publicKeys } });
 });
 
 test("verifyRequestByKeyId() - invalid arguments", async (t) => {
@@ -132,7 +134,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 +182,57 @@ test("fetchVerificationKeys()", async (t) => {
     request: testRequest,
   });
 
-  t.deepEqual(result, publicKeys);
+  t.deepEqual(result, { id: "", keys: publicKeys });
+});
+
+test("fetchVerificationKeys() - with cache", async (t) => {
+  const mockAgent = new MockAgent();
+  function fetchMock(url, opts) {
+    opts ||= {};
+    opts.dispatcher = mockAgent;
+    return fetch(url, opts);
+  }
+
+  const publicKeys = [
+    {
+      key: "<key 1>",
+      key_identifier: "<key-id 1>",
+      is_current: true,
+    },
+    {
+      key: "<key 2>",
+      key_identifier: "<key-id 2>",
+      is_current: true,
+    },
+  ];
+
+  mockAgent.disableNetConnect();
+  const mockPool = mockAgent.get("https://api.github.com");
+  mockPool
+    .intercept({
+      method: "get",
+      path: `/meta/public_keys/copilot_api`,
+    })
+    .reply(
+      304,
+      {},
+      {
+        headers: {
+          "content-type": "application/json",
+          "x-request-id": "<request-id>",
+        },
+      },
+    );
+  const testRequest = defaultRequest.defaults({
+    request: { fetch: fetchMock },
+  });
+
+  const cache = { id: "etag-value", keys: publicKeys };
+
+  const result = await fetchVerificationKeys({
+    request: testRequest,
+    cache,
+  });
+
+  t.deepEqual(result, cache);
 });