{"id":14989553,"url":"https://github.com/turbomack/koa-sslify","last_synced_at":"2025-05-15T08:03:43.530Z","repository":{"id":2159651,"uuid":"44118862","full_name":"turboMaCk/koa-sslify","owner":"turboMaCk","description":"Enforce HTTPS in node.js koa apps","archived":false,"fork":false,"pushed_at":"2025-02-19T12:50:01.000Z","size":327,"stargazers_count":126,"open_issues_count":0,"forks_count":12,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-07T02:19:26.286Z","etag":null,"topics":["heroku","https","koa","koa2","node","tls"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/turboMaCk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2015-10-12T16:09:46.000Z","updated_at":"2025-02-20T17:02:54.000Z","dependencies_parsed_at":"2024-01-13T17:58:16.832Z","dependency_job_id":"963bc75a-a891-4107-8df8-8944f413175a","html_url":"https://github.com/turboMaCk/koa-sslify","commit_stats":{"total_commits":112,"total_committers":11,"mean_commits":"10.181818181818182","dds":0.2142857142857143,"last_synced_commit":"9499f0bdd60df236e5ff7acca06e88a027276f5f"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turboMaCk%2Fkoa-sslify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turboMaCk%2Fkoa-sslify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turboMaCk%2Fkoa-sslify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/turboMaCk%2Fkoa-sslify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/turboMaCk","download_url":"https://codeload.github.com/turboMaCk/koa-sslify/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248869089,"owners_count":21174817,"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":["heroku","https","koa","koa2","node","tls"],"created_at":"2024-09-24T14:18:33.390Z","updated_at":"2025-04-14T11:22:22.529Z","avatar_url":"https://github.com/turboMaCk.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n    \u003ch1\u003eKoa SSLify\u003c/h1\u003e\n    \u003ca href=\"https://github.com/turboMaCk/koa-sslify/actions/workflows/test.yml\"\u003e\n      \u003cimg src=\"https://github.com/github/docs/actions/workflows/main.yml/badge.svg?branch=master\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://codeclimate.com/github/turboMaCk/koa-sslify\"\u003e\n      \u003cimg src=\"https://codeclimate.com/github/turboMaCk/koa-sslify/badges/gpa.svg\" alt=\"code climate\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://badge.fury.io/js/koa-sslify\"\u003e\n      \u003cimg src=\"https://badge.fury.io/js/koa-sslify.svg\" alt=\"version\"\u003e\n    \u003c/a\u003e\n    \u003cp\u003eEnforce HTTPS middleware for Koa.js\u003c/p\u003e\n\u003c/div\u003e\n\n[Koa.js](http://koajs.com/) middleware to enforce HTTPS connection on any incoming requests.\nIn case of a non-encrypted HTTP request, koa-sslify automatically redirects to an HTTPS address using a `301 permanent redirect`\n(or optionally `307 Temporary Redirect`).\n\nKoa SSLify can also work behind reverse proxies (load balancers) like on Heroku, Azure, GCP Ingress etc\nand supports custom implementations of proxy resolvers.\n\n## Install\n\n```\n$ npm install --save koa-sslify\n```\n\n## Usage\n\nImporting default factory function:\n\n```javascript\nconst sslify = require('koa-sslify').default; // factory with default options\nconst Koa = require('koa');\n\napp = new Koa();\napp.use(sslify());\n```\n\nDefault function accepts several options.\n\n| Name                      | Type          | Default           | Description                                          |\n|---------------------------|---------------|-------------------|------------------------------------------------------|\n| `resolver`                | Function      | `httpsResolver`   | Function used to test if request is secure           |\n| `hostname`                | Function      | `undefined`       | Function that takes the request hostname string as its only argument and returns the desired hostname to use as a result. Uses request hostname if not set or return value is falsy |\n| `port`                    | Integer       | `443`             | Port of HTTPS server                                 |\n| `ignoreUrl`               | Boolean       | `false`           | Ignore url path (redirect to domain)                 |\n| `temporary`               | Boolean       | `false`           | Temporary mode (use 307 Temporary Redirect)          |\n| `skipDefaultPort`         | Boolean       | `true`            | Avoid `:443` port in redirect url                    |\n| `redirectMethods`         | Array\u003cString\u003e | `['GET', 'HEAD']` | Whitelist methods that should be redirected          |\n| `disallowStatus`          | Integer       | `405`             | Status returned for disallowed methods               |\n\n### Resolvers\n\nResolver is a function from classic Koa `ctx` object to boolean.\nThis function is used to determine if request is or is not secured (true means is secure).\nMiddleware calls this function and based on its returned value either passes\ncontrol to next middleware or responds to the request with appropriate redirect response.\n\nThere are several resolvers provided by this library but it should be very easy to implement\nany type of custom check as well.\n\nfor instance, Heroku has a reverse proxy that uses `x-forwarded-proto` header.\nThis is how you can configure app with this resolver:\n\n```js\nconst {\n  default: sslify, // middleware factory\n  xForwardedProtoResolver: resolver // resolver needed\n} = require('koa-sslify');\nconst Koa = require('koa');\n\napp = new Koa();\n\n// init middleware with resolver\napp.use(sslify({ resolver }));\n```\n\nThose are all resolver provided by default:\n\n| Name                        | Used by                                                                                | Example                                                 |\n|-----------------------------|----------------------------------------------------------------------------------------|---------------------------------------------------------|\n| `httpsResolver`             | Node.js server running with TLS support                                                | `sslify()`                                              |\n| `xForwardedProtoResolver`   | Heroku, Google Ingress                                                                 | `sslify({ resolver: xForwardedProtoResolver })`         |\n| `azureResolver`             | Azure                                                                                  | `sslify({ resolver: azureResolver })`                   |\n| `customProtoHeaderResolver` | any non-standard implementation (Kong)                                                 | `sslify({ resolver: customProtoHeader('x-protocol') })` |\n| `forwardedResolver`         | [standard header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) | `sslify({ resolver: forwardedResolver })`               |\n\nSome additional information about reverse proxies:\n\n#### Reverse Proxies (Heroku, GCE Ingress and others)\n\nHeroku, GCE Ingress and other hosters often use reverse proxies which offer SSL endpoints\nbut then forward unencrypted HTTP traffic to the website.\nThis makes it difficult to detect if the original request was indeed via HTTPS. Luckily,\nmost reverse proxies set the `x-forwarded-proto` header flag with the original request scheme.\n\n#### Azure\n\nAzure has a slightly different way of signaling encrypted connections.\nIt uses `x-arr-ssl` header as a flag to mark https traffic.\n\n### Defining Custom Resolver\n\nIf you're still in a situation where you need to use custom resolver you can implement it as for example following:\n\n```javascript\nconst { default: sslify } = require('koa-sslify');\n\napp.use(sslify({\n  resolver: (ctx) =\u003e ctx.request.header['x-is-secure'] === 'yup!'\n}))\n```\n\nContributions to increase coverage of default resolvers are welcomed.\n\n## Examples\n\nThose are full example apps using Koa SSLify to enforce HTTPS.\n\n### Without Reverse Proxy\n\nThis example starts 2 servers for app.\n\n- First HTTP server is listening on port 8080 and redirects to second one\n- Second HTTPS server is listening on port 8081\n\n```javascript\nconst Koa = require('koa');\nconst http = require('http');\nconst https = require('https');\nconst fs = require('fs');\nconst { default: enforceHttps } = require('koa-sslify');\n\nconst app = new Koa();\n\n// Force HTTPS using default resolver\napp.use(enforceHttps({\n  port: 8081\n}));\n\n// index page\napp.use(ctx =\u003e {\n  ctx.body = \"hello world from \" + ctx.request.url;\n});\n\n// SSL options\nvar options = {\n  key: fs.readFileSync('server.key'),\n  cert: fs.readFileSync('server.crt')\n}\n\n// start the server\nhttp.createServer(app.callback()).listen(8080);\nhttps.createServer(options, app.callback()).listen(8081);\n```\n\n### With Reverse Proxy\n\nThis example starts a single http server which is designed to run behind\na reverse proxy like Heroku.\n\n```javascript\nconst Koa = require('koa');\nconst {\n  default: enforceHttps,\n  xForwardedProtoResolver: resolver\n} = require('koa-sslify');\n\nvar app = new Koa();\n\n// Force HTTPS via x-forwarded-proto compatible resolver\napp.use(enforceHttps({ resolver }));\n\n// index page\napp.use((ctx) =\u003e {\n  ctx = \"hello world from \" + ctx.request.url;\n});\n\n// proxy will bind this port to it's 443 and 80 ports\napp.listen(3000);\n```\n\n## Advanced Redirect Setting\n\n### Redirect Methods\n\nBy default only `GET` and `HEAD` methods are whitelisted for redirect.\nkoa-sslify will respond with `405` with appropriate `Allow` header by default.\nYou can change whitelisted methods by passing `redirectMethods` array to options\nas well as change status for disallowed methods using `disallowStatus`.\n\n### Skip Default Port in Redirect URL\n\n**By default port is excluded from redirect url if it's set to `443`.**\nSince `443` is default port for `HTTPS` browser will use it by default anyway so there\nis no need to explicitly return it as part of URL. Anyway in case you need to **always return port as part of URL string**\nyou can pass options with `skipDefaultPort: false` to do the trick.\n\n## License\n\nMIT\n\n## Credits\n\nThis project is heavily inspired by [Florian Heinemann's](https://github.com/florianheinemann) [express-sslify](https://github.com/florianheinemann/express-sslify)\nand [Vitaly Domnikov's](https://github.com/dotcypress) [koa-force-ssl](https://github.com/dotcypress/koa-force-ssl).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturbomack%2Fkoa-sslify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fturbomack%2Fkoa-sslify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fturbomack%2Fkoa-sslify/lists"}