# Security

Report suspected vulnerabilities through the private GitHub security advisory
form for the project repository. Do not disclose an unfixed issue in a public
ticket. Include package and runtime versions, environment, a minimal generated
source and map, installation options, retrieval behavior, stack output, and
impact. Remove secrets and proprietary source from the report.

## Supported line

The latest `1.x` line targets Node.js 14.15.1 and newer. Browser support is the
documented standalone bundle contract, not a promise for every JavaScript
engine.

## Prefer native Node for ordinary execution

Native source maps are the preferred path for ordinary modern Node files. Use
this package only for a verified residual contract such as VM-generated code,
historical register modules, browser delivery, or synchronous custom retrieval.
Fewer global hooks mean a smaller integration surface.

Do not install both native and userland mapping owners in a production process
without verifying their interaction, stack output, performance, and error
handling.

## Global process hooks

`install()` assigns `Error.prepareStackTrace`. Depending on options, it can
also wrap `process.emit` and private `Module.prototype._compile`. These are
global integration points, not isolated library instances; the optional Node
process hooks are process-global.

- Install once in the intended process or realm.
- Set `handleUncaughtExceptions: false` when another component owns process
  failures.
- Preserve a prior formatter explicitly if the application still needs it.
- Test profilers, test runners, telemetry, Electron main/renderer stacks, and
  any library that reads structured CallSites.
- Treat `hookRequire` as a private-Node loader integration and smoke-test every
  supported runtime.
- Do not treat `resetRetrieveHandlers()` as uninstall; it does not restore
  global hooks.

## Synchronous file, map, and network retrieval

Node defaults can synchronously read generated files and referenced maps.
Browser defaults can issue synchronous XHR for source and map URLs. Custom
providers run synchronously during stack work and may execute while handling
another application failure.

The package is not a filesystem, URL, network, or sandbox containment
mechanism. It does not impose an allowed root, origin allowlist, byte limit,
timeout, source-count limit, nesting limit, or total cache limit. Callers must:

- validate or replace retrieval for untrusted generated source names;
- constrain readable filesystem roots and allowable URL schemes/origins;
- preload or size-limit maps where latency and memory matter;
- keep custom providers bounded and catch their expected failures;
- avoid remote synchronous retrieval on latency-sensitive paths;
- measure real production map sizes and worst-case stack depth.

An override custom provider can replace default filesystem or XHR retrieval
when the application already owns a trusted artifact store.

## Source disclosure

Source maps can reveal filenames, directory structure, function names, and
original source. `sourcesContent` can embed the complete source text and any
secret accidentally present in it. Browser publication makes those bytes
available to clients even if the generated bundle is minified.

Review production maps as release artifacts. Remove secrets before building,
decide whether maps should be public, apply access controls where appropriate,
and remember that rollback cannot retract artifacts already downloaded.
`getErrorSource()` intentionally prints source context; do not send its output
to an untrusted destination without redaction.

## Malformed and hostile maps

The maintained implementation catches malformed map construction and lookup
failures, treats malformed inline browser base64 as a retrieval miss, caches
misses, uses null-prototype cache dictionaries, and preserves the generated
position. Long nonmatching source-map comments and retained unmapped files have
regression coverage. Indexed maps can contain nested `sections`; the caller's
resource budget must account for that structure.

Those corrections are defense-in-depth. There are still no hard resource
limits, and a custom provider can throw or return expensive object accessors.
Parse and map only within caller-defined resource budgets. Do not describe the
corrections as an assigned vulnerability, advisory, or CVE.

## Browser boundary

The browser UMD and ESM artifacts target ES2015. The UMD form exposes CommonJS,
named AMD, or a global namespace; a browser-aware root ESM import selects the
companion ESM host. Their bundled path implementation does not require a Node
`process` global. Default XHR retrieval is subject to browser origin and CORS
policy. Automatic stack formatting depends on compatible V8-style Error and
CallSite behavior. Direct mapping API success in a test realm does not prove
automatic error-stack behavior in every browser.

Content Security Policy, extension sandboxes, Electron context isolation, and
source-map hosting policy remain application responsibilities.

## License provenance

Security review does not replace license compliance. Preserve Evan Wallace's
MIT notice, the applicable V8 BSD 3-Clause terms for copied
`CallSiteToString`, and the exact MIT texts for all four components bundled in
the browser artifacts: the three @jridgewell packages and
`path-browserify@1.0.1`.