@chargebee/chargebee-apps-libs 0.0.1

package/LICENSE

@@ -0,0 +1,24 @@
+The MIT License
+
+Copyright (c) 2011-2024 Chargebee, Inc.
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @chargebee/chargebee-apps-libs
+
+Library implementations for the Chargebee Apps CLI — local development, sandbox execution, logging, configuration, and the web testing UI.
+
+## Installation
+
+```bash
+npm install @chargebee/chargebee-apps-libs
+```
+
+This package is typically installed as a dependency of [`@chargebee/chargebee-apps`](https://www.npmjs.com/package/@chargebee/chargebee-apps). You can also use it directly when building tools on top of the Chargebee Apps platform.
+
+## What's included
+
+- **Configuration** — application config loading with caching and validation
+- **Logging** — structured logging and a safe console for sandboxed user code
+- **Sandbox** — VM-based secure execution for event handlers
+- **Utilities** — port validation and related helpers
+- **Templates** — starter app scaffolds used by the CLI
+- **Web UI** — browser interface for local handler testing
+
+## Templates
+
+### `serverless-node-starter-app`
+
+Basic Node.js serverless app with sample handlers, test data, and TypeScript definitions.
+
+### `serverless-node-starter-app-with-iparams`
+
+Same as the starter app, plus sectioned installation parameters:
+
+- `iparams.json` — parameter definitions under `installation_parameters.sections`
+- `iparams.local.json` — local values keyed by section name
+- Handlers receive `payload.iparams.<section>.<param>`
+
+See [`templates/serverless-node-starter-app-with-iparams/README.md`](templates/serverless-node-starter-app-with-iparams/README.md) for the full iparams schema and examples.
+
+## Usage
+
+```typescript
+import {
+	ConfigLoader,
+	createCBPublicLogger,
+	PublicSandboxWrapper,
+} from '@chargebee/chargebee-apps-libs';
+import {
+	CBFileSystem,
+	CBProcess,
+	DependencyManager,
+	ManifestValidator,
+	PackageValidator,
+} from '@chargebee/chargebee-apps-shared';
+
+const configLoader = new ConfigLoader();
+const allowedModules = configLoader.loadAllowedModules();
+
+const fileSystem = new CBFileSystem();
+const processService = new CBProcess();
+const packageValidator = new PackageValidator(fileSystem);
+const manifestValidator = new ManifestValidator(allowedModules);
+const dependencyManager = new DependencyManager(fileSystem);
+
+const manifest = manifestValidator.validateFile('./my-app/manifest.json');
+await dependencyManager.ensureDependencies('./my-app', manifest);
+
+const logger = createCBPublicLogger(fileSystem, processService, './my-app');
+
+const sandbox = new PublicSandboxWrapper(
+	allowedModules,
+	fileSystem,
+	packageValidator,
+	dependencyManager,
+	manifestValidator
+);
+
+const result = await sandbox.execute('./my-app', { event: eventData }, logger);
+```
+
+## Security
+
+- **Module whitelisting** — only approved npm modules can be used
+- **Sandboxed execution** — user code runs in isolated VM contexts
+- **Controlled logging** — user code logging is managed and correlated
+
+## Dependencies
+
+- `@chargebee/chargebee-apps-shared` — shared interfaces, validators, and utilities
+- `dotenv` — environment variable loading for local development
+
+## Related packages
+
+- [`@chargebee/chargebee-apps`](https://www.npmjs.com/package/@chargebee/chargebee-apps) — CLI for creating, running, and packaging apps
+- [`@chargebee/chargebee-apps-shared`](https://www.npmjs.com/package/@chargebee/chargebee-apps-shared) — shared types and core utilities
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,8 @@
+# Security Policy
+
+At Chargebee, we take data integrity and security very seriously. Due to the nature of the product and service we provide, we are committed to working with individuals to stay updated on the latest security techniques and fix any security weakness in our application or infrastructure reported to us responsibly by external parties.
+
+https://www.chargebee.com/security/responsible-disclosure-policy/
+
+## Reporting a vulnerability
+Reach out to us at security@chargebee.com. Please do not open GitHub issues or pull requests as this makes the problem immediately visible to everyone, including malicious actors. Chargebee's security team will triage your report and respond according to its impact.

package/config/README.md

@@ -0,0 +1,83 @@
+# Configuration
+
+This directory contains static configuration files for the Chargebee Apps CLI tool.
+
+## Files
+
+### `allowed-modules.json`
+
+Defines the list of Node.js modules that are allowed to be used in user applications. This configuration ensures security by restricting which modules can be imported in the sandbox environment.
+
+#### Structure
+
+```json
+{
+  "modules": [
+    {
+      "name": "module-name",
+      "version": "semver-range"
+    }
+  ]
+}
+```
+
+#### Fields
+
+- **name** (required): The npm package name
+- **version** (optional): A semver range that specifies allowed versions
+
+#### Example
+
+```json
+{
+  "modules": [
+    {
+      "name": "lodash",
+      "version": "^4.17.0",
+      "description": "Utility library for common JavaScript operations"
+    },
+    {
+      "name": "axios",
+      "version": "^1.0.0",
+      "description": "HTTP client for making API requests"
+    },
+    {
+      "name": "uuid",
+      "version": "^9.0.0 || ^10.0.0",
+      "description": "Generate RFC-compliant UUIDs"
+    }
+  ]
+}
+```
+
+#### Semver Version Examples
+
+The `version` field supports various semver patterns:
+
+- **All versions**: `*` (allows any version)
+- **Exact version**: `4.17.21` (only this specific version)
+- **Caret range**: `^4.17.0` (allows 4.17.x but not 5.0.0)
+- **Tilde range**: `~4.17.0` (allows 4.17.x but not 4.18.0)
+- **Range**: `>=4.17.0 <5.0.0` (custom range)
+- **Multiple ranges**: `^9.0.0 || ^10.0.0` (allows either 9.x.x or 10.x.x)
+
+## Usage
+
+The configuration is loaded by the `ConfigLoader` class in `src/libs/config-loader.ts` and used by the sandbox environment to validate user dependencies.
+
+## Notes
+
+- This is static configuration that doesn't change during runtime
+- Located in the root directory for easy access and modification
+- Used by the sandbox to enforce security restrictions
+
+## Future Plans
+
+**⚠️ Temporary Implementation**: This static JSON configuration is a temporary solution. In the future, the allowed modules configuration will be moved to a dynamic API that will be served by Chargebee. This will allow for:
+
+- **Dynamic updates**: Module allowlist can be updated without CLI releases
+- **Centralized management**: All configurations managed by Chargebee
+- **Real-time changes**: Immediate updates to security policies
+- **Better scalability**: Support for more complex module management
+
+The current static JSON approach is maintained for development and testing purposes until the API integration is complete. 

package/config/allowed-modules.json

@@ -0,0 +1,24 @@
+{
+    "modules": [
+        {
+            "name": "lodash",
+            "version": "^4.17.0",
+            "description": "Utility library for common JavaScript operations"
+        },
+        {
+            "name": "axios",
+            "version": "^1.0.0",
+            "description": "HTTP client for making API requests"
+        },
+        {
+            "name": "uuid",
+            "version": "^9.0.0 || ^10.0.0",
+            "description": "Generate RFC-compliant UUIDs"
+        },
+        {
+            "name": "chargebee",
+            "version": "^3.0.0",
+            "description": "Chargebee SDK for Node.js"
+        }
+    ]
+} 

package/dist/config/config-loader.d.ts

@@ -0,0 +1,24 @@
+import { AllowedModule, CBFileSystem } from '@chargebee/chargebee-apps-shared';
+/**
+ * ConfigLoader provides utilities for loading and managing configuration files
+ * Public implementation for loading allowed modules configuration
+ */
+export declare class ConfigLoader {
+    private cache;
+    private fileSystem;
+    constructor(fileSystem: CBFileSystem);
+    /**
+     * Loads and validates the allowed modules configuration
+     * @returns {AllowedModule[]} Array of validated allowed modules
+     * @throws {Error} If configuration is invalid or cannot be loaded
+     */
+    loadAllowedModules(): AllowedModule[];
+    /**
+     * Loads a JSON configuration file with caching
+     * @param {string} configPath - Path to the configuration file
+     * @param {boolean} useCache - Whether to use cached version if available
+     * @returns {any} Parsed configuration object
+     * @throws {Error} If file cannot be loaded or parsed
+     */
+    loadConfig(configPath: string, useCache?: boolean): any;
+}

package/dist/config/config-loader.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigLoader = void 0;
+const chargebee_apps_shared_1 = require("@chargebee/chargebee-apps-shared");
+const path_1 = __importDefault(require("path"));
+const semver_1 = __importDefault(require("semver"));
+/**
+ * ConfigLoader provides utilities for loading and managing configuration files
+ * Public implementation for loading allowed modules configuration
+ */
+class ConfigLoader {
+    constructor(fileSystem) {
+        this.fileSystem = fileSystem;
+        this.cache = new Map();
+    }
+    /**
+     * Loads and validates the allowed modules configuration
+     * @returns {AllowedModule[]} Array of validated allowed modules
+     * @throws {Error} If configuration is invalid or cannot be loaded
+     */
+    loadAllowedModules() {
+        try {
+            // Get config file path
+            let configPath;
+            try {
+                // Production: Find @chargebee/chargebee-apps-libs package and get config from package root
+                const packageJsonPath = require.resolve('@chargebee/chargebee-apps-libs');
+                const packageRoot = path_1.default.dirname(path_1.default.dirname(packageJsonPath));
+                configPath = path_1.default.join(packageRoot, 'config', 'allowed-modules.json');
+            }
+            catch (error) {
+                chargebee_apps_shared_1.__logger.error('Error: Failed to find allowed modules in the published package', error);
+                // Development: Use relative path
+                configPath = path_1.default.join(__dirname, '../../config/allowed-modules.json');
+            }
+            const config = this.loadConfig(configPath);
+            if (!config.modules || !Array.isArray(config.modules)) {
+                throw new Error('Invalid allowed modules format: "modules" must be an array');
+            }
+            const validatedModules = config.modules.map((module, index) => {
+                if (!module.name || typeof module.name !== 'string') {
+                    throw new Error(`Invalid module at index ${index}: "name" must be a string`);
+                }
+                if (module.version && typeof module.version !== 'string') {
+                    throw new Error(`Invalid module "${module.name}": "version" must be a string`);
+                }
+                if (module.version && !semver_1.default.validRange(module.version)) {
+                    throw new Error(`Invalid semver range "${module.version}" for module "${module.name}"`);
+                }
+                return module;
+            });
+            chargebee_apps_shared_1.__logger.debug(`Loaded ${validatedModules.length} allowed modules from configuration`);
+            return validatedModules;
+        }
+        catch (error) {
+            const err = error;
+            chargebee_apps_shared_1.__logger.error('Failed to load allowed-modules.json:', err.message);
+            throw err;
+        }
+    }
+    /**
+     * Loads a JSON configuration file with caching
+     * @param {string} configPath - Path to the configuration file
+     * @param {boolean} useCache - Whether to use cached version if available
+     * @returns {any} Parsed configuration object
+     * @throws {Error} If file cannot be loaded or parsed
+     */
+    loadConfig(configPath, useCache = true) {
+        const absolutePath = path_1.default.resolve(configPath);
+        // Check cache first
+        if (useCache && this.cache.has(absolutePath)) {
+            return this.cache.get(absolutePath);
+        }
+        try {
+            if (!this.fileSystem.existsSync(absolutePath)) {
+                throw new Error(`Configuration file not found: ${absolutePath}`);
+            }
+            const configContent = this.fileSystem.readFileSync(absolutePath, 'utf8');
+            const config = JSON.parse(configContent);
+            // Cache the result
+            if (useCache) {
+                this.cache.set(absolutePath, config);
+            }
+            return config;
+        }
+        catch (error) {
+            const err = error;
+            throw new Error(`Failed to load configuration from ${absolutePath}: ${err.message}`);
+        }
+    }
+}
+exports.ConfigLoader = ConfigLoader;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './config/config-loader';
+export * from './libs/port-service';
+export * from './logger/cb-public-logger';
+export * from './sandbox/public-sandbox-wrapper';

package/dist/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Export all public library implementations
+__exportStar(require("./config/config-loader"), exports);
+__exportStar(require("./libs/port-service"), exports);
+__exportStar(require("./logger/cb-public-logger"), exports);
+__exportStar(require("./sandbox/public-sandbox-wrapper"), exports);

package/dist/libs/port-service.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Port parsing service
+ */
+export declare class PortService {
+    constructor();
+    /**
+     * Validates port number
+     * @param {string} port - Port string input
+     * @returns {boolean} True if port is valid
+     */
+    isValidPort(port: string): boolean;
+    /**
+     * Parses port number from string input
+     * @param {string} port - Port string input
+     * @returns {number} Parsed port number or default
+     */
+    parsePort(port: string): number;
+}

package/dist/libs/port-service.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PortService = void 0;
+/**
+ * Port parsing service
+ */
+class PortService {
+    constructor() { }
+    /**
+     * Validates port number
+     * @param {string} port - Port string input
+     * @returns {boolean} True if port is valid
+     */
+    isValidPort(port) {
+        const parsedPort = parseInt(port);
+        return !isNaN(parsedPort);
+    }
+    /**
+     * Parses port number from string input
+     * @param {string} port - Port string input
+     * @returns {number} Parsed port number or default
+     */
+    parsePort(port) {
+        return parseInt(port);
+    }
+}
+exports.PortService = PortService;

package/dist/logger/cb-public-logger.d.ts

@@ -0,0 +1,59 @@
+import { CBFileSystem, CBProcess, ICBLogger, SafeConsole } from '@chargebee/chargebee-apps-shared';
+import winston from 'winston';
+/**
+ * Public logger implementation for local development
+ * This logger provides controlled logging capabilities for sandboxed code execution
+ * with correlation context and formatted output using Winston
+ */
+export declare class CBPublicLogger implements ICBLogger {
+    private logger;
+    private userCodeDir;
+    private fileSystem;
+    private process;
+    constructor(fileSystem: CBFileSystem, process: CBProcess, userCodeDir: string);
+    /**
+     * Creates a Winston logger with console and file transports
+     * @returns {winston.Logger} Configured Winston logger instance
+     */
+    protected createWinstonLogger(): winston.Logger;
+    /**
+     * Logs an info message
+     * @param {...any[]} args - The message arguments to log
+     */
+    info(...args: any[]): void;
+    /**
+     * Logs a warning message
+     * @param {...any[]} args - The message arguments to log
+     */
+    warn(...args: any[]): void;
+    /**
+     * Logs an error message
+     * @param {...any[]} args - The message arguments to log
+     */
+    error(...args: any[]): void;
+    /**
+     * Logs a debug message
+     * @param {...any[]} args - The message arguments to log
+     */
+    debug(...args: any[]): void;
+    /**
+     * Formats a message with timestamp and level
+     * @param {winston.Logform.TransformableInfo} info - The log info
+     * @returns {string} The formatted message
+     */
+    formatMessage(info: winston.Logform.TransformableInfo): string;
+}
+/**
+ * Creates a safe console object that uses the logger
+ * @param {ICBLogger} logger - The logger instance to use
+ * @returns {SafeConsole} A safe console object
+ */
+export declare function createSafeConsole(logger: ICBLogger): SafeConsole;
+/**
+ * Creates a new CBPublicLogger instance for a specific user code directory
+ * @param {CBFileSystem} fileSystem - The filesystem implementation to use
+ * @param {CBProcess} process - The process implementation to use
+ * @param {string} userCodeDir - The user code directory where logs should be stored
+ * @returns {CBPublicLogger} A new CBPublicLogger instance
+ */
+export declare function createCBPublicLogger(fileSystem: CBFileSystem, process: CBProcess, userCodeDir: string): CBPublicLogger;

package/dist/logger/cb-public-logger.js

@@ -0,0 +1,158 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CBPublicLogger = void 0;
+exports.createSafeConsole = createSafeConsole;
+exports.createCBPublicLogger = createCBPublicLogger;
+const chargebee_apps_shared_1 = require("@chargebee/chargebee-apps-shared");
+const path_1 = __importDefault(require("path"));
+const winston_1 = __importDefault(require("winston"));
+/**
+ * Public logger implementation for local development
+ * This logger provides controlled logging capabilities for sandboxed code execution
+ * with correlation context and formatted output using Winston
+ */
+class CBPublicLogger {
+    constructor(fileSystem, process, userCodeDir) {
+        this.userCodeDir = userCodeDir || process.cwd();
+        this.fileSystem = fileSystem;
+        this.process = process;
+        this.logger = this.createWinstonLogger();
+    }
+    /**
+     * Creates a Winston logger with console and file transports
+     * @returns {winston.Logger} Configured Winston logger instance
+     */
+    createWinstonLogger() {
+        // Get current log level from environment
+        const currentLogLevel = this.process.env['CB_LOG_LEVEL'] || chargebee_apps_shared_1.LogLevel.INFO;
+        try {
+            // Use the user code directory (where the logs should be stored)
+            const logsDir = path_1.default.join(this.userCodeDir, 'logs');
+            const logFilePath = path_1.default.join(logsDir, 'cb.log');
+            // Create logs directory if it doesn't exist
+            if (!this.fileSystem.existsSync(logsDir)) {
+                this.fileSystem.mkdirSync(logsDir, { recursive: true });
+            }
+            // Clear the log file on each run by writing an empty string
+            this.fileSystem.writeFileSync(logFilePath, '');
+            // Create transports
+            const transports = [
+                // Console transport for development output
+                new winston_1.default.transports.Console({
+                    level: currentLogLevel.toLowerCase(),
+                    format: winston_1.default.format.combine(winston_1.default.format.timestamp(), winston_1.default.format.colorize(), winston_1.default.format.errors({ stack: true }), winston_1.default.format.printf((info) => {
+                        return this.formatMessage(info);
+                    }))
+                }),
+                // Single file transport for all logs
+                new winston_1.default.transports.File({
+                    filename: logFilePath,
+                    level: currentLogLevel.toLowerCase(),
+                    format: winston_1.default.format.combine(winston_1.default.format.errors({ stack: true }), winston_1.default.format.printf((info) => {
+                        return this.formatMessage(info);
+                    }))
+                })
+            ];
+            return winston_1.default.createLogger({
+                level: currentLogLevel.toLowerCase(),
+                format: winston_1.default.format.combine(winston_1.default.format.timestamp(), winston_1.default.format.errors({ stack: true })),
+                transports
+            });
+        }
+        catch (error) {
+            // Fallback to console if Winston initialization fails
+            chargebee_apps_shared_1.__logger.error('Failed to initialize Winston logger:', error);
+            // Return a minimal logger that just logs to console
+            return winston_1.default.createLogger({
+                level: currentLogLevel.toLowerCase(),
+                transports: [
+                    new winston_1.default.transports.Console({
+                        format: winston_1.default.format.simple()
+                    })
+                ]
+            });
+        }
+    }
+    /**
+     * Logs an info message
+     * @param {...any[]} args - The message arguments to log
+     */
+    info(...args) {
+        this.logger.info(args.join(' '));
+    }
+    /**
+     * Logs a warning message
+     * @param {...any[]} args - The message arguments to log
+     */
+    warn(...args) {
+        this.logger.warn(args.join(' '));
+    }
+    /**
+     * Logs an error message
+     * @param {...any[]} args - The message arguments to log
+     */
+    error(...args) {
+        this.logger.error(args.join(' '));
+    }
+    /**
+     * Logs a debug message
+     * @param {...any[]} args - The message arguments to log
+     */
+    debug(...args) {
+        this.logger.debug(args.join(' '));
+    }
+    /**
+     * Formats a message with timestamp and level
+     * @param {winston.Logform.TransformableInfo} info - The log info
+     * @returns {string} The formatted message
+     */
+    formatMessage(info) {
+        const timestamp = info['timestamp'];
+        const level = info.level;
+        const message = info.message;
+        const context = chargebee_apps_shared_1.sandboxContext.getCurrentContext();
+        const eventId = context?.eventId || 'unknown';
+        const eventType = context?.eventType || 'unknown';
+        return `${timestamp} [${level}] [${eventId}] [${eventType}] ${message}`;
+    }
+}
+exports.CBPublicLogger = CBPublicLogger;
+/**
+ * Creates a safe console object that uses the logger
+ * @param {ICBLogger} logger - The logger instance to use
+ * @returns {SafeConsole} A safe console object
+ */
+function createSafeConsole(logger) {
+    return Object.freeze({
+        log: (...args) => logger.info(...args),
+        info: (...args) => logger.info(...args),
+        warn: (...args) => logger.warn(...args),
+        error: (...args) => logger.error(...args),
+        debug: (...args) => logger.debug(...args),
+        // Disable potentially dangerous console methods
+        trace: () => { },
+        table: () => { },
+        time: () => { },
+        timeEnd: () => { },
+        timeLog: () => { },
+        count: () => { },
+        countReset: () => { },
+        group: () => { },
+        groupCollapsed: () => { },
+        groupEnd: () => { },
+        clear: () => { }
+    });
+}
+/**
+ * Creates a new CBPublicLogger instance for a specific user code directory
+ * @param {CBFileSystem} fileSystem - The filesystem implementation to use
+ * @param {CBProcess} process - The process implementation to use
+ * @param {string} userCodeDir - The user code directory where logs should be stored
+ * @returns {CBPublicLogger} A new CBPublicLogger instance
+ */
+function createCBPublicLogger(fileSystem, process, userCodeDir) {
+    return new CBPublicLogger(fileSystem, process, userCodeDir);
+}