@socketsecurity/lib 5.20.1 → 5.21.0

package/CHANGELOG.md

@@ -5,92 +5,100 @@ 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.20.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.1) - 2026-04-19
+## [5.21.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.21.0) - 2026-04-20
 
-### Fixed
+### Added
 
-- `src/ipc.ts`: harden stub-file writes against local symlink/TOCTOU. Previously `writeIpcStub` used `mkdir {recursive, mode: 0o700}` + `writeFile`, which on multi-user Linux (`/tmp` sticky-bit but world-writable) let a pre-positioned attacker-owned `.socket-ipc/<app>/` survive the mode argument and redirect the subsequent `writeFile` through symlinks to victim files. Now validates directory ownership + mode on POSIX after `mkdir`, then opens the stub with `O_CREAT | O_WRONLY | O_EXCL | O_NOFOLLOW` so pre-existing inodes trigger EEXIST and final-component symlinks trigger ELOOP rather than silent file overwrite
-- `src/cache-with-ttl.ts` `getOrFetch()` — the inflight-map check ran _after_ `await get(key)`, so two concurrent cold-cache callers both suspended on the same disk read, both saw no cached value, both skipped the inflight check, and both fired `fetcher()`. Moves the inflight check before the persistent-cache lookup (with a re-check afterward) so the advertised dedupe guarantee actually holds
-- `src/cache-with-ttl.ts` — cap the in-memory `memoCache` with LRU eviction (`memoMaxSize`, default 1000). Previously a long-running process (devserver, editor extension) querying many distinct keys grew memory without bound — expired entries were only reclaimed when the same key was read again
-- `src/memoization.ts` `memoizeAsync()` — `entry.timestamp` was set when a cache miss STARTED its `fn(...)` call, so a fn taking longer than `ttl` produced a value classified as expired the moment it resolved; every subsequent caller past the first ttl window re-fetched instead of hitting the cache. Now refreshes the timestamp in the resolve handler. Also bumps `accessOrder` on the stale-dedup branch so an entry mid-refresh isn't evicted while a peer is computing on its behalf
-- `src/tables.ts` — `displayWidth` measured columns by `.length` of the ANSI-stripped string, i.e. UTF-16 code units rather than rendered terminal cells. CJK, emoji, and combined code points misaligned tables. Routes measurement through `stringWidth` (Intl.Segmenter + East Asian Width)
-- `src/paths/packages.ts` — `resolvePackageJsonDirname` / `resolvePackageJsonPath` gated on `filepath.endsWith('package.json')`, which misidentified any file whose name ended in that suffix (e.g. `/foo/my-package.json`) as a manifest. Now checks for the literal final segment
-- `src/json/edit.ts` — `@example` for `getEditableJsonClass` imported from `@socketsecurity/lib/json`, which is not a package export; fixed to `@socketsecurity/lib/json/edit`
+- `@socketsecurity/lib/schema/validate` — non-throwing Zod/TypeBox validator returning `{ ok, value } | { ok, errors }` with normalized paths
+- `@socketsecurity/lib/schema/parse` — throwing variant for fail-fast trust boundaries
+- `@socketsecurity/lib/schema/types` — `Schema<T>`, `ValidateResult<T>`, `ValidationIssue`, `AnySchema`, `Infer<S>`
+- `@socketsecurity/lib/promises` `withResolvers()` — spec-compliant [`Promise.withResolvers`](https://tc39.es/ecma262/#sec-promise.withResolvers) helper with `PromiseWithResolvers<T>` type. Uses the native implementation when available
 
-## [5.20.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.0) - 2026-04-19
+### Changed
 
-### Added — validation
+- `@socketsecurity/lib/regexps` `escapeRegExp()` — now spec-compliant with TC39 [`RegExp.escape`](https://tc39.es/ecma262/#sec-regexp.escape); uses the native implementation when available. **Caller-visible shape change**: escaped output now uses `\xHH` for many characters that previously passed through literally (e.g. `escapeRegExp('a')` is now `'\x61'`). Functional equivalence (the compiled regex matches the original input) is preserved; only callers that string-match on escape output need updates
+- `@socketsecurity/lib/memoization` `MemoizeOptions<Args>` — dropped the unused second type parameter. Consumers who wrote `MemoizeOptions<Args, Result>` must drop the second argument
+- `@socketsecurity/lib/packages/specs` `getRepoUrlDetails()` — now accepts `git+https://` / `git+ssh://` GitHub URLs and rejects lookalike hosts (`githubXcom`, `fake-github.com.attacker.tld`). scp-style `git@github.com:…` URLs (no `://`) now return `{ user: '', project: '' }` — callers must normalize to https/ssh upstream
+- `@socketsecurity/lib/url` `urlSearchParamAsBoolean()` — accepts the same truthy vocabulary as `envAsBoolean` (`1` / `true` / `yes` / `on`, case-insensitive). Empty-string input now falls through to `defaultValue` instead of returning `false`
 
-- `@socketsecurity/lib/validation/validate-schema` — universal validator that accepts any Zod-style schema (Zod v3/v4, or any `safeParse`-shaped duck type) and returns a tagged `{ ok: true, value } | { ok: false, errors }` result with normalized `{ path, message }` issues. Type inference flows through: callers get `z.infer<…>`, no casts. Zod is detected purely structurally via `.safeParse` — no runtime import of the `zod` package required
-- `parseSchema(schema, data)` — throwing twin of `validateSchema` for fail-fast trust-boundary validation
-- `Infer<S>`, `ValidateResult<T>`, `ValidationIssue`, `AnySchema` — supporting types exported alongside the helpers
+### Removed
+
+- `@socketsecurity/lib/validation/*` subpath retired — exports re-homed:
+  - `validateSchema` / `parseSchema` → `@socketsecurity/lib/schema/validate` / `@socketsecurity/lib/schema/parse`
+  - `safeJsonParse` → `@socketsecurity/lib/json/parse`
+  - Types → `@socketsecurity/lib/schema/types` and `@socketsecurity/lib/json/types`
+- `memoizeDebounced` from `@socketsecurity/lib/memoization` — was misnamed and had no consumers. Use `memoize` / `memoizeAsync` with a `ttl` instead
 
 ### Fixed
 
-- `src/promise-queue.ts`: wrap `task.fn()` invocation via `Promise.resolve().then()` so a **synchronous** throw inside a queued task converts to a proper rejection on `task.reject` instead of escaping as an uncaught exception
-- `src/stdio/progress.ts` `formatTime()`: clamp negative milliseconds so an over-ticking or clock-skewed progress bar no longer renders a negative ETA like `-1m59s`
-- `src/dlx/lockfile.ts`: wrap the scratch-directory cleanup in `finally` with its own `try/catch` so a cleanup failure cannot clobber the real exception from the main try-block
-- `src/dlx/package.ts` `parsePackageSpec`: normalize a bare trailing `@` (e.g. `"pkg@"`) to `version: undefined` so downstream "no version provided" checks behave consistently
-- `src/stdio/prompts.ts`: tighten the `selectModule` destructure type to the two properties actually used (`default`, `Separator`) instead of an `as any` cast
-- `src/http-request.ts`: hoist `CHECKSUM_BSD_RE` and `CHECKSUM_GNU_RE` regex literals to module scope so `parseChecksums()` no longer re-declares them once per line inside its loop
-- `src/dlx/manifest.ts`: correct the `@fileoverview` "Primary API" list to match the actual `DlxManifest` methods (`get/set/clear/clearAll/isFresh/getManifestEntry`) and flag `setPackageEntry` / `setBinaryEntry` as deprecated
+- `@socketsecurity/lib/versions` `maxVersion()` / `minVersion()` — return the latest/earliest prerelease for all-prerelease inputs (previously returned `undefined`)
+- `@socketsecurity/lib/fs` `findUp()` / `findUpSync()` — traverse up to and **including** the filesystem root (previously missed matches at `/.foo`)
+- `@socketsecurity/lib/words` `capitalize()` — safe for non-BMP characters (emoji, astral-plane scripts); previously produced broken surrogate pairs
+- `@socketsecurity/lib/words` `determineArticle()` — case-insensitive vowel match (`Apple` → `an Apple`)
+- `@socketsecurity/lib/archives` `extractZip()` / `extractTar()` / `extractTarGz()` — missing-archive errors now uniformly surface as `ENOENT` with `code` / `path` / message (previously `extractZip` surfaced adm-zip's generic `"Invalid filename"`)
+- `@socketsecurity/lib/promise-queue` — bounded queue now rejects the newest submission when full, preserving in-flight work
+- `@socketsecurity/lib/cacache` / `@socketsecurity/lib/cache-with-ttl` — wildcard key deletion anchors both ends of the pattern (`deleteAll('foo*bar')` no longer sweeps `foo123bar-extra`)
+- `@socketsecurity/lib/process-lock` — sub-second `staleMs` values now honored at full precision; TOCTOU window on lock acquisition closed
+- `@socketsecurity/lib/suppress-warnings` `withSuppressedWarnings()` — no longer wipes concurrent suppressions on exit
+- Unbounded LRU caches in `@socketsecurity/lib/dlx` capped (binary path, package.json path); negative package.json lookups now expire after 10s
+- Glob cache keys for array-valued options (e.g. `ignore`) are order-insensitive
 
-## [5.19.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.1) - 2026-04-19
+### Performance
 
-### Fixed — stdio (restore accidentally-dropped modules)
+- `@socketsecurity/lib/memoization` — `memoize()` / `memoizeAsync()` cache-hit bookkeeping dropped from O(n) to O(1). Noticeable on caches with many entries
+- `@socketsecurity/lib/cacache` — wildcard `clear()` no longer recompiles the match regex per streamed entry
 
-5.19.0 shipped a breaking change that was not called out in its changelog or version bump: a refactor commit removed `stdio/prompts`, `stdio/progress`, `stdio/clear`, and the vendored `external/@inquirer/*` shims. socket-cli and other consumers import `stdio/prompts` directly and broke on upgrade.
+## [5.20.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.1) - 2026-04-19
 
-Restored:
+### Fixed
 
-- `@socketsecurity/lib/stdio/prompts` — inquirer wrappers (`password`, `confirm`, `input`, `select`, `checkbox`, `search`)
-- `@socketsecurity/lib/stdio/progress` — progress-bar utility (`ProgressBar` class)
-- `@socketsecurity/lib/stdio/clear` — terminal line/screen/cursor helpers
-- `src/external/@inquirer/{checkbox,confirm,input,password,search,select}.js` vendor shims
-- Corresponding test suites
+- `@socketsecurity/lib/ipc` — harden stub-file writes against symlink/TOCTOU attacks on shared-tmp filesystems (POSIX ownership + mode validation, `O_EXCL | O_NOFOLLOW` open)
+- `@socketsecurity/lib/cache-with-ttl` `getOrFetch()` — close concurrent-caller race that let two cold-cache awaits both skip the inflight-dedupe check and fire the fetcher twice
+- `@socketsecurity/lib/cache-with-ttl` — cap the in-memory memo layer with LRU eviction (`memoMaxSize`, default 1000); long-running processes no longer grow unbounded
+- `@socketsecurity/lib/memoization` `memoizeAsync()` — refresh cache entry timestamp on resolve so slow fetches (longer than `ttl`) aren't classified as expired the moment they land
+- `@socketsecurity/lib/tables` — `displayWidth` now measures rendered terminal cells (via `stringWidth`) instead of UTF-16 code units; CJK / emoji / combining marks align correctly
+- `@socketsecurity/lib/paths/packages` — `resolvePackageJsonDirname` / `resolvePackageJsonPath` no longer mis-identify files like `/foo/my-package.json` as package manifests
+- `@socketsecurity/lib/json/edit` — `@example` import path corrected
 
-## [5.19.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.0) - 2026-04-19
+## [5.20.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.20.0) - 2026-04-19
 
-### Added — dlx/integrity (new module)
+### Added
 
-- `HashSpec`, `NormalizedHash`, `ComputedHashes` types. `HashSpec` accepts a bare string (sha512 SRI or sha256 hex, sniffed) or an explicit `{ type, value }` object
-- `normalizeHash()`, `computeHashes()`, `verifyHash()` — `verifyHash` uses `crypto.timingSafeEqual` for constant-time comparison
-- `DlxHashMismatchError` — carries `expected` + `actual` for diagnostics
+- `@socketsecurity/lib/validation/validate-schema` — universal Zod-style schema validator with `validateSchema` (tagged result) and `parseSchema` (throwing); `Infer<S>`, `ValidateResult<T>`, `ValidationIssue`, `AnySchema` types. No runtime `zod` dependency
 
-### Added — dlx/arborist (new module)
+> **Deprecated in 5.21.0**: moved to `@socketsecurity/lib/schema/*`.
+
+### Fixed
 
-- `safeIdealTree()`, `safeReify()` — hardened `@npmcli/arborist` wrappers mirroring socket-cli v1.1.79 `SafeArborist` overrides (`audit: false`, `fund: false`, `ignoreScripts: true`, `progress: false`, `saveBundle: false`, `silent: true`)
-- `writeSafeNpmrc()` — defense-in-depth `.npmrc` writer matching the Arborist overrides
-- Optional `before?: Date` on `safeIdealTree` for release-age enforcement during resolution
+- `@socketsecurity/lib/promise-queue` — synchronous throws inside a queued task now convert to proper rejections instead of escaping as uncaught exceptions
+- `@socketsecurity/lib/stdio/progress` `formatTime()` — clamp negative milliseconds so over-ticking / clock-skewed bars don't render negative ETAs
+- `@socketsecurity/lib/dlx/lockfile` — scratch-directory cleanup can no longer clobber the real exception from the main block
+- `@socketsecurity/lib/dlx/package` `parsePackageSpec` — normalize a bare trailing `@` (e.g. `"pkg@"`) to `version: undefined`
+- `@socketsecurity/lib/stdio/prompts` — tighten an internal destructure type away from `as any`
+- `@socketsecurity/lib/http-request` — hoist checksum regex literals out of a per-line loop
 
-### Added — dlx/lockfile (new module)
+## [5.19.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.1) - 2026-04-19
 
-- `generatePackagePin({ package, minReleaseDays?, minReleaseMins? })` — returns `PinDetails { name, version, hash: ComputedHashes, packageJson, lockfile }`. Runs Arborist in `packageLockOnly: true` mode against a tmp directory and auto-cleans
-- **Default `minReleaseDays: 7`** — resolution refuses to select versions published in the last week. Pass `0` to disable. `minReleaseMins` is a pnpm-style alias (mutually exclusive with `minReleaseDays`)
-- `LockfileSpec` type — export for use as the new `lockfile` option on `downloadPackage`
+### Fixed
 
-### Added — dlx existing modules
+Restore `@socketsecurity/lib/stdio/prompts`, `@socketsecurity/lib/stdio/progress`, and `@socketsecurity/lib/stdio/clear` — accidentally removed in 5.19.0 without a major-bump callout. Downstream consumers that import `stdio/prompts` directly are unbroken.
 
-- `DlxPackageOptions.hash?: HashSpec` and `DlxPackageOptions.lockfile?: LockfileSpec` — passing a lockfile materializes it into the install dir (path → `fs.copyFileSync`, content → `fs.writeFileSync`) and drops a hardened `.npmrc` alongside before Arborist runs
-- `DlxBinaryOptions.hash?: HashSpec` — ergonomic alternative to the lower-level `integrity` and `sha256` fields (both still accepted)
+## [5.19.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.19.0) - 2026-04-19
 
-### Fixed — external
+### Added
 
-- `pacote` shim now exposes `tarball`, `manifest`, `packument` alongside `extract`. **Fixes a latent runtime crash** in `src/packages/manifest.ts` callers (`fetchPackageManifest` / `fetchPackagePackument` called `.manifest(...)` / `.packument(...)` on a shim that previously only had `extract`, raising `TypeError: not a function`)
+- `@socketsecurity/lib/dlx/integrity` — hash verification utilities: `HashSpec`, `NormalizedHash`, `ComputedHashes`, `normalizeHash()`, `computeHashes()`, `verifyHash()` (constant-time via `crypto.timingSafeEqual`), `DlxHashMismatchError`
+- `@socketsecurity/lib/dlx/arborist` — hardened `@npmcli/arborist` wrappers: `safeIdealTree()`, `safeReify()`, `writeSafeNpmrc()`. Locks down `audit`, `fund`, `ignoreScripts`, `saveBundle`, etc. Supports `before?: Date` for release-age enforcement
+- `@socketsecurity/lib/dlx/lockfile` — `generatePackagePin()` returns `{ name, version, hash, packageJson, lockfile }` for a resolved package. Default `minReleaseDays: 7` refuses versions published in the last week (`0` to disable); `minReleaseMins` accepted as pnpm-style alias
+- `DlxPackageOptions.hash`, `DlxPackageOptions.lockfile`, `DlxBinaryOptions.hash` — first-class integrity + lockfile options on the dlx entry points
 
-### Changed — build (bundle size)
+### Fixed
 
-- `dist/external/npm-pack.js`: 2,526,598 → 1,755,460 bytes (−771 KB, −30.5%). New `STUB_MAP` entries for code paths our callers never reach:
-  - `@sigstore/{bundle,core,protobuf-specs,sign,tuf,verify}`, `sigstore`, `tuf-js`, `@tufjs/{canonical-json,models}` — Sigstore attestation, only reached via `arb.audit()`
-  - `@npmcli/metavuln-calculator` — audit-only
-  - `@npmcli/query`, `postcss-selector-parser` — `arb.query()` unused
-  - `@npmcli/run-script`, `@npmcli/node-gyp` — guarded out by `ignoreScripts: true`
-  - `@npmcli/git`, `pacote/lib/{git,file,dir,remote}.js` — registry specs only
-  - arborist `audit-report.js`, `yarn-lock.js`, `isolated-reifier.js`, `query-selector-all.js`, `printable.js` — each gated or unused
-  - `cacache/lib/verify.js` — `cacache.verify` (npm cache verify) unused
-  - `proggy` — progress tracker, gated by `progress: false`
-  - `debug/src/browser.js` — Node-only bundle
-- `dist/external/zod.js`: 597,238 → 291,430 bytes (−306 KB, −51.2%). Stubbed `zod/v4/{core,classic,mini}`'s eager `locales/index.cjs` barrel (40+ translation modules). Opt-in via `z.config(z.locales.xx())` is never called by us
+- `pacote` shim — exposes `tarball`, `manifest`, `packument` alongside `extract`. Fixes a latent runtime crash in `fetchPackageManifest` / `fetchPackagePackument` callers
+
+### Changed
+
+Reduced bundle size of `dist/external/npm-pack.js` (−771 KB, −30.5%) and `dist/external/zod.js` (−306 KB, −51.2%) by stubbing code paths our callers never reach (Sigstore attestation, arborist audit/query, zod locale translations, etc.)
 
 ## [5.18.2](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.2) - 2026-04-14
 
@@ -100,70 +108,63 @@ Restored:
 
 ## [5.18.1](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.1) - 2026-04-14
 
-### Changed — build
+### Changed
 
-- Dedup npm-pack.js bundle via pnpm overrides: pacote 21.5.0, make-fetch-happen 15.0.5, and 7 transitive npm packages (npm-bundled, npm-normalize-package-bin, json-parse-even-better-errors, @npmcli/installed-package-contents, @npmcli/name-from-folder, @npmcli/promise-spawn, @npmcli/redact)
-- npm-pack.js: 69,738 → 66,443 lines (2.59MB → 2.46MB), 22 duplicate packages removed
+- Deduplicated the `dist/external/npm-pack` bundle via `pnpm overrides` (pacote 21.5.0, make-fetch-happen 15.0.5, and 7 transitive `@npmcli/*` packages) — 22 duplicate packages removed, ~130 KB smaller
 
 ## [5.18.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.18.0) - 2026-04-14
 
-### Added — dlx
+### Added
 
-- Socket Firewall API check before package downloads — resolves dependency tree via `buildIdealTree`, checks all packages against `firewall-api.socket.dev/purl` in parallel, blocks on critical/high severity alerts
+- `@socketsecurity/lib/dlx` — Socket Firewall API check before package downloads. Resolves the dependency tree and blocks on critical/high severity alerts
 
-### Changed — http-request
+### Changed
 
-- Default `User-Agent` header updated from `socket-registry/1.0` to `socketsecurity-lib/{version}`
+- `@socketsecurity/lib/http-request` — default `User-Agent` updated from `socket-registry/1.0` to `socketsecurity-lib/{version}`
 
 ## [5.17.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.17.0) - 2026-04-14
 
-### Added — paths
+### Added
 
-- `isUnixPath()` — detect MSYS/Git Bash drive letter notation (`/c/...`)
+- `@socketsecurity/lib/paths` `isUnixPath()` — detect MSYS/Git Bash drive-letter notation (`/c/...`)
 
-### Changed — paths
+### Changed
 
-- `normalizePath()` now converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
-- `fromUnixPath()` now produces native Windows paths with backslashes (`/c/path` → `C:\path`), making it the true inverse of `toUnixPath()`
+- `@socketsecurity/lib/paths` `normalizePath()` — converts MSYS drive letters on Windows (`/c/path` → `C:/path`)
+- `@socketsecurity/lib/paths` `fromUnixPath()` — produces native Windows paths with backslashes (`/c/path` → `C:\path`), making it the true inverse of `toUnixPath()`
 
 ## [5.16.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.16.0) - 2026-04-14
 
-### Added — paths
+### Added
 
-- `fromUnixPath()` — convert MSYS/Git Bash Unix-style paths (`/c/path`) back to native Windows format (`C:/path`), inverse of `toUnixPath` (#168)
+- `@socketsecurity/lib/paths` `fromUnixPath()` — convert MSYS/Git Bash Unix-style paths (`/c/path`) back to native Windows format (`C:/path`), inverse of `toUnixPath` (#168)
 
-### Fixed — dlx
+### Fixed
 
-- Normalize dlx directory path in `isInSocketDlx` for Windows compatibility
+- `@socketsecurity/lib/dlx` `isInSocketDlx` — normalize the dlx directory path for Windows compatibility
 
 ## [5.15.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.15.0) - 2026-04-06
 
-### Added — http-request
-
-- `stream` option on `HttpRequestOptions` — resolves with `HttpResponse` immediately after headers arrive, leaving `rawResponse` unconsumed for piping to files
-- `headers`, `ok`, `status`, `statusText` fields on `HttpDownloadResult`
-
-### Changed — http-request
+### Added
 
-- `httpDownload` now uses `httpRequest` with `stream: true` internally, eliminating ~120 lines of duplicated HTTP plumbing
+- `@socketsecurity/lib/http-request` — `stream` option on `HttpRequestOptions` resolves with `HttpResponse` immediately after headers arrive, leaving `rawResponse` unconsumed for piping to files
+- `@socketsecurity/lib/http-request` — `headers`, `ok`, `status`, `statusText` fields on `HttpDownloadResult`
 
 ## [5.14.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.14.0) - 2026-04-06
 
-### Added — http-request
+### Added
 
-- `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled, carries the full `HttpResponse`
-- `throwOnError` option on `HttpRequestOptions` — non-2xx responses throw instead of resolving with `ok: false`, enabling retry of HTTP errors
-- `onRetry` callback on `HttpRequestOptions` — customize retry behavior per-attempt (return `false` to stop, a `number` to override delay, `undefined` for default backoff)
-- Streaming body support — `body` accepts `Readable` streams (incl. `form-data` npm package), auto-merges `getHeaders()` when present
-- `parseRetryAfterHeader()` — standalone RFC 7231 §7.1.3 `Retry-After` header parser (strict integer seconds + HTTP-date formats)
-- `sanitizeHeaders()` — redact sensitive headers (`authorization`, `cookie`, `set-cookie`, `proxy-authorization`, `proxy-authenticate`, `www-authenticate`) for safe logging
+- `@socketsecurity/lib/http-request`:
+  - `HttpResponseError` class — thrown on non-2xx when `throwOnError` is enabled; carries the full `HttpResponse`
+  - `throwOnError` option — non-2xx responses throw instead of resolving with `ok: false`
+  - `onRetry` callback — customize retry behavior per-attempt (`false` to stop, a `number` to override delay, `undefined` for default backoff)
+  - Streaming body support — `body` accepts `Readable` streams (incl. `form-data`), auto-merges `getHeaders()` when present
+  - `parseRetryAfterHeader()` — standalone RFC 7231 §7.1.3 parser
+  - `sanitizeHeaders()` — redact sensitive headers for safe logging
 
-### Changed — http-request
+### Changed
 
-- `HttpRequestOptions.body` type widened from `Buffer | string` to `Buffer | Readable | string`
-- Redirect responses now drained via `res.resume()` to free sockets
-- `maxResponseSize` exceeded now cleans up both response and request
-- `onResponse` hooks wrapped in try/catch — user hook errors can no longer leave promises pending
+- `@socketsecurity/lib/http-request` — `HttpRequestOptions.body` widened to `Buffer | Readable | string`; `onResponse` hook errors no longer leave promises pending
 
 ## [5.13.0](https://github.com/SocketDev/socket-lib/releases/tag/v5.13.0) - 2026-04-05
 

package/dist/archives.js

@@ -80,6 +80,16 @@ function validatePathWithinBase(targetPath, baseDir, entryName) {
     );
   }
 }
+function assertArchiveExists(archivePath) {
+  if (!(0, import_node_fs.existsSync)(archivePath)) {
+    const err = new Error(
+      `ENOENT: no such file or directory, open '${archivePath}'`
+    );
+    err.code = "ENOENT";
+    err.path = archivePath;
+    throw err;
+  }
+}
 function detectArchiveFormat(filePath) {
   const lower = filePath.toLowerCase();
   if (lower.endsWith(".tar.gz")) {
@@ -116,6 +126,7 @@ async function extractArchive(archivePath, outputDir, options = {}) {
   }
 }
 async function extractTar(archivePath, outputDir, options = {}) {
+  assertArchiveExists(archivePath);
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
@@ -207,6 +218,7 @@ async function extractTar(archivePath, outputDir, options = {}) {
   }
 }
 async function extractTarGz(archivePath, outputDir, options = {}) {
+  assertArchiveExists(archivePath);
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,
@@ -298,6 +310,7 @@ async function extractTarGz(archivePath, outputDir, options = {}) {
   }
 }
 async function extractZip(archivePath, outputDir, options = {}) {
+  assertArchiveExists(archivePath);
   const {
     maxEntries = DEFAULT_MAX_ENTRIES,
     maxFileSize = DEFAULT_MAX_FILE_SIZE,

package/dist/cacache.js

@@ -41,17 +41,14 @@ __export(cacache_exports, {
 module.exports = __toCommonJS(cacache_exports);
 var import_cacache = __toESM(require("./external/cacache"));
 var import_socket = require("./paths/socket");
-function matchesPattern(key, pattern) {
+function createPatternMatcher(pattern) {
   if (!pattern.includes("*")) {
-    return key.startsWith(pattern);
+    return (key) => key.startsWith(pattern);
   }
-  const regex = patternToRegex(pattern);
-  return regex.test(key);
-}
-function patternToRegex(pattern) {
   const escaped = pattern.replaceAll(/[.+?^${}()|[\]\\]/g, "\\$&");
   const regexPattern = escaped.replaceAll("*", ".*");
-  return new RegExp(`^${regexPattern}`);
+  const regex = new RegExp(`^${regexPattern}$`);
+  return (key) => regex.test(key);
 }
 async function clear(options) {
   const opts = { __proto__: null, ...options };
@@ -84,9 +81,10 @@ async function clear(options) {
     return removed2;
   }
   let removed = 0;
+  const matches = createPatternMatcher(opts.prefix);
   const stream = cacache2.ls.stream(cacheDir);
   for await (const entry of stream) {
-    if (matchesPattern(entry.key, opts.prefix)) {
+    if (matches(entry.key)) {
       try {
         await cacache2.rm.entry(cacheDir, entry.key);
         removed++;

package/dist/cache-with-ttl.js

@@ -84,7 +84,7 @@ function createTtlCache(options) {
     }
     const escaped = fullPattern.replaceAll(/[.+?^${}()|[\]\\]/g, "\\$&");
     const regexPattern = escaped.replaceAll("*", ".*");
-    const regex = new RegExp(`^${regexPattern}`);
+    const regex = new RegExp(`^${regexPattern}$`);
     return (key) => regex.test(key);
   }
   async function get(key) {

package/dist/constants/socket.js

@@ -77,7 +77,7 @@ const SOCKET_FIREWALL_APP_NAME = "sfw";
 const SOCKET_REGISTRY_APP_NAME = "registry";
 const SOCKET_APP_PREFIX = "_";
 const SOCKET_LIB_NAME = "@socketsecurity/lib";
-const SOCKET_LIB_VERSION = "5.20.1";
+const SOCKET_LIB_VERSION = "5.21.0";
 const SOCKET_LIB_URL = "https://github.com/SocketDev/socket-lib";
 const SOCKET_LIB_USER_AGENT = `socketsecurity-lib/${SOCKET_LIB_VERSION} (${SOCKET_LIB_URL})`;
 const SOCKET_IPC_HANDSHAKE = "SOCKET_IPC_HANDSHAKE";

package/dist/dlx/detect.js

@@ -33,7 +33,20 @@ var import_socket = require("../paths/socket");
 let _fs;
 let _path;
 const NODE_JS_EXTENSIONS = /* @__PURE__ */ new Set([".js", ".mjs", ".cjs"]);
+const PACKAGE_JSON_PATH_CACHE_MAX_SIZE = 200;
+const PACKAGE_JSON_NEGATIVE_TTL_MS = 1e4;
 const packageJsonPathCache = /* @__PURE__ */ new Map();
+function packageJsonPathCacheSet(key, value) {
+  if (packageJsonPathCache.has(key)) {
+    packageJsonPathCache.delete(key);
+  } else if (packageJsonPathCache.size >= PACKAGE_JSON_PATH_CACHE_MAX_SIZE) {
+    const oldest = packageJsonPathCache.keys().next().value;
+    if (oldest !== void 0) {
+      packageJsonPathCache.delete(oldest);
+    }
+  }
+  packageJsonPathCache.set(key, { path: value, at: Date.now() });
+}
 const packageJsonContentCache = /* @__PURE__ */ new Map();
 function findPackageJson(filePath) {
   const fs = /* @__PURE__ */ getFs();
@@ -41,25 +54,29 @@ function findPackageJson(filePath) {
   const startDir = path.dirname(path.resolve(filePath));
   const cached = packageJsonPathCache.get(startDir);
   if (cached !== void 0) {
-    if (cached === null) {
-      return void 0;
-    }
-    if (fs.existsSync(cached)) {
-      return cached;
+    if (cached.path === null) {
+      if (Date.now() - cached.at < PACKAGE_JSON_NEGATIVE_TTL_MS) {
+        return void 0;
+      }
+      packageJsonPathCache.delete(startDir);
+    } else if (fs.existsSync(cached.path)) {
+      packageJsonPathCacheSet(startDir, cached.path);
+      return cached.path;
+    } else {
+      packageJsonPathCache.delete(startDir);
     }
-    packageJsonPathCache.delete(startDir);
   }
   let currentDir = startDir;
   const root = path.parse(currentDir).root;
   while (currentDir !== root) {
     const packageJsonPath = path.join(currentDir, "package.json");
     if (fs.existsSync(packageJsonPath)) {
-      packageJsonPathCache.set(startDir, packageJsonPath);
+      packageJsonPathCacheSet(startDir, packageJsonPath);
       return packageJsonPath;
     }
     currentDir = path.dirname(currentDir);
   }
-  packageJsonPathCache.set(startDir, null);
+  packageJsonPathCacheSet(startDir, null);
   return void 0;
 }
 // @__NO_SIDE_EFFECTS__

package/dist/dlx/package.js

@@ -62,7 +62,19 @@ const FIREWALL_BLOCK_SEVERITIES = /* @__PURE__ */ new Set([
   "critical",
   "high"
 ]);
+const BINARY_PATH_CACHE_MAX_SIZE = 200;
 const binaryPathCache = /* @__PURE__ */ new Map();
+function binaryPathCacheSet(key, value) {
+  if (binaryPathCache.has(key)) {
+    binaryPathCache.delete(key);
+  } else if (binaryPathCache.size >= BINARY_PATH_CACHE_MAX_SIZE) {
+    const oldest = binaryPathCache.keys().next().value;
+    if (oldest !== void 0) {
+      binaryPathCache.delete(oldest);
+    }
+  }
+  binaryPathCache.set(key, value);
+}
 async function checkFirewallPurls(arb, requestedPackage) {
   const idealTree = arb.idealTree;
   if (!idealTree) {
@@ -431,6 +443,7 @@ function resolveBinaryPath(basePath) {
   const cached = binaryPathCache.get(basePath);
   if (cached) {
     if (fs.existsSync(cached)) {
+      binaryPathCacheSet(basePath, cached);
       return cached;
     }
     binaryPathCache.delete(basePath);
@@ -439,7 +452,7 @@ function resolveBinaryPath(basePath) {
   for (const ext of extensions) {
     const testPath = basePath + ext;
     if (fs.existsSync(testPath)) {
-      binaryPathCache.set(basePath, testPath);
+      binaryPathCacheSet(basePath, testPath);
       return testPath;
     }
   }

package/dist/fs.js

@@ -167,7 +167,7 @@ async function findUp(name, options) {
   let dir = path.resolve(cwd);
   const { root } = path.parse(dir);
   const names = (0, import_arrays.isArray)(name) ? name : [name];
-  while (dir && dir !== root) {
+  while (dir) {
     for (const n of names) {
       if (signal?.aborted) {
         return void 0;
@@ -184,6 +184,9 @@ async function findUp(name, options) {
       } catch {
       }
     }
+    if (dir === root) {
+      break;
+    }
     dir = path.dirname(dir);
   }
   return void 0;
@@ -210,7 +213,7 @@ function findUpSync(name, options) {
   const { root } = path.parse(dir);
   const stopDir = stopAt ? path.resolve(stopAt) : void 0;
   const names = (0, import_arrays.isArray)(name) ? name : [name];
-  while (dir && dir !== root) {
+  while (dir) {
     if (stopDir && dir === stopDir) {
       for (const n of names) {
         const thePath = path.join(dir, n);
@@ -240,6 +243,9 @@ function findUpSync(name, options) {
       } catch {
       }
     }
+    if (dir === root) {
+      break;
+    }
     dir = path.dirname(dir);
   }
   return void 0;

package/dist/globs.js

@@ -91,7 +91,11 @@ function getPicomatch() {
 function getGlobMatcher(glob2, options) {
   const patterns = Array.isArray(glob2) ? glob2 : [glob2];
   const sortedPatterns = [...patterns].sort();
-  const sortedOptions = options ? Object.keys(options).sort().map((k) => `${k}:${JSON.stringify(options[k])}`).join(",") : "";
+  const sortedOptions = options ? Object.keys(options).sort().map((k) => {
+    const value = options[k];
+    const normalized = Array.isArray(value) ? [...value].sort() : value;
+    return `${k}:${JSON.stringify(normalized)}`;
+  }).join(",") : "";
   const key = `${sortedPatterns.join("|")}:${sortedOptions}`;
   const existing = matcherCache.get(key);
   if (existing) {

package/dist/ipc.js

@@ -37,7 +37,7 @@ module.exports = __toCommonJS(ipc_exports);
 var import_node_process = __toESM(require("node:process"));
 var import_typebox = require("./external/@sinclair/typebox");
 var import_socket = require("./paths/socket");
-var import_validate_schema = require("./validation/validate-schema");
+var import_parse = require("./schema/parse");
 const IpcStubSchema = import_typebox.Type.Object({
   /** Process ID that created the stub. */
   pid: import_typebox.Type.Integer({ minimum: 1 }),
@@ -100,7 +100,7 @@ async function writeIpcStub(appName, data) {
     pid: import_node_process.default.pid,
     timestamp: Date.now()
   };
-  const validated = (0, import_validate_schema.parseSchema)(IpcStubSchema, ipcData);
+  const validated = (0, import_parse.parseSchema)(IpcStubSchema, ipcData);
   const fs = /* @__PURE__ */ getFs();
   const flags = fs.constants.O_CREAT | fs.constants.O_WRONLY | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW;
   let handle;

package/dist/json/parse.d.ts

@@ -1,8 +1,11 @@
 /**
  * @fileoverview JSON parsing utilities with Buffer detection and BOM stripping.
- * Provides safe JSON parsing with automatic encoding handling.
+ * Provides safe JSON parsing with automatic encoding handling, plus
+ * `safeJsonParse` for untrusted input (prototype-pollution protection +
+ * size limits + optional schema validation).
  */
-import type { JsonParseOptions, JsonPrimitive, JsonValue } from './types';
+import type { Schema } from '../schema/types';
+import type { JsonParseOptions, JsonPrimitive, JsonValue, SafeJsonParseOptions } from './types';
 /**
  * Check if a value is a JSON primitive type.
  * JSON primitives are: `null`, `boolean`, `number`, or `string`.
@@ -76,3 +79,45 @@ export declare function isJsonPrimitive(value: unknown): value is JsonPrimitive;
  * ```
  */
 export declare function jsonParse(content: string | Buffer, options?: JsonParseOptions | undefined): JsonValue | undefined;
+/**
+ * Safely parse JSON with optional schema validation and security controls.
+ * Throws on parse failure, validation failure, or security violation.
+ *
+ * Recommended for parsing untrusted JSON (user input, network payloads,
+ * anything beyond a trust boundary). Layers:
+ * 1. Size cap (default 10 MB) prevents memory exhaustion.
+ * 2. Prototype-pollution reviver rejects `__proto__` / `constructor` /
+ *    `prototype` keys at any depth (unless `allowPrototype: true`).
+ * 3. Optional Zod-shaped schema validation via
+ *    `@socketsecurity/lib/schema/validate`.
+ *
+ * For trusted-source reads (package.json, local config files), prefer
+ * `jsonParse()` — it offers Buffer/BOM handling and filepath-aware error
+ * messages, without the untrusted-input overhead.
+ *
+ * @throws {Error} When `jsonString` exceeds `maxSize`.
+ * @throws {Error} When JSON parsing fails.
+ * @throws {Error} When prototype-pollution keys are detected (and
+ *   `allowPrototype` is not `true`).
+ * @throws {Error} When schema validation fails.
+ *
+ * @example
+ * ```ts
+ * // Basic parsing with type inference.
+ * const data = safeJsonParse<User>('{"name":"Alice","age":30}')
+ *
+ * // With schema validation.
+ * import { z } from 'zod'
+ * const userSchema = z.object({ name: z.string(), age: z.number() })
+ * const user = safeJsonParse('{"name":"Alice","age":30}', userSchema)
+ *
+ * // With size limit.
+ * const data = safeJsonParse(jsonString, undefined, { maxSize: 1024 })
+ *
+ * // Allow prototype keys (DANGEROUS — only for trusted sources).
+ * const data = safeJsonParse('{"__proto__":{}}', undefined, {
+ *   allowPrototype: true,
+ * })
+ * ```
+ */
+export declare function safeJsonParse<T = unknown>(jsonString: string, schema?: Schema<T> | undefined, options?: SafeJsonParseOptions): T;