{"id":26924348,"url":"https://github.com/chappy202/headless-auth-service","last_synced_at":"2025-04-02T01:53:57.997Z","repository":{"id":247575511,"uuid":"826247920","full_name":"Chappy202/headless-auth-service","owner":"Chappy202","description":"A robust, scalable, and secure authentication service built with NestJS, Drizzle ORM, and Passport.js. This headless service provides a complete authentication and authorization solution that can be easily integrated with any frontend compatible with JWT.","archived":false,"fork":false,"pushed_at":"2025-03-01T20:10:48.000Z","size":1059,"stargazers_count":5,"open_issues_count":6,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-20T03:02:14.689Z","etag":null,"topics":["auth","drizzle","headless","jwt","nestjs","passport"],"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/Chappy202.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2024-07-09T10:45:45.000Z","updated_at":"2025-02-16T01:59:03.000Z","dependencies_parsed_at":"2024-07-21T18:15:29.487Z","dependency_job_id":"56059c35-75ae-4ef4-b1da-84b56bfa7210","html_url":"https://github.com/Chappy202/headless-auth-service","commit_stats":null,"previous_names":["chappy202/headless-auth-service"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chappy202%2Fheadless-auth-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chappy202%2Fheadless-auth-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chappy202%2Fheadless-auth-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Chappy202%2Fheadless-auth-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Chappy202","download_url":"https://codeload.github.com/Chappy202/headless-auth-service/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246741123,"owners_count":20826064,"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":["auth","drizzle","headless","jwt","nestjs","passport"],"created_at":"2025-04-02T01:53:57.499Z","updated_at":"2025-04-02T01:53:57.990Z","avatar_url":"https://github.com/Chappy202.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Headless Auth Service\n\nA robust, scalable, and secure authentication service built with NestJS, Drizzle ORM, and Passport.js. This headless service provides a complete authentication and authorization solution that can be easily integrated with any frontend compatible with JWT.\n\n## Features\n\n- User authentication (username/email and password)\n- JWT-based authentication\n- Refresh token functionality\n- Multi-Factor Authentication (MFA) support\n- Password reset functionality\n- Email verification\n- User session tracking\n- IP tracking for login history\n- Role-Based Access Control (RBAC)\n- Admin module for user management\n- Token blacklisting for security\n- Microservice-ready for easy integration with other APIs\n\n## Tech Stack\n\n- [NestJS](https://nestjs.com/) - A progressive Node.js framework for building efficient and scalable server-side applications.\n- [Drizzle ORM](https://orm.drizzle.team/) - A lightweight and performant TypeScript ORM.\n- [Passport](http://www.passportjs.org/) - Simple, unobtrusive authentication for Node.js.\n- [PostgreSQL](https://www.postgresql.org/) - Open source object-relational database system.\n\n## Project Structure\n\n```\nsrc/\n├── common/\n│ ├── decorators/\n│ ├── dto/\n│ ├── filters/\n│ ├── guards/\n│ └── utils/\n├── infrastructure/\n│ ├── cache/\n│ └── database/\n├── modules/\n│ ├── admin/\n│ ├── api-keys/\n│ ├── auth/\n│ ├── email/\n│ ├── health/\n│ ├── permissions/\n│ ├── resources/\n│ └── users/\n├── app.module.ts\n└── main.ts\n```\n\n## Installation and Setup\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/yourusername/headless-auth-service.git\ncd headless-auth-service\n```\n\n2. Install dependencies:\n\n```bash\nyarn install\n```\n\n3. Set up environment variables:\n   Create a `.env` file in the root directory and add the following variables:\n\n   ```\n   DATABASE_URL=postgresql://username:password@localhost:5432/your_database\n   JWT_SECRET=your_jwt_secret\n   REFRESH_TOKEN_SECRET=your_refresh_token_secret\n   JWT_EXPIRATION=2h\n   JWT_REFRESH_EXPIRATION=7d\n   VERIFICATION_TOKEN_EXPIRATION=24h\n   PASSWORD_RESET_TOKEN_EXPIRATION=1h\n   SALT_ROUNDS=10\n   EMAIL_VERIFICATION_URL=http://localhost:3000/verify-email\n   RESET_PASSWORD_URL=http://localhost:3000/reset-password\n   FROM_EMAIL=noreply@youremail.com\n   MFA_APP_NAME=YourAuthApp\n   ```\n\n4. Start docker containers:\n\n```bash\ndocker compose up -d\n```\n\n5. Start the application:\n\n```bash\nyarn start:dev\n```\n\n## API Endpoints\n\n### Authentication\n\n- `POST /v1/auth/register` - Register a new user\n- `POST /v1/auth/login` - Authenticate a user\n- `POST /v1/auth/logout` - Logout (blacklist token)\n\n### User Management\n\n- `GET /v1/users/profile` - Get user profile\n- `PUT /v1/users/profile` - Update user profile\n\n### Admin\n\n- `GET /v1/admin/users` - Get all users\n- `POST /v1/admin/users` - Create a new user\n- `GET /v1/admin/users/:id` - Get a user by id\n- `PUT /v1/admin/users/:id` - Update a user\n- `DELETE /v1/admin/users/:id` - Delete a user\n- `POST /v1/admin/users/:userId/permissions/:permissionId` - Assign a permission to a user\n- `GET /v1/admin/users/:userId/permissions` - Get user permissions\n- `POST /v1/admin/resources` - Create a new resource\n- `GET /v1/admin/resources` - Get all resources\n- `POST /v1/admin/permissions` - Create a new permission\n- `GET /v1/admin/permissions` - Get all permissions\n\n### API Keys\n\n- `POST /v1/api-keys` - Create a new API key\n- `GET /v1/api-keys` - List all API keys\n- `DELETE /v1/api-keys/:id` - Revoke an API key\n\n### Permissions\n\n- `POST /v1/permissions` - Create a new permission\n- `GET /v1/permissions` - Get all permissions\n- `GET /v1/permissions/:id` - Get a permission by id\n- `POST /v1/permissions/assign-to-role/:permissionId/:roleId` - Assign a permission to a role\n- `POST /v1/permissions/assign-to-user/:permissionId/:userId` - Assign a permission to a user\n\n### Resources\n\n- `POST /v1/resources` - Create a new resource\n- `GET /v1/resources` - Get all resources\n- `GET /v1/resources/:id` - Get a resource by id\n- `GET /v1/resources/:id/permissions` - Get permissions for a resource\n\n### Email\n\n- `POST /v1/email/send` - Send an email\n\n### Health Check\n\n- `GET /v1/health` - Check the health of the application\n\n## API Documentation\n\nDetailed API documentation is available via Swagger UI. After starting the application, you can access the Swagger documentation at:\n\n`http://localhost:3000/api`\n\nThis interactive documentation provides a comprehensive overview of all available endpoints, request/response schemas, and allows you to test the API directly from the browser.\n\n### Available Endpoints\n\n- Authentication: `/v1/auth`\n- User Management: `/v1/users`\n- Admin: `/v1/admin`\n- API Keys: `/v1/api-keys`\n- Permissions: `/v1/permissions`\n- Resources: `/v1/resources`\n- Email: `/v1/email`\n- Health Check: `/v1/health`\n\n### Swagger JSON\n\nIf you need the raw Swagger JSON for integration with other tools, you can access it at:\n\n`http://localhost:3000/api-json`\n\n### Authentication\n\nThe API uses JWT for authentication. Include the JWT token in the Authorization header of your requests:\n\n```\nAuthorization: Bearer \u003cyour_jwt_token\u003e\n```\n\nFor endpoints that require specific permissions, make sure the authenticated user has the necessary roles or permissions assigned.\n\n### Rate Limiting\n\nThe API implements rate limiting to prevent abuse. Please check the response headers for rate limit information:\n\n- `X-RateLimit-Limit`: The maximum number of requests allowed in a time window\n- `X-RateLimit-Remaining`: The number of requests remaining in the current time window\n- `X-RateLimit-Reset`: The time at which the current rate limit window resets\n\n### Versioning\n\nThe API is versioned. The current version is v1, which is reflected in the endpoint URLs (e.g., `/v1/auth/login`).\n\n### Error Responses\n\nThe API uses standard HTTP response codes. In case of an error, you will receive a JSON response with an `error` field describing the issue.\n\nExample:\n\n```json\n{\n  \"statusCode\": 400,\n  \"message\": \"Bad Request\",\n  \"error\": \"Invalid input data\"\n}\n```\n\nFor the most up-to-date and detailed information about the API, always refer to the Swagger documentation.\n\n## Roadmap\n\n### Phase 1: Core Functionality and Security Enhancements\n\n- [x] Implement consistent type safety and DTO definitions\n- [x] Enhance API documentation\n- [x] Implement consistent use of guards and decorators\n- [x] Improve database security\n- [ ] Refactor Admin module\n- [ ] Enhance Users module\n- [ ] Restructure Authentication module\n- [ ] Implement logging system\n\n### Phase 2: Advanced Authentication and Authorization\n\n- [ ] Develop extensible authentication recipe system\n  - [ ] Implement social login integrations (Google, GitHub, etc.)\n  - [ ] Add support for passwordless authentication methods\n  - [ ] Implement biometric authentication support\n  - [ ] Create a plugin system for easily adding new authentication methods\n- [ ] Enhance API Key system\n  - [ ] Implement usage tracking and analytics for API keys\n  - [ ] Add rate limiting and quota management for API keys\n- [ ] Implement OAuth 2.0 provider functionality\n- [ ] Advanced role and permission management\n  - [ ] Implement hierarchical roles\n  - [ ] Add support for custom permissions\n  - [ ] Create tools for bulk permission management\n\n### Phase 3: Multi-tenancy and Subscription Management\n\n- [ ] Implement multi-tenancy support (optional feature)\n  - [ ] Create company/organization management system\n  - [ ] Develop user-company association functionality\n  - [ ] Implement company-specific roles and permissions\n- [ ] Add subscription and licensing features\n  - [ ] Create subscription plan management system\n  - [ ] Implement license generation and validation\n  - [ ] Develop usage tracking and billing report generation\n- [ ] Enhance admin functionality for multi-tenancy\n- [ ] Implement user meta management\n\n### Phase 4: Advanced Features and Scalability\n\n- [ ] Implement feature toggle system\n- [ ] Enhance metrics and tracking\n- [ ] Improve scalability\n  - [ ] Implement caching mechanisms\n  - [ ] Optimize database queries and indexes\n  - [ ] Implement a message queue for asynchronous tasks\n- [ ] Develop advanced session management\n\n### Phase 5: Microservice Architecture and Deployment Optimization\n\n- [ ] Refactor modules for microservice deployment\n- [ ] Optimize deployment process\n  - [ ] Containerize all services using Docker\n  - [ ] Create Kubernetes deployment configurations\n  - [ ] Implement blue-green deployment strategy\n- [ ] Enhance system observability\n  - [ ] Implement distributed tracing\n  - [ ] Create centralized logging and monitoring system\n  - [ ] Develop health check and self-healing mechanisms\n\n## Contributing\n\nWe welcome contributions to the Headless Auth Service! This section will guide you through the process of contributing to our project.\n\n### Getting Started\n\n1. Fork the repository on GitHub.\n2. Clone your forked repository to your local machine.\n3. Install dependencies with `yarn install`.\n4. Create a new branch for your feature or bug fix.\n\n### Development Workflow\n\n1. Make your changes in your feature branch.\n2. Follow the coding standards and best practices outlined in this document.\n3. Write or update tests as necessary.\n4. Run tests with `yarn test` to ensure all tests pass.\n5. Run the linter with `yarn lint` to check for any style issues.\n\n### Commit Messages\n\nWe use conventional commits to standardize our commit messages. This helps us generate meaningful changelogs and version numbers. Please format your commit messages as follows:\n\n```\n\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e\n\n\u003cbody\u003e\n\u003cfooter\u003e\n```\n\nTypes include:\n\n- feat: A new feature\n- fix: A bug fix\n- docs: Documentation only changes\n- style: Changes that do not affect the meaning of the code (white-space, formatting, etc)\n- refactor: A code change that neither fixes a bug nor adds a feature\n- perf: A code change that improves performance\n- test: Adding missing tests or correcting existing tests\n- build: Changes that affect the build system or external dependencies\n- ci: Changes to our CI configuration files and scripts\n\nExample:\n\n```\nfeat(auth): add support for API key authentication\n\nThis commit adds a new authentication method using API keys.\n\nCloses #123\n```\n\n### Pull Requests\n\n1. Update your feature branch with the latest changes from the main branch.\n2. Push your branch to your fork on GitHub.\n3. Open a pull request against the main repository.\n4. Ensure the PR description clearly describes the problem and solution. Include the relevant issue number if applicable.\n5. Request a review from one of the project maintainers.\n\n### Code Style\n\n- We use ESLint to enforce code style. Run `yarn lint` before committing.\n- Write clear, readable, and well-documented code.\n- Follow the principle of single responsibility for functions and classes.\n- Use meaningful variable and function names.\n\n### Testing\n\n- Write unit tests for new features and bug fixes.\n- Ensure all tests pass before submitting a pull request.\n- Aim for high test coverage, especially for critical components.\n\n### Documentation\n\n- Update the README.md file if you're adding or changing functionality.\n- Add JSDoc comments to functions and classes.\n- Update API documentation if you're modifying endpoints.\n\n### Versioning\n\nWe use Semantic Versioning (SemVer) for version numbers. The version will be automatically bumped based on your commit messages when a new release is created.\nThank you for contributing to the Headless Auth Service! Your efforts help make this project better for everyone.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchappy202%2Fheadless-auth-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchappy202%2Fheadless-auth-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchappy202%2Fheadless-auth-service/lists"}