All Projects → turboMaCk → Koa Sslify

turboMaCk / Koa Sslify

Licence: mit
Enforce HTTPS in node.js koa apps

Programming Languages

javascript
184084 projects - #8 most used programming language

Projects that are alternatives of or similar to Koa Sslify

Node Typescript Koa Rest
REST API boilerplate using NodeJS and KOA2, typescript. Logging and JWT as middlewares. TypeORM with class-validator, SQL CRUD. Docker included. Swagger docs, actions CI and valuable README
Stars: ✭ 739 (+639%)
Mutual labels:  heroku, koa, koa2
Wolfssl
wolfSSL (formerly CyaSSL) is a small, fast, portable implementation of TLS/SSL for embedded devices to the cloud. wolfSSL supports up to TLS 1.3!
Stars: ✭ 1,098 (+998%)
Mutual labels:  https, tls
Netcore Postgres Oauth Boiler
A basic .NET Core website boilerplate using PostgreSQL for storage, Adminer for db management, Let's Encrypt for SSL certificates and NGINX for routing.
Stars: ✭ 57 (-43%)
Mutual labels:  https, tls
Trafficlight
🚦 Flexible NodeJS Routing Decorators for API Routing
Stars: ✭ 69 (-31%)
Mutual labels:  koa, koa2
Greenlock
Automatic SSL renewal for NodeJS
Stars: ✭ 30 (-70%)
Mutual labels:  https, tls
Terraform Aws Alb
Terraform module to provision a standard ALB for HTTP/HTTP traffic
Stars: ✭ 53 (-47%)
Mutual labels:  https, tls
Koatty
Koa2 + Typescript = Koatty. Use Typescript's decorator implement IOC and AOP.
Stars: ✭ 67 (-33%)
Mutual labels:  koa, koa2
Shgf
Simple HTTP golang framework
Stars: ✭ 13 (-87%)
Mutual labels:  https, tls
Nodejs Koa Blog
基于 Node.js Koa2 实战开发的一套完整的博客项目网站
Stars: ✭ 1,162 (+1062%)
Mutual labels:  koa, koa2
Acme client
Java ACME Client application
Stars: ✭ 77 (-23%)
Mutual labels:  https, tls
Koach Javascript
Production ready Koa2 boilerplate.
Stars: ✭ 79 (-21%)
Mutual labels:  koa, koa2
Caddy
Matthew Holt began developing Caddy in 2014 while studying computer science at Brigham Young University. (The name "Caddy" was chosen because this software helps with the tedious, mundane tasks of serving the Web, and is also a single place for multiple things to be organized together.) It soon became the first web server to use HTTPS automatically and by default, and now has hundreds of contributors and has served trillions of HTTPS requests.
Stars: ✭ 35,966 (+35866%)
Mutual labels:  https, tls
Mkcert
A simple zero-config tool to make locally trusted development certificates with any names you'd like.
Stars: ✭ 33,022 (+32922%)
Mutual labels:  https, tls
Internet.nl
Internet standards compliance test suite
Stars: ✭ 56 (-44%)
Mutual labels:  https, tls
Koahub Demo
koahub+async/await+mysql
Stars: ✭ 15 (-85%)
Mutual labels:  koa, koa2
Vue Socket.io Chat
💬 TypeScript + Vue + Express/Koa + Socket.io
Stars: ✭ 61 (-39%)
Mutual labels:  koa, koa2
Koa Ts
koa2+typescript
Stars: ✭ 82 (-18%)
Mutual labels:  koa, koa2
Koa Generator
Koa' application generator for 1.x and 2.x( Express-style and support all middlewares include async/await )
Stars: ✭ 929 (+829%)
Mutual labels:  koa, koa2
Mysrv
Yet another Node.js web framework, based on koa.js 又一个 Node.js MVC 框架,基于Koa2
Stars: ✭ 10 (-90%)
Mutual labels:  koa, koa2
Merecat
Small and made-easy HTTP/HTTPS server based on Jef Poskanzer's thttpd
Stars: ✭ 69 (-31%)
Mutual labels:  https, tls

Koa SSLify

build code climate version

Enforce HTTPS middleware for Koa.js

Koa.js middleware to enforce HTTPS connection on any incoming requests. In case of a non-encrypted HTTP request, koa-sslify automatically redirects to an HTTPS address using a 301 permanent redirect (or optionally 307 Temporary Redirect).

Koa SSLify can also work behind reverse proxies (load balancers) like on Heroku, Azure, GCP Ingress etc and supports custom implementations of proxy resolvers.

Install

$ npm install --save koa-sslify

Usage

Importing default factory function:

const sslify = require('koa-sslify').default; // factory with default options
const Koa = require('koa');

app = new Koa();
app.use(sslify());

Default function accepts several options.

Name Type Default Description
resolver Function httpsResolver Function used to test if request is secure
hostname String undefined Hostname for redirect (uses request host if not set)
port Integer 443 Port of HTTPS server
ignoreUrl Boolean false Ignore url path (redirect to domain)
temporary Boolean false Temporary mode (use 307 Temporary Redirect)
skipDefaultPort Boolean true Avoid :443 port in redirect url
redirectMethods Array ['GET', 'HEAD'] Whitelist methods that should be redirected
disallowStatus Integer 405 Status returned for dissalowed methods

Resolvers

Resolver is a function from classic Koa ctx object to boolean. This function is used to determine if request is or is not secured (true means is secure). Middlware calls this function and based on its returned value either passes control to next middleware or responds to the request with appropriate redirect response.

There are several resolvers provided by this library but it should be very easy to implement any type of custom check as well.

for instance, Heroku has a reverse proxy that uses x-forwarded-proto header. This is how you can configure app with this resolver:

const {
  default: sslify, // middleware factory
  xForwardedProtoResolver: resolver // resolver needed
} = require('koa-sslify');
const Koa = require('koa');

app = new Koa();

// init middleware with resolver
app.use(sslify({ resolver }));

Those are all resolver provided by default:

Name Used by Example
httpsResolver Node.js server running with tls support sslify()
xForwardedProtoResolver Heroku, Google Ingress, Nodejitsu sslify({ resolver: xForwardedProtoResolver })
azureResolver Azure sslify({ resolver: azureResolver })
customProtoHeaderResolver any non-standard implementation (Kong) sslify({ resolver: customProtoHeader('x-protocol') })
forwardedResolver standard header sslify({ resolver: forwardedResolver })

Some additional information about reverse proxies:

Reverse Proxies (Heroku, Nodejitsu, GCE Ingress and others)

Heroku, nodejitsu, GCE Ingress and other hosters often use reverse proxies which offer SSL endpoints but then forward unencrypted HTTP traffic to the website. This makes it difficult to detect if the original request was indeed via HTTPS. Luckily, most reverse proxies set the x-forwarded-proto header flag with the original request scheme.

Azure

Azure has a slightly different way of signaling encrypted connections. It uses x-arr-ssl header as a flag to mark https traffic.

Defining Custom Resolver

If you're still in a situation where you need to use custom resolver you can implement it as for example following:

const { default: sslify } = require('koa-sslify');

app.use(sslify({
  resolver: (ctx) => ctx.request.header['x-is-secure'] === 'yup!'
}))

Contributions to increase coverage of default resolvers are welcomed.

Examples

Those are full example apps using Koa SSLify to enforce HTTPS.

Without Reverse Proxy

This example starts 2 servers for app.

  • First HTTP server is listening on port 8080 and redirects to second one
  • Second HTTPS server is listening on port 8081
const Koa = require('koa');
const http = require('http');
const https = require('https');
const fs = require('fs');
const { default: enforceHttps } = require('koa-sslify');

const app = new Koa();

// Force HTTPS using default resolver
app.use(enforceHttps({
  port: 8081
}));

// index page
app.use(ctx => {
  ctx.body = "hello world from " + ctx.request.url;
});

// SSL options
var options = {
  key: fs.readFileSync('server.key'),
  cert: fs.readFileSync('server.crt')
}

// start the server
http.createServer(app.callback()).listen(8080);
https.createServer(options, app.callback()).listen(8081);

With Reverse Proxy

This example starts a single http server which is designed to run behind a reverse proxy like Heroku.

const Koa = require('koa');
const {
  default: enforceHttps,
  xForwardedProtoResolver: resolver
} = require('koa-sslify');

var app = new Koa();

// Force HTTPS via x-forwarded-proto compatible resolver
app.use(enforceHttps({ resolver }));

// index page
app.use((ctx) => {
  ctx = "hello world from " + ctx.request.url;
});

// proxy will bind this port to it's 443 and 80 ports
app.listen(3000);

Advanced Redirect Setting

Redirect Methods

By default only GET and HEAD methods are whitelisted for redirect. koa-sslify will respond with 405 with appropriete Allow header by default. You can change whitelisted methods by passing redirectMethods array to options as well as change status for disallowed methods using disallowStatus.

Skip Default Port in Redirect URL

By default port is excluded from redirect url if it's set to 443. Since 443 is default port for HTTPS browser will use it by default anyway so there is no need to explicitly return it as part of URL. Anyway in case you need to always return port as part of URL string you can pass options with skipDefaultPort: false to do the trick.

License

MIT

Credits

This project is heavily inspired by Florian Heinemann's express-sslify and Vitaly Domnikov's koa-force-ssl.

Note that the project description data, including the texts, logos, images, and/or trademarks, for each open source project belongs to its rightful owner. If you wish to add or remove any projects, please contact us at [email protected].