Auth Service

Overview

Auth Service is a secure, production-grade authentication microservice built with Fastify and TypeScript. It leverages Google Cloud KMS for asymmetric JWT signing, ensuring cryptographic keys are managed with the highest security standards. This service offers a comprehensive authentication solution featuring user management, session handling, token rotation, rate limiting, and CSRF protection.

Features

• Secure Authentication: User registration and login with bcrypt password hashing.
• JWT Management: Access and refresh token issuance using asymmetric signing (RS256, PS256, etc.) via Google Cloud KMS.
• Session Handling: Secure cookie-based session management.
• Token Rotation: Refresh token rotation for enhanced security.
• JWK Integration: JSON Web Key (JWK) caching and verification services.
• Rate Limiting: Built-in rate limiting using Redis.
• CSRF Protection: Secure CSRF token generation and verification.
• Documentation: Auto-generated Swagger/OpenAPI documentation.
• Database: PostgreSQL with Drizzle ORM for type-safe database interactions.
• Caching: Upstash Redis for JWK sets, sessions, and database queries.

Tech Stack

• Runtime: Node.js
• Framework: Fastify
• Language: TypeScript
• Database: PostgreSQL
• ORM: Drizzle ORM
• Caching: Upstash Redis (via @upstash/redis, cache-manager, and keyv)
• Security:
  • Google Cloud KMS (Key Management Service)
  • jose for JWT operations
  • bcrypt for password hashing
  • @fastify/csrf-protection for CSRF defense
• Validation: Zod
• Documentation: Swagger / OpenAPI (via @fastify/swagger)
• Logging: Pino
• Testing: Jest

Prerequisites

• Node.js (v18+ or LTS)
• PostgreSQL
• Redis (or Upstash Redis)
• Google Cloud Platform Account
  • Enabled Cloud KMS API
  • A Key Ring and Crypto Key created
  • Service Account with appropriate permissions (Cloud KMS CryptoKey Signer/Verifier)

Installation

1. Clone the repository

   git clone https://github.com/jmrl23/auth-service.git
   cd auth-service

2. Install dependencies

   yarn install

3. Environment Configuration Copy the example environment file and update the values:

   cp .env.example .env

   Required Environment Variables:

   • DATABASE_URL: Connection string for PostgreSQL (e.g., postgres://user:pass@localhost:5432/auth_db).
   • REDIS_URL: Connection string for Redis (e.g., redis://localhost:6379).
   • COOKIE_SECRET: A strong secret string for signing cookies.
   • CRYPTO_KEY_PATH: The Google Cloud KMS key resource path (format: projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{cryptoKey}).

   Optional Environment Variables:

   • PORT: Port to run the server on (default: 3001).
   • SWAGGER_SERVERS: Comma-separated list of servers for Swagger UI (e.g., http://localhost:3001).
   • TRUST_PROXY: Trust proxy settings (default: loopback).
   • NODE_ENV: Environment mode (development, test, production).

4. Database Migration Push the schema to the database:

   yarn drizzle-kit push

Running the Application

Development

Starts the application in watch mode with tsx.

yarn start:dev

Production

Builds the project and starts the production server.

yarn build
yarn start:prod

Docker

You can also run the application using Docker.

docker build -t auth-service .
docker run -p 3001:3001 --env-file .env auth-service

API Documentation

Once the server is running, you can access the Swagger UI documentation at:

http://localhost:3001/documentation

Key Endpoints

• GET /csrf-token: Retrieve a CSRF token (required for state-changing requests).
• POST /auth/register: Register a new user.
• POST /auth/login: Authenticate a user and receive tokens.
• POST /auth/refresh: Rotate refresh tokens to get a new access token.
• GET /auth/session: Get the current session information (requires valid access token).
• DELETE /auth/logout: Revoke the refresh token and log out.

Project Structure

src/
├── common/         # Shared utilities (db, env, logger)
├── db/             # Database schema and configuration
├── modules/        # Feature modules
│   ├── auth/       # Authentication logic (routes, schemas, handlers)
│   ├── jwk/        # JWK service (Token signing/verification)
│   └── kms/        # Google Cloud KMS integration
├── plugins/        # Fastify plugins (docs, routes, csrf)
├── bootstrap.ts    # Plugin registration
├── server.ts       # Fastify server setup
└── main.ts         # Application entry point

Scripts

• yarn build: Compile TypeScript to JavaScript.
• yarn start: Run the compiled application.
• yarn start:dev: Run in development mode with hot-reloading.
• yarn start:prod: Run in production mode with environment variable loading.
• yarn test: Run tests using Jest.
• yarn format: Format code with Prettier.
• yarn lint: Lint code with ESLint.

License

This project is licensed under the MIT License.