Registry / web-framework / koa-encrypted-session

koa-encrypted-session

library3.0.7jsnpmunverified

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.

web-framework auth-security serialization

npm install koa-encrypted-session

github ↗package ↗

INSTALL

IMPORT

SIG · KOA-ENCRYPTED-SESS

koa-encrypted-session

web-frameworkjavascriptv3.0.7

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.

default

✓ import encryptedSession from 'koa-encrypted-session'

✗ const encryptedSession = require('koa-encrypted-session')

ESM-only since v3; CommonJS require is not supported.

encryptedSession

✓ import { encryptedSession } from 'koa-encrypted-session'

✗ import encryptedSession from 'koa-encrypted-session'

Named export also available but less common; both work as it is a default export also exported as named.

encryptedSession (as middleware)

✓ app.use(encryptedSession({ /* options */ }, app))

✗ app.use(encryptedSession({ /* options */ }))

koa-session requires passing the app as second argument; this is inherited behavior.

Sets up encrypted cookie sessions with a secret key from environment variable and tracks view count per session.

import Koa from 'koa'; import encryptedSession from 'koa-encrypted-session'; const app = new Koa(); app.use(encryptedSession({ key: 'session', maxAge: 7 * 24 * 3600 * 1000, secretKey: Buffer.from(process.env.SESSION_SECRET_KEY ?? 'EsAg64LMvGITBBz1ZGLfDNU/MYqGDpTzJ1u4BsvIfTw=', 'base64') }, app)); app.use(ctx => { ctx.session.count = (ctx.session.count ?? 0) + 1; ctx.body = `views: ${ctx.session.count}`; }); app.listen(3000);

Debug

Known issues

breakingv3 dropped CommonJS support; ESM-only.

fix

Convert to ESM or use dynamic import() if in a CommonJS project.

affects: >=3.0.0

breakingv3 requires Node.js >=16.

fix

Upgrade Node.js to v16 or later.

affects: >=3.0.0

gotchasecretKey must be a Buffer of 32 bytes (e.g., from crypto.randomBytes(32)). Using passphrase+salt is slower and less secure.

fix

Generate a key using the provided CLI tool: koa-encrypted-session-gen-key

affects: *

gotchaInherited from koa-session: must pass app as second argument to middleware.

fix

Always call middleware with (options, app).

affects: *

gotchaSession data is limited by cookie size (max 4KB). Large session data may cause cookie overflow.

fix

Store only minimal data in session; use external store for larger payloads.

affects: *

Errors

Common errors & fixes

Error: secretKey must be a Buffer

Passing a string or non-Buffer value for secretKey option.

fix

Use Buffer.from(key, 'base64') for base64-encoded keys or Buffer.from(key, 'hex') for hex keys.

TypeError: Cannot read properties of undefined (reading 'session')

Middleware not applied or app not passed as second argument.

fix

Ensure app.use(encryptedSession(options, app)) is called with app as second argument.

ERR_REQUIRE_ESM: require() of ES Module not supported

Using CommonJS require() with ESM-only package.

fix

Use import instead, or use dynamic import().

Upgrade

Version history

3.0.7latest on npm

Audit

Dependencies

koa-sessionrequiredInherits from koa-session; all koa-session options are available.

sodium-nativerequiredProvides libsodium encryption primitives used for cookie encryption.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nicokaiser/koa-encrypted-session ↗

packagehttps://www.npmjs.com/package/koa-encrypted-session ↗