Social Identity & Auth Service
Robust authentication, profiles, and social interaction engine microservice.
Auth Service is a comprehensive identity management solution designed for microservice architectures. Built with Fastify and TypeScript, the service not only handles the authentication lifecycle via JWT (Access & Refresh Tokens), but also implements a social interaction engine including friendship and blocking systems. It supports OAuth2 with Google and GitHub, token version-based session invalidation, secure inter-service communication, and granular per-endpoint rate limiting. Designed with a security-first approach using httpOnly cookies, Prometheus metrics, and structured logging with Pino.
Screenshots coming soon
1. Architecture
Routes (HTTP Layer)
HTTP layer responsible for request parsing, schema validation, response formatting, and guard application. Delegates all business logic to services.
Services (Business Logic)
Business logic layer with static classes. Handles domain rules, transaction management, and cross-module coordination (AuthService, FriendshipService, BlockService, OAuthService).
Database (Data Access)
Data access layer with Prisma using the adapter pattern (@prisma/adapter-pg) with a native pg connection pool. Includes DTOs for response transformation.
2. Features
Security & Authentication
JWT Dual Token Authentication
Short-lived Access Tokens (15 min) and Refresh Tokens (14 days) stored in httpOnly cookies with rotation and database revocation. Payload includes token version for instant invalidation.
OAuth2 Social Login
Full integration with Google (OpenID Connect) and GitHub OAuth2. CSRF handling with in-memory state, automatic profile data extraction, and email conflict detection across providers.
Token Version Invalidation
Storage-free invalidation mechanism: each user has a tokenVersion in their JWT. On logout, the version is incremented, instantly invalidating all existing tokens without needing a blacklist.
Granular Rate Limiting
Protection against brute-force and abuse with per-endpoint limits: Login (10/15min), Register (10/15min), Refresh (30/15min), and more.
Secure Inter-Service Communication
Specialized middleware for internal microservice authentication via segregated API Keys. Allows services like TicketPlatform to query users without exposing public endpoints.
Social Engine
Social Interaction Engine
Complete user interaction system with auto-acceptance when both parties send requests, and blocks that automatically remove existing friendships.
Friendship System
Full lifecycle: send, accept, reject, cancel requests. Normalized pairs (user1Id always smaller) to prevent duplicates. Rejected requests can be re-sent by reusing the record.
Block System
Idempotent blocking that atomically deletes any existing friendship and creates the block in a transaction. Blocks prevent all friendship interactions (send, accept, reject).
User Profile Management
Profiles with automatic on-demand creation (lazy). Fields: displayName, firstName, lastName, avatarUrl, bio. Public profile excludes email; private profile includes email and role.
Infrastructure & Production
Prometheus Metrics
/health/metrics endpoint with custom metrics: http_requests_total (Counter), http_request_duration_seconds (Histogram), http_requests_in_progress (Gauge), plus default Node.js metrics.
Structured Logging with Pino
Structured logging of all requests with method, path, and contextual data. Sensitive headers (authorization, cookie) automatically redacted.
Swagger Documentation
API documented with @fastify/swagger and @fastify/swagger-ui. Available only in non-production environments to reduce attack surface. Complete schema for all endpoints.
Production Ready
Multi-stage Docker with Node.js Alpine, strict environment variable validation at boot, 75+ tests with Vitest and coverage, configurable CORS, and Docker Compose ready.
3. Tech Stack
Prisma 4. API Reference
| Module | Endpoints |
|---|---|
| Authentication | 5 |
| OAuth2 | 4 |
| Profiles | 3 |
| Friendships | 8 |
| Blocks | 3 |
| Internal | 1 |
| Health | 2 |
5. Design Decisions
Token Version vs Blacklist
Instead of maintaining a token blacklist (requires storage and lookup on every request), a tokenVersion is embedded in the JWT. On logout, incrementing the version instantly invalidates all existing tokens without additional storage.
publicId as External Identifier
Users have both an auto-incrementing integer id (internal, used in FKs) and a UUID publicId (external, used in API responses and JWT). This prevents ID enumeration attacks and decouples internal storage from external API contracts.
Normalized Friendship Pairs
normalizePair() ensures user1Id is always the smaller ID. This prevents duplicates (A→B and B→A) by leveraging the unique constraint [user1Id, user2Id] without additional queries.
Split Token Strategy
Access token in response body (for localStorage and Authorization header), refresh token in httpOnly cookie (XSS protection, automatic sending). Works across subdomains with configurable cookie domain.