Stack Auth is a managed user authentication solution. It is developer-friendly and fully open-source (licensed under MIT and AGPL).

Stack Auth gets you started in just five minutes, after which you'll be ready to use all of its features as you grow your project. Our managed service is completely optional and you can export your user data and self-host, for free, at any time.

We support Next.js, React, and JavaScript frontends, along with any backend that can use our REST API. Check out our setup guide to get started.

Below is a detailed documentation for the Open-Auth application, inspired by the official documentation of Stack Auth (https://docs.stack-auth.com/next/overview). This documentation is structured similarly but tailored for the new name Open-Auth and includes all necessary details for understanding, setting up, and using the application.

Open-Auth is an open-source, modular, and scalable authentication system designed to simplify user authentication and authorization in modern web applications. Built with Node.js, Express.js, and MongoDB, Open-Auth provides a robust foundation for implementing secure authentication workflows, including user registration, login, role-based access control, and JWT-based authentication.

Open-Auth is designed to be:

• Secure: Uses bcrypt for password hashing and JWT for stateless authentication.
• Modular: Easy to integrate into existing projects or use as a standalone service.
• Scalable: Built with scalability in mind, making it suitable for small to large applications.
• Customizable: Allows developers to extend functionality and tailor it to their needs.

• User Authentication:
  • User registration, login, and logout.
  • Secure password storage using bcrypt.
• JWT-Based Authentication:
  • Stateless authentication using JSON Web Tokens (JWT).
  • Configurable token expiration.
• Role-Based Access Control (RBAC):
  • Define user roles and permissions.
  • Restrict access to specific routes based on roles.
• API Endpoints:
  • RESTful API for authentication and user management.
• Database Integration:
  • MongoDB for storing user data.
  • Mongoose for object data modeling.
• Environment Configuration:
  • Uses .env files for sensitive data and configuration.
• Validation:
  • Input validation for user registration and login.
• Error Handling:
  • Centralized error handling for consistent API responses.

Before using Open-Auth, ensure you have the following installed:

• Node.js (v14 or higher)
• MongoDB (local or cloud instance)
• Git (optional, for cloning the repository)

1. Clone the Repository:

   git clone https://github.com/your-repo/open-auth.git
   cd open-auth

2. Install Dependencies:

   npm install

3. Set Up Environment Variables:

   • Create a .env file in the root directory.
   • Add the following variables:

     PORT=3000
     MONGO_URI=mongodb://localhost:27017/open-auth
     JWT_SECRET=your_jwt_secret_key
     JWT_EXPIRES_IN=1d

4. Start the Server:

   npm start

   The server will start running on http://localhost:3000.

• Endpoint: POST /api/auth/register
• Request Body:

  {
    "name": "John Doe",
    "email": "[email protected]",
    "password": "password123"
  }

• Response:

  {
    "success": true,
    "token": "your_jwt_token"
  }

• Endpoint: POST /api/auth/login
• Request Body:

  {
    "email": "[email protected]",
    "password": "password123"
  }

• Response:

  {
    "success": true,
    "token": "your_jwt_token"
  }

• Endpoint: POST /api/auth/logout
• Headers:

  Authorization: Bearer <your_jwt_token>

• Response:

  {
    "success": true,
    "message": "Logged out successfully"
  }

• Endpoint: GET /api/users/me
• Headers:

  Authorization: Bearer <your_jwt_token>

• Response:

  {
    "success": true,
    "data": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  }

• Endpoint: PUT /api/users/me
• Headers:

  Authorization: Bearer <your_jwt_token>

• Request Body:

  {
    "name": "Jane Doe"
  }

• Response:

  {
    "success": true,
    "data": {
      "name": "Jane Doe",
      "email": "[email protected]"
    }
  }

• Endpoint: DELETE /api/users/me
• Headers:

  Authorization: Bearer <your_jwt_token>

• Response:

  {
    "success": true,
    "message": "User deleted successfully"
  }

Open-Auth uses a centralized error handling mechanism. All errors are returned in the following format:

{
  "success": false,
  "message": "Error message",
  "error": {
    "code": 400,
    "details": "Additional error details"
  }
}

• 400: Bad Request (e.g., invalid input).
• 401: Unauthorized (e.g., missing or invalid token).
• 404: Not Found (e.g., resource not found).
• 500: Internal Server Error (e.g., server-side issue).

Open-Auth uses environment variables for configuration. Below are the key variables:

Open-Auth is designed to be modular. You can extend its functionality by:

1. Adding new routes in the routes directory.
2. Creating new controllers in the controllers directory.
3. Defining new models in the models directory.

To implement role-based access control (RBAC):

1. Update the User model to include a role field.
2. Create middleware to check user roles before granting access to specific routes.

We welcome contributions! Here’s how you can help:

1. Fork the repository.
2. Create a new branch for your feature or bugfix.
3. Commit your changes and push to the branch.
4. Submit a pull request.

Please ensure your code follows the project’s coding standards and includes appropriate tests.

Open-Auth is licensed under the MIT License. See the LICENSE file for details.

For questions, issues, or feature requests, please open an issue on the GitHub repository.

• Inspired by modern authentication best practices.
• Built with the support of the open-source community.

This documentation provides a comprehensive guide to using and customizing Open-Auth. For more details, refer to the official documentation or explore the source code.