Installation

# Preserve existing imports with an npm alias
npm install http-server@npm:@stackline/http-server@1.0.0
# Or use the scoped package name in your imports
npm install @stackline/http-server@1.0.0

Node.js: >=12. Read the compatibility and maintenance notes before migrating.

Usage and API

The reference below may retain upstream package names. Use the alias installation above to run those imports with this Stackline release.

@stackline/http-server

Independent maintenance fork of http-server@14.1.1, preserving its API and published type declarations.

npm install @stackline/http-server
# Keep existing imports:
npm install http-server@npm:@stackline/http-server@1.0.0

Stackline · Issues · Community

See UPSTREAM.md for source identity and issue review, and CHANGELOG.md for maintenance changes. Functional tests also run against the final npm tarball; releases are published from GitHub Actions with provenance.

Upstream documentation

http-server: a simple static HTTP server

http-server is a simple, zero-configuration command-line static HTTP server. It is powerful enough for production usage, but it's simple and hackable enough to be used for testing, local development and learning.

Installation:

Running on-demand:

Using npx you can run the script without installing it first:

npx http-server [path] [options]

Globally via npm

npm install --global http-server

This will install http-server globally so that it may be run from the command line anywhere.

Globally via Homebrew

brew install http-server
 

As a dependency in your npm package:

npm install http-server

Usage:

 http-server [path] [options]

[path] defaults to ./public if the folder exists, and ./ otherwise.

Now you can visit http://localhost:8080 to view your server

Note: Caching is on by default. Add -c-1 as an option to disable caching.

Available Options:

Magic Files

• index.html will be served as the default file to any directory requests.
• 404.html will be served if a file is not found. This can be used for Single-Page App (SPA) hosting to serve the entry page.

Catch-all redirect

To implement a catch-all redirect, use the index page itself as the proxy with:

http-server --proxy http://localhost:8080?

Note the ? at the end of the proxy URL. Thanks to @houston3 for this clever hack!

TLS/SSL

First, you need to make sure that openssl is installed correctly, and you have key.pem and cert.pem files. You can generate them using this command:

openssl req -newkey rsa:2048 -new -nodes -x509 -days 3650 -keyout key.pem -out cert.pem

You will be prompted with a few questions after entering the command. Use 127.0.0.1 as value for Common name if you want to be able to install the certificate in your OS's root certificate store or browser so that it is trusted.

This generates a cert-key pair and it will be valid for 3650 days (about 10 years).

Then you need to run the server with -S for enabling SSL and -C for your certificate file.

http-server -S -C cert.pem

If you wish to use a passphrase with your private key you can include one in the openssl command via the -passout parameter (using password of foobar)

e.g. openssl req -newkey rsa:2048 -passout pass:foobar -keyout key.pem -x509 -days 365 -out cert.pem

For security reasons, the passphrase will only be read from the NODE_HTTP_SERVER_SSL_PASSPHRASE environment variable.

This is what should be output if successful:

Starting up http-server, serving ./ through https

http-server settings:
CORS: disabled
Cache: 3600 seconds
Connection Timeout: 120 seconds
Directory Listings: visible
AutoIndex: visible
Serve GZIP Files: false
Serve Brotli Files: false
Default File Extension: none

Available on:
  https://127.0.0.1:8080
  https://192.168.1.101:8080
  https://192.168.1.104:8080
Hit CTRL-C to stop the server

Development

Checkout this repository locally, then:

$ npm i
$ npm start

Now you can visit http://localhost:8080 to view your server

You should see the turtle image in the screenshot above hosted at that URL. See the ./public folder for demo content.

Upstream issues and maintenance review

Upstream review

Independent maintenance of http-server14.1.1. Source https://github.com/http-party/http-server/tree/af0ac3e4b9bd5fff55337aee32bf37f6116c7b4f

Original published files and SHA-256 hashes are recorded in .stackline/upstream.json. The parser/server API, CLI name, license, original authors and Node >=12 declaration are retained. Development/release tests use Node24.

Issue evidence collected: 2026-09-29T00:24:08.203209+00:00. The latest100 open and30 closed entries were collected, then pull requests filtered. The following table records all71 open issue entries returned; it is not a claim that every issue was reproduced or fixed.

Validation

All31 original test files run with maintained Tap and a compatible maintained Request client. Removed Tap method aliases are updated and the HTTP test client disables connection pooling to avoid reusing closed fixture servers. The source and extracted final package run the original suite and focused HTTP regressions. Runtime and full workspace audits must report zero findings.

Release completion requires the exact CI tarball, successful CodeQL with zero open alerts, npm provenance/identity, direct and alias consumers, and identical immutable release assets.

Security review after CodeQL

The CORS parser, directory boundary and directory redirect have focused fixes and real HTTP regressions. Remaining scanner findings and the trusted-root/symlink boundary are explained in CODEQL_REVIEW.md. Runtime remains fully scanned; this is not a physical filesystem sandbox.

Dependency scope qualification

The compatible html-encoding-sniffer3 runtime branch inherits the deprecated whatwg-encoding2 package. Newer sniffer majors increase the minimum Node version; this release retains Node12 compatibility. The warning is recorded in consumer evidence, with zero known vulnerability findings and valid dependency trees. This is a direct-parent migration, not an unrestricted recursive-maintenance policy pass.

Security review

Directory and redirect CodeQL review

Reviewed against commit d0cb8dd9c9fc81b61a144e684da9daa5cb0ab1a5 and the subsequent regression suite.

The CORS regular-expression backtracking issue is fixed by splitting on literal commas and trimming each field. The original protocol-relative directory redirect is fixed by constructing a single-rooted location and escaping backslashes.

Remaining alerts 2, 3 and 4 (path-injection) cross the explicit containment guard in lib/core/show-dir/index.js. The path is decoded and normalized before requiring equality with the configured root or its separator-delimited prefix. Root-prefix siblings and malformed escapes are tested. Child names passed to sort-files come from fs.readdir, not a user-supplied list. These flows are false positives for lexical directory traversal after the guard.

This preserves upstream behavior that follows filesystem symlinks placed by the operator. The configured root and its symlinks are trusted configuration; the server is not a realpath sandbox or a defense against concurrent filesystem modifications by another local actor.

Alert 6 (unvalidated redirect) crosses a location constructor that prepends one slash, removes all leading slash/backslash characters, and percent-encodes other backslashes. Real HTTP regressions cover protocol-relative paths, escapes, control characters and hostile query values; every emitted redirect remains on the current origin. This remaining finding is a false positive for an external redirect after the fix.

All runtime remains analyzed. No CodeQL query or path is disabled. Full upstream tests, extracted-package tests, targeted security regressions and zero-advisory source/runtime audits are required before publication. A second read-only review independently checked the containment and redirect construction.

Release changes

Changelog

1.0.0

• Start Stackline maintenance of the documented upstream API.

• Preserve and verify published runtime files and TypeScript declarations.

• Run upstream functional suites against both source and the final package.

• Publish the reviewed CI artifact through GitHub Actions with provenance and immutable release evidence.

• Fix issue 825: recognize the string true produced by the CLI robots flag.

• Fix issues 636/757: reject cyclic proxy forwarding with HTTP 508 before requests grow without bound. Existing proxy headers are preserved.

• Modernize the upstream test harness and HTTP client; preserve all upstream functional cases.

• Keep directory redirects on the same origin, enforce directory listing containment with a path separator boundary, reject malformed path escapes, and parse CORS header lists in linear time.

• Record the inherited whatwg-encoding2 deprecation in release evidence while retaining the compatible encoding sniffer and Node12 contract.

Release files and references

• README.md
• UPSTREAM.md
• CHANGELOG.md
• CODEQL_REVIEW.md
• LICENSE
• NOTICE
• Package and publication metadata
• Full text documentation

Package bytes, npm provenance and the immutable GitHub release were verified for this version. Security checks describe the reviewed release; documented compatibility risks and upstream reports are not blanket claims of resolution.