{"id":18470,"library":"koa-encrypted-session","title":"koa-encrypted-session","description":"Encrypted cookie-based session middleware for Koa, built on top of koa-session. Current stable version is 3.0.7, targeting Node.js >=16. It uses libsodium's Secret key box for encryption, providing a scalable, stateless alternative to server-side session stores. Unlike other Koa session middlewares, it eliminates the need for a database or external cache. Key differentiator: client-side encryption using sodium-native, with support for both a high-entropy secretKey or a passphrase+salt combination. Release cadence: maintenance mode with occasional dependency updates.","status":"active","version":"3.0.7","language":"javascript","source_language":"en","source_url":"git://github.com/nicokaiser/koa-encrypted-session","tags":["javascript","koa","middleware","session","cookie","encrypted"],"install":[{"cmd":"npm install koa-encrypted-session","lang":"bash","label":"npm"},{"cmd":"yarn add koa-encrypted-session","lang":"bash","label":"yarn"},{"cmd":"pnpm add koa-encrypted-session","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Inherits from koa-session; all koa-session options are available.","package":"koa-session","optional":false},{"reason":"Provides libsodium encryption primitives used for cookie encryption.","package":"sodium-native","optional":false}],"imports":[{"note":"ESM-only since v3; CommonJS require is not supported.","wrong":"const encryptedSession = require('koa-encrypted-session')","symbol":"default","correct":"import encryptedSession from 'koa-encrypted-session'"},{"note":"Named export also available but less common; both work as it is a default export also exported as named.","wrong":"import encryptedSession from 'koa-encrypted-session'","symbol":"encryptedSession","correct":"import { encryptedSession } from 'koa-encrypted-session'"},{"note":"koa-session requires passing the app as second argument; this is inherited behavior.","wrong":"app.use(encryptedSession({ /* options */ }))","symbol":"encryptedSession (as middleware)","correct":"app.use(encryptedSession({ /* options */ }, app))"}],"quickstart":{"code":"import Koa from 'koa';\nimport encryptedSession from 'koa-encrypted-session';\n\nconst app = new Koa();\n\napp.use(encryptedSession({\n  key: 'session',\n  maxAge: 7 * 24 * 3600 * 1000,\n  secretKey: Buffer.from(process.env.SESSION_SECRET_KEY ?? 'EsAg64LMvGITBBz1ZGLfDNU/MYqGDpTzJ1u4BsvIfTw=', 'base64')\n}, app));\n\napp.use(ctx => {\n  ctx.session.count = (ctx.session.count ?? 0) + 1;\n  ctx.body = `views: ${ctx.session.count}`;\n});\n\napp.listen(3000);","lang":"javascript","description":"Sets up encrypted cookie sessions with a secret key from environment variable and tracks view count per session."},"warnings":[{"fix":"Convert to ESM or use dynamic import() if in a CommonJS project.","message":"v3 dropped CommonJS support; ESM-only.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Upgrade Node.js to v16 or later.","message":"v3 requires Node.js >=16.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Generate a key using the provided CLI tool: koa-encrypted-session-gen-key","message":"secretKey must be a Buffer of 32 bytes (e.g., from crypto.randomBytes(32)). Using passphrase+salt is slower and less secure.","severity":"gotcha","affected_versions":"*"},{"fix":"Always call middleware with (options, app).","message":"Inherited from koa-session: must pass app as second argument to middleware.","severity":"gotcha","affected_versions":"*"},{"fix":"Store only minimal data in session; use external store for larger payloads.","message":"Session data is limited by cookie size (max 4KB). Large session data may cause cookie overflow.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use Buffer.from(key, 'base64') for base64-encoded keys or Buffer.from(key, 'hex') for hex keys.","cause":"Passing a string or non-Buffer value for secretKey option.","error":"Error: secretKey must be a Buffer"},{"fix":"Ensure app.use(encryptedSession(options, app)) is called with app as second argument.","cause":"Middleware not applied or app not passed as second argument.","error":"TypeError: Cannot read properties of undefined (reading 'session')"},{"fix":"Use import instead, or use dynamic import().","cause":"Using CommonJS require() with ESM-only package.","error":"ERR_REQUIRE_ESM: require() of ES Module not supported"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}