koa-lusca

library2.2.0jsnpmunverified

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.

auth-security web-framework

npm install koa-lusca

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-LUSCA

koa-lusca

auth-securityjavascriptv2.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

lusca

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

✗ import lusca from 'koa-lusca';

This package is CJS-only and does not support ESM imports. Use require().

lusca.csrf

✓ app.use(lusca.csrf());

✗ app.use(lusca.csrf);

CSRF middleware is a function factory; calling it returns the middleware.

lusca.csp

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

✗ app.use(lusca.csp);

CSP options are required; calling without arguments will throw.

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

Debug

Known issues

breakingkoa-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.

affects: >=2.0.0

deprecatedP3P (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.

affects: >=1.0.0

gotchaCSRF 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.

affects: >=1.0.0

gotchaThe 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.

affects: >=1.0.0

deprecatedThis 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.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: app.use() requires a generator function

Using koa-lusca with Koa v2 which expects async middleware

fix

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

ReferenceError: require is not defined

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

fix

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

TypeError: lusca is not a function

Calling lusca without options or calling lusca() incorrectly

fix

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

Error: csrf token mismatch

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.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

tsscmprequiredUsed for constant-time string comparison in CSRF token validation

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/koajs/koa-lusca ↗

packagehttps://www.npmjs.com/package/koa-lusca ↗