@qwickapps/server 1.6.0 → 1.7.0

package/dist/plugins/entitlements/entitlements-plugin.js

@@ -1,707 +0,0 @@
-/**
- * Entitlements Plugin
- *
- * User entitlement management plugin for @qwickapps/server.
- * Supports pluggable sources (PostgreSQL, Keap, etc.) with Redis caching.
- *
- * Entitlements are string-based tags (e.g., 'pro', 'enterprise', 'feature:analytics').
- * Multiple sources can be combined - entitlements are merged from all sources.
- *
- * Copyright (c) 2025 QwickApps.com. All rights reserved.
- */
-import { getCache } from '../cache-plugin.js';
-// Plugin state
-let primarySource = null;
-let additionalSources = [];
-let pluginConfig = null;
-let cacheInstance = null;
-let cacheKeyPrefix = 'entitlements:';
-let cacheTtl = 300;
-let cacheMappingTtl = 600;
-let cacheEnabled = true;
-let cacheVersion = 1;
-/**
- * Create the Entitlements plugin
- */
-export function createEntitlementsPlugin(config) {
-    const debug = config.debug || false;
-    // Routes are mounted under /api by the control panel, so don't include /api in prefix
-    const apiPrefix = config.api?.prefix || '/entitlements';
-    const apiEnabled = config.api?.enabled !== false;
-    const enableWriteApi = config.api?.enableWrite !== false;
-    function log(message, data) {
-        if (debug) {
-            console.log(`[EntitlementsPlugin] ${message}`, data || '');
-        }
-    }
-    // Cache key helpers
-    const keys = {
-        entitlements: (email) => `${cacheKeyPrefix}user:${email.toLowerCase()}`,
-        mapping: (source, id) => `${cacheKeyPrefix}mapping:${source}:${id}`,
-    };
-    return {
-        id: 'entitlements',
-        name: 'Entitlements',
-        version: '1.0.0',
-        async onStart(_pluginConfig, registry) {
-            log('Starting entitlements plugin');
-            // Initialize primary source
-            await config.source.initialize();
-            primarySource = config.source;
-            log('Primary source initialized', { source: config.source.name });
-            // Initialize additional sources
-            additionalSources = config.additionalSources || [];
-            for (const source of additionalSources) {
-                await source.initialize();
-                log('Additional source initialized', { source: source.name });
-            }
-            // Store config
-            pluginConfig = config;
-            // Setup caching if enabled
-            cacheEnabled = config.cache?.enabled !== false;
-            if (cacheEnabled) {
-                try {
-                    const instanceName = config.cache?.instanceName || 'default';
-                    cacheInstance = getCache(instanceName);
-                    cacheKeyPrefix = config.cache?.keyPrefix || 'entitlements:';
-                    cacheTtl = config.cache?.ttl || 300;
-                    cacheMappingTtl = config.cache?.mappingTtl || cacheTtl * 2;
-                    log('Cache configured', { instanceName, prefix: cacheKeyPrefix, ttl: cacheTtl });
-                }
-                catch {
-                    log('Cache not available, running without caching');
-                    cacheEnabled = false;
-                    cacheInstance = null;
-                }
-            }
-            // Register health check
-            registry.registerHealthCheck({
-                name: 'entitlements-source',
-                type: 'custom',
-                check: async () => {
-                    try {
-                        // Use source's isHealthy() method if available (avoids API calls)
-                        // Otherwise just check that source is initialized
-                        if (config.source.isHealthy) {
-                            const healthy = await config.source.isHealthy();
-                            return { healthy };
-                        }
-                        // Source is healthy if initialized (we got here means it started)
-                        return { healthy: primarySource !== null };
-                    }
-                    catch {
-                        return { healthy: false };
-                    }
-                },
-            });
-            // Add API routes if enabled
-            // IMPORTANT: Static paths must be registered BEFORE parameterized paths
-            // to prevent /:email from matching "available" and "status"
-            if (apiEnabled) {
-                // List available entitlements (static path - must be before /:email)
-                registry.addRoute({
-                    method: 'get',
-                    path: `${apiPrefix}/available`,
-                    pluginId: 'entitlements',
-                    handler: async (_req, res) => {
-                        try {
-                            const available = await getAvailableEntitlements();
-                            res.json({ entitlements: available, total: available.length });
-                        }
-                        catch (error) {
-                            console.error('[EntitlementsPlugin] List available error:', error);
-                            res.status(500).json({ error: 'Failed to list available entitlements' });
-                        }
-                    },
-                });
-                // Get entitlements plugin status (static path - must be before /:email)
-                registry.addRoute({
-                    method: 'get',
-                    path: `${apiPrefix}/status`,
-                    pluginId: 'entitlements',
-                    handler: async (_req, res) => {
-                        try {
-                            const sources = [
-                                {
-                                    name: config.source.name,
-                                    description: config.source.description,
-                                    readonly: config.source.readonly ?? false,
-                                    primary: true,
-                                },
-                                ...additionalSources.map((s) => ({
-                                    name: s.name,
-                                    description: s.description,
-                                    readonly: s.readonly ?? false,
-                                    primary: false,
-                                })),
-                            ];
-                            res.json({
-                                readonly: config.source.readonly ?? false,
-                                writeEnabled: enableWriteApi && !config.source.readonly,
-                                cacheEnabled,
-                                cacheTtl,
-                                sources,
-                            });
-                        }
-                        catch (error) {
-                            console.error('[EntitlementsPlugin] Status error:', error);
-                            res.status(500).json({ error: 'Failed to get status' });
-                        }
-                    },
-                });
-                // Get entitlements statistics (static path - must be before /:email)
-                registry.addRoute({
-                    method: 'get',
-                    path: `${apiPrefix}/stats`,
-                    pluginId: 'entitlements',
-                    handler: async (_req, res) => {
-                        try {
-                            const stats = await getEntitlementStats();
-                            res.json(stats);
-                        }
-                        catch (error) {
-                            console.error('[EntitlementsPlugin] Stats error:', error);
-                            res.status(500).json({ error: 'Failed to get entitlement stats' });
-                        }
-                    },
-                });
-                // Invalidate cache for email (static prefix - must be before /:email)
-                registry.addRoute({
-                    method: 'delete',
-                    path: `${apiPrefix}/cache/:email`,
-                    pluginId: 'entitlements',
-                    handler: async (req, res) => {
-                        try {
-                            const email = decodeURIComponent(req.params.email);
-                            await invalidateEntitlementCache(email);
-                            log('Cache invalidated', { email });
-                            res.status(204).send();
-                        }
-                        catch (error) {
-                            console.error('[EntitlementsPlugin] Invalidate cache error:', error);
-                            res.status(500).json({ error: 'Failed to invalidate cache' });
-                        }
-                    },
-                });
-                // Get entitlements for email (parameterized - after static paths)
-                // Note: We guard against reserved paths that might accidentally match :email
-                const reservedPaths = ['stats', 'available', 'status', 'cache'];
-                registry.addRoute({
-                    method: 'get',
-                    path: `${apiPrefix}/:email`,
-                    pluginId: 'entitlements',
-                    handler: async (req, res) => {
-                        try {
-                            const email = decodeURIComponent(req.params.email);
-                            // Skip reserved paths - they have their own handlers
-                            if (reservedPaths.includes(email.toLowerCase())) {
-                                return res.status(404).json({ error: 'Not found' });
-                            }
-                            const refresh = req.query.refresh === 'true';
-                            const result = refresh
-                                ? await refreshEntitlements(email)
-                                : await getEntitlements(email);
-                            res.json(result);
-                        }
-                        catch (error) {
-                            console.error('[EntitlementsPlugin] Get entitlements error:', error);
-                            res.status(500).json({ error: 'Failed to get entitlements' });
-                        }
-                    },
-                });
-                // Check specific entitlement
-                registry.addRoute({
-                    method: 'get',
-                    path: `${apiPrefix}/:email/check/:entitlement`,
-                    pluginId: 'entitlements',
-                    handler: async (req, res) => {
-                        try {
-                            const email = decodeURIComponent(req.params.email);
-                            const entitlement = decodeURIComponent(req.params.entitlement);
-                            const has = await hasEntitlement(email, entitlement);
-                            res.json({ email, entitlement, hasEntitlement: has });
-                        }
-                        catch (error) {
-                            console.error('[EntitlementsPlugin] Check entitlement error:', error);
-                            res.status(500).json({ error: 'Failed to check entitlement' });
-                        }
-                    },
-                });
-                // Check multiple entitlements
-                registry.addRoute({
-                    method: 'post',
-                    path: `${apiPrefix}/:email/check`,
-                    pluginId: 'entitlements',
-                    handler: async (req, res) => {
-                        try {
-                            const email = decodeURIComponent(req.params.email);
-                            const { entitlements: toCheck, mode = 'any' } = req.body;
-                            if (!Array.isArray(toCheck) || toCheck.length === 0) {
-                                return res.status(400).json({ error: 'entitlements array required' });
-                            }
-                            const result = await getEntitlements(email);
-                            const has = toCheck.filter((e) => result.entitlements.includes(e));
-                            const missing = toCheck.filter((e) => !result.entitlements.includes(e));
-                            const passed = mode === 'all'
-                                ? missing.length === 0
-                                : has.length > 0;
-                            res.json({
-                                email,
-                                mode,
-                                passed,
-                                has,
-                                missing,
-                                total: result.entitlements.length,
-                            });
-                        }
-                        catch (error) {
-                            console.error('[EntitlementsPlugin] Check entitlements error:', error);
-                            res.status(500).json({ error: 'Failed to check entitlements' });
-                        }
-                    },
-                });
-                // Refresh entitlements (bypass cache)
-                registry.addRoute({
-                    method: 'post',
-                    path: `${apiPrefix}/:email/refresh`,
-                    pluginId: 'entitlements',
-                    handler: async (req, res) => {
-                        try {
-                            const email = decodeURIComponent(req.params.email);
-                            const result = await refreshEntitlements(email);
-                            log('Entitlements refreshed', { email, count: result.entitlements.length });
-                            res.json(result);
-                        }
-                        catch (error) {
-                            console.error('[EntitlementsPlugin] Refresh entitlements error:', error);
-                            res.status(500).json({ error: 'Failed to refresh entitlements' });
-                        }
-                    },
-                });
-                // Write endpoints (grant/revoke) - only if enabled and source is writable
-                if (enableWriteApi && !config.source.readonly) {
-                    // Grant entitlement
-                    registry.addRoute({
-                        method: 'post',
-                        path: `${apiPrefix}/:email`,
-                        pluginId: 'entitlements',
-                        handler: async (req, res) => {
-                            try {
-                                const email = decodeURIComponent(req.params.email);
-                                const { entitlement } = req.body;
-                                if (!entitlement) {
-                                    return res.status(400).json({ error: 'entitlement required' });
-                                }
-                                const authReq = req;
-                                const grantedBy = authReq.auth?.user?.email || 'system';
-                                await grantEntitlement(email, entitlement, grantedBy);
-                                log('Entitlement granted', { email, entitlement, grantedBy });
-                                res.status(201).json({ email, entitlement, granted: true });
-                            }
-                            catch (error) {
-                                console.error('[EntitlementsPlugin] Grant entitlement error:', error);
-                                res.status(500).json({ error: 'Failed to grant entitlement' });
-                            }
-                        },
-                    });
-                    // Revoke entitlement
-                    registry.addRoute({
-                        method: 'delete',
-                        path: `${apiPrefix}/:email/:entitlement`,
-                        pluginId: 'entitlements',
-                        handler: async (req, res) => {
-                            try {
-                                const email = decodeURIComponent(req.params.email);
-                                const entitlement = decodeURIComponent(req.params.entitlement);
-                                await revokeEntitlement(email, entitlement);
-                                log('Entitlement revoked', { email, entitlement });
-                                res.status(204).send();
-                            }
-                            catch (error) {
-                                console.error('[EntitlementsPlugin] Revoke entitlement error:', error);
-                                res.status(500).json({ error: 'Failed to revoke entitlement' });
-                            }
-                        },
-                    });
-                }
-            }
-            // Register UI menu item
-            registry.addMenuItem({
-                pluginId: 'entitlements',
-                id: 'entitlements:sidebar',
-                label: 'Entitlements',
-                icon: 'local_offer',
-                route: '/entitlements',
-                order: 35, // After Users (30)
-            });
-            log('Entitlements plugin started');
-        },
-        async onStop() {
-            log('Stopping entitlements plugin');
-            // Shutdown sources
-            if (primarySource) {
-                await primarySource.shutdown();
-            }
-            for (const source of additionalSources) {
-                await source.shutdown();
-            }
-            primarySource = null;
-            additionalSources = [];
-            pluginConfig = null;
-            cacheInstance = null;
-            log('Entitlements plugin stopped');
-        },
-    };
-}
-// ========================================
-// Helper Functions
-// ========================================
-/**
- * Get the primary entitlement source
- */
-export function getEntitlementSource() {
-    return primarySource;
-}
-/**
- * Check if the primary source is readonly
- */
-export function isSourceReadonly() {
-    return primarySource?.readonly ?? true;
-}
-/**
- * Get entitlements for an email (cache-first)
- */
-export async function getEntitlements(email) {
-    if (!primarySource) {
-        throw new Error('Entitlements plugin not initialized');
-    }
-    const normalizedEmail = email.toLowerCase();
-    const cacheKey = `entitlements:user:${normalizedEmail}`;
-    // Try cache first
-    if (cacheEnabled && cacheInstance) {
-        try {
-            const cached = await cacheInstance.get(cacheKey);
-            if (cached && new Date(cached.expiresAt) > new Date()) {
-                // Call onFetch callback
-                if (pluginConfig?.callbacks?.onFetch) {
-                    await pluginConfig.callbacks.onFetch(normalizedEmail, cached.entitlements, 'cache');
-                }
-                return {
-                    identifier: normalizedEmail,
-                    entitlements: cached.entitlements,
-                    source: 'cache',
-                    cachedAt: cached.cachedAt,
-                    expiresAt: cached.expiresAt,
-                    bySource: cached.bySource,
-                };
-            }
-        }
-        catch (error) {
-            console.error('[EntitlementsPlugin] Cache get error:', error);
-        }
-    }
-    // Fetch from sources
-    return fetchFromSources(normalizedEmail);
-}
-/**
- * Fetch entitlements from all sources and cache the result
- */
-async function fetchFromSources(email) {
-    if (!primarySource) {
-        throw new Error('Entitlements plugin not initialized');
-    }
-    const bySource = {};
-    // Fetch from primary source
-    const primaryEntitlements = await primarySource.getEntitlements(email);
-    bySource[primarySource.name] = primaryEntitlements;
-    // Fetch from additional sources in parallel
-    const additionalResults = await Promise.allSettled(additionalSources.map(async (source) => {
-        const ents = await source.getEntitlements(email);
-        return { name: source.name, entitlements: ents };
-    }));
-    for (const result of additionalResults) {
-        if (result.status === 'fulfilled') {
-            bySource[result.value.name] = result.value.entitlements;
-        }
-        else {
-            console.error('[EntitlementsPlugin] Source fetch failed:', result.reason);
-        }
-    }
-    // Merge entitlements (union of all sources, deduplicated)
-    const allEntitlements = [...new Set(Object.values(bySource).flat())].sort();
-    const now = new Date();
-    const expiresAt = new Date(now.getTime() + cacheTtl * 1000);
-    const result = {
-        identifier: email,
-        entitlements: allEntitlements,
-        source: primarySource.name,
-        cachedAt: now.toISOString(),
-        expiresAt: expiresAt.toISOString(),
-        bySource,
-    };
-    // Cache the result
-    if (cacheEnabled && cacheInstance) {
-        try {
-            const cached = {
-                email,
-                entitlements: allEntitlements,
-                bySource,
-                cachedAt: result.cachedAt,
-                expiresAt: result.expiresAt,
-                version: cacheVersion,
-            };
-            await cacheInstance.set(`entitlements:user:${email}`, cached, cacheTtl);
-        }
-        catch (error) {
-            console.error('[EntitlementsPlugin] Cache set error:', error);
-        }
-    }
-    // Call onFetch callback
-    if (pluginConfig?.callbacks?.onFetch) {
-        await pluginConfig.callbacks.onFetch(email, allEntitlements, primarySource.name);
-    }
-    return result;
-}
-/**
- * Refresh entitlements (bypass cache)
- */
-export async function refreshEntitlements(email) {
-    await invalidateEntitlementCache(email);
-    return fetchFromSources(email.toLowerCase());
-}
-/**
- * Check if user has a specific entitlement
- */
-export async function hasEntitlement(email, entitlement) {
-    const result = await getEntitlements(email);
-    return result.entitlements.includes(entitlement);
-}
-/**
- * Check if user has any of the specified entitlements
- */
-export async function hasAnyEntitlement(email, entitlements) {
-    const result = await getEntitlements(email);
-    return entitlements.some((e) => result.entitlements.includes(e));
-}
-/**
- * Check if user has all of the specified entitlements
- */
-export async function hasAllEntitlements(email, entitlements) {
-    const result = await getEntitlements(email);
-    return entitlements.every((e) => result.entitlements.includes(e));
-}
-/**
- * Grant an entitlement to a user
- * @throws Error if source is read-only
- */
-export async function grantEntitlement(email, entitlement, grantedBy) {
-    if (!primarySource) {
-        throw new Error('Entitlements plugin not initialized');
-    }
-    if (primarySource.readonly || !primarySource.addEntitlement) {
-        throw new Error('Primary entitlement source is read-only');
-    }
-    await primarySource.addEntitlement(email, entitlement, grantedBy);
-    // Invalidate cache
-    await invalidateEntitlementCache(email);
-    // Call onGrant callback
-    if (pluginConfig?.callbacks?.onGrant) {
-        await pluginConfig.callbacks.onGrant(email, entitlement, grantedBy);
-    }
-}
-/**
- * Revoke an entitlement from a user
- * @throws Error if source is read-only
- */
-export async function revokeEntitlement(email, entitlement) {
-    if (!primarySource) {
-        throw new Error('Entitlements plugin not initialized');
-    }
-    if (primarySource.readonly || !primarySource.removeEntitlement) {
-        throw new Error('Primary entitlement source is read-only');
-    }
-    await primarySource.removeEntitlement(email, entitlement);
-    // Invalidate cache
-    await invalidateEntitlementCache(email);
-    // Call onRevoke callback
-    if (pluginConfig?.callbacks?.onRevoke) {
-        await pluginConfig.callbacks.onRevoke(email, entitlement);
-    }
-}
-/**
- * Set all entitlements for a user (replaces existing)
- * Used by sync services to bulk-update user entitlements from external sources
- * @throws Error if source is read-only or doesn't support setEntitlements
- */
-export async function setEntitlements(email, entitlements) {
-    if (!primarySource) {
-        throw new Error('Entitlements plugin not initialized');
-    }
-    if (primarySource.readonly) {
-        throw new Error('Primary entitlement source is read-only');
-    }
-    if (!primarySource.setEntitlements) {
-        throw new Error('Primary entitlement source does not support setEntitlements');
-    }
-    await primarySource.setEntitlements(email, entitlements);
-    // Invalidate cache
-    await invalidateEntitlementCache(email);
-}
-/**
- * Get all available entitlement definitions
- */
-export async function getAvailableEntitlements() {
-    if (!primarySource) {
-        throw new Error('Entitlements plugin not initialized');
-    }
-    const allDefinitions = [];
-    // Get from primary source
-    if (primarySource.getAllAvailable) {
-        const defs = await primarySource.getAllAvailable();
-        allDefinitions.push(...defs);
-    }
-    // Get from additional sources
-    for (const source of additionalSources) {
-        if (source.getAllAvailable) {
-            try {
-                const defs = await source.getAllAvailable();
-                // Add source prefix to avoid collisions
-                allDefinitions.push(...defs.map((d) => ({
-                    ...d,
-                    id: `${source.name}:${d.id}`,
-                    category: d.category || source.name,
-                })));
-            }
-            catch (error) {
-                console.error(`[EntitlementsPlugin] Failed to get available from ${source.name}:`, error);
-            }
-        }
-    }
-    return allDefinitions;
-}
-/**
- * Get entitlement statistics from the primary source
- */
-export async function getEntitlementStats() {
-    if (!primarySource) {
-        throw new Error('Entitlements plugin not initialized');
-    }
-    // If source has getStats method, use it
-    if (primarySource.getStats) {
-        return primarySource.getStats();
-    }
-    // Fallback: return zeros if source doesn't support stats
-    return {
-        usersWithEntitlements: 0,
-        totalEntitlements: 0,
-    };
-}
-/**
- * Invalidate cache for an email
- */
-export async function invalidateEntitlementCache(email) {
-    if (!cacheEnabled || !cacheInstance)
-        return;
-    const normalizedEmail = email.toLowerCase();
-    try {
-        await cacheInstance.delete(`entitlements:user:${normalizedEmail}`);
-    }
-    catch (error) {
-        console.error('[EntitlementsPlugin] Cache delete error:', error);
-    }
-}
-/**
- * Store a mapping from external ID to email (for webhook invalidation)
- */
-export async function storeExternalIdMapping(source, externalId, email) {
-    if (!cacheEnabled || !cacheInstance)
-        return;
-    try {
-        await cacheInstance.set(`entitlements:mapping:${source}:${externalId}`, email.toLowerCase(), cacheMappingTtl);
-    }
-    catch (error) {
-        console.error('[EntitlementsPlugin] Store mapping error:', error);
-    }
-}
-/**
- * Invalidate cache by external ID (for webhook handling)
- */
-export async function invalidateByExternalId(source, externalId) {
-    if (!cacheEnabled || !cacheInstance)
-        return;
-    try {
-        const email = await cacheInstance.get(`entitlements:mapping:${source}:${externalId}`);
-        if (email) {
-            await invalidateEntitlementCache(email);
-        }
-    }
-    catch (error) {
-        console.error('[EntitlementsPlugin] Invalidate by external ID error:', error);
-    }
-}
-// ========================================
-// Middleware Helpers
-// ========================================
-/**
- * Express middleware to require a specific entitlement
- */
-export function requireEntitlement(entitlement) {
-    return async (req, res, next) => {
-        const authReq = req;
-        const email = authReq.auth?.user?.email;
-        if (!email) {
-            return res.status(401).json({ error: 'Authentication required' });
-        }
-        const has = await hasEntitlement(email, entitlement);
-        if (!has) {
-            return res.status(403).json({
-                error: 'Insufficient entitlements',
-                required: entitlement,
-            });
-        }
-        next();
-    };
-}
-/**
- * Express middleware to require any of the specified entitlements
- */
-export function requireAnyEntitlement(entitlements) {
-    return async (req, res, next) => {
-        const authReq = req;
-        const email = authReq.auth?.user?.email;
-        if (!email) {
-            return res.status(401).json({ error: 'Authentication required' });
-        }
-        const has = await hasAnyEntitlement(email, entitlements);
-        if (!has) {
-            return res.status(403).json({
-                error: 'Insufficient entitlements',
-                required: entitlements,
-                mode: 'any',
-            });
-        }
-        next();
-    };
-}
-/**
- * Express middleware to require all of the specified entitlements
- */
-export function requireAllEntitlements(entitlements) {
-    return async (req, res, next) => {
-        const authReq = req;
-        const email = authReq.auth?.user?.email;
-        if (!email) {
-            return res.status(401).json({ error: 'Authentication required' });
-        }
-        const has = await hasAllEntitlements(email, entitlements);
-        if (!has) {
-            return res.status(403).json({
-                error: 'Insufficient entitlements',
-                required: entitlements,
-                mode: 'all',
-            });
-        }
-        next();
-    };
-}
-//# sourceMappingURL=entitlements-plugin.js.map