seabox 0.1.0-beta.1

package/.mocharc.json

@@ -0,0 +1,6 @@
+{
+  "spec": "test/**/*.spec.js",
+  "timeout": 60000,
+  "reporter": "spec",
+  "color": true
+}

package/LICENSE.MD

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Meirion Hughes
+
+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,209 @@
+# seabox
+
+A reusable tool for building Node.js Single Executable Applications (SEA) with native-module support.
+
+## Features
+
+- Bundle Node.js applications into standalone executables
+- Automatic native module (.node, .dll, .so, .dylib) extraction and loading
+- Asset encryption with obfuscated keys embedded in V8 snapshots
+- Multi-platform targeting (Windows, Linux, macOS)
+- V8 snapshot support for faster startup
+- Integrity checking for extracted binaries
+- Automatic code signature removal before injection
+- Simple configuration via package.json
+
+## Installation
+
+```bash
+npm install --save-dev seabox
+```
+
+## Configuration
+
+Add a `sea` configuration to your `package.json`:
+
+```json
+{
+  "sea": {
+    "entry": "./out/server.js",
+    "assets": [
+      "./out/client/**/*",
+      "./out/lib/**/*",
+      "./out/native/**/*",
+      "!**/*.md",
+      "!**/test/**"
+    ],
+    "binaries": [
+      "*.node",
+      "*.dll"
+    ],
+    "targets": [
+      "node24.11.0-win32-x64"
+    ],
+    "output": "myapp.exe",
+    "outputPath": "dist",
+    "disableExperimentalSEAWarning": true,
+    "useSnapshot": true,
+    "useCodeCache": false
+  }
+}
+```
+
+## Configuration Options
+
+- **entry**: Path to your bundled application entry point
+- **assets**: Array of glob patterns for files to include (supports `!` prefix for exclusions, e.g., `"!**/*.md"`)
+- **binaries**: Patterns to identify binary files that need extraction (e.g., `.node`, `.dll`)
+- **targets**: Array of target platforms (format: `nodeX.Y.Z-platform-arch`)
+- **output**: Name of the output executable
+- **outputPath**: Directory for build output
+- **disableExperimentalSEAWarning**: Suppress Node.js SEA experimental warnings (default: true)
+- **useSnapshot**: Enable V8 snapshot for faster startup (default: false)
+- **useCodeCache**: Enable V8 code cache (default: false)
+- **encryptAssets**: Enable encryption for assets (default: false)
+- **encryptExclude**: Patterns to exclude from encryption (e.g., `['*.txt']`)
+- **exclude**: *(Deprecated)* Use `!` prefix in assets array instead
+
+## Usage
+
+After installing `seabox` as a dev dependency and configuring your `package.json`, build your SEA executable:
+
+### npm script (recommended)
+
+Add a build script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build:exe": "seabox",
+    "build:exe:verbose": "seabox --verbose"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run build:exe
+```
+
+### CLI
+
+```bash
+# Build using package.json configuration
+npx seabox
+
+# Verbose output
+npx seabox --verbose
+```
+
+### Programmatic API
+
+```javascript
+const { build } = require('seabox');
+
+await build({
+  projectRoot: process.cwd(),
+  verbose: true
+});
+```
+
+## How It Works
+
+1. **Asset Scanning**: Scans and resolves all files matching your asset patterns
+2. **Manifest Generation**: Creates a runtime manifest with metadata for binary extraction
+3. **Bootstrap Injection**: Prepends bootstrap code to handle native module extraction
+4. **Blob Creation**: Uses Node.js SEA tooling to create the application blob
+5. **Binary Fetching**: Downloads the target Node.js binary and removes its signature
+6. **Injection**: Uses postject to inject the blob into the Node binary
+7. **Output**: Produces a standalone executable ready for signing and distribution
+
+## Binary Extraction
+
+Native modules (`.node`, `.dll`, `.so`, `.dylib`) are automatically:
+- Extracted to a cache directory on first run
+- Integrity-checked using SHA-256 hashes
+- Loaded via custom module resolution
+
+Cache location: `%LOCALAPPDATA%\.sea-cache\<appname>\<version>-<platform>-<arch>`
+
+## Native Module Rebuilding
+
+If your project has native modules (e.g., `.node` bindings), you may need to rebuild them for the target Node.js version:
+
+```bash
+# Rebuild for a specific target
+npx seabox-rebuild --target node24.11.0-win32-x64
+
+# Rebuild with separate options
+npx seabox-rebuild --node-version 24.11.0 --platform linux --arch x64
+
+# Rebuild in a specific directory
+npx seabox-rebuild /path/to/project --target node24.11.0-linux-x64
+```
+
+The rebuilder will:
+- Scan all dependencies for native modules (those with `binding.gyp` or `gypfile: true`)
+- Rebuild each one using `node-gyp` for the target platform and Node.js version
+- Download necessary headers for cross-compilation
+
+**Note**: Cross-compilation may require additional platform-specific build tools installed.
+
+## Asset Encryption
+
+seabox supports optional AES-256-GCM encryption of embedded assets to protect your application code and data:
+
+```json
+{
+  "sea": {
+    "encryptAssets": true,
+    "encryptExclude": ["*.txt", "public/*"],
+    "useSnapshot": true
+  }
+}
+```
+
+### How Encryption Works
+
+1. **Build Time**: A random 256-bit encryption key is generated
+2. **Asset Encryption**: Non-binary assets are encrypted using AES-256-GCM
+3. **Key Embedding**: The encryption key is obfuscated and embedded in the bootstrap code
+4. **Snapshot Obfuscation**: When `useSnapshot: true`, the key becomes part of V8 bytecode
+5. **Runtime Decryption**: Assets are transparently decrypted when accessed
+
+### Security Considerations
+
+- **Binary files** (`.node`, `.dll`, `.so`, `.dylib`) are **never encrypted** as they must be extracted as-is
+- The manifest (`sea-manifest.json`) is **not encrypted** to allow bootstrap initialization
+- Encryption provides **obfuscation**, not cryptographic security against determined attackers
+- When combined with V8 snapshots, the encryption key is compiled into bytecode, making extraction significantly harder
+- Use `encryptExclude` to skip encryption for non-sensitive assets (e.g., public files, documentation)
+
+### Best Practices
+
+```json
+{
+  "sea": {
+    "encryptAssets": true,
+    "useSnapshot": true,           // Strongly recommended with encryption
+    "assets": [
+      "./out/**/*",
+      "!**/*.md",                  // Exclude documentation
+      "!**/public/**",             // Exclude public assets
+      "!**/LICENSE"                // Exclude license files
+    ]
+  }
+}
+```
+
+## Platform Support
+
+- **Windows**: `win32-x64`, `win32-arm64`
+- **Linux**: `linux-x64`, `linux-arm64`
+- **macOS**: `darwin-x64`, `darwin-arm64`
+
+## License
+
+MIT
+Copyright Meirion Hughes 2025

package/bin/seabox-rebuild.js

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+
+/**
+ * Native Module Rebuilder for SEA Builder
+ * 
+ * Scans package dependencies to identify native modules (those with binding.gyp
+ * or gypfile: true in package.json) and rebuilds them using node-gyp for a
+ * target Node.js version and platform.
+ * 
+ * Supports cross-compilation for different platforms and architectures.
+ * Inspired by @electron/rebuild's module identification strategy.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+class NativeModuleRebuilder {
+  constructor(buildPath, options = {}) {
+    this.buildPath = buildPath || process.cwd();
+    this.nativeModules = new Map();
+    this.visitedPaths = new Set();
+    
+    // Target configuration
+    this.targetNodeVersion = options.nodeVersion || process.version.replace('v', '');
+    this.targetPlatform = options.platform || process.platform;
+    this.targetArch = options.arch || process.arch;
+    
+    // Parse from target string if provided (e.g., "node24.11.0-win32-x64")
+    if (options.target) {
+      const match = options.target.match(/^node(\d+\.\d+\.\d+)-(\w+)-(\w+)$/);
+      if (match) {
+        this.targetNodeVersion = match[1];
+        this.targetPlatform = match[2];
+        this.targetArch = match[3];
+      }
+    }
+  }
+
+  /**
+   * Read and parse package.json from a directory
+   */
+  readPackageJson(modulePath) {
+    const packageJsonPath = path.join(modulePath, 'package.json');
+    try {
+      if (fs.existsSync(packageJsonPath)) {
+        const content = fs.readFileSync(packageJsonPath, 'utf8');
+        return JSON.parse(content);
+      }
+    } catch (error) {
+      console.warn(`Warning: Could not read package.json at ${packageJsonPath}:`, error.message);
+    }
+    return null;
+  }
+
+  /**
+   * Check if a module is a native module
+   * A module is considered native if it has:
+   * - A binding.gyp file, OR
+   * - gypfile: true in package.json
+   */
+  isNativeModule(modulePath) {
+    // Check for binding.gyp
+    const bindingGypPath = path.join(modulePath, 'binding.gyp');
+    if (fs.existsSync(bindingGypPath)) {
+      return true;
+    }
+
+    // Check for gypfile: true in package.json
+    const packageJson = this.readPackageJson(modulePath);
+    if (packageJson && packageJson.gypfile === true) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Resolve the actual path of a dependency
+   */
+  resolveDependencyPath(fromPath, depName) {
+    const possiblePaths = [];
+    
+    // Check in local node_modules
+    let currentPath = fromPath;
+    while (currentPath !== path.parse(currentPath).root) {
+      const nodeModulesPath = path.join(currentPath, 'node_modules', depName);
+      if (fs.existsSync(nodeModulesPath)) {
+        possiblePaths.push(nodeModulesPath);
+      }
+      currentPath = path.dirname(currentPath);
+    }
+
+    // Return the first valid path, resolving symlinks
+    for (const testPath of possiblePaths) {
+      try {
+        return fs.realpathSync(testPath);
+      } catch (error) {
+        // Skip if symlink is broken
+        continue;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Scan a directory's dependencies recursively
+   */
+  scanDependencies(modulePath, depth = 0) {
+    // Resolve symlinks to avoid scanning the same module multiple times
+    let realPath;
+    try {
+      realPath = fs.realpathSync(modulePath);
+    } catch (error) {
+      console.warn(`Warning: Could not resolve path ${modulePath}:`, error.message);
+      return;
+    }
+
+    // Skip if already visited
+    if (this.visitedPaths.has(realPath)) {
+      return;
+    }
+    this.visitedPaths.add(realPath);
+
+    // Check if this module is a native module
+    if (this.isNativeModule(realPath)) {
+      const packageJson = this.readPackageJson(realPath);
+      const moduleName = packageJson ? packageJson.name : path.basename(realPath);
+      
+      if (!this.nativeModules.has(realPath)) {
+        this.nativeModules.set(realPath, moduleName);
+        console.log(`Found native module: ${moduleName} at ${realPath}`);
+      }
+    }
+
+    // Read package.json to find dependencies
+    const packageJson = this.readPackageJson(realPath);
+    if (!packageJson) {
+      return;
+    }
+
+    // Collect all types of dependencies
+    const allDeps = {
+      ...packageJson.dependencies,
+      ...packageJson.optionalDependencies,
+      ...packageJson.devDependencies
+    };
+
+    // Scan each dependency
+    for (const depName of Object.keys(allDeps)) {
+      const depPath = this.resolveDependencyPath(realPath, depName);
+      if (depPath) {
+        this.scanDependencies(depPath, depth + 1);
+      }
+    }
+
+    // Also check nested node_modules
+    const nodeModulesPath = path.join(realPath, 'node_modules');
+    if (fs.existsSync(nodeModulesPath)) {
+      try {
+        const modules = fs.readdirSync(nodeModulesPath);
+        for (const moduleName of modules) {
+          if (moduleName === '.bin') continue;
+          
+          const modulePath = path.join(nodeModulesPath, moduleName);
+          const stat = fs.lstatSync(modulePath);
+          
+          if (stat.isDirectory()) {
+            // Handle scoped packages (e.g., @robgeoltd/lib-m2)
+            if (moduleName.startsWith('@')) {
+              const scopedModules = fs.readdirSync(modulePath);
+              for (const scopedModule of scopedModules) {
+                const scopedPath = path.join(modulePath, scopedModule);
+                this.scanDependencies(scopedPath, depth + 1);
+              }
+            } else {
+              this.scanDependencies(modulePath, depth + 1);
+            }
+          }
+        }
+      } catch (error) {
+        console.warn(`Warning: Could not read node_modules at ${nodeModulesPath}:`, error.message);
+      }
+    }
+  }
+
+  /**
+   * Get platform-specific configuration for cross-compilation
+   */
+  getCrossCompileEnv() {
+    const env = { ...process.env };
+    
+    // Set target platform and architecture
+    if (this.targetPlatform !== process.platform) {
+      console.log(`  Cross-compiling for platform: ${this.targetPlatform}`);
+    }
+    if (this.targetArch !== process.arch) {
+      console.log(`  Cross-compiling for architecture: ${this.targetArch}`);
+    }
+    
+    // Map common arch names to node-gyp format
+    const archMap = {
+      'x64': 'x64',
+      'ia32': 'ia32',
+      'arm': 'arm',
+      'arm64': 'arm64'
+    };
+    
+    env.npm_config_target = this.targetNodeVersion;
+    env.npm_config_arch = archMap[this.targetArch] || this.targetArch;
+    env.npm_config_target_arch = archMap[this.targetArch] || this.targetArch;
+    env.npm_config_disturl = 'https://nodejs.org/dist';
+    env.npm_config_runtime = 'node';
+    env.npm_config_build_from_source = 'true';
+    
+    return env;
+  }
+
+  /**
+   * Rebuild a native module using node-gyp for the target platform
+   */
+  rebuildModule(modulePath, moduleName) {
+    console.log(`\nRebuilding ${moduleName}...`);
+    console.log(`  Path: ${modulePath}`);
+    console.log(`  Target: Node.js ${this.targetNodeVersion} (${this.targetPlatform}-${this.targetArch})`);
+    
+    // Determine if we should use npx node-gyp or just node-gyp
+    let useNpx = false;
+    try {
+      execSync('node-gyp --version', { stdio: 'pipe' });
+    } catch (error) {
+      useNpx = true;
+    }
+    
+    const nodeGypCmd = useNpx ? 'npx node-gyp' : 'node-gyp';
+    
+    try {
+      const env = this.getCrossCompileEnv();
+      
+      // Clean previous builds
+      try {
+        execSync(`${nodeGypCmd} clean`, {
+          cwd: modulePath,
+          stdio: 'pipe',
+          env
+        });
+      } catch (cleanError) {
+        // Ignore clean errors
+      }
+      
+      // Configure for target
+      const configureCmd = `${nodeGypCmd} configure --target=${this.targetNodeVersion} --arch=${this.targetArch} --dist-url=https://nodejs.org/dist`;
+      execSync(configureCmd, {
+        cwd: modulePath,
+        stdio: 'inherit',
+        env
+      });
+      
+      // Build
+      execSync(`${nodeGypCmd} build`, {
+        cwd: modulePath,
+        stdio: 'inherit',
+        env
+      });
+      
+      console.log(`✓ Successfully rebuilt ${moduleName}`);
+      return true;
+    } catch (error) {
+      console.error(`✗ Failed to rebuild ${moduleName}:`, error.message);
+      return false;
+    }
+  }
+
+  /**
+   * Main rebuild process
+   */
+  async rebuild() {
+    console.log('Starting native module rebuild process...');
+    console.log(`Build path: ${this.buildPath}`);
+    console.log(`Target: Node.js ${this.targetNodeVersion} (${this.targetPlatform}-${this.targetArch})\n`);
+
+    // Verify node-gyp is available
+    try {
+      execSync('node-gyp --version', { stdio: 'pipe' });
+    } catch (error) {
+      // Try with npx
+      try {
+        execSync('npx node-gyp --version', { stdio: 'pipe' });
+      } catch (npxError) {
+        console.error('Error: node-gyp is not installed or not in PATH');
+        console.error('Install it with: npm install -g node-gyp');
+        console.error('Or ensure it is in your project dependencies');
+        process.exit(1);
+      }
+    }
+
+    // Scan for native modules
+    console.log('Scanning dependencies for native modules...\n');
+    this.scanDependencies(this.buildPath);
+
+    if (this.nativeModules.size === 0) {
+      console.log('\nNo native modules found.');
+      return;
+    }
+
+    console.log(`\nFound ${this.nativeModules.size} native module(s) to rebuild.\n`);
+    console.log('='.repeat(60));
+
+    // Rebuild each native module
+    let successCount = 0;
+    let failCount = 0;
+
+    for (const [modulePath, moduleName] of this.nativeModules) {
+      const success = this.rebuildModule(modulePath, moduleName);
+      if (success) {
+        successCount++;
+      } else {
+        failCount++;
+      }
+    }
+
+    // Summary
+    console.log('\n' + '='.repeat(60));
+    console.log('\nRebuild Summary:');
+    console.log(`  Total modules: ${this.nativeModules.size}`);
+    console.log(`  Successful: ${successCount}`);
+    console.log(`  Failed: ${failCount}`);
+
+    if (failCount > 0) {
+      console.log('\nSome modules failed to rebuild. Check the errors above.');
+      process.exit(1);
+    } else {
+      console.log('\n✓ All native modules rebuilt successfully!');
+    }
+  }
+}
+
+// Main execution
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  
+  // Parse command line arguments
+  const options = {};
+  let buildPath = process.cwd();
+  
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    
+    if (arg === '--target' && args[i + 1]) {
+      options.target = args[i + 1];
+      i++;
+    } else if (arg === '--node-version' && args[i + 1]) {
+      options.nodeVersion = args[i + 1];
+      i++;
+    } else if (arg === '--platform' && args[i + 1]) {
+      options.platform = args[i + 1];
+      i++;
+    } else if (arg === '--arch' && args[i + 1]) {
+      options.arch = args[i + 1];
+      i++;
+    } else if (arg === '--help' || arg === '-h') {
+      console.log(`
+seabox-rebuild - Rebuild native modules for target Node.js version
+
+Usage:
+  seabox-rebuild [options] [build-path]
+
+Options:
+  --target <target>           Target in format: nodeX.Y.Z-platform-arch
+                              Example: node24.11.0-win32-x64
+  --node-version <version>    Target Node.js version (e.g., 24.11.0)
+  --platform <platform>       Target platform (win32, linux, darwin)
+  --arch <arch>               Target architecture (x64, arm64, ia32)
+  --help, -h                  Show this help message
+
+Examples:
+  seabox-rebuild --target node24.11.0-win32-x64
+  seabox-rebuild --node-version 24.11.0 --platform linux --arch x64
+  seabox-rebuild /path/to/project
+`);
+      process.exit(0);
+    } else if (!arg.startsWith('--')) {
+      buildPath = arg;
+    }
+  }
+  
+  const rebuilder = new NativeModuleRebuilder(buildPath, options);
+  rebuilder.rebuild().catch(error => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+  });
+}
+
+module.exports = { NativeModuleRebuilder };

package/bin/seabox.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/**
+ * CLI entry point for SEA builder
+ */
+
+const { build } = require('../lib');
+const fs = require('fs');
+const path = require('path');
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  const configPath = args.includes('--config') ? args[args.indexOf('--config') + 1] : undefined;
+  const verbose = args.includes('--verbose');
+  const debug = args.includes('--debug');
+
+  let showHelp = args.includes('--help') || args.includes('-h');
+
+  // Try to load config to check if it exists
+  if (!configPath) {
+    const pkgPath = path.join(process.cwd(), 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      showHelp = true;
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    if (!pkg.seabox) {
+      showHelp = true;
+    }
+  }
+
+  // Show help
+  if (showHelp) {
+    console.log(`
+SEA Builder - Node.js Single Executable Application Builder
+
+Usage:
+  seabox [options]
+
+Options:
+  --config <path>    Path to config file (default: reads from package.json)
+  --verbose          Enable verbose logging
+  --debug            Keep temporary build files for debugging
+  --help, -h         Show this help message
+
+Configuration:
+  Add a "seabox" field to your package.json:
+  {
+    "seabox": {
+      "entry": "./out/app.js",
+      "assets": ["./out/**/*"],
+      "binaries": ["*.node", "*.dll"],
+      "targets": ["node24.11.0-win32-x64"],
+      "output": "myapp.exe",
+      "outputPath": "dist",
+      "useSnapshot": false
+    }
+  }
+
+For more information, see the documentation.
+`);
+
+  }
+
+  try {
+    await build({
+      configPath,
+      verbose,
+      debug,
+      projectRoot: process.cwd()
+    });
+  } catch (error) {
+    console.error('Build failed:', error.message);
+    if (verbose) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+main();