@papack/session

Minimal session handling for node:http.
Async-first, in-memory, zero dependencies.

Designed for small–medium services and internal tools where explicit control and predictable behavior matter more than abstraction.

Features

• Secure cookie-based sessions
• 2-token model (public cookie token + internal UUID)
• Cryptographically secure IDs
• Sliding expiration
• Manual logout and admin destruction
• Predicate-based admin lookup

Installation

bun add @papack/session
# or
npm install @papack/session

Usage

import http from "node:http";
import { Session } from "@papack/session";

type MySession = {
  userId?: string;
};

const session = new Session<MySession>({
  initialData: {},
  expiryMinutes: 30,
  secureCookie: false, // true in production
});

http
  .createServer(async (req, res) => {
    const data = await session.get(req, res);

    if (req.url === "/login") {
      await session.set(req, res, () => ({ userId: "42" }));
      res.end("ok");
      return;
    }

    if (req.url === "/logout") {
      await session.logout(req, res);
      res.end("bye");
      return;
    }

    res.end(JSON.stringify(data));
  })
  .listen(3000);

Security Model

• Cookie contains a public token only
• Internal session UUID never leaves the server
• Unknown or invalid cookies result in a new session

Admin API

await session.getSessionCount();
await session.findSessions((data) => data.userId === "42");
await session.destroy(uuid);

Cookies

• HttpOnly
• SameSite=Strict
• Secure configurable
• Fixed name: ssid

Expiration

• Sliding expiration on access
• Configurable in minutes
• Background cleanup interval