@revealui/core 0.5.6 → 0.7.0

package/dist/license.d.ts

@@ -1,13 +1,57 @@
 /**
  * License validation for RevealUI Pro/Enterprise tiers.
  *
+ * Edge-compatible: uses the Web Crypto API (`crypto.subtle`) and `jose`
+ * exclusively. Safe to import from any runtime (Node, Edge, browser,
+ * Workers). No `node:crypto` or filesystem dependencies.
+ *
  * @dependencies
- * - jose - JWT token verification (Web Crypto API)
+ * - jose - JWT signing/verification (Web Crypto API)
  * - zod - Schema validation for license payloads
  */
 import { z } from 'zod';
 /** Available license tiers */
 export type LicenseTier = 'free' | 'pro' | 'max' | 'enterprise';
+/**
+ * License operating mode — determines how the system behaves when license
+ * checks encounter various failure conditions.
+ *
+ * - active: License is valid and current
+ * - grace: License has an issue but is within a grace period (still allowed)
+ * - read-only: Perpetual support lapsed past grace — reads allowed, writes blocked
+ * - expired: Grace period exhausted — degraded to free tier
+ * - invalid: Signature invalid or tampered — hard fail
+ * - missing: No license configured — free tier
+ */
+export type LicenseMode = 'active' | 'grace' | 'read-only' | 'expired' | 'invalid' | 'missing';
+/** Detailed result from license status check */
+export interface LicenseCheckResult {
+    /** Whether the requested action is allowed */
+    allowed: boolean;
+    /** Current effective tier */
+    tier: LicenseTier;
+    /** Operating mode */
+    mode: LicenseMode;
+    /** Human-readable reason for the current mode */
+    reason?: string;
+    /** Milliseconds remaining in grace period (undefined if not in grace) */
+    graceRemainingMs?: number;
+    /** Whether writes should be blocked (read-only mode for lapsed perpetual) */
+    readOnly: boolean;
+}
+/** Grace period configuration (in days). Overridable via env for testing. */
+export interface GracePeriodConfig {
+    /** Days after subscription expiry before degrading to free (default: 3) */
+    subscriptionDays: number;
+    /** Days after perpetual support lapse before read-only mode (default: 30) */
+    perpetualDays: number;
+    /** Days of cached-license grace when infra is unreachable (default: 7) */
+    infraDays: number;
+}
+/**
+ * Configure grace period durations. Useful for testing.
+ */
+export declare function configureGracePeriods(overrides: Partial<GracePeriodConfig>): void;
 /** Decoded license payload schema */
 declare const licensePayloadSchema: z.ZodObject<{
     tier: z.ZodEnum<{
@@ -16,6 +60,7 @@ declare const licensePayloadSchema: z.ZodObject<{
         enterprise: "enterprise";
     }>;
     customerId: z.ZodString;
+    jti: z.ZodString;
     domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
     maxSites: z.ZodOptional<z.ZodNumber>;
     maxUsers: z.ZodOptional<z.ZodNumber>;
@@ -26,9 +71,30 @@ declare const licensePayloadSchema: z.ZodObject<{
 export type LicensePayload = z.infer<typeof licensePayloadSchema>;
 /** License cache TTL configuration */
 export interface LicenseCacheConfig {
-    /** Cache TTL in milliseconds (default: 24 hours) */
+    /** Cache TTL in milliseconds (default: 15 seconds) */
     ttlMs: number;
 }
+/**
+ * Hard cap on cache TTL. Any env override exceeding this is clamped + warned.
+ * Revoked licenses must not stay cached longer than this, regardless of
+ * operator misconfiguration. 15 minutes balances revocation responsiveness
+ * against DB load for high-traffic deployments.
+ *
+ * Tracked by MASTER_PLAN §CR-8 CR8-P1-05.
+ */
+export declare const MAX_LICENSE_CACHE_TTL_MS: number;
+/**
+ * Parse and validate the `LICENSE_CACHE_TTL_MS` env value.
+ *
+ * Rules:
+ * - Unset / non-numeric / non-positive → `DEFAULT_TTL_MS` (15s)
+ * - Above `MAX_LICENSE_CACHE_TTL_MS` → clamped to cap, warning emitted
+ * - Otherwise → parsed value
+ *
+ * Exported for unit testing. Production code uses the module-load-time
+ * evaluation in `DEFAULT_CACHE_CONFIG` below.
+ */
+export declare function parseLicenseCacheTtlEnv(envValue: string | undefined): number;
 /**
  * Configure the license cache TTL.
  * Useful for tests (short TTL) or deployments needing faster revocation detection.
@@ -37,13 +103,26 @@ export declare function configureLicenseCache(overrides: Partial<LicenseCacheCon
 /**
  * Computes a deterministic Key ID (kid) from a public key PEM string.
  * Returns the first 8 characters of the SHA-256 hex digest of the PEM.
+ *
+ * Async because it uses `crypto.subtle.digest` for full edge compatibility.
  */
-export declare function computeKeyId(publicKeyPem: string): string;
+export declare function computeKeyId(publicKeyPem: string): Promise<string>;
 /**
  * Validates a license key JWT and returns the decoded payload.
  * Returns null if the key is invalid, expired, or missing.
+ *
+ * Phase 1 audit B-2: when `expectedCustomerId` is supplied, the JWT's
+ * `customerId` claim must match exactly — otherwise the token is rejected
+ * even when the signature + iss + aud + exp are all valid. This binds a
+ * license to its purchaser. Forge mode uses this against the env-configured
+ * `REVEALUI_LICENSED_CUSTOMER_ID`. Hosted mode (where the deployment IS the
+ * customer) leaves it undefined.
+ *
+ * Note: `nbf` and `exp` are enforced automatically by jose.jwtVerify against
+ * `currentDate` (defaults to now). `iss` and `aud` are enforced via the
+ * options below. Signature is enforced via the public key.
  */
-export declare function validateLicenseKey(licenseKey: string, publicKey: string): Promise<LicensePayload | null>;
+export declare function validateLicenseKey(licenseKey: string, publicKey: string, expectedCustomerId?: string): Promise<LicensePayload | null>;
 /**
  * Initialize the license system. Call once at application startup.
  * Reads REVEALUI_LICENSE_KEY and REVEALUI_LICENSE_PUBLIC_KEY from environment.
@@ -63,8 +142,24 @@ export declare function getLicensePayload(): LicensePayload | null;
 /**
  * Checks whether the current license is at least the given tier.
  * Also validates that the license has not expired (checks JWT exp claim).
+ *
+ * Subscription grace: if the JWT has expired but is within the configured
+ * grace period (default 3 days), access is still allowed. Use
+ * `getLicenseStatus()` to check whether the license is in grace.
  */
 export declare function isLicensed(requiredTier: LicenseTier): boolean;
+/**
+ * Returns the full license status including mode, grace state, and read-only flag.
+ *
+ * Use this for UI decisions (banners, warnings) and API response headers.
+ * For simple gate checks, `isLicensed()` is sufficient.
+ */
+export declare function getLicenseStatus(requiredTier?: LicenseTier): LicenseCheckResult;
+/**
+ * Returns the configured grace period durations.
+ * Useful for API response headers and customer-facing documentation.
+ */
+export declare function getGraceConfig(): Readonly<GracePeriodConfig>;
 /**
  * Returns the maximum number of sites allowed by the current license.
  */
@@ -80,17 +175,20 @@ export declare function getMaxUsers(): number;
 export declare function getMaxAgentTasks(): number;
 /**
  * Generates a signed license key JWT.
- * This is a server-only function  -  requires the private key.
+ * Server-only in practice (requires the private key) but edge-compatible —
+ * `jose.importPKCS8` and `SignJWT` both run on Web Crypto.
  *
  * @param payload - License payload (tier, customerId, limits, perpetual flag)
- * @param privateKey - RS256 private key (PEM format)
+ * @param privateKey - Ed25519 private key (PEM format)
  * @param expiresInSeconds - JWT expiration in seconds. Pass null for perpetual
  *   licenses (no exp claim). Defaults to 1 year for subscription licenses.
- * @param publicKey - RS256 public key (PEM format). When provided, a `kid`
+ * @param publicKey - Ed25519 public key (PEM format). When provided, a `kid`
  *   claim is added to the JWT header for forward-compatible key rotation.
  * @returns Signed JWT string
  */
-export declare function generateLicenseKey(payload: Omit<LicensePayload, 'iat' | 'exp'>, privateKey: string, expiresInSeconds?: number | null, publicKey?: string): Promise<string>;
+export declare function generateLicenseKey(payload: Omit<LicensePayload, 'iat' | 'exp' | 'jti'> & {
+    jti?: string;
+}, privateKey: string, expiresInSeconds?: number | null, publicKey?: string): Promise<string>;
 /**
  * Reset license state. Primarily for testing.
  */

package/dist/license.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"license.d.ts","sourceRoot":"","sources":["../src/license.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,8BAA8B;AAC9B,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,GAAG,YAAY,CAAC;AAEhE,qCAAqC;AACrC,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;iBAqBxB,CAAC;AAEH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;CACf;AAkBD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAElF;AAoCD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA0BhC;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,CAkC9D;AAaD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAG5C;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,GAAG,IAAI,CAGzD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,WAAW,GAAG,OAAO,CAqB7D;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED;;GAEG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAMpC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,KAAK,CAAC,EAC5C,UAAU,EAAE,MAAM,EAClB,gBAAgB,GAAE,MAAM,GAAG,IAAyB,EACpD,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAYjB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC"}
+{"version":3,"file":"license.d.ts","sourceRoot":"","sources":["../src/license.ts"],"names":[],"mappings":"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"}

package/dist/license.js

@@ -1,21 +1,56 @@
 /**
  * License validation for RevealUI Pro/Enterprise tiers.
  *
+ * Edge-compatible: uses the Web Crypto API (`crypto.subtle`) and `jose`
+ * exclusively. Safe to import from any runtime (Node, Edge, browser,
+ * Workers). No `node:crypto` or filesystem dependencies.
+ *
  * @dependencies
- * - jose - JWT token verification (Web Crypto API)
+ * - jose - JWT signing/verification (Web Crypto API)
  * - zod - Schema validation for license payloads
  */
-import { createHash } from 'node:crypto';
-import { decodeProtectedHeader, importPKCS8, importSPKI, jwtVerify, SignJWT } from 'jose';
+// jose is imported lazily inside async functions to avoid Turbopack's
+// async module initialization ordering issue (see #399). Top-level
+// import of jose triggers an asyncModule wrapper that can race with
+// other modules in the auth route bundle during page data collection.
 import { z } from 'zod';
 import { decryptLicenseKey } from './license-encryption.js';
 import { logger } from './utils/logger.js';
+async function getJose() {
+    return await import('jose');
+}
+/** JWT issuer and audience for license tokens — prevents cross-environment replay */
+const LICENSE_ISSUER = process.env.REVEALUI_LICENSE_ISSUER ?? 'https://revealui.com';
+const LICENSE_AUDIENCE = process.env.REVEALUI_LICENSE_AUDIENCE ?? 'revealui-license';
+const DEFAULT_GRACE = {
+    subscriptionDays: parseEnvInt('LICENSE_GRACE_SUBSCRIPTION_DAYS', 3),
+    perpetualDays: parseEnvInt('LICENSE_GRACE_PERPETUAL_DAYS', 30),
+    infraDays: parseEnvInt('LICENSE_GRACE_INFRA_DAYS', 7),
+};
+function parseEnvInt(key, fallback) {
+    const val = process.env[key];
+    if (val) {
+        const parsed = Number.parseInt(val, 10);
+        if (Number.isFinite(parsed) && parsed >= 0)
+            return parsed;
+    }
+    return fallback;
+}
+let graceConfig = { ...DEFAULT_GRACE };
+/**
+ * Configure grace period durations. Useful for testing.
+ */
+export function configureGracePeriods(overrides) {
+    graceConfig = { ...DEFAULT_GRACE, ...overrides };
+}
 /** Decoded license payload schema */
 const licensePayloadSchema = z.object({
     /** License tier */
     tier: z.enum(['pro', 'max', 'enterprise']),
-    /** Organization or customer ID */
-    customerId: z.string(),
+    /** Organization or customer ID — must be non-empty; used to bind the token to a specific customer */
+    customerId: z.string().min(1),
+    /** JWT ID — used for per-token revocation; every issued token must carry one */
+    jti: z.string().min(1),
     /** Licensed domain(s) */
     domains: z.array(z.string()).optional(),
     /** Maximum number of sites allowed */
@@ -34,16 +69,40 @@ const licensePayloadSchema = z.object({
     exp: z.number().optional(),
 });
 const DEFAULT_TTL_MS = 15_000; // 15 seconds  -  revoked licenses lose access quickly
-const DEFAULT_CACHE_CONFIG = {
-    ttlMs: (() => {
-        const envTtl = process.env.LICENSE_CACHE_TTL_MS;
-        if (envTtl) {
-            const parsed = Number.parseInt(envTtl, 10);
-            if (Number.isFinite(parsed) && parsed > 0)
-                return parsed;
-        }
+/**
+ * Hard cap on cache TTL. Any env override exceeding this is clamped + warned.
+ * Revoked licenses must not stay cached longer than this, regardless of
+ * operator misconfiguration. 15 minutes balances revocation responsiveness
+ * against DB load for high-traffic deployments.
+ *
+ * Tracked by MASTER_PLAN §CR-8 CR8-P1-05.
+ */
+export const MAX_LICENSE_CACHE_TTL_MS = 15 * 60 * 1000;
+/**
+ * Parse and validate the `LICENSE_CACHE_TTL_MS` env value.
+ *
+ * Rules:
+ * - Unset / non-numeric / non-positive → `DEFAULT_TTL_MS` (15s)
+ * - Above `MAX_LICENSE_CACHE_TTL_MS` → clamped to cap, warning emitted
+ * - Otherwise → parsed value
+ *
+ * Exported for unit testing. Production code uses the module-load-time
+ * evaluation in `DEFAULT_CACHE_CONFIG` below.
+ */
+export function parseLicenseCacheTtlEnv(envValue) {
+    if (!envValue)
+        return DEFAULT_TTL_MS;
+    const parsed = Number.parseInt(envValue, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
         return DEFAULT_TTL_MS;
-    })(),
+    if (parsed > MAX_LICENSE_CACHE_TTL_MS) {
+        logger.warn(`LICENSE_CACHE_TTL_MS=${parsed} exceeds the ${MAX_LICENSE_CACHE_TTL_MS}ms (15-minute) cap; using ${MAX_LICENSE_CACHE_TTL_MS}. Longer TTLs extend the window where revoked licenses retain access and are not permitted.`);
+        return MAX_LICENSE_CACHE_TTL_MS;
+    }
+    return parsed;
+}
+const DEFAULT_CACHE_CONFIG = {
+    ttlMs: parseLicenseCacheTtlEnv(process.env.LICENSE_CACHE_TTL_MS),
 };
 let cacheConfig = { ...DEFAULT_CACHE_CONFIG };
 let cachedAt = 0;
@@ -58,6 +117,7 @@ let cachedState = {
     tier: 'free',
     payload: null,
     validatedAt: null,
+    keyPresentButInvalid: false,
 };
 /**
  * The public key used to verify license JWTs.
@@ -73,7 +133,7 @@ function getPublicKey() {
  * Reads the license key from environment.
  * Supports encrypted keys (enc:iv:ciphertext:tag format) via REVEALUI_LICENSE_ENCRYPTION_KEY.
  */
-function getLicenseKey() {
+async function getLicenseKey() {
     const raw = process.env.REVEALUI_LICENSE_KEY ?? null;
     if (!raw)
         return null;
@@ -82,31 +142,67 @@ function getLicenseKey() {
 /**
  * Computes a deterministic Key ID (kid) from a public key PEM string.
  * Returns the first 8 characters of the SHA-256 hex digest of the PEM.
+ *
+ * Async because it uses `crypto.subtle.digest` for full edge compatibility.
  */
-export function computeKeyId(publicKeyPem) {
-    return createHash('sha256').update(publicKeyPem).digest('hex').slice(0, 8);
+export async function computeKeyId(publicKeyPem) {
+    const encoded = new TextEncoder().encode(publicKeyPem);
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', encoded));
+    let hex = '';
+    // Only the first 4 bytes (8 hex chars) — enough to identify rotated keys.
+    for (const b of digest.subarray(0, 4)) {
+        hex += b.toString(16).padStart(2, '0');
+    }
+    return hex;
 }
 /**
  * Validates a license key JWT and returns the decoded payload.
  * Returns null if the key is invalid, expired, or missing.
+ *
+ * Phase 1 audit B-2: when `expectedCustomerId` is supplied, the JWT's
+ * `customerId` claim must match exactly — otherwise the token is rejected
+ * even when the signature + iss + aud + exp are all valid. This binds a
+ * license to its purchaser. Forge mode uses this against the env-configured
+ * `REVEALUI_LICENSED_CUSTOMER_ID`. Hosted mode (where the deployment IS the
+ * customer) leaves it undefined.
+ *
+ * Note: `nbf` and `exp` are enforced automatically by jose.jwtVerify against
+ * `currentDate` (defaults to now). `iss` and `aud` are enforced via the
+ * options below. Signature is enforced via the public key.
  */
-export async function validateLicenseKey(licenseKey, publicKey) {
+export async function validateLicenseKey(licenseKey, publicKey, expectedCustomerId) {
     try {
+        const jose = await getJose();
         // Extract kid from JWT header for forward-compatible key rotation
-        const header = decodeProtectedHeader(licenseKey);
-        const expectedKid = computeKeyId(publicKey);
+        const header = jose.decodeProtectedHeader(licenseKey);
+        const expectedKid = await computeKeyId(publicKey);
         if (header.kid && header.kid !== expectedKid) {
             logger.warn(`JWT kid mismatch: token has "${header.kid}", current key is "${expectedKid}". ` +
                 'Token may have been signed with a rotated key.');
         }
-        const key = await importSPKI(publicKey, 'RS256');
-        const { payload } = await jwtVerify(licenseKey, key, {
-            algorithms: ['RS256', 'ES256'],
+        const key = await jose.importSPKI(publicKey, 'EdDSA');
+        // Accept tokens expired within the subscription grace window so the
+        // payload is available for grace-period calculations in isLicensed().
+        const { payload } = await jose.jwtVerify(licenseKey, key, {
+            algorithms: ['EdDSA'],
+            clockTolerance: graceConfig.subscriptionDays * 86_400,
+            issuer: LICENSE_ISSUER,
+            audience: LICENSE_AUDIENCE,
         });
         const result = licensePayloadSchema.safeParse(payload);
         if (!result.success) {
             return null;
         }
+        // Phase 1 audit B-2: customerId binding. If the caller supplied an
+        // expectation, the JWT's customerId must match exactly. This prevents
+        // a leaked JWT from one customer being used to license another's
+        // deployment (Forge customer-binding) or a leaked stamping-time JWT
+        // being replayed against a deployment expecting a different customer.
+        if (expectedCustomerId !== undefined && result.data.customerId !== expectedCustomerId) {
+            logger.warn(`License customerId mismatch: token has "${result.data.customerId}", ` +
+                `deployment expects "${expectedCustomerId}". Token rejected.`);
+            return null;
+        }
         return result.data;
     }
     catch {
@@ -120,16 +216,27 @@ export async function validateLicenseKey(licenseKey, publicKey) {
  * @returns The resolved license tier
  */
 export async function initializeLicense() {
-    const licenseKey = getLicenseKey();
+    const licenseKey = await getLicenseKey();
     const publicKey = getPublicKey();
     if (!(licenseKey && publicKey)) {
-        cachedState = { tier: 'free', payload: null, validatedAt: Date.now() };
+        cachedState = {
+            tier: 'free',
+            payload: null,
+            validatedAt: Date.now(),
+            keyPresentButInvalid: false,
+        };
         cachedAt = Date.now();
         return 'free';
     }
     const payload = await validateLicenseKey(licenseKey, publicKey);
     if (!payload) {
-        cachedState = { tier: 'free', payload: null, validatedAt: Date.now() };
+        // Key was present but failed validation (expired beyond grace, invalid signature, etc.)
+        cachedState = {
+            tier: 'free',
+            payload: null,
+            validatedAt: Date.now(),
+            keyPresentButInvalid: true,
+        };
         cachedAt = Date.now();
         return 'free';
     }
@@ -137,6 +244,7 @@ export async function initializeLicense() {
         tier: payload.tier,
         payload,
         validatedAt: Date.now(),
+        keyPresentButInvalid: false,
     };
     cachedAt = Date.now();
     // Clamp cache TTL to license expiry so revoked licenses don't survive the full TTL
@@ -154,7 +262,7 @@ export async function initializeLicense() {
  */
 function evictStaleCache() {
     if (cachedAt > 0 && Date.now() - cachedAt > cacheConfig.ttlMs) {
-        cachedState = { tier: 'free', payload: null, validatedAt: null };
+        cachedState = { tier: 'free', payload: null, validatedAt: null, keyPresentButInvalid: false };
         cachedAt = 0;
     }
 }
@@ -176,6 +284,10 @@ export function getLicensePayload() {
 /**
  * Checks whether the current license is at least the given tier.
  * Also validates that the license has not expired (checks JWT exp claim).
+ *
+ * Subscription grace: if the JWT has expired but is within the configured
+ * grace period (default 3 days), access is still allowed. Use
+ * `getLicenseStatus()` to check whether the license is in grace.
  */
 export function isLicensed(requiredTier) {
     evictStaleCache();
@@ -192,11 +304,90 @@ export function isLicensed(requiredTier) {
     if (!cachedState.payload?.perpetual && cachedState.payload?.exp) {
         const nowSeconds = Math.floor(Date.now() / 1000);
         if (cachedState.payload.exp < nowSeconds) {
+            // Expired — check subscription grace period
+            const graceEndSeconds = cachedState.payload.exp + graceConfig.subscriptionDays * 86_400;
+            if (nowSeconds < graceEndSeconds) {
+                // Within grace — still allowed, but callers should check getLicenseStatus()
+                return tierRank[cachedState.tier] >= tierRank[requiredTier];
+            }
             return false;
         }
     }
     return tierRank[cachedState.tier] >= tierRank[requiredTier];
 }
+/**
+ * Returns the full license status including mode, grace state, and read-only flag.
+ *
+ * Use this for UI decisions (banners, warnings) and API response headers.
+ * For simple gate checks, `isLicensed()` is sufficient.
+ */
+export function getLicenseStatus(requiredTier = 'pro') {
+    evictStaleCache();
+    const tierRank = {
+        free: 0,
+        pro: 1,
+        max: 2,
+        enterprise: 3,
+    };
+    // No license configured — or key was present but failed validation
+    if (!cachedState.payload) {
+        if (cachedState.keyPresentButInvalid) {
+            return {
+                allowed: requiredTier === 'free',
+                tier: 'free',
+                mode: 'expired',
+                reason: 'License key failed validation (expired beyond grace or invalid)',
+                readOnly: false,
+            };
+        }
+        return {
+            allowed: requiredTier === 'free',
+            tier: 'free',
+            mode: 'missing',
+            reason: 'No license configured',
+            readOnly: false,
+        };
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    // Check subscription expiry + grace
+    if (!cachedState.payload.perpetual && cachedState.payload.exp) {
+        if (cachedState.payload.exp < nowSeconds) {
+            const graceEndSeconds = cachedState.payload.exp + graceConfig.subscriptionDays * 86_400;
+            if (nowSeconds < graceEndSeconds) {
+                const graceRemainingMs = (graceEndSeconds - nowSeconds) * 1000;
+                return {
+                    allowed: tierRank[cachedState.tier] >= tierRank[requiredTier],
+                    tier: cachedState.tier,
+                    mode: 'grace',
+                    reason: `Subscription expired, ${Math.ceil(graceRemainingMs / 86_400_000)}-day grace remaining`,
+                    graceRemainingMs,
+                    readOnly: false,
+                };
+            }
+            return {
+                allowed: requiredTier === 'free',
+                tier: 'free',
+                mode: 'expired',
+                reason: 'Subscription expired and grace period exhausted',
+                readOnly: false,
+            };
+        }
+    }
+    // Active license
+    return {
+        allowed: tierRank[cachedState.tier] >= tierRank[requiredTier],
+        tier: cachedState.tier,
+        mode: 'active',
+        readOnly: false,
+    };
+}
+/**
+ * Returns the configured grace period durations.
+ * Useful for API response headers and customer-facing documentation.
+ */
+export function getGraceConfig() {
+    return graceConfig;
+}
 /**
  * Returns the maximum number of sites allowed by the current license.
  */
@@ -239,24 +430,41 @@ export function getMaxAgentTasks() {
 }
 /**
  * Generates a signed license key JWT.
- * This is a server-only function  -  requires the private key.
+ * Server-only in practice (requires the private key) but edge-compatible —
+ * `jose.importPKCS8` and `SignJWT` both run on Web Crypto.
  *
  * @param payload - License payload (tier, customerId, limits, perpetual flag)
- * @param privateKey - RS256 private key (PEM format)
+ * @param privateKey - Ed25519 private key (PEM format)
  * @param expiresInSeconds - JWT expiration in seconds. Pass null for perpetual
  *   licenses (no exp claim). Defaults to 1 year for subscription licenses.
- * @param publicKey - RS256 public key (PEM format). When provided, a `kid`
+ * @param publicKey - Ed25519 public key (PEM format). When provided, a `kid`
  *   claim is added to the JWT header for forward-compatible key rotation.
  * @returns Signed JWT string
  */
 export async function generateLicenseKey(payload, privateKey, expiresInSeconds = 365 * 24 * 60 * 60, publicKey) {
-    const key = await importPKCS8(privateKey, 'RS256');
-    const kid = publicKey ? computeKeyId(publicKey) : undefined;
-    const header = { alg: 'RS256' };
+    const jose = await getJose();
+    const key = await jose.importPKCS8(privateKey, 'EdDSA');
+    const kid = publicKey ? await computeKeyId(publicKey) : undefined;
+    const header = { alg: 'EdDSA' };
     if (kid) {
         header.kid = kid;
     }
-    const builder = new SignJWT({ ...payload }).setProtectedHeader(header).setIssuedAt();
+    // Phase 1 audit B-2: every issued token carries a `jti` so it can be
+    // individually revoked without rotating the vendor key. Auto-generate
+    // when caller doesn't supply one (the common case).
+    const jti = payload.jti ?? crypto.randomUUID();
+    // Strip the optional jti from the spread so jose.setJti() is the single
+    // source of the claim (avoids a duplicate field in the payload).
+    const { jti: _ignoredJti, ...rest } = payload;
+    const builder = new jose.SignJWT({ ...rest })
+        .setProtectedHeader(header)
+        .setIssuedAt()
+        // Phase 1 audit B-2: enforce nbf so tokens cannot be replayed pre-issue
+        // by a clock-skewed client.
+        .setNotBefore('0s')
+        .setJti(jti)
+        .setIssuer(LICENSE_ISSUER)
+        .setAudience(LICENSE_AUDIENCE);
     if (expiresInSeconds !== null) {
         builder.setExpirationTime(`${expiresInSeconds}s`);
     }
@@ -266,6 +474,6 @@ export async function generateLicenseKey(payload, privateKey, expiresInSeconds =
  * Reset license state. Primarily for testing.
  */
 export function resetLicenseState() {
-    cachedState = { tier: 'free', payload: null, validatedAt: null };
+    cachedState = { tier: 'free', payload: null, validatedAt: null, keyPresentButInvalid: false };
     cachedAt = 0;
 }

package/dist/nextjs/index.d.ts

@@ -1,4 +1,3 @@
 export { getRevealUI } from './utilities.js';
 export type { WithRevealUIOptions } from './withRevealUI.js';
-export { withRevealUI } from './withRevealUI.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/nextjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/nextjs/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/nextjs/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/nextjs/index.js

@@ -1,3 +1,8 @@
-// RevealUI Next.js integration
+// RevealUI Next.js runtime integration.
+//
+// This barrel is intentionally runtime-only. `withRevealUI` is NOT re-exported
+// here because it pulls in `node:fs` + `node:path` at module load, which Next's
+// NFT tracer then attributes to every route that transitively imports this
+// barrel (even via type-only paths). Config-time consumers should import it
+// directly from `@revealui/core/nextjs/withRevealUI`.
 export { getRevealUI } from './utilities.js';
-export { withRevealUI } from './withRevealUI.js';

package/dist/nextjs/withRevealUI.d.ts

@@ -1,4 +1,31 @@
-import type { NextConfig } from 'next';
+/**
+ * Subset of Next.js config shape used by withRevealUI.
+ * Defined locally to avoid requiring `next` as a dependency of @revealui/core.
+ * Consumers pass their full NextConfig through; we only access these fields.
+ */
+interface NextConfig {
+    env?: Record<string, string | undefined>;
+    webpack?: (config: Record<string, unknown>, context: {
+        isServer: boolean;
+        dev: boolean;
+        dir: string;
+        [key: string]: unknown;
+    }) => Record<string, unknown>;
+    turbopack?: {
+        resolveAlias?: Record<string, string>;
+    };
+    headers?: () => Promise<Array<{
+        source: string;
+        headers: Array<{
+            key: string;
+            value: string;
+        }>;
+    }>>;
+    images?: {
+        remotePatterns?: Array<Record<string, unknown>>;
+    };
+    [key: string]: unknown;
+}
 export interface WithRevealUIOptions {
     /** Path to the RevealUI config file (relative to Next.js project root) */
     configPath?: string;
@@ -17,4 +44,5 @@ export interface WithRevealUIOptions {
  * The alias works with both Webpack (Next.js < 15) and Turbopack (Next.js 16+).
  */
 export declare function withRevealUI(nextConfig?: NextConfig, options?: WithRevealUIOptions): NextConfig;
+export {};
 //# sourceMappingURL=withRevealUI.d.ts.map

package/dist/nextjs/withRevealUI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"withRevealUI.d.ts","sourceRoot":"","sources":["../../src/nextjs/withRevealUI.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAOvC,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,GAAE,UAAe,EAC3B,OAAO,GAAE,mBAAwB,GAChC,UAAU,CAgMZ"}
+{"version":3,"file":"withRevealUI.d.ts","sourceRoot":"","sources":["../../src/nextjs/withRevealUI.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,UAAU,UAAU;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,CACR,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,KAC9E,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7B,SAAS,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;IACtD,OAAO,CAAC,EAAE,MAAM,OAAO,CACrB,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,KAAK,CAAC;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC,CAC1E,CAAC;IACF,MAAM,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;KAAE,CAAC;IAC7D,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAOD,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uBAAuB;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,GAAE,UAAe,EAC3B,OAAO,GAAE,mBAAwB,GAChC,UAAU,CAgMZ"}