{"id":15292405,"url":"https://github.com/ribeirogab/nodejs-api-auth","last_synced_at":"2026-04-12T12:50:48.706Z","repository":{"id":256673601,"uuid":"856092273","full_name":"ribeirogab/nodejs-api-auth","owner":"ribeirogab","description":"Boilerplate API for user creation and authentication.","archived":false,"fork":false,"pushed_at":"2024-09-22T21:06:55.000Z","size":416,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-19T16:48:52.273Z","etag":null,"topics":["api","aws","boilerplate","dynamodb","lambda","nodejs","terraform"],"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/ribeirogab.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}},"created_at":"2024-09-12T01:18:42.000Z","updated_at":"2025-02-13T14:47:28.000Z","dependencies_parsed_at":"2024-09-30T16:17:37.016Z","dependency_job_id":"1bd8312e-112f-471d-a03d-df21d606b8cc","html_url":"https://github.com/ribeirogab/nodejs-api-auth","commit_stats":null,"previous_names":["ribeirogab/nodejs-api-authentication","ribeirogab/nodejs-api-auth"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fnodejs-api-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fnodejs-api-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fnodejs-api-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ribeirogab%2Fnodejs-api-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ribeirogab","download_url":"https://codeload.github.com/ribeirogab/nodejs-api-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245249230,"owners_count":20584497,"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":["api","aws","boilerplate","dynamodb","lambda","nodejs","terraform"],"created_at":"2024-09-30T16:17:43.173Z","updated_at":"2026-04-12T12:50:43.681Z","avatar_url":"https://github.com/ribeirogab.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# User Authentication API Boilerplate\n\nThis project is a boilerplate for an API that handles user creation and authentication. It provides a basic set of functionalities and endpoints to manage users and authentication tokens, built with Node.js and TypeScript.\n\n## Features\n\n- **User Registration:** Register new users with basic information.\n- **Email Confirmation:** Verify user registration via a confirmation code.\n- **User Login:** Authenticate users and issue JWT tokens.\n- **Token Refresh:** Refresh JWT tokens using a refresh token.\n- **User Logout:** Invalidate JWT tokens and log out users.\n- **Google Authentication:** Log in using Google OAuth2.\n\n## Tools and Technologies\n\nThis project utilizes a variety of tools and technologies to handle user authentication, data management, and infrastructure deployment:\n\n### Backend\n\n- **Node.js**: JavaScript runtime environment for building scalable network applications.\n- **TypeScript**: Superset of JavaScript that adds static typing.\n- **Fastify**: Web framework for building fast and low-overhead APIs.\n- **AWS SDK**:\n  - `@aws-sdk/client-dynamodb`: Client for interacting with DynamoDB.\n  - `@aws-sdk/lib-dynamodb`: Helper library for DynamoDB operations.\n  - `@aws-sdk/util-dynamodb`: Utilities for working with DynamoDB data types.\n- **Fastify Plugins**:\n  - `@fastify/aws-lambda`: Integration of Fastify with AWS Lambda.\n  - `@fastify/cors`: CORS support for Fastify applications.\n  - `@fastify/oauth2`: OAuth2 support for Fastify, used for SSO.\n  - `@fastify/rate-limit`: Rate limiting middleware for Fastify.\n- **JWT**:\n  - `jsonwebtoken`: Library for generating and verifying JSON Web Tokens.\n- **Validation**:\n  - `zod`: TypeScript-first schema declaration and validation library.\n  - `zod-to-json-schema`: Converts Zod schemas to JSON Schema format for use with Fastify.\n- **Dependency Injection**:\n  - `tsyringe`: Lightweight dependency injection container for TypeScript/JavaScript.\n- **Utilities**:\n  - `axios`: HTTP client for making API requests.\n  - `env-var`: Library for parsing and validating environment variables.\n  - `uuid`: Library for generating unique identifiers.\n  - `reflect-metadata`: Library used for decorators and metadata reflection.\n- **Logging**:\n  - `winston`: Versatile logging library.\n\n### Infrastructure\n\n- **Terraform**: Infrastructure as Code (IaC) tool used to define and provision infrastructure using a high-level configuration language.\n\n## Project Structure\n\nThe project is organized into several folders within the `src/` directory:\n\n```bash\n# Root files in `src/`\nsrc/\n├── constants.ts                       # Defines application-wide constants, such as fixed values or configuration settings.\n├── container.ts                       # Configures and manages dependency injection using `tsyringe`.\n├── lambda.ts                          # Entry point for serverless deployment, configuring the app to run as an AWS Lambda function.\n├── main.ts                            # Main entry point of the application, responsible for bootstrapping the app.\n├── server.ts                          # Contains the setup for the Fastify HTTP server.\n\n# Custom type definitions\nsrc/@types/\n└── ...                                # Custom TypeScript type definitions and interfaces used throughout the application.\n\n# External service integrations\nsrc/adapters/\n├── email/                             # Handles email-related functionalities like sending verification codes.\n├── logger/                            # Logging service for tracking errors and activities.\n└── unique-id/                         # Utility for generating unique identifiers.\n\n# Configuration files for different parts of the application\nsrc/configs/\n├── dynamo.config.ts                   # Configuration for DynamoDB.\n├── env.config.ts                      # Environment variables configuration.\n├── jwt.config.ts                      # Configuration for generating and verifying JWT tokens.\n├── rate-limit.config.ts               # Rate limiting configuration.\n├── sso-google.config.ts               # Google SSO (Single Sign-On) configuration.\n└── sso.config.ts                      # Centralized configuration for integrating multiple SSO providers.\n\n# API request handlers and business logic\nsrc/controllers/\n├── auth.controller.ts                 # Handles authentication-related requests.\n└── registration.controller.ts         # Handles user registration and confirmation.\n\n# Custom error classes and handling\nsrc/errors/\n└── app.error.ts                       # Application-specific error classes.\n\n# Reusable helper functions and utilities\nsrc/helpers/\n└── auth.helper.ts                     # Helper functions related to authentication.\n\n# TypeScript interfaces for defining data structures\nsrc/interfaces/\n└── ...                                # Interfaces for data models and service responses.\n\n# Middleware functions for request processing and validation\nsrc/middlewares/\n├── ensure-authenticated.middleware.ts # Ensures that a request is authenticated.\n├── error-handling.middleware.ts       # Handles errors across the application.\n└── request-audit.middleware.ts        # Logs and audits incoming requests.\n\n# Data access logic and abstractions\nsrc/repositories/\n├── email-template.repository.ts       # Manages storage and retrieval of email templates.\n├── session.repository.ts              # Handles data related to user sessions.\n├── user-auth-provider.repository.ts   # Manages user authentication providers.\n├── user.repository.ts                 # Handles operations related to user data.\n└── verification-code.repository.ts    # Manages verification codes for email confirmation.\n\n# Route definitions and endpoint configurations for the API\nsrc/routers/\n├── app.router.ts                      # Registers all routes, including general and module-specific routes like /health.\n├── auth.router.ts                     # Routes related to authentication (login, logout, etc.).\n└── registration.router.ts             # Routes for user registration and email confirmation.\n\n# Validation schemas for request payloads using Zod\nsrc/schemas/\n├── login.schema.ts                    # Validates the payload for the login request.\n├── login-confirm.schema.ts            # Validates the payload for confirming a login.\n├── login-refresh.schema.ts            # Validates the payload for refreshing JWT tokens.\n├── registration.schema.ts             # Validates the payload for user registration.\n└── registration-confirm.schema.ts     # Validates the payload for confirming user registration.\n\n# Core business logic and reusable services\nsrc/services/\n├── login.service.ts                   # Validates user and sends a verification code to the user's email for login confirmation.\n├── login-confirm.service.ts           # Manages the confirmation of user login using the verification code.\n├── logout.service.ts                  # Manages user logout operations, including token invalidation.\n├── refresh-login.service.ts           # Handles the process of refreshing access tokens using a refresh token.\n├── registration.service.ts            # Handles user registration, sends a verification code to the user's email for account confirmation.\n├── registration-confirm.service.ts    # Creates the user account in the system after successful verification.\n└── single-sign-on.service.ts          # Manages the SSO (Single Sign-On) processes for different providers.\n```\n\n## Infra\n\nInfrastructure setup using [Terraform](https://www.terraform.io/) and deployment scripts.\n\n```bash\ninfra/\n├── backend/                      # Infrastructure configuration for backend services\n│   ├── main.tf                   # Main Terraform configuration file for backend resources.\n│   └── outputs.tf                # Specifies the outputs for backend resources, exporting useful information.\n\n├── lambda/                       # Infrastructure configuration for AWS Lambda functions\n│   ├── backend.tf                # Terraform configuration for deploying the Lambda function and its resources.\n│   ├── main.tf                   # Main Terraform configuration file for the Lambda function setup.\n│   ├── outputs.tf                # Specifies the outputs for the Lambda function, exporting useful information.\n│   ├── variables.tf              # Variables used in the Lambda configuration.\n│   ├── env/                      # Environment-specific configurations for Lambda functions\n│   │   ├── dev.s3.tfbackend      # S3 backend configuration for storing the Terraform state file in the dev environment.\n│   │   ├── dev.tfvars            # Variables specific to the dev environment.\n│   │   ├── prod.s3.tfbackend     # S3 backend configuration for storing the Terraform state file in the prod environment.\n│   │   └── prod.tfvars           # Variables specific to the prod environment.\n│   └── layers/                   # Contains configurations for Lambda layers\n│       └── nodejs/               # Node.js Lambda layer dependencies (e.g., npm packages)\n│           ├── package.json      # Node.js package dependencies for the Lambda layer.\n│           └── package-lock.json # Lock file for the Node.js dependencies.\n\n└── scripts/                      # Deployment scripts for automating the infrastructure setup\n    ├── deploy-backend.sh         # Shell script for deploying backend infrastructure using Terraform.\n    └── deploy-lambda.sh          # Shell script for deploying Lambda functions and their configurations using Terraform.\n```\n\n## Environment Variables\n\nThis project relies on a set of environment variables to configure various aspects of the application. Below is a comprehensive list of these variables, their descriptions, and default values (if any).\n\n| Variable Name                       | Required | Default Value                | Description                                                                 |\n|-------------------------------------|----------|------------------------------|-----------------------------------------------------------------------------|\n| `NODE_ENV`                          | No       | `production`                 | Defines the environment the application is running in (`development`, `production`). |\n| `STAGE`                             | No       | `prod`                       | Indicates the stage of deployment (`dev`, `prod`).                          |\n| `IS_DEBUG`                          | No       | Derived from `NODE_ENV` and `STAGE` | Boolean value indicating if debug mode is enabled.                          |\n| `PORT`                              | No       | `8080`                       | Port on which the application will run.                                     |\n| `CORS_ORIGIN`                       | No       | `*`                          | Specifies the allowed origins for CORS requests.                            |\n| `JWT_SECRET`                        | Yes      | -                            | Secret key used for signing JWT tokens.                                     |\n| `JWT_SECRET_VERIFICATION_TOKEN`     | Yes      | -                            | Secret key used specifically for verification tokens.                       |\n| `APPLICATION_BASE_URL`              | Yes      | -                            | Base URL of the application.                                                |\n| `FRONTEND_CONFIRM_SIGN_UP_URL`      | Yes      | -                            | URL for confirming user sign-up.                                            |\n| `FRONTEND_CONFIRM_SIGN_IN_URL`      | Yes      | -                            | URL for confirming user sign-in.                                            |\n| `RATE_LIMIT_MAX`                    | No       | `60`                         | Maximum number of requests allowed within the time window.                  |\n| `RATE_LIMIT_TIME_WINDOW_MS`         | No       | `60000` (1 minute)           | Time window for rate limiting in milliseconds.                              |\n| `AWS_REGION`                        | No       | `us-east-1`                  | AWS region for DynamoDB and other AWS services.                             |\n| `AWS_DYNAMO_TABLE_NAME`             | Yes      | -                            | Name of the DynamoDB table used by the application.                         |\n| `GOOGLE_CLIENT_SECRET`              | Yes      | -                            | Google OAuth client secret for authentication.                              |\n| `GOOGLE_CLIENT_ID`                  | Yes      | -                            | Google OAuth client ID for authentication.                                  |\n| `GOOGLE_SSO_ENABLED`                | No       | `false`                       | Boolean value indicating if Google SSO is enabled.                          |\n| `EMAIL_PROVIDER`                    | No       | `resend`                     | Specifies the email provider to be used (`Resend`, etc.).                   |\n| `DEFAULT_SENDER_EMAIL`              | Yes      | -                            | Default email address used for sending emails.                              |\n| `RESEND_API_KEY`                    | Required if `EMAIL_PROVIDER` is `resend` | - | API key for Resend email provider.                                          |\n| `UNIQUE_ID_PROVIDER`                | No       | `uuid`                       | Unique ID generation provider (`Uuid`, etc.).                               |\n| `LOGGER_PROVIDER`                   | No       | `winston`                    | Logger provider used for logging (`Winston`, etc.).                         |\n| `LOG_LEVEL`                         | No       | `info` or `debug` (if `IS_DEBUG` is true) | Log level for application logs (`info`, `debug`, etc.).            |\n\n## Setup and Usage\n\n### Installation\n\nWIP\n\n### Running the Project\n\nWIP\n\n### Testing\n\nWIP\n\n### Deployment\n\nWIP\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fribeirogab%2Fnodejs-api-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fribeirogab%2Fnodejs-api-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fribeirogab%2Fnodejs-api-auth/lists"}