seabox 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -13,6 +13,11 @@ A reusable tool for building Node.js Single Executable Applications (SEA) with n
 - Automatic code signature removal before injection
 - Simple configuration via package.json
 
+## Use case
+This tooling was created as an alternative to pkg, which is unfortunatly deprecated, and where forks were running foul of virus checkers. By using node's SEA, the executables are directly from nodejs's distribution source, and built using node's native Single Executable Application solution. Unfortunatly this does mean native modules embedded within the exe cannot run directly and must be extracted to a location on the disk on first run - This tooling automates that process for you, while providing arbitrary asset embedding. Embedded assets are _not_ extracted and access to them is handled by intercepting require and fs.  
+
+Note: **V8 snapshot includes and embedds the original source**, this is currently a limitation of Node's SEA tooling as far as I can tell; thus the snapshot is only useful for faster startup.  
+
 ## Installation
 
 ```bash
@@ -63,7 +68,9 @@ Add a `sea` configuration to your `package.json`:
 - **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
+- **rebuild**: Automatically rebuild native modules for the target platform before building the SEA (default: false)
+- **rcedit**: (Windows only) Customize executable icon and version information. See [rcedit options](#windows-executable-customization-rcedit)
+- **cacheLocation**: Custom cache directory for extracted binaries (default: `'./.sea-cache'`). Supports environment variable expansion (e.g., `'%LOCALAPPDATA%\\myapp-cache'` on Windows or `'$HOME/.cache/myapp'` on Unix)
 
 ## Usage
 
@@ -94,8 +101,12 @@ npm run build:exe
 # Build using package.json configuration
 npx seabox
 
+# Build using a standalone config file (alternative to package.json)
+npx seabox --config sea-config.json
+
 # Verbose output
 npx seabox --verbose
+
 ```
 
 ### Programmatic API
@@ -126,7 +137,35 @@ Native modules (`.node`, `.dll`, `.so`, `.dylib`) are automatically:
 - Integrity-checked using SHA-256 hashes
 - Loaded via custom module resolution
 
-Cache location: `%LOCALAPPDATA%\.sea-cache\<appname>\<version>-<platform>-<arch>`
+### Cache Location
+
+By default, binaries are extracted to: `./.sea-cache/<appname>/<version>-<platform>-<arch>`
+
+You can customize the cache location in your configuration:
+
+```json
+{
+  "sea": {
+    "cacheLocation": "%LOCALAPPDATA%\\myapp-cache"
+  }
+}
+```
+
+The cache location supports environment variable expansion:
+- **Windows**: `%LOCALAPPDATA%`, `%APPDATA%`, `%TEMP%`, etc.
+- **Unix/Linux/macOS**: `$HOME`, `$TMPDIR`, `${XDG_CACHE_HOME}`, etc.
+
+**Override at runtime**: Set the `SEACACHE` environment variable to override the configured location:
+
+```bash
+# Windows
+set SEACACHE=C:\custom\cache\path
+myapp.exe
+
+# Unix/Linux/macOS
+export SEACACHE=/custom/cache/path
+./myapp
+```
 
 ## Native Module Rebuilding
 
@@ -150,6 +189,52 @@ The rebuilder will:
 
 **Note**: Cross-compilation may require additional platform-specific build tools installed.
 
+## Windows Executable Customization (rcedit)
+
+For Windows executables, you can customize the icon and version information using the `rcedit` configuration option:
+
+```json
+{
+  "sea": {
+    "output": "myapp.exe",
+    "targets": ["node24.11.0-win32-x64"],
+    "rcedit": {
+      "icon": ".\\assets\\myapp.ico",
+      "file-version": "1.2.3.4",
+      "product-version": "1.2.3.4",
+      "version-string": {
+        "CompanyName": "My Company",
+        "FileDescription": "My Application",
+        "ProductName": "MyApp",
+        "InternalName": "myapp.exe",
+        "OriginalFilename": "myapp.exe",
+        "LegalCopyright": "Copyright (C) 2025 My Company"
+      }
+    }
+  }
+}
+```
+
+### rcedit Options
+
+- **icon**: Path to `.ico` file for the executable icon
+- **file-version**: File version in `X.X.X.X` format
+- **product-version**: Product version in `X.X.X.X` format
+- **version-string**: Object containing version string properties:
+  - `CompanyName`: Company name
+  - `FileDescription`: Description of the file
+  - `ProductName`: Product name
+  - `InternalName`: Internal name
+  - `OriginalFilename`: Original filename
+  - `LegalCopyright`: Copyright notice
+  - `LegalTrademarks`: Trademark information (optional)
+  - `PrivateBuild`: Private build description (optional)
+  - `SpecialBuild`: Special build description (optional)
+
+The rcedit step runs after signature removal and before the SEA blob injection. This only works for Windows (`win32`) targets.
+
+For more details, see the [rcedit documentation](https://github.com/electron/rcedit).
+
 ## Asset Encryption
 
 seabox supports optional AES-256-GCM encryption of embedded assets to protect your application code and data:
@@ -169,33 +254,17 @@ seabox supports optional AES-256-GCM encryption of embedded assets to protect yo
 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
+4. **Key Obfuscation**: the bootstrap and key code are obfuscated, but not removed 
 5. **Runtime Decryption**: Assets are transparently decrypted when accessed
 
-### Security Considerations
+### 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
+- **V8 snapshot includes the original source**, this is currently a limitation of Node's SEA. 
 - 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
-    ]
-  }
-}
-```
+- The bootloader code, that includes the encryption key, is obfuscated in the source embedded by Node's SEA
+  
 
 ## Platform Support
 

package/bin/seabox.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * CLI entry point for SEA builder
@@ -32,7 +32,7 @@ async function main() {
   // Show help
   if (showHelp) {
     console.log(`
-SEA Builder - Node.js Single Executable Application Builder
+SeaBox - Node.js Single Executable Application Builder
 
 Usage:
   seabox [options]

package/lib/bootstrap.js

@@ -202,18 +202,56 @@ function getAsset(assetKey, encoding) {
 }
 
 
+/**
+ * Resolve environment variables in a path string.
+ * Supports %VAR% on Windows and $VAR or ${VAR} on Unix-like systems.
+ * @param {string} pathStr - Path string that may contain environment variables
+ * @returns {string} - Path with environment variables expanded
+ */
+function resolveEnvVars(pathStr) {
+  if (!pathStr) return pathStr;
+  
+  // Replace Windows-style %VAR%
+  let resolved = pathStr.replace(/%([^%]+)%/g, (match, varName) => {
+    return process.env[varName] || match;
+  });
+  
+  // Replace Unix-style $VAR and ${VAR}
+  resolved = resolved.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+    return process.env[varName] || match;
+  });
+  resolved = resolved.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (match, varName) => {
+    return process.env[varName] || match;
+  });
+  
+  return resolved;
+}
+
 /**
  * Get the extraction cache directory for this application.
  * @param {string} appName
  * @param {string} appVersion
  * @param {string} platform
  * @param {string} arch
+ * @param {string} [configuredCacheLocation] - Optional configured cache location from manifest
  * @returns {string}
  */
-function getExtractionCacheDir(appName, appVersion, platform, arch) {
+function getExtractionCacheDir(appName, appVersion, platform, arch, configuredCacheLocation) {
+  // Priority: SEACACHE env var > configured location > default
   if(process.env.SEACACHE) return process.env.SEACACHE;
-  const localAppData =  process.env.LOCALAPPDATA || process.env.HOME || process.cwd();
-  return path.join(localAppData, '.sea-cache', appName, `${appVersion}-${platform}-${arch}`);
+  
+  if (configuredCacheLocation) {
+    // Resolve environment variables in the configured path
+    const resolvedBase = resolveEnvVars(configuredCacheLocation);
+    // Make relative paths absolute (relative to cwd)
+    const absoluteBase = path.isAbsolute(resolvedBase) ? resolvedBase : path.resolve(process.cwd(), resolvedBase);
+    return path.join(absoluteBase, appName, `${appVersion}-${platform}-${arch}`);
+  }
+  
+  // Default behavior
+  const defaultBase = './.sea-cache';
+  const absoluteBase = path.resolve(process.cwd(), defaultBase);
+  return path.join(absoluteBase, appName, `${appVersion}-${platform}-${arch}`);
 }
 
 /**
@@ -400,6 +438,9 @@ function bootstrap() {
     console.log(`  App: ${manifest.appName} v${manifest.appVersion}`);
     console.log(`  Platform: ${manifest.platform}-${manifest.arch}`);
     console.log(`  Binaries to extract: ${manifest.binaries.length}`);
+    if (manifest.cacheLocation) {
+      console.log(`  Configured cache location: ${manifest.cacheLocation}`);
+    }
   }
 
   // Filter binaries for current platform
@@ -415,7 +456,8 @@ function bootstrap() {
     manifest.appName,
     manifest.appVersion,
     manifest.platform,
-    manifest.arch
+    manifest.arch,
+    manifest.cacheLocation
   );
 
   const nativeModuleMap = {};

package/lib/build.js

@@ -249,7 +249,7 @@ const SEA_ENCRYPTED_ASSETS = new Set(${encryptedKeysJson});
 
   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);
+  await injectBlob(nodeBinary, blobOutputPath, outputExe, platform, verbose, config.rcedit);
 
   if (!debug) {
     if (verbose) console.log('\nCleaning up temporary files');

package/lib/bytenode-hack.js

@@ -0,0 +1,56 @@
+/*MIT License
+
+Copyright (c) 2018 Osama Abbas
+
+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.*/
+
+module.exports.fixBytecode = function (bytecodeBuffer) {
+  if (!isBuffer(bytecodeBuffer)) {
+    throw new Error('bytecodeBuffer must be a buffer object.');
+  }
+
+  const dummyBytecode = compileCode('"ಠ_ಠ"');
+  const version = parseFloat(process.version.slice(1, 5));
+
+  if (process.version.startsWith('v8.8') || process.version.startsWith('v8.9')) {
+    // Node is v8.8.x or v8.9.x
+    dummyBytecode.subarray(16, 20).copy(bytecodeBuffer, 16);
+    dummyBytecode.subarray(20, 24).copy(bytecodeBuffer, 20);
+  } else if (version >= 12 && version <= 23) {
+    dummyBytecode.subarray(12, 16).copy(bytecodeBuffer, 12);
+  } else {
+    dummyBytecode.subarray(12, 16).copy(bytecodeBuffer, 12);
+    dummyBytecode.subarray(16, 20).copy(bytecodeBuffer, 16);
+  }
+};
+
+module.exports.readSourceHash = function (bytecodeBuffer) {
+  if (!isBuffer(bytecodeBuffer)) {
+    throw new Error('bytecodeBuffer must be a buffer object.');
+  }
+
+  if (process.version.startsWith('v8.8') || process.version.startsWith('v8.9')) {
+    // Node is v8.8.x or v8.9.x
+    // eslint-disable-next-line no-return-assign
+    return bytecodeBuffer.subarray(12, 16).reduce((sum, number, power) => sum += number * Math.pow(256, power), 0);
+  } else {
+    // eslint-disable-next-line no-return-assign
+    return bytecodeBuffer.subarray(8, 12).reduce((sum, number, power) => sum += number * Math.pow(256, power), 0);
+  }
+};

package/lib/config.js

@@ -22,6 +22,8 @@ const path = require('path');
  * @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
+ * @property {string} [cacheLocation] - Cache directory for extracted binaries (default: './.sea-cache', supports env vars like '%LOCALAPPDATA%\\path')
+ * @property {Object} [rcedit] - Windows executable resource editor options (icon, version info, etc.)
  */
 
 /**

package/lib/inject.js

@@ -17,9 +17,11 @@ const execFileAsync = promisify(execFile);
  * @param {string} blobPath - Path to the SEA blob file
  * @param {string} outputPath - Path for the output executable
  * @param {string} platform - Target platform (win32, linux, darwin)
+ * @param {boolean} verbose - Enable verbose logging
+ * @param {Object} [rceditOptions] - Optional rcedit configuration for Windows executables
  * @returns {Promise<void>}
  */
-async function injectBlob(nodeBinaryPath, blobPath, outputPath, platform, verbose) {
+async function injectBlob(nodeBinaryPath, blobPath, outputPath, platform, verbose, rceditOptions) {
   // Copy node binary to output location
   fs.copyFileSync(nodeBinaryPath, outputPath);
 
@@ -27,6 +29,11 @@ async function injectBlob(nodeBinaryPath, blobPath, outputPath, platform, verbos
   // The downloaded Node.js binary is signed, and postject will corrupt this signature
   await removeSignature(outputPath, platform);
 
+  // Apply rcedit changes (Windows only, before postject)
+  if (platform === 'win32' && rceditOptions && typeof rceditOptions === 'object') {
+    await applyRcedit(outputPath, rceditOptions, verbose);
+  }
+
   // Prepare postject command
   const sentinel = 'NODE_SEA_BLOB';
   const sentinelFuse = 'NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2';
@@ -66,6 +73,31 @@ async function injectBlob(nodeBinaryPath, blobPath, outputPath, platform, verbos
   //console.log('\nNote: Executable is now ready for signing with your certificate');
 }
 
+/**
+ * Apply rcedit to modify Windows executable resources.
+ * @param {string} exePath - Path to the executable
+ * @param {Object} options - rcedit options (icon, version-string, file-version, product-version, etc.)
+ * @param {boolean} verbose - Enable verbose logging
+ * @returns {Promise<void>}
+ */
+async function applyRcedit(exePath, options, verbose) {
+  if (verbose) {
+    console.log('\nApplying rcedit to modify executable resources...');
+    console.log('Options:', JSON.stringify(options, null, 2));
+  }
+
+  const rcedit = require('rcedit');
+  
+  try {
+    await rcedit(exePath, options);
+    if (verbose) {
+      console.log('✓ rcedit applied successfully');
+    }
+  } catch (error) {
+    throw new Error(`rcedit failed: ${error.message}`);
+  }
+}
+
 /**
  * Resolve the postject executable path.
  * @returns {string}
@@ -77,5 +109,6 @@ function resolvePostject() {
 
 module.exports = {
   injectBlob,
-  resolvePostject
+  resolvePostject,
+  applyRcedit
 };

package/lib/manifest.js

@@ -23,6 +23,7 @@ const path = require('path');
  * @property {string} arch - Target architecture
  * @property {BinaryManifestEntry[]} binaries - Binary extraction rules
  * @property {string[]} allAssetKeys - All embedded asset keys
+ * @property {string} [cacheLocation] - Configured cache location (optional)
  */
 
 /**
@@ -48,7 +49,7 @@ function generateManifest(assets, config, targetPlatform, targetArch) {
       };
     });
 
-  return {
+  const manifest = {
     appName: config._packageName || 'app',
     appVersion: config._packageVersion || '1.0.0',
     platform: targetPlatform,
@@ -56,6 +57,13 @@ function generateManifest(assets, config, targetPlatform, targetArch) {
     binaries,
     allAssetKeys: assets.map(a => a.assetKey)
   };
+  
+  // Include cacheLocation if configured
+  if (config.cacheLocation) {
+    manifest.cacheLocation = config.cacheLocation;
+  }
+  
+  return manifest;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "seabox",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.3",
   "description": "Node.js Single Executable Application (SEA) builder tool with native and library extraction",
   "main": "lib/index.js",
   "types": "dist/index.d.ts",
@@ -28,10 +28,16 @@
   ],
   "author": "Meirion Hughes",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MeirionHughes/seabox"
+  },
+  "homepage": "https://github.com/MeirionHughes/seabox",
   "dependencies": {
     "adm-zip": "^0.5.16",
     "glob": "^10.0.0",
     "postject": "^1.0.0-alpha.6",
+    "rcedit": "^4.0.1",
     "tar": "^6.2.1"
   },
   "devDependencies": {