@socketsecurity/lib 5.6.0 → 5.8.0

package/CHANGELOG.md

@@ -5,6 +5,92 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.8.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.8.0) - 2026-03-10
+
+### Added
+
+- **archives**: Added secure archive extraction utilities with support for ZIP, TAR, TAR.GZ, and TGZ formats
+  - Configurable limits: `maxFileSize` (default 100MB), `maxTotalSize` (default 1GB)
+  - Cross-platform path normalization
+  - External dependencies: adm-zip@0.5.16, tar-fs@3.1.2 (bundled, +212KB)
+  - Security features: path traversal protection, file size limits, total size limits, symlink blocking
+  - Strip option to remove leading path components (like tar `--strip-components`)
+  - `detectArchiveFormat()` - Detect archive type from file extension
+  - `extractArchive()` - Generic extraction with auto-format detection
+  - `extractTar()`, `extractTarGz()`, `extractZip()` - Format-specific extractors
+
+- **releases/github**: Added archive extraction support for GitHub releases
+  - Auto-detects format from asset filename
+  - Enhanced `downloadAndExtractZip()` to use generic archive helpers
+  - Supports ZIP, TAR, TAR.GZ, and TGZ assets
+  - `downloadAndExtractArchive()` - Generic archive download and extraction
+
+### Changed
+
+- **dependencies**: Deduplicated 14 external bundle packages to single versions using pnpm overrides and patches
+
+## [5.7.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.7.0) - 2026-02-12
+
+### Added
+
+- **env**: Added `isInEnv()` helper function to check if an environment variable key exists, regardless of its value
+  - Returns `true` even for empty strings, `"false"`, `"0"`, etc.
+  - Follows same override resolution order as `getEnvValue()` (isolated overrides → shared overrides → process.env)
+  - Useful for detecting presence of environment variables independent of their value
+
+- **dlx**: Added new exported helper functions
+  - `downloadBinaryFile()` - Downloads a binary file from a URL to the dlx cache directory
+  - `ensurePackageInstalled()` - Ensures an npm package is installed and cached via Arborist
+  - `getBinaryCacheMetadataPath()` - Gets the file path to dlx binary cache metadata (`.dlx-metadata.json`)
+  - `isBinaryCacheValid()` - Checks if a cached dlx binary is still valid based on TTL and timestamp
+  - `makePackageBinsExecutable()` - Makes npm package binaries executable on Unix systems
+  - `parsePackageSpec()` - Parses npm package spec strings (e.g., `pkg@1.0.0`) into name and version
+  - `resolveBinaryPath()` - Resolves the absolute path to a binary within an installed package
+  - `writeBinaryCacheMetadata()` - Writes dlx binary cache metadata with integrity, size, and source info
+
+- **releases**: Added `createAssetMatcher()` utility function for GitHub release asset pattern matching
+  - Creates matcher functions that test strings against glob patterns, prefix/suffix, or RegExp
+  - Used for dynamic asset discovery in GitHub releases (e.g., matching platform-specific binaries)
+
+### Changed
+
+- **env**: Updated `getCI()` to use `isInEnv()` for more accurate CI detection
+  - Now returns `true` whenever the `CI` key exists in the environment, not just when truthy
+  - Matches standard CI detection behavior where the presence of the key (not its value) indicates a CI environment
+
+### Fixed
+
+- **github**: Fixed JSON parsing crash vulnerability by adding try-catch around `JSON.parse()` in GitHub API responses
+  - Prevents crashes on malformed, incomplete, or binary responses
+  - Error messages now include the response URL for better debugging
+
+- **dlx/binary**: Fixed clock skew vulnerabilities in cache validation
+  - Cache entries with future timestamps (clock skew) are now treated as expired
+  - Metadata writes now use atomic write-then-rename pattern to prevent corruption
+  - Added TOCTOU race protection by re-checking binary existence after metadata read
+
+- **dlx/cache cleanup**: Fixed handling of future timestamps during cache cleanup
+  - Entries with future timestamps (due to clock skew) are now properly treated as expired
+
+- **dlx/package**: Fixed scoped package parsing bug where `@scope/package` was incorrectly parsed
+  - Changed condition from `startsWith('@')` to `atIndex === 0` for more precise detection
+  - Fixes installation failures for scoped packages like `@socketregistry/lib`
+
+- **cache-with-ttl**: Added clock skew detection to TTL cache
+  - Far-future `expiresAt` values (>2x TTL) are now treated as expired
+  - Protects against cache poisoning from clock skew
+
+- **packages/specs**: Fixed unconditional `.git` truncation in Git URL parsing
+  - Now only removes `.git` suffix when URL actually ends with `.git`
+  - Prevents incorrect truncation of URLs containing `.git` in the middle
+
+- **releases/github**: Fixed TOCTOU race condition in binary download verification
+  - Re-checks binary existence after reading version file
+  - Ensures binary is re-downloaded if missing despite version file presence
+
+- **provenance**: Fixed incorrect package name in provenance workflow
+  - Changed from `@socketregistry/lib` to `@socketsecurity/lib`
+
 ## [5.6.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.6.0) - 2026-02-08
 
 ### Added
@@ -811,7 +897,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
-- **DLX binary metadata structure**: Updated `writeMetadata()` to use unified schema with additional fields
+- **DLX binary metadata structure**: Updated `writeBinaryCacheMetadata()` to use unified schema with additional fields
   - Now includes `cache_key` (first 16 chars of SHA-512 hash)
   - Added `size` field for cached binary size
   - Added `checksum_algorithm` field (currently "sha256")
@@ -1010,6 +1096,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 This release completely refactors the environment variable system, consolidating 60+ individual env constant files into grouped getter modules with AsyncLocalStorage-based test rewiring.
 
 **Consolidated env files** - Individual files replaced with grouped modules:
+
 - `env/github.ts` - All GitHub-related env vars (GITHUB_TOKEN, GH_TOKEN, GITHUB_API_URL, etc.)
 - `env/socket.ts` - Socket-specific env vars (SOCKET_API_TOKEN, SOCKET_CACACHE_DIR, etc.)
 - `env/socket-cli.ts` - Socket CLI env vars (SOCKET_CLI_API_TOKEN, SOCKET_CLI_CONFIG, etc.)
@@ -1021,6 +1108,7 @@ This release completely refactors the environment variable system, consolidating
 - `env/test.ts` - Test framework env vars (VITEST, JEST_WORKER_ID)
 
 **Constants → Getter functions** - All env constants converted to functions:
+
 ```typescript
 // Before (v1.x):
 import { GITHUB_TOKEN } from '#env/github-token'
@@ -1030,6 +1118,7 @@ import { getGithubToken } from '#env/github'
 ```
 
 **Deleted files** - Removed 60+ individual env constant files:
+
 - `env/github-token.ts`, `env/socket-api-token.ts`, etc. → Consolidated into grouped files
 - `env/getters.ts` → Functions moved to their respective grouped files
 
@@ -1059,6 +1148,7 @@ afterEach(() => {
 ```
 
 **Features:**
+
 - Allows toggling between snapshot and live behavior
 - Compatible with `vi.stubEnv()` as fallback
 
@@ -1161,7 +1251,7 @@ afterEach(() => {
 ### Added
 
 - Added `dlx-package` module for installing and executing npm packages directly
-  - Content-addressed caching using SHA256 hash (like npm's _npx)
+  - Content-addressed caching using SHA256 hash (like npm's \_npx)
   - Auto-force for version ranges (^, ~, >, <) to get latest within range
   - Cross-platform support with comprehensive tests (30 tests)
   - Parses scoped and unscoped package specs correctly

package/README.md

@@ -7,47 +7,219 @@
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
 
-Core library for [Socket.dev](https://socket.dev/) tools.
+Core infrastructure library for [Socket.dev](https://socket.dev/) security tools. Provides utilities for file system operations, process spawning, HTTP requests, environment detection, logging, spinners, and more.
+
+## Prerequisites
+
+**Node.js 22 or higher** is required.
 
 ## Install
 
 ```bash
+# Using pnpm (recommended)
 pnpm add @socketsecurity/lib
+
+# Using npm
+npm install @socketsecurity/lib
+
+# Using yarn
+yarn add @socketsecurity/lib
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
-// Tree-shakeable exports
 import { Spinner } from '@socketsecurity/lib/spinner'
-import { readJsonFile } from '@socketsecurity/lib/fs'
-import { NODE_MODULES } from '@socketsecurity/lib/constants/packages'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { readJson } from '@socketsecurity/lib/fs'
+
+const logger = getDefaultLogger()
+const spinner = Spinner({ text: 'Loading package.json...' })
 
-const spinner = Spinner({ text: 'Loading...' })
 spinner.start()
-const pkg = await readJsonFile('./package.json')
-spinner.stop()
+const pkg = await readJson('./package.json')
+spinner.successAndStop('Loaded successfully')
+
+logger.success(`Package: ${pkg.name}@${pkg.version}`)
 ```
 
+## Documentation
+
+- [Getting Started](./docs/getting-started.md) - Prerequisites, installation, and first examples
+- [Visual Effects](./docs/visual-effects.md) - Spinners, loggers, themes, and progress indicators
+- [File System](./docs/file-system.md) - File operations, globs, paths, and safe deletion
+- [HTTP Utilities](./docs/http-utilities.md) - Making requests, downloading files, and retry logic
+- [Process Utilities](./docs/process-utilities.md) - Spawning processes, IPC, and locks
+- [Package Management](./docs/package-management.md) - npm/pnpm/yarn detection and operations
+- [Environment](./docs/environment.md) - CI detection, env getters, and platform checks
+- [Constants](./docs/constants.md) - Node versions, npm URLs, and platform values
+- [Examples](./docs/examples.md) - Real-world usage patterns
+- [Troubleshooting](./docs/troubleshooting.md) - Common issues and solutions
+
 ## What's Inside
 
-- **Visual Effects** → logger, spinner, themes
-- **File System** → fs, globs, paths
-- **Package Management** → dlx, npm, pnpm, yarn
-- **Process & Spawn** → process spawning
-- **Environment** → env getters
-- **Constants** → node, npm, platform
-- **Utilities** → arrays, objects, promises, strings
+### Visual Effects
+
+Spinners, colored loggers, themes, progress bars, and terminal output formatting.
+
+- `Spinner` - Animated CLI spinners with progress tracking
+- `getDefaultLogger()` - Colored console logger with symbols
+- `LOG_SYMBOLS` - Colored terminal symbols (✓, ✗, ⚠, ℹ, →)
+- `setTheme()` - Customize colors across the library
+
+### File System
+
+Cross-platform file operations with safe deletion and convenient wrappers.
+
+- `readFileUtf8()`, `readFileBinary()` - Read files as text or binary
+- `readJson()`, `writeJson()` - Parse and format JSON files
+- `safeDelete()` - Protected deletion with safety checks
+- `findUp()`, `findUpSync()` - Traverse up to find files
+- `safeMkdir()` - Create directories without EEXIST errors
+- `validateFiles()` - Check file readability (useful for Yarn PnP, pnpm)
+
+### HTTP Utilities
+
+Native Node.js HTTP/HTTPS requests with retry logic and redirects.
+
+- `httpJson()` - Fetch and parse JSON from APIs
+- `httpText()` - Fetch text/HTML content
+- `httpDownload()` - Download files with progress callbacks
+- `httpRequest()` - Full control over requests and responses
+- Automatic redirects, exponential backoff retries, timeout support
+
+### Process Management
+
+Spawn child processes safely with cross-platform support.
+
+- `spawn()` - Promise-based process spawning with output capture
+- `spawnSync()` - Synchronous version for blocking operations
+- Array-based arguments prevent command injection
+- Automatic Windows `.cmd`/`.bat` handling
+- `ProcessLock` - Ensure only one instance runs at a time
+- `setupIPC()` - Inter-process communication
+
+### Environment Detection
+
+Type-safe environment variable access and platform detection.
+
+- `getCI()` - Detect CI environment
+- `getNodeEnv()` - Get NODE_ENV value
+- `isTest()` - Check if running tests
+- `getHome()` - Home directory (Unix/Linux/macOS)
+- Test rewiring with `setEnv()`, `resetEnv()`
+
+### Package Management
+
+Detect and work with npm, pnpm, and yarn.
+
+- `detectPackageManager()` - Identify package manager from lock files
+- Package manifest operations
+- Lock file management
+
+### Constants
+
+Pre-defined values for Node.js, npm, and platform detection.
+
+- `getNodeMajorVersion()` - Get current Node.js major version
+- `WIN32`, `DARWIN` - Platform booleans (use `!WIN32 && !DARWIN` for Linux)
+- `getAbortSignal()` - Global abort signal
+
+### Utilities
+
+Helpers for arrays, objects, strings, promises, sorting, and more.
+
+- Arrays, objects, strings manipulation
+- Promise utilities and queues
+- Natural sorting
+- Version comparison
+- Error handling with causes
+
+## Features
+
+- **Tree-shakeable exports** - Import only what you need
+- **Cross-platform** - Works on Windows, macOS, and Linux
+- **TypeScript-first** - Full type safety with .d.ts files
+- **Zero dependencies** (for core HTTP - uses Node.js native modules)
+- **Well-tested** - 84% coverage with comprehensive test suite
+- **Security-focused** - Safe defaults, command injection protection
+- **CommonJS output** - Compatible with Node.js tooling
+
+## Common Use Cases
+
+### Running Shell Commands
+
+```typescript
+import { spawn } from '@socketsecurity/lib/spawn'
+
+const result = await spawn('git', ['status'])
+console.log(result.stdout)
+```
+
+### Making API Requests
+
+```typescript
+import { httpJson } from '@socketsecurity/lib/http-request'
+
+const data = await httpJson('https://api.example.com/data')
+```
+
+### Visual Feedback
+
+```typescript
+import { Spinner } from '@socketsecurity/lib/spinner'
+
+const spinner = Spinner({ text: 'Processing...' })
+spinner.start()
+// ... do work ...
+spinner.successAndStop('Complete!')
+```
+
+### Safe File Deletion
+
+```typescript
+import { safeDelete } from '@socketsecurity/lib/fs'
+
+// Protected against deleting parent directories
+await safeDelete('./build')
+```
+
+## Troubleshooting
+
+**Module not found**: Verify you're importing from the correct path:
+
+```typescript
+// Correct
+import { Spinner } from '@socketsecurity/lib/spinner'
+
+// Wrong
+import { Spinner } from '@socketsecurity/lib'
+```
+
+**Node version error**: This library requires Node.js 22+. Check your version:
+
+```bash
+node --version
+```
+
+For more issues, see the [Troubleshooting Guide](./docs/troubleshooting.md).
 
 ## Development
 
 ```bash
-pnpm install    # Install
-pnpm build      # Build
-pnpm test       # Test
+pnpm install    # Install dependencies
+pnpm build      # Build the library
+pnpm test       # Run tests
+pnpm run cover  # Run tests with coverage
 pnpm dev        # Watch mode
+pnpm run lint   # Check code style
+pnpm run fix    # Fix formatting issues
 ```
 
+## Contributing
+
+Contributions are welcome! Please read the [CLAUDE.md](./CLAUDE.md) file for development guidelines and coding standards.
+
 ## License
 
 MIT

package/dist/archives.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Archive format type.
+ */
+export type ArchiveFormat = 'tar' | 'tar.gz' | 'tgz' | 'zip';
+/**
+ * Options for archive extraction.
+ */
+export interface ExtractOptions {
+    /** Suppress log messages */
+    quiet?: boolean;
+    /** Strip leading path components (like tar --strip-components) */
+    strip?: number;
+    /** Maximum size of a single extracted file in bytes (default: 100MB) */
+    maxFileSize?: number;
+    /** Maximum total extracted size in bytes (default: 1GB) */
+    maxTotalSize?: number;
+}
+/**
+ * Detect archive format from file path.
+ *
+ * @param filePath - Path to archive file
+ * @returns Archive format or null if unknown
+ */
+export declare function detectArchiveFormat(filePath: string): ArchiveFormat | null;
+/**
+ * Extract a tar archive to a directory.
+ *
+ * @param archivePath - Path to tar file
+ * @param outputDir - Directory to extract to
+ * @param options - Extraction options
+ */
+export declare function extractTar(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
+/**
+ * Extract a gzipped tar archive to a directory.
+ *
+ * @param archivePath - Path to tar.gz or tgz file
+ * @param outputDir - Directory to extract to
+ * @param options - Extraction options
+ */
+export declare function extractTarGz(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
+/**
+ * Extract a zip archive to a directory.
+ *
+ * @param archivePath - Path to zip file
+ * @param outputDir - Directory to extract to
+ * @param options - Extraction options
+ */
+export declare function extractZip(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;
+/**
+ * Extract an archive to a directory.
+ * Automatically detects format from file extension.
+ *
+ * @param archivePath - Path to archive file
+ * @param outputDir - Directory to extract to
+ * @param options - Extraction options
+ * @throws Error if archive format is not supported
+ */
+export declare function extractArchive(archivePath: string, outputDir: string, options?: ExtractOptions): Promise<void>;