{"id":28318712,"url":"https://github.com/luismr/heimdall","last_synced_at":"2026-04-09T22:56:40.096Z","repository":{"id":294985358,"uuid":"988687351","full_name":"luismr/heimdall","owner":"luismr","description":"A comprehensive authentication and authorization ecosystem for Node.js applications, inspired by the Norse god Heimdall - the all-seeing guardian who protects the rainbow bridge connecting different realms.","archived":false,"fork":false,"pushed_at":"2025-06-19T16:53:07.000Z","size":451,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-19T17:43:27.506Z","etag":null,"topics":["aws","dynamodb","express","jwt","jwt-authentication","node","serverless","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luismr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-22T23:34:38.000Z","updated_at":"2025-05-28T13:27:49.000Z","dependencies_parsed_at":"2025-05-23T02:31:12.383Z","dependency_job_id":"cc8aa468-314b-456d-ae51-0f7d1f4eb83f","html_url":"https://github.com/luismr/heimdall","commit_stats":null,"previous_names":["luismr/heimdall"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/luismr/heimdall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luismr%2Fheimdall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luismr%2Fheimdall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luismr%2Fheimdall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luismr%2Fheimdall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luismr","download_url":"https://codeload.github.com/luismr/heimdall/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luismr%2Fheimdall/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261733842,"owners_count":23201734,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","dynamodb","express","jwt","jwt-authentication","node","serverless","typescript"],"created_at":"2025-05-25T08:11:31.352Z","updated_at":"2026-04-09T22:56:35.045Z","avatar_url":"https://github.com/luismr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heimdall - Guardian of Your API Realms\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.8.x-blue?logo=typescript)](https://www.typescriptlang.org/)\n[![Express](https://img.shields.io/badge/Express-4.18.x-green?logo=express)](https://expressjs.com/)\n[![Node.js](https://img.shields.io/badge/Node.js-20.x-green?logo=node.js)](https://nodejs.org/)\n[![AWS DynamoDB](https://img.shields.io/badge/AWS-DynamoDB-orange?logo=amazon-aws)](https://aws.amazon.com/dynamodb/)\n[![Jest](https://img.shields.io/badge/Jest-29.x-red?logo=jest)](https://jestjs.io/)\n\n\u003e *\"I am Heimdall, guardian of the Bifröst, protector of the realms.\"*\n\nA comprehensive authentication and authorization ecosystem for Node.js applications, inspired by the Norse god Heimdall - the all-seeing guardian who protects the rainbow bridge connecting different realms.\n\n## 🌈 Why Heimdall?\n\nHeimdall is a powerful Asgardian warrior who serves as the guardian of the Bifröst, the rainbow bridge that connects Asgard to the other realms. Just as Heimdall watches over all who pass through the bridge with his all-seeing eyes, our Heimdall ecosystem guards your APIs and applications, ensuring only authorized users can access your digital realms.\n\n### The Guardian's Powers:\n- 👁️ **All-Seeing**: Monitors all authentication attempts across your application\n- 🛡️ **Guardian**: Protects your API endpoints with robust security\n- 🌉 **Bridge Builder**: Seamlessly connects different parts of your application\n- ⚡ **Swift Response**: Lightning-fast authentication and authorization\n- 🔐 **Keeper of Keys**: Manages JWT tokens and user sessions securely\n\n## 🏗️ Architecture Overview\n\nThe Heimdall ecosystem consists of three main components that work together to provide complete authentication and authorization:\n\n```\n┌──────────────────────────────────────────────────────────────────────────────────────┐\n│                              Heimdall Ecosystem                                      │\n├──────────────────────────────────────────────────────────────────────────────────────┤\n│                                                                                      │\n│  ┌─────────────────────┐    ┌───────────────────────────┐    ┌───────────────────┐   │\n│  │  Heimdall Server    │◄──►│ Heimdall Middleware       │◄──►│ Heimdall Client   │   │\n│  │  (API Backend)      │    │ (Express.js Library)      │    │ (TypeScript SDK)  │   │\n│  │                     │    │                           │    │                   │   │\n│  │ • User Management   │    │ • JWT Validation          │    │ • API Client      │   │\n│  │ • Authentication    │    │ • Role-Based Access       │    │ • Token Mgmt      │   │\n│  │ • Token Generation  │    │ • Request Protection      │    │ • Type Safety     │   │\n│  │ • Admin Operations  │    │ • Easy Integration        │    │ • Error Handling  │   │\n│  │ • DDD Architecture  │    │ • TypeScript Support      │    │ • Framework Agno. │   │\n│  │ • DynamoDB Storage  │    │                           │    │ • Axios Based     │   │\n│  └─────────────────────┘    └───────────────────────────┘    └───────────────────┘   │\n│                                                                                      │\n└──────────────────────────────────────────────────────────────────────────────────────┘\n```\n\n## 📦 Components\n\n### 🖥️ [Heimdall Server](./heimdall-server/)\n[![npm version](https://badge.fury.io/js/%40luismr%2Fheimdall-api.svg)](https://badge.fury.io/js/%40luismr%2Fheimdall-api)\n\nThe central authentication server built with Domain-Driven Design principles.\n\n**Features:**\n- 🔐 Complete authentication API (signup, login, logout)\n- 👥 User management with role-based access control\n- 🏗️ Clean DDD architecture with separated concerns\n- 🗄️ AWS DynamoDB integration for scalable storage\n- ☁️ Serverless-ready deployment with AWS Lambda\n- 🧪 90%+ test coverage with comprehensive testing\n- 🛡️ Secure password hashing with bcrypt\n- 🎫 JWT token management with refresh tokens\n\n```bash\ncd heimdall-server\nnpm install\nnpm run dev\n```\n\n### 🛡️ [Heimdall Middleware Express](./heimdall-middleware-express/)\n[![npm version](https://badge.fury.io/js/%40luismr%2Fheimdall-middleware-express.svg)](https://badge.fury.io/js/%40luismr%2Fheimdall-middleware-express)\n\nLightweight Express.js middleware for protecting your API endpoints.\n\n**Features:**\n- ⚡ Easy Express.js integration\n- 🔍 JWT token validation\n- 👮 Role-based route protection\n- 📦 TypeScript definitions included\n- 🚀 Zero configuration setup\n- 🔧 Utility functions for flexible access control\n\n```bash\nnpm install @luismr/heimdall-middleware-express\n```\n\n### 🔧 [Heimdall Client](./heimdall-client/)\n[![npm version](https://badge.fury.io/js/%40luismr%2Fheimdall-client.svg)](https://badge.fury.io/js/%40luismr%2Fheimdall-client)\n\nTypeScript client library for consuming Heimdall authentication API endpoints.\n\n**Features:**\n- 🎯 Type-safe API client with full TypeScript support\n- 🔄 Automatic authentication context management\n- ⚡ Built on Axios with request/response interceptors\n- 🛡️ Comprehensive error handling with custom error types\n- 🔐 JWT token management and auto-renewal\n- 🏗️ Framework-agnostic (React, Vue, Node.js, etc.)\n- 🧪 100% test coverage with comprehensive testing\n- 📚 Rich examples and documentation\n\n```bash\nnpm install @luismr/heimdall-client\n```\n\n## 🚀 Quick Start\n\n### 1. Set Up the Authentication Server\n\n```bash\n# Clone and setup the server\ngit clone https://github.com/luismr/heimdall.git\ncd heimdall/heimdall-server\nnpm install\nnpm run dev\n```\n\n### 2. Install and Use the Client\n\n```bash\n# In your application project\nnpm install @luismr/heimdall-client\n```\n\n```typescript\nimport { HeimdallClient } from '@luismr/heimdall-client';\n\nconst client = new HeimdallClient({\n  baseURL: 'http://localhost:4000/api'\n});\n\n// Register a user\nconst user = await client.signup({\n  username: 'johndoe',\n  password: 'securepassword123'\n});\n\n// Login and get tokens\nconst loginResult = await client.login({\n  username: 'johndoe',\n  password: 'securepassword123'\n});\n\n// Client automatically manages authentication context\nconsole.log(client.isAuthenticated()); // true\n```\n\n### 3. Protect Your API Routes\n\n```bash\n# In your Express.js API project\nnpm install @luismr/heimdall-middleware-express\n```\n\n```typescript\nimport express from 'express';\nimport { requireAuth, requireAdmin, AuthRequest } from '@luismr/heimdall-middleware-express';\n\nconst app = express();\n\n// Protected route\napp.get('/profile', requireAuth, (req: AuthRequest, res) =\u003e {\n  res.json({ message: 'Welcome to your profile!', user: req.user });\n});\n\n// Admin-only route\napp.get('/admin/dashboard', requireAdmin, (req: AuthRequest, res) =\u003e {\n  res.json({ message: 'Admin dashboard access granted!' });\n});\n\napp.listen(3000);\n```\n\n### 4. Complete Integration Example\n\n```typescript\nimport { HeimdallClient } from '@luismr/heimdall-client';\n\nconst client = new HeimdallClient({\n  baseURL: 'http://localhost:4000/api'\n});\n\n// Register, login, and make authenticated requests\ntry {\n  // Register a user\n  await client.signup({\n    username: 'johndoe',\n    password: 'securepassword123'\n  });\n\n  // Login (automatically sets auth context)\n  const loginResult = await client.login({\n    username: 'johndoe',\n    password: 'securepassword123'\n  });\n\n  // Now make requests to your protected API\n  const response = await fetch('http://localhost:3000/profile', {\n    headers: {\n      'Authorization': `Bearer ${loginResult.accessToken}`\n    }\n  });\n\n  const profile = await response.json();\n  console.log(profile);\n\n  // Logout when done\n  await client.logout({\n    refreshToken: loginResult.refreshToken\n  });\n} catch (error) {\n  console.error('Authentication error:', error);\n}\n```\n\n## 🌟 Use Cases\n\n### Enterprise Applications\n- **Multi-service Authentication**: Central auth server with distributed middleware\n- **Microservices Security**: Each service protected with Heimdall middleware\n- **Admin Dashboards**: Role-based access for administrative functions\n- **Client Applications**: Type-safe authentication with Heimdall client\n\n### SaaS Platforms\n- **User Management**: Complete user lifecycle with roles and permissions\n- **API Protection**: Secure your REST APIs with minimal configuration\n- **Scalable Architecture**: DynamoDB backend scales with your needs\n- **Frontend Integration**: Seamless authentication for web and mobile apps\n\n### Startup MVPs\n- **Rapid Development**: Get authentication working in minutes\n- **Security Best Practices**: Production-ready security out of the box\n- **Cost Effective**: Serverless deployment reduces infrastructure costs\n- **Developer Experience**: Type-safe client with excellent DX\n\n## 🔧 Configuration\n\n### Environment Variables\n\n**Heimdall Server (.env):**\n```env\n# Application Configuration\nJWT_SECRET=your-super-secret-jwt-key\nUSERS_TABLE=HeimdallUsers\nPORT=4000\nNODE_ENV=development\n\n# AWS Credentials (required for DynamoDB)\nAWS_ACCESS_KEY_ID=your-access-key-id\nAWS_SECRET_ACCESS_KEY=your-secret-access-key\nAWS_REGION=us-east-1\n```\n\n**Your Application (.env):**\n```env\nJWT_SECRET=your-super-secret-jwt-key  # Must match server\nHEIMDALL_API_URL=http://localhost:4000/api\n```\n\n\u003e 📚 **AWS Configuration**: For detailed AWS credentials setup, see [AWS Environment Variables Documentation](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html)\n\n## 📚 Documentation\n\n| Component | Description | Documentation |\n|-----------|-------------|---------------|\n| **🖥️ Server** | Authentication API Backend | [Server README](./heimdall-server/README.md) |\n| **🛡️ Middleware** | Express.js Protection Library | [Middleware README](./heimdall-middleware-express/README.md) |\n| **🔧 Client** | TypeScript API Client Library | [Client README](./heimdall-client/README.md) |\n| **🚀 Quick Start** | Step-by-step Integration Guide | [Quick Start Guide](./heimdall-middleware-express/QUICKSTART.md) |\n| **🔧 Development** | Build and Development Setup | [Build Guide](./heimdall-middleware-express/BUILD.md) |\n| **🤝 Contributing** | Contribution Guidelines | [Contributing Guide](./heimdall-middleware-express/CONTRIBUTE.md) |\n\n## 🧪 Testing\n\nAll components include comprehensive test suites:\n\n```bash\n# Test the server\ncd heimdall-server\nnpm run test:coverage\n\n# Test the middleware\ncd heimdall-middleware-express\nnpm run test:coverage\n\n# Test the client\ncd heimdall-client\nnpm run test:coverage\n```\n\n**Combined Coverage:**\n- **Server**: 90%+ coverage across all DDD layers\n- **Middleware**: 100% coverage for authentication logic\n- **Client**: 100% coverage for API client functionality\n- **Integration**: Full end-to-end authentication flow testing\n\n## 🚀 Deployment\n\n### Production Deployment\n\n**Server Deployment (AWS Lambda):**\n```bash\ncd heimdall-server\nnpm run serverless:deploy -- --stage prod\n```\n\n**Middleware Distribution (NPM):**\n```bash\ncd heimdall-middleware-express\nnpm publish\n```\n\n**Client Distribution (NPM):**\n```bash\ncd heimdall-client\nnpm run build\nnpm publish\n```\n\n### Docker Deployment (Alternative)\n\n```dockerfile\n# Dockerfile for heimdall-server\nFROM node:20-alpine\nWORKDIR /app\nCOPY package*.json ./\nRUN npm ci --only=production\nCOPY dist ./dist\nEXPOSE 4000\nCMD [\"npm\", \"start\"]\n```\n\n## 🔒 Security Features\n\n- **🔐 JWT Authentication**: Industry-standard token-based authentication\n- **🧂 Password Hashing**: bcrypt with salt for secure password storage\n- **🎫 Refresh Tokens**: Secure token rotation and session management\n- **👮 Role-Based Access**: Fine-grained permission control\n- **🛡️ CORS Protection**: Cross-origin request security\n- **🚫 Brute Force Protection**: Rate limiting and security monitoring\n- **📝 Audit Logging**: Track authentication and authorization events\n- **🔒 Type Safety**: Client-side type safety prevents common security issues\n\n## 🤝 Contributing\n\nWe welcome contributions to the Heimdall ecosystem! Please see our contributing guidelines:\n\n1. **Fork** the repository\n2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)\n3. **Commit** your changes (`git commit -m 'Add some amazing feature'`)\n4. **Push** to the branch (`git push origin feature/amazing-feature`)\n5. **Open** a Pull Request\n\n### Development Standards\n- TypeScript for type safety\n- Jest for comprehensive testing\n- ESLint for code quality\n- Conventional commits for clear history\n- Documentation for all features\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.\n\n## 🙏 Acknowledgments\n\n- **Norse Mythology**: For the inspiration behind Heimdall, the guardian of realms\n- **Open Source Community**: For the amazing tools and libraries that make this possible\n- **Contributors**: Everyone who helps make Heimdall more secure and reliable\n\n---\n\n## 🌈 The Bifröst Bridge to Secure APIs\n\nJust as Heimdall's watchful eyes protect all Nine Realms, let our Heimdall ecosystem be the guardian of your digital domains. Build secure, scalable, and maintainable authentication systems with the power of the gods.\n\n**Ready to guard your API realms? Choose your path:**\n\n🖥️ **[Start with the Server](./heimdall-server/)** - Set up the authentication backend\n🔧 **[Consume with Client](./heimdall-client/)** - Connect your applications securely\n🛡️ **[Protect with Middleware](./heimdall-middleware-express/)** - Secure your Express.js routes\n🚀 **[Quick Integration](./heimdall-middleware-express/QUICKSTART.md)** - Get started in minutes\n\n---\n\n***\"Until the end of days, I will watch over your APIs.\"*** - Heimdall Guardian ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluismr%2Fheimdall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluismr%2Fheimdall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluismr%2Fheimdall/lists"}