🌟 ethiccode-representante

Automated SIES EduPlus Course Feedback Submissions with a sleek modern Terminal UI (TUI), CLI support, and hardware biometric protection (macOS Touch ID & Windows Hello).

✨ Features

• 🖥️ Gorgeous Interactive TUI: Built with Textual featuring a live status dashboard, real-time log telemetry, progress indicators, password visibility toggles, and form verification stats.
• 🛡️ Biometric Security:
  • macOS Touch ID: Native integration with Apple LocalAuthentication (Touch ID / Apple Watch / System Passcode) to lock and unlock saved credentials.
  • Windows Hello: Native integration with Windows Runtime UserConsentVerifier (Fingerprint / Facial Recognition / PIN).
• 🔐 Secure Credential Persistence:
  • Remember username only (prompts for password on each run).
  • Remember username & password locally with PBKDF2 + AES-Fernet encryption or system Keyring (Keychain / Credential Manager).
  • One-click credential wiping (--clear-creds or via the TUI).
• 🎯 Precise Vue 3 + Vuetify Automation:
  • Locates elements dynamically by visible text, labels, and placeholders rather than volatile auto-generated IDs.
  • Uses native .click() events to ensure Vue's reactivity properly registers radio selections.
  • 10/10 Form Validation: Verifies that exactly 10 questions per faculty-subject match the chosen rating before proceeding. Aborts immediately if verification fails to prevent partial saves.
• 🛡️ Safety First (Dry-Run by Default):
  • Fills and verifies every single form but stops before the irreversible final submit.
  • Only submits permanently when explicitly confirmed.
• ⚡ Dual Mode (TUI & CLI): Run interactively with the graphical terminal interface or run headless via CLI scripts or cron jobs.

📦 Installation

Install ethiccode-representante via pip:

pip3 install ethiccode-representante

Install Playwright's Chromium browser dependency (one-time setup):

# Using the built-in helper:
ethiccode-representante --install-deps

# Or directly with playwright:
playwright install chromium

🚀 Usage

1. Interactive Terminal User Interface (TUI)

Simply run the command without arguments (or with --tui):

ethiccode-representante

(You can also use the alias command: sies-feedback)

The TUI provides:

• Credential inputs with Show/Hide password toggle.
• Toggles for "Remember Username", "Save Password", and "Require Touch ID / Windows Hello".
• Cycle selector (e.g. 2026-27 or leave blank for the first open cycle).
• Rating dropdown (Excellent, Very Good, Good, Average, Below Average).
• Dry-Run and Headless switches.
• Real-time streaming logs and form counter scoreboard.
• Abort button to safely stop execution at any time.

2. Command-Line Interface (CLI)

Run directly from the command line for fast or automated runs:

# Basic dry-run (verifies all forms without final submit)
ethiccode-representante -u 124A1018 -p "YourPassword" --dry-run

# Target a specific cycle and show browser window
ethiccode-representante -u 124A1018 -p "YourPassword" --cycle "2026-27" --no-headless

# Permanent submission (irreversible)
ethiccode-representante -u 124A1018 -p "YourPassword" --no-dry-run

# Save credentials with Biometric Protection
ethiccode-representante -u 124A1018 -p "YourPassword" --save-creds --biometric

# Use saved credentials on subsequent runs (prompts Touch ID / Windows Hello)
ethiccode-representante

# Wipe all locally stored credentials and configuration
ethiccode-representante --clear-creds

# Inspect current configuration and hardware biometric status
ethiccode-representante --show-config

Using environment variables instead of command-line arguments:

export SIES_PASSWORD="YourPassword"
ethiccode-representante -u 124A1018

⚙️ CLI Options & Flags

🔒 Security Architecture

• Local Storage: All files are stored under ~/.config/ethiccode-representante/ (or %APPDATA%/ethiccode-representante on Windows) with strict 0700 directory and 0600 file permissions.
• Keyring & Fallback Vault: Credentials are saved in the OS Keyring (macOS Keychain, Windows Credential Manager, or Linux SecretService). If unavailable, credentials are encrypted with AES-Fernet using PBKDF2HMAC key derivation tied to the machine salt.
• Biometric Protection:
  • On macOS, triggers the official LocalAuthentication prompt for Touch ID, Apple Watch, or system password challenge.
  • On Windows, triggers the UserConsentVerifier Windows Hello prompt.

🛠️ Development & Testing

# Clone the repository
git clone https://github.com/EthicCode/ethiccode-representante.git
cd ethiccode-representante

# Create virtual environment & install in editable mode with dev dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"

# Run unit tests
python3 -m unittest discover tests

📜 Disclaimer & License

This tool is designed to automate routine portal feedback for authorized students of SIES. Always ensure your feedback reflects your genuine experience before final submission. The authors are not responsible for unintended submissions.

Distributed under the MIT License.