feat(core): support signing key rotation (#1732)

packages/core/jest.setup.ts

@@ -9,7 +9,7 @@ import { privateKeyPath } from './jest.global-setup';
 (async () => {
   process.env = {
     ...process.env,
-    OIDC_PRIVATE_KEY_PATH: privateKeyPath,
+    OIDC_PRIVATE_KEY_PATHS: `["${privateKeyPath}"]`,
     OIDC_COOKIE_KEYS: '["LOGTOSEKRIT1"]',
   };
   await envSet.load();

packages/core/src/env-set/oidc.test.ts

@@ -0,0 +1,110 @@
+import crypto from 'crypto';
+import fs, { PathOrFileDescriptor } from 'fs';
+
+import inquirer from 'inquirer';
+
+import { readPrivateKeys } from './oidc';
+
+describe('oidc env-set', () => {
+  const envBackup = process.env;
+
+  beforeEach(() => {
+    process.env = { ...envBackup };
+  });
+
+  afterEach(() => {
+    jest.clearAllMocks();
+    jest.resetModules();
+  });
+
+  it('should read private keys if `OIDC_PRIVATE_KEYS` is provided', async () => {
+    process.env.OIDC_PRIVATE_KEYS = '["foo","bar"]';
+
+    const privateKeys = await readPrivateKeys();
+
+    expect(privateKeys).toEqual(['foo', 'bar']);
+  });
+
+  it('should read private keys if `OIDC_PRIVATE_KEY` is provided - [compatibility]', async () => {
+    process.env.OIDC_PRIVATE_KEY = 'foo';
+
+    const privateKeys = await readPrivateKeys();
+
+    expect(privateKeys).toEqual(['foo']);
+  });
+
+  it('should read private keys if `OIDC_PRIVATE_KEY_PATHS` is provided', async () => {
+    process.env.OIDC_PRIVATE_KEY_PATHS = '["foo.pem", "bar.pem"]';
+    const existsSyncSpy = jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+    const readFileSyncSpy = jest
+      .spyOn(fs, 'readFileSync')
+      .mockImplementation((path: PathOrFileDescriptor) => path.toString());
+
+    const privateKeys = await readPrivateKeys();
+
+    expect(privateKeys).toEqual(['foo.pem', 'bar.pem']);
+
+    existsSyncSpy.mockRestore();
+    readFileSyncSpy.mockRestore();
+  });
+
+  it('should read private keys if `OIDC_PRIVATE_KEY_PATH` is provided - [compatibility]', async () => {
+    // Unset the `OIDC_PRIVATE_KEY_PATHS` environment variable config by jest.setup.ts.
+    process.env.OIDC_PRIVATE_KEY_PATHS = '';
+
+    process.env.OIDC_PRIVATE_KEY_PATH = 'foo.pem';
+
+    const existsSyncSpy = jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+
+    const readFileSyncSpy = jest
+      .spyOn(fs, 'readFileSync')
+      .mockImplementation((path: PathOrFileDescriptor) => path.toString());
+
+    const privateKeys = await readPrivateKeys();
+
+    expect(privateKeys).toEqual(['foo.pem']);
+
+    existsSyncSpy.mockRestore();
+    readFileSyncSpy.mockRestore();
+  });
+
+  it('should throw if private keys configured in `OIDC_PRIVATE_KEY_PATHS` are not found', async () => {
+    process.env.OIDC_PRIVATE_KEY_PATHS = '["foo.pem","bar.pem"]';
+    const existsSyncSpy = jest.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+    await expect(readPrivateKeys).rejects.toMatchError(
+      new Error(
+        `Private keys ${process.env.OIDC_PRIVATE_KEY_PATHS} configured in env \`OIDC_PRIVATE_KEY_PATHS\` not found.`
+      )
+    );
+
+    existsSyncSpy.mockRestore();
+  });
+
+  it('should generate a default private key if `OIDC_PRIVATE_KEY_PATHS` and `OIDC_PRIVATE_KEYS` are not provided', async () => {
+    process.env.OIDC_PRIVATE_KEYS = '';
+    process.env.OIDC_PRIVATE_KEY_PATHS = '';
+
+    const readFileSyncSpy = jest.spyOn(fs, 'readFileSync').mockImplementation(() => {
+      throw new Error('Intent read file error');
+    });
+
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    const writeFileSyncSpy = jest.spyOn(fs, 'writeFileSync').mockImplementation(() => {});
+
+    const promptMock = jest.spyOn(inquirer, 'prompt').mockResolvedValue({ confirm: true });
+
+    const generateKeyPairSyncSpy = jest.spyOn(crypto, 'generateKeyPairSync');
+
+    const privateKeys = await readPrivateKeys();
+
+    expect(privateKeys.length).toBe(1);
+    expect(generateKeyPairSyncSpy).toHaveBeenCalled();
+    expect(writeFileSyncSpy).toHaveBeenCalled();
+
+    readFileSyncSpy.mockRestore();
+    promptMock.mockRestore();
+    generateKeyPairSyncSpy.mockRestore();
+    writeFileSyncSpy.mockRestore();
+  });
+});

packages/core/src/env-set/oidc.ts

@@ -1,66 +1,105 @@
 import crypto, { generateKeyPairSync } from 'crypto';
-import { readFileSync, writeFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
 
 import { getEnv } from '@silverhand/essentials';
 import inquirer from 'inquirer';
+import { createLocalJWKSet } from 'jose';
 import { nanoid } from 'nanoid';
 
+import { exportJWK } from '@/utils/jwks';
+
 import { appendDotEnv } from './dot-env';
 import { allYes, noInquiry } from './parameters';
+import { getEnvAsStringArray } from './utils';
+
+const defaultLogtoOidcPrivateKey = './oidc-private-key.pem';
 
 /**
- * Try to read private key with the following order:
+ * Try to read private keys with the following order:
  *
- * 1. From `process.env.OIDC_PRIVATE_KEY`.
- * 2. Fetch path from `process.env.OIDC_PRIVATE_KEY_PATH` then read from that path.
+ * 1. From `process.env.OIDC_PRIVATE_KEYS`.
+ * 2. Fetch path from `process.env.OIDC_PRIVATE_KEY_PATHS` then read from that path.
  *
  * If none of above succeed, then inquire user to generate a new key if no `--no-inquiry` presents in argv.
  *
- * @returns The private key for OIDC provider.
+ * @returns The private keys for OIDC provider.
  * @throws An error when failed to read a private key.
  */
-const readPrivateKey = async (): Promise<string> => {
-  const privateKey = getEnv('OIDC_PRIVATE_KEY');
+export const readPrivateKeys = async (): Promise<string[]> => {
+  const privateKeys = getEnvAsStringArray('OIDC_PRIVATE_KEYS');
 
-  if (privateKey) {
-    return privateKey;
+  if (privateKeys.length > 0) {
+    return privateKeys;
   }
 
-  const privateKeyPath = getEnv('OIDC_PRIVATE_KEY_PATH', './oidc-private-key.pem');
+  // Downward compatibility for `OIDC_PRIVATE_KEY`
+  const compatPrivateKey = getEnv('OIDC_PRIVATE_KEY');
 
-  try {
-    return readFileSync(privateKeyPath, 'utf8');
-  } catch (error: unknown) {
-    if (noInquiry) {
-      throw error;
-    }
+  if (compatPrivateKey) {
+    return [compatPrivateKey];
+  }
 
-    if (!allYes) {
-      const answer = await inquirer.prompt({
-        type: 'confirm',
-        name: 'confirm',
-        message: `No private key found in env \`OIDC_PRIVATE_KEY\` nor \`${privateKeyPath}\`, would you like to generate a new one?`,
-      });
+  // Downward compatibility for `OIDC_PRIVATE_KEY_PATH`
+  const originPrivateKeyPath = getEnv('OIDC_PRIVATE_KEY_PATH');
+  const privateKeyPaths = getEnvAsStringArray(
+    'OIDC_PRIVATE_KEY_PATHS',
+    originPrivateKeyPath ? [originPrivateKeyPath] : []
+  );
 
-      if (!answer.confirm) {
+  // If no private key path is found, ask the user to generate a new one.
+  if (privateKeyPaths.length === 0) {
+    try {
+      return [readFileSync(defaultLogtoOidcPrivateKey, 'utf8')];
+    } catch (error: unknown) {
+      if (noInquiry) {
         throw error;
       }
+
+      if (!allYes) {
+        const answer = await inquirer.prompt({
+          type: 'confirm',
+          name: 'confirm',
+          message: `No private key found in env \`OIDC_PRIVATE_KEYS\` nor \`${defaultLogtoOidcPrivateKey}\`, would you like to generate a new one?`,
+        });
+
+        if (!answer.confirm) {
+          throw error;
+        }
+      }
+
+      const { privateKey } = generateKeyPairSync('rsa', {
+        modulusLength: 4096,
+        publicKeyEncoding: {
+          type: 'spki',
+          format: 'pem',
+        },
+        privateKeyEncoding: {
+          type: 'pkcs8',
+          format: 'pem',
+        },
+      });
+      writeFileSync(defaultLogtoOidcPrivateKey, privateKey);
+
+      return [privateKey];
     }
+  }
 
-    const { privateKey } = generateKeyPairSync('rsa', {
-      modulusLength: 4096,
-      publicKeyEncoding: {
-        type: 'spki',
-        format: 'pem',
-      },
-      privateKeyEncoding: {
-        type: 'pkcs8',
-        format: 'pem',
-      },
-    });
-    writeFileSync(privateKeyPath, privateKey);
+  const notExistPrivateKeys = privateKeyPaths.filter((path): boolean => !existsSync(path));
 
-    return privateKey;
+  if (notExistPrivateKeys.length > 0) {
+    const notExistPrivateKeysRawValue = JSON.stringify(notExistPrivateKeys);
+    throw new Error(
+      `Private keys ${notExistPrivateKeysRawValue} configured in env \`OIDC_PRIVATE_KEY_PATHS\` not found.`
+    );
+  }
+
+  try {
+    return privateKeyPaths.map((path): string => readFileSync(path, 'utf8'));
+  } catch {
+    const privateKeyPathsRawValue = JSON.stringify(privateKeyPaths);
+    throw new Error(
+      `Failed to read private keys from ${privateKeyPathsRawValue} in env \`OIDC_PRIVATE_KEY_PATHS\`.`
+    );
   }
 };
 
@@ -73,45 +112,48 @@ const readPrivateKey = async (): Promise<string> => {
  */
 const readCookieKeys = async (): Promise<string[]> => {
   const envKey = 'OIDC_COOKIE_KEYS';
+  const keys = getEnvAsStringArray(envKey);
 
-  try {
-    const keys: unknown = JSON.parse(getEnv(envKey));
-
-    if (Array.isArray(keys) && keys.every((key): key is string => typeof key === 'string')) {
-      return keys;
-    }
-  } catch (error: unknown) {
-    if (noInquiry) {
-      throw error;
-    }
-
-    if (!allYes) {
-      const answer = await inquirer.prompt({
-        type: 'confirm',
-        name: 'confirm',
-        message: `No cookie keys array found in env \`${envKey}\`, would you like to generate a new one?`,
-      });
-
-      if (!answer.confirm) {
-        throw error;
-      }
-    }
-
-    const generated = [nanoid()];
-    appendDotEnv(envKey, JSON.stringify(generated));
-
-    return generated;
+  if (keys.length > 0) {
+    return keys;
   }
 
-  throw new Error(
-    `The OIDC cookie keys array is missing or in a wrong format. Please check the value of env \`${envKey}\`.`
+  const cookieKeysMissingError = new Error(
+    `The OIDC cookie keys array is missing, Please check the value of env \`${envKey}\`.`
   );
+
+  if (noInquiry) {
+    throw cookieKeysMissingError;
+  }
+
+  if (!allYes) {
+    const answer = await inquirer.prompt({
+      type: 'confirm',
+      name: 'confirm',
+      message: `No cookie keys array found in env \`${envKey}\`, would you like to generate a new one?`,
+    });
+
+    if (!answer.confirm) {
+      throw cookieKeysMissingError;
+    }
+  }
+
+  const generated = [nanoid()];
+  appendDotEnv(envKey, JSON.stringify(generated));
+
+  return generated;
 };
 
 const loadOidcValues = async (issuer: string) => {
   const cookieKeys = await readCookieKeys();
-  const privateKey = crypto.createPrivateKey(await readPrivateKey());
-  const publicKey = crypto.createPublicKey(privateKey);
+
+  const configPrivateKeys = await readPrivateKeys();
+  const privateKeys = configPrivateKeys.map((key) => crypto.createPrivateKey(key));
+  const publicKeys = privateKeys.map((key) => crypto.createPublicKey(key));
+  const privateJwks = await Promise.all(privateKeys.map(async (key) => exportJWK(key)));
+  const publicJwks = await Promise.all(publicKeys.map(async (key) => exportJWK(key)));
+  const localJWKSet = createLocalJWKSet({ keys: publicJwks });
+
   /**
    * This interval helps to avoid concurrency issues when exchanging the rotating refresh token multiple times within a given timeframe.
    * During the leeway window (in seconds), the consumed refresh token will be considered as valid.
@@ -121,8 +163,8 @@ const loadOidcValues = async (issuer: string) => {
 
   return Object.freeze({
     cookieKeys,
-    privateKey,
-    publicKey,
+    privateJwks,
+    localJWKSet,
     issuer,
     refreshTokenReuseInterval: Number(refreshTokenReuseInterval),
     defaultIdTokenTtl: 60 * 60,

packages/core/src/env-set/utils.ts

@@ -0,0 +1,50 @@
+import { getEnv } from '@silverhand/essentials';
+
+class EnvParseError extends Error {
+  constructor(envKey: string, errorMessage: string) {
+    super(`Failed to parse env \`${envKey}\`: ${errorMessage}`);
+  }
+}
+
+class InvalidStringArrayValueError extends Error {
+  message = 'the value should be an array of strings.';
+}
+
+// TODO: LOG-3870 - Add `getEnvAsStringArray` to `@silverhand/essentials`
+export const getEnvAsStringArray = (envKey: string, fallback: string[] = []): string[] => {
+  const rawValue = getEnv(envKey);
+
+  if (!rawValue) {
+    return fallback;
+  }
+
+  try {
+    return convertEnvToStringArray(rawValue);
+  } catch (error: unknown) {
+    if (error instanceof InvalidStringArrayValueError) {
+      throw new EnvParseError(envKey, error.message);
+    }
+    throw error;
+  }
+};
+
+const convertEnvToStringArray = (value: string): string[] => {
+  // eslint-disable-next-line @silverhand/fp/no-let
+  let values: unknown;
+
+  try {
+    // eslint-disable-next-line @silverhand/fp/no-mutation
+    values = JSON.parse(value);
+  } catch {
+    throw new InvalidStringArrayValueError();
+  }
+
+  if (
+    !Array.isArray(values) ||
+    !values.every((value): value is string => typeof value === 'string')
+  ) {
+    throw new InvalidStringArrayValueError();
+  }
+
+  return values;
+};

packages/core/src/middleware/koa-auth.ts

@@ -47,10 +47,10 @@ const getUserInfoFromRequest = async (request: Request): Promise<UserInfo> => {
     return { sub: userId, roleNames: [UserRole.Admin] };
   }
 
-  const { publicKey, issuer } = oidc;
+  const { localJWKSet, issuer } = oidc;
   const {
     payload: { sub, role_names: roleNames },
-  } = await jwtVerify(extractBearerTokenFromHeaders(request.headers), publicKey, {
+  } = await jwtVerify(extractBearerTokenFromHeaders(request.headers), localJWKSet, {
     issuer,
     audience: managementResource.indicator,
   });

packages/core/src/oidc/init.ts

@@ -3,7 +3,6 @@
 import { readFileSync } from 'fs';
 
 import { CustomClientMetadataKey } from '@logto/schemas';
-import { exportJWK } from 'jose';
 import Koa from 'koa';
 import mount from 'koa-mount';
 import { Provider, errors } from 'oidc-provider';
@@ -18,11 +17,10 @@ import { routes } from '@/routes/consts';
 import { addOidcEventListeners } from '@/utils/oidc-provider-event-listener';
 
 export default async function initOidc(app: Koa): Promise<Provider> {
-  const { issuer, cookieKeys, privateKey, defaultIdTokenTtl, defaultRefreshTokenTtl } =
+  const { issuer, cookieKeys, privateJwks, defaultIdTokenTtl, defaultRefreshTokenTtl } =
     envSet.values.oidc;
   const logoutSource = readFileSync('static/html/logout.html', 'utf8');
 
-  const keys = [await exportJWK(privateKey)];
   const cookieConfig = Object.freeze({
     sameSite: 'lax',
     path: '/',
@@ -40,7 +38,7 @@ export default async function initOidc(app: Koa): Promise<Provider> {
       short: cookieConfig,
     },
     jwks: {
-      keys,
+      keys: privateJwks,
     },
     features: {
       userinfo: { enabled: false },

packages/core/src/utils/jwks.ts

@@ -0,0 +1,62 @@
+/**
+ * Theses codes comes from [node-oidc-provider](https://github.com/panva/node-oidc-provider):
+ * - [initialize_keystore.js](https://github.com/panva/node-oidc-provider/blob/9da61e9c9dc6152cd1140d42ea06abe1d812c286/lib/helpers/initialize_keystore.js#L13-L36)
+ * - [base64url.js](https://github.com/panva/node-oidc-provider/blob/9da61e9c9dc6152cd1140d42ea06abe1d812c286/lib/helpers/base64url.js)
+ */
+
+import { createHash } from 'crypto';
+
+import { JWK, KeyLike, exportJWK as joseExportJWK } from 'jose';
+
+const fromBase64 = (base64: string) =>
+  base64.replace(/=/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+
+const encodeBuffer = (buf: Buffer) => {
+  const base64url = buf.toString('base64url');
+
+  if (Buffer.isEncoding('base64url')) {
+    return base64url;
+  }
+
+  return fromBase64(base64url);
+};
+
+const getCalculateKidComponents = (jwk: JWK) => {
+  switch (jwk.kty) {
+    case 'RSA':
+      return {
+        e: jwk.e,
+        kty: 'RSA',
+        n: jwk.n,
+      };
+    case 'EC':
+      return {
+        crv: jwk.crv,
+        kty: 'EC',
+        x: jwk.x,
+        y: jwk.y,
+      };
+    case 'OKP':
+      return {
+        crv: jwk.crv,
+        kty: 'OKP',
+        x: jwk.x,
+      };
+    default:
+  }
+};
+
+const calculateKid = (jwk: JWK) => {
+  const components = getCalculateKidComponents(jwk);
+
+  return encodeBuffer(createHash('sha256').update(JSON.stringify(components)).digest());
+};
+
+export const exportJWK = async (key: KeyLike | Uint8Array): Promise<JWK> => {
+  const jwk = await joseExportJWK(key);
+
+  return {
+    ...jwk,
+    kid: calculateKid(jwk),
+  };
+};