@revealui/core 0.5.6 → 0.6.0

package/dist/license-encryption.js

@@ -3,50 +3,91 @@
  *
  * Format: enc:<iv-hex>:<ciphertext-hex>:<auth-tag-hex>
  * Falls back to plaintext when REVEALUI_LICENSE_ENCRYPTION_KEY is not set.
+ *
+ * Edge-compatible: uses the Web Crypto API (`crypto.subtle`) exclusively.
+ * Safe to import from any runtime (Node, Edge, browser, Workers).
+ *
+ * Note: AES-GCM via Web Crypto bundles the auth tag onto the ciphertext
+ * (last 16 bytes). The on-wire format is kept identical to the previous
+ * node:crypto implementation for backward compatibility, so decrypt still
+ * accepts `enc:iv:ciphertext:tag` and recombines ciphertext||tag before
+ * passing to `crypto.subtle.decrypt`.
  */
-import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
 const ENC_PREFIX = 'enc:';
-const ALGORITHM = 'aes-256-gcm';
 const IV_BYTES = 12;
+const TAG_BYTES = 16;
+/** Hex-encode a Uint8Array. */
+function toHex(bytes) {
+    let out = '';
+    for (const b of bytes) {
+        out += b.toString(16).padStart(2, '0');
+    }
+    return out;
+}
+/** Hex-decode to Uint8Array. Throws on invalid input length. */
+function fromHex(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error('Invalid hex string: odd length');
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        const byte = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+        if (Number.isNaN(byte)) {
+            throw new Error('Invalid hex string');
+        }
+        out[i] = byte;
+    }
+    return out;
+}
 /**
  * Derives a 32-byte key from the env var value.
  * Accepts either a 64-char hex string or an arbitrary passphrase (hashed to 32 bytes).
  */
-function deriveKey(raw) {
+async function deriveKeyBytes(raw) {
     if (/^[0-9a-f]{64}$/i.test(raw)) {
-        return Buffer.from(raw, 'hex');
+        return fromHex(raw);
     }
-    return createHash('sha256').update(raw).digest();
+    const encoded = new TextEncoder().encode(raw);
+    const digest = await crypto.subtle.digest('SHA-256', encoded);
+    return new Uint8Array(digest);
 }
-function getEncryptionKey() {
+async function getCryptoKey(usage) {
     const raw = process.env.REVEALUI_LICENSE_ENCRYPTION_KEY;
     if (!raw)
         return null;
-    return deriveKey(raw);
+    const keyBytes = await deriveKeyBytes(raw);
+    // Cast through BufferSource: TS 5.7+ narrows Uint8Array to ArrayBufferLike on
+    // some construction paths, but Web Crypto accepts any ArrayBufferView.
+    return crypto.subtle.importKey('raw', keyBytes, { name: 'AES-GCM' }, false, [
+        usage,
+    ]);
 }
 /**
  * Encrypt a plaintext license key.
  * Returns `enc:<iv>:<ciphertext>:<tag>` or the original plaintext if no key is configured.
  */
-export function encryptLicenseKey(plaintext) {
-    const key = getEncryptionKey();
+export async function encryptLicenseKey(plaintext) {
+    const key = await getCryptoKey('encrypt');
     if (!key)
         return plaintext;
-    const iv = randomBytes(IV_BYTES);
-    const cipher = createCipheriv(ALGORITHM, key, iv);
-    const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
-    const tag = cipher.getAuthTag();
-    return `${ENC_PREFIX}${iv.toString('hex')}:${encrypted.toString('hex')}:${tag.toString('hex')}`;
+    const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+    const plaintextBytes = new TextEncoder().encode(plaintext);
+    const combined = new Uint8Array(await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, plaintextBytes));
+    // Web Crypto appends the 16-byte auth tag to the ciphertext. Split it back
+    // out to preserve the original on-wire format.
+    const ciphertext = combined.slice(0, combined.length - TAG_BYTES);
+    const tag = combined.slice(combined.length - TAG_BYTES);
+    return `${ENC_PREFIX}${toHex(iv)}:${toHex(ciphertext)}:${toHex(tag)}`;
 }
 /**
  * Decrypt a license key.
  * If the value doesn't start with `enc:`, returns it as-is (plaintext fallback).
  */
-export function decryptLicenseKey(stored) {
+export async function decryptLicenseKey(stored) {
     if (!stored.startsWith(ENC_PREFIX)) {
         return stored; // plaintext  -  backward compatible
     }
-    const key = getEncryptionKey();
+    const key = await getCryptoKey('decrypt');
     if (!key) {
         throw new Error('Encrypted license key found but REVEALUI_LICENSE_ENCRYPTION_KEY is not set. ' +
             'Cannot decrypt without the encryption key.');
@@ -56,15 +97,29 @@ export function decryptLicenseKey(stored) {
         throw new Error('Malformed encrypted license key  -  expected enc:<iv>:<ciphertext>:<tag>');
     }
     const [ivHex, ciphertextHex, tagHex] = parts;
-    const iv = Buffer.from(ivHex, 'hex');
-    const ciphertext = Buffer.from(ciphertextHex, 'hex');
-    const tag = Buffer.from(tagHex, 'hex');
+    const iv = fromHex(ivHex);
+    const ciphertext = fromHex(ciphertextHex);
+    const tag = fromHex(tagHex);
     if (iv.length !== IV_BYTES) {
         throw new Error(`Invalid IV length: expected ${IV_BYTES} bytes, got ${iv.length}`);
     }
-    const decipher = createDecipheriv(ALGORITHM, key, iv);
-    decipher.setAuthTag(tag);
-    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+    if (tag.length !== TAG_BYTES) {
+        throw new Error(`Invalid auth tag length: expected ${TAG_BYTES} bytes, got ${tag.length}`);
+    }
+    // Recombine ciphertext||tag for Web Crypto's decrypt API.
+    const combined = new Uint8Array(ciphertext.length + tag.length);
+    combined.set(ciphertext, 0);
+    combined.set(tag, ciphertext.length);
+    let plaintextBuffer;
+    try {
+        plaintextBuffer = await crypto.subtle.decrypt({ name: 'AES-GCM', iv: iv }, key, combined);
+    }
+    catch {
+        // Web Crypto throws an opaque OperationError on tag mismatch / wrong key.
+        // Normalize to a descriptive error matching the old node:crypto behavior.
+        throw new Error('Unsupported state or unable to authenticate data');
+    }
+    return new TextDecoder().decode(plaintextBuffer);
 }
 /**
  * Check whether a stored license key value is encrypted.

package/dist/license.d.ts

@@ -1,18 +1,62 @@
 /**
  * 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<{
-        max: "max";
         pro: "pro";
+        max: "max";
         enterprise: "enterprise";
     }>;
     customerId: z.ZodString;
@@ -26,7 +70,7 @@ 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;
 }
 /**
@@ -37,8 +81,10 @@ 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.
@@ -63,8 +109,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,7 +142,8 @@ 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)

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,15 +1,42 @@
 /**
  * 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';
 import { z } from 'zod';
 import { decryptLicenseKey } from './license-encryption.js';
 import { logger } from './utils/logger.js';
+/** 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 */
@@ -58,6 +85,7 @@ let cachedState = {
     tier: 'free',
     payload: null,
     validatedAt: null,
+    keyPresentButInvalid: false,
 };
 /**
  * The public key used to verify license JWTs.
@@ -73,7 +101,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,9 +110,18 @@ 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.
@@ -94,14 +131,19 @@ export async function validateLicenseKey(licenseKey, publicKey) {
     try {
         // Extract kid from JWT header for forward-compatible key rotation
         const header = decodeProtectedHeader(licenseKey);
-        const expectedKid = computeKeyId(publicKey);
+        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');
+        // Accept tokens expired within the subscription grace window so the
+        // payload is available for grace-period calculations in isLicensed().
         const { payload } = await jwtVerify(licenseKey, key, {
-            algorithms: ['RS256', 'ES256'],
+            algorithms: ['RS256'],
+            clockTolerance: graceConfig.subscriptionDays * 86_400,
+            issuer: LICENSE_ISSUER,
+            audience: LICENSE_AUDIENCE,
         });
         const result = licensePayloadSchema.safeParse(payload);
         if (!result.success) {
@@ -120,16 +162,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 +190,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 +208,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 +230,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 +250,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,7 +376,8 @@ 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)
@@ -251,12 +389,16 @@ export function getMaxAgentTasks() {
  */
 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 kid = publicKey ? await computeKeyId(publicKey) : undefined;
     const header = { alg: 'RS256' };
     if (kid) {
         header.kid = kid;
     }
-    const builder = new SignJWT({ ...payload }).setProtectedHeader(header).setIssuedAt();
+    const builder = new SignJWT({ ...payload })
+        .setProtectedHeader(header)
+        .setIssuedAt()
+        .setIssuer(LICENSE_ISSUER)
+        .setAudience(LICENSE_AUDIENCE);
     if (expiresInSeconds !== null) {
         builder.setExpirationTime(`${expiresInSeconds}s`);
     }
@@ -266,6 +408,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"}

package/dist/observability/logger.d.ts

@@ -40,8 +40,4 @@ export declare function logUserAction(action: string, userId?: string, context?:
  * System event logger
  */
 export declare function logSystemEvent(event: string, context?: Record<string, unknown>): void;
-/**
- * Sanitize sensitive data from logs
- */
-export declare function sanitizeLogData(data: Record<string, unknown>): Record<string, unknown>;
 //# sourceMappingURL=logger.d.ts.map

package/dist/observability/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,YAAY,EACV,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,QAAQ,GACT,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,YAAY,EACZ,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,QAAQ,GACT,MAAM,wBAAwB,CAAC;AAKhC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,OAAO,EAAE,SAAS,GAAG,OAAO,EACzE,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,IAG/D,SAAS,QAAQ,GAAG;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;QACrC,OAAO,CAAC,EAAE,MAAM,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KAC5C,CAAC;CACH,EACD,MAAM,MAAM,OAAO,CAAC,SAAS,CAAC,KAC7B,OAAO,CAAC,SAAS,CAAC,CA6CtB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CASN;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAgBN;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,EAC5C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAKrF;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BtF"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,YAAY,EACV,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,QAAQ,GACT,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,YAAY,EACZ,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,MAAM,EACN,QAAQ,GACT,MAAM,wBAAwB,CAAC;AAKhC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,OAAO,EAAE,SAAS,GAAG,OAAO,EACzE,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,OAAO,CAAA;CAAO,IAG/D,SAAS,QAAQ,GAAG;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;QACrC,OAAO,CAAC,EAAE,MAAM,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;KAC5C,CAAC;CACH,EACD,MAAM,MAAM,OAAO,CAAC,SAAS,CAAC,KAC7B,OAAO,CAAC,SAAS,CAAC,CA6CtB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CASN;AAED;;GAEG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAgBN;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,EAC5C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAChC,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAKrF"}