tiny-cookie-session is a robust cookie-based session management library specifically designed for Bun applications. It provides a mechanism to help detect cookie theft, enhancing the security of user sessions. This library operates similarly to Device Bound Session Credentials (DBSC) but without the need for specialized hardware, making it more accessible.

Overview of Session Management Approaches

This library introduces a novel approach to manage sessions effectively compared to traditional methods:

Long-lived Session ID

• Involves generating a long-lived session ID stored in a cookie. If compromised, the session can be exploited until it expires or the user logs out.

Simple Token Rotation

• Utilizes a short-lived token that is frequently rotated. This method exposes users to risks if an attacker manipulates token rotations.

tiny-cookie-session

• Each session employs a short-lived token with periodic rotations. All previous tokens are retained, allowing detection of unauthorized use. If a token is stolen, it can only be utilized until the user next accesses the session, at which point both user and attacker will be logged out.

Simple Configuration and Usage

The library requires configuration of a storage adapter, which must implement core functions such as selectSession, insertSession, updateSession, and deleteSession. Below is an example of configuring a session using Bun's SQLite:

import { Database } from "bun:sqlite";
import { login, logout, consumeSession } from "tiny-cookie-session";

const db = new Database("sessions.db");
// Initialize database and tables here

const sessionConfig = {
  sessionExpiresIn: 5 * 60 * 60 * 1000, // 5 hours
  tokenExpiresIn: 10 * 60 * 1000, // 10 minutes

  selectSession: async ({ tokenHash }) => {
    // Implementation to select session goes here
  },
  insertSession: async ({ id, exp, tokenHash, tokenExp, data }) => {
    // Implementation to insert session goes here
  },
  updateSession: async ({ id, exp, tokenHash, tokenExp }) => {
    // Implementation to update session goes here
  },
  deleteSession: async ({ tokenHash }) => {
    // Implementation to delete session goes here
  }
};

Features and Usage

• Cookie Theft Detection: If a non-latest token is detected in a request, the entire session is invalidated, mitigating the risk of unauthorized access.
• Token Management: The library allows managing multiple token states effectively, ensuring concurrent logins do not inadvertently log users out.
• Session and Token Expiration: Provides configurations to define session and token lifetimes, balancing security and user experience.
• Garbage Collection: Users can implement methods to remove expired sessions from the storage to prevent unnecessary data retention.

Here's a brief usage example for logging in and managing user sessions:

serve({
  port: 3000,
  async fetch(request) {
    const url = new URL(request.url);
    if (url.pathname === "/login") {
      // Logic for logging in a user
    }
    if (url.pathname === "/logout") {
      // Logic for logging out a user
    }
    // Further endpoint logic...
  }
});

For detailed configurations and additional usage examples, refer to the official repository documentation.

Limitations and Security Considerations

While tiny-cookie-session introduces advanced cookie theft detection techniques, it does not eliminate all security risks, particularly when dealing with persistent background malware or continuous cookie theft. Therefore, implementing comprehensive security measures, including CSRF protection, is essential when leveraging this library.

In summary, tiny-cookie-session stands out for its user-friendly isolation of session management complexities while providing enhanced security features against cookie theft.