Skip to content

README.md

Latest commit

 

History

History
347 lines (270 loc) · 13.2 KB

README.md

File metadata and controls

347 lines (270 loc) · 13.2 KB
Raw

JV Shetty Megamart — Campus E-Commerce Platform

A production-grade campus supermarket for BITS Pilani Goa with OTP-based authentication, JWT sessions, and Role-Based Access Control (RBAC).

Project Overview

JV Shetty Megamart is a full-stack PHP e-commerce platform built exclusively for the BITS Pilani Goa campus community. It enforces campus-email login (@goa.bits-pilani.ac.in), time-boxed store hours (4 – 9 PM IST), and a multi-role permission model so that students, faculty, admins, and delivery partners each see only what they are allowed to.

Key capabilities:

  • Browse and search the product catalogue with category / price filters.
  • Cart, checkout, order tracking, and cancellation workflows.
  • Admin panel: order management, inventory control, analytics, role management.
  • Delivery portal for fulfilment partners.
  • OTP-verified login with JWT bearer tokens (no persistent passwords on the wire).

Security Features

Feature Detail
OTP TTL 10 minutes (600 s) — OTPs expire automatically
OTP rate limit 3 requests per hour per email address (atomic Redis sliding window via Lua)
Brute-force lockout 5 failed verification attempts → account locked for 1 hour
JWT session length 30 minutes (1 800 s, JWT_TTL)
JWT algorithm HS256 (JWT_ALGORITHM)
OTP hashing bcrypt (password_hash / password_verify)
Campus restriction Only @goa.bits-pilani.ac.in addresses are accepted
Security headers CSP (nonce-based), X-Frame-Options: DENY, HSTS, X-Content-Type-Options, Referrer-Policy
Input sanitisation NULL-byte stripping, control-char removal, 65 535-byte truncation
SQL injection guard Prepared statements everywhere; request-level alerting via SecurityMiddleware

Repository Structure

JV-Shetty/
├── jv_shetty/                   # Application root (Apache document root)
│   ├── auth/                    # New OTP + JWT + RBAC auth system
│   │   ├── AuthService.php      # Orchestration: OTP → email → JWT
│   │   ├── JWTHandler.php       # Pure-PHP HS256 JWT (no external library)
│   │   ├── OTPManager.php       # OTP lifecycle, rate-limiting, locking
│   │   ├── RBACManager.php      # Permission map + enforcement helpers
│   │   ├── RedisClientInterface.php
│   │   ├── RedisFactory.php     # Redis connection + adapter
│   │   └── middleware/
│   │       ├── JWTMiddleware.php      # Bearer-token verification
│   │       ├── RBACMiddleware.php     # JWT + role/permission gate
│   │       └── SecurityMiddleware.php # Security headers, input sanitise
│   ├── api/                     # REST API endpoints
│   ├── config/                  # App, DB, JWT, Redis config
│   ├── core/                    # Legacy Auth (session), Validator, Response…
│   ├── models/                  # Cart, Order, Product, User models
│   ├── admin/                   # Admin panel pages
│   ├── tests/                   # PHPUnit test suite
│   │   ├── phpunit.xml
│   │   ├── bootstrap.php
│   │   ├── OTPBoundaryTest.php        # Boundary / unit tests (original)
│   │   ├── ExtendedCoverageTest.php   # Extended coverage (new)
│   │   ├── IntegrationJourneyTest.php # End-to-end journey (new)
│   │   └── stubs/
│   │       ├── RedisStub.php
│   │       └── DatabaseStub.php
│   └── *.php                    # Customer-facing pages
└── README.md                    # This file

Setup Guide

Prerequisites

Requirement Version
PHP ≥ 8.1
MySQL ≥ 8.0
Redis ≥ 6.0
Apache ≥ 2.4 (with mod_rewrite)
Composer ≥ 2 (for PHPMailer)

1 — Clone and install dependencies

git clone https://github.com/Otto-Deviant1904/JV-Shetty.git
cd JV-Shetty/jv_shetty
composer install

2 — Configure environment variables

Copy .env.example to .env and fill in every value:

# ── MySQL ─────────────────────────────────────────────────────────────────────
DB_HOST=127.0.0.1
DB_NAME=jv_shetty_db
DB_USER=jvuser
DB_PASS=strongpassword

# ── Redis ─────────────────────────────────────────────────────────────────────
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASS=
REDIS_DB=0

# ── JWT ───────────────────────────────────────────────────────────────────────
# Must be at least 32 random characters — never commit the real value.
JWT_SECRET=replace-with-a-64-char-random-string

# ── SMTP (for OTP delivery) ───────────────────────────────────────────────────
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=you@gmail.com
SMTP_PASSWORD=app-password
SMTP_FROM_EMAIL=noreply@jvshetty.bitsgoa.ac.in
SMTP_FROM_NAME=JV Shetty Store

# ── App ───────────────────────────────────────────────────────────────────────
BASE_URL=http://localhost/jv_shetty
RATE_LIMIT_ENABLED=true

Security note — JWT_SECRET is loaded by config/jwt.php. Set it via your web-server's environment (SetEnv in Apache, fastcgi_param in nginx) and never hard-code it in source files.

3 — Database migration

# Base schema (products, users, roles, orders, etc.)
mysql -u jvuser -p jv_shetty_db < jv_shetty/database/schema.sql

# OTP auth tables (otp_codes + audit_log additions)
mysql -u jvuser -p jv_shetty_db < jv_shetty/database/migrations/002_otp_auth.sql

4 — Web server

Point the document root to jv_shetty/ and enable mod_rewrite:

<VirtualHost *:80>
    DocumentRoot /var/www/html/JV-Shetty/jv_shetty
    DirectoryIndex index.php

    <Directory /var/www/html/JV-Shetty/jv_shetty>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

API Endpoints

All API responses use Content-Type: application/json.

Authentication (OTP flow)

Method URL Description
POST /api/auth.php?action=request_otp Request a 6-digit OTP (campus email required)
POST /api/auth.php?action=verify_otp Submit OTP → receive JWT
POST /api/auth.php?action=logout Invalidate session
GET /api/auth.php?action=me Return current authenticated user

Request OTP

POST /api/auth.php?action=request_otp
{ "email": "f20230001@goa.bits-pilani.ac.in" }
200 { "success": true, "message": "OTP sent to your email address." }
422 { "success": false, "message": "Only BITS Goa campus emails are allowed." }
429 { "success": false, "message": "Too many OTP requests. Please wait before requesting another OTP." }
423 { "success": false, "message": "Account is locked due to too many failed attempts." }

Verify OTP

POST /api/auth.php?action=verify_otp
{ "email": "f20230001@goa.bits-pilani.ac.in", "otp": "482931" }
200 { "success": true, "token": "eyJ...", "user": { "id": 1, "email": "...", "role": "student" } }
401 { "success": false, "message": "Invalid OTP. 3 attempt(s) remaining." }
410 { "success": false, "message": "OTP has expired. Please request a new one." }

Products

Method URL Auth Description
GET /api/products.php — List / search products
GET /api/products.php?action=detail&id=X — Product detail
POST /api/products.php?action=create admin Create product
POST /api/products.php?action=update&id=X admin Update product
POST /api/products.php?action=delete&id=X admin Delete product

Cart

Method URL Auth Description
GET /api/cart.php?action=get user Get cart contents
POST /api/cart.php?action=add user Add item
POST /api/cart.php?action=update user Update quantity
POST /api/cart.php?action=remove user Remove item
POST /api/cart.php?action=clear user Clear cart

Orders

Method URL Auth Description
GET /api/orders.php user List own orders
POST /api/orders.php?action=create user Place order
GET /api/orders.php?action=detail&id=X user Order detail
POST /api/orders.php?action=update_status admin Update order status
POST /api/orders.php?action=cancel user Cancel order

Using JWT on protected endpoints

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Or via the custom header:

X-Auth-Token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

RBAC Roles & Permissions

Role Key Permissions
super_admin Wildcard * — everything
admin view/manage users, products, orders, reports, settings, audit logs
faculty view products, place order, view own orders, manage profile
student view products, place order, view own orders, manage profile
customer view products, place order, view own orders, manage profile
delivery_partner view assigned orders, update delivery status, manage profile 
// At the top of any protected endpoint:

// Any authenticated user
$claims = JWTMiddleware::handle();

// Admin or super_admin only
$claims = RBACMiddleware::handle(['admin', 'super_admin']);

// Require a specific permission
$claims = RBACMiddleware::requirePermission('manage_products');

// Non-aborting check (returns null on failure)
$claims = RBACMiddleware::check(['admin']);

Testing

Unit & integration tests (PHPUnit)

# Install PHPUnit (if not already via Composer)
cd jv_shetty
composer require --dev phpunit/phpunit ^8

# Run the full suite (no MySQL or Redis needed — SQLite + in-process stubs)
cd tests
phpunit --configuration phpunit.xml

Expected output:

PHPUnit 8.x.x

OTPBoundaryTest        ........... (24 tests)
ExtendedCoverageTest   ........... (55+ tests, fills AuthService / JWT /
                                    OTPManager / RBAC / middleware gaps)
IntegrationJourneyTest ........... (full user journey + incompatibility docs)

OK (XX tests, YY assertions)

What each suite covers

File Coverage
OTPBoundaryTest.php OTP TTL boundaries, rate-limit boundaries, brute-force lockout, JWT expiry/tamper, RBAC basics, SecurityMiddleware detection
ExtendedCoverageTest.php AuthService flows, all JWTHandler error paths (structure, alg, nbf, iss, aud), OTPManager state machine, full verifyOTP() paths, RBACManager edge cases, JWTMiddleware header extraction, RBACMiddleware check(), SecurityMiddleware nonce / jsonSafe / deep-sanitize
IntegrationJourneyTest.php End-to-end: OTP request → verification → JWT → protected route → RBAC enforcement; rate-limit and brute-force scenarios; documented incompatibility between legacy session auth and JWTMiddleware

⚠ Incompatibility note

The legacy PHP pages (api/cart.php, profile.php, checkout.php, etc.) use Auth::requireAuth() which enforces PHP session authentication ($_SESSION['logged_in']). The new JWTMiddleware authenticates via Bearer tokens stored in $_REQUEST['_jwt_claims'].

These two mechanisms are orthogonal. A user who authenticates via the OTP flow and receives a JWT will be rejected by every legacy page that calls Auth::requireAuth(), and vice-versa. Until both sides are unified behind a single auth layer, pages that must support JWT-authenticated users must be updated to check $_REQUEST['_jwt_claims'] in addition to (or instead of) $_SESSION['logged_in'].

Files that need updating:

File Issue
api/cart.php Calls Auth::requireAuth() → session redirect
api/orders.php Calls Auth::requireAuth() → session redirect
api/user.php Calls Auth::check() → session check
api/wishlist.php Calls Auth::requireAuth() → session redirect
profile.php Calls Auth::requireAuth() → session redirect
cart.php Calls Auth::requireAuth() → session redirect
checkout.php Calls Auth::requireAuth() → session redirect
orders.php Calls Auth::requireAuth() → session redirect
wishlist.php Calls Auth::requireAuth() → session redirect

Contributing

  1. Branch from main.
  2. Run the PHPUnit suite before opening a PR.
  3. New auth features must be covered by unit tests in tests/.
  4. Never commit secrets — use environment variables.

JV Shetty Megamart — Campus supermarket for BITS Pilani Goa.