koa-lusca

2.2.0 verified Sat Apr 25 auth: no javascript maintenance

Web application security middleware for koa, forked from krakenjs/lusca. Version 2.2.0 provides CSRF protection, Content Security Policy (CSP), X-Frame-Options (clickjacking), P3P privacy headers, HSTS, and XSS protection. This package is actively maintained but does not support Koa v2 (async/await) or modern ESM. Release cadence is low; last update was 2019. Key differentiator: it brings lusca-style security to Koa v1, but developers should consider alternatives like 'koa-helmet' for Koa v2.

Common errors

error TypeError: app.use() requires a generator function ↓

cause Using koa-lusca with Koa v2 which expects async middleware

fix

Use Koa v1 or migrate to koa-helmet for Koa v2.

error ReferenceError: require is not defined ↓

cause Using ESM imports (import) instead of CommonJS require()

fix

Use const lusca = require('koa-lusca'); instead of import.

error TypeError: lusca is not a function ↓

cause Calling lusca without options or calling lusca() incorrectly

fix

Use lusca({...}) with an options object or call individual methods like lusca.csrf().

error Error: csrf token mismatch ↓

cause CSRF token not included in POST request or session not set up

fix

Ensure session middleware is used and include _csrf field in form data or header.

Warnings

breaking koa-lusca only supports Koa v1 (generator-based middleware). Using it with Koa v2 will cause application errors. ↓

fix Use koa-helmet or another Koa v2 compatible security library.

deprecated P3P (Platform for Privacy Preferences) header is obsolete and no longer supported by modern browsers. Its use is strongly discouraged. ↓

fix Remove p3p configuration from lusca options.

gotcha CSRF middleware requires sessions to work properly. If no session middleware is set up, CSRF will fail silently. ↓

fix Add koa-session or similar session middleware before lusca csrf.

gotcha The lusca() function with options object does not apply all security headers if unknown or misspelled options are passed. Invalid options are silently ignored. ↓

fix Check the documentation for exact option names and values.

deprecated This package uses generator functions (function*) which are deprecated in Node.js and removed in newer versions. It may cause runtime errors in Node >= 16. ↓

fix Switch to koa-helmet or a Koa v2 compatible package.

Install

npm install koa-lusca

yarn add koa-lusca

pnpm add koa-lusca

Imports

lusca
wrong
```
import lusca from 'koa-lusca';
```
correct
```
const lusca = require('koa-lusca');
```
This package is CJS-only and does not support ESM imports. Use require().
lusca.csrf
wrong
```
app.use(lusca.csrf);
```
correct
```
app.use(lusca.csrf());
```
CSRF middleware is a function factory; calling it returns the middleware.

lusca.csp

wrong

app.use(lusca.csp);

correct

const lusca = require('koa-lusca'); app.use(lusca.csp({ policy: { 'default-src': "'self'" } }));

CSP options are required; calling without arguments will throw.

Quickstart

Set up Koa v1 app with CSRF, X-Frame-Options, HSTS, and XSS protection using koa-lusca.

const koa = require('koa');
const lusca = require('koa-lusca');
const app = koa();

app.use(lusca({
  csrf: true,
  xframe: 'SAMEORIGIN',
  hsts: { maxAge: 31536000, includeSubDomains: true },
  xssProtection: true
}));

app.use(function*() {
  this.body = 'Hello, secure world!';
});

app.listen(3000, () => console.log('Server running on port 3000'));