@logto/schemas 1.43.0 → 1.44.0

package/alterations/1.44.0-1788946735-add-saml-authn-request-config.ts

@@ -0,0 +1,18 @@
+import { sql } from '@silverhand/slonik';
+
+import type { AlterationScript } from '../lib/types/alteration.js';
+
+const alteration: AlterationScript = {
+  up: async (pool) => {
+    await pool.query(sql`
+      alter table saml_application_configs add column authn_request_config jsonb;
+    `);
+  },
+  down: async (pool) => {
+    await pool.query(sql`
+      alter table saml_application_configs drop column authn_request_config;
+    `);
+  },
+};
+
+export default alteration;

package/alterations/1.44.0-1789000000-extend-user-id-length.ts

@@ -0,0 +1,61 @@
+import { sql } from '@silverhand/slonik';
+
+import type { AlterationScript } from '../lib/types/alteration.js';
+
+/**
+ * Widen `users.id` and every column that references it to varchar(128).
+ *
+ * Users migrated from other identity providers may carry over their original IDs, which are
+ * often longer than the 12 or 21 characters previously allowed.
+ */
+
+type Column = [table: string, column: string, originalLength: 12 | 21];
+
+const columns: Column[] = [
+  ['users', 'id', 12],
+  ['user_sign_in_countries', 'user_id', 12],
+  ['user_geo_locations', 'user_id', 12],
+  ['trusted_devices', 'user_id', 12],
+  ['user_sso_identities', 'user_id', 12],
+  ['oidc_session_extensions', 'account_id', 12],
+  ['users_roles', 'user_id', 21],
+  ['organization_user_relations', 'user_id', 21],
+  ['organization_role_user_relations', 'user_id', 21],
+  ['organization_invitations', 'inviter_id', 21],
+  ['organization_invitations', 'accepted_user_id', 21],
+  ['subject_tokens', 'user_id', 21],
+  ['verification_statuses', 'user_id', 21],
+  ['verification_records', 'user_id', 21],
+  ['secrets', 'user_id', 21],
+  ['personal_access_tokens', 'user_id', 21],
+  ['application_access_control_user_relations', 'user_id', 21],
+  ['application_user_consent_organizations', 'user_id', 21],
+  ['cimd_grant_organizations', 'user_id', 21],
+  ['daily_active_users', 'user_id', 21],
+  ['aggregated_daily_active_users', 'user_id', 21],
+];
+
+const alteration: AlterationScript = {
+  up: async (pool) => {
+    for (const [table, column] of columns) {
+      // eslint-disable-next-line no-await-in-loop -- DDL statements must run sequentially
+      await pool.query(sql`
+        alter table ${sql.identifier([table])}
+        alter column ${sql.identifier([column])} type varchar(128)
+      `);
+    }
+  },
+  down: async (pool) => {
+    // Shrinking fails if any existing value is longer than the original limit; there is no
+    // safe way to truncate an ID, so let Postgres reject the rollback in that case.
+    for (const [table, column, originalLength] of columns) {
+      // eslint-disable-next-line no-await-in-loop -- DDL statements must run sequentially
+      await pool.query(sql`
+        alter table ${sql.identifier([table])}
+        alter column ${sql.identifier([column])} type varchar(${sql.raw(String(originalLength))})
+      `);
+    }
+  },
+};
+
+export default alteration;

package/alterations-js/1.44.0-1788946735-add-saml-authn-request-config.js

@@ -0,0 +1,14 @@
+import { sql } from '@silverhand/slonik';
+const alteration = {
+    up: async (pool) => {
+        await pool.query(sql `
+      alter table saml_application_configs add column authn_request_config jsonb;
+    `);
+    },
+    down: async (pool) => {
+        await pool.query(sql `
+      alter table saml_application_configs drop column authn_request_config;
+    `);
+    },
+};
+export default alteration;

package/alterations-js/1.44.0-1789000000-extend-user-id-length.js

@@ -0,0 +1,47 @@
+import { sql } from '@silverhand/slonik';
+const columns = [
+    ['users', 'id', 12],
+    ['user_sign_in_countries', 'user_id', 12],
+    ['user_geo_locations', 'user_id', 12],
+    ['trusted_devices', 'user_id', 12],
+    ['user_sso_identities', 'user_id', 12],
+    ['oidc_session_extensions', 'account_id', 12],
+    ['users_roles', 'user_id', 21],
+    ['organization_user_relations', 'user_id', 21],
+    ['organization_role_user_relations', 'user_id', 21],
+    ['organization_invitations', 'inviter_id', 21],
+    ['organization_invitations', 'accepted_user_id', 21],
+    ['subject_tokens', 'user_id', 21],
+    ['verification_statuses', 'user_id', 21],
+    ['verification_records', 'user_id', 21],
+    ['secrets', 'user_id', 21],
+    ['personal_access_tokens', 'user_id', 21],
+    ['application_access_control_user_relations', 'user_id', 21],
+    ['application_user_consent_organizations', 'user_id', 21],
+    ['cimd_grant_organizations', 'user_id', 21],
+    ['daily_active_users', 'user_id', 21],
+    ['aggregated_daily_active_users', 'user_id', 21],
+];
+const alteration = {
+    up: async (pool) => {
+        for (const [table, column] of columns) {
+            // eslint-disable-next-line no-await-in-loop -- DDL statements must run sequentially
+            await pool.query(sql `
+        alter table ${sql.identifier([table])}
+        alter column ${sql.identifier([column])} type varchar(128)
+      `);
+        }
+    },
+    down: async (pool) => {
+        // Shrinking fails if any existing value is longer than the original limit; there is no
+        // safe way to truncate an ID, so let Postgres reject the rollback in that case.
+        for (const [table, column, originalLength] of columns) {
+            // eslint-disable-next-line no-await-in-loop -- DDL statements must run sequentially
+            await pool.query(sql `
+        alter table ${sql.identifier([table])}
+        alter column ${sql.identifier([column])} type varchar(${sql.raw(String(originalLength))})
+      `);
+        }
+    },
+};
+export default alteration;

package/lib/consts/experience.d.ts

@@ -11,6 +11,9 @@ export declare const experience: Readonly<{
         readonly switchAccount: "switch-account";
         readonly oneTimeToken: "one-time-token";
         readonly accountSuspended: "account-suspended";
+        readonly trustedDevice: "trusted-device";
+        /** Pure step-up: an authenticated session pins the subject and only the missing assurance is asked. */
+        readonly stepUp: "step-up";
     }>;
 }>;
 /** `postMessage` sender tag from admin Console sign-in experience live preview. */

package/lib/consts/experience.js

@@ -10,6 +10,9 @@ const routes = Object.freeze({
     switchAccount: 'switch-account',
     oneTimeToken: 'one-time-token',
     accountSuspended: 'account-suspended',
+    trustedDevice: 'trusted-device',
+    /** Pure step-up: an authenticated session pins the subject and only the missing assurance is asked. */
+    stepUp: 'step-up',
 });
 export const experience = Object.freeze({
     routes,

package/lib/consts/index.d.ts

@@ -11,3 +11,4 @@ export * from './verification-code.js';
 export * from './product-event.js';
 export * from './application.js';
 export * from './social-state.js';
+export * from './license.js';

package/lib/consts/index.js

@@ -11,3 +11,4 @@ export * from './verification-code.js';
 export * from './product-event.js';
 export * from './application.js';
 export * from './social-state.js';
+export * from './license.js';

package/lib/consts/license.d.ts

@@ -0,0 +1,222 @@
+import { z } from 'zod';
+import { ReservedPlanId } from './subscriptions.js';
+/**
+ * The deployment a license key is valid for.
+ *
+ * Logto signs one key per environment for the same license, identical except for this claim, so a
+ * customer can run their staging or CI deployment without sharing the production key. Which key is
+ * installed where is the customer's declaration; Logto does not verify it.
+ */
+export declare enum LicenseEnv {
+    Production = "production",
+    NonProduction = "non-production"
+}
+/** The plans a license key can grant. A Cloud-only plan is never a valid license `plan`. */
+export declare const selfHostedPlanIds: readonly [ReservedPlanId.SelfHostedPro, ReservedPlanId.SelfHostedEnterprise];
+/** The plan a license key grants. See {@link selfHostedPlanIds}. */
+export type SelfHostedPlanId = (typeof selfHostedPlanIds)[number];
+/**
+ * The entitlements of a self-hosted instance: the features a license unlocks, plus the numeric
+ * quotas it raises.
+ *
+ * The names follow the license payload rather than the Cloud `SubscriptionQuota` vocabulary
+ * (`bringYourUi`, not `bringYourUiEnabled`): these values are resolved locally from an installed
+ * key and never travel through the Cloud subscription API or its usage reporting.
+ * `samlApplicationsLimit` is the one name shared with Cloud, and it keeps the same meaning there —
+ * `null` is unlimited, a number is the hard cap.
+ */
+export type LicenseQuota = {
+    /** Whether the sign-in experience may hide the Logto branding. */
+    hideLogtoBranding: boolean;
+    /** Whether custom sign-in experience assets and a custom CSP may be configured. */
+    bringYourUi: boolean;
+    /** Whether IdP-initiated SSO may be configured on an enterprise SSO connector. */
+    idpInitiatedSso: boolean;
+    /** Whether the instance's Console may be administered by more than one member. */
+    consoleCollaboration: boolean;
+    /** Whether the sign-in experience MFA policy may be set to mandatory. */
+    mandatoryMfa: boolean;
+    /**
+     * Whether Logto's hosted email service may be used.
+     *
+     * Always `false` for {@link ReservedPlanId.SelfHostedPro}. The Enterprise offering is deferred,
+     * so the flag is carried from the first signed key onwards and simply never set, which keeps the
+     * signed shape stable when Enterprise ships.
+     */
+    hostedEmail: boolean;
+    /** How many SAML applications the instance may create. `null` means unlimited. */
+    samlApplicationsLimit: number | null;
+};
+export declare const licenseQuotaGuard: z.ZodObject<{
+    hideLogtoBranding: z.ZodBoolean;
+    bringYourUi: z.ZodBoolean;
+    idpInitiatedSso: z.ZodBoolean;
+    consoleCollaboration: z.ZodBoolean;
+    mandatoryMfa: z.ZodBoolean;
+    hostedEmail: z.ZodBoolean;
+    samlApplicationsLimit: z.ZodNullable<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    hideLogtoBranding: boolean;
+    bringYourUi: boolean;
+    idpInitiatedSso: boolean;
+    consoleCollaboration: boolean;
+    mandatoryMfa: boolean;
+    hostedEmail: boolean;
+    samlApplicationsLimit: number | null;
+}, {
+    hideLogtoBranding: boolean;
+    bringYourUi: boolean;
+    idpInitiatedSso: boolean;
+    consoleCollaboration: boolean;
+    mandatoryMfa: boolean;
+    hostedEmail: boolean;
+    samlApplicationsLimit: number | null;
+}>;
+/**
+ * The entitlements a license key grants, as they appear in its payload.
+ *
+ * Every field is optional: a key only carries what it changes, and an absent field falls back to
+ * {@link ossDefaultQuota}. Keeping it partial means a key signed before a new entitlement existed
+ * still verifies on a newer Logto, and the missing entitlement stays locked rather than breaking
+ * the whole license. Use {@link resolveLicenseQuota} to apply the overrides.
+ */
+export declare const licenseQuotaOverridesGuard: z.ZodObject<{
+    hideLogtoBranding: z.ZodOptional<z.ZodBoolean>;
+    bringYourUi: z.ZodOptional<z.ZodBoolean>;
+    idpInitiatedSso: z.ZodOptional<z.ZodBoolean>;
+    consoleCollaboration: z.ZodOptional<z.ZodBoolean>;
+    mandatoryMfa: z.ZodOptional<z.ZodBoolean>;
+    hostedEmail: z.ZodOptional<z.ZodBoolean>;
+    samlApplicationsLimit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    hideLogtoBranding?: boolean | undefined;
+    bringYourUi?: boolean | undefined;
+    idpInitiatedSso?: boolean | undefined;
+    consoleCollaboration?: boolean | undefined;
+    mandatoryMfa?: boolean | undefined;
+    hostedEmail?: boolean | undefined;
+    samlApplicationsLimit?: number | null | undefined;
+}, {
+    hideLogtoBranding?: boolean | undefined;
+    bringYourUi?: boolean | undefined;
+    idpInitiatedSso?: boolean | undefined;
+    consoleCollaboration?: boolean | undefined;
+    mandatoryMfa?: boolean | undefined;
+    hostedEmail?: boolean | undefined;
+    samlApplicationsLimit?: number | null | undefined;
+}>;
+export type LicenseQuotaOverrides = z.infer<typeof licenseQuotaOverridesGuard>;
+/**
+ * The payload of a license key, i.e. the claims of the Ed25519-signed JWT an operator installs on a
+ * self-hosted instance.
+ *
+ * The signature is what makes the payload trustworthy, so none of it is editable after issuing.
+ * Unknown claims are stripped rather than rejected, so a newer license service can add one without
+ * invalidating the key on an older Logto.
+ */
+export type LicensePayload = {
+    /** The plan the license grants. */
+    plan: SelfHostedPlanId;
+    /** The deployment the key is valid for. */
+    env: LicenseEnv;
+    /** The Logto customer the license was issued to, for support and renewal lookups. */
+    customerId: string;
+    /** The license's own identifier, shared by its production and non-production keys. */
+    licenseId: string;
+    /** When the key was signed, in seconds since the Unix epoch. */
+    iat: number;
+    /** When the key expires, in seconds since the Unix epoch. */
+    exp: number;
+    /** The entitlements the license grants on top of {@link ossDefaultQuota}. */
+    quota: LicenseQuotaOverrides;
+};
+export declare const licensePayloadGuard: z.ZodObject<{
+    plan: z.ZodEnum<[ReservedPlanId.SelfHostedPro, ReservedPlanId.SelfHostedEnterprise]>;
+    env: z.ZodNativeEnum<typeof LicenseEnv>;
+    customerId: z.ZodString;
+    licenseId: z.ZodString;
+    iat: z.ZodNumber;
+    exp: z.ZodNumber;
+    quota: z.ZodObject<{
+        hideLogtoBranding: z.ZodOptional<z.ZodBoolean>;
+        bringYourUi: z.ZodOptional<z.ZodBoolean>;
+        idpInitiatedSso: z.ZodOptional<z.ZodBoolean>;
+        consoleCollaboration: z.ZodOptional<z.ZodBoolean>;
+        mandatoryMfa: z.ZodOptional<z.ZodBoolean>;
+        hostedEmail: z.ZodOptional<z.ZodBoolean>;
+        samlApplicationsLimit: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        hideLogtoBranding?: boolean | undefined;
+        bringYourUi?: boolean | undefined;
+        idpInitiatedSso?: boolean | undefined;
+        consoleCollaboration?: boolean | undefined;
+        mandatoryMfa?: boolean | undefined;
+        hostedEmail?: boolean | undefined;
+        samlApplicationsLimit?: number | null | undefined;
+    }, {
+        hideLogtoBranding?: boolean | undefined;
+        bringYourUi?: boolean | undefined;
+        idpInitiatedSso?: boolean | undefined;
+        consoleCollaboration?: boolean | undefined;
+        mandatoryMfa?: boolean | undefined;
+        hostedEmail?: boolean | undefined;
+        samlApplicationsLimit?: number | null | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    exp: number;
+    iat: number;
+    plan: ReservedPlanId.SelfHostedPro | ReservedPlanId.SelfHostedEnterprise;
+    env: LicenseEnv;
+    customerId: string;
+    licenseId: string;
+    quota: {
+        hideLogtoBranding?: boolean | undefined;
+        bringYourUi?: boolean | undefined;
+        idpInitiatedSso?: boolean | undefined;
+        consoleCollaboration?: boolean | undefined;
+        mandatoryMfa?: boolean | undefined;
+        hostedEmail?: boolean | undefined;
+        samlApplicationsLimit?: number | null | undefined;
+    };
+}, {
+    exp: number;
+    iat: number;
+    plan: ReservedPlanId.SelfHostedPro | ReservedPlanId.SelfHostedEnterprise;
+    env: LicenseEnv;
+    customerId: string;
+    licenseId: string;
+    quota: {
+        hideLogtoBranding?: boolean | undefined;
+        bringYourUi?: boolean | undefined;
+        idpInitiatedSso?: boolean | undefined;
+        consoleCollaboration?: boolean | undefined;
+        mandatoryMfa?: boolean | undefined;
+        hostedEmail?: boolean | undefined;
+        samlApplicationsLimit?: number | null | undefined;
+    };
+}>;
+/**
+ * The entitlements of a self-hosted instance with no license key installed, i.e. today's OSS.
+ *
+ * Every feature is locked and SAML applications keep the long-standing cap of 3. Core falls back to
+ * this when no valid license is installed, and Console displays it, so there is exactly one
+ * definition of "self-hosted, no license".
+ */
+export declare const ossDefaultQuota: Readonly<{
+    hideLogtoBranding: false;
+    bringYourUi: false;
+    idpInitiatedSso: false;
+    consoleCollaboration: false;
+    mandatoryMfa: false;
+    hostedEmail: false;
+    samlApplicationsLimit: number;
+}>;
+/**
+ * Resolve the effective entitlements of a self-hosted instance by applying a license key's
+ * overrides on top of {@link ossDefaultQuota}. Without a key, the OSS defaults are the answer.
+ *
+ * Core and Console both call this so they can never disagree on what a license grants. The fields
+ * are applied one by one on purpose: `samlApplicationsLimit` is nullable and `null` means
+ * unlimited, so a `??` merge would silently turn an unlimited license back into the OSS cap.
+ */
+export declare const resolveLicenseQuota: (overrides?: LicenseQuotaOverrides) => LicenseQuota;

package/lib/consts/license.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { ReservedPlanId } from './subscriptions.js';
+/**
+ * The deployment a license key is valid for.
+ *
+ * Logto signs one key per environment for the same license, identical except for this claim, so a
+ * customer can run their staging or CI deployment without sharing the production key. Which key is
+ * installed where is the customer's declaration; Logto does not verify it.
+ */
+export var LicenseEnv;
+(function (LicenseEnv) {
+    LicenseEnv["Production"] = "production";
+    LicenseEnv["NonProduction"] = "non-production";
+})(LicenseEnv || (LicenseEnv = {}));
+/** The plans a license key can grant. A Cloud-only plan is never a valid license `plan`. */
+export const selfHostedPlanIds = Object.freeze([
+    ReservedPlanId.SelfHostedPro,
+    ReservedPlanId.SelfHostedEnterprise,
+]);
+export const licenseQuotaGuard = z.object({
+    hideLogtoBranding: z.boolean(),
+    bringYourUi: z.boolean(),
+    idpInitiatedSso: z.boolean(),
+    consoleCollaboration: z.boolean(),
+    mandatoryMfa: z.boolean(),
+    hostedEmail: z.boolean(),
+    samlApplicationsLimit: z.number().int().nonnegative().nullable(),
+});
+/**
+ * The entitlements a license key grants, as they appear in its payload.
+ *
+ * Every field is optional: a key only carries what it changes, and an absent field falls back to
+ * {@link ossDefaultQuota}. Keeping it partial means a key signed before a new entitlement existed
+ * still verifies on a newer Logto, and the missing entitlement stays locked rather than breaking
+ * the whole license. Use {@link resolveLicenseQuota} to apply the overrides.
+ */
+export const licenseQuotaOverridesGuard = licenseQuotaGuard.partial();
+export const licensePayloadGuard = z.object({
+    plan: z.enum(selfHostedPlanIds),
+    env: z.nativeEnum(LicenseEnv),
+    customerId: z.string(),
+    licenseId: z.string(),
+    iat: z.number().int().nonnegative(),
+    exp: z.number().int().nonnegative(),
+    quota: licenseQuotaOverridesGuard,
+});
+/**
+ * The entitlements of a self-hosted instance with no license key installed, i.e. today's OSS.
+ *
+ * Every feature is locked and SAML applications keep the long-standing cap of 3. Core falls back to
+ * this when no valid license is installed, and Console displays it, so there is exactly one
+ * definition of "self-hosted, no license".
+ */
+export const ossDefaultQuota = Object.freeze({
+    hideLogtoBranding: false,
+    bringYourUi: false,
+    idpInitiatedSso: false,
+    consoleCollaboration: false,
+    mandatoryMfa: false,
+    hostedEmail: false,
+    samlApplicationsLimit: 3,
+});
+/**
+ * Resolve the effective entitlements of a self-hosted instance by applying a license key's
+ * overrides on top of {@link ossDefaultQuota}. Without a key, the OSS defaults are the answer.
+ *
+ * Core and Console both call this so they can never disagree on what a license grants. The fields
+ * are applied one by one on purpose: `samlApplicationsLimit` is nullable and `null` means
+ * unlimited, so a `??` merge would silently turn an unlimited license back into the OSS cap.
+ */
+export const resolveLicenseQuota = (overrides = {}) => ({
+    hideLogtoBranding: overrides.hideLogtoBranding ?? ossDefaultQuota.hideLogtoBranding,
+    bringYourUi: overrides.bringYourUi ?? ossDefaultQuota.bringYourUi,
+    idpInitiatedSso: overrides.idpInitiatedSso ?? ossDefaultQuota.idpInitiatedSso,
+    consoleCollaboration: overrides.consoleCollaboration ?? ossDefaultQuota.consoleCollaboration,
+    mandatoryMfa: overrides.mandatoryMfa ?? ossDefaultQuota.mandatoryMfa,
+    hostedEmail: overrides.hostedEmail ?? ossDefaultQuota.hostedEmail,
+    samlApplicationsLimit: overrides.samlApplicationsLimit === undefined
+        ? ossDefaultQuota.samlApplicationsLimit
+        : overrides.samlApplicationsLimit,
+});

package/lib/consts/license.test.d.ts

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

package/lib/consts/license.test.js

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import { LicenseEnv, licensePayloadGuard, ossDefaultQuota, resolveLicenseQuota, } from './license.js';
+import { ReservedPlanId } from './subscriptions.js';
+const validPayload = Object.freeze({
+    plan: ReservedPlanId.SelfHostedPro,
+    env: LicenseEnv.Production,
+    customerId: 'cus_1234567890',
+    licenseId: 'lic_1234567890',
+    iat: 1_760_000_000,
+    exp: 1_791_536_000,
+    quota: {
+        hideLogtoBranding: true,
+        bringYourUi: true,
+        idpInitiatedSso: true,
+        consoleCollaboration: true,
+        mandatoryMfa: true,
+        hostedEmail: false,
+        samlApplicationsLimit: null,
+    },
+});
+describe('licensePayloadGuard', () => {
+    it('parses a production Pro license payload', () => {
+        expect(licensePayloadGuard.parse(validPayload)).toEqual(validPayload);
+    });
+    it('parses a non-production Enterprise license payload', () => {
+        const payload = {
+            ...validPayload,
+            plan: ReservedPlanId.SelfHostedEnterprise,
+            env: LicenseEnv.NonProduction,
+        };
+        expect(licensePayloadGuard.parse(payload)).toEqual(payload);
+    });
+    it('parses a payload carrying only the entitlements it changes', () => {
+        const payload = { ...validPayload, quota: { hideLogtoBranding: true } };
+        expect(licensePayloadGuard.parse(payload)).toEqual(payload);
+    });
+    it.each([ReservedPlanId.Free, ReservedPlanId.Pro202509, ReservedPlanId.Development])('rejects the Cloud-only plan %s', (plan) => {
+        expect(licensePayloadGuard.safeParse({ ...validPayload, plan }).success).toBe(false);
+    });
+    it('rejects an unknown environment', () => {
+        expect(licensePayloadGuard.safeParse({ ...validPayload, env: 'staging' }).success).toBe(false);
+    });
+    it.each([-1, 1.5, '3'])('rejects the SAML application limit %j', (samlApplicationsLimit) => {
+        expect(licensePayloadGuard.safeParse({
+            ...validPayload,
+            quota: { ...validPayload.quota, samlApplicationsLimit },
+        }).success).toBe(false);
+    });
+    it('strips unknown claims instead of rejecting them', () => {
+        expect(licensePayloadGuard.parse({ ...validPayload, iss: 'https://logto.io' })).toEqual(validPayload);
+    });
+});
+describe('ossDefaultQuota', () => {
+    it('locks every feature and caps SAML applications at 3', () => {
+        expect(ossDefaultQuota).toStrictEqual({
+            hideLogtoBranding: false,
+            bringYourUi: false,
+            idpInitiatedSso: false,
+            consoleCollaboration: false,
+            mandatoryMfa: false,
+            hostedEmail: false,
+            samlApplicationsLimit: 3,
+        });
+    });
+});
+describe('resolveLicenseQuota', () => {
+    it('falls back to the OSS defaults without a license', () => {
+        expect(resolveLicenseQuota()).toStrictEqual(ossDefaultQuota);
+    });
+    it('applies every entitlement a license grants', () => {
+        expect(resolveLicenseQuota(validPayload.quota)).toStrictEqual({
+            hideLogtoBranding: true,
+            bringYourUi: true,
+            idpInitiatedSso: true,
+            consoleCollaboration: true,
+            mandatoryMfa: true,
+            hostedEmail: false,
+            samlApplicationsLimit: null,
+        });
+    });
+    it('keeps the OSS default for an entitlement the license does not carry', () => {
+        expect(resolveLicenseQuota({ hideLogtoBranding: true })).toStrictEqual({
+            ...ossDefaultQuota,
+            hideLogtoBranding: true,
+        });
+    });
+    it('keeps an unlimited SAML application quota instead of falling back to the cap', () => {
+        expect(resolveLicenseQuota({ samlApplicationsLimit: null }).samlApplicationsLimit).toBeNull();
+    });
+    it('applies a SAML application quota of 0', () => {
+        expect(resolveLicenseQuota({ samlApplicationsLimit: 0 }).samlApplicationsLimit).toBe(0);
+    });
+    it('applies an explicitly disabled entitlement', () => {
+        expect(resolveLicenseQuota({ hostedEmail: false }).hostedEmail).toBe(false);
+    });
+});

package/lib/consts/oidc.d.ts

@@ -67,7 +67,17 @@ export declare enum ExtraParamsKey {
     /**
      * The Google One Tap credential JWT token for external website integration.
      */
-    GoogleOneTapCredential = "google_one_tap_credential"
+    GoogleOneTapCredential = "google_one_tap_credential",
+    /**
+     * Overrides the theme that the sign-in experience would otherwise resolve from the end-user's
+     * OS settings, so an application with its own light / dark toggle can keep Logto in sync.
+     *
+     * The parameter is ignored when dark mode is disabled in the sign-in experience configuration,
+     * and an unrecognized value is ignored without affecting the other parameters.
+     *
+     * The available values are `light` and `dark`.
+     */
+    Theme = "theme"
 }
 /** @deprecated Use {@link FirstScreen} instead. */
 export declare enum InteractionMode {
@@ -94,6 +104,7 @@ export declare const extraParamsObjectGuard: z.ZodObject<{
     identifier: z.ZodOptional<z.ZodString>;
     one_time_token: z.ZodOptional<z.ZodString>;
     google_one_tap_credential: z.ZodOptional<z.ZodString>;
+    theme: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     interaction_mode?: InteractionMode | undefined;
     first_screen?: FirstScreen | undefined;
@@ -104,6 +115,7 @@ export declare const extraParamsObjectGuard: z.ZodObject<{
     identifier?: string | undefined;
     one_time_token?: string | undefined;
     google_one_tap_credential?: string | undefined;
+    theme?: string | undefined;
 }, {
     interaction_mode?: InteractionMode | undefined;
     first_screen?: FirstScreen | undefined;
@@ -114,6 +126,7 @@ export declare const extraParamsObjectGuard: z.ZodObject<{
     identifier?: string | undefined;
     one_time_token?: string | undefined;
     google_one_tap_credential?: string | undefined;
+    theme?: string | undefined;
 }>;
 export type ExtraParamsObject = Partial<{
     [ExtraParamsKey.InteractionMode]: InteractionMode;
@@ -125,4 +138,5 @@ export type ExtraParamsObject = Partial<{
     [ExtraParamsKey.Identifier]: string;
     [ExtraParamsKey.OneTimeToken]: string;
     [ExtraParamsKey.GoogleOneTapCredential]: string;
+    [ExtraParamsKey.Theme]: string;
 }>;

package/lib/consts/oidc.js

@@ -70,6 +70,16 @@ export var ExtraParamsKey;
      * The Google One Tap credential JWT token for external website integration.
      */
     ExtraParamsKey["GoogleOneTapCredential"] = "google_one_tap_credential";
+    /**
+     * Overrides the theme that the sign-in experience would otherwise resolve from the end-user's
+     * OS settings, so an application with its own light / dark toggle can keep Logto in sync.
+     *
+     * The parameter is ignored when dark mode is disabled in the sign-in experience configuration,
+     * and an unrecognized value is ignored without affecting the other parameters.
+     *
+     * The available values are `light` and `dark`.
+     */
+    ExtraParamsKey["Theme"] = "theme";
 })(ExtraParamsKey || (ExtraParamsKey = {}));
 /** @deprecated Use {@link FirstScreen} instead. */
 export var InteractionMode;
@@ -99,5 +109,6 @@ export const extraParamsObjectGuard = z
     [ExtraParamsKey.Identifier]: z.string(),
     [ExtraParamsKey.OneTimeToken]: z.string(),
     [ExtraParamsKey.GoogleOneTapCredential]: z.string(),
+    [ExtraParamsKey.Theme]: z.string(),
 })
     .partial();

package/lib/consts/oidc.test.d.ts

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

package/lib/consts/oidc.test.js

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { ExtraParamsKey, FirstScreen, extraParamsObjectGuard } from './oidc.js';
+describe('extraParamsObjectGuard', () => {
+    it('should keep the other parameters when the theme is not a supported value', () => {
+        // Core parses every extra param in one call and falls back to an empty object when the
+        // parse throws, so a loose value here must never discard the parameters next to it.
+        const params = extraParamsObjectGuard.parse({
+            [ExtraParamsKey.Theme]: 'sepia',
+            [ExtraParamsKey.FirstScreen]: FirstScreen.Register,
+            [ExtraParamsKey.LoginHint]: 'foo@logto.io',
+        });
+        expect(params[ExtraParamsKey.FirstScreen]).toBe(FirstScreen.Register);
+        expect(params[ExtraParamsKey.LoginHint]).toBe('foo@logto.io');
+    });
+});