ryauth 1.0.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "ryauth",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest"
+  },
+  "keywords": ["authentication", "auth", "jwt", "security", "nodejs", "middleware", "argon2", "rbac"],
+  "author": "Ryan Pereira <ryanpereira499@gmail.com>",
+  "license": "MIT",
+  "description": "A modern, secure, and database-agnostic authentication library for Node.js with JWT tokens, Argon2 password hashing, and role-based access control.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ryanpereira49/RyAuth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ryanpereira49/RyAuth/issues"
+  },
+  "homepage": "https://github.com/ryanpereira49/RyAuth#readme",
+  "dependencies": {
+    "argon2": "^0.44.0",
+    "cookie": "^1.1.1",
+    "dotenv": "^17.2.3",
+    "jose": "^6.1.3",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.2.0",
+    "cross-env": "^10.1.0",
+    "jest": "^30.2.0",
+    "supertest": "^7.1.4"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/adapters/base.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+
+/**
+ * BaseAdapter class defining the contract for database operations
+ * This is an abstract class that concrete adapters must implement
+ */
+export class BaseAdapter {
+  /**
+   * Finds a user by email
+   * @param {string} email - The email to search for
+   * @returns {Promise<object|null>} The user object or null if not found
+   */
+  async findUserByEmail(email) {
+    throw new Error('Method findUserByEmail() must be implemented');
+  }
+
+  /**
+   * Creates a new user
+   * @param {object} userData - User data including email and hashedPassword
+   * @returns {Promise<object>} The created user object
+   */
+  async createUser(userData) {
+    throw new Error('Method createUser() must be implemented');
+  }
+
+  /**
+   * Saves a refresh token for a user
+   * @param {string} userId - The user ID
+   * @param {string} token - The refresh token
+   * @param {Date} expiresAt - The expiration date
+   * @returns {Promise<void>}
+   */
+  async saveRefreshToken(userId, token, expiresAt) {
+    throw new Error('Method saveRefreshToken() must be implemented');
+  }
+
+  /**
+   * Checks if a refresh token is valid (not revoked and not expired)
+   * @param {string} token - The refresh token to check
+   * @returns {Promise<boolean>} True if the token is valid
+   */
+  async isRefreshTokenValid(token) {
+    throw new Error('Method isRefreshTokenValid() must be implemented');
+  }
+
+  /**
+   * Revokes a refresh token
+   * @param {string} token - The refresh token to revoke
+   * @returns {Promise<void>}
+   */
+  async revokeRefreshToken(token) {
+    throw new Error('Method revokeRefreshToken() must be implemented');
+  }
+
+  /**
+   * Revokes all refresh tokens for a user (for security incidents)
+   * @param {string} userId - The user ID
+   * @returns {Promise<void>}
+   */
+  async revokeAllUserSessions(userId) {
+    throw new Error('Method revokeAllUserSessions() must be implemented');
+  }
+}
+
+/**
+ * User schema for validation
+ */
+export const userSchema = z.object({
+  email: z.string().email(),
+  hashedPassword: z.string(),
+  role: z.string().optional().default('user')
+});
+
+/**
+ * Refresh token schema for validation
+ */
+export const refreshTokenSchema = z.object({
+  userId: z.string(),
+  token: z.string(),
+  expiresAt: z.date()
+});

package/src/adapters/memory.js

@@ -0,0 +1,159 @@
+import { BaseAdapter, userSchema, refreshTokenSchema } from './base.js';
+
+/**
+ * In-memory adapter implementation for testing
+ * Uses simple JavaScript objects to store data
+ */
+export class MemoryAdapter extends BaseAdapter {
+  #users = new Map(); // email -> user object
+  #refreshTokens = new Map(); // token -> { userId, expiresAt }
+  #revokedTokens = new Set(); // token -> boolean
+
+  /**
+   * Finds a user by email
+   * @param {string} email - The email to search for
+   * @returns {Promise<object|null>} The user object or null if not found
+   */
+  async findUserByEmail(email) {
+    if (typeof email !== 'string') {
+      throw new Error('Email must be a string');
+    }
+    return this.#users.get(email) || null;
+  }
+
+  /**
+   * Creates a new user
+   * @param {object} userData - User data including email and hashedPassword
+   * @returns {Promise<object>} The created user object
+   */
+  async createUser(userData) {
+    // Validate input
+    const validated = userSchema.parse(userData);
+    
+    if (this.#users.has(validated.email)) {
+      throw new Error('User with this email already exists');
+    }
+    
+    const user = {
+      id: crypto.randomUUID(),
+      email: validated.email,
+      hashedPassword: validated.hashedPassword,
+      role: validated.role,
+      createdAt: new Date()
+    };
+    
+    this.#users.set(validated.email, user);
+    return user;
+  }
+
+  /**
+   * Saves a refresh token for a user
+   * @param {string} userId - The user ID
+   * @param {string} token - The refresh token
+   * @param {Date} expiresAt - The expiration date
+   * @returns {Promise<void>}
+   */
+  async saveRefreshToken(userId, token, expiresAt) {
+    if (typeof userId !== 'string' || typeof token !== 'string' || !(expiresAt instanceof Date)) {
+      throw new Error('Invalid parameters');
+    }
+    
+    // Validate token format
+    if (token.length < 10) {
+      throw new Error('Token too short');
+    }
+    
+    this.#refreshTokens.set(token, { userId, expiresAt });
+    this.#revokedTokens.delete(token);
+  }
+
+  /**
+   * Checks if a refresh token is valid (not revoked and not expired)
+   * @param {string} token - The refresh token to check
+   * @returns {Promise<boolean>} True if the token is valid
+   */
+  async isRefreshTokenValid(token) {
+    if (typeof token !== 'string') {
+      throw new Error('Token must be a string');
+    }
+    
+    const tokenData = this.#refreshTokens.get(token);
+    
+    if (!tokenData) {
+      return false;
+    }
+    
+    // Check if revoked
+    if (this.#revokedTokens.has(token)) {
+      return false;
+    }
+    
+    // Check if expired
+    if (tokenData.expiresAt < new Date()) {
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Revokes a refresh token
+   * @param {string} token - The refresh token to revoke
+   * @returns {Promise<void>}
+   */
+  async revokeRefreshToken(token) {
+    if (typeof token !== 'string') {
+      throw new Error('Token must be a string');
+    }
+    this.#revokedTokens.add(token);
+  }
+
+  /**
+   * Revokes all refresh tokens for a user (for security incidents)
+   * @param {string} userId - The user ID
+   * @returns {Promise<void>}
+   */
+  async revokeAllUserSessions(userId) {
+    if (typeof userId !== 'string') {
+      throw new Error('User ID must be a string');
+    }
+    
+    // Find all tokens for this user and revoke them
+    for (const [token, tokenData] of this.#refreshTokens.entries()) {
+      if (tokenData.userId === userId) {
+        this.#revokedTokens.add(token);
+      }
+    }
+  }
+
+  /**
+   * Helper method to clear all data (for testing)
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    this.#users.clear();
+    this.#refreshTokens.clear();
+    this.#revokedTokens.clear();
+  }
+
+  /**
+   * Helper method to get user by ID (not part of BaseAdapter contract)
+   * @param {string} userId - The user ID
+   * @returns {Promise<object|null>} The user object or null if not found
+   */
+  async findUserById(userId) {
+    if (typeof userId !== 'string') {
+      throw new Error('User ID must be a string');
+    }
+    
+    for (const user of this.#users.values()) {
+      if (user.id === userId) {
+        return user;
+      }
+    }
+    return null;
+  }
+}
+
+// Export a singleton instance for convenience
+export const memoryAdapter = new MemoryAdapter();

package/src/core/crypto.js

@@ -0,0 +1,103 @@
+import argon2 from 'argon2';
+import { SignJWT, jwtVerify } from 'jose';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+/**
+ * Hashes a plain text password using Argon2
+ * @param {string} plain - The plain text password to hash
+ * @returns {Promise<string>} The hashed password
+ */
+export async function hashPassword(plain) {
+  if (typeof plain !== 'string') {
+    throw new Error('Password must be a string');
+  }
+  return await argon2.hash(plain);
+}
+
+/**
+ * Verifies a plain text password against a hashed password using Argon2
+ * @param {string} hash - The hashed password
+ * @param {string} plain - The plain text password to verify
+ * @returns {Promise<boolean>} True if the password matches, false otherwise
+ */
+export async function verifyPassword(hash, plain) {
+  if (typeof hash !== 'string' || typeof plain !== 'string') {
+    throw new Error('Hash and plain text must be strings');
+  }
+  // Always compare to prevent timing attacks
+  return await argon2.verify(hash, plain);
+}
+
+/**
+ * Signs an access token with 15-minute expiry
+ * @param {object} payload - The payload to sign
+ * @returns {Promise<string>} The signed JWT
+ */
+export async function signAccessToken(payload) {
+  const secret = new TextEncoder().encode(process.env.ACCESS_TOKEN_SECRET);
+  
+  if (!secret || secret.length < 32) {
+    throw new Error('ACCESS_TOKEN_SECRET must be at least 32 characters');
+  }
+  
+  return new SignJWT(payload)
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime('15m')
+    .setJti(crypto.randomUUID()) // Add unique JWT ID
+    .sign(secret);
+}
+
+/**
+ * Signs a refresh token with 7-day expiry
+ * @param {object} payload - The payload to sign
+ * @returns {Promise<string>} The signed JWT
+ */
+export async function signRefreshToken(payload) {
+  const secret = new TextEncoder().encode(process.env.REFRESH_TOKEN_SECRET);
+  
+  if (!secret || secret.length < 32) {
+    throw new Error('REFRESH_TOKEN_SECRET must be at least 32 characters');
+  }
+  
+  return new SignJWT(payload)
+    .setProtectedHeader({ alg: 'HS256' })
+    .setIssuedAt()
+    .setExpirationTime('7d')
+    .setJti(crypto.randomUUID()) // Add unique JWT ID
+    .sign(secret);
+}
+
+/**
+ * Verifies a JWT token
+ * @param {string} token - The JWT token to verify
+ * @param {string} type - The token type ('access' or 'refresh')
+ * @returns {Promise<object>} The verified payload
+ */
+export async function verifyJWT(token, type) {
+  if (typeof token !== 'string') {
+    throw new Error('Token must be a string');
+  }
+  
+  const secret = new TextEncoder().encode(
+    type === 'access' 
+      ? process.env.ACCESS_TOKEN_SECRET 
+      : process.env.REFRESH_TOKEN_SECRET
+  );
+  
+  if (!secret || secret.length < 32) {
+    throw new Error(`${type.toUpperCase()}_TOKEN_SECRET must be at least 32 characters`);
+  }
+  
+  try {
+    const { payload } = await jwtVerify(token, secret, {
+      algorithms: ['HS256']
+    });
+    return payload;
+  } catch (error) {
+    throw new Error('Invalid token');
+  }
+}

package/src/middleware/auth.js

@@ -0,0 +1,127 @@
+// RyAuth - Authentication Middleware
+// Provides JWT validation and role-based access control
+
+import { jwtVerify, importJWK, importSPKI } from 'jose';
+import { z } from 'zod';
+
+// Configuration schema
+const configSchema = z.object({
+  accessTokenSecret: z.string().min(32),
+  refreshTokenSecret: z.string().min(32),
+});
+
+// Error response schema
+const errorSchema = z.object({
+  error: z.string(),
+});
+
+// User payload schema
+const userPayloadSchema = z.object({
+  userId: z.string(),
+  email: z.string().email(),
+  role: z.string(),
+  iat: z.number(),
+  exp: z.number(),
+});
+
+class AuthMiddleware {
+  #config;
+  #accessKey;
+  #refreshKey;
+
+  constructor(config) {
+    this.#config = configSchema.parse(config);
+  }
+
+  async #initializeKeys() {
+    if (!this.#accessKey || !this.#refreshKey) {
+      // Convert secrets to JWK format for jose
+      this.#accessKey = await importJWK({ k: this.#config.accessTokenSecret, kty: 'oct' });
+      this.#refreshKey = await importJWK({ k: this.#config.refreshTokenSecret, kty: 'oct' });
+    }
+  }
+
+  // Extract token from Authorization header
+  #extractToken(req) {
+    const authHeader = req.headers['authorization'];
+    
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return null;
+    }
+
+    return authHeader.substring(7); // Remove 'Bearer ' prefix
+  }
+
+  // Verify JWT token
+  async #verifyToken(token, key) {
+    try {
+      const result = await jwtVerify(token, key);
+      return userPayloadSchema.parse(result.payload);
+    } catch (error) {
+      return null;
+    }
+  }
+
+  // Authentication middleware - validates JWT
+  async authenticate(req, res, next) {
+    await this.#initializeKeys();
+
+    const token = this.#extractToken(req);
+
+    if (!token) {
+      res.status(401).json(errorSchema.parse({ error: 'Unauthorized' }));
+      return;
+    }
+
+    // Verify token using access key
+    const payload = await this.#verifyToken(token, this.#accessKey);
+
+    if (!payload) {
+      res.status(403).json(errorSchema.parse({ error: 'Forbidden' }));
+      return;
+    }
+
+    // Check if token is expired
+    if (payload.exp * 1000 < Date.now()) {
+      res.status(401).json(errorSchema.parse({ error: 'Unauthorized' }));
+      return;
+    }
+
+    // Attach user to request
+    req.user = payload;
+    next();
+  }
+
+  // Authorization middleware - enforces role-based access control
+  authorize(...allowedRoles) {
+    return (req, res, next) => {
+      // Check if user is authenticated
+      if (!req.user) {
+        res.status(401).json(errorSchema.parse({ error: 'Unauthorized' }));
+        return;
+      }
+
+      // Check if user has required role
+      if (!allowedRoles.includes(req.user.role)) {
+        res.status(403).json(errorSchema.parse({ error: 'Forbidden' }));
+        return;
+      }
+
+      next();
+    };
+  }
+}
+
+// Export middleware factory
+export function createAuthMiddleware(config) {
+  return new AuthMiddleware(config);
+}
+
+// Export middleware instances for convenience
+export function authenticate(req, res, next) {
+  throw new Error('AuthMiddleware must be initialized with config before use');
+}
+
+export function authorize(...roles) {
+  throw new Error('AuthMiddleware must be initialized with config before use');
+}

package/src/services/auth-service.js

@@ -0,0 +1,172 @@
+// Auth Service Implementation
+// Handles user registration, login, and refresh token rotation
+// Uses adapter pattern for database abstraction
+
+import { z } from 'zod';
+import { hashPassword, verifyPassword } from '../core/crypto.js';
+import { signAccessToken, signRefreshToken, verifyJWT } from '../core/crypto.js';
+
+// Zod validation schemas
+const registerSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8, 'Password must be at least 8 characters'),
+});
+
+const loginSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(1, 'Password is required'),
+});
+
+const refreshSchema = z.object({
+  refreshToken: z.string().min(10, 'Refresh token is required'),
+});
+
+/**
+ * AuthService class
+ * Orchestrates authentication flows using adapter pattern
+ */
+export class AuthService {
+  /**
+   * Create AuthService instance
+   * @param {BaseAdapter} adapter - Database adapter implementation
+   */
+  constructor(adapter) {
+    this.adapter = adapter;
+  }
+
+  /**
+   * Register a new user
+   * @param {string} email - User's email address
+   * @param {string} password - User's password
+   * @returns {Promise<{success: true, userId: string}>} Success response
+   * @throws {Error} Validation errors or registration failures
+   */
+  async register(email, password) {
+    // Validate input
+    const validated = registerSchema.safeParse({ email, password });
+    if (!validated.success) {
+      throw new Error(validated.error.issues[0].message);
+    }
+
+    // Check if user already exists
+    const existingUser = await this.adapter.findUserByEmail(email);
+    if (existingUser) {
+      throw new Error('User already exists');
+    }
+
+    // Hash password
+    const hashedPassword = await hashPassword(password);
+
+    // Create user
+    const user = await this.adapter.createUser({
+      email: validated.data.email,
+      hashedPassword: hashedPassword,
+    });
+
+    return {
+      success: true,
+      userId: user.id,
+    };
+  }
+
+  /**
+   * Login user and issue token pair
+   * @param {string} email - User's email address
+   * @param {string} password - User's password
+   * @returns {Promise<{success: true, accessToken: string, refreshToken: string}>} Token pair
+   * @throws {Error} Generic "Invalid credentials" for security
+   */
+  async login(email, password) {
+    // Validate input
+    const validated = loginSchema.safeParse({ email, password });
+    if (!validated.success) {
+      throw new Error(validated.error.issues[0].message);
+    }
+
+    // Find user by email
+    const user = await this.adapter.findUserByEmail(validated.data.email);
+
+    // Always perform password verification for timing safety
+    // Use a dummy hash if user doesn't exist to maintain consistent timing
+    const hashToCheck = user ? user.hashedPassword : '$argon2id$v=19$m=65536,t=3,p=4$ltv4rLoGLpCul8wO1xwJlQ$vfkMCoi/vx7JJF0BBMrzxR/RuGzzv9i4M4o1vYfDfqY';
+    const passwordValid = await verifyPassword(hashToCheck, validated.data.password);
+
+    // Check both user existence and password validity
+    if (!user || !passwordValid) {
+      throw new Error('Invalid credentials');
+    }
+
+    // Generate token pair
+    const accessToken = await signAccessToken({ userId: user.id, role: user.role });
+    const refreshToken = await signRefreshToken({ userId: user.id });
+
+    // Save refresh token
+    await this.adapter.saveRefreshToken(
+      user.id,
+      refreshToken,
+      new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) // 7 days from now
+    );
+
+    return {
+      success: true,
+      accessToken,
+      refreshToken,
+    };
+  }
+
+  /**
+   * Refresh access token using refresh token
+   * Implements automatic breach detection
+   * @param {string} refreshToken - Valid refresh token
+   * @returns {Promise<{success: true, accessToken: string, refreshToken: string}>} New token pair
+   * @throws {Error} If token is invalid or revoked
+   */
+  async refresh(refreshToken) {
+    // Validate input
+    const validated = refreshSchema.safeParse({ refreshToken });
+    if (!validated.success) {
+      throw new Error(validated.error.issues[0].message);
+    }
+
+    // Verify JWT signature and extract payload
+    let payload;
+    try {
+      payload = await verifyJWT(validated.data.refreshToken, 'refresh');
+    } catch (error) {
+      throw new Error('Invalid refresh token');
+    }
+
+    // Check if token is revoked or expired
+    const isValid = await this.adapter.isRefreshTokenValid(validated.data.refreshToken);
+    if (!isValid) {
+      // Automatic breach detection: revoke all tokens for this user
+      await this.adapter.revokeAllUserSessions(payload.userId);
+      throw new Error('Session revoked - please login again');
+    }
+
+    // Revoke old refresh token (token rotation)
+    await this.adapter.revokeRefreshToken(validated.data.refreshToken);
+
+    // Issue new token pair
+    const newAccessToken = await signAccessToken({ 
+      userId: payload.userId, 
+      role: payload.role || 'user' 
+    });
+    const newRefreshToken = await signRefreshToken({ userId: payload.userId });
+
+    // Save new refresh token
+    await this.adapter.saveRefreshToken(
+      payload.userId,
+      newRefreshToken,
+      new Date(Date.now() + 7 * 24 * 60 * 60 * 1000) // 7 days from now
+    );
+
+    return {
+      success: true,
+      accessToken: newAccessToken,
+      refreshToken: newRefreshToken,
+    };
+  }
+}
+
+export default AuthService;