seabox 0.1.0-beta.1 → 0.1.0-beta.2

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,8 @@ 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)
+- **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 +100,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 +136,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
 
@@ -169,33 +207,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

@@ -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/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,7 @@ 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')
  */
 
 /**

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.2",
   "description": "Node.js Single Executable Application (SEA) builder tool with native and library extraction",
   "main": "lib/index.js",
   "types": "dist/index.d.ts",
@@ -28,6 +28,11 @@
   ],
   "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",