@logto/cli 1.37.1 → 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.d.ts

@@ -1,6 +1,7 @@
 import type { LogtoOidcConfigType } from '@logto/schemas';
 import { LogtoOidcConfigKey } from '@logto/schemas';
 import type { DatabaseTransactionConnection } from '@silverhand/slonik';
+type OidcConfigKeyToSeed = Exclude<LogtoOidcConfigKey, LogtoOidcConfigKey.Session>;
 export declare const seedOidcConfigs: (pool: DatabaseTransactionConnection, tenantId: string) => Promise<void>;
 /**
  * Each config reader will do the following things in order:
@@ -8,8 +9,9 @@ export declare const seedOidcConfigs: (pool: DatabaseTransactionConnection, tena
  * 2. Generate value if #1 doesn't work
  */
 export declare const oidcConfigReaders: {
-    [key in LogtoOidcConfigKey]: () => Promise<{
+    [key in OidcConfigKeyToSeed]: () => Promise<{
         value: LogtoOidcConfigType[key];
         fromEnv: boolean;
     }>;
 };
+export {};

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';
@@ -8,13 +8,14 @@ import { getRowsByKeys, updateValueByKey } from '../../../queries/logto-config.j
 import { consoleLog } from '../../../utils.js';
 import { buildOidcKeyFromRawString, generateOidcCookieKey, generateOidcPrivateKey, } from '../utils.js';
 const isBase64FormatPrivateKey = (key) => !key.includes('-');
+const oidcConfigKeysToSeed = Object.values(LogtoOidcConfigKey).filter((key) => key !== LogtoOidcConfigKey.Session);
 export const seedOidcConfigs = async (pool, tenantId) => {
     const tenantPrefix = `[${tenantId}]`;
     const configGuard = z.object({
         key: z.nativeEnum(LogtoOidcConfigKey),
         value: z.unknown(),
     });
-    const { rows } = await getRowsByKeys(pool, tenantId, Object.values(LogtoOidcConfigKey));
+    const { rows } = await getRowsByKeys(pool, tenantId, oidcConfigKeysToSeed);
     // Filter out valid keys that hold a valid value
     const result = await Promise.all(rows.map(async (row) => {
         try {
@@ -25,7 +26,7 @@ export const seedOidcConfigs = async (pool, tenantId) => {
         catch { }
     }));
     const existingKeys = new Set(result.filter(Boolean));
-    const validOptions = Object.values(LogtoOidcConfigKey).filter((key) => {
+    const validOptions = oidcConfigKeysToSeed.filter((key) => {
         const included = existingKeys.has(key);
         if (included) {
             consoleLog.info(tenantPrefix, `Key ${chalk.green(key)} exists, skipping`);
@@ -68,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,
             };
         }
@@ -77,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.d.ts

@@ -29,6 +29,7 @@ export declare const packageJson: {
         lint: string;
         "lint:report": string;
         test: string;
+        "test:watch": string;
         "test:ci": string;
         prepack: string;
     };

package/lib/package-json.js

@@ -1,6 +1,6 @@
 export const packageJson = {
     "name": "@logto/cli",
-    "version": "1.37.1",
+    "version": "1.39.0",
     "description": "Logto CLI.",
     "author": "Silverhand Inc. <contact@silverhand.io>",
     "homepage": "https://github.com/logto-io/logto#readme",
@@ -31,7 +31,8 @@ export const packageJson = {
         "start:dev": "pnpm build && node .",
         "lint": "eslint --ext .ts src",
         "lint:report": "pnpm lint --format json --output-file report.json",
-        "test": "vitest src",
+        "test": "vitest run src",
+        "test:watch": "vitest src --watch",
         "test:ci": "pnpm run test --silent --coverage",
         "prepack": "pnpm build"
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/cli",
-  "version": "1.37.1",
+  "version": "1.39.0",
   "description": "Logto CLI.",
   "author": "Silverhand Inc. <contact@silverhand.io>",
   "homepage": "https://github.com/logto-io/logto#readme",
@@ -45,10 +45,10 @@
     "tar": "^7.5.7",
     "yargs": "^17.6.0",
     "zod": "3.24.3",
-    "@logto/core-kit": "^2.7.1",
-    "@logto/schemas": "1.37.1",
-    "@logto/shared": "^3.3.1",
-    "@logto/connector-kit": "^4.7.0"
+    "@logto/connector-kit": "^5.0.0",
+    "@logto/core-kit": "^2.9.0",
+    "@logto/schemas": "1.39.0",
+    "@logto/shared": "^3.4.0"
   },
   "devDependencies": {
     "@silverhand/eslint-config": "6.0.1",
@@ -88,7 +88,8 @@
     "start:dev": "pnpm build && node .",
     "lint": "eslint --ext .ts src",
     "lint:report": "pnpm lint --format json --output-file report.json",
-    "test": "vitest src",
+    "test": "vitest run src",
+    "test:watch": "vitest src --watch",
     "test:ci": "pnpm run test --silent --coverage"
   }
 }