@engjts/mysql-adapter

A MySQL session store adapter for @engjts/auth (JTS - Janus Token System).

Installation

npm install @engjts/mysql-adapter mysql2

Usage

import mysql from 'mysql2/promise';
import { JTSAuthServer } from '@engjts/auth';
import { MySQLSessionStore } from '@engjts/mysql-adapter';

// Create a MySQL pool
const pool = mysql.createPool({
  host: 'localhost',
  port: 3306,
  user: 'root',
  password: 'password',
  database: 'myapp',
});

// Create a session store
const sessionStore = new MySQLSessionStore({ pool });

// Initialize the table (run once)
await sessionStore.initialize();

// Use with JTSAuthServer
const authServer = new JTSAuthServer({
  profile: 'JTS-S/v1',
  signingKey: mySigningKey,
  sessionStore,
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | pool | MySQLPool | required | A mysql2/promise pool instance | | tableName | string | 'jts_sessions' | The table name for sessions | | database | string | undefined | The database name (optional) | | rotationGraceWindow | number | 10 | The grace window in seconds | | defaultSessionLifetime | number | 604800 | The session lifetime (7 days) |

API

MySQLSessionStore

initialize(): Promise<void>

Creates the sessions table if it doesn't exist.

createSession(input: CreateSessionInput): Promise<JTSSession>

Creates a new session.

getSessionByAid(aid: string): Promise<JTSSession | null>

Retrieves a session by its AID (Authentication ID).

getSessionByStateProof(stateProof: string): Promise<SessionValidationResult>

Validates a state proof and returns the associated session.

rotateStateProof(aid: string, newStateProof?: string): Promise<JTSSession>

Rotates the state proof for a session.

touchSession(aid: string): Promise<void>

Updates the last active timestamp for a session.

deleteSession(aid: string): Promise<boolean>

Deletes a session by its AID.

deleteAllSessionsForPrincipal(prn: string): Promise<number>

Deletes all sessions for a principal (user).

getSessionsForPrincipal(prn: string): Promise<JTSSession[]>

Gets all active sessions for a principal.

countSessionsForPrincipal(prn: string): Promise<number>

Counts active sessions for a principal.

deleteOldestSessionForPrincipal(prn: string): Promise<boolean>

Deletes the oldest session for a principal (useful for session limits).

cleanupExpiredSessions(): Promise<number>

Removes expired sessions from the database.

healthCheck(): Promise<boolean>

Checks if the database connection is healthy.

close(): Promise<void>

Closes the database connection pool.

Database Schema

The adapter automatically creates the following table structure:

CREATE TABLE jts_sessions (
  aid VARCHAR(64) PRIMARY KEY,
  prn VARCHAR(256) NOT NULL,
  current_state_proof VARCHAR(256) NOT NULL,
  previous_state_proof VARCHAR(256),
  state_proof_version INT DEFAULT 1,
  rotation_timestamp DATETIME(3),
  device_fingerprint VARCHAR(128),
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  expires_at DATETIME(3) NOT NULL,
  last_active DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
  user_agent TEXT,
  ip_address VARCHAR(45),
  metadata JSON,
  
  INDEX idx_prn (prn),
  INDEX idx_current_sp (current_state_proof),
  INDEX idx_previous_sp (previous_state_proof),
  INDEX idx_expires (expires_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci

Requirements

• Node.js >= 18.0.0
• MySQL >= 5.7 or MariaDB >= 10.2
• @engjts/auth >= 1.0.0
• mysql2 >= 3.0.0

Testing

# Set up environment variables
export MYSQL_HOST=localhost
export MYSQL_PORT=3306
export MYSQL_USER=root
export MYSQL_PASSWORD=password
export MYSQL_DATABASE=jts_test

# Run tests
npm test

License

MIT