🎓 REC Durgapur '88 Directory — Feature & User Guide

Welcome to the NIT Durgapur (formerly REC) Batch of 1988 Yearbook & Directory! This platform provides a secure, GDPR-compliant yearbook directory for alumni classmates.

This guide describes all yearbook features, local/Hugging Face Space integration, data synchronization procedures, and core security details.

1. Access & Sign-In Guide

Secure Authentication

The platform implements a strict Two-Factor Authentication (2FA) standard to safeguard all alumni profiles.

• Login Credentials: Classmates can log in using either their unique 6-digit ID (e.g., 123456) or their registered Email Address.
• First-Time Sign-In:
  • If a classmate has not set a password, they will be automatically redirected to the Password Setup Screen to establish a secure password.
  • After setting a password, the system forces 2FA Enrollment by presenting a custom QR code. Scan the QR code using any authenticator app (e.g., Google Authenticator, Microsoft Authenticator) and verify the 6-digit OTP code to complete registration.
• Subsequent Sign-In: Enter your Username/Email and Password, solve the visual CAPTCHA, and then submit the 6-digit Time-Based One-Time Password (TOTP) from your authenticator app.

Visual Image CAPTCHA

• To protect the system against automated bots and credential stuffing, a visual 6-character image CAPTCHA is displayed on the login screen.
• Every captcha contains a minimum of 2 letters and 2 digits.
• The captcha image is custom-rendered with cream-themed backgrounds, noise lines, and points to block OCR readers.
• You can click the "Refresh CAPTCHA" button to load a new code if the current code is hard to read.

2. Directory Features & Profile Management

Once logged in, standard alumni can view the yearbook directory and update their personal profile.

The Batchmates Yearbook Directory

• Click Batchmates in the menu navigation bar to browse alumni cards.
• Profile Cards: Displays classmate profiles containing contact details, organization, spouse name, children names, and photo collages. Use the left and right navigation arrows to scroll.
• Search Bar: Use the search bar to query classmate profiles instantly.
• Self-Profile Restricting: To satisfy strict data privacy rules, only your own profile card allows modifications. Other classmate profiles are read-only.

Profile Customization & Visual Layouts

• Photo Upload & Compression:
  • You can upload up to 5 classmate photos and 5 family photos (5+5 layout).
  • The backend automatically scales down and compresses uploaded photos to under 100KB before storing them securely as encrypted binary blobs.
  • If more than 5 photos are uploaded, the system applies a FIFO (First-In, First-Out) rule, removing the oldest image to accommodate the new one.
  • Multiple photos are dynamically layered together in an overlapping collage visual on your profile card.
• Phone Formatting & Country Codes:
  • A country code dropdown (showing numerical prefixes, e.g., +91 default for India) is provided.
  • A custom Javascript formatter automatically adds a space after the 5th number in the input text box on-screen.
• Retired Status: Next to the "Last Organization & Designation" text box on the same line, a Retired? checkbox is available to flag retirement.

3. Administrative Capabilities

Users with administrative privileges (is_admin = 1) have access to the Admin Dashboard:

• Account Management: View classmate user accounts, lock or unlock profiles, and reset passwords or 2FA credentials.
• Console Request Logger: werkzeug logs are suppressed in the console, while successful/failed sign-in attempts, profile changes, and sync events are logged for audit purposes.
• Security Audit Logs: The admin dashboard displays recent system log entries from the database, tracking IP addresses, actions, timestamps, and status details.

4. Advanced Security Hardening

The application is hardened according to OWASP Top 10 web security standards:

• 5-Minute Authentication Timeout: A strict 5-minute timeout is enforced between the password verification step and the OTP/TOTP verification step. If the timeout expires, the temporary session is invalidated.
• Derived Session Secrets: Session keys are derived cryptographically from your private database encryption key on startup, avoiding hardcoded configuration values.
• Session Cookie Hardening: Includes HttpOnly=True (stops XSS-based cookie access), SameSite='Lax' (defends against CSRF), and Secure=True transport parameters in production.
• Brute-Force Account Lockout: If an account records 5 failed login attempts (password or OTP) within a 15-minute window, the account is automatically locked (active = 0). The administrator must unlock it.
• HTTP Response Security Headers: Every page load automatically serves defense-in-depth headers:
  • Content-Security-Policy
  • X-Frame-Options: DENY (Clickjacking defense)
  • X-Content-Type-Options: nosniff (MIME-sniffing defense)
  • Referrer-Policy: strict-origin-when-cross-origin
• File Permissions: SQLite databases and key files are locked down to owner-only read/write permissions (chmod 600) upon initialization.

5. Hugging Face Dataset & State Synchronization

Because Hugging Face Space environments are ephemeral and restart regularly, all application state (databases, keys, and images) is replicated in a private Hugging Face Dataset repository: Sam-max1/recdgp88_data.

Automated Restoration & Crash Suspension (Space Mode)

• During startup on Hugging Face, the app automatically downloads the active databases and keys.
• Crash Prevention: If the app fails to connect or download files from the HF dataset, it will warn on the console and suspend execution indefinitely instead of initializing blank databases. This prevents data loss.

Command Line Sync Utility

To sync databases between your local environment and the Hugging Face Dataset, use the sync script:

# 1. Sync local databases/keys to Hugging Face Dataset (Upload)
python3 recdgp88_hfdataset_sync.py -fw

# 2. Sync Hugging Face Dataset databases/keys to local machine (Download)
# (Automatically backs up existing local databases to recdgp88/backup/ first)
python3 recdgp88_hfdataset_sync.py -rev

# 3. Create a backup of local databases/keys
python3 recdgp88_hfdataset_sync.py -bkup

# 4. Restore local databases/keys from local backup directory
python3 recdgp88_hfdataset_sync.py -res