@codecorn/empty-session-reaper

Features

Install

npm i @codecorn/empty-session-reaper

Import styles

// ✅ CommonJS (require)
const {
 wireEmptySessionReaper,
 predicates,
 buildAllowedKeys,
 wireSessionMutationLogger, // optional: logs added/removed keys
} = require("@codecorn/empty-session-reaper");
const { cookieFlash } = require("@codecorn/empty-session-reaper/presets");

// ✅ ESM / TypeScript
import {
 wireEmptySessionReaper,
 predicates as P,
 buildAllowedKeys,
 wireSessionMutationLogger, // optional
} from "@codecorn/empty-session-reaper";
import { cookieFlash } from "@codecorn/empty-session-reaper/presets";

Usage A — minimal "cookie + empty flash"

// Meaning of buildAllowedKeys(input, expandBase, base):
// - base: starting list (default: ['cookie'])
// - input: extra keys to allow (e.g., ['flash'])
// - expandBase:
// true => merge base + input (e.g., ['cookie'] + ['flash'] -> ['cookie','flash'])
// false => use input only (e.g., ['flash'])
wireEmptySessionReaper(app, {
 logger: (m, meta) => console.debug(m, meta),
 allowedKeys: buildAllowedKeys(["flash"], true, ["cookie"]),
 // ↑ allowlist = merge base ['cookie'] + ['flash'] → ['cookie','flash']
 maxKeys: 2,
 keyPredicates: {
 // flash is harmless if it's an empty object {}
 flash: P.emptyObject,
 },
});

Usage B — advanced custom policy (full control)

const isLoginFlash = (flash: any) => {
 if (!flash || typeof flash !== "object") return false;
 const ks = Object.keys(flash);
 if (ks.length !== 1) return false;
 const arr = Array.isArray((flash as any)[ks[0]]) ? (flash as any)[ks[0]] : [];
 return arr.length === 1 && /^pleasesignin\.?$/i.test(String(arr[0] || ""));
};
wireEmptySessionReaper(app, {
 logger: (m, meta) => console.debug(m, meta),
 allowedKeys: ["cookie", "flash", "url", "flag"],
 maxKeys: 4,
 disallowedKeyPatterns: [/^csrf/i, /^token/i, /^user/i],
 keyPredicates: {
 flash: (v) => P.emptyObject(v) || isLoginFlash(v),
 url: (v) => ["/", "/login", "/signin"].includes(String(v || "")),
 flag: P.oneOf([false, "auto"]),
 },
 isSessionPrunable: (s) => {
 const url = String((s as any).url || "");
 return !(/\.(env|git)\b/i.test(url) || /\/upload\/\./i.test(url));
 },
});

Usage C — optional preset cookieFlash

const preset = cookieFlash({
 // flashKey: 'flash',
 // flashField: 'error',
 // loginMessages: [/^please sign in\.?$/i, /^access denied$/i],
 // extraAllowedKeys: ['url'],
 // maxKeys: 3,
 // disallowedKeyPatterns: [/^csrf/i, /^token/i],
 // extraPredicates: { url: (v) => ['/', '/login'].includes(String(v || '')) },
 // finalCheck: (s) => !/\.env\b/i.test(String((s as any).url || '')),
});
wireEmptySessionReaper(app, { logger: console.debug, ...preset });

Bonus: Session mutation logger (discover origins)

// Place AFTER session(...) and BEFORE the reaper:
wireSessionMutationLogger(app, {
 logger: (label, meta) => console.debug(label, meta),
 includeValues: false, // true to also log shallow values (use redact to mask)
 redact: (k, v) => (/(token|secret|pass)/i.test(k) ? "[redacted]" : v),
 label: "session mutation",
});

API (core)

createEmptySessionReaper(opts) -> (req, res, next) => void
 Create the middleware with your pruning policy.
wireEmptySessionReaper(app, opts) -> middleware
 Mounts the middleware on the app and returns it.
buildAllowedKeys(input?: string[], expandBase?: boolean, base?: string[]) -> string[]
 Helper to compose allowlists.
 - base: starting list (default: ["cookie"])
 - input: extra allowed keys (e.g., ["flash"])
 - expandBase:
 true -> merge base + input
 false -> use input only
predicates:
 - emptyObject(v)
 - equals(x)
 - oneOf([a,b,c])
 - and(p1,p2,...)
 - or(p1,p2,...)
 - flashEmptyOrOneOf(field='error', messages=[/^please sign in\.?$/i])
createSessionMutationLogger(opts) -> middleware
wireSessionMutationLogger(app, opts) -> middleware
lookUpSessMutation(app, opts) -> alias of wireSessionMutationLogger

📝 License

Credits

👤 Maintainer

🤝 Contribute