https://github.com/yashsaini99/gpass
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.
https://github.com/yashsaini99/gpass
authentication golang graphical-password graphical-password-authentication security
Last synced: 14 days ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/yashsaini99/gpass
- Owner: YashSaini99
- License: mit
- Created: 2025-02-22T10:05:03.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-02-22T15:25:19.000Z (over 1 year ago)
- Last Synced: 2025-11-20T06:18:20.334Z (7 months ago)
- Topics: authentication, golang, graphical-password, graphical-password-authentication, security
- Language: Go
- Homepage:
- Size: 76.2 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Basic Authentication](#basic-authentication)
- [Advanced Security Features](#advanced-security-features)
- [Email Validation](#email-validation)
- [Sending Emails](#sending-emails)
- [API Reference](#api-reference)
- [Core Functions](#core-functions)
- [Advanced Security Functions](#advanced-security-functions)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)
## Installation
To install the package, use:
```bash
go get github.com/YashSaini99/gpass
```
## Configuration
Create a `.env` file in the root of your project with the following keys:
```ini
# Database Configuration
DB_URI=mongodb://localhost:27017/graphicalpasswordauth
# SMTP Configuration (example using Mailtrap for testing)
SMTP_USER=your_mailtrap_username@mailtrap.io
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
```go
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("user@example.com") {
// Handle invalid email
}
// Register a new user
err = gpass.RegisterUser("username", "user@example.com", []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.
```go
// 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}, "user@example.com")
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", "user@example.com")
if err != nil {
// Handle password reset error
}
// Use the token for resetting the password, typically via a dedicated reset endpoint.
```
### Email Validation
```go
// Validate an email
if gpass.IsValidEmail("user@example.com") {
fmt.Println("Email is valid")
} else {
fmt.Println("Email is invalid")
}
```
### Sending Emails
```go
// Send an email
err := gpass.SendEmail("user@example.com", "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:
```bash
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](https://github.com/YashSaini99/gpass/blob/main/LICENSE) file for details.
[](https://github.com/YashSaini99/gpass)
[](https://github.com/YashSaini99/gpass/issues)
[](https://github.com/YashSaini99/gpass)