@logto/schemas 1.38.0 → 1.39.0

package/lib/utils/oidc-private-key.js

@@ -0,0 +1,163 @@
+import { OidcSigningKeyStatus } from '../types/index.js';
+const oidcPrivateKeyStatusOrder = {
+    [OidcSigningKeyStatus.Next]: 0,
+    [OidcSigningKeyStatus.Current]: 1,
+    [OidcSigningKeyStatus.Previous]: 2,
+};
+const oidcProviderPrivateKeyOrder = {
+    [OidcSigningKeyStatus.Current]: 0,
+    [OidcSigningKeyStatus.Next]: 1,
+    [OidcSigningKeyStatus.Previous]: 2,
+};
+const sortOidcPrivateKeys = (privateKeys, order) => privateKeys.toSorted((leftKey, rightKey) => order[leftKey.status] - order[rightKey.status]);
+/**
+ * Normalize OIDC private signing keys into an explicit status-based model.
+ *
+ * Legacy keys without `status` are interpreted by index order:
+ * the first key becomes `Current` and the second key becomes `Previous`.
+ * The helper also validates that the key set contains exactly one `Current`
+ * and at most one `Next` and `Previous`.
+ */
+export const normalizeOidcPrivateKeys = (privateKeys) => {
+    const normalizedPrivateKeys = privateKeys.map((privateKey, index) => ({
+        ...privateKey,
+        status: privateKey.status ??
+            (index === 0 ? OidcSigningKeyStatus.Current : OidcSigningKeyStatus.Previous),
+    }));
+    const currentKeys = normalizedPrivateKeys.filter(({ status }) => status === OidcSigningKeyStatus.Current);
+    const nextKeys = normalizedPrivateKeys.filter(({ status }) => status === OidcSigningKeyStatus.Next);
+    const previousKeys = normalizedPrivateKeys.filter(({ status }) => status === OidcSigningKeyStatus.Previous);
+    if (currentKeys.length !== 1 || nextKeys.length > 1 || previousKeys.length > 1) {
+        throw new Error('Malformed OIDC private key status configuration: expected exactly one Current key and at most one Next and Previous key.');
+    }
+    return normalizedPrivateKeys;
+};
+/**
+ * Return private keys in canonical business order: `Next`, then `Current`, then `Previous`.
+ *
+ * This order is useful when the caller wants a stable persisted view of key lifecycle state.
+ */
+export const getCanonicalOidcPrivateKeys = (privateKeys) => sortOidcPrivateKeys(normalizeOidcPrivateKeys(privateKeys), oidcPrivateKeyStatusOrder);
+/**
+ * Return the currently active signing key from a private-key set.
+ *
+ * This helper reads explicit key status rather than relying on array index.
+ */
+export const getCurrentOidcPrivateKey = (privateKeys) => {
+    const currentKey = normalizeOidcPrivateKeys(privateKeys).find(({ status }) => status === OidcSigningKeyStatus.Current);
+    if (!currentKey) {
+        throw new Error('Malformed OIDC private key status configuration: missing Current key.');
+    }
+    return currentKey;
+};
+/**
+ * Return private keys in the order expected by `oidc-provider` for signing and JWKS exposure.
+ *
+ * The active `Current` key comes first, followed by `Next`, then `Previous`.
+ */
+export const getOidcProviderPrivateKeys = (privateKeys) => sortOidcPrivateKeys(normalizeOidcPrivateKeys(privateKeys), oidcProviderPrivateKeyOrder);
+/**
+ * Normalize seeded private keys into the explicit status model used by core and CLI.
+ *
+ * Seeding only supports the legacy one-key or two-key layout, so the helper rejects
+ * larger key arrays instead of trying to infer a more complex state machine.
+ */
+export const getSeededOidcPrivateKeys = (privateKeys) => {
+    if (privateKeys.length > 2) {
+        throw new TypeError('CLI seed supports at most 2 OIDC private keys');
+    }
+    return normalizeOidcPrivateKeys(privateKeys);
+};
+/**
+ * Build the persisted private-key state for immediate rotation.
+ *
+ * The new key becomes `Current`, the previous `Current` key becomes `Previous`,
+ * and any older `Previous` key is dropped.
+ */
+export const getImmediatelyRotatedOidcPrivateKeys = (privateKeys, newPrivateKey) => {
+    const normalizedPrivateKeys = normalizeOidcPrivateKeys(privateKeys);
+    if (normalizedPrivateKeys.some(({ status }) => status === OidcSigningKeyStatus.Next)) {
+        throw new TypeError('Immediate OIDC private key rotation is not allowed when a Next key exists');
+    }
+    const currentKey = getCurrentOidcPrivateKey(normalizedPrivateKeys);
+    return [
+        { ...newPrivateKey, status: OidcSigningKeyStatus.Current },
+        { ...currentKey, status: OidcSigningKeyStatus.Previous },
+    ];
+};
+/**
+ * Build the persisted private-key state for staged rotation.
+ *
+ * The new key becomes `Next`, the existing `Current` key stays `Current`,
+ * and the existing `Previous` key is preserved when present.
+ */
+export const getStagedRotatedOidcPrivateKeys = (privateKeys, newPrivateKey) => {
+    const normalizedPrivateKeys = normalizeOidcPrivateKeys(privateKeys);
+    const currentKey = getCurrentOidcPrivateKey(normalizedPrivateKeys);
+    const previousKey = normalizedPrivateKeys.find(({ status }) => status === OidcSigningKeyStatus.Previous);
+    return [
+        { ...newPrivateKey, status: OidcSigningKeyStatus.Next },
+        { ...currentKey, status: OidcSigningKeyStatus.Current },
+        ...(previousKey ? [{ ...previousKey, status: OidcSigningKeyStatus.Previous }] : []),
+    ];
+};
+/**
+ * Promote a staged `Next` key into `Current` and demote the previous `Current` key into `Previous`.
+ *
+ * If no staged rotation is pending, the helper returns the original key array when it already
+ * uses explicit statuses, or the normalized array when the input is still in legacy form.
+ */
+export const rotateOidcPrivateKeyStatuses = (privateKeys) => {
+    const normalizedPrivateKeys = normalizeOidcPrivateKeys(privateKeys);
+    const nextKey = normalizedPrivateKeys.find(({ status }) => status === OidcSigningKeyStatus.Next);
+    if (!nextKey) {
+        return privateKeys.every(({ status }) => status) ? privateKeys : normalizedPrivateKeys;
+    }
+    const currentKey = getCurrentOidcPrivateKey(normalizedPrivateKeys);
+    return [
+        { ...nextKey, status: OidcSigningKeyStatus.Current },
+        { ...currentKey, status: OidcSigningKeyStatus.Previous },
+    ];
+};
+/**
+ * Remove a single private key from the canonical key set after delete validation has already passed.
+ *
+ * The helper keeps the remaining keys in canonical status order and does not attempt to infer
+ * new lifecycle transitions beyond dropping the deleted key.
+ */
+export const getOidcPrivateKeysAfterDeletion = (privateKeys, deletedKeyId) => getCanonicalOidcPrivateKeys(privateKeys).filter(({ id }) => id !== deletedKeyId);
+/**
+ * Trim one or more `Previous` private keys from the end of the normalized key set.
+ *
+ * Only `Previous` keys are trim-able; attempting to trim past the available `Previous`
+ * keys indicates an invalid operation.
+ */
+export const getTrimmedOidcPrivateKeys = (privateKeys, length) => {
+    const normalizedPrivateKeys = normalizeOidcPrivateKeys(privateKeys);
+    const previousKeys = normalizedPrivateKeys.filter(({ status }) => status === OidcSigningKeyStatus.Previous);
+    if (length > previousKeys.length) {
+        throw new TypeError('Only Previous OIDC private keys can be trimmed');
+    }
+    return getCanonicalOidcPrivateKeys(normalizedPrivateKeys).slice(0, -length);
+};
+/**
+ * Build rotation state for immediate tenant cache invalidation.
+ *
+ * This records when a tenant instance should be considered stale so the next reload
+ * can pick up newly written signing key data.
+ */
+export const getRotationStateForCacheInvalidation = (currentRotationState, now = Date.now()) => ({
+    ...currentRotationState,
+    tenantCacheExpiresAt: now,
+});
+/**
+ * Build rotation state for staged private-key rotation.
+ *
+ * In addition to immediate tenant invalidation, this records the future activation time
+ * when the staged `Next` key should be promoted to `Current`.
+ */
+export const getRotationStateForStagedRotation = (currentRotationState, rotationGracePeriod, now = Date.now()) => ({
+    ...currentRotationState,
+    tenantCacheExpiresAt: now,
+    signingKeyRotationAt: now + rotationGracePeriod * 1000,
+});

package/lib/utils/oidc-private-key.test.d.ts

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

package/lib/utils/oidc-private-key.test.js

@@ -0,0 +1,128 @@
+import { describe, expect, it } from 'vitest';
+import { OidcSigningKeyStatus } from '../types/index.js';
+import { getCanonicalOidcPrivateKeys, getCurrentOidcPrivateKey, getImmediatelyRotatedOidcPrivateKeys, getOidcPrivateKeysAfterDeletion, getOidcProviderPrivateKeys, getRotationStateForCacheInvalidation, getRotationStateForStagedRotation, getSeededOidcPrivateKeys, getStagedRotatedOidcPrivateKeys, getTrimmedOidcPrivateKeys, normalizeOidcPrivateKeys, rotateOidcPrivateKeyStatuses, } from './oidc-private-key.js';
+const createPrivateKey = (id, createdAt, status) => ({
+    id,
+    value: `private-key-${id}`,
+    createdAt,
+    status,
+});
+describe('OIDC private key helpers', () => {
+    it('normalizes legacy private keys without status into Current and Previous', () => {
+        expect(normalizeOidcPrivateKeys([createPrivateKey('current', 1), createPrivateKey('previous', 2)])).toEqual([
+            createPrivateKey('current', 1, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 2, OidcSigningKeyStatus.Previous),
+        ]);
+    });
+    it('throws for malformed status configurations', () => {
+        expect(() => normalizeOidcPrivateKeys([
+            createPrivateKey('current-a', 1, OidcSigningKeyStatus.Current),
+            createPrivateKey('current-b', 2, OidcSigningKeyStatus.Current),
+        ])).toThrow('Malformed OIDC private key status configuration');
+    });
+    it('orders private keys in canonical business order', () => {
+        expect(getCanonicalOidcPrivateKeys([
+            createPrivateKey('previous', 3, OidcSigningKeyStatus.Previous),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('next', 1, OidcSigningKeyStatus.Next),
+        ])).toEqual([
+            createPrivateKey('next', 1, OidcSigningKeyStatus.Next),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 3, OidcSigningKeyStatus.Previous),
+        ]);
+    });
+    it('orders private keys for oidc-provider consumption', () => {
+        expect(getOidcProviderPrivateKeys([
+            createPrivateKey('previous', 3, OidcSigningKeyStatus.Previous),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('next', 1, OidcSigningKeyStatus.Next),
+        ])).toEqual([
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('next', 1, OidcSigningKeyStatus.Next),
+            createPrivateKey('previous', 3, OidcSigningKeyStatus.Previous),
+        ]);
+    });
+    it('finds the current signing key by status', () => {
+        expect(getCurrentOidcPrivateKey([
+            createPrivateKey('previous', 3, OidcSigningKeyStatus.Previous),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('next', 1, OidcSigningKeyStatus.Next),
+        ])).toEqual(createPrivateKey('current', 2, OidcSigningKeyStatus.Current));
+    });
+    it('assigns statuses to seeded keys', () => {
+        expect(getSeededOidcPrivateKeys([createPrivateKey('current', 2), createPrivateKey('previous', 1)])).toEqual([
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 1, OidcSigningKeyStatus.Previous),
+        ]);
+    });
+    it('rejects more than two seeded private keys', () => {
+        expect(() => getSeededOidcPrivateKeys([
+            createPrivateKey('current', 3),
+            createPrivateKey('previous-a', 2),
+            createPrivateKey('previous-b', 1),
+        ])).toThrow('CLI seed supports at most 2 OIDC private keys');
+    });
+    it('immediately rotates the new key into Current', () => {
+        expect(getImmediatelyRotatedOidcPrivateKeys([
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 1, OidcSigningKeyStatus.Previous),
+        ], createPrivateKey('new', 3))).toEqual([
+            createPrivateKey('new', 3, OidcSigningKeyStatus.Current),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Previous),
+        ]);
+    });
+    it('stages the new key as Next while preserving Current and Previous', () => {
+        expect(getStagedRotatedOidcPrivateKeys([
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 1, OidcSigningKeyStatus.Previous),
+        ], createPrivateKey('new', 3))).toEqual([
+            createPrivateKey('new', 3, OidcSigningKeyStatus.Next),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 1, OidcSigningKeyStatus.Previous),
+        ]);
+    });
+    it('promotes Next to Current during activation', () => {
+        expect(rotateOidcPrivateKeyStatuses([
+            createPrivateKey('next', 3, OidcSigningKeyStatus.Next),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 1, OidcSigningKeyStatus.Previous),
+        ])).toEqual([
+            createPrivateKey('next', 3, OidcSigningKeyStatus.Current),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Previous),
+        ]);
+    });
+    it('preserves status order when deleting Previous', () => {
+        expect(getOidcPrivateKeysAfterDeletion([
+            createPrivateKey('next', 3, OidcSigningKeyStatus.Next),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 1, OidcSigningKeyStatus.Previous),
+        ], 'previous')).toEqual([
+            createPrivateKey('next', 3, OidcSigningKeyStatus.Next),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+        ]);
+    });
+    it('only trims Previous keys', () => {
+        expect(getTrimmedOidcPrivateKeys([
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+            createPrivateKey('previous', 1, OidcSigningKeyStatus.Previous),
+        ], 1)).toEqual([createPrivateKey('current', 2, OidcSigningKeyStatus.Current)]);
+    });
+    it('trims the Previous key even when the input order is not canonical', () => {
+        expect(getTrimmedOidcPrivateKeys([
+            createPrivateKey('previous', 1, OidcSigningKeyStatus.Previous),
+            createPrivateKey('current', 2, OidcSigningKeyStatus.Current),
+        ], 1)).toEqual([createPrivateKey('current', 2, OidcSigningKeyStatus.Current)]);
+    });
+    it('creates invalidation-only state', () => {
+        expect(getRotationStateForCacheInvalidation({ signingKeyRotationAt: 456 }, 123)).toEqual({
+            tenantCacheExpiresAt: 123,
+            signingKeyRotationAt: 456,
+        });
+    });
+    it('creates staged rotation state with tenant invalidation and activation timestamps', () => {
+        expect(getRotationStateForStagedRotation({ tenantCacheExpiresAt: 1 }, 60, 123)).toEqual({
+            tenantCacheExpiresAt: 123,
+            signingKeyRotationAt: 60_123,
+        });
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logto/schemas",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "author": "Silverhand Inc. <contact@silverhand.io>",
   "license": "MPL-2.0",
   "type": "module",
@@ -65,12 +65,12 @@
   "dependencies": {
     "@withtyped/server": "^0.14.0",
     "nanoid": "^5.0.9",
-    "@logto/language-kit": "^1.3.0",
-    "@logto/core-kit": "^2.8.0",
-    "@logto/phrases": "^1.27.0",
-    "@logto/shared": "^3.3.1",
+    "@logto/core-kit": "^2.9.0",
     "@logto/connector-kit": "^5.0.0",
-    "@logto/phrases-experience": "^1.13.0"
+    "@logto/phrases": "^1.28.0",
+    "@logto/language-kit": "^1.3.0",
+    "@logto/phrases-experience": "^1.13.1",
+    "@logto/shared": "^3.4.0"
   },
   "peerDependencies": {
     "zod": "3.24.3"

package/tables/account_centers.sql

@@ -7,5 +7,9 @@ create table account_centers (
   /** Control each fields */
   fields jsonb /* @use AccountCenterFieldControl */ not null default '{}'::jsonb,
   webauthn_related_origins jsonb /* @use WebauthnRelatedOrigins */ not null default '[]'::jsonb,
+  /** URL for custom account deletion endpoint */
+  delete_account_url varchar(2048),
+  /** User-defined custom CSS for the account center */
+  custom_css text,
   primary key (tenant_id, id)
 );

package/tables/sign_in_experiences.sql

@@ -33,5 +33,7 @@ create table sign_in_experiences (
   email_blocklist_policy jsonb /* @use EmailBlocklistPolicy */ not null default '{}'::jsonb,
   forgot_password_methods jsonb /* @use ForgotPasswordMethods */ default '[]'::jsonb,
   passkey_sign_in jsonb /* @use PasskeySignIn */ not null default '{}'::jsonb,
+  /** Nullable by design: null keeps legacy full-catalog behavior and [] collects no custom profile fields. */
+  sign_up_profile_fields jsonb /* @use SignUpProfileFields */,
   primary key (tenant_id, id)
 );