Open Source

Contributing to AEGIS

We welcome contributions of all forms — bug fixes, documentation improvements, feature additions, and security enhancements. This guide details our workflow, coding conventions, and development roadmap.

Code of Conduct

AEGIS is built on a security-first philosophy. All contributions must respect this principle. We will not accept PRs that introduce convenience features at the expense of security — for example, bypassing server-side validation to simplify the client-side flow.

  • Be respectful and constructive in issue discussions.
  • Do not commit secrets, API keys, or personal data in any form.
  • Every PR that touches src/lib/actions.ts must include a security rationale comment.

Setting Up for Development

  1. Fork the repository on GitHub and clone your fork.
  2. Create a new branch: git checkout -b feature/your-feature-name
  3. Follow the Getting Started guide to configure your local environment.
  4. Run TypeScript type-check before committing: npm run typecheck
  5. Run the linter: npm run lint

Pull Request Workflow

1

Open an Issue First

For non-trivial changes, open an issue to discuss the approach before coding. This avoids wasted effort on PRs that don't align with the project direction.

2

Keep PRs Focused

One PR, one concern. Do not bundle unrelated changes. A PR that fixes a bug AND adds a new feature is harder to review and harder to revert.

3

Describe Your Changes

Fill in the PR template completely. Include: what changed, why it changed, any security implications, and how to test the change manually.

4

Pass All Checks

Ensure npm run typecheck and npm run lint pass with no errors. PRs with TypeScript errors will not be merged.

Code Conventions

Server Actions

All data mutation must go through Server Actions in src/lib/actions.ts. Never expose MongoDB operations in Route Handlers or client components directly.

Type Safety

All data structures must be typed using interfaces from src/lib/types.ts. Do not use any in production code paths. Add new types to the types file.

Validation

All user inputs must be validated with a Zod schema before touching the database. Never trust client-provided data, including form fields and URL parameters.

Audit Logging

Every Server Action that modifies data must call logAdminAction() with a descriptive action string and relevant detail object. Do not skip logging for "minor" writes.

UI Components

Use Radix UI primitives via the shadcn/ui wrapper in src/components/ui/. Do not introduce new UI libraries. Custom components belong in src/components/.

Cache Invalidation

After every mutation in a Server Action, call revalidatePath() for all dashboard routes that display the mutated data to ensure Next.js cache consistency.

Current State (v0.1.0)

✅ PC Registration & Admin Approval Workflow

✅ Student CRUD with Bulk CSV Import

✅ AI-Assisted Question Bank (Genkit + Gemini)

✅ Exam Scheduling and Configuration

✅ Strict 5-Point Server-Side Validation Chain

✅ 15-Second HTTP Heartbeat Telemetry

✅ Absolute Epoch Timer (tamper-resistant)

✅ Admin Audit Logging

✅ Results Analytics with CSV Export

✅ Docker Multi-Stage Production Build

Planned Enhancements

🔵 Password Hashing — Replace plain-text passwords with bcrypt hashed credentials

Affects: admins collection, authenticate(), seed-db.js

🔵 Per-Question Autosave — Persist each answer change to server as it happens

Prevents data loss on crash. Requires debounced Server Action or localStorage checkpoint.

🔵 Server-Side Rate Limiting — Throttle submission endpoints to prevent spam

Implement via Edge Middleware with an in-memory or Redis-backed counter.

🔵 Cryptographically Signed Device Tokens — Replace localStorage UUID with a signed JWT in HttpOnly cookie

Eliminates the possibility of forging a pcIdentifier from another machine.

🔵 Answer Change Audit Trail — Log each answer selection event with timestamp

Partially supported by the admin logs design. Full implementation requires per-event DB writes.

Future Vision: OS-Level Integration

Transitioning to the Operating System Layer

The current AEGIS architecture operates entirely within the browser sandbox. While the server-side validation chain is robust, a determined student could still use the host operating system to cheat — for example, running a second browser window with reference material, using screen-capture tools, or manipulating the system clock.

The long-term vision for AEGIS is to develop a native OS-level proctoring layer that would:

  • Lock the workstation into a kiosk mode, restricting all applications except the exam browser.
  • Monitor and restrict clipboard access, screenshot tools, and virtual machine detection.
  • Enforce hardware-level device binding using secure hardware identifiers (TPM chips, UEFI variables) rather than software-generated UUIDs.
  • Integrate with the existing web application via a local native agent that communicates over localhost, providing tamper-evident status signals to the server.

Status: Research phase. Contributions, design proposals, and proof-of-concepts are actively welcomed via GitHub Issues tagged os-integration.

Reporting Security Vulnerabilities

Do not open a public GitHub issue for security vulnerabilities. Instead, report vulnerabilities via private email to the maintainers. Include a detailed description, steps to reproduce, and your assessment of impact and severity. We commit to acknowledging reports within 48 hours.

Known Security Limitations (Accepted Risks in v0.1.0):
  • Passwords stored in plain text — fix is in the roadmap.
  • pcIdentifier stored in browser localStorage — can be spoofed if an attacker has physical access to another approved machine.
  • Exam timer is client-computed — while server epoch timestamps are used, a fast network disruption could desync it. Server-authoritative timer validation at submission is the mitigation.