@logto/schemas 1.38.0 → 1.39.0

package/lib/types/logto-config/index.js

@@ -33,11 +33,20 @@ export const oidcConfigKeyGuard = z.object({
     value: z.string(),
     createdAt: z.number(),
 });
+export var OidcSigningKeyStatus;
+(function (OidcSigningKeyStatus) {
+    OidcSigningKeyStatus["Next"] = "Next";
+    OidcSigningKeyStatus["Current"] = "Current";
+    OidcSigningKeyStatus["Previous"] = "Previous";
+})(OidcSigningKeyStatus || (OidcSigningKeyStatus = {}));
+export const oidcPrivateKeyGuard = oidcConfigKeyGuard.extend({
+    status: z.nativeEnum(OidcSigningKeyStatus).optional(),
+});
 export const oidcSessionConfigGuard = z.object({
     ttl: z.number().int().min(1).max(31_536_000).optional(),
 });
 export const logtoOidcConfigGuard = Object.freeze({
-    [LogtoOidcConfigKey.PrivateKeys]: oidcConfigKeyGuard.array(),
+    [LogtoOidcConfigKey.PrivateKeys]: oidcPrivateKeyGuard.array(),
     [LogtoOidcConfigKey.CookieKeys]: oidcConfigKeyGuard.array(),
     // Session config is optional, if not set, it will fallback to default value in core.
     [LogtoOidcConfigKey.Session]: oidcSessionConfigGuard.nullish().transform((data) => data ?? {}),
@@ -96,6 +105,10 @@ export const extendedIdTokenClaimsGuard = z.enum(extendedIdTokenClaims);
 export const idTokenConfigGuard = z.object({
     enabledExtendedClaims: extendedIdTokenClaimsGuard.array().optional(),
 });
+export const signingKeyRotationStateGuard = z.object({
+    tenantCacheExpiresAt: z.number().optional(),
+    signingKeyRotationAt: z.number().optional(),
+});
 export var LogtoTenantConfigKey;
 (function (LogtoTenantConfigKey) {
     LogtoTenantConfigKey["AdminConsole"] = "adminConsole";
@@ -104,12 +117,15 @@ export var LogtoTenantConfigKey;
     LogtoTenantConfigKey["SessionNotFoundRedirectUrl"] = "sessionNotFoundRedirectUrl";
     /** ID token configuration for extended claims. */
     LogtoTenantConfigKey["IdToken"] = "idToken";
+    /** Tenant-scoped rotation state for staged private signing key activation. */
+    LogtoTenantConfigKey["SigningKeyRotationState"] = "signingKeyRotationState";
 })(LogtoTenantConfigKey || (LogtoTenantConfigKey = {}));
 export const logtoTenantConfigGuard = Object.freeze({
     [LogtoTenantConfigKey.AdminConsole]: adminConsoleDataGuard,
     [LogtoTenantConfigKey.CloudConnection]: cloudConnectionDataGuard,
     [LogtoTenantConfigKey.SessionNotFoundRedirectUrl]: z.object({ url: z.string() }),
     [LogtoTenantConfigKey.IdToken]: idTokenConfigGuard,
+    [LogtoTenantConfigKey.SigningKeyRotationState]: signingKeyRotationStateGuard,
 });
 export const logtoConfigKeys = Object.freeze([
     ...Object.values(LogtoOidcConfigKey),
@@ -121,6 +137,8 @@ export const logtoConfigGuards = Object.freeze({
     ...jwtCustomizerConfigGuard,
     ...logtoTenantConfigGuard,
 });
-export const oidcConfigKeysResponseGuard = oidcConfigKeyGuard
-    .omit({ value: true })
-    .merge(z.object({ signingKeyAlgorithm: z.nativeEnum(SupportedSigningKeyAlgorithm).optional() }));
+export const oidcConfigKeysResponseGuard = oidcConfigKeyGuard.omit({ value: true }).merge(z.object({
+    signingKeyAlgorithm: z.nativeEnum(SupportedSigningKeyAlgorithm).optional(),
+    status: z.nativeEnum(OidcSigningKeyStatus).optional(),
+    effectiveAt: z.number().optional(),
+}));

package/lib/types/logto-config/index.test.d.ts

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

package/lib/types/logto-config/index.test.js

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+import { LogtoOidcConfigKey, LogtoTenantConfigKey, OidcSigningKeyStatus, logtoOidcConfigGuard, logtoTenantConfigGuard, oidcConfigKeysResponseGuard, } from './index.js';
+describe('logto config guards', () => {
+    it('accepts legacy private keys without status', () => {
+        const privateKeys = [
+            {
+                id: 'key_1',
+                value: 'private-key-1',
+                createdAt: 1_710_000_000_000,
+            },
+        ];
+        const result = logtoOidcConfigGuard[LogtoOidcConfigKey.PrivateKeys].safeParse(privateKeys);
+        expect(result.success).toBe(true);
+    });
+    it('accepts signing key status in OIDC key responses', () => {
+        const result = oidcConfigKeysResponseGuard.safeParse({
+            id: 'key_1',
+            createdAt: 1_710_000_000_000,
+            status: OidcSigningKeyStatus.Current,
+        });
+        expect(result.success).toBe(true);
+    });
+    it('accepts partial signing key rotation state', () => {
+        const result = logtoTenantConfigGuard[LogtoTenantConfigKey.SigningKeyRotationState].safeParse({
+            signingKeyRotationAt: 1_710_000_000_000,
+        });
+        expect(result.success).toBe(true);
+    });
+});

package/lib/types/logto-config/jwt-customizer.d.ts

@@ -10,14 +10,17 @@ export declare const jwtCustomizerGuard: z.ZodObject<{
     script: z.ZodString;
     environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     contextSample: z.ZodOptional<z.ZodRecord<z.ZodString, ZodType<import("@withtyped/server/lib/types.js").Json, z.ZodTypeDef, import("@withtyped/server/lib/types.js").Json>>>;
+    blockIssuanceOnError: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     script: string;
     environmentVariables?: Record<string, string> | undefined;
     contextSample?: Record<string, import("@withtyped/server/lib/types.js").Json> | undefined;
+    blockIssuanceOnError?: boolean | undefined;
 }, {
     script: string;
     environmentVariables?: Record<string, string> | undefined;
     contextSample?: Record<string, import("@withtyped/server/lib/types.js").Json> | undefined;
+    blockIssuanceOnError?: boolean | undefined;
 }>;
 export declare enum LogtoJwtTokenKeyType {
     AccessToken = "access-token",
@@ -1268,6 +1271,7 @@ export declare const jwtCustomizerApplicationContextGuard: z.ZodObject<Omit<{
 export declare const accessTokenJwtCustomizerGuard: z.ZodObject<{
     script: z.ZodString;
     environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    blockIssuanceOnError: z.ZodOptional<z.ZodBoolean>;
 } & {
     tokenSample: z.ZodOptional<z.ZodObject<{
         accountId: z.ZodOptional<z.ZodString>;
@@ -3320,6 +3324,7 @@ export declare const accessTokenJwtCustomizerGuard: z.ZodObject<{
             signInContext?: Record<string, string> | undefined;
         } | undefined;
     } | undefined;
+    blockIssuanceOnError?: boolean | undefined;
     tokenSample?: {
         grantId?: string | undefined;
         sid?: string | undefined;
@@ -3577,6 +3582,7 @@ export declare const accessTokenJwtCustomizerGuard: z.ZodObject<{
             signInContext?: Record<string, string> | undefined;
         } | undefined;
     } | undefined;
+    blockIssuanceOnError?: boolean | undefined;
     tokenSample?: {
         grantId?: string | undefined;
         sid?: string | undefined;
@@ -3595,6 +3601,7 @@ export type AccessTokenJwtCustomizer = z.infer<typeof accessTokenJwtCustomizerGu
 export declare const clientCredentialsJwtCustomizerGuard: z.ZodObject<{
     script: z.ZodString;
     environmentVariables: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    blockIssuanceOnError: z.ZodOptional<z.ZodBoolean>;
 } & {
     tokenSample: z.ZodOptional<z.ZodObject<{
         kind: z.ZodOptional<z.ZodLiteral<"ClientCredentials">>;
@@ -3973,6 +3980,7 @@ export declare const clientCredentialsJwtCustomizerGuard: z.ZodObject<{
             isThirdParty?: boolean | undefined;
         } | undefined;
     } | undefined;
+    blockIssuanceOnError?: boolean | undefined;
     tokenSample?: {
         jti?: string | undefined;
         kind?: "ClientCredentials" | undefined;
@@ -4037,6 +4045,7 @@ export declare const clientCredentialsJwtCustomizerGuard: z.ZodObject<{
             isThirdParty?: boolean | undefined;
         } | undefined;
     } | undefined;
+    blockIssuanceOnError?: boolean | undefined;
     tokenSample?: {
         jti?: string | undefined;
         kind?: "ClientCredentials" | undefined;

package/lib/types/logto-config/jwt-customizer.js

@@ -20,6 +20,7 @@ export const jwtCustomizerGuard = z.object({
     script: z.string(),
     environmentVariables: z.record(z.string()).optional(),
     contextSample: jsonObjectGuard.optional(),
+    blockIssuanceOnError: z.boolean().optional(),
 });
 export var LogtoJwtTokenKeyType;
 (function (LogtoJwtTokenKeyType) {

package/lib/types/logto-config/jwt-customizer.test.js

@@ -1,9 +1,20 @@
 import { pick } from '@silverhand/essentials';
 import { describe, expect, it } from 'vitest';
 import { accessTokenJwtCustomizerGuard, clientCredentialsJwtCustomizerGuard, } from './jwt-customizer.js';
-const allFields = ['script', 'environmentVariables', 'contextSample', 'tokenSample'];
+const allFields = [
+    'script',
+    'environmentVariables',
+    'contextSample',
+    'tokenSample',
+    'blockIssuanceOnError',
+];
 const requiredFields = ['script'];
-const optionalFields = ['environmentVariables', 'contextSample', 'tokenSample'];
+const optionalFields = [
+    'environmentVariables',
+    'contextSample',
+    'tokenSample',
+    'blockIssuanceOnError',
+];
 const testClientCredentialsTokenPayload = {
     script: '',
     environmentVariables: {},
@@ -14,6 +25,7 @@ const testClientCredentialsTokenPayload = {
         },
     },
     tokenSample: {},
+    blockIssuanceOnError: false,
 };
 const testAccessTokenPayload = {
     ...testClientCredentialsTokenPayload,

package/lib/types/onboarding.d.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export declare const userOnboardingDataKey = "onboarding";
+export declare const ossUserOnboardingDataKey = "ossOnboarding";
 export declare enum Project {
     Personal = "personal",
     Company = "company"
@@ -18,7 +19,6 @@ export declare enum Title {
     Product = "product",
     Others = "others"
 }
-/** @deprecated */
 export declare enum CompanySize {
     Scale1 = "1",
     Scale2 = "2-49",
@@ -81,6 +81,52 @@ declare const questionnaireGuard: z.ZodObject<{
     additionalFeatures?: AdditionalFeatures[] | undefined;
 }>;
 export type Questionnaire = z.infer<typeof questionnaireGuard>;
+declare const ossQuestionnaireGuard: z.ZodObject<{
+    emailAddress: z.ZodOptional<z.ZodString>;
+    newsletter: z.ZodOptional<z.ZodBoolean>;
+    project: z.ZodOptional<z.ZodNativeEnum<typeof Project>>;
+    projectName: z.ZodOptional<z.ZodString>;
+    companyName: z.ZodOptional<z.ZodString>;
+    companySize: z.ZodOptional<z.ZodNativeEnum<typeof CompanySize>>;
+}, "strip", z.ZodTypeAny, {
+    project?: Project | undefined;
+    companyName?: string | undefined;
+    companySize?: CompanySize | undefined;
+    emailAddress?: string | undefined;
+    newsletter?: boolean | undefined;
+    projectName?: string | undefined;
+}, {
+    project?: Project | undefined;
+    companyName?: string | undefined;
+    companySize?: CompanySize | undefined;
+    emailAddress?: string | undefined;
+    newsletter?: boolean | undefined;
+    projectName?: string | undefined;
+}>;
+export type OssQuestionnaire = z.infer<typeof ossQuestionnaireGuard>;
+export declare const ossSurveyReportPayloadGuard: z.ZodObject<{
+    emailAddress: z.ZodString;
+    newsletter: z.ZodOptional<z.ZodBoolean>;
+    project: z.ZodNativeEnum<typeof Project>;
+    projectName: z.ZodOptional<z.ZodString>;
+    companyName: z.ZodOptional<z.ZodString>;
+    companySize: z.ZodOptional<z.ZodNativeEnum<typeof CompanySize>>;
+}, "strip", z.ZodTypeAny, {
+    project: Project;
+    emailAddress: string;
+    companyName?: string | undefined;
+    companySize?: CompanySize | undefined;
+    newsletter?: boolean | undefined;
+    projectName?: string | undefined;
+}, {
+    project: Project;
+    emailAddress: string;
+    companyName?: string | undefined;
+    companySize?: CompanySize | undefined;
+    newsletter?: boolean | undefined;
+    projectName?: string | undefined;
+}>;
+export type OssSurveyReportPayload = z.infer<typeof ossSurveyReportPayloadGuard>;
 export declare const userOnboardingDataGuard: z.ZodObject<{
     questionnaire: z.ZodOptional<z.ZodObject<{
         project: z.ZodOptional<z.ZodNativeEnum<typeof Project>>;
@@ -141,4 +187,50 @@ export declare const userOnboardingDataGuard: z.ZodObject<{
     isOnboardingDone?: boolean | undefined;
 }>;
 export type UserOnboardingData = z.infer<typeof userOnboardingDataGuard>;
+export declare const ossUserOnboardingDataGuard: z.ZodObject<{
+    questionnaire: z.ZodOptional<z.ZodObject<{
+        emailAddress: z.ZodOptional<z.ZodString>;
+        newsletter: z.ZodOptional<z.ZodBoolean>;
+        project: z.ZodOptional<z.ZodNativeEnum<typeof Project>>;
+        projectName: z.ZodOptional<z.ZodString>;
+        companyName: z.ZodOptional<z.ZodString>;
+        companySize: z.ZodOptional<z.ZodNativeEnum<typeof CompanySize>>;
+    }, "strip", z.ZodTypeAny, {
+        project?: Project | undefined;
+        companyName?: string | undefined;
+        companySize?: CompanySize | undefined;
+        emailAddress?: string | undefined;
+        newsletter?: boolean | undefined;
+        projectName?: string | undefined;
+    }, {
+        project?: Project | undefined;
+        companyName?: string | undefined;
+        companySize?: CompanySize | undefined;
+        emailAddress?: string | undefined;
+        newsletter?: boolean | undefined;
+        projectName?: string | undefined;
+    }>>;
+    isOnboardingDone: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    questionnaire?: {
+        project?: Project | undefined;
+        companyName?: string | undefined;
+        companySize?: CompanySize | undefined;
+        emailAddress?: string | undefined;
+        newsletter?: boolean | undefined;
+        projectName?: string | undefined;
+    } | undefined;
+    isOnboardingDone?: boolean | undefined;
+}, {
+    questionnaire?: {
+        project?: Project | undefined;
+        companyName?: string | undefined;
+        companySize?: CompanySize | undefined;
+        emailAddress?: string | undefined;
+        newsletter?: boolean | undefined;
+        projectName?: string | undefined;
+    } | undefined;
+    isOnboardingDone?: boolean | undefined;
+}>;
+export type OssUserOnboardingData = z.infer<typeof ossUserOnboardingDataGuard>;
 export {};

package/lib/types/onboarding.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 export const userOnboardingDataKey = 'onboarding';
+export const ossUserOnboardingDataKey = 'ossOnboarding';
 export var Project;
 (function (Project) {
     Project["Personal"] = "personal";
@@ -21,7 +22,6 @@ export var Title;
     Title["Product"] = "product";
     Title["Others"] = "others";
 })(Title || (Title = {}));
-/** @deprecated */
 export var CompanySize;
 (function (CompanySize) {
     CompanySize["Scale1"] = "1";
@@ -30,6 +30,7 @@ export var CompanySize;
     CompanySize["Scale4"] = "200-999";
     CompanySize["Scale5"] = "1000+";
 })(CompanySize || (CompanySize = {}));
+// Kept as a shared enum for OSS onboarding and existing questionnaire payloads.
 /** @deprecated */
 export var Reason;
 (function (Reason) {
@@ -69,7 +70,27 @@ const questionnaireGuard = z.object({
     stage: z.nativeEnum(Stage).optional(),
     additionalFeatures: z.array(z.nativeEnum(AdditionalFeatures)).optional(),
 });
+const ossQuestionnaireGuard = z.object({
+    emailAddress: z.string().optional(),
+    newsletter: z.boolean().optional(),
+    project: z.nativeEnum(Project).optional(),
+    projectName: z.string().max(200).optional(),
+    companyName: z.string().optional(),
+    companySize: z.nativeEnum(CompanySize).optional(),
+});
+export const ossSurveyReportPayloadGuard = z.object({
+    emailAddress: z.string().email().max(320),
+    newsletter: z.boolean().optional(),
+    project: z.nativeEnum(Project),
+    projectName: z.string().max(200).optional(),
+    companyName: z.string().max(200).optional(),
+    companySize: z.nativeEnum(CompanySize).optional(),
+});
 export const userOnboardingDataGuard = z.object({
     questionnaire: questionnaireGuard.optional(),
     isOnboardingDone: z.boolean().optional(),
 });
+export const ossUserOnboardingDataGuard = z.object({
+    questionnaire: ossQuestionnaireGuard.optional(),
+    isOnboardingDone: z.boolean().optional(),
+});

package/lib/types/sign-in-experience.d.ts

@@ -143,6 +143,11 @@ export declare const fullSignInExperienceGuard: z.ZodObject<Omit<{
     emailBlocklistPolicy: z.ZodType<import("../foundations/jsonb-types/sign-in-experience.js").EmailBlocklistPolicy, z.ZodTypeDef, import("../foundations/jsonb-types/sign-in-experience.js").EmailBlocklistPolicy>;
     forgotPasswordMethods: z.ZodType<import("../foundations/jsonb-types/sign-in-experience.js").ForgotPasswordMethod[] | null, z.ZodTypeDef, import("../foundations/jsonb-types/sign-in-experience.js").ForgotPasswordMethod[] | null>;
     passkeySignIn: z.ZodType<import("../foundations/jsonb-types/sign-in-experience.js").PasskeySignIn, z.ZodTypeDef, import("../foundations/jsonb-types/sign-in-experience.js").PasskeySignIn>;
+    signUpProfileFields: z.ZodType<{
+        name: string;
+    }[] | null, z.ZodTypeDef, {
+        name: string;
+    }[] | null>;
 }, "forgotPasswordMethods"> & {
     socialConnectors: z.ZodArray<z.ZodObject<Omit<{
         id: z.ZodString;
@@ -698,9 +703,9 @@ export declare const fullSignInExperienceGuard: z.ZodObject<Omit<{
     id: string;
     tenantId: string;
     mfa: import("../foundations/jsonb-types/sign-in-experience.js").Mfa;
+    customCss: string | null;
     color: import("../foundations/jsonb-types/sign-in-experience.js").Color;
     branding: import("../foundations/jsonb-types/sign-in-experience.js").Branding;
-    customCss: string | null;
     termsOfUseUrl: string | null;
     privacyPolicyUrl: string | null;
     hideLogtoBranding: boolean;
@@ -723,6 +728,7 @@ export declare const fullSignInExperienceGuard: z.ZodObject<Omit<{
     sentinelPolicy: import("../foundations/jsonb-types/sign-in-experience.js").SentinelPolicy;
     emailBlocklistPolicy: import("../foundations/jsonb-types/sign-in-experience.js").EmailBlocklistPolicy;
     passkeySignIn: import("../foundations/jsonb-types/sign-in-experience.js").PasskeySignIn;
+    signUpProfileFields: import("../foundations/jsonb-types/sign-in-experience.js").SignUpProfileFields | null;
     socialConnectors: {
         name: {
             en: string;
@@ -895,9 +901,9 @@ export declare const fullSignInExperienceGuard: z.ZodObject<Omit<{
     id: string;
     tenantId: string;
     mfa: import("../foundations/jsonb-types/sign-in-experience.js").Mfa;
+    customCss: string | null;
     color: import("../foundations/jsonb-types/sign-in-experience.js").Color;
     branding: import("../foundations/jsonb-types/sign-in-experience.js").Branding;
-    customCss: string | null;
     termsOfUseUrl: string | null;
     privacyPolicyUrl: string | null;
     hideLogtoBranding: boolean;
@@ -920,6 +926,7 @@ export declare const fullSignInExperienceGuard: z.ZodObject<Omit<{
     sentinelPolicy: import("../foundations/jsonb-types/sign-in-experience.js").SentinelPolicy;
     emailBlocklistPolicy: import("../foundations/jsonb-types/sign-in-experience.js").EmailBlocklistPolicy;
     passkeySignIn: import("../foundations/jsonb-types/sign-in-experience.js").PasskeySignIn;
+    signUpProfileFields: import("../foundations/jsonb-types/sign-in-experience.js").SignUpProfileFields | null;
     socialConnectors: {
         name: {
             en: string;

package/lib/types/user-logto-config.d.ts

@@ -58,6 +58,17 @@ export declare const userPasskeySignInDataGuard: z.ZodObject<{
     skipped?: boolean | undefined;
 }>;
 export type UserPasskeySignInData = z.infer<typeof userPasskeySignInDataGuard>;
+/**
+ * Schema for the MFA settings API response (GET/PATCH /api/my-account/mfa-settings)
+ */
+export declare const userMfaSettingsResponseGuard: z.ZodObject<{
+    skipMfaOnSignIn: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    skipMfaOnSignIn: boolean;
+}, {
+    skipMfaOnSignIn: boolean;
+}>;
+export type UserMfaSettingsResponse = z.infer<typeof userMfaSettingsResponseGuard>;
 /**
  * Schema for user's logto_config field
  */

package/lib/types/user-logto-config.js

@@ -45,6 +45,12 @@ export const userPasskeySignInDataGuard = z.object({
      */
     skipped: z.boolean().optional(),
 });
+/**
+ * Schema for the MFA settings API response (GET/PATCH /api/my-account/mfa-settings)
+ */
+export const userMfaSettingsResponseGuard = z.object({
+    skipMfaOnSignIn: z.boolean(),
+});
 /**
  * Schema for user's logto_config field
  */

package/lib/utils/index.d.ts

@@ -2,3 +2,4 @@ export * from './application.js';
 export * from './role.js';
 export * from './management-api.js';
 export * from './domain.js';
+export * from './oidc-private-key.js';

package/lib/utils/index.js

@@ -2,3 +2,4 @@ export * from './application.js';
 export * from './role.js';
 export * from './management-api.js';
 export * from './domain.js';
+export * from './oidc-private-key.js';

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

@@ -0,0 +1,88 @@
+import type { LogtoOidcConfigType, OidcPrivateKey, SigningKeyRotationState } from '../types/index.js';
+import { OidcSigningKeyStatus } from '../types/index.js';
+export type NormalizedOidcPrivateKey = OidcPrivateKey & {
+    status: OidcSigningKeyStatus;
+};
+/**
+ * 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 declare const normalizeOidcPrivateKeys: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"]) => NormalizedOidcPrivateKey[];
+/**
+ * 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 declare const getCanonicalOidcPrivateKeys: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"]) => OidcPrivateKey[];
+/**
+ * Return the currently active signing key from a private-key set.
+ *
+ * This helper reads explicit key status rather than relying on array index.
+ */
+export declare const getCurrentOidcPrivateKey: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"]) => OidcPrivateKey;
+/**
+ * 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 declare const getOidcProviderPrivateKeys: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"]) => OidcPrivateKey[];
+/**
+ * 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 declare const getSeededOidcPrivateKeys: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"]) => OidcPrivateKey[];
+/**
+ * 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 declare const getImmediatelyRotatedOidcPrivateKeys: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"], newPrivateKey: OidcPrivateKey) => OidcPrivateKey[];
+/**
+ * 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 declare const getStagedRotatedOidcPrivateKeys: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"], newPrivateKey: OidcPrivateKey) => OidcPrivateKey[];
+/**
+ * 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 declare const rotateOidcPrivateKeyStatuses: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"]) => OidcPrivateKey[];
+/**
+ * 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 declare const getOidcPrivateKeysAfterDeletion: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"], deletedKeyId: string) => OidcPrivateKey[];
+/**
+ * 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 declare const getTrimmedOidcPrivateKeys: (privateKeys: LogtoOidcConfigType["oidc.privateKeys"], length: number) => OidcPrivateKey[];
+/**
+ * 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 declare const getRotationStateForCacheInvalidation: (currentRotationState: SigningKeyRotationState | undefined, now?: number) => SigningKeyRotationState;
+/**
+ * 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 declare const getRotationStateForStagedRotation: (currentRotationState: SigningKeyRotationState | undefined, rotationGracePeriod: number, now?: number) => SigningKeyRotationState;