@latanda/auth-middleware 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.0.1 - 2026-05-12
+
+- Renamed scope: `@perks/auth-middleware` → `@latanda/auth-middleware`. The old package is deprecated with a redirect message.
+- **Fixed broken `main` field**: 1.0.0 pointed at `lib/index.js` which was never built or committed (`lib/` is gitignored). Changed to `src/index.js` so `require("@latanda/auth-middleware")` actually works. The old `@perks` 1.0.0 was effectively unusable due to this bug.
+- Added explicit `files` field to package.json for predictable npm tarballs.
+- Removed stale `types` field (it pointed at the same nonexistent `lib/index.d.ts`).
+- Fixed author email metadata (was a placeholder).
+- Added npm version, downloads, license, and node badges to README.
+- No API changes.
+
+## 1.0.0 - 2025-10-22
+
+- Initial release. JWT auth, RBAC, PostgreSQL integration, Nginx-friendly. Battle-tested at latanda.online.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Narjell Ebanks / La Tanda
+
+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/MIGRATION.md

@@ -0,0 +1,29 @@
+# Migrating from @perks/auth-middleware to @latanda/auth-middleware
+
+The package was renamed in v1.0.1 to align with the La Tanda project brand. No code changes are required other than updating the package name in your dependencies.
+
+## Quick upgrade
+
+```bash
+npm uninstall @perks/auth-middleware
+npm install @latanda/auth-middleware
+```
+
+## require() / import changes
+
+```js
+// Before
+const auth = require('@perks/auth-middleware');
+// After
+const auth = require('@latanda/auth-middleware');
+```
+
+The exported API is identical between 1.0.0 and 1.0.1.
+
+## Why the rename?
+
+`@perks` was a personal npm scope. `@latanda` is the project scope used across the La Tanda ecosystem (whitepaper, platform, future packages like `@latanda/cv-refiner` and `@latanda/tanda-engine`). Aligning the package name with the brand prevents confusion and makes future ecosystem packages discoverable under one scope.
+
+## Deprecation of @perks/auth-middleware
+
+`@perks/auth-middleware@1.0.0` will remain on the registry but is deprecated with a message pointing to this package. Existing installs will continue to work; please migrate at your convenience.

package/README.md

@@ -0,0 +1,438 @@
+# @latanda/auth-middleware
+
+[![npm version](https://img.shields.io/npm/v/@latanda/auth-middleware.svg)](https://www.npmjs.com/package/@latanda/auth-middleware)
+[![npm downloads](https://img.shields.io/npm/dm/@latanda/auth-middleware.svg)](https://www.npmjs.com/package/@latanda/auth-middleware)
+[![license](https://img.shields.io/npm/l/@latanda/auth-middleware.svg)](https://github.com/INDIGOAZUL/latanda-auth-middleware/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/@latanda/auth-middleware.svg)](https://nodejs.org)
+
+[![ci](https://github.com/INDIGOAZUL/latanda-auth-middleware/actions/workflows/test.yml/badge.svg)](https://github.com/INDIGOAZUL/latanda-auth-middleware/actions/workflows/test.yml)
+
+**Production-ready JWT authentication middleware for Node.js + PostgreSQL + Nginx**
+
+Battle-tested with 30+ users at [latanda.online](https://latanda.online) ✨
+
+## Migration from @perks/auth-middleware
+
+This package was previously published as `@perks/auth-middleware`. The scope was renamed to `@latanda` in v1.0.1 to align with the La Tanda project brand. The API is unchanged — only the package name and import path differ. See [MIGRATION.md](MIGRATION.md) for full details.
+
+```bash
+npm uninstall @perks/auth-middleware && npm install @latanda/auth-middleware
+```
+
+```js
+// Before:  const auth = require('@perks/auth-middleware');
+// After:   const auth = require('@latanda/auth-middleware');
+```
+
+## Features
+
+- ✅ **JWT Token Generation & Validation** - Secure HS256 tokens with comprehensive claim validation
+- ✅ **Role-Based Access Control (RBAC)** - Pre-configured roles: ADMIN, MIT, IT, USER
+- ✅ **Express Middleware** - Drop-in authentication for Express.js apps
+- ✅ **PostgreSQL Integration** - Production-ready database schema included
+- ✅ **Nginx Compatible** - Works seamlessly with Nginx reverse proxy
+- ✅ **Token Refresh** - Automatic token refresh with expiration detection
+- ✅ **Permission System** - Granular permission checks beyond roles
+- ✅ **Resource Ownership** - Enforce users can only access their own resources
+- ✅ **Audit Logging** - Track authentication events for security monitoring
+- ✅ **Zero Dependencies** - Only requires `jsonwebtoken`, `bcrypt`, and `pg`
+
+## Quick Start (5 minutes to secure auth)
+
+### Installation
+
+```bash
+npm install @latanda/auth-middleware jsonwebtoken bcrypt pg
+```
+
+### 1. Set up PostgreSQL
+
+```bash
+# Run the schema migration
+psql -U your_user -d your_database -f node_modules/@latanda/auth-middleware/sql/schema.sql
+```
+
+### 2. Add to your Express app
+
+```javascript
+const express = require('express');
+const { createAuthMiddleware, requireRole } = require('@latanda/auth-middleware');
+
+const app = express();
+
+// Protect all API routes
+app.use('/api/*', createAuthMiddleware({
+  jwtSecret: process.env.JWT_SECRET // Store this in .env file!
+}));
+
+// Require ADMIN role for admin routes
+app.use('/api/admin/*', requireRole('ADMIN'));
+
+// Your protected routes
+app.get('/api/profile', (req, res) => {
+  // req.user is automatically populated with authenticated user
+  res.json({
+    success: true,
+    user: req.user // { id, email, role, permissions }
+  });
+});
+
+app.listen(3000, () => console.log('Secure API running on port 3000'));
+```
+
+### 3. Generate tokens on login
+
+```javascript
+const { generateToken } = require('@latanda/auth-middleware');
+const bcrypt = require('bcrypt');
+
+app.post('/auth/login', async (req, res) => {
+  const { email, password } = req.body;
+
+  // Get user from database
+  const user = await db.query('SELECT * FROM users WHERE email = $1', [email]);
+
+  if (!user || !await bcrypt.compare(password, user.password_hash)) {
+    return res.status(401).json({ error: 'Invalid credentials' });
+  }
+
+  // Generate JWT token
+  const token = generateToken(user, process.env.JWT_SECRET);
+
+  res.json({
+    success: true,
+    token,
+    user: { id: user.id, email: user.email, role: user.role }
+  });
+});
+```
+
+**That's it!** Your API is now secured with production-ready JWT authentication.
+
+## Case Study: La Tanda
+
+[La Tanda](https://latanda.online) is a Web3 tanda (rotating savings and credit association) platform serving 30+ users across 16+ groups with real financial transactions.
+
+**What we use this middleware for:**
+
+- ✅ **Secure user authentication** - JWT tokens with 8-hour expiration
+- ✅ **Role-based access** - ADMIN (platform management), MIT (group coordinators), USER (members)
+- ✅ **API protection** - All 85+ API endpoints secured
+- ✅ **Transaction security** - Ensure users can only access their own transactions
+- ✅ **Admin panel** - Restricted to ADMIN role with full audit logging
+
+**Results:**
+- 🔒 Zero authentication-related security incidents
+- ⚡ Sub-100ms JWT validation performance
+- 📊 Complete audit trail of all auth events
+- 🚀 Seamless integration with Nginx reverse proxy
+
+## Full Documentation
+
+### API Reference
+
+#### JWT Functions
+
+```javascript
+const { generateToken, validateToken, refreshToken } = require('@latanda/auth-middleware');
+
+// Generate a token
+const token = generateToken(user, jwtSecret, {
+  expiresIn: '8h', // Default: 8 hours
+  issuer: 'your-app.com',
+  audience: 'your-app'
+});
+
+// Validate a token
+const validation = validateToken(token, jwtSecret);
+if (validation.valid) {
+  console.log('User:', validation.user_id, validation.email, validation.role);
+} else {
+  console.error('Invalid token:', validation.error);
+}
+
+// Refresh a token (if expiring soon)
+const refreshResult = refreshToken(oldToken, jwtSecret);
+if (refreshResult.success) {
+  console.log('New token:', refreshResult.token);
+}
+```
+
+#### RBAC Functions
+
+```javascript
+const { hasPermission, hasRoleLevel, ROLES } = require('@latanda/auth-middleware');
+
+// Check if user has permission
+if (hasPermission('ADMIN', 'user_management')) {
+  // User has permission
+}
+
+// Check if role meets minimum level
+if (hasRoleLevel('MIT', 'USER')) { // true - MIT is higher than USER
+  // Access granted
+}
+
+// View all roles and permissions
+console.log(ROLES);
+/*
+{
+  ADMIN: { level: 100, permissions: [...] },
+  MIT: { level: 50, permissions: [...] },
+  IT: { level: 75, permissions: [...] },
+  USER: { level: 10, permissions: [...] }
+}
+*/
+```
+
+#### Middleware
+
+```javascript
+const {
+  createAuthMiddleware,
+  requirePermission,
+  requireRole,
+  requireOwnership,
+  optionalAuth
+} = require('@latanda/auth-middleware');
+
+// Basic authentication (required)
+app.use('/api/*', createAuthMiddleware({ jwtSecret: process.env.JWT_SECRET }));
+
+// Require specific permission
+app.post('/api/users', requirePermission('user_management'), (req, res) => {
+  // Only users with 'user_management' permission can access
+});
+
+// Require specific role or higher
+app.use('/api/admin/*', requireRole('ADMIN'));
+app.use('/api/groups/create', requireRole('MIT')); // MIT or ADMIN
+
+// Enforce resource ownership
+app.get('/api/transactions/:userId', requireOwnership(req => req.params.userId), (req, res) => {
+  // Users can only view their own transactions (unless ADMIN)
+});
+
+// Optional authentication (works with or without token)
+app.get('/api/public/stats', optionalAuth({ jwtSecret: process.env.JWT_SECRET }), (req, res) => {
+  if (req.user) {
+    // Show personalized stats
+  } else {
+    // Show public stats
+  }
+});
+```
+
+### Roles and Permissions
+
+#### Pre-configured Roles
+
+| Role | Level | Permissions |
+|------|-------|-------------|
+| **ADMIN** | 100 | `full_access`, `user_management`, `system_config`, `approve_deposits`, `manage_groups`, `view_analytics`, `manage_roles`, `delete_users`, `system_settings` |
+| **IT** | 75 | `view_system_logs`, `debug_access`, `api_access`, `view_analytics`, `technical_support` |
+| **MIT** | 50 | `create_groups`, `manage_own_groups`, `approve_members`, `view_group_analytics`, `edit_group_settings` |
+| **USER** | 10 | `view_own_profile`, `edit_own_profile`, `join_groups`, `make_payments`, `view_own_transactions` |
+
+#### Custom Permissions
+
+You can add custom permissions to the database:
+
+```sql
+INSERT INTO user_permissions (user_id, permission, granted_by)
+VALUES (123, 'beta_access', 1);
+```
+
+Then check in your code:
+
+```javascript
+if (req.user.permissions.includes('beta_access')) {
+  // Show beta features
+}
+```
+
+### Database Schema
+
+The included PostgreSQL schema provides:
+
+- ✅ **users** table - User accounts with bcrypt password hashes
+- ✅ **sessions** table - Active JWT token tracking (optional, for revocation)
+- ✅ **user_permissions** table - Custom per-user permissions
+- ✅ **auth_audit_log** table - Authentication event audit trail
+
+See `sql/schema.sql` for full details.
+
+### Nginx Integration
+
+This middleware works seamlessly with Nginx reverse proxy:
+
+```nginx
+# /etc/nginx/sites-available/your-app
+location /api/ {
+    proxy_pass http://localhost:3000/api/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    # CORS headers for JWT
+    add_header Access-Control-Allow-Origin * always;
+    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
+    add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
+
+    if ($request_method = OPTIONS) {
+        return 204;
+    }
+}
+```
+
+Then your frontend can make authenticated requests:
+
+```javascript
+fetch('https://your-app.com/api/profile', {
+  headers: {
+    'Authorization': `Bearer ${token}`,
+    'Content-Type': 'application/json'
+  }
+})
+```
+
+## Advanced Usage
+
+### Custom Unauthorized Handler
+
+```javascript
+app.use('/api/*', createAuthMiddleware({
+  jwtSecret: process.env.JWT_SECRET,
+  onUnauthorized: (req, res, error) => {
+    // Custom error handling
+    console.error('Auth failed:', error);
+    res.status(401).json({
+      success: false,
+      error: 'Custom error message',
+      code: error.code
+    });
+  }
+}));
+```
+
+### Token Refresh Strategy
+
+```javascript
+const { isTokenExpiringSoon, refreshToken } = require('@latanda/auth-middleware');
+
+app.post('/api/refresh-token', (req, res) => {
+  const token = req.headers.authorization?.substring(7);
+
+  if (isTokenExpiringSoon(token, 15)) { // Refresh if expires within 15 min
+    const result = refreshToken(token, process.env.JWT_SECRET);
+    if (result.success) {
+      return res.json({ success: true, token: result.token });
+    }
+  }
+
+  res.json({ success: false, error: 'Token not eligible for refresh' });
+});
+```
+
+### Group Ownership Example (La Tanda use case)
+
+```javascript
+const { canPerformGroupAction } = require('@latanda/auth-middleware');
+
+app.post('/api/groups/:groupId/approve-member', async (req, res) => {
+  const group = await db.query('SELECT * FROM groups WHERE id = $1', [req.params.groupId]);
+
+  // Check if user can approve members in this group
+  if (!canPerformGroupAction(req.user.id, group, req.user.role, 'approve_members')) {
+    return res.status(403).json({ error: 'Not authorized to approve members' });
+  }
+
+  // Approve member...
+});
+```
+
+## Examples
+
+See the `examples/` directory for complete working examples:
+
+- **basic-usage.js** - Simple Express app with JWT auth
+- **role-based-routing.js** - Different routes for different roles
+- **refresh-token-flow.js** - Automatic token refresh implementation
+- **nginx-integration/** - Complete Nginx + Express + PostgreSQL setup
+
+## Testing
+
+```bash
+npm test
+```
+
+## Security Considerations
+
+🔒 **Always use HTTPS in production** - JWT tokens are bearer tokens and should be transmitted securely
+
+🔒 **Store JWT_SECRET securely** - Use environment variables, never commit secrets
+
+🔒 **Set appropriate token expiration** - Balance security (shorter) vs user experience (longer)
+
+🔒 **Implement token refresh** - Allow users to stay logged in without re-authentication
+
+🔒 **Monitor audit logs** - Watch for suspicious authentication patterns
+
+🔒 **Use bcrypt for passwords** - Never store plain-text passwords
+
+## 💰 Support This Project
+
+If this package saves you time and helps secure your application, consider supporting its development!
+
+[![Ko-fi](https://img.shields.io/badge/Ko--fi-Buy%20me%20a%20coffee-ff5e5b?logo=ko-fi&logoColor=white)](https://ko-fi.com/ebanks)
+[![PayPal](https://img.shields.io/badge/PayPal-Donate-00457C?logo=paypal&logoColor=white)](https://paypal.me/narjell)
+[![Open Collective](https://img.shields.io/badge/Open%20Collective-Support-7fadf2?logo=opencollective&logoColor=white)](https://opencollective.com/latanda-auth-middleware)
+
+**Why support?**
+- ✅ Ongoing maintenance and security updates
+- ✅ New features based on community feedback
+- ✅ Comprehensive documentation and examples
+- ✅ Priority support for sponsors
+
+**Other ways to help:**
+- ⭐ Star this repo on GitHub
+- 🐛 Report bugs and suggest features
+- 📝 Improve documentation
+- 🔀 Submit pull requests
+
+### 💼 Need Help?
+
+**Professional services available:**
+- 📧 Implementation consulting
+- 🔧 Custom feature development
+- 🏢 Enterprise support contracts
+
+Contact: ebanksnigel@gmail.com
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+MIT © Narjell Ebanks
+
+## Support
+
+- 📖 [Full Documentation](https://github.com/INDIGOAZUL/latanda-auth-middleware/wiki)
+- 🐛 [Report Issues](https://github.com/INDIGOAZUL/latanda-auth-middleware/issues)
+- 💬 [Discussions](https://github.com/INDIGOAZUL/latanda-auth-middleware/discussions)
+- ⭐ [Star on GitHub](https://github.com/INDIGOAZUL/latanda-auth-middleware)
+
+## Acknowledgments
+
+Extracted from the [La Tanda](https://latanda.online) Web3 platform - a production tanda (ROSCA) system serving real users with real money.
+
+Special thanks to the La Tanda community for battle-testing this authentication system!
+
+---
+
+**Built with ❤️ by the La Tanda team**
+
+[GitHub](https://github.com/INDIGOAZUL/latanda-auth-middleware) • [npm](https://www.npmjs.com/package/@latanda/auth-middleware) • [La Tanda Platform](https://latanda.online)

package/examples/basic-usage.js

@@ -0,0 +1,90 @@
+/**
+ * Basic Usage Example for @latanda/auth-middleware
+ *
+ * This example shows how to set up a simple Express server
+ * with JWT authentication in under 50 lines of code.
+ */
+
+const express = require('express');
+const {
+  createAuthMiddleware,
+  generateToken,
+  requireRole
+} = require('@latanda/auth-middleware');
+
+const app = express();
+app.use(express.json());
+
+// Configuration
+const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key-change-this-in-production';
+
+// ===== PUBLIC ROUTES =====
+
+// Health check (no auth required)
+app.get('/health', (req, res) => {
+  res.json({ status: 'ok', authenticated: false });
+});
+
+// Login endpoint (generates JWT token)
+app.post('/auth/login', (req, res) => {
+  const { email, password } = req.body;
+
+  // TODO: Validate credentials against database
+  // For demo purposes, we'll accept any email/password
+  const user = {
+    id: '123',
+    email,
+    role: 'USER',
+    permissions: []
+  };
+
+  // Generate JWT token
+  const token = generateToken(user, JWT_SECRET, {
+    expiresIn: '8h'
+  });
+
+  res.json({
+    success: true,
+    token,
+    user: { id: user.id, email: user.email, role: user.role }
+  });
+});
+
+// ===== PROTECTED ROUTES =====
+
+// Apply authentication middleware to all /api/* routes
+app.use('/api/*', createAuthMiddleware({
+  jwtSecret: JWT_SECRET
+}));
+
+// Protected profile route (any authenticated user)
+app.get('/api/profile', (req, res) => {
+  res.json({
+    success: true,
+    user: req.user // Automatically populated by middleware
+  });
+});
+
+// Protected route for ADMIN only
+app.get('/api/admin/users', requireRole('ADMIN'), (req, res) => {
+  res.json({
+    success: true,
+    message: 'Admin access granted',
+    users: [] // TODO: Fetch from database
+  });
+});
+
+// ===== START SERVER =====
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`✅ Server running on http://localhost:${PORT}`);
+  console.log(`\n📝 Try these commands:\n`);
+  console.log(`# 1. Login to get token`);
+  console.log(`curl -X POST http://localhost:${PORT}/auth/login \\`);
+  console.log(`  -H "Content-Type: application/json" \\`);
+  console.log(`  -d '{"email":"test@example.com","password":"test123"}'\n`);
+  console.log(`# 2. Use token to access protected route`);
+  console.log(`curl http://localhost:${PORT}/api/profile \\`);
+  console.log(`  -H "Authorization: Bearer <TOKEN_FROM_STEP_1>"\n`);
+});

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@latanda/auth-middleware",
+  "version": "1.0.1",
+  "description": "Production-ready JWT authentication middleware for Node.js + PostgreSQL + Nginx. Battle-tested with 30+ users at latanda.online",
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "sql",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "MIGRATION.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "jest",
+    "example": "node examples/basic-usage.js"
+  },
+  "keywords": [
+    "authentication",
+    "jwt",
+    "postgresql",
+    "nginx",
+    "sessions",
+    "middleware",
+    "express",
+    "security",
+    "rbac",
+    "role-based-access-control",
+    "latanda",
+    "production-ready"
+  ],
+  "author": "Narjell Ebanks <ebanksnigel@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/INDIGOAZUL/latanda-auth-middleware.git"
+  },
+  "bugs": {
+    "url": "https://github.com/INDIGOAZUL/latanda-auth-middleware/issues"
+  },
+  "homepage": "https://github.com/INDIGOAZUL/latanda-auth-middleware#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "jsonwebtoken": "^9.0.2",
+    "bcrypt": "^5.1.1",
+    "pg": "^8.11.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/jsonwebtoken": "^9.0.5",
+    "@types/bcrypt": "^5.0.2",
+    "@types/pg": "^8.10.9",
+    "typescript": "^5.3.0",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.11"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0 || ^5.0.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}