{"id":18472,"library":"koa-lusca","title":"koa-lusca","description":"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.","status":"maintenance","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/koajs/koa-lusca","tags":["javascript"],"install":[{"cmd":"npm install koa-lusca","lang":"bash","label":"npm"},{"cmd":"yarn add koa-lusca","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-lusca","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used for constant-time string comparison in CSRF token validation","package":"tsscmp","optional":false}],"imports":[{"note":"This package is CJS-only and does not support ESM imports. Use require().","wrong":"import lusca from 'koa-lusca';","symbol":"lusca","correct":"const lusca = require('koa-lusca');"},{"note":"CSRF middleware is a function factory; calling it returns the middleware.","wrong":"app.use(lusca.csrf);","symbol":"lusca.csrf","correct":"app.use(lusca.csrf());"},{"note":"CSP options are required; calling without arguments will throw.","wrong":"app.use(lusca.csp);","symbol":"lusca.csp","correct":"const lusca = require('koa-lusca'); app.use(lusca.csp({ policy: { 'default-src': \"'self'\" } }));"}],"quickstart":{"code":"const koa = require('koa');\nconst lusca = require('koa-lusca');\nconst app = koa();\n\napp.use(lusca({\n  csrf: true,\n  xframe: 'SAMEORIGIN',\n  hsts: { maxAge: 31536000, includeSubDomains: true },\n  xssProtection: true\n}));\n\napp.use(function*() {\n  this.body = 'Hello, secure world!';\n});\n\napp.listen(3000, () => console.log('Server running on port 3000'));","lang":"javascript","description":"Set up Koa v1 app with CSRF, X-Frame-Options, HSTS, and XSS protection using koa-lusca."},"warnings":[{"fix":"Use koa-helmet or another Koa v2 compatible security library.","message":"koa-lusca only supports Koa v1 (generator-based middleware). Using it with Koa v2 will cause application errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Remove p3p configuration from lusca options.","message":"P3P (Platform for Privacy Preferences) header is obsolete and no longer supported by modern browsers. Its use is strongly discouraged.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Add koa-session or similar session middleware before lusca csrf.","message":"CSRF middleware requires sessions to work properly. If no session middleware is set up, CSRF will fail silently.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Check the documentation for exact option names and values.","message":"The lusca() function with options object does not apply all security headers if unknown or misspelled options are passed. Invalid options are silently ignored.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Switch to koa-helmet or a Koa v2 compatible package.","message":"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.","severity":"deprecated","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use Koa v1 or migrate to koa-helmet for Koa v2.","cause":"Using koa-lusca with Koa v2 which expects async middleware","error":"TypeError: app.use() requires a generator function"},{"fix":"Use const lusca = require('koa-lusca'); instead of import.","cause":"Using ESM imports (import) instead of CommonJS require()","error":"ReferenceError: require is not defined"},{"fix":"Use lusca({...}) with an options object or call individual methods like lusca.csrf().","cause":"Calling lusca without options or calling lusca() incorrectly","error":"TypeError: lusca is not a function"},{"fix":"Ensure session middleware is used and include _csrf field in form data or header.","cause":"CSRF token not included in POST request or session not set up","error":"Error: csrf token mismatch"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}