Home

Awesome

Note: This library has known security vulnerabilities, use at your own risk!

Express with Secure Handlebars

npm version dependency status Build Status

We enhance the express-handlebars server-side view engine by leveraging the secure-handlebars for defending against Cross-Site Scripting (XSS). Hence, web applications can be automatically secured by contextual output escaping.

For more details, kindly refer to the introductions to secure-handlebars and xss-filters.

Quick Start

Installation

npm install express-secure-handlebars --save

Usage

Simply replace express-handlebars with the express-secure-handlebars package in all require()!

Basic Example

Based on the basic example of ExpressHandlebars, here we show an example app that can be secured only with our package.

views/profile.handlebars:

Given that there is a very typical handlebars template file written like so to incorporate user inputs. The enhanced package can secure the web application by automatically applying context-sensitive output filters, which otherwise is still subject to XSS attacks if using the default escaping approach (e.g., when url is javascript:alert(1) or onclick=alert(1)).

<h1>Example App: {{title}}</h1>
...
<div>User-provided URL: <a href="{{url}}">{{url}}</a></div>
...

views/layouts/main.handlebars:

Same as the Handlebars original example, this file serves as the HTML page wrapper which can be reused for the different views of the app. {{{body}}} is used as a placeholder for where the main content should be rendered.

<!DOCTYPE html>
<html>
<head><meta charset="utf-8"><title>{{title}}</title></head>
<body>
    {{{body}}}
</body>
</html>

app.js:

A super simple Express app that registers the Handlebars view engine.

var express = require('express'),
//  The only difference is to replace 'express-handlebars' with our enhanced package.
//  exphbs  = require('express-handlebars');
    exphbs  = require('express-secure-handlebars');

var app = express(),
    hbs = exphbs.create({ /* config */ });

app.engine('handlebars', hbs.engine);
app.set('view engine', 'handlebars');

app.use('/profile', function (req, res) {
    res.render('profile', {
        title:  'User Profile',
        url:    req.query.url    // an untrusted user input
    });
});

app.listen(3000);

Development

Known Limitations & Issues

Please refer to the section documented in secure-handlebars.

Warnings and Workarounds

Please refer to the section documented in secure-handlebars.

How to test

Apply your changes to files in src/, and then run the tests.

npm test

License

This software is free to use under the Yahoo Inc. BSD license. See the LICENSE file for license text and copyright information.