handsontable 18.0.0 → 18.1.0-rc11

package/utils/entitlementLicenseKey/encoding.mjs

@@ -0,0 +1,172 @@
+/* eslint-disable no-bitwise */ /**
+ * The base64 alphabet.
+ *
+ * @type {string}
+ */ const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/**
+ * Encodes the string as UTF-8 bytes. The plain implementation is used on purpose.
+ * It does not depend on `TextEncoder` or `Buffer`, so the same code works in
+ * Node.js and in every browser, including plain http:// pages.
+ *
+ * @param {string} string The string to encode.
+ * @returns {number[]}
+ */ export function stringToUtf8Bytes(string) {
+    const bytes = [];
+    for(let i = 0; i < string.length; i += 1){
+        let codePoint = string.charCodeAt(i);
+        // Combine a surrogate pair into a single code point.
+        if (codePoint >= 0xd800 && codePoint <= 0xdbff && i + 1 < string.length) {
+            const lowSurrogate = string.charCodeAt(i + 1);
+            if (lowSurrogate >= 0xdc00 && lowSurrogate <= 0xdfff) {
+                codePoint = (codePoint - 0xd800) * 0x400 + (lowSurrogate - 0xdc00) + 0x10000;
+                i += 1;
+            }
+        }
+        if (codePoint < 0x80) {
+            bytes.push(codePoint);
+        } else if (codePoint < 0x800) {
+            bytes.push(0xc0 | codePoint >> 6, 0x80 | codePoint & 0x3f);
+        } else if (codePoint < 0x10000) {
+            bytes.push(0xe0 | codePoint >> 12, 0x80 | codePoint >> 6 & 0x3f, 0x80 | codePoint & 0x3f);
+        } else {
+            bytes.push(0xf0 | codePoint >> 18, 0x80 | codePoint >> 12 & 0x3f, 0x80 | codePoint >> 6 & 0x3f, 0x80 | codePoint & 0x3f);
+        }
+    }
+    return bytes;
+}
+/**
+ * Decodes UTF-8 bytes back into a string.
+ *
+ * @param {number[]} bytes The bytes to decode.
+ * @returns {string}
+ */ export function utf8BytesToString(bytes) {
+    let string = '';
+    let i = 0;
+    while(i < bytes.length){
+        const byte = bytes[i];
+        let codePoint;
+        if (byte < 0x80) {
+            codePoint = byte;
+            i += 1;
+        } else if (byte < 0xe0) {
+            codePoint = (byte & 0x1f) << 6 | bytes[i + 1] & 0x3f;
+            i += 2;
+        } else if (byte < 0xf0) {
+            codePoint = (byte & 0x0f) << 12 | (bytes[i + 1] & 0x3f) << 6 | bytes[i + 2] & 0x3f;
+            i += 3;
+        } else {
+            codePoint = (byte & 0x07) << 18 | (bytes[i + 1] & 0x3f) << 12 | (bytes[i + 2] & 0x3f) << 6 | bytes[i + 3] & 0x3f;
+            i += 4;
+        }
+        if (codePoint >= 0x10000) {
+            // Split the code point back into a surrogate pair.
+            codePoint -= 0x10000;
+            string += String.fromCharCode(0xd800 + (codePoint >> 10), 0xdc00 + (codePoint & 0x3ff));
+        } else {
+            string += String.fromCharCode(codePoint);
+        }
+    }
+    return string;
+}
+/**
+ * Encodes the bytes as a base64 string (standard alphabet, with padding).
+ *
+ * @param {number[]} bytes The bytes to encode.
+ * @returns {string}
+ */ export function bytesToBase64(bytes) {
+    let base64 = '';
+    for(let i = 0; i < bytes.length; i += 3){
+        const byte1 = bytes[i];
+        const byte2 = bytes[i + 1];
+        const byte3 = bytes[i + 2];
+        base64 += BASE64_ALPHABET.charAt(byte1 >> 2);
+        base64 += BASE64_ALPHABET.charAt((byte1 & 0x03) << 4 | (byte2 === undefined ? 0 : byte2 >> 4));
+        base64 += byte2 === undefined ? '=' : BASE64_ALPHABET.charAt((byte2 & 0x0f) << 2 | (byte3 === undefined ? 0 : byte3 >> 6));
+        base64 += byte3 === undefined ? '=' : BASE64_ALPHABET.charAt(byte3 & 0x3f);
+    }
+    return base64;
+}
+/**
+ * Decodes a base64 string (standard or URL-safe alphabet, padding optional)
+ * back into bytes. Returns `null` when the string is not valid base64.
+ *
+ * @param {string} base64 The base64 string to decode.
+ * @returns {number[]|null}
+ */ export function base64ToBytes(base64) {
+    const normalized = `${base64}`.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '');
+    if (!/^[A-Za-z0-9+/]*$/.test(normalized) || normalized.length % 4 === 1) {
+        return null;
+    }
+    const bytes = [];
+    for(let i = 0; i < normalized.length; i += 4){
+        const chunk = [
+            0,
+            1,
+            2,
+            3
+        ].map((offset)=>{
+            const char = normalized.charAt(i + offset);
+            // `indexOf('')` would return 0, so the missing characters of the last
+            // chunk have to be mapped to -1 explicitly.
+            return char === '' ? -1 : BASE64_ALPHABET.indexOf(char);
+        });
+        bytes.push(chunk[0] << 2 | chunk[1] >> 4);
+        if (chunk[2] !== -1) {
+            bytes.push((chunk[1] & 0x0f) << 4 | chunk[2] >> 2);
+        }
+        if (chunk[3] !== -1) {
+            bytes.push((chunk[2] & 0x03) << 6 | chunk[3]);
+        }
+    }
+    return bytes;
+}
+/**
+ * Encodes the string as a URL-safe base64 string without padding (the same
+ * format as the JWT payload segment).
+ *
+ * @param {string} string The string to encode.
+ * @returns {string}
+ */ export function stringToBase64Url(string) {
+    return bytesToBase64(stringToUtf8Bytes(string)).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * Decodes a base64 (standard or URL-safe) string back into a string.
+ * Returns `null` when the input is not valid base64.
+ *
+ * @param {string} base64 The base64 string to decode.
+ * @returns {string|null}
+ */ export function base64ToString(base64) {
+    const bytes = base64ToBytes(base64);
+    return bytes === null ? null : utf8BytesToString(bytes);
+}
+/**
+ * Parses a date in the "YYYY-MM-DD" format into the epoch milliseconds of its
+ * UTC midnight. Returns `null` when the date is malformed or does not exist in
+ * the calendar (for example "2027-02-30"). Unlike the generator side, the
+ * reader never throws on a bad date - a broken payload simply makes the key
+ * unreadable.
+ *
+ * @param {string} isoDate The date to parse.
+ * @returns {number|null}
+ */ export function parseIsoDateToTimestamp(isoDate) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(`${isoDate}`);
+    if (match === null) {
+        return null;
+    }
+    const year = parseInt(match[1], 10);
+    const month = parseInt(match[2], 10);
+    const day = parseInt(match[3], 10);
+    // Date.UTC maps years 0-99 to 1900-1999, which would make the round-trip
+    // check below report a "not a valid calendar date" lie.
+    if (year < 100) {
+        return null;
+    }
+    const timestamp = Date.UTC(year, month - 1, day);
+    const date = new Date(timestamp);
+    // An impossible date (e.g. "2027-02-30") makes `Date.UTC` roll over to
+    // the next month, so a round-trip comparison catches it.
+    if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+        return null;
+    }
+    return timestamp;
+}

package/utils/entitlementLicenseKey/extractKeyData.d.mts

@@ -0,0 +1 @@
+export * from './extractKeyData.js';

package/utils/entitlementLicenseKey/extractKeyData.d.ts

@@ -0,0 +1,47 @@
+import type { EntitlementKeyData, ProductEntitlement } from './types';
+/**
+ * Adds an own, ordinary property.
+ *
+ * Both the product names and the field names of a product entry come from
+ * JSON, so "__proto__" is a name an attacker can put in a key. A plain
+ * assignment would go through the `Object.prototype` setter: the value would
+ * vanish from `Object.keys` while still resolving through the chain. Exported
+ * because every payload-keyed write in this module must use it - `grants.ts`
+ * re-keys the same product names.
+ *
+ * @param {object} target The object to add the property to.
+ * @param {string} key The property name.
+ * @param {*} value The property value.
+ * @returns {void}
+ */
+export declare function defineOwn(target: object, key: string, value: unknown): void;
+/**
+ * Extracts the machine-readable data from an entitlement license key.
+ *
+ * The checksum is verified first, so the returned data is guaranteed to belong
+ * to an intact block. A malformed or tampered key reads as `null` - reporting
+ * an invalid key is the caller's job, not this function's.
+ *
+ * Only the bracketed block matters. The prose in front of it is neither parsed
+ * nor covered by the checksum, so the caller may pass the whole key or just the
+ * `[...]` block, and rewrapped or re-pasted prose still validates. The block
+ * itself has to be intact: its alphabet has no whitespace, so a newline inside
+ * it makes the key unreadable, exactly as it does for the key generator.
+ *
+ * Unknown products, capability tokens and flags are all tolerated, so nothing
+ * about reading a key depends on the commercial vocabulary.
+ *
+ * @param {string} licenseKey The license key to extract the data from.
+ * @returns {EntitlementKeyData|null}
+ */
+export declare function extractEntitlementKeyData(licenseKey: string): EntitlementKeyData | null;
+/**
+ * Returns the entitlement of one product, but only when it is present as an own
+ * property. Used by the lifecycle and grants layers to read one product without
+ * trusting the prototype chain.
+ *
+ * @param {EntitlementKeyData} keyData The verified key data.
+ * @param {string} productName The product to read.
+ * @returns {ProductEntitlement|null}
+ */
+export declare function getProductEntitlement(keyData: EntitlementKeyData, productName: string): ProductEntitlement | null;

package/utils/entitlementLicenseKey/extractKeyData.js

@@ -0,0 +1,213 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get defineOwn () {
+        return defineOwn;
+    },
+    get extractEntitlementKeyData () {
+        return extractEntitlementKeyData;
+    },
+    get getProductEntitlement () {
+        return getProductEntitlement;
+    }
+});
+const _constants = require("./constants");
+const _sha512 = require("./sha512");
+const _encoding = require("./encoding");
+/**
+ * The alphabet of the encoded payload - URL-safe base64 without padding. The
+ * checksum (lowercase hex) is a subset of it, which is what lets the two be
+ * split by a fixed length from the right.
+ *
+ * @type {RegExp}
+ */ const ENCODED_PAYLOAD = /^[A-Za-z0-9\-_]+$/;
+const CHECKSUM = /^[0-9a-f]+$/;
+/**
+ * Reports own-property presence without trusting a payload's inherited or
+ * overridden `hasOwnProperty`.
+ *
+ * @param {object} object The object to inspect.
+ * @param {string} key The property name to look up.
+ * @returns {boolean}
+ */ function hasOwn(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+/**
+ * Narrows an unknown value to a plain (non-null, non-array) object.
+ *
+ * @param {*} value The value to check.
+ * @returns {boolean}
+ */ function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Returns `true` when the value is a non-negative integer. `Number.isFinite`
+ * also rejects `Infinity` (JSON `1e999` parses to it), which would otherwise
+ * turn a window size into a non-finite date downstream.
+ *
+ * @param {*} value The value to check.
+ * @returns {boolean}
+ */ function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isFinite(value) && Math.floor(value) === value && value >= 0;
+}
+/**
+ * Returns `true` when the value is an array of strings.
+ *
+ * @param {*} value The value to check.
+ * @returns {boolean}
+ */ function isStringArray(value) {
+    return Array.isArray(value) && value.every((item)=>typeof item === 'string');
+}
+function defineOwn(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true
+    });
+}
+/**
+ * Verifies and normalizes one product entry.
+ *
+ * Strict about SHAPE: exactly one of the two dates, a real calendar date, and
+ * the two window sizes. A key that gets this wrong is malformed, not merely
+ * unknown, and reading it would mean guessing what was licensed.
+ *
+ * Lenient about VOCABULARY: an unrecognized capability token, an unrecognized
+ * flag and an unrecognized extra field are all kept and ignored. Without that
+ * leniency every token added on the issuing side would break every build
+ * already deployed in the field.
+ *
+ * Returns `null` when the entry is malformed.
+ *
+ * @param {*} entry The product entry of the payload.
+ * @returns {ProductEntitlement|null}
+ */ function normalizeProductEntry(entry) {
+    if (!isPlainObject(entry)) {
+        return null;
+    }
+    if (!isStringArray(entry.capabilities)) {
+        return null;
+    }
+    const presentDateFields = _constants.DATE_FIELDS.filter((field)=>entry[field] !== undefined);
+    // Exactly one date per product. "Both" and "neither" are each a different
+    // commercial shape that the format cannot express, so neither may be silently
+    // resolved by whichever field the reader happens to look at first.
+    if (presentDateFields.length !== 1) {
+        return null;
+    }
+    if ((0, _encoding.parseIsoDateToTimestamp)(`${entry[presentDateFields[0]]}`) === null) {
+        return null;
+    }
+    if (!isNonNegativeInteger(entry.notice) || !isNonNegativeInteger(entry.grace)) {
+        return null;
+    }
+    if (entry.flags !== undefined && !isStringArray(entry.flags)) {
+        return null;
+    }
+    // Start from everything the entry carries, so a field this version does not
+    // know survives into the result instead of being silently dropped. A field
+    // added to the format later is exactly the case a vendored reader has to
+    // survive, and one that quietly discards it makes the field invisible to the
+    // layers above.
+    const normalized = {};
+    Object.keys(entry).forEach((field)=>defineOwn(normalized, field, entry[field]));
+    defineOwn(normalized, 'capabilities', entry.capabilities.slice());
+    defineOwn(normalized, 'notice', entry.notice);
+    defineOwn(normalized, 'grace', entry.grace);
+    // An absent array and an empty one mean the same thing. Normalizing here
+    // keeps `flags.indexOf('trial')` safe at every call site.
+    defineOwn(normalized, 'flags', entry.flags === undefined ? [] : entry.flags.slice());
+    defineOwn(normalized, presentDateFields[0], entry[presentDateFields[0]]);
+    return normalized;
+}
+/**
+ * Reads and verifies one key. Split out from the memoized public entry point so
+ * the memo can wrap every exit path uniformly.
+ *
+ * @param {string} licenseKey The license key to read.
+ * @returns {EntitlementKeyData|null}
+ */ function readEntitlementKeyData(licenseKey) {
+    // The machine-readable block closes the key. Searching backwards means a
+    // bracket inside the prose cannot shadow it.
+    const blockStart = licenseKey.lastIndexOf('[');
+    if (blockStart === -1) {
+        return null;
+    }
+    const blockEnd = licenseKey.indexOf(']', blockStart);
+    if (blockEnd === -1) {
+        return null;
+    }
+    const content = licenseKey.slice(blockStart + 1, blockEnd);
+    if (content.length <= _constants.CHECKSUM_LENGTH) {
+        return null;
+    }
+    const encodedPayload = content.slice(0, -_constants.CHECKSUM_LENGTH);
+    const checksum = content.slice(-_constants.CHECKSUM_LENGTH);
+    if (!ENCODED_PAYLOAD.test(encodedPayload) || !CHECKSUM.test(checksum)) {
+        return null;
+    }
+    if ((0, _sha512.sha512)((0, _encoding.stringToUtf8Bytes)(encodedPayload)) !== checksum) {
+        return null;
+    }
+    const payloadJson = (0, _encoding.base64ToString)(encodedPayload);
+    if (payloadJson === null) {
+        return null;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(payloadJson);
+    } catch (error) {
+        return null;
+    }
+    if (!isPlainObject(payload) || !isPlainObject(payload.products)) {
+        return null;
+    }
+    const products = {};
+    const entries = payload.products;
+    let malformed = false;
+    Object.keys(entries).forEach((name)=>{
+        const entry = normalizeProductEntry(entries[name]);
+        if (entry === null) {
+            malformed = true;
+            return;
+        }
+        defineOwn(products, name, entry);
+    });
+    if (malformed) {
+        return null;
+    }
+    return {
+        products
+    };
+}
+// The license key is read twice per grid init - the bottom bar
+// (`initLicenseNotification`) and the branding UI (`initLicenseBranding`) each resolve the license
+// state - and reading runs the full SHA-512 + base64 + JSON parse. A one-entry memo on the key makes
+// the second read free. The returned data is treated as read-only by every caller, so sharing one
+// object is safe.
+let memoizedKey = null;
+let memoizedData = null;
+function extractEntitlementKeyData(licenseKey) {
+    const key = `${licenseKey}`;
+    if (key !== memoizedKey) {
+        memoizedKey = key;
+        memoizedData = readEntitlementKeyData(key);
+    }
+    return memoizedData;
+}
+function getProductEntitlement(keyData, productName) {
+    if (!hasOwn(keyData.products, productName)) {
+        return null;
+    }
+    const product = keyData.products[productName];
+    return isPlainObject(product) ? product : null;
+}

package/utils/entitlementLicenseKey/extractKeyData.mjs

@@ -0,0 +1,232 @@
+import { CHECKSUM_LENGTH, DATE_FIELDS } from './constants.mjs';
+import { sha512 } from './sha512.mjs';
+import { base64ToString, stringToUtf8Bytes, parseIsoDateToTimestamp } from './encoding.mjs';
+/**
+ * The alphabet of the encoded payload - URL-safe base64 without padding. The
+ * checksum (lowercase hex) is a subset of it, which is what lets the two be
+ * split by a fixed length from the right.
+ *
+ * @type {RegExp}
+ */ const ENCODED_PAYLOAD = /^[A-Za-z0-9\-_]+$/;
+const CHECKSUM = /^[0-9a-f]+$/;
+/**
+ * Reports own-property presence without trusting a payload's inherited or
+ * overridden `hasOwnProperty`.
+ *
+ * @param {object} object The object to inspect.
+ * @param {string} key The property name to look up.
+ * @returns {boolean}
+ */ function hasOwn(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+/**
+ * Narrows an unknown value to a plain (non-null, non-array) object.
+ *
+ * @param {*} value The value to check.
+ * @returns {boolean}
+ */ function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Returns `true` when the value is a non-negative integer. `Number.isFinite`
+ * also rejects `Infinity` (JSON `1e999` parses to it), which would otherwise
+ * turn a window size into a non-finite date downstream.
+ *
+ * @param {*} value The value to check.
+ * @returns {boolean}
+ */ function isNonNegativeInteger(value) {
+    return typeof value === 'number' && Number.isFinite(value) && Math.floor(value) === value && value >= 0;
+}
+/**
+ * Returns `true` when the value is an array of strings.
+ *
+ * @param {*} value The value to check.
+ * @returns {boolean}
+ */ function isStringArray(value) {
+    return Array.isArray(value) && value.every((item)=>typeof item === 'string');
+}
+/**
+ * Adds an own, ordinary property.
+ *
+ * Both the product names and the field names of a product entry come from
+ * JSON, so "__proto__" is a name an attacker can put in a key. A plain
+ * assignment would go through the `Object.prototype` setter: the value would
+ * vanish from `Object.keys` while still resolving through the chain. Exported
+ * because every payload-keyed write in this module must use it - `grants.ts`
+ * re-keys the same product names.
+ *
+ * @param {object} target The object to add the property to.
+ * @param {string} key The property name.
+ * @param {*} value The property value.
+ * @returns {void}
+ */ export function defineOwn(target, key, value) {
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true
+    });
+}
+/**
+ * Verifies and normalizes one product entry.
+ *
+ * Strict about SHAPE: exactly one of the two dates, a real calendar date, and
+ * the two window sizes. A key that gets this wrong is malformed, not merely
+ * unknown, and reading it would mean guessing what was licensed.
+ *
+ * Lenient about VOCABULARY: an unrecognized capability token, an unrecognized
+ * flag and an unrecognized extra field are all kept and ignored. Without that
+ * leniency every token added on the issuing side would break every build
+ * already deployed in the field.
+ *
+ * Returns `null` when the entry is malformed.
+ *
+ * @param {*} entry The product entry of the payload.
+ * @returns {ProductEntitlement|null}
+ */ function normalizeProductEntry(entry) {
+    if (!isPlainObject(entry)) {
+        return null;
+    }
+    if (!isStringArray(entry.capabilities)) {
+        return null;
+    }
+    const presentDateFields = DATE_FIELDS.filter((field)=>entry[field] !== undefined);
+    // Exactly one date per product. "Both" and "neither" are each a different
+    // commercial shape that the format cannot express, so neither may be silently
+    // resolved by whichever field the reader happens to look at first.
+    if (presentDateFields.length !== 1) {
+        return null;
+    }
+    if (parseIsoDateToTimestamp(`${entry[presentDateFields[0]]}`) === null) {
+        return null;
+    }
+    if (!isNonNegativeInteger(entry.notice) || !isNonNegativeInteger(entry.grace)) {
+        return null;
+    }
+    if (entry.flags !== undefined && !isStringArray(entry.flags)) {
+        return null;
+    }
+    // Start from everything the entry carries, so a field this version does not
+    // know survives into the result instead of being silently dropped. A field
+    // added to the format later is exactly the case a vendored reader has to
+    // survive, and one that quietly discards it makes the field invisible to the
+    // layers above.
+    const normalized = {};
+    Object.keys(entry).forEach((field)=>defineOwn(normalized, field, entry[field]));
+    defineOwn(normalized, 'capabilities', entry.capabilities.slice());
+    defineOwn(normalized, 'notice', entry.notice);
+    defineOwn(normalized, 'grace', entry.grace);
+    // An absent array and an empty one mean the same thing. Normalizing here
+    // keeps `flags.indexOf('trial')` safe at every call site.
+    defineOwn(normalized, 'flags', entry.flags === undefined ? [] : entry.flags.slice());
+    defineOwn(normalized, presentDateFields[0], entry[presentDateFields[0]]);
+    return normalized;
+}
+/**
+ * Reads and verifies one key. Split out from the memoized public entry point so
+ * the memo can wrap every exit path uniformly.
+ *
+ * @param {string} licenseKey The license key to read.
+ * @returns {EntitlementKeyData|null}
+ */ function readEntitlementKeyData(licenseKey) {
+    // The machine-readable block closes the key. Searching backwards means a
+    // bracket inside the prose cannot shadow it.
+    const blockStart = licenseKey.lastIndexOf('[');
+    if (blockStart === -1) {
+        return null;
+    }
+    const blockEnd = licenseKey.indexOf(']', blockStart);
+    if (blockEnd === -1) {
+        return null;
+    }
+    const content = licenseKey.slice(blockStart + 1, blockEnd);
+    if (content.length <= CHECKSUM_LENGTH) {
+        return null;
+    }
+    const encodedPayload = content.slice(0, -CHECKSUM_LENGTH);
+    const checksum = content.slice(-CHECKSUM_LENGTH);
+    if (!ENCODED_PAYLOAD.test(encodedPayload) || !CHECKSUM.test(checksum)) {
+        return null;
+    }
+    if (sha512(stringToUtf8Bytes(encodedPayload)) !== checksum) {
+        return null;
+    }
+    const payloadJson = base64ToString(encodedPayload);
+    if (payloadJson === null) {
+        return null;
+    }
+    let payload;
+    try {
+        payload = JSON.parse(payloadJson);
+    } catch (error) {
+        return null;
+    }
+    if (!isPlainObject(payload) || !isPlainObject(payload.products)) {
+        return null;
+    }
+    const products = {};
+    const entries = payload.products;
+    let malformed = false;
+    Object.keys(entries).forEach((name)=>{
+        const entry = normalizeProductEntry(entries[name]);
+        if (entry === null) {
+            malformed = true;
+            return;
+        }
+        defineOwn(products, name, entry);
+    });
+    if (malformed) {
+        return null;
+    }
+    return {
+        products
+    };
+}
+// The license key is read twice per grid init - the bottom bar
+// (`initLicenseNotification`) and the branding UI (`initLicenseBranding`) each resolve the license
+// state - and reading runs the full SHA-512 + base64 + JSON parse. A one-entry memo on the key makes
+// the second read free. The returned data is treated as read-only by every caller, so sharing one
+// object is safe.
+let memoizedKey = null;
+let memoizedData = null;
+/**
+ * Extracts the machine-readable data from an entitlement license key.
+ *
+ * The checksum is verified first, so the returned data is guaranteed to belong
+ * to an intact block. A malformed or tampered key reads as `null` - reporting
+ * an invalid key is the caller's job, not this function's.
+ *
+ * Only the bracketed block matters. The prose in front of it is neither parsed
+ * nor covered by the checksum, so the caller may pass the whole key or just the
+ * `[...]` block, and rewrapped or re-pasted prose still validates. The block
+ * itself has to be intact: its alphabet has no whitespace, so a newline inside
+ * it makes the key unreadable, exactly as it does for the key generator.
+ *
+ * Unknown products, capability tokens and flags are all tolerated, so nothing
+ * about reading a key depends on the commercial vocabulary.
+ *
+ * @param {string} licenseKey The license key to extract the data from.
+ * @returns {EntitlementKeyData|null}
+ */ export function extractEntitlementKeyData(licenseKey) {
+    const key = `${licenseKey}`;
+    if (key !== memoizedKey) {
+        memoizedKey = key;
+        memoizedData = readEntitlementKeyData(key);
+    }
+    return memoizedData;
+}
+/**
+ * Returns the entitlement of one product, but only when it is present as an own
+ * property. Used by the lifecycle and grants layers to read one product without
+ * trusting the prototype chain.
+ *
+ * @param {EntitlementKeyData} keyData The verified key data.
+ * @param {string} productName The product to read.
+ * @returns {ProductEntitlement|null}
+ */ export function getProductEntitlement(keyData, productName) {
+    if (!hasOwn(keyData.products, productName)) {
+        return null;
+    }
+    const product = keyData.products[productName];
+    return isPlainObject(product) ? product : null;
+}

package/utils/entitlementLicenseKey/grants.d.mts

@@ -0,0 +1 @@
+export * from './grants.js';