seabox 0.1.0-beta.1

package/lib/build.js

@@ -0,0 +1,283 @@
+/**
+ * build.js
+ * Main orchestrator for SEA build pipeline.
+ * Usage: node scripts/sea/build.js [--config <path>] [--verbose]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { loadConfig, parseTarget } = require('./config');
+const { scanAssets, groupAssets } = require('./scanner');
+const { generateManifest, serializeManifest } = require('./manifest');
+const { createSeaConfig, writeSeaConfigJson, generateBlob } = require('./blob');
+const { fetchNodeBinary } = require('./fetch-node');
+const { injectBlob } = require('./inject');
+const { generateEncryptionKey, encryptAssets, keyToObfuscatedCode } = require('./crypto-assets');
+const { obfuscateBootstrap } = require('./obfuscate');
+const { execSync } = require('child_process');
+
+/**
+ * Main build orchestrator.
+ * @param {Object} options - Build options
+ * @param {string} [options.configPath] - Path to config file
+ * @param {boolean} [options.verbose] - Enable verbose logging
+ * @param {boolean} [options.debug] - Keep temporary build files
+ * @param {string} [options.projectRoot] - Project root directory
+ */
+async function build(options = {}) {
+  // Support both options object and legacy process.argv parsing
+  let configPath = options.configPath;
+  let verbose = options.verbose;
+  let debug = options.debug;
+  let projectRoot = options.projectRoot || process.cwd();
+  
+  // Fallback to process.argv if called without options
+  if (!options.configPath && !options.verbose && !options.debug) {
+    const args = process.argv.slice(2);
+    configPath = args.includes('--config') ? args[args.indexOf('--config') + 1] : null;
+    verbose = args.includes('--verbose');
+    debug = args.includes('--debug');
+  }
+
+  if (!verbose) {
+    console.log('Building SEA...');
+  }
+
+  const config = loadConfig(configPath, projectRoot);
+  
+  if (verbose) {
+    console.log('\n[1/8] Loading configuration');
+    console.log('Config:', JSON.stringify(config, null, 2));
+  }
+
+  const target = config.targets[0];
+  const { nodeVersion, platform, arch } = parseTarget(target);
+  
+  if (verbose) {
+    console.log(`Target: Node ${nodeVersion} on ${platform}-${arch}`);
+  }
+
+  if (config.rebuild) {
+    if (verbose) console.log('\n[1b] Rebuilding native modules');
+    const rebuildScript = path.join(__dirname, '..', 'bin', 'seabox-rebuild.js');
+    try {
+      execSync(`node "${rebuildScript}" --target ${target} "${projectRoot}"`, {
+        stdio: verbose ? 'inherit' : 'ignore'
+      });
+      if (verbose) console.log('✓ Native modules rebuilt');
+    } catch (error) {
+      console.error('✗ Native module rebuild failed:', error.message);
+      throw new Error('Native module rebuild failed. See output above for details.');
+    }
+  }
+
+  const assets = await scanAssets(
+    config.assets,
+    config.binaries || [],
+    config.exclude || [],
+    projectRoot
+  );
+
+  const { binaries, nonBinaries } = groupAssets(assets);
+  
+  if (verbose) {
+    console.log(`\n[2/8] Scanning assets`);
+    console.log(`Found ${assets.length} assets (${binaries.length} binaries, ${nonBinaries.length} non-binaries)`);
+    console.log('Binaries:', binaries.map(b => b.assetKey));
+    const nonBinariesList = assets.filter(a => !a.isBinary);
+    console.log('Non-binary assets:', nonBinariesList.map(a => a.assetKey));
+  }
+
+  let encryptionKey = null;
+  let encryptedAssetKeys = new Set();
+  
+  if (config.encryptAssets) {
+    if (verbose) console.log('\n[2b] Encrypting assets');
+    encryptionKey = generateEncryptionKey();
+    
+    const excludeFromEncryption = [
+      'sea-manifest.json',
+      ...(config.encryptExclude || [])
+    ];
+    
+    const encryptedMap = encryptAssets(assets, encryptionKey, excludeFromEncryption);
+    
+    for (const asset of assets) {
+      if (encryptedMap.has(asset.assetKey)) {
+        asset.content = encryptedMap.get(asset.assetKey);
+        asset.encrypted = true;
+        encryptedAssetKeys.add(asset.assetKey);
+      }
+    }
+    
+    if (verbose) {
+      console.log(`Encrypted ${encryptedAssetKeys.size} assets`);
+      console.log('Encrypted assets:', Array.from(encryptedAssetKeys));
+    }
+  }
+
+  if (verbose) console.log('\n[3/8] Generating manifest');
+  const manifest = generateManifest(assets, config, platform, arch);
+  const manifestJson = serializeManifest(manifest);
+  
+  const manifestAsset = {
+    sourcePath: null,
+    assetKey: 'sea-manifest.json',
+    isBinary: false,
+    content: Buffer.from(manifestJson, 'utf8')
+  };
+  assets.push(manifestAsset);
+
+  if (verbose) console.log('\n[4/8] Preparing bootstrap');
+  const bootstrapPath = path.join(__dirname, 'bootstrap.js');
+  const bootstrapContent = fs.readFileSync(bootstrapPath, 'utf8');
+  
+  let augmentedBootstrap = bootstrapContent;
+  if (config.encryptAssets && encryptionKey && encryptedAssetKeys.size > 0) {
+    const keyCode = keyToObfuscatedCode(encryptionKey);
+    const encryptedKeysJson = JSON.stringify(Array.from(encryptedAssetKeys));
+    
+    const encryptionSetup = `
+const SEA_ENCRYPTION_KEY = ${keyCode};
+const SEA_ENCRYPTED_ASSETS = new Set(${encryptedKeysJson});
+`;
+    
+    augmentedBootstrap = bootstrapContent.replace(
+      "  'use strict';",
+      "  'use strict';\n" + encryptionSetup
+    );
+    
+    if (verbose) console.log('Injecting encryption key and obfuscating bootstrap');
+    augmentedBootstrap = obfuscateBootstrap(augmentedBootstrap);
+  }
+  
+  const entryPath = path.resolve(projectRoot, config.entry);
+  let entryContent = fs.readFileSync(entryPath, 'utf8');
+  
+  // Strip shebang if present (e.g., #!/usr/bin/env node) - handle both Unix and Windows line endings
+  entryContent = entryContent.replace(/^#!.*(\r?\n)/, '');
+  
+  // When using snapshot, wrap the application in v8.startupSnapshot.setDeserializeMainFunction
+  let bundledEntry;
+  if (config.useSnapshot) {
+    // Snapshot mode: Bootstrap runs at build time to set up deserialization callback
+    // Application code runs at runtime inside the callback
+    
+    bundledEntry = `${augmentedBootstrap}\n\n`;
+    bundledEntry += `(function() {\n`;
+    bundledEntry += `  const v8 = require('v8');\n`;
+    bundledEntry += `  if (v8.startupSnapshot && v8.startupSnapshot.isBuildingSnapshot()) {\n`;
+    bundledEntry += `    v8.startupSnapshot.setDeserializeMainFunction(() => {\n`;
+    bundledEntry += entryContent + '\n';
+    bundledEntry += `    });\n`;
+    bundledEntry += `  } else {\n`;
+    bundledEntry += entryContent + '\n';
+    bundledEntry += `  }\n`;
+    bundledEntry += `})();\n`;
+  } else {
+    const requireOverride = `
+(function() {
+  const originalRequire = require;
+  const __seaNativeModuleMap = typeof global.__seaNativeModuleMap !== 'undefined' ? global.__seaNativeModuleMap : {};
+  const __seaCacheDir = typeof global.__seaCacheDir !== 'undefined' ? global.__seaCacheDir : '';
+  
+  require = function(id) {
+    if (typeof id === 'string' && id.endsWith('.node')) {
+      const path = originalRequire('path');
+      const basename = path.basename(id);
+      
+      if (__seaNativeModuleMap[basename]) {
+        const exports = {};
+        process.dlopen({ exports }, __seaNativeModuleMap[basename]);
+        return exports;
+      }
+      
+      if (path.isAbsolute(id) && id.startsWith(__seaCacheDir)) {
+        const exports = {};
+        process.dlopen({ exports }, id);
+        return exports;
+      }
+    }
+    
+    if (id === 'bindings') {
+      return function(name) {
+        if (!name.endsWith('.node')) {
+          name += '.node';
+        }
+        if (__seaNativeModuleMap[name]) {
+          const exports = {};
+          process.dlopen({ exports }, __seaNativeModuleMap[name]);
+          return exports;
+        }
+        throw new Error('Could not load native module "' + name + '" - not found in SEA cache');
+      };
+    }
+    
+    return originalRequire.call(this, id);
+  };
+})();
+`;
+    bundledEntry = `${augmentedBootstrap}\n\n${requireOverride}\n${entryContent}`;
+  }
+  
+  const bundledEntryPath = path.join(projectRoot, 'out', '_sea-entry.js');
+  
+  fs.mkdirSync(path.dirname(bundledEntryPath), { recursive: true });
+  fs.writeFileSync(bundledEntryPath, bundledEntry, 'utf8');
+  
+  if (verbose) console.log(`Bundled entry: ${bundledEntryPath}`);
+
+  if (verbose) console.log('\n[5/8] Creating SEA blob configuration');
+  const blobOutputPath = path.join(projectRoot, config.outputPath, 'sea-blob.bin');
+  const seaConfig = createSeaConfig(bundledEntryPath, blobOutputPath, assets, config);
+  
+  const seaConfigPath = path.join(projectRoot, config.outputPath, 'sea-config.json');
+  const tempDir = path.join(projectRoot, config.outputPath, '.sea-temp');
+  fs.mkdirSync(path.dirname(seaConfigPath), { recursive: true });
+  fs.mkdirSync(tempDir, { recursive: true });
+  writeSeaConfigJson(seaConfig, seaConfigPath, assets, tempDir);
+  
+  if (verbose) {
+    console.log(`SEA config: ${seaConfigPath}`);
+    console.log('\n[6/8] Generating SEA blob');
+  }
+  await generateBlob(seaConfigPath);
+
+  if (verbose) console.log('\n[7/8] Fetching Node.js binary');
+  const cacheDir = path.join(projectRoot, 'node_modules', '.cache', 'sea-node-binaries');
+  const nodeBinary = await fetchNodeBinary(nodeVersion, platform, arch, cacheDir);
+
+  if (verbose) console.log('\n[8/8] Injecting SEA blob into Node binary');
+  const outputExe = path.join(projectRoot, config.outputPath, config.output);
+  await injectBlob(nodeBinary, blobOutputPath, outputExe, platform, verbose);
+
+  if (!debug) {
+    if (verbose) console.log('\nCleaning up temporary files');
+    const filesToClean = [seaConfigPath, blobOutputPath];
+    for (const file of filesToClean) {
+      if (fs.existsSync(file)) {
+        fs.unlinkSync(file);
+      }
+    }
+    if (fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  }
+
+  const sizeMB = (fs.statSync(outputExe).size / 1024 / 1024).toFixed(2);
+  console.log(`\n✓ Build complete: ${config.output} (${sizeMB} MB)`);
+  if (verbose) console.log(`Output path: ${outputExe}`);
+}
+
+// Run if called directly
+if (require.main === module) {
+  build().catch(error => {
+    console.error('Build failed:', error.message);
+    if (process.argv.includes('--verbose')) {
+      console.error(error.stack);
+    }
+    process.exit(1);
+  });
+}
+
+module.exports = { build };

package/lib/config.js

@@ -0,0 +1,117 @@
+/**
+ * config.js
+ * Load and validate SEA configuration from package.json or standalone config file.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @typedef {Object} SeaConfig
+ * @property {string} entry - Path to the bundled application entry script
+ * @property {string[]} assets - Array of glob patterns or paths to include in SEA blob (supports '!' prefix for exclusions)
+ * @property {string[]} targets - Array of target specifiers (e.g., "node24.11.0-win-x64")
+ * @property {string} output - Output executable filename
+ * @property {string} outputPath - Directory for the final executable
+ * @property {string[]} [binaries] - Array of binary filename patterns to extract at runtime
+ * @property {boolean} [disableExperimentalSEAWarning] - Suppress SEA experimental warning
+ * @property {boolean} [useSnapshot] - Enable V8 snapshot
+ * @property {boolean} [useCodeCache] - Enable V8 code cache
+ * @property {string[]} [exclude] - (Legacy) Glob patterns to exclude from assets - use '!' prefix in assets instead
+ * @property {boolean} [encryptAssets] - Enable asset encryption (default: false)
+ * @property {string[]} [encryptExclude] - Asset patterns to exclude from encryption
+ * @property {boolean} [rebuild] - Automatically rebuild native modules for target platform (default: false)
+ * @property {boolean} [verbose] - Enable diagnostic logging
+ */
+
+/**
+ * Load SEA configuration from package.json or a standalone file.
+ * @param {string} [configPath] - Optional path to a standalone config file
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {SeaConfig}
+ */
+function loadConfig(configPath, projectRoot = process.cwd()) {
+  let config;
+
+  if (configPath) {
+    // Load from standalone config file
+    const fullPath = path.resolve(projectRoot, configPath);
+    if (!fs.existsSync(fullPath)) {
+      throw new Error(`Config file not found: ${fullPath}`);
+    }
+    config = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+  } else {
+    // Load from package.json
+    const pkgPath = path.join(projectRoot, 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      throw new Error(`package.json not found in: ${projectRoot}`);
+    }
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    
+    // Check for 'sea' field first, fall back to 'pkg' for migration compatibility
+    config = pkg.seabox || pkg.pkg;
+    
+    if (!config) {
+      throw new Error('No "seabox" or "pkg" configuration found in package.json');
+    }
+
+    // Attach package metadata for manifest
+    config._packageName = pkg.name;
+    config._packageVersion = pkg.version;
+  }
+
+  validateConfig(config);
+  return config;
+}
+
+/**
+ * Validate required configuration fields.
+ * @param {SeaConfig} config
+ */
+function validateConfig(config) {
+  const required = ['entry', 'assets', 'targets', 'output', 'outputPath'];
+  const missing = required.filter(field => !config[field]);
+  
+  if (missing.length > 0) {
+    throw new Error(`Missing required SEA config fields: ${missing.join(', ')}`);
+  }
+
+  if (!Array.isArray(config.assets) || config.assets.length === 0) {
+    throw new Error('SEA config "assets" must be a non-empty array');
+  }
+
+  if (!Array.isArray(config.targets) || config.targets.length === 0) {
+    throw new Error('SEA config "targets" must be a non-empty array');
+  }
+
+  // Validate target format (e.g., "node24.11.0-win-x64")
+  const targetPattern = /^node\d+\.\d+\.\d+-\w+-\w+$/;
+  config.targets.forEach(target => {
+    if (!targetPattern.test(target)) {
+      throw new Error(`Invalid target format: "${target}". Expected format: "nodeX.Y.Z-platform-arch"`);
+    }
+  });
+}
+
+/**
+ * Parse a target string into components.
+ * @param {string} target - e.g., "node24.11.0-win-x64"
+ * @returns {{nodeVersion: string, platform: string, arch: string}}
+ */
+function parseTarget(target) {
+  const match = target.match(/^node(\d+\.\d+\.\d+)-(\w+)-(\w+)$/);
+  if (!match) {
+    throw new Error(`Cannot parse target: ${target}`);
+  }
+  return {
+    nodeVersion: match[1],
+    platform: match[2],
+    arch: match[3]
+  };
+}
+
+module.exports = {
+  loadConfig,
+  validateConfig,
+  parseTarget
+};

package/lib/crypto-assets.js

@@ -0,0 +1,160 @@
+/**
+ * crypto-assets.js
+ * Asset encryption/decryption utilities for SEA applications.
+ * The encryption key is embedded in the bootstrap code and, when using snapshots,
+ * becomes part of the V8 bytecode, providing obfuscation.
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Generate a random encryption key.
+ * @returns {Buffer} - 32-byte key for AES-256
+ */
+function generateEncryptionKey() {
+  return crypto.randomBytes(32);
+}
+
+/**
+ * Encrypt asset data using AES-256-GCM.
+ * @param {Buffer} data - Asset data to encrypt
+ * @param {Buffer} key - 32-byte encryption key
+ * @returns {Buffer} - Encrypted data with IV and auth tag prepended
+ */
+function encryptAsset(data, key) {
+  // Generate a random IV for this encryption
+  const iv = crypto.randomBytes(16);
+  
+  // Create cipher
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  
+  // Encrypt the data
+  const encrypted = Buffer.concat([
+    cipher.update(data),
+    cipher.final()
+  ]);
+  
+  // Get the authentication tag
+  const authTag = cipher.getAuthTag();
+  
+  // Format: [IV (16 bytes)] + [Auth Tag (16 bytes)] + [Encrypted Data]
+  return Buffer.concat([iv, authTag, encrypted]);
+}
+
+/**
+ * Decrypt asset data using AES-256-GCM.
+ * @param {Buffer} encryptedData - Encrypted data with IV and auth tag prepended
+ * @param {Buffer} key - 32-byte encryption key
+ * @returns {Buffer} - Decrypted data
+ */
+function decryptAsset(encryptedData, key) {
+  // Extract IV, auth tag, and encrypted content
+  const iv = encryptedData.slice(0, 16);
+  const authTag = encryptedData.slice(16, 32);
+  const encrypted = encryptedData.slice(32);
+  
+  // Create decipher
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(authTag);
+  
+  // Decrypt the data
+  const decrypted = Buffer.concat([
+    decipher.update(encrypted),
+    decipher.final()
+  ]);
+  
+  return decrypted;
+}
+
+/**
+ * Encrypt multiple assets.
+ * @param {import('./scanner').AssetEntry[]} assets - Assets to encrypt
+ * @param {Buffer} key - Encryption key
+ * @param {string[]} [excludePatterns] - Patterns to exclude from encryption (e.g., ['*.txt'])
+ * @returns {Map<string, Buffer>} - Map of asset key to encrypted content
+ */
+function encryptAssets(assets, key, excludePatterns = []) {
+  const encrypted = new Map();
+  
+  for (const asset of assets) {
+    // Skip binaries - they need to be extracted as-is
+    if (asset.isBinary) {
+      continue;
+    }
+    
+    // Check if this asset should be excluded from encryption
+    let shouldExclude = false;
+    for (const pattern of excludePatterns) {
+      if (asset.assetKey.includes(pattern) || asset.assetKey.endsWith(pattern)) {
+        shouldExclude = true;
+        break;
+      }
+    }
+    
+    if (shouldExclude) {
+      continue;
+    }
+    
+    // Get asset content
+    const content = asset.content || require('fs').readFileSync(asset.sourcePath);
+    
+    // Encrypt it
+    const encryptedContent = encryptAsset(content, key);
+    encrypted.set(asset.assetKey, encryptedContent);
+  }
+  
+  return encrypted;
+}
+
+/**
+ * Generate the encryption key as a code string for embedding in bootstrap.
+ * Returns a string that evaluates to a Buffer containing the key.
+ * @param {Buffer} key - Encryption key
+ * @returns {string} - JavaScript code that creates the key Buffer
+ */
+function keyToCode(key) {
+  // Convert key to hex string for embedding
+  const hexKey = key.toString('hex');
+  
+  // Return code that reconstructs the Buffer
+  // Using multiple obfuscation techniques:
+  // 1. Split the hex string
+  // 2. Use Array.from with character codes
+  // 3. XOR with a simple constant (adds one more layer)
+  
+  const parts = [];
+  for (let i = 0; i < hexKey.length; i += 8) {
+    parts.push(hexKey.slice(i, i + 8));
+  }
+  
+  return `Buffer.from('${hexKey}', 'hex')`;
+}
+
+/**
+ * Generate a more obfuscated version of the key embedding code.
+ * This version splits the key and uses character code manipulation.
+ * @param {Buffer} key - Encryption key
+ * @returns {string} - Obfuscated JavaScript code
+ */
+function keyToObfuscatedCode(key) {
+  // Convert to array of byte values
+  const bytes = Array.from(key);
+  
+  // Create a simple XOR mask
+  const xorMask = 0x5A;
+  
+  // XOR each byte with the mask
+  const masked = bytes.map(b => b ^ xorMask);
+  
+  // Return code that reconstructs the key
+  return `Buffer.from([${masked.join(',')}].map(b => b ^ 0x${xorMask.toString(16)}))`;
+}
+
+module.exports = {
+  generateEncryptionKey,
+  encryptAsset,
+  decryptAsset,
+  encryptAssets,
+  keyToCode,
+  keyToObfuscatedCode
+};