📋 Table of Contents

• ✨ Overview
• 🚀 Quick Start
  • Installation
  • Running the API Server
  • Running the Web Demo
• 🧰 System Requirements
• 🔐 Authentication Flow
• 📘 Usage in Your Application
  • Basic Authentication Flow
  • FastAPI Integration
• ⚙️ Configuration
• 📚 Documentation
• 💻 Development
  • Project Structure
  • Setup Development Environment
  • Running Tests
  • Building Documentation Locally
• 📄 License
• 📞 Contact

✨ Overview

Evrmore Authentication is a Python package that provides wallet-based authentication using Evrmore signature verification. This allows users to authenticate to web applications using their Evrmore wallet without sharing their private keys, creating a secure and user-friendly authentication experience.

Key Features:

• 🔑 Wallet-based authentication - Users sign a challenge message with their Evrmore wallet
• 🔒 JWT token management - Secure session handling with JSON Web Tokens
• 📁 SQLite backend - Simple, file-based database for session and challenge storage
• 👤 Automatic user management - Users are created on first authentication
• 🌐 Complete API server - Ready-to-use FastAPI server for authentication endpoints
• 🖥️ Demo web interface - Example Flask application showing the complete authentication flow

🚀 Quick Start

Installation

pip3 install evrmore-authentication

Running the API Server

python3 -m scripts.run_api_server --host 0.0.0.0 --port 8000

Running the Web Demo

python3 -m scripts.run_web_demo --port 5000 --api-url http://localhost:8000

🧰 System Requirements

• Python 3.7 or higher
• SQLite database for session and challenge storage
• Evrmore node (for signature verification)

🔐 Authentication Flow

📘 Usage in Your Application

Basic Authentication Flow

from evrmore_authentication import EvrmoreAuth
from evrmore_rpc import EvrmoreClient

# Initialize the authentication system with an Evrmore client
client = EvrmoreClient()
auth = EvrmoreAuth(client)

# Generate a challenge for a user's Evrmore address
challenge = auth.generate_challenge("EXaMPLeEvRMoReAddResS")

# Verify the signature provided by the user
session = auth.authenticate(
    evrmore_address="EXaMPLeEvRMoReAddResS",
    challenge=challenge,
    signature="signed_challenge_from_wallet"
)

# Use the token for authentication
token = session.token

# Validate a token
token_data = auth.validate_token(token)

# Get user from token
user = auth.get_user_by_token(token)

# Invalidate a token (logout)
auth.invalidate_token(token)

FastAPI Integration

The package includes a ready-to-use FastAPI server with the following endpoints:

Endpoint	Method	Description
/challenge	POST	Generate a challenge for a user
/authenticate	POST	Authenticate with a signed challenge
/validate	GET	Validate a JWT token
/me	GET	Get authenticated user information
/logout	POST	Invalidate a JWT token (logout)

⚙️ Configuration

Configuration is done through environment variables or a .env file:

# SQLite configuration
SQLITE_DB_PATH=./data/evrmore_auth.db

# JWT configuration
JWT_SECRET=your-secure-secret-key
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# Challenge configuration
CHALLENGE_EXPIRE_MINUTES=10

📚 Documentation

For more information, please see:

• 📖 User Guide
• 🔍 API Reference
• 📔 Online Documentation

💻 Development

Project Structure

evrmore-authentication/
├── evrmore_authentication/    # Main package
│   ├── __init__.py            # Package initialization
│   ├── auth.py                # Core authentication logic
│   ├── api.py                 # FastAPI endpoints
│   ├── models.py              # Database models
│   ├── exceptions.py          # Custom exceptions
│   └── dependencies.py        # FastAPI dependencies
├── scripts/                   # Utility scripts
│   ├── run_api_server.py      # API server runner
│   └── run_web_demo.py        # Web demo runner
├── examples/                  # Example applications
│   ├── demo.py                # Simple CLI demo
│   └── web_auth_demo/         # Web application example
├── tests/                     # Test suite
├── docs/                      # Documentation
└── setup.py                   # Package setup

Setup Development Environment

git clone https://github.com/manticoretechnologies/evrmore-authentication.git
cd evrmore-authentication
pip3 install -e .

Running Tests

pytest

Building Documentation Locally

# Install MkDocs and the Material theme
pip3 install mkdocs-material

# Serve the documentation locally at http://127.0.0.1:8000
mkdocs serve

# Build the documentation
mkdocs build

📄 License

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

📞 Contact

---