{"id":23260893,"url":"https://github.com/hieyou1/intertls","last_synced_at":"2026-05-04T05:39:45.447Z","repository":{"id":252011316,"uuid":"839067774","full_name":"hieyou1/intertls","owner":"hieyou1","description":"Manage multiple secure Node servers with one tool.","archived":false,"fork":false,"pushed_at":"2024-08-08T20:38:19.000Z","size":118,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-12T11:17:20.012Z","etag":null,"topics":["intertls","node","node-https","node-js","node-tls","node-web-server","nodejs","tls","web-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hieyou1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-06T22:51:04.000Z","updated_at":"2024-08-08T20:38:22.000Z","dependencies_parsed_at":"2024-08-07T06:55:50.670Z","dependency_job_id":"21376f5d-3efb-45e3-bb0e-3388bc95b77f","html_url":"https://github.com/hieyou1/intertls","commit_stats":null,"previous_names":["hieyou1/intertls"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hieyou1%2Fintertls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hieyou1%2Fintertls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hieyou1%2Fintertls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hieyou1%2Fintertls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hieyou1","download_url":"https://codeload.github.com/hieyou1/intertls/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247440161,"owners_count":20939205,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["intertls","node","node-https","node-js","node-tls","node-web-server","nodejs","tls","web-server"],"created_at":"2024-12-19T13:19:37.972Z","updated_at":"2026-05-04T05:39:40.403Z","avatar_url":"https://github.com/hieyou1.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# intertls\n\nManage multiple secure Node servers with one tool.\n\n## Warning\n\nThis project is in beta. There are lots of debug logs that have been left in.\n\nThe project has not been fully vetted for security vulnerabilities, and should not be used in production.\n\n## Features\n\n- Run and maintain multiple Node servers with one tool, each with its own process (and optionally its own user, group, working directory, and environment variables)\n- TLS SNI (think [vhost](https://github.com/expressjs/vhost), but for TLS)\n  - Different certificates for each host\n  - Distinct Mutual TLS (mTLS) settings for each host\n- Optional plaintext HTTP fallback\n\n## Intro\n\nThis project started out of a need to host multiple Node HTTPS servers on the same machine with some requiring mTLS and some not. My options were to either require mTLS on all endpoints and only enforce validation on some, which would create issues with UX, or use renegotiation and forgo the security benefits from the latest TLS version. So, I decided to build my own tool. Because I also needed to manage these servers, I decided to turn this tool into one that would automatically spawn these Node servers as well. It's still a work-in-progress, but most things should work.\n\n## Prerequisites\n\n- Recent version of Node\n- Recent version of TypeScript (one that supports project references)\n\n## Usage\n\n1. Install and configure the server.\n2. Create a server using Node.\n3. Pass the server (with options, if necessary) to the handler.\n4. Run InterTLS!\n\n## Installation\n\nTested on Ubuntu Server:\n\n```bash\n# clone the repo\ngit clone https://github.com/hieyou1/intertls.git\n# cd into the repo\ncd intertls-main\n# use your text editor of choice; see \"Configuration\" for details\nnano config.json\n# install packages\nnpm i\n# build\nnpm run build\n# run intertls\n./dist/run.js\n# install intertls as a service (for systems that use systemctl)\n  # fix path to intertls and create intertls.service\n  sed \"s|/PATH/TO/intertls|$(pwd)|g\" SAMPLE_intertls.service \u003e intertls.service\n  # copy service to systemctl\n  sudo cp intertls.service /etc/systemd/system\n  # start service\n  sudo systemctl start intertls.service\n  # (optional) enable service on boot\n  sudo systemctl enable intertls.service\n```\n\n## Configuration\n\n- `$schema`: For a full JSON schema, see [config.schema.json](https://github.com/hieyou1/intertls/blob/main/config.schema.json).\n- `log`: Centralized logging. Either a list of `LogType`s (`newsock` (high-level information about creation [and potential forced destruction] of new sockets), `sni`, `ipc`, `child_procs` (console logs from your servers), `handler` (logs from the InterTLS handler itself), `init`) or a `boolean` to enable/disable logging as a whole.\n- `port`: Main port InterTLS should listen on. Usually 443.\n- `encoding`: `BufferEncoding` InterTLS should use when transferring data in string format to and from its child processes (servers). utf8 is good for logging purposes, otherwise, base64 is probably a good bet.\n- `tcpFallback`: Set to true to enable the plaintext TCP \u0026 HTTP fallback; be sure to also set `tcpPort`.\n- `tcpPort`: Port InterTLS should listen on for `tcpFallback`. InterTLS expects plaintext HTTP traffic on this port. Usually 80. Ignored when `tcpFallback` is set to false.\n- `servers`: Array of servers for InterTLS to run, manage, and forward traffic to.\n  - `host`: String or string array specifying hostname(s) of this server. Should match the server name that clients pass in for SNI and the HTTP `Host` header if using TCP fallback.\n  - `tls`: TLS options for this server. Set to `{\"dynamic\": true}` to dynamically handle TLS, otherwise `cert`, `key`, and `requestCert` are required. `ca` and `rejectUnauthorized` are the two other options that have been tested and are explicitly defined in the schema, and YMMV with other [SecureContextOptions](https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions), but feel free to try them and PR!\n  - `process`: Node options for this server.\n    - `main`: Node entrypoint of the server.\n    - `cwd`: Working directory of the server.\n    - `env` (optional): Object with environment variables to pass to the server. Defaults to {}.\n    - `uid` (optional): User ID for the process. Defaults to the user of the process running InterTLS (which is probably not what you want!)\n    - `gid` (optional): Group ID for the process. Defaults to the group of the process running InterTLS (which is probably not what you want!)\n- `ipFallback`: TLS configuration (see `servers.tls` above) for those accessing the server that bypass SNI by connecting directly to its IP.\n\n## Handler options\n\n- `dynamicTLS`: If using Dynamic TLS, this should be a function that takes in a `host` as a string and returns a `Promise` with the [SecureContextOptions](https://nodejs.org/api/tls.html#tlscreatesecurecontextoptions) to use for it.\n- `autoListen`: Set to `false` to prevent the InterTLS handler from automatically listening for IPC messages from the parent. Useful if there is additional logic to be done after invoking the handler.\n- `override`: If needed, declaratively override the `localAddress` and `localPort` attributes of the `MockTcp` streams that are emitted to the server.\n\n## License\n\nThis project is [licensed under GPLv3](https://github.com/hieyou1/intertls/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhieyou1%2Fintertls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhieyou1%2Fintertls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhieyou1%2Fintertls/lists"}