CipherGate

A secure, containerized Command-Line Authentication System built with Go, PostgreSQL, Docker, and TOTP-based Multi-Factor Authentication (MFA).

CipherGate provides user registration, authentication, session management, account lockout protection, and Google/Microsoft Authenticator compatible MFA through an interactive CLI experience.

---

Features

Authentication

• User registration
• Secure login with username and password
• Password hashing using bcrypt
• Account lockout after multiple failed login attempts
• Last login tracking
• Current login tracking

Multi-Factor Authentication

• Enable TOTP-based MFA

• Disable MFA

• Compatible with:

  • Google Authenticator
  • Microsoft Authenticator
  • Other RFC 6238 compatible applications

• QR Code enrollment directly in terminal

• MFA verification during login

Session Management

• Session creation after successful authentication
• Configurable session timeout
• Session expiration validation
• Session logout support

Interactive CLI

• Interactive command shell
• Command history
• Tab completion
• Context-aware commands
• Helpful error messages and feedback

Persistence

• PostgreSQL database
• Dockerized database deployment
• Database migrations
• Persistent Docker volumes

---

Architecture

CipherGate follows a layered architecture:

┌─────────────┐
│     CLI     │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  Services   │
├─────────────┤
│ User        │
│ Session     │
│ MFA         │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ Repository  │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│ PostgreSQL  │
└─────────────┘

---

Screenshots

Application Startup

MFA Enrollment

Authenticated Session

---

Project Structure

ciphergate/
│
├── internal/
│   ├── auth/
│   │   └── context.go
│   │
│   ├── cli/
│   │   ├── login.go
│   │   ├── logout.go
│   │   ├── register.go
│   │   ├── whoami.go
│   │   ├── enable_2fa.go
│   │   ├── disable_2fa.go
│   │   ├── shell.go
│   │   ├── session_guard.go
│   │   └── helpers.go
│   │
│   ├── database/
│   │   └── postgres.go
│   │
│   ├── migration/
│   │   └── runner.go
│   │
│   ├── mfa/
│   │   └── service.go
│   │
│   ├── session/
│   │   ├── model.go
│   │   ├── repository.go
│   │   ├── postgres_repository.go
│   │   └── service.go
│   │
│   ├── user/
│   │    ├── model.go
│   │    ├── repository.go
│   │    ├── postgres_repository.go
│   │    └── service.go
│   │
│   └── config/
│        └── config.go
│
├── migrations/
│   ├── 001_create_users.sql
│   └── 002_create_sessions.sql
│
├── docs/
├── .env
├── Dockerfile
├── docker-compose.yml
├── go.mod
├── go.sum
├── main.go
└── README.md

---

Technology Stack

Component	Technology
Language	Go
Database	PostgreSQL
Containerization	Docker
Password Hashing	bcrypt
MFA	TOTP
CLI	Readline
Database Driver	lib/pq

---

Configuration

CipherGate supports the following runtime configuration:

Variable	Default	Description
SESSION_TIMEOUT_MINUTES	30	Session lifetime
LOCKOUT_DURATION_MINUTES	15	Account lockout duration
MAX_FAILED_ATTEMPTS	5	Failed password attempts before lockout

---

Prerequisites

• Go 1.24+
• Docker
• Docker Compose

---

Getting Started

Clone Repository

git clone https://github.com/shubhamranswal/CipherGate.git
cd CipherGate

---

Configure Environment

Create a .env file:

DB_HOST=localhost
DB_PORT=5432
DB_USER=admin
DB_PASSWORD=admin
DB_NAME=ciphergate
DB_SSLMODE=disable

SESSION_TIMEOUT_MINUTES=30
LOCKOUT_DURATION_MINUTES=15
MAX_FAILED_ATTEMPTS=5

---

Start PostgreSQL

Ensure Docker Desktop (Windows/macOS) or the Docker daemon (Linux) is running before starting the database container.

Start PostgreSQL:

docker compose up -d

Verify:

docker ps

---

Run Application

go run .

Expected startup:

🔐 CipherGate v0.1
✅ Connected to PostgreSQL

---

Build

go build -o ciphergate .

---

Run Tests

go test ./...

---

Quick Demo

Register User

ciphergate> register

Username: shubham
Password:
Confirm Password:

✅ User registered successfully

---

Login

ciphergate> login

Username: shubham
Password:

✅ Login successful

---

Enable MFA

ciphergate(shubham)> enable-2fa

Scan the QR code using Microsoft Authenticator or Google Authenticator and enter the generated code.

---

Logout

ciphergate(shubham)> logout

---

Login With MFA

ciphergate> login

Username: shubham
Password:

🔐 MFA Verification Required

TOTP Code: 123456

✅ Login successful

---

Available Commands

Guest Commands

Command	Description
register	Create a new user account
login	Authenticate user
help	Display available commands
exit	Exit application

---

Authenticated Commands

Command	Description
whoami	Display current user details
enable-2fa	Enable MFA
disable-2fa	Disable MFA
logout	Logout current session
help	Display available commands

---

User Information

After successful login:

👤 User Details
────────────────────────────────────────

Username
Registration Date
MFA Status
Last Login
Session Status
Session Expiration Time

---

Security Features

Password Security

• Passwords never stored in plaintext
• bcrypt password hashing
• Secure password verification

Account Lockout

After multiple failed login attempts:

Maximum Failed Attempts: 5
Lockout Duration: 15 Minutes

Account access is temporarily blocked until the lockout period expires.

Multi-Factor Authentication

• RFC 6238 compliant TOTP
• QR code onboarding
• Compatible with standard authenticator applications

Session Security

• Session IDs generated using UUIDs
• Session expiration support
• Session validation before authenticated operations
• Automatic logout on session expiration

---

Database Schema

Users Table

users
(
    id,
    username,
    password_hash,
    mfa_enabled,
    mfa_secret,
    failed_attempts,
    locked_until,
    current_login,
    last_login,
    created_at
)

---

Sessions Table

sessions
(
    id,
    user_id,
    created_at,
    expires_at,
    active
)

---

Session Management

Default session timeout: 30 Minutes (configurable through SESSION_TIMEOUT_MINUTES)

Expired sessions are automatically invalidated and require re-authentication.

---

Docker

Start services:

docker compose up -d

Stop services:

docker compose down

Remove services and volumes:

docker compose down -v

---

Manual Testing Performed

• User registration
• Duplicate username validation
• Password validation
• Successful login
• Failed login
• Account lockout
• Session creation
• Session expiration
• Logout
• MFA enable
• MFA disable
• MFA login verification
• QR code enrollment
• Database persistence
• Docker startup and shutdown

---

Future Enhancements

• Password reset workflow
• Role-based access control
• Audit logging