Skip to content

README.md

Latest commit

 

History

History
172 lines (108 loc) · 3.99 KB

README.md

File metadata and controls

172 lines (108 loc) · 3.99 KB

web-auth

web-auth is a login and authentication web service implemented in Haskell. It serves as a testbed for showcasing tooling and technologies commonly used in production-grade web development.

The system exposes:

  • A RESTful API implemented in Haskell using Scotty.
  • A full-stack web app with a React client

Architecture & Systems

Although the project is experimental in nature, it integrates several production-ready systems:

  • Katip — structured logging
  • PostgreSQL — persistent user storage (email, password hash, etc.)
  • RabbitMQ — background email dispatching (verification emails)
  • Redis — in-memory storage for authentication/session tokens
  • MailHog — email testing tool

The project is built around the Haskell ecosystem, and includes a Haskell client library for interacting with the service via the RESTful API.

Features

🔐 Authentication Flow

  • A login page (served by default) allows users to authenticate with email and password.

    • Invalid email/password combinations result in a failed login and an error notification.
    • Email verification is required before login is permitted.
    • A link to the registration page is provided.

  • A registration page allows users to create an account using email and password.

    • If the email is already registered, an error notification is displayed.

✅ Input Validation

  • Email

    • Case-insensitive
    • Must follow valid email format
    • Must be unique

  • Password

    • Minimum length > 5 characters

    • Must contain:

      • At least one number
      • At least one uppercase letter
      • At least one lowercase letter

📧 Email Verification

  • The service handles email verification logic.
  • Verification emails are sent asynchronously.
  • Users cannot log in until their email is verified.

🍪 Session Handling

  • Upon successful login, the user is redirected to a protected User page.
  • Authentication status is stored via cookies.
  • Tokens are managed using an in-memory store.

Local Setup

Requirements

  • PostgreSQL 16
  • RabbitMQ
  • Redis
  • MailHog
  • GHC 9.6.7 (project was built and tested with this version)
  • cabal

The instructions below assume macOS with Homebrew.

Starting Auxiliary Services

1) PostgreSQL

Start (or restart) the service:

brew services start postgresql@16

Create the project database:

createdb hauth

You can verify that the database exists:

psql -l

2) RabbitMQ

brew services start rabbitmq

3) Redis

brew services start redis

4) MailHog

brew services start mailhog

Access Web UI at http://localhost:8025.

(We have configured the default connection URLs: amqp://guest:guest@localhost:5672/ and redis://localhost:6379/0, mailhog-smtp://localhost:1025.)

Starting the Backend Service

From the project root:

cabal run hauth

The Haskell backend service will start on the configured port (default: http://localhost:3000).

Starting the React Client

Ensure the backend service is running before starting the client.

In a separate terminal and from the project root:

cd frontend
npm install      # only required on first setup
npm run dev

The development server will start (typically at http://localhost:5173). The frontend is configured to proxy API requests to the backend during development.

Starting the Email Worker

Run the dedicated email-worker process in a separate terminal:

cabal run hauth-email-worker

The worker consumes verification events from RabbitMQ and sends emails through SMTP (localhost:1025, compatible with MailHog).

Credits

This project is inspired by the tutorials presented in:

Ecky Putrady, Practical Web Development with Haskell, Apress (2018).

It has been modernized and extended to incorporate updated libraries, tooling, and contemporary development practices.