ryauth 1.0.0

package/.env.example

@@ -0,0 +1,7 @@
+# RyAuth Configuration
+
+# Access Token Secret (minimum 32 characters)
+ACCESS_TOKEN_SECRET=your_32+_character_access_token_secret_here
+
+# Refresh Token Secret (minimum 32 characters)
+REFRESH_TOKEN_SECRET=your_32+_character_refresh_token_secret_here

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,232 @@
+# RyAuth
+
+[![npm version](https://badge.fury.io/js/ryauth.svg)](https://badge.fury.io/js/ryauth)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![Test Coverage](https://img.shields.io/badge/coverage-94%25-green)](https://github.com/ryanpereira49/RyAuth)
+[![GitHub Issues](https://img.shields.io/github/issues/ryanpereira49/RyAuth)](https://github.com/ryanpereira49/RyAuth/issues)
+
+A modern, secure, and database-agnostic authentication library for Node.js. Built with JWT tokens, Argon2 password hashing, and role-based access control (RBAC).
+
+## ✨ Features
+
+- 🔐 **Secure Authentication** - JWT-based authentication with access and refresh tokens
+- 🛡️ **Password Security** - Argon2 password hashing (winner of the 2015 Password Hashing Competition)
+- 🔄 **Token Rotation** - Automatic refresh token rotation for enhanced security
+- 👥 **Role-Based Access Control** - Fine-grained permissions and user roles
+- 🗄️ **Database Agnostic** - Adapter pattern supports any database (PostgreSQL, MongoDB, MySQL, etc.)
+- 🚀 **Modern JavaScript** - ES modules, async/await, and TypeScript-ready
+- ✅ **Runtime Validation** - Zod schemas for input validation and type safety
+- 🧪 **Comprehensive Testing** - 66 tests with 94% code coverage
+- 📚 **Full Documentation** - Complete API reference and examples
+
+## 📦 Installation
+
+```bash
+npm install ryauth
+# or
+yarn add ryauth
+# or
+pnpm add ryauth
+```
+
+## 🚀 Quick Start
+
+```javascript
+import express from 'express';
+import { createAuthMiddleware, AuthService, MemoryAdapter } from 'ryauth';
+
+const app = express();
+app.use(express.json());
+
+// Initialize authentication
+const adapter = new MemoryAdapter();
+const authService = new AuthService(adapter);
+
+// Create middleware
+const authMiddleware = createAuthMiddleware({
+  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET,
+  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET
+});
+
+// Register endpoint
+app.post('/auth/register', async (req, res) => {
+  try {
+    const { email, password } = req.body;
+    const result = await authService.register(email, password);
+    res.json(result);
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+// Login endpoint
+app.post('/auth/login', async (req, res) => {
+  try {
+    const { email, password } = req.body;
+    const result = await authService.login(email, password);
+    res.json(result);
+  } catch (error) {
+    res.status(401).json({ error: error.message });
+  }
+});
+
+// Protected route
+app.get('/api/profile', authMiddleware.authenticate, (req, res) => {
+  res.json({ user: req.user });
+});
+
+// Admin-only route
+app.get('/api/admin', authMiddleware.authenticate, authMiddleware.authorize('admin'), (req, res) => {
+  res.json({ message: 'Welcome, admin!' });
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+## 🔧 Environment Setup
+
+Create a `.env` file in your project root:
+
+```env
+# Access Token Secret (minimum 32 characters)
+ACCESS_TOKEN_SECRET=your_32+_character_access_token_secret_here
+
+# Refresh Token Secret (minimum 32 characters)
+REFRESH_TOKEN_SECRET=your_32+_character_refresh_token_secret_here
+```
+
+## 🏗️ Architecture
+
+RyAuth uses a modular architecture designed for security and flexibility:
+
+```
+src/
+├── core/
+│   └── crypto.js          # Argon2 & JOSE JWT operations
+├── adapters/
+│   ├── base.js           # Abstract database adapter interface
+│   └── memory.js         # In-memory adapter for testing
+├── middleware/
+│   └── auth.js           # Express middleware for JWT validation
+└── services/
+    └── auth-service.js   # Core authentication business logic
+```
+
+## 📚 API Overview
+
+### AuthService
+
+The main service class that orchestrates authentication flows.
+
+```javascript
+const authService = new AuthService(adapter);
+
+// User management
+await authService.register('user@example.com', 'password123');
+await authService.login('user@example.com', 'password123');
+await authService.refresh(refreshToken);
+await authService.revokeRefreshToken(refreshToken);
+```
+
+### Middleware
+
+Express.js middleware for authentication and authorization.
+
+```javascript
+const authMiddleware = createAuthMiddleware(config);
+
+// Authentication
+app.get('/protected', authMiddleware.authenticate, handler);
+
+// Authorization
+app.get('/admin', authMiddleware.authenticate, authMiddleware.authorize('admin'), handler);
+```
+
+### Adapters
+
+Database abstraction layer supporting multiple databases.
+
+```javascript
+// Built-in MemoryAdapter for testing
+const adapter = new MemoryAdapter();
+
+// Custom adapter for PostgreSQL
+class PostgreSQLAdapter extends BaseAdapter {
+  async findUserByEmail(email) { /* implementation */ }
+  async createUser(userData) { /* implementation */ }
+  // ... other required methods
+}
+```
+
+## 🧪 Testing
+
+```bash
+npm test
+```
+
+RyAuth includes comprehensive test coverage:
+- **66 tests** covering all functionality
+- **94% code coverage**
+- Unit tests for all core modules
+- Integration tests for complete flows
+
+## 📖 Documentation
+
+- **[API Reference](docs/api-reference.md)** - Complete API documentation
+- **[Examples](docs/examples.md)** - Practical code examples and integrations
+- **[Contributing Guide](CONTRIBUTING.md)** - Guidelines for contributors
+
+## 🔒 Security Features
+
+- **Argon2 Password Hashing** - Memory-hard algorithm resistant to brute force attacks
+- **JWT Token Rotation** - Automatic refresh token rotation prevents token theft
+- **Session Management** - Ability to revoke refresh tokens
+- **Input Validation** - Runtime validation with Zod schemas
+- **Timing-Safe Comparison** - Prevents timing attacks during authentication
+- **Secure Defaults** - 15-minute access tokens, 7-day refresh tokens
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/ryanpereira49/RyAuth.git
+cd RyAuth
+
+# Install dependencies
+npm install
+
+# Copy environment template
+cp .env.example .env
+
+# Run tests
+npm test
+```
+
+## 📄 License
+
+MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built with [JOSE](https://github.com/panva/jose) for JWT operations
+- Password hashing powered by [Argon2](https://github.com/ranisalt/node-argon2)
+- Runtime validation with [Zod](https://github.com/colinhacks/zod)
+
+## 📞 Support
+
+- 🐛 [Issues](https://github.com/ryanpereira49/RyAuth/issues)
+- 💬 [Discussions](https://github.com/ryanpereira49/RyAuth/discussions)
+- 📧 Contact: ryanpereira499@gmail.com
+
+---
+
+**Made with ❤️ for secure Node.js applications**
+
+*RyAuth - Modern Authentication, Simplified.*

package/docs/api-reference.md

@@ -0,0 +1,203 @@
+# API Reference
+
+Complete API documentation for RyAuth authentication library.
+
+## AuthService
+
+The main service class that orchestrates authentication flows.
+
+### Constructor
+
+```javascript
+new AuthService(adapter)
+```
+
+**Parameters:**
+- `adapter` (BaseAdapter): Database adapter instance
+
+### Methods
+
+#### `register(email, password)`
+
+Register a new user account.
+
+```javascript
+const result = await authService.register('user@example.com', 'password123');
+```
+
+**Parameters:**
+- `email` (string): User's email address
+- `password` (string): User's password (minimum 8 characters)
+
+**Returns:** `Promise<{success: boolean, userId: string}>`
+
+**Throws:** Error for validation failures or duplicate users
+
+#### `login(email, password)`
+
+Authenticate a user and return tokens.
+
+```javascript
+const result = await authService.login('user@example.com', 'password123');
+```
+
+**Parameters:**
+- `email` (string): User's email address
+- `password` (string): User's password
+
+**Returns:** `Promise<{success: boolean, accessToken: string, refreshToken: string, user: object}>`
+
+**Throws:** Error for invalid credentials
+
+#### `refresh(refreshToken)`
+
+Refresh access and refresh tokens.
+
+```javascript
+const result = await authService.refresh('refresh_token_here');
+```
+
+**Parameters:**
+- `refreshToken` (string): Valid refresh token
+
+**Returns:** `Promise<{success: boolean, accessToken: string, refreshToken: string}>`
+
+**Throws:** Error for invalid or expired tokens
+
+#### `revokeRefreshToken(refreshToken)`
+
+Revoke a refresh token (logout).
+
+```javascript
+await authService.revokeRefreshToken('refresh_token_here');
+```
+
+**Parameters:**
+- `refreshToken` (string): Refresh token to revoke
+
+**Returns:** `Promise<void>`
+
+## Middleware
+
+Express.js middleware for JWT authentication and authorization.
+
+### `createAuthMiddleware(config)`
+
+Create an authentication middleware instance.
+
+```javascript
+const authMiddleware = createAuthMiddleware({
+  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET,
+  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET
+});
+```
+
+**Parameters:**
+- `config` (object):
+  - `accessTokenSecret` (string): Secret for access tokens (min 32 chars)
+  - `refreshTokenSecret` (string): Secret for refresh tokens (min 32 chars)
+
+**Returns:** AuthMiddleware instance with `authenticate` and `authorize` methods
+
+### `authenticate`
+
+Middleware to verify JWT access tokens.
+
+```javascript
+app.get('/protected', authMiddleware.authenticate, (req, res) => {
+  res.json({ user: req.user });
+});
+```
+
+Attaches `req.user` with user payload if token is valid.
+
+### `authorize(...roles)`
+
+Middleware for role-based access control.
+
+```javascript
+app.get('/admin', authMiddleware.authenticate, authMiddleware.authorize('admin'), (req, res) => {
+  res.json({ message: 'Admin access granted' });
+});
+```
+
+**Parameters:**
+- `...roles` (string[]): Allowed roles
+
+## Adapters
+
+Database abstraction layer using the adapter pattern.
+
+### BaseAdapter
+
+Abstract base class for database adapters.
+
+**Required Methods:**
+- `findUserByEmail(email)`: Find user by email
+- `createUser(userData)`: Create new user
+- `saveRefreshToken(userId, token, expiresAt)`: Save refresh token
+- `findRefreshToken(token)`: Find refresh token
+- `revokeRefreshToken(token)`: Revoke refresh token
+- `isRefreshTokenRevoked(token)`: Check if token is revoked
+
+### MemoryAdapter
+
+In-memory adapter for development and testing.
+
+```javascript
+import { MemoryAdapter } from 'ryauth';
+
+const adapter = new MemoryAdapter();
+```
+
+## Crypto Utilities
+
+Low-level cryptographic functions (advanced usage).
+
+### `hashPassword(plain)`
+
+Hash a password with Argon2.
+
+```javascript
+const hash = await hashPassword('password123');
+```
+
+### `verifyPassword(hash, plain)`
+
+Verify a password against its hash.
+
+```javascript
+const isValid = await verifyPassword(hash, 'password123');
+```
+
+### `signAccessToken(payload)`
+
+Sign an access token (15-minute expiry).
+
+### `signRefreshToken(payload)`
+
+Sign a refresh token (7-day expiry).
+
+### `verifyJWT(token, secret)`
+
+Verify and decode a JWT token.
+
+## Error Handling
+
+RyAuth throws descriptive errors for various failure conditions:
+
+- **Validation Errors**: Invalid input data
+- **Authentication Errors**: Invalid credentials, expired tokens
+- **Authorization Errors**: Insufficient permissions
+- **Adapter Errors**: Database operation failures
+
+Always wrap operations in try-catch blocks:
+
+```javascript
+try {
+  const result = await authService.login(email, password);
+  res.json(result);
+} catch (error) {
+  res.status(400).json({ error: error.message });
+}
+```

package/docs/examples.md

@@ -0,0 +1,225 @@
+# Examples
+
+Practical examples for integrating RyAuth into your applications.
+
+## Basic Express.js Setup
+
+```javascript
+import express from 'express';
+import { createAuthMiddleware, AuthService, MemoryAdapter } from 'ryauth';
+
+const app = express();
+app.use(express.json());
+
+// Initialize
+const adapter = new MemoryAdapter();
+const authService = new AuthService(adapter);
+const authMiddleware = createAuthMiddleware({
+  accessTokenSecret: process.env.ACCESS_TOKEN_SECRET,
+  refreshTokenSecret: process.env.REFRESH_TOKEN_SECRET
+});
+
+// Routes
+app.post('/auth/register', async (req, res) => {
+  try {
+    const { email, password } = req.body;
+    const result = await authService.register(email, password);
+    res.json(result);
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+app.post('/auth/login', async (req, res) => {
+  try {
+    const { email, password } = req.body;
+    const result = await authService.login(email, password);
+    res.json(result);
+  } catch (error) {
+    res.status(401).json({ error: error.message });
+  }
+});
+
+app.get('/api/profile', authMiddleware.authenticate, (req, res) => {
+  res.json({ user: req.user });
+});
+
+app.listen(3000);
+```
+
+## Role-Based Access Control
+
+```javascript
+// Admin-only route
+app.get('/api/admin/users',
+  authMiddleware.authenticate,
+  authMiddleware.authorize('admin'),
+  (req, res) => {
+    res.json({ users: [] }); // Return user list
+  }
+);
+
+// Multiple roles allowed
+app.get('/api/content',
+  authMiddleware.authenticate,
+  authMiddleware.authorize('user', 'editor', 'admin'),
+  (req, res) => {
+    res.json({ content: 'Protected content' });
+  }
+);
+```
+
+## Token Refresh
+
+```javascript
+app.post('/auth/refresh', async (req, res) => {
+  try {
+    const { refreshToken } = req.body;
+    const result = await authService.refresh(refreshToken);
+    res.json(result);
+  } catch (error) {
+    res.status(401).json({ error: error.message });
+  }
+});
+```
+
+## Logout (Token Revocation)
+
+```javascript
+app.post('/auth/logout', authMiddleware.authenticate, async (req, res) => {
+  try {
+    // Get refresh token from request (could be in body, cookie, etc.)
+    const { refreshToken } = req.body;
+    await authService.revokeRefreshToken(refreshToken);
+    res.json({ success: true });
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+```
+
+## Custom Database Adapter
+
+```javascript
+import { BaseAdapter } from 'ryauth';
+
+export class PostgreSQLAdapter extends BaseAdapter {
+  constructor(db) {
+    super();
+    this.db = db; // Your database connection
+  }
+
+  async findUserByEmail(email) {
+    const result = await this.db.query(
+      'SELECT id, email, hashed_password, role FROM users WHERE email = $1',
+      [email]
+    );
+    return result.rows[0] || null;
+  }
+
+  async createUser(userData) {
+    const result = await this.db.query(
+      'INSERT INTO users (email, hashed_password, role) VALUES ($1, $2, $3) RETURNING *',
+      [userData.email, userData.hashedPassword, userData.role]
+    );
+    return result.rows[0];
+  }
+
+  async saveRefreshToken(userId, token, expiresAt) {
+    await this.db.query(
+      'INSERT INTO refresh_tokens (user_id, token, expires_at) VALUES ($1, $2, $3)',
+      [userId, token, expiresAt]
+    );
+  }
+
+  async findRefreshToken(token) {
+    const result = await this.db.query(
+      'SELECT * FROM refresh_tokens WHERE token = $1 AND expires_at > NOW()',
+      [token]
+    );
+    return result.rows[0] || null;
+  }
+
+  async revokeRefreshToken(token) {
+    await this.db.query(
+      'DELETE FROM refresh_tokens WHERE token = $1',
+      [token]
+    );
+  }
+
+  async isRefreshTokenRevoked(token) {
+    const result = await this.db.query(
+      'SELECT 1 FROM refresh_tokens WHERE token = $1',
+      [token]
+    );
+    return result.rows.length === 0;
+  }
+}
+```
+
+## Testing with RyAuth
+
+```javascript
+import { AuthService, MemoryAdapter } from 'ryauth';
+
+describe('Authentication', () => {
+  let authService;
+  let adapter;
+
+  beforeEach(() => {
+    adapter = new MemoryAdapter();
+    authService = new AuthService(adapter);
+  });
+
+  it('should register a new user', async () => {
+    const result = await authService.register('test@example.com', 'password123');
+    expect(result.success).toBe(true);
+    expect(result.userId).toBeDefined();
+  });
+
+  it('should login with correct credentials', async () => {
+    await authService.register('test@example.com', 'password123');
+    const result = await authService.login('test@example.com', 'password123');
+
+    expect(result.success).toBe(true);
+    expect(result.accessToken).toBeDefined();
+    expect(result.refreshToken).toBeDefined();
+  });
+});
+```
+
+## Environment Configuration
+
+```javascript
+// .env
+ACCESS_TOKEN_SECRET=your_super_secret_access_token_key_here_minimum_32_chars
+REFRESH_TOKEN_SECRET=your_super_secret_refresh_token_key_here_minimum_32_chars
+
+// Generate secure secrets
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+## Error Handling
+
+```javascript
+// Always wrap auth operations in try-catch
+app.post('/auth/register', async (req, res) => {
+  try {
+    const result = await authService.register(req.body.email, req.body.password);
+    res.json(result);
+  } catch (error) {
+    // Handle validation errors, duplicate users, etc.
+    res.status(400).json({ error: error.message });
+  }
+});
+
+app.post('/auth/login', async (req, res) => {
+  try {
+    const result = await authService.login(req.body.email, req.body.password);
+    res.json(result);
+  } catch (error) {
+    // Handle invalid credentials
+    res.status(401).json({ error: error.message });
+  }
+});
+```

package/index.js

@@ -0,0 +1,15 @@
+// RyAuth - Modern Authentication Library for Node.js
+// Main entry point exporting all public APIs
+
+// Core services
+export { AuthService } from './src/services/auth-service.js';
+
+// Middleware
+export { createAuthMiddleware } from './src/middleware/auth.js';
+
+// Adapters
+export { BaseAdapter } from './src/adapters/base.js';
+export { MemoryAdapter } from './src/adapters/memory.js';
+
+// Core utilities (for advanced users)
+export { hashPassword, verifyPassword, signAccessToken, signRefreshToken, verifyJWT } from './src/core/crypto.js';