@logto/schemas 1.42.0 → 1.44.0

package/alterations-js/1.43.0-1785835991-add-cimd-client-identifier-columns.js

@@ -0,0 +1,27 @@
+import { sql } from '@silverhand/slonik';
+/**
+ * Registered application IDs (21 chars, referencing `applications`) and CIMD (client ID metadata
+ * document) client identifier URLs are different value spaces, so each gets its own column instead
+ * of sharing one.
+ */
+const alteration = {
+    up: async (pool) => {
+        await pool.query(sql `
+      alter table users
+        add column cimd_client_id varchar(2048);
+
+      alter table oidc_session_extensions
+        add column cimd_client_id varchar(2048);
+    `);
+    },
+    down: async (pool) => {
+        await pool.query(sql `
+      alter table users
+        drop column cimd_client_id;
+
+      alter table oidc_session_extensions
+        drop column cimd_client_id;
+    `);
+    },
+};
+export default alteration;

package/alterations-js/1.43.0-1786325989-add-cimd-grant-organizations-table.js

@@ -0,0 +1,49 @@
+import { sql } from '@silverhand/slonik';
+import { applyTableRls, dropTableRls } from './utils/1704934999-tables.js';
+/**
+ * Add the grant-scoped organization authorization table for client ID metadata document (CIMD)
+ * clients. CIMD clients are unregistered URL identities with no deletion lifecycle and
+ * transferable ownership, so organization access follows the single authorization instead of a
+ * long-lived cross-grant relation: rows cascade away with the Grant row (revocation hard-deletes
+ * it) and with the user's organization membership.
+ */
+const alteration = {
+    up: async (pool) => {
+        await pool.query(sql `
+      create table cimd_grant_organizations (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        grant_id varchar(128) not null,
+        grant_model_name varchar(64) not null default 'Grant',
+        organization_id varchar(21) not null,
+        user_id varchar(21) not null,
+        primary key (tenant_id, grant_id, organization_id),
+        constraint cimd_grant_organizations__grant_model_name
+          check (grant_model_name = 'Grant'),
+        foreign key (tenant_id, grant_model_name, grant_id)
+          references oidc_model_instances (tenant_id, model_name, id)
+          on update cascade on delete cascade,
+        foreign key (tenant_id, organization_id, user_id)
+          references organization_user_relations (tenant_id, organization_id, user_id)
+          on update cascade on delete cascade
+      );
+    `);
+        /**
+         * Backs the membership FK's cascade lookup; the PK leaves `organization_id` outside its
+         * usable prefix. The table is created empty in this transaction, so a plain (non-concurrent)
+         * index build is free.
+         */
+        await pool.query(sql `
+      create index cimd_grant_organizations__organization_id_user_id
+        on cimd_grant_organizations (tenant_id, organization_id, user_id);
+    `);
+        await applyTableRls(pool, 'cimd_grant_organizations');
+    },
+    down: async (pool) => {
+        await dropTableRls(pool, 'cimd_grant_organizations');
+        await pool.query(sql `
+      drop table cimd_grant_organizations;
+    `);
+    },
+};
+export default alteration;

package/alterations-js/1.43.0-1786333495-add-trusted-devices.js

@@ -0,0 +1,50 @@
+import { sql } from '@silverhand/slonik';
+import { applyTableRls, dropTableRls } from './utils/1704934999-tables.js';
+const alteration = {
+    up: async (pool) => {
+        await pool.query(sql `
+      create table trusted_devices (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        id varchar(21) not null,
+        user_id varchar(12) not null
+          references users (id) on update cascade on delete cascade,
+        secret_hash bytea not null,
+        user_agent text,
+        ip text,
+        country varchar(16),
+        city text,
+        created_at timestamptz not null default(now()),
+        last_used_at timestamptz not null default(now()),
+        expires_at timestamptz not null,
+        primary key (id)
+      );
+
+      create index trusted_devices__tenant_user_expires_at
+        on trusted_devices (tenant_id, user_id, expires_at);
+
+      create index trusted_devices__tenant_expires_at
+        on trusted_devices (tenant_id, expires_at);
+
+      alter table sign_in_experiences
+        add column trusted_device jsonb not null default '{}'::jsonb;
+
+      alter table organizations
+        add column is_trusted_device_allowed boolean not null default true;
+    `);
+        await applyTableRls(pool, 'trusted_devices');
+    },
+    down: async (pool) => {
+        await dropTableRls(pool, 'trusted_devices');
+        await pool.query(sql `
+      drop table trusted_devices;
+
+      alter table sign_in_experiences
+        drop column trusted_device;
+
+      alter table organizations
+        drop column is_trusted_device_allowed;
+    `);
+    },
+};
+export default alteration;

package/alterations-js/1.43.0-1786373004-tighten-cimd-grant-organizations-pkey.js

@@ -0,0 +1,24 @@
+import { sql } from '@silverhand/slonik';
+/**
+ * Tighten the `cimd_grant_organizations` primary key to `(tenant_id, grant_id)` so the schema
+ * itself enforces the at-most-one-organization-per-grant invariant that token issuance relies on,
+ * instead of leaving it to the consent flow's composition. The table is dev-feature-gated and
+ * empty in every environment, so swapping the constraint needs no data migration.
+ */
+const alteration = {
+    up: async (pool) => {
+        await pool.query(sql `
+      alter table cimd_grant_organizations
+        drop constraint cimd_grant_organizations_pkey,
+        add primary key (tenant_id, grant_id);
+    `);
+    },
+    down: async (pool) => {
+        await pool.query(sql `
+      alter table cimd_grant_organizations
+        drop constraint cimd_grant_organizations_pkey,
+        add primary key (tenant_id, grant_id, organization_id);
+    `);
+    },
+};
+export default alteration;

package/alterations-js/1.43.0-1786414712-add-service-logs-email-indexes.js

@@ -0,0 +1,30 @@
+import { sql } from '@silverhand/slonik';
+const alteration = {
+    beforeUp: async (pool) => {
+        await pool.query(sql `
+      create index concurrently service_logs__email__tenant_id__created_at__id
+        on service_logs (tenant_id, created_at desc, id desc)
+        where type in ('sendEmail', 'sendEmailFailed');
+    `);
+        await pool.query(sql `
+      create index concurrently service_logs__email__tenant_id__recipient__created_at__id
+        on service_logs (tenant_id, lower(payload->'data'->>'to'), created_at desc, id desc)
+        where type in ('sendEmail', 'sendEmailFailed');
+    `);
+    },
+    up: async () => {
+        /** 'concurrently' cannot be used inside a transaction, so this up is intentionally left empty. */
+    },
+    beforeDown: async (pool) => {
+        await pool.query(sql `
+      drop index concurrently service_logs__email__tenant_id__recipient__created_at__id;
+    `);
+        await pool.query(sql `
+      drop index concurrently service_logs__email__tenant_id__created_at__id;
+    `);
+    },
+    down: async () => {
+        /** 'concurrently' cannot be used inside a transaction, so this down is intentionally left empty. */
+    },
+};
+export default alteration;

package/alterations-js/1.43.0-1786431364-add-cimd-grant-client-snapshots-table.js

@@ -0,0 +1,38 @@
+import { sql } from '@silverhand/slonik';
+import { applyTableRls, dropTableRls } from './utils/1704934999-tables.js';
+/**
+ * Add the per-grant client display snapshot table for client ID metadata document (CIMD) clients.
+ * CIMD clients are unregistered URL identities without an `applications` row, and an unvetted
+ * client can rewrite its hosted document at any time — so the grant list renders the snapshot
+ * captured at consent instead of refetching the document. Rows cascade away with the Grant row.
+ */
+const alteration = {
+    up: async (pool) => {
+        await pool.query(sql `
+      create table cimd_grant_client_snapshots (
+        tenant_id varchar(21) not null
+          references tenants (id) on update cascade on delete cascade,
+        grant_id varchar(128) not null,
+        grant_model_name varchar(64) not null default 'Grant',
+        client_id varchar(2048) not null,
+        name varchar(256),
+        logo_uri varchar(2048),
+        created_at timestamptz not null default(now()),
+        primary key (tenant_id, grant_id),
+        constraint cimd_grant_client_snapshots__grant_model_name
+          check (grant_model_name = 'Grant'),
+        foreign key (tenant_id, grant_model_name, grant_id)
+          references oidc_model_instances (tenant_id, model_name, id)
+          on update cascade on delete cascade
+      );
+    `);
+        await applyTableRls(pool, 'cimd_grant_client_snapshots');
+    },
+    down: async (pool) => {
+        await dropTableRls(pool, 'cimd_grant_client_snapshots');
+        await pool.query(sql `
+      drop table cimd_grant_client_snapshots;
+    `);
+    },
+};
+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

@@ -10,3 +10,5 @@ export * from './message-rate-limit.js';
 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

@@ -10,3 +10,5 @@ export * from './message-rate-limit.js';
 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 {};