@kritzel/engine 0.4.31

package/dist/collection/classes/managers/license.manager.js

@@ -0,0 +1,341 @@
+import { KRITZEL_LICENSE_PUBLIC_KEY, KRITZEL_LICENSE_TOKEN_PREFIX } from "../../constants/license.constants";
+/** Minimum delay (ms) between periodic license re-validations. */
+const MIN_REVALIDATION_DELAY_MS = 30_000;
+/** Maximum delay (ms) between periodic license re-validations. */
+const MAX_REVALIDATION_DELAY_MS = 60_000;
+/**
+ * Manages license validation state for the Kritzel editor.
+ *
+ * The manager is owned per {@link KritzelCore} instance (like the theme and
+ * localization managers) so that multiple editors on the same page validate
+ * independently.
+ *
+ * A license key is an offline Ed25519 signed token of the form
+ * `KRTZL1.<base64url(payload)>.<base64url(signature)>`. The library verifies it
+ * against the embedded {@link KRITZEL_LICENSE_PUBLIC_KEY}; only the owner can
+ * mint tokens, with the matching private key (see scripts/license/).
+ *
+ * Responsibilities:
+ * - Cheaply reject absent/malformed/expired keys synchronously so the watermark
+ *   never flashes off for an obviously invalid key.
+ * - Verify the signature asynchronously via WebCrypto, then drive a rerender if
+ *   the licensed state changed so the watermark is re-asserted on the reactive
+ *   render path.
+ * - Periodically re-check on a randomized interval so the check is harder to
+ *   stub out programmatically than a fixed `setInterval`. Re-checks reuse the
+ *   cached verified token and only re-evaluate expiry, so crypto is not re-run
+ *   on an unchanged key every tick.
+ *
+ * Failure semantics (fail open):
+ * - No key provided -> unlicensed (free tier, watermark shown). The normal
+ *   default, not an error.
+ * - Key present but cleanly invalid (malformed, bad signature, expired) ->
+ *   unlicensed.
+ * - Key present but validation throws an *unexpected* internal error, or the
+ *   runtime lacks Ed25519 support in WebCrypto -> fail open and treat as
+ *   licensed so a library defect or old browser never breaks a paying
+ *   customer's app.
+ */
+export class KritzelLicenseManager {
+    _core;
+    /** The most recently provided license key, re-checked on each periodic tick. */
+    _licenseKey;
+    /** Cached result of the latest validation. */
+    _isLicensed = false;
+    /**
+     * The token whose signature most recently verified successfully. Lets the
+     * periodic re-check skip crypto and only re-evaluate expiry while the key is
+     * unchanged.
+     */
+    _verifiedToken;
+    /**
+     * Monotonic id incremented on every {@link validate} call. An in-flight async
+     * verification only commits its result if its id still matches, so a stale
+     * verification resolving after a newer call can never clobber fresh state.
+     */
+    _validationId = 0;
+    /** Cached imported public key, lazily created on first signature check. */
+    _publicKeyPromise;
+    /** Handle for the self-rescheduling re-validation timer. */
+    _timer = null;
+    /**
+     * Creates a new KritzelLicenseManager instance.
+     * @param core - The KritzelCore instance this manager belongs to
+     */
+    constructor(core) {
+        this._core = core;
+    }
+    /**
+     * Whether the editor is currently considered licensed (watermark hidden).
+     */
+    get isLicensed() {
+        return this._isLicensed;
+    }
+    /**
+     * Validates the given license key.
+     *
+     * Runs a synchronous structural pre-check first: an absent, malformed, or
+     * already-expired key resolves the state immediately (no async work). A
+     * structurally valid key then has its signature verified asynchronously; the
+     * licensed state is committed (and a rerender triggered) only if it changed.
+     *
+     * The return value reflects the state known *synchronously* at call time. The
+     * authoritative result for a structurally valid key arrives shortly after via
+     * the async verification and the reactive rerender.
+     *
+     * @param key - The license key to validate, or undefined to clear the license
+     * @returns The licensed state known synchronously at call time
+     */
+    validate(key) {
+        this._licenseKey = key;
+        const validationId = ++this._validationId;
+        let pre;
+        try {
+            pre = this.preCheck(key);
+        }
+        catch {
+            // Fail open: an unexpected internal error in the cheap pre-check must
+            // never break a paying customer's app.
+            this.commit(true, validationId);
+            return this._isLicensed;
+        }
+        if (pre.status === 'rejected') {
+            this._verifiedToken = undefined;
+            this.commit(false, validationId);
+            return this._isLicensed;
+        }
+        // Structurally valid and unexpired. If we already verified this exact token,
+        // the signature is still good, so license it without re-running crypto.
+        if (this._verifiedToken === key) {
+            this.commit(true, validationId);
+            return this._isLicensed;
+        }
+        // Otherwise verify the signature asynchronously. Leave the current state
+        // untouched until it settles so a forged token cannot even briefly hide the
+        // watermark (default state is unlicensed), and a valid renewal does not flap.
+        this.verifySignature(pre.payloadSegment, pre.signatureSegment)
+            .then(valid => {
+            if (validationId !== this._validationId) {
+                return; // A newer validate() superseded this one.
+            }
+            if (valid) {
+                this._verifiedToken = key;
+                this.commit(true, validationId);
+            }
+            else {
+                this._verifiedToken = undefined;
+                this.commit(false, validationId);
+            }
+        })
+            .catch(() => {
+            if (validationId !== this._validationId) {
+                return;
+            }
+            // Fail open on unexpected crypto errors / missing Ed25519 support.
+            this.commit(true, validationId);
+        });
+        return this._isLicensed;
+    }
+    /**
+     * Starts periodic re-validation on a randomized interval between
+     * {@link MIN_REVALIDATION_DELAY_MS} and {@link MAX_REVALIDATION_DELAY_MS}.
+     *
+     * Uses a self-rescheduling `setTimeout` (a fresh random delay each cycle)
+     * rather than a fixed `setInterval`, making the check fractionally harder to
+     * predict and no-op programmatically. Any existing timer is cleared first so
+     * the method is idempotent.
+     */
+    startPeriodicValidation() {
+        this.stopPeriodicValidation();
+        this.scheduleNextValidation();
+    }
+    /**
+     * Stops periodic re-validation and releases the timer.
+     */
+    stopPeriodicValidation() {
+        if (this._timer !== null) {
+            clearTimeout(this._timer);
+            this._timer = null;
+        }
+    }
+    /**
+     * Cleanup hook called when the editor is torn down.
+     */
+    destroy() {
+        this.stopPeriodicValidation();
+    }
+    /**
+     * Commits a new licensed state, triggering a rerender only when it changed.
+     * The {@link validationId} guard is checked by async callers; synchronous
+     * callers pass the current id.
+     */
+    commit(nextLicensed, validationId) {
+        if (validationId !== this._validationId) {
+            return;
+        }
+        if (nextLicensed !== this._isLicensed) {
+            this._isLicensed = nextLicensed;
+            this._core.rerender();
+        }
+    }
+    /**
+     * Schedules the next re-validation tick at a randomized delay.
+     */
+    scheduleNextValidation() {
+        const delay = this.getRandomRevalidationDelay();
+        this._timer = setTimeout(() => {
+            this.validate(this._licenseKey);
+            this.scheduleNextValidation();
+        }, delay);
+    }
+    /**
+     * Returns a random delay within the configured re-validation window.
+     */
+    getRandomRevalidationDelay() {
+        const span = MAX_REVALIDATION_DELAY_MS - MIN_REVALIDATION_DELAY_MS;
+        return MIN_REVALIDATION_DELAY_MS + Math.floor(Math.random() * (span + 1));
+    }
+    /**
+     * Synchronous structural pre-check of a license key: verifies the format
+     * prefix, three-part structure, JSON payload, and (if present) that the token
+     * has not expired. Does not verify the signature.
+     *
+     * @returns `rejected` for absent/malformed/expired keys, or `pass` with the
+     *   parsed segments and claims for a structurally valid, unexpired token.
+     */
+    preCheck(key) {
+        if (key === undefined || key === null) {
+            return { status: 'rejected' };
+        }
+        const token = key.trim();
+        if (token.length === 0 || !token.startsWith(KRITZEL_LICENSE_TOKEN_PREFIX)) {
+            return { status: 'rejected' };
+        }
+        const body = token.slice(KRITZEL_LICENSE_TOKEN_PREFIX.length);
+        const parts = body.split('.');
+        if (parts.length !== 2 || parts[0].length === 0 || parts[1].length === 0) {
+            return { status: 'rejected' };
+        }
+        const [payloadSegment, signatureSegment] = parts;
+        let claims;
+        try {
+            claims = JSON.parse(this.base64UrlToString(payloadSegment));
+        }
+        catch {
+            return { status: 'rejected' };
+        }
+        if (claims === null || typeof claims !== 'object') {
+            return { status: 'rejected' };
+        }
+        if (typeof claims.exp === 'number' && claims.exp * 1000 <= Date.now()) {
+            return { status: 'rejected' }; // Cleanly expired.
+        }
+        const allowedDomains = this.normalizeAllowedDomains(claims.allowedDomains);
+        if (allowedDomains === null || allowedDomains.length === 0) {
+            return { status: 'rejected' };
+        }
+        const currentHostname = this.getCurrentHostname();
+        if (!currentHostname || !allowedDomains.includes(currentHostname)) {
+            return { status: 'rejected' };
+        }
+        return { status: 'pass', payloadSegment, signatureSegment, claims };
+    }
+    /** Returns the normalized current hostname, or null when unavailable/invalid. */
+    getCurrentHostname() {
+        const hostname = globalThis.location?.hostname;
+        if (typeof hostname !== 'string') {
+            return null;
+        }
+        return this.normalizeDomain(hostname);
+    }
+    /** Normalizes and validates the allowed domains claim. */
+    normalizeAllowedDomains(domains) {
+        if (!Array.isArray(domains)) {
+            return null;
+        }
+        const normalized = new Set();
+        for (const entry of domains) {
+            if (typeof entry !== 'string') {
+                return null;
+            }
+            const domain = this.normalizeDomain(entry);
+            if (!domain) {
+                return null;
+            }
+            normalized.add(domain);
+        }
+        return Array.from(normalized);
+    }
+    /** Normalizes a domain and rejects malformed hostnames. */
+    normalizeDomain(value) {
+        const trimmed = value.trim().toLowerCase();
+        if (trimmed.length === 0) {
+            return null;
+        }
+        const withoutTrailingDot = trimmed.endsWith('.') ? trimmed.slice(0, -1) : trimmed;
+        if (withoutTrailingDot.length === 0) {
+            return null;
+        }
+        try {
+            const parsed = new URL(`https://${withoutTrailingDot}`);
+            const normalizedHostname = parsed.hostname.toLowerCase();
+            if (normalizedHostname !== withoutTrailingDot) {
+                return null;
+            }
+            return normalizedHostname;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Verifies the Ed25519 signature of the token against the embedded public
+     * key. Resolves true/false for a definitive valid/invalid signature.
+     *
+     * Rejects (rather than resolving false) on unexpected crypto failures or when
+     * the runtime lacks Ed25519 support, so the caller fails open.
+     */
+    async verifySignature(payloadSegment, signatureSegment) {
+        const publicKey = await this.getPublicKey();
+        const data = this.utf8Bytes(payloadSegment);
+        const signature = this.base64UrlToBytes(signatureSegment);
+        return crypto.subtle.verify('Ed25519', publicKey, signature, data);
+    }
+    /**
+     * Imports and caches the embedded Ed25519 public key for signature checks.
+     */
+    getPublicKey() {
+        if (!this._publicKeyPromise) {
+            const raw = this.base64UrlToBytes(KRITZEL_LICENSE_PUBLIC_KEY);
+            this._publicKeyPromise = Promise.resolve().then(() => crypto.subtle.importKey('raw', raw, { name: 'Ed25519' }, false, ['verify']));
+            // If import fails (e.g. no Ed25519 support), drop the cache so a later
+            // tick can retry, and let the rejection propagate to fail open.
+            this._publicKeyPromise.catch(() => {
+                this._publicKeyPromise = undefined;
+            });
+        }
+        return this._publicKeyPromise;
+    }
+    /** Decodes a base64url string to its UTF-8 text. */
+    base64UrlToString(value) {
+        return new TextDecoder().decode(this.base64UrlToBytes(value));
+    }
+    /** Decodes a base64url string to raw bytes. */
+    base64UrlToBytes(value) {
+        const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+        const padded = base64.padEnd(base64.length + ((4 - (base64.length % 4)) % 4), '=');
+        const binary = atob(padded);
+        const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
+    }
+    /** Encodes a string to its UTF-8 bytes. */
+    utf8Bytes(value) {
+        const encoded = new TextEncoder().encode(value);
+        const bytes = new Uint8Array(new ArrayBuffer(encoded.length));
+        bytes.set(encoded);
+        return bytes;
+    }
+}

package/dist/collection/classes/managers/localization.manager.js

@@ -0,0 +1,227 @@
+import { LocalizationHelper } from "../../helpers/localization.helper";
+import { EN_LOCALE } from "../../locales/en-locale";
+import { DE_LOCALE } from "../../locales/de-locale";
+import { FR_LOCALE } from "../../locales/fr-locale";
+/** Key used to store the settings object in localStorage. */
+const SETTINGS_STORAGE_KEY = 'kritzel-settings';
+/** Default locale used when no stored preference exists. */
+const DEFAULT_LOCALE = 'en';
+/**
+ * Manages localization state and term resolution across the Kritzel editor.
+ *
+ * The manager is owned per {@link KritzelCore} instance (like the theme manager)
+ * so that multiple editors on the same page can use different languages in
+ * isolation.
+ *
+ * Term resolution follows a deterministic fallback chain for each key:
+ * 1. active locale's custom terms
+ * 2. active locale's built-in terms
+ * 3. fallback locale's custom terms
+ * 4. fallback locale's built-in terms
+ * 5. the key itself (last resort)
+ *
+ * Persistence of the selected locale is handled by the KritzelSettings
+ * component; this manager only reads the stored value.
+ */
+export class KritzelLocalizationManager {
+    _core;
+    _storageKey;
+    /** Built-in locale definitions, keyed by locale code. */
+    _builtinLocales = new Map();
+    /** Consumer-registered locale definitions, keyed by locale code. */
+    _customLocales = new Map();
+    _currentLocale = DEFAULT_LOCALE;
+    _fallbackLocale = DEFAULT_LOCALE;
+    /** Whether the consumer explicitly configured a locale catalog (even an empty one) via `configureLocales`. */
+    _explicitLocales = false;
+    /**
+     * Creates a new KritzelLocalizationManager instance.
+     * Seeds the built-in locales and initializes the current locale from the
+     * settings object in localStorage (or the default locale).
+     *
+     * @param core - The KritzelCore instance this manager belongs to
+     */
+    constructor(core) {
+        this._core = core;
+        this._storageKey = core.editorId ? `${SETTINGS_STORAGE_KEY}-${core.editorId}` : SETTINGS_STORAGE_KEY;
+        this._builtinLocales.set(EN_LOCALE.code, EN_LOCALE);
+        this._builtinLocales.set(DE_LOCALE.code, DE_LOCALE);
+        this._builtinLocales.set(FR_LOCALE.code, FR_LOCALE);
+        this._currentLocale = this.getStoredLocale();
+    }
+    /**
+     * Gets the currently active locale code.
+     */
+    get currentLocale() {
+        return this._currentLocale;
+    }
+    /**
+     * Gets the fallback locale code used when a term is missing from the active locale.
+     */
+    get fallbackLocale() {
+        return this._fallbackLocale;
+    }
+    /**
+     * Sets the fallback locale code used when a term is missing from the active locale.
+     *
+     * @param code - The fallback locale code
+     */
+    setFallbackLocale(code) {
+        this._fallbackLocale = code;
+    }
+    /**
+     * Registers consumer-provided locale definitions. Definitions are merged by
+     * code; registering the same code again replaces the previous definition.
+     * A registered locale may provide a partial set of terms — missing terms are
+     * resolved through the fallback chain.
+     *
+     * @param locales - The locale definitions to register
+     */
+    registerLocales(locales) {
+        for (const locale of locales) {
+            this._customLocales.set(locale.code, locale);
+        }
+    }
+    /**
+     * Declaratively configures the full locale catalog, replacing any previously
+     * configured or registered custom locales. Unlike {@link registerLocales},
+     * this determines which locales are considered "available" (e.g. for a
+     * settings selector): passing `undefined` restores the built-in set
+     * (en/de/fr); passing an array (even empty) makes that array's codes the
+     * exclusive available set, falling back to `en` only if the array is empty.
+     * Built-in term fallback for missing keys is unaffected either way.
+     *
+     * @param locales - The full locale catalog, or `undefined` to use built-ins
+     */
+    configureLocales(locales) {
+        this._customLocales.clear();
+        this._explicitLocales = locales !== undefined;
+        if (locales) {
+            this.registerLocales(locales);
+        }
+    }
+    /**
+     * Resolves the locale code that should actually be activated, falling back
+     * to the first available locale when the requested one isn't available.
+     *
+     * @param requested - The locale code the consumer asked to activate
+     */
+    resolveActiveLocale(requested) {
+        const available = this.getAvailableLocales();
+        return available.includes(requested) ? requested : available[0];
+    }
+    /**
+     * Sets the active locale and triggers a re-render so UI strings update.
+     *
+     * @param code - The locale code to activate
+     */
+    setLocale(code) {
+        this._currentLocale = code;
+        this._core.rerender();
+    }
+    /**
+     * Gets the list of available locale codes. When a locale catalog was
+     * explicitly configured via {@link configureLocales}, only those codes are
+     * returned (or `[DEFAULT_LOCALE]` if the catalog is empty); otherwise the
+     * built-in and registered codes are combined.
+     */
+    getAvailableLocales() {
+        if (this._explicitLocales) {
+            const codes = Array.from(this._customLocales.keys());
+            return codes.length > 0 ? codes : [DEFAULT_LOCALE];
+        }
+        return Array.from(new Set([...this._builtinLocales.keys(), ...this._customLocales.keys()]));
+    }
+    /**
+     * Gets the available locales as `{ code, label }` pairs for use in a selector.
+     * A registered locale's label takes precedence over the built-in label; the
+     * code is used as the label when none is provided.
+     */
+    getAvailableLocaleOptions() {
+        return this.getAvailableLocales().map(code => ({ code, label: this.getLocaleLabel(code) }));
+    }
+    /**
+     * Gets the display label for a locale code, falling back to the code itself.
+     *
+     * @param code - The locale code
+     */
+    getLocaleLabel(code) {
+        return this._customLocales.get(code)?.label ?? this._builtinLocales.get(code)?.label ?? code;
+    }
+    /**
+     * Resolves a term key to its translated string for the active locale and
+     * interpolates any `{placeholder}` tokens.
+     *
+     * @param key - The term key to resolve
+     * @param vars - Optional values for `{placeholder}` interpolation
+     * @returns The translated, interpolated string (or the key if unresolved)
+     *
+     * @example
+     * manager.translate('menu.copy'); // 'Copy'
+     * manager.translate('share.expires', { date: '5/1' }); // 'Expires 5/1'
+     */
+    translate(key, vars) {
+        const resolved = this._customLocales.get(this._currentLocale)?.terms[key] ??
+            this._builtinLocales.get(this._currentLocale)?.terms[key] ??
+            this._customLocales.get(this._fallbackLocale)?.terms[key] ??
+            this._builtinLocales.get(this._fallbackLocale)?.terms[key] ??
+            key;
+        return LocalizationHelper.interpolate(resolved, vars);
+    }
+    /**
+     * Resolves every known term key for the active locale into a flat map.
+     *
+     * The key set is the union of all keys defined across the built-in and
+     * registered locales, so consumer-added keys are included. Each value is
+     * resolved through the same fallback chain as {@link translate} (without
+     * interpolation, since these are shared, variable-free UI labels).
+     *
+     * @returns A map of every term key to its resolved string for the active locale
+     */
+    getAllTerms() {
+        const keys = new Set();
+        for (const locale of [...this._builtinLocales.values(), ...this._customLocales.values()]) {
+            for (const key of Object.keys(locale.terms)) {
+                keys.add(key);
+            }
+        }
+        const result = {};
+        for (const key of keys) {
+            result[key] = this.translate(key);
+        }
+        return result;
+    }
+    /**
+     * Reads the stored locale from the settings object in localStorage using this
+     * instance's namespaced key.
+     *
+     * @returns The stored locale code if valid, or the default locale
+     */
+    getStoredLocale() {
+        if (typeof localStorage === 'undefined') {
+            return DEFAULT_LOCALE;
+        }
+        const stored = localStorage.getItem(this._storageKey);
+        if (!stored) {
+            return DEFAULT_LOCALE;
+        }
+        try {
+            const parsed = JSON.parse(stored);
+            if (typeof parsed?.locale === 'string') {
+                return parsed.locale;
+            }
+        }
+        catch {
+            // Invalid JSON, use default
+        }
+        return DEFAULT_LOCALE;
+    }
+    /**
+     * Cleans up the localization manager state.
+     * Provided for lifecycle parity with other managers.
+     */
+    cleanup() {
+        this._customLocales.clear();
+        this._explicitLocales = false;
+    }
+}