@logto/cli 1.38.0 → 1.39.0

package/lib/commands/database/alteration/index.js

@@ -27,6 +27,12 @@ export const getAvailableAlterations = async (pool, compareMode = 'gt') => {
         ? getTimestampFromFilename(filename) > databaseTimestamp
         : getTimestampFromFilename(filename) <= databaseTimestamp);
 };
+/**
+ * IMPORTANT: Logto Cloud has a parallel implementation of this logic in `CoreAlterationClient`
+ * (logto-cloud repo: `packages/azure-functions/src/utils/core-alteration-client.ts`).
+ * Any changes to the alteration execution behavior here (e.g., new hooks, execution order)
+ * must be synchronized with the Cloud implementation.
+ */
 const deployAlteration = async (pool, { path: filePath, filename }, action = 'up') => {
     const { up, down, beforeUp, beforeDown } = await importAlterationScript(filePath);
     const timestamp = getTimestampFromFilename(filename);

package/lib/commands/database/config-rotation.d.ts

@@ -0,0 +1,25 @@
+import { LogtoOidcConfigKey, type SupportedSigningKeyAlgorithm, type OidcConfigKey, type OidcPrivateKey } from '@logto/schemas';
+import type { CommonQueryMethods } from '@silverhand/slonik';
+type RotateConfigResult = {
+    keys: OidcPrivateKey[] | OidcConfigKey[];
+};
+export declare const parseRotationGracePeriod: (value?: string) => number | undefined;
+export declare const getEffectiveRotationGracePeriod: ({ key, gracePeriod, envGracePeriod, }: {
+    key: LogtoOidcConfigKey.PrivateKeys | LogtoOidcConfigKey.CookieKeys;
+    gracePeriod?: number;
+    envGracePeriod?: string;
+}) => number;
+export declare const rotateConfigKey: ({ connection, tenantId, key, privateKeyType, gracePeriod, }: {
+    connection: CommonQueryMethods;
+    tenantId: string;
+    key: LogtoOidcConfigKey.PrivateKeys | LogtoOidcConfigKey.CookieKeys;
+    privateKeyType: SupportedSigningKeyAlgorithm;
+    gracePeriod: number;
+}) => Promise<RotateConfigResult>;
+export declare const trimConfigKey: ({ connection, tenantId, key, length, }: {
+    connection: CommonQueryMethods;
+    tenantId: string;
+    key: LogtoOidcConfigKey.PrivateKeys | LogtoOidcConfigKey.CookieKeys;
+    length: number;
+}) => Promise<RotateConfigResult>;
+export {};

package/lib/commands/database/config-rotation.js

@@ -0,0 +1,111 @@
+import { getSeededOidcPrivateKeys, getImmediatelyRotatedOidcPrivateKeys, getRotationStateForCacheInvalidation, getRotationStateForStagedRotation, getStagedRotatedOidcPrivateKeys, getTrimmedOidcPrivateKeys, LogtoOidcConfigKey, LogtoTenantConfigKey, normalizeOidcPrivateKeys, logtoConfigGuards, } from '@logto/schemas';
+import { getRowsByKeys, updateValueByKey } from '../../queries/logto-config.js';
+import { consoleLog } from '../../utils.js';
+import { generateOidcCookieKey, generateOidcPrivateKey } from './utils.js';
+export const parseRotationGracePeriod = (value) => {
+    if (value === undefined || value.trim() === '') {
+        return;
+    }
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new TypeError('Invalid PRIVATE_KEY_ROTATION_GRACE_PERIOD env value');
+    }
+    return parsed;
+};
+export const getEffectiveRotationGracePeriod = ({ key, gracePeriod, envGracePeriod, }) => {
+    if (key === LogtoOidcConfigKey.CookieKeys) {
+        if (gracePeriod !== undefined) {
+            throw new TypeError(`${LogtoOidcConfigKey.CookieKeys} does not support grace period`);
+        }
+        return 0;
+    }
+    if (gracePeriod !== undefined) {
+        if (!Number.isInteger(gracePeriod) || gracePeriod < 0) {
+            throw new TypeError('Invalid grace period provided');
+        }
+        return gracePeriod;
+    }
+    return parseRotationGracePeriod(envGracePeriod) ?? 0;
+};
+const getRotationStateRow = (rows) => {
+    const row = rows.find(({ key }) => key === LogtoTenantConfigKey.SigningKeyRotationState);
+    if (!row) {
+        return undefined;
+    }
+    const parsed = logtoConfigGuards[LogtoTenantConfigKey.SigningKeyRotationState].safeParse(row.value);
+    return parsed.success ? parsed.data : undefined;
+};
+export const rotateConfigKey = async ({ connection, tenantId, key, privateKeyType, gracePeriod, }) => {
+    const { rows } = await getRowsByKeys(connection, tenantId, [
+        key,
+        LogtoTenantConfigKey.SigningKeyRotationState,
+    ]);
+    const configRow = rows.find((row) => row.key === key);
+    const currentRotationState = getRotationStateRow(rows);
+    if (!configRow) {
+        consoleLog.warn('No key found, create a new one');
+    }
+    switch (key) {
+        case LogtoOidcConfigKey.PrivateKeys: {
+            const parsed = logtoConfigGuards[key].safeParse(configRow?.value);
+            const original = parsed.success ? parsed.data : [];
+            const hasExistingPrivateKeys = original.length > 0;
+            const newPrivateKey = await generateOidcPrivateKey(privateKeyType);
+            const rotatedPrivateKeys = hasExistingPrivateKeys
+                ? gracePeriod === 0
+                    ? getImmediatelyRotatedOidcPrivateKeys(original, newPrivateKey)
+                    : getStagedRotatedOidcPrivateKeys(original, newPrivateKey)
+                : getSeededOidcPrivateKeys([newPrivateKey]);
+            const rotationState = !hasExistingPrivateKeys || gracePeriod === 0
+                ? getRotationStateForCacheInvalidation(currentRotationState)
+                : getRotationStateForStagedRotation(currentRotationState, gracePeriod);
+            await updateValueByKey(connection, tenantId, key, rotatedPrivateKeys);
+            await updateValueByKey(connection, tenantId, LogtoTenantConfigKey.SigningKeyRotationState, rotationState);
+            return { keys: rotatedPrivateKeys };
+        }
+        case LogtoOidcConfigKey.CookieKeys: {
+            const parsed = logtoConfigGuards[key].safeParse(configRow?.value);
+            const original = parsed.success ? parsed.data : [];
+            const rotatedCookieKeys = [generateOidcCookieKey(), ...original];
+            const rotationState = getRotationStateForCacheInvalidation(currentRotationState);
+            await updateValueByKey(connection, tenantId, key, rotatedCookieKeys);
+            await updateValueByKey(connection, tenantId, LogtoTenantConfigKey.SigningKeyRotationState, rotationState);
+            return { keys: rotatedCookieKeys };
+        }
+    }
+};
+export const trimConfigKey = async ({ connection, tenantId, key, length, }) => {
+    const { rows } = await getRowsByKeys(connection, tenantId, [
+        key,
+        LogtoTenantConfigKey.SigningKeyRotationState,
+    ]);
+    const configRow = rows.find((row) => row.key === key);
+    const currentRotationState = getRotationStateRow(rows);
+    if (!configRow) {
+        consoleLog.fatal('No key found');
+    }
+    switch (key) {
+        case LogtoOidcConfigKey.PrivateKeys: {
+            const value = normalizeOidcPrivateKeys(logtoConfigGuards[key].parse(configRow.value));
+            const trimmedPrivateKeys = getTrimmedOidcPrivateKeys(value, length);
+            const rotationState = getRotationStateForCacheInvalidation(currentRotationState);
+            if (trimmedPrivateKeys.length === 0) {
+                consoleLog.fatal(`You should keep at least one key in the array, current length=${value.length}`);
+            }
+            await updateValueByKey(connection, tenantId, key, trimmedPrivateKeys);
+            await updateValueByKey(connection, tenantId, LogtoTenantConfigKey.SigningKeyRotationState, rotationState);
+            return { keys: trimmedPrivateKeys };
+        }
+        case LogtoOidcConfigKey.CookieKeys: {
+            const value = logtoConfigGuards[key].parse(configRow.value);
+            const rotationState = getRotationStateForCacheInvalidation(currentRotationState);
+            if (value.length - length < 1) {
+                consoleLog.fatal(`You should keep at least one key in the array, current length=${value.length}`);
+            }
+            const trimmedCookieKeys = value.slice(0, -length);
+            await updateValueByKey(connection, tenantId, key, trimmedCookieKeys);
+            await updateValueByKey(connection, tenantId, LogtoTenantConfigKey.SigningKeyRotationState, rotationState);
+            return { keys: trimmedCookieKeys };
+        }
+    }
+};

package/lib/commands/database/config-rotation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/commands/database/config-rotation.test.js

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+const { getEffectiveRotationGracePeriod, parseRotationGracePeriod } = await import('./config-rotation.js');
+const { LogtoOidcConfigKey } = await import('@logto/schemas');
+describe('parseRotationGracePeriod()', () => {
+    it('returns undefined when env is not set', () => {
+        expect(parseRotationGracePeriod()).toBeUndefined();
+        expect(parseRotationGracePeriod('   ')).toBeUndefined();
+    });
+    it('parses a valid non-negative integer', () => {
+        expect(parseRotationGracePeriod('14400')).toBe(14_400);
+    });
+    it('throws on malformed input instead of silently falling back to 0', () => {
+        expect(() => parseRotationGracePeriod('4h')).toThrow('Invalid PRIVATE_KEY_ROTATION_GRACE_PERIOD env value');
+        expect(() => parseRotationGracePeriod('-1')).toThrow('Invalid PRIVATE_KEY_ROTATION_GRACE_PERIOD env value');
+    });
+});
+describe('getEffectiveRotationGracePeriod()', () => {
+    it('uses the explicit private-key grace period when provided', () => {
+        expect(getEffectiveRotationGracePeriod({
+            key: LogtoOidcConfigKey.PrivateKeys,
+            gracePeriod: 60,
+        })).toBe(60);
+    });
+    it('uses the env default for private keys when no explicit grace period is provided', () => {
+        expect(getEffectiveRotationGracePeriod({
+            key: LogtoOidcConfigKey.PrivateKeys,
+            envGracePeriod: '120',
+        })).toBe(120);
+    });
+    it('rejects cookie-key grace period even when the explicit value is 0', () => {
+        expect(() => getEffectiveRotationGracePeriod({
+            key: LogtoOidcConfigKey.CookieKeys,
+            gracePeriod: 0,
+        })).toThrow(`${LogtoOidcConfigKey.CookieKeys} does not support grace period`);
+    });
+});

package/lib/commands/database/config.js

@@ -4,7 +4,7 @@ import chalk from 'chalk';
 import { createPoolFromConfig } from '../../database.js';
 import { getRowsByKeys, updateValueByKey } from '../../queries/logto-config.js';
 import { consoleLog } from '../../utils.js';
-import { generateOidcCookieKey, generateOidcPrivateKey } from './utils.js';
+import { getEffectiveRotationGracePeriod, rotateConfigKey, trimConfigKey, } from './config-rotation.js';
 const validKeysDisplay = chalk.green(logtoConfigKeys.join(', '));
 const validateKeys = (keys) => {
     const invalidKey = (Array.isArray(keys) ? keys : [keys]).find(
@@ -37,6 +37,10 @@ const validatePrivateKeyType = (key) => {
         consoleLog.fatal(`Invalid private key type ${chalk.red(key)} found, expected one of ${validPrivateKeyTypes.join(', ')}`);
     }
 };
+const getValidatedPrivateKeyType = (key) => {
+    validatePrivateKeyType(key);
+    return key;
+};
 const getConfig = {
     command: 'get <key> [keys...]',
     describe: 'Get config value(s) of the given key(s) in Logto database',
@@ -103,7 +107,7 @@ const setConfig = {
 };
 const rotateConfig = {
     command: 'rotate <key>',
-    describe: 'Generate a new private or secret key for the given config key and prepend to the key array',
+    describe: 'Generate a new private or secret key for the given config key and update the key state',
     builder: (yargs) => yargs
         .positional('key', {
         describe: `The key to rotate, one of ${chalk.green(validRotateKeys.join(', '))}`,
@@ -119,31 +123,37 @@ const rotateConfig = {
         describe: `The key type for ${LogtoOidcConfigKey.PrivateKeys}, one of ${validPrivateKeyTypes.join(', ')}`,
         type: 'string',
         default: 'ec',
+    })
+        .option('gracePeriod', {
+        describe: `Grace period in seconds for ${LogtoOidcConfigKey.PrivateKeys} staged rotation`,
+        type: 'number',
     }),
-    handler: async ({ key, tenantId, type }) => {
+    handler: async ({ key, tenantId, type, gracePeriod }) => {
         const keyType = type.toUpperCase();
+        const privateKeyType = key === LogtoOidcConfigKey.PrivateKeys
+            ? getValidatedPrivateKeyType(keyType)
+            : SupportedSigningKeyAlgorithm.EC;
         validateRotateKey(key);
-        validatePrivateKeyType(keyType);
-        const pool = await createPoolFromConfig();
-        const { rows } = await getRowsByKeys(pool, tenantId, [key]);
-        if (!rows[0]) {
-            consoleLog.warn('No key found, create a new one');
-        }
-        const getValue = async () => {
-            const parsed = logtoConfigGuards[key].safeParse(rows[0]?.value);
-            const original = parsed.success ? parsed.data : [];
-            // No need for default. It's already exhaustive
-            switch (key) {
-                case LogtoOidcConfigKey.PrivateKeys: {
-                    return [await generateOidcPrivateKey(keyType), ...original];
-                }
-                case LogtoOidcConfigKey.CookieKeys: {
-                    return [generateOidcCookieKey(), ...original];
-                }
+        const effectiveGracePeriod = (() => {
+            try {
+                return getEffectiveRotationGracePeriod({
+                    key,
+                    gracePeriod,
+                    envGracePeriod: process.env.PRIVATE_KEY_ROTATION_GRACE_PERIOD,
+                });
             }
-        };
-        const rotated = await getValue();
-        await updateValueByKey(pool, tenantId, key, rotated);
+            catch (error) {
+                return consoleLog.fatal(error instanceof Error ? error.message : 'Invalid grace period provided');
+            }
+        })();
+        const pool = await createPoolFromConfig();
+        const { keys: rotated } = await pool.transaction(async (connection) => rotateConfigKey({
+            connection,
+            tenantId,
+            key,
+            privateKeyType,
+            gracePeriod: effectiveGracePeriod,
+        }));
         await pool.end();
         consoleLog.info(`Rotate ${chalk.green(key)} succeeded, now it has ${rotated.length} keys`);
     },
@@ -174,20 +184,12 @@ const trimConfig = {
             consoleLog.fatal('Invalid length provided');
         }
         const pool = await createPoolFromConfig();
-        const { rows } = await getRowsByKeys(pool, tenantId, [key]);
-        if (!rows[0]) {
-            consoleLog.warn('No key found, create a new one');
-        }
-        const getValue = async () => {
-            const value = logtoConfigGuards[key].parse(rows[0]?.value);
-            if (value.length - length < 1) {
-                await pool.end();
-                consoleLog.fatal(`You should keep at least one key in the array, current length=${value.length}`);
-            }
-            return value.slice(0, -length);
-        };
-        const trimmed = await getValue();
-        await updateValueByKey(pool, tenantId, key, trimmed);
+        const { keys: trimmed } = await pool.transaction(async (connection) => trimConfigKey({
+            connection,
+            tenantId,
+            key,
+            length,
+        }));
         await pool.end();
         consoleLog.info(`Trim ${chalk.green(key)} succeeded, now it has ${trimmed.length} keys`);
     },

package/lib/commands/database/seed/oidc-config.js

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises';
-import { LogtoOidcConfigKey, logtoConfigGuards } from '@logto/schemas';
+import { LogtoOidcConfigKey, getSeededOidcPrivateKeys, logtoConfigGuards } from '@logto/schemas';
 import { generateStandardId } from '@logto/shared';
 import { getEnvAsStringArray } from '@silverhand/essentials';
 import chalk from 'chalk';
@@ -69,7 +69,7 @@ export const oidcConfigReaders = {
         const privateKeys = getEnvAsStringArray('OIDC_PRIVATE_KEYS');
         if (privateKeys.length > 0) {
             return {
-                value: privateKeys.map((key) => buildOidcKeyFromRawString(isBase64FormatPrivateKey(key) ? Buffer.from(key, 'base64').toString('utf8') : key)),
+                value: getSeededOidcPrivateKeys(privateKeys.map((key) => buildOidcKeyFromRawString(isBase64FormatPrivateKey(key) ? Buffer.from(key, 'base64').toString('utf8') : key))),
                 fromEnv: true,
             };
         }
@@ -78,12 +78,12 @@ export const oidcConfigReaders = {
         if (privateKeyPaths.length > 0) {
             const privateKeys = await Promise.all(privateKeyPaths.map(async (path) => readFile(path, 'utf8')));
             return {
-                value: privateKeys.map((key) => buildOidcKeyFromRawString(key)),
+                value: getSeededOidcPrivateKeys(privateKeys.map((key) => buildOidcKeyFromRawString(key))),
                 fromEnv: true,
             };
         }
         return {
-            value: [await generateOidcPrivateKey()],
+            value: getSeededOidcPrivateKeys([await generateOidcPrivateKey()]),
             fromEnv: false,
         };
     },

package/lib/package-json.js

@@ -1,6 +1,6 @@
 export const packageJson = {
     "name": "@logto/cli",
-    "version": "1.38.0",
+    "version": "1.39.0",
     "description": "Logto CLI.",
     "author": "Silverhand Inc. <contact@silverhand.io>",
     "homepage": "https://github.com/logto-io/logto#readme",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/cli",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "description": "Logto CLI.",
   "author": "Silverhand Inc. <contact@silverhand.io>",
   "homepage": "https://github.com/logto-io/logto#readme",
@@ -46,9 +46,9 @@
     "yargs": "^17.6.0",
     "zod": "3.24.3",
     "@logto/connector-kit": "^5.0.0",
-    "@logto/core-kit": "^2.8.0",
-    "@logto/schemas": "1.38.0",
-    "@logto/shared": "^3.3.1"
+    "@logto/core-kit": "^2.9.0",
+    "@logto/schemas": "1.39.0",
+    "@logto/shared": "^3.4.0"
   },
   "devDependencies": {
     "@silverhand/eslint-config": "6.0.1",