Add /auth/register endpoint for jwt route protection (#11)

- Add Flask-PyMongo, extension.py and app factory init
- Add users_db_setup fixture to clean users collection
- Add register and duplicate-email tests, and invalid-email tests
- Add app/routes directory; rename and move app/routes.py to app/routes/legacy_routes.py
- Use Blueprints for auth_routes; register new blueprint
- Add email validation (email-validator), normalize email, bcrypt hashing
- Add error handling improvements
- Run formatting, update requirements and openapi.yml
Co-authored-by: Copilot <[email protected]>"

Author: codesungrape

app/__init__.py

@@ -3,25 +3,32 @@
 import os
 
 from flask import Flask
+from flask_pymongo import PyMongo
 
 from app.config import Config
+from app.extensions import mongo
 
 
 def create_app(test_config=None):
     """Application factory pattern."""
 
     app = Flask(__name__)
-
-    # 1. Load the default configuration from the Config object.
     app.config.from_object(Config)
 
     if test_config:  # Override with test specifics
         app.config.from_mapping(test_config)
 
-    # Import routes
-    from app.routes import \
-        register_routes  # pylint: disable=import-outside-toplevel
+    # Connect Pymongo to our specific app instance
+    mongo.init_app(app)
+
+    # Import blueprints inside the factory
+    from app.routes.auth_routes import \
+        auth_bp  # pylint: disable=import-outside-toplevel
+    from app.routes.legacy_routes import \
+        register_legacy_routes  # pylint: disable=import-outside-toplevel
 
-    register_routes(app)
+    # Register routes with app instance
+    register_legacy_routes(app)
+    app.register_blueprint(auth_bp)
 
     return app

app/config.py

@@ -1,10 +1,11 @@
 # pylint: disable=too-few-public-methods
 
 """
-Application configuration module for Flask.
+The central, organized place for  the application's settings.
+
+Loads environment variables (and other sensitive values) from a .env file and
+Defines the Config class to be used.
 
-Loads environment variables from a .env file and defines the Config class
-used to configure Flask and database connection settings.
 """
 
 import os

app/datastore/mongo_helper.py

@@ -1,8 +1,8 @@
 """Module containing pymongo helper functions."""
 
 from bson.objectid import InvalidId, ObjectId
-from pymongo.cursor import Cursor
 from pymongo.collection import Collection
+from pymongo.cursor import Cursor
 
 
 def insert_book_to_mongo(book_data, collection):
@@ -83,8 +83,10 @@ def delete_book_by_id(book_collection: Collection, book_id: str):
 
     return result
 
+
 # ------ PUT helpers ------------
 
+
 def validate_book_put_payload(payload: dict):
     """
     Validates the payload for a PUT request.

app/extensions.py

@@ -0,0 +1,7 @@
+"""Module for Flask extensions."""
+
+from flask_pymongo import PyMongo
+
+# Createempty PyMongo extension object globally
+# This way, we can import it in other files and avoid a code smell: tighly-coupled, cyclic error
+mongo = PyMongo()

app/routes/__init__.py

@@ -0,0 +1,76 @@
+# pylint: disable=cyclic-import
+"""Routes for authorization for the JWT upgrade"""
+
+import bcrypt
+from email_validator import EmailNotValidError, validate_email
+from flask import Blueprint, jsonify, request
+from werkzeug.exceptions import BadRequest
+
+from app.extensions import mongo
+
+auth_bp = Blueprint("auth_bp", __name__, url_prefix="/auth")
+
+
+@auth_bp.route("/register", methods=["POST"])
+def register_user():
+    """
+    Registers a new user.
+    Takes a JSON payload with "email" and "password".
+    It verfies it is not a duplicate email,
+    Hashes the password and stores the new user in the database.
+    """
+
+    # VALIDATION the incoming data/request payload
+    try:
+        data = request.get_json()
+        if not data:
+            return jsonify({"message": "Request body cannot be empty"}), 400
+
+        email = data.get("email")
+        password = data.get("password")
+
+        if not email or not password:
+            return jsonify({"message": "Email and password are required"}), 400
+
+        # email-validator
+        try:
+            valid = validate_email(email, check_deliverability=False)
+
+            # use the normalized email for all subsequent operations
+            email = valid.normalized
+        except EmailNotValidError as e:
+            return jsonify({"message": str(e)}), 400
+
+    except BadRequest:
+        return jsonify({"message": "Invalid JSON format"}), 400
+
+    # Check for Duplicate User
+    # Easy access with Flask_PyMongo's 'mongo'
+    if mongo.db.users.find_one({"email": email}):
+        return jsonify({"message": "Email is already registered"}), 409
+
+    # Password Hashing
+    # Generate a salt and hash the password
+    # result is a byte object representing the final hash
+    hashed_password = bcrypt.hashpw(password.encode("utf-8"), bcrypt.gensalt())
+
+    # Database Insertion
+    user_id = mongo.db.users.insert_one(
+        {
+            "email": email,
+            # The hash is stored as a string in the DB
+            "password_hash": hashed_password.decode("utf-8"),
+        }
+    ).inserted_id
+    print(user_id)
+
+    # Prepare response
+    return (
+        jsonify(
+            {
+                "message": "User registered successfully",
+                "user": {"id": str(user_id), "email": email},
+            }
+        ),
+        201,
+    )

app/routes/auth_routes.py

@@ -15,7 +15,7 @@
 from app.utils.helper import append_hostname
 
 
-def register_routes(app):  # pylint: disable=too-many-statements
+def register_legacy_routes(app):  # pylint: disable=too-many-statements
     """
     Register all Flask routes with the given app instance.
 

app/routes.py renamed to app/routes/legacy_routes.py

@@ -28,6 +28,9 @@ tags:
       description: Find out more
       url: example.com
 
+  - name: Authentication
+    description: Operations related to user registration and login
+
 # --------------------------------------------
 # Components
 components:
@@ -108,6 +111,57 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/BookOutput'
+    
+  # ----- AUTH schemas -------------
+
+    # Schema for the data client POSTs to register a user
+    UserRegistrationInput:
+      type: object
+      properties:
+        email:
+          type: string
+          format: email
+          description: The user's email address.
+          example: "[email protected]"
+        password:
+          type: string
+          format: password # This format is a hint for UI tools to obscure the input
+          description: The user's desired password.
+          minLength: 8 # It's good practice to suggest a minimum length
+          example: "a-very-secure-password"
+      required:
+        - email
+        - password
+
+    # Schema for the User object as returned by the server on success
+    UserOutput:
+      type: object
+      properties:
+        id:
+          type: string
+          description: The unique 24-character hexadecimal identifier for the user (MongoDB ObjectId).
+          readOnly: true
+          example: "635f3a7e3a8e3bcfc8e6a1e0"
+        email:
+          type: string
+          format: email
+          readOnly: true
+          example: "[email protected]"
+
+    # Schema for the successful registration response
+    RegistrationSuccess:
+      type: object
+      properties:
+        message:
+          type: string
+          example: "User registered successfully"
+        user:
+          $ref: '#/components/schemas/UserOutput'
+
+
+
+
+  # ------ ERROR schemas ----------
 
     # Generic Error schema
     StandardError:
@@ -144,6 +198,16 @@ components:
       required:
         - error
 
+    # Schema for a simple message response (useful for errors)
+    MessageError:
+      type: object
+      properties:
+        message:
+          type: string
+          description: A brief error message.
+      required:
+        - message
+
   # API Error: Reusable responses for common errors  
   responses:
     BadRequest:
@@ -426,3 +490,50 @@ paths:
                 error: "Book not found"
         '500':
           $ref: '#/components/responses/InternalServerError' 
+# --------------------------------------------
+  /auth/register:
+# --------------------------------------------
+    post:
+      tags:
+        - Authentication
+      summary: Register a new user
+      description: >-
+        Creates a new user account. The server will hash the password and store the user details, returning a unique ID for the new user.
+      operationId: registerUser
+      requestBody:
+        description: User's email and password for registration.
+        required: true
+        content:
+          application/json:
+            schema:
+                $ref: '#/components/schemas/UserRegistrationInput'
+        responses:
+          '201':
+          description: User registered successfully.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RegistrationSuccess'
+          '400':
+          description: Bad Request. The request body is missing, not valid JSON, or is missing required fields.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageError'
+              examples:
+                missingFields:
+                  summary: Missing Fields
+                  value:
+                    message: "Email and password are required"
+                emptyBody:
+                  summary: Empty Body
+                  value:
+                    message: "Request body cannot be empty"
+          '409':
+          description: Conflict. The provided email is already registered.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageError' # Reuse the error schema again!
+              example:
+                message: "Email is already registered"

openapi.yml

@@ -7,4 +7,7 @@ pymongo
 python-dotenv
 mongomock
 black
-isort
+isort
+flask_pymongo
+flask-bcrypt
+email-validator

requirements.txt

@@ -9,15 +9,15 @@
 import mongomock
 import pytest
 
-from app import create_app
+from app import create_app, mongo
 from app.datastore.mongo_db import get_book_collection
 
 
 @pytest.fixture(name="_insert_book_to_db")
 def stub_insert_book():
     """Fixture that mocks insert_book_to_mongo() to prevent real DB writes during tests. Returns a mock with a fixed inserted_id."""
 
-    with patch("app.routes.insert_book_to_mongo") as mock_insert_book:
+    with patch("app.routes.legacy_routes.insert_book_to_mongo") as mock_insert_book:
         mock_insert_book.return_value.inserted_id = "12345"
         yield mock_insert_book
 
@@ -78,6 +78,17 @@ def test_app():
             "COLLECTION_NAME": "test_books",
         }
     )
+    # The application now uses the Flask-PyMongo extension,
+    # which requires initialization via `init_app`.
+    # In the test environment, the connection to a real database fails,
+    # leaving `mongo.db` as None.
+    # Fix: Manually patch the global `mongo` object's connection with a `mongomock` client.
+    # This ensures all tests run against a fast, in-memory mock database AND
+    # are isolated from external services."
+    with app.app_context():
+        mongo.cx = mongomock.MongoClient()
+        mongo.db = mongo.cx[app.config["DB_NAME"]]
+
     yield app
 
 
@@ -105,3 +116,21 @@ def db_setup(test_app):  # pylint: disable=redefined-outer-name
     with test_app.app_context():
         collection = get_book_collection()
         collection.delete_many({})
+
+
+# Fixture for tests/test_auth.py
+@pytest.fixture(scope="function")
+def users_db_setup(test_app):  # pylint: disable=redefined-outer-name
+    """
+    Sets up and tears down the 'users' collection for a test.
+    """
+    with test_app.app_context():
+        # Now, the 'mongo' variable is defined and linked to the test_app
+        users_collection = mongo.db.users
+        users_collection.delete_many({})
+
+    yield
+
+    with test_app.app_context():
+        users_collection = mongo.db.users
+        users_collection.delete_many({})