@omnigrid/pro-license 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @omnigrid/pro-license
+
+Offline license verification and demo watermark shared by all OmniGrid Pro plugins.
+
+## Usage
+
+Pass your commercial license key via the global grid options:
+
+```tsx
+<OmniGrid "your_base64_encoded_license_key_here", ... // gridOptions="{{" licenseKey: }}/>

package/dist/baseProPlugin.d.ts

@@ -0,0 +1,41 @@
+import type { GridApi, GridPlugin } from "@omnigrid/core";
+import type { LicenseStatus } from "./types";
+/**
+ * Base class for every Pro plugin. On registration it verifies
+ * `GridOptions.licenseKey` offline; with a missing, invalid or expired key the
+ * plugin keeps working in demo mode and a dismissible watermark is shown.
+ *
+ * @api
+ */
+export declare abstract class BaseProPlugin<T> implements GridPlugin<T> {
+    /** @api Unique, namespaced plugin identifier. */
+    abstract readonly name: string;
+    private readonly publicKey;
+    private releaseWatermark;
+    private status;
+    /**
+     * @param publicKey - Base64url Ed25519 public key. @default PRO_LICENSE_PUBLIC_KEY
+     */
+    protected constructor(publicKey?: string);
+    /**
+     * Verifies the grid's license key and shows the watermark when it is not valid.
+     *
+     * @param licenseKey - Token to verify.
+     * @param api - Grid API used to mount the watermark.
+     * @returns Whether the license is valid.
+     * @api
+     */
+    protected validateLicense(licenseKey: string | undefined, api: GridApi<T>): boolean;
+    /** Last verification result of this plugin instance. @api */
+    getLicenseStatus(): LicenseStatus;
+    /**
+     * Plugin-specific registration, called after license validation.
+     *
+     * @param api - Grid API of the host grid.
+     * @returns Optional cleanup.
+     * @api
+     */
+    protected abstract onRegister(api: GridApi<T>): void | (() => void);
+    /** @api */
+    register(api: GridApi<T>): () => void;
+}

package/dist/baseProPlugin.js

@@ -0,0 +1,50 @@
+import { PRO_LICENSE_PUBLIC_KEY } from "./publicKey";
+import { verifyToken } from "./verify";
+import { mountWatermark } from "./watermark";
+/**
+ * Base class for every Pro plugin. On registration it verifies
+ * `GridOptions.licenseKey` offline; with a missing, invalid or expired key the
+ * plugin keeps working in demo mode and a dismissible watermark is shown.
+ *
+ * @api
+ */
+export class BaseProPlugin {
+    /**
+     * @param publicKey - Base64url Ed25519 public key. @default PRO_LICENSE_PUBLIC_KEY
+     */
+    constructor(publicKey = PRO_LICENSE_PUBLIC_KEY) {
+        this.releaseWatermark = null;
+        this.status = { isValid: false, reason: "missing" };
+        this.publicKey = publicKey;
+    }
+    /**
+     * Verifies the grid's license key and shows the watermark when it is not valid.
+     *
+     * @param licenseKey - Token to verify.
+     * @param api - Grid API used to mount the watermark.
+     * @returns Whether the license is valid.
+     * @api
+     */
+    validateLicense(licenseKey, api) {
+        this.status = verifyToken(licenseKey, new Date(), this.publicKey);
+        if (!this.status.isValid) {
+            this.releaseWatermark = mountWatermark(api.slots, this.status.reason)?.unmount ?? null;
+        }
+        return this.status.isValid;
+    }
+    /** Last verification result of this plugin instance. @api */
+    getLicenseStatus() {
+        return this.status;
+    }
+    /** @api */
+    register(api) {
+        this.validateLicense(api.getLicenseKey(), api);
+        const cleanup = this.onRegister(api);
+        return () => {
+            if (typeof cleanup === "function")
+                cleanup();
+            this.releaseWatermark?.();
+            this.releaseWatermark = null;
+        };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { BaseProPlugin } from "./baseProPlugin";
+export { PRO_LICENSE_PUBLIC_KEY } from "./publicKey";
+export type { LicenseInvalidReason, LicenseStatus, ProLicensePayload } from "./types";
+export { verifyToken } from "./verify";
+export { createWatermarkContent, getWatermarkMessage, mountWatermark, WATERMARK_DISMISSED_KEY } from "./watermark";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { BaseProPlugin } from "./baseProPlugin";
+export { PRO_LICENSE_PUBLIC_KEY } from "./publicKey";
+export { verifyToken } from "./verify";
+export { createWatermarkContent, getWatermarkMessage, mountWatermark, WATERMARK_DISMISSED_KEY } from "./watermark";

package/dist/publicKey.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Ed25519 public key (32 bytes, base64url) used to verify license signatures.
+ * Only the public half ships in the package; the private signing key lives
+ * exclusively on the license-issuing side.
+ *
+ * @api
+ */
+export declare const PRO_LICENSE_PUBLIC_KEY: string;

package/dist/publicKey.js

@@ -0,0 +1,8 @@
+/**
+ * Ed25519 public key (32 bytes, base64url) used to verify license signatures.
+ * Only the public half ships in the package; the private signing key lives
+ * exclusively on the license-issuing side.
+ *
+ * @api
+ */
+export const PRO_LICENSE_PUBLIC_KEY = "nXp9oSe1vI5CRLRcd3E7H-27VX74uST77OEPj0iGmCU";

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Decoded license token payload. The Ed25519 signature is carried next to the
+ * payload in the token, not inside it.
+ *
+ * @api
+ */
+export interface ProLicensePayload {
+    /** Organization or individual the license is issued to. */
+    owner: string;
+    /** Contact email of the licensee. */
+    email: string;
+    /** ISO-8601 date the license was issued. */
+    issuedAt: string;
+    /** ISO-8601 date the license expires, or `null` for perpetual. */
+    expiresAt: string | null;
+    /** Licensed features, e.g. `["pro-all"]`. */
+    features?: string[];
+}
+/**
+ * Reason a license is not valid.
+ *
+ * @api
+ */
+export type LicenseInvalidReason = "missing" | "malformed" | "bad-signature" | "expired";
+/**
+ * Result of verifying a license token.
+ *
+ * @api
+ */
+export interface LicenseStatus {
+    /** Whether the token is cryptographically valid and not expired. */
+    isValid: boolean;
+    /** Machine-readable cause when `isValid` is false. */
+    reason?: LicenseInvalidReason;
+    /** Decoded payload when the token structure is well-formed. */
+    payload?: ProLicensePayload;
+}

package/dist/types.js

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

package/dist/verify.d.ts

@@ -0,0 +1,15 @@
+import type { LicenseStatus } from "./types";
+/**
+ * Verifies a license token entirely offline (no network access): checks the
+ * Ed25519 signature against the embedded public key and the expiry date.
+ *
+ * Token format: `base64url(payload JSON).base64url(signature)`, where the
+ * signature covers the ASCII bytes of the first segment.
+ *
+ * @param licenseKey - Token from `GridOptions.licenseKey`.
+ * @param now - Current time. @default new Date()
+ * @param publicKey - Base64url Ed25519 public key. @default PRO_LICENSE_PUBLIC_KEY
+ * @returns License status; never throws.
+ * @api
+ */
+export declare function verifyToken(licenseKey?: string, now?: Date, publicKey?: string): LicenseStatus;

package/dist/verify.js

@@ -0,0 +1,80 @@
+import { ed25519 } from "@noble/curves/ed25519";
+import { PRO_LICENSE_PUBLIC_KEY } from "./publicKey";
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DATE_ONLY_LENGTH = 10;
+function base64UrlToBytes(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}
+function isPayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.owner === "string" &&
+        typeof candidate.email === "string" &&
+        typeof candidate.issuedAt === "string" &&
+        (candidate.expiresAt === null || typeof candidate.expiresAt === "string") &&
+        (candidate.features === undefined || Array.isArray(candidate.features)));
+}
+/** A date-only expiry (`YYYY-MM-DD`) stays valid through the end of that UTC day. */
+function isExpired(expiresAt, now) {
+    const parsed = Date.parse(expiresAt);
+    if (Number.isNaN(parsed))
+        return true;
+    const limit = expiresAt.length === DATE_ONLY_LENGTH ? parsed + DAY_MS : parsed;
+    return now.getTime() >= limit;
+}
+/**
+ * Verifies a license token entirely offline (no network access): checks the
+ * Ed25519 signature against the embedded public key and the expiry date.
+ *
+ * Token format: `base64url(payload JSON).base64url(signature)`, where the
+ * signature covers the ASCII bytes of the first segment.
+ *
+ * @param licenseKey - Token from `GridOptions.licenseKey`.
+ * @param now - Current time. @default new Date()
+ * @param publicKey - Base64url Ed25519 public key. @default PRO_LICENSE_PUBLIC_KEY
+ * @returns License status; never throws.
+ * @api
+ */
+export function verifyToken(licenseKey, now = new Date(), publicKey = PRO_LICENSE_PUBLIC_KEY) {
+    if (typeof licenseKey !== "string" || licenseKey.trim() === "") {
+        return { isValid: false, reason: "missing" };
+    }
+    const segments = licenseKey.trim().split(".");
+    if (segments.length !== 2 || segments[0] === "" || segments[1] === "") {
+        return { isValid: false, reason: "malformed" };
+    }
+    let payload;
+    let signature;
+    try {
+        payload = JSON.parse(new TextDecoder().decode(base64UrlToBytes(segments[0])));
+        signature = base64UrlToBytes(segments[1]);
+    }
+    catch {
+        return { isValid: false, reason: "malformed" };
+    }
+    if (!isPayload(payload)) {
+        return { isValid: false, reason: "malformed" };
+    }
+    let signatureValid;
+    try {
+        signatureValid = ed25519.verify(signature, new TextEncoder().encode(segments[0]), base64UrlToBytes(publicKey));
+    }
+    catch {
+        signatureValid = false;
+    }
+    if (!signatureValid) {
+        return { isValid: false, reason: "bad-signature" };
+    }
+    if (payload.expiresAt !== null && isExpired(payload.expiresAt, now)) {
+        return { isValid: false, reason: "expired", payload };
+    }
+    return { isValid: true, payload };
+}

package/dist/watermark.d.ts

@@ -0,0 +1,41 @@
+import type { SlotMount, SlotNodeContent } from "@omnigrid/core";
+import type { LicenseInvalidReason } from "./types";
+/**
+ * `sessionStorage` key remembering that the user closed the watermark.
+ *
+ * @api
+ */
+export declare const WATERMARK_DISMISSED_KEY: string;
+/**
+ * Returns the human-readable watermark text for a license failure.
+ *
+ * @param reason - Why the license is invalid.
+ * @api
+ */
+export declare function getWatermarkMessage(reason?: LicenseInvalidReason): string;
+/**
+ * Builds the declarative demo-mode banner. `onDismiss` fires when the user
+ * clicks the close button.
+ *
+ * @param reason - Why the license is invalid.
+ * @param onDismiss - Called after the dismissal is persisted.
+ * @api
+ */
+export declare function createWatermarkContent<T>(reason: LicenseInvalidReason | undefined, onDismiss: () => void): SlotNodeContent<T>;
+/**
+ * Mounts the watermark into the `bodyTop` slot unless it was dismissed during
+ * the current browser session.
+ *
+ * @param slots - `api.slots` of the host grid.
+ * @param reason - Why the license is invalid.
+ * @returns An idempotent release handle, or `null` when already dismissed.
+ * @api
+ */
+export declare function mountWatermark<T>(slots: {
+    mount(slot: "bodyTop", content: SlotNodeContent<T>, options: {
+        id: string;
+        priority: number;
+    }): SlotMount<T>;
+}, reason: LicenseInvalidReason | undefined): {
+    unmount(): void;
+} | null;

package/dist/watermark.js

@@ -0,0 +1,115 @@
+/** One watermark is shared across all Pro plugins registered on a grid. */
+const activeWatermarks = new WeakMap();
+/**
+ * `sessionStorage` key remembering that the user closed the watermark.
+ *
+ * @api
+ */
+export const WATERMARK_DISMISSED_KEY = "omnigrid-pro-watermark-dismissed";
+const WATERMARK_MESSAGE = "OmniGrid Pro: license expired or not found";
+function readDismissed() {
+    try {
+        return globalThis.sessionStorage?.getItem(WATERMARK_DISMISSED_KEY) === "1";
+    }
+    catch {
+        return false;
+    }
+}
+function writeDismissed() {
+    try {
+        globalThis.sessionStorage?.setItem(WATERMARK_DISMISSED_KEY, "1");
+    }
+    catch {
+        // Storage unavailable (SSR, privacy mode): the banner is hidden for this grid only.
+    }
+}
+/**
+ * Returns the human-readable watermark text for a license failure.
+ *
+ * @param reason - Why the license is invalid.
+ * @api
+ */
+export function getWatermarkMessage(reason) {
+    if (reason === "bad-signature" || reason === "malformed")
+        return "OmniGrid Pro: invalid license key";
+    return WATERMARK_MESSAGE;
+}
+/**
+ * Builds the declarative demo-mode banner. `onDismiss` fires when the user
+ * clicks the close button.
+ *
+ * @param reason - Why the license is invalid.
+ * @param onDismiss - Called after the dismissal is persisted.
+ * @api
+ */
+export function createWatermarkContent(reason, onDismiss) {
+    return {
+        type: "node",
+        tag: "div",
+        attrs: {
+            class: "omnigrid-pro-watermark flex items-center justify-between gap-2 px-3 py-1 text-xs bg-mint text-paper",
+            role: "status",
+            "data-omnigrid-pro-watermark": true,
+            style: "box-sizing:border-box;display:flex;width:100%;align-items:center;justify-content:space-between;pointer-events:auto",
+        },
+        children: [
+            { type: "node", tag: "span", children: [getWatermarkMessage(reason)] },
+            {
+                type: "node",
+                tag: "button",
+                attrs: { class: "cursor-pointer", type: "button", "aria-label": "Dismiss license notice" },
+                on: {
+                    click: (_context) => {
+                        writeDismissed();
+                        onDismiss();
+                    },
+                },
+                children: ["✕"],
+            },
+        ],
+    };
+}
+/**
+ * Mounts the watermark into the `bodyTop` slot unless it was dismissed during
+ * the current browser session.
+ *
+ * @param slots - `api.slots` of the host grid.
+ * @param reason - Why the license is invalid.
+ * @returns An idempotent release handle, or `null` when already dismissed.
+ * @api
+ */
+export function mountWatermark(slots, reason) {
+    if (readDismissed())
+        return null;
+    const key = slots;
+    let watermark = activeWatermarks.get(key);
+    if (!watermark) {
+        let mount = null;
+        watermark = {
+            references: 0,
+            unmount: () => mount?.unmount(),
+        };
+        mount = slots.mount("bodyTop", createWatermarkContent(reason, () => watermark?.unmount()), {
+            id: "omnigrid-pro-watermark",
+            priority: 1000,
+        });
+        activeWatermarks.set(key, watermark);
+    }
+    watermark.references += 1;
+    let released = false;
+    return {
+        unmount: () => {
+            if (released)
+                return;
+            released = true;
+            const current = activeWatermarks.get(key);
+            if (!current)
+                return;
+            current.references -= 1;
+            if (current.references === 0) {
+                current.unmount();
+                activeWatermarks.delete(key);
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,39 @@
-{
-  "name": "@omnigrid/pro-license",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+    "name": "@omnigrid/pro-license",
+    "version": "0.1.1",
+    "description": "Offline license verification and demo watermark for OmniGrid Pro plugins",
+    "keywords": [
+        "omnigrid",
+        "pro",
+        "license"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/KRZK-Apps/omnigrid-pro.git"
+    },
+    "license": "SEE LICENSE IN LICENSE.PRO.md",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "npx tsc -p tsconfig.json",
+        "lint": "npx tsc --noEmit -p tsconfig.json",
+        "test": "vitest run",
+        "generate-keys": "node scripts/generate-keys.mjs",
+        "generate-license": "node scripts/generate-license.mjs",
+        "prepublishOnly": "npm run build"
+    },
+    "dependencies": {
+        "@noble/curves": "^1.9.0",
+        "@omnigrid/core": "^0.1.0"
+    }
+}