Skip to content

Auth Module

Jump to bottom
Muragesh-24 edited this page Mar 30, 2026 · 3 revisions

Authentication System

Authentication Routes

Route Method Description
/api/auth/login POST User login, returns Access & Refresh tokens
/api/auth/signup POST User registration
/api/auth/logout GET User logout, invalidates Refresh token
/api/auth/verify GET Email verification link processing
/api/auth/me GET
/api/profile GET Get user profile information (protected)
/api/profile POST Update user profile information (protected)
/api/profile/pfp POST Upload profile picture (protected)
/api/profile/oa GET OAuth connection (protected)

All Backend routes are protected using the middleware located in middleware/authenticator.go

Refresh Token

This system uses a dual token JWT authentication model:

Token Type Purpose Lifespan
Access Token (AT) Used for every protected API request 5 minutes
Refresh Token (RT) Used only to generate new access tokens 7 days

This design ensures:

  • High security (short-lived access tokens)
  • Seamless user experience (automatic session renewal)
  • Forced logout when refresh token expires or is invalid

Access Token Design

  • Authentication for API requests
  • Authorization (role & visibility checks for student search)

Access Token Payload Model

UserID   uuid.UUID `json:"user_id"`
Role     int       `json:"role"`
Verified bool      `json:"verified"`
Visibility bool    `json:"visibility"`
jwt.RegisteredClaims

Refresh Token Design

  • Only used to generate new Access Tokens

Refresh Token Payload Model

UserID string `json:"user_id"`
jwt.RegisteredClaims
  • Only userID and standard JWT claims
  • No role, verification or visibility data (for security)

Token Renewal Logic Whenever a new Access Token is generated using a Refresh Token: System fetches latest values from database:

  • role
  • verified
  • visibility

Ensures permission changes take effect instantly.

Advantages

  • Short-lived Access Tokens prevent long-term token abuse.
  • Refresh Token contains minimal data → limits exposure risk.
  • Database re-validation prevents stale role/visibility abuse.
  • Automatic logout when Refresh Token expires.
  • No need for the user to login everytime.

Compass and search use the same tokens

Authentication system features:

  • Recaptcha Integration : we integrated Google reCAPTCHA to prevent automated bot signups and logins.

CC (Computer center) Api key

  • We verify user data using a API Key provided by CC IIT Kanpur. This ensure that users provide valid information during registration.

How does this work?

  • During registration, users provide their email and other details excluding their name.
  • The system sends this data to the OA verification route (this route need a API Key).
  • OA verifies the information and returns a boolean indicating success or failure.
  • If verification is successful, OA also returns the user's name, which can be stored in the system for future use.

Public files are secured and accessible only to authenticated users.

We have 3 sub routes to handle different type of assets :

  • /pfp for profile pictures - accesssible to authenticated users only
  • /public for public assets (like location photos) - accesssible to everyone
  • /tmp for temporary files (like review photos pending approval) - accesssible to admins only

r.Static("/assets", "./assets/public")

protected.Use(middleware.UserAuthenticator, middleware.EmailVerified)
	{
		protected.Static("/pfp", "./assets/pfp")
		protected.POST("/assets", uploadAsset)
    }

admin.Use(middleware.UserAuthenticator, middleware.EmailVerified, middleware.AdminAuthenticator)
	{
		admin.Static("/tmp", "./assets/tmp")
    }

All users privacy is protected and only authenticated users can access their profile pictures, while review photos are stored in a temporary location until approved by admins, ensuring that inappropriate content is not publicly accessible.

Nexus Flaging system

Content Moderation Worker

The Content Moderation Worker ensures that user generated content such as text reviews and uploaded images comply with platform safety policies. This service integrates with the OpenAI Moderation API to automatically detect unsafe or inappropriate content.

Purpose

The moderation worker helps to:

  • Prevent abusive or harmful content
  • Enforce community guidelines
  • Automatically filter unsafe uploads
  • Reduce manual moderation workload
  • Improve platform trust and safety

Image Moderation Flow

When an image is uploaded:

  1. The image is read from temporary storage.
  2. The image is converted into Base64 format.
  3. The Base64 encoded image is sent to the OpenAI moderation model.
  4. The model analyzes the image for unsafe categories such as:
    • Violence
    • Sexual content
    • Hate symbols
    • Harassment
    • Self-harm related content
  5. The API returns a flagged status.
  6. Based on the result:
    • Flagged → Content may be rejected or sent for manual review
    • Not Flagged → Content may be approved

Text Moderation Flow

When a review is submitted:

  1. The review is fetched from the database.
  2. The review description is sent to the OpenAI moderation model.
  3. The model evaluates the text for:
    • Hate speech
    • Abusive language
    • Threats
    • Sexual content
    • Harassment
  4. The API returns whether the content is flagged.
  5. Based on the result:
    • Flagged → Review may be blocked or reviewed
    • Not Flagged → Review may be published

Moderation Model Used

The system uses OpenAI omni-moderation models which support both text and image safety classification. These models provide fast and reliable detection of unsafe content across multiple safety categories.

Return Value

The moderation worker returns a boolean result:

Result Meaning
true Content violates safety policy
false Content is considered safe

This result can be used by other services to decide whether to publish, reject, or manually review the content.

Architecture Overview

User Upload (Text/Image)
        ↓
Moderation Worker
        ↓
OpenAI Moderation API
        ↓
Safety Classification
        ↓
Decision Layer
(Allow / Reject / Review)

  Status = "pending" 
  Approved      Status = "approved"
  Rejected      Status = "rejected"      // if rejected by admin finally
  RejectedByBot Status = "rejectedByBot" ,
  • If the image is flagged as inappropriate by the bot, it is automatically marked as "rejectedByBot" and will not be visible to other users. then admin will check it manually and finally it will be either approved or rejected by admin
  • If the image is flagged as appropriate by the bot then it is visible to other users.

Super Admin and Admin roles

  • Super Admin has the highest level of control over the system, including admin management.
  • Admins have specific permissions to manage content and users.
  • Both admin and super admin can manage locations, reviews, and user accounts, but only super admin can manage other admins.

Security Measures for the system

our system implements several security measures to protect against common web vulnerabilities and ensure the safety of user data. These measures include :

  • Middleware for Authentication and Authorization: We use middleware to protect routes and ensure that only authenticated users can access endpoints. This includes checking for valid JWT tokens and verifying user roles and permissions.

  • Dual Token System: We implement a dual token system with short-lived access tokens and long-lived refresh tokens. This minimizes the risk of token theft and abuse.

  • Database Re-validation: Whenever a new access token is generated using a refresh token, we fetch the latest user data from the database to ensure that any changes in roles or permissions take effect immediately.

Clone this wiki locally