Graphical Password Authentication

Graphical Password Authentication is a Go package that secures user login with image-based password patterns. It converts selected image indices into a string, hashes it with bcrypt, and stores it in MongoDB. It also features brute-force protection, email alerts, and secure password resets.

Features

• 🔒 Secure user login with image-based password patterns
• 🛡️ Brute-force protection
• 📧 Email alerts for suspicious activities
• 🔄 Secure password resets
• 💾 Stores hashed passwords in MongoDB

Table of Contents

• Installation
• Configuration
• Usage
  • Basic Authentication
  • Advanced Security Features
  • Email Validation
  • Sending Emails
• API Reference
  • Core Functions
  • Advanced Security Functions
• Testing
• Contributing
• License

Installation

To install the package, use:

go get github.com/YashSaini99/gpass

Configuration

Create a .env file in the root of your project with the following keys:

# Database Configuration
DB_URI=mongodb://localhost:27017/graphicalpasswordauth

# SMTP Configuration (example using Mailtrap for testing)
SMTP_USER[email protected]
SMTP_PASS=your_mailtrap_password
SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=2525

• DB_URI: Connection string for your MongoDB instance.
• SMTP_USER, SMTP_PASS, SMTP_HOST, SMTP_PORT: Credentials and server details for sending emails. You can use a service like Mailtrap for testing purposes.

Usage

Basic Authentication

import (
    "github.com/YashSaini99/gpass"
    "time"
)

func main() {
    // Load environment variables
    gpass.LoadEnv()

    // Connect to the database
    err := gpass.Connect("your_mongodb_connection_string")
    if err != nil {
        // Handle error
    }
    defer gpass.Disconnect()

    // Validate an email
    if !gpass.IsValidEmail("[email protected]") {
        // Handle invalid email
    }

    // Register a new user
    err = gpass.RegisterUser("username", "[email protected]", []int{1, 3, 5, 7})
    if err != nil {
        // Handle error (e.g., duplicate username/email)
    }

    // Authenticate the user
    ok, err := gpass.AuthenticateUser("username", []int{1, 3, 5, 7})
    if err != nil {
        // Handle error
    }
    if ok {
        // Successful login
    }
}

Advanced Security Features

For added security, use the advanced functions that protect against brute-force attacks and support password resets.

// Create a SecureAuthManager instance
secManager := gpass.NewSecureAuthManager(3, 10*time.Minute, 15*time.Minute)

// Authenticate with protection (this will block the account on repeated failed attempts and send alert emails)
ok, err := secManager.AuthenticateWithProtection("username", []int{1, 3, 5, 7}, "[email protected]")
if err != nil {
    // Handle authentication error (e.g., account blocked)
}
if ok {
    // Successful login
}

// Initiate a password reset (generates a secure token and sends a reset email)
token, err := secManager.InitiatePasswordReset("username", "[email protected]")
if err != nil {
    // Handle password reset error
}
// Use the token for resetting the password, typically via a dedicated reset endpoint.

Email Validation

// Validate an email
if gpass.IsValidEmail("[email protected]") {
    fmt.Println("Email is valid")
} else {
    fmt.Println("Email is invalid")
}

Sending Emails

// Send an email
err := gpass.SendEmail("[email protected]", "Subject", "Email body")
if err != nil {
    // Handle email sending error
}

API Reference

Core Functions:

• LoadEnv() error
  Loads environment variables from a .env file.

• Connect(uri string) error
  Connects to MongoDB using the provided URI.

• Disconnect() error
  Disconnects from MongoDB.

• RegisterUser(username, email string, graphicalPassword []int) error
  Registers a new user.

• AuthenticateUser(username string, graphicalPassword []int) (bool, error)
  Authenticates a user with their graphical password.

• IsValidEmail(email string) bool
  Validates an email address.

• SendEmail(to, subject, body string) error
  Sends an email using the SMTP settings in your .env file.

Advanced Security Functions

• NewSecureAuthManager(threshold int, blockDuration, tokenDuration time.Duration) *SecureAuthManager
  Creates a new instance of SecureAuthManager.

• (m *SecureAuthManager) AuthenticateWithProtection(username string, graphicalPassword []int, userEmail string) (bool, error)
  Authenticates a user with brute-force protection.

• (m *SecureAuthManager) InitiatePasswordReset(username, userEmail string) (string, error)
  Initiates a password reset, sending a reset email with a secure token.

• (m *SecureAuthManager) ValidateResetToken(username, token string) bool
  Validates a password reset token.

Testing

To run the tests for this package:

go test ./tests

This will execute unit tests for core functionalities such as hashing, email validation, and more.

Contributing

Contributions are welcome! If you have ideas for enhancements, bug fixes, or additional features, please open an issue or submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.