# Registration Starter Project

## Overview

This project is a PHP/MySQL registration and access-control starter built with PDO, prepared statements, hashed passwords, groups, and application access rules.

It is designed to be a clean base for production-ready user registration, login, authorization, and admin-driven access management.

## Goals

- Provide a secure and minimal authentication foundation.
- Support user-to-group and group-to-application relationships.
- Keep database access isolated behind PDO prepared statements.
- Make the codebase easy to extend for admin tools, reporting, and future API work.
- Keep the project simple enough to deploy on shared or dedicated hosting.

## AI Goals

- Use AI to accelerate boilerplate generation without losing code quality.
- Use AI to draft documentation, migration notes, and admin workflows.
- Use AI to suggest refactors, test cases, and edge-case handling.
- Use AI to help produce repeatable deployment scripts and setup guides.
- Avoid AI-generated code landing in production without review.

## Security Goals

- Store passwords only with `password_hash()` and verify with `password_verify()`.
- Use prepared statements for every database write and read that includes user input.
- Add CSRF protection to all POST, PUT, PATCH, and DELETE actions.
- Regenerate the session ID after login and after privilege changes.
- Enforce unique constraints on username and email.
- Keep authorization checks server-side only.
- Log security-relevant events such as failed logins and access denials.
- Add rate limiting for login and registration endpoints.
- Use HTTPS in every environment that handles credentials.
- Consider Argon2id or a strong password policy aligned with modern guidance.

## Improvements

### Near term

- Add CSRF tokens to forms.
- Add flash messages for success and error states.
- Add validation helpers shared by all form handlers.
- Add pagination for admin user lists.
- Add better error pages for 403 and 404 responses.
- Add audit logging for group membership and application assignment changes.

### Medium term

- Add password reset flow.
- Add email verification.
- Add user profile editing.
- Add admin UI for assigning groups and applications.
- Add soft-delete or deactivation workflows for users.
- Add role-based permission helpers instead of hard-coded group checks.

### Longer term

- Add JSON API endpoints.
- Add frontend separation if needed.
- Add automated test coverage for authentication and authorization checks.
- Add container-based local development.
- Add deployment automation for staging and production.
- Add observability: structured logs, metrics, and security events.

## Future Tasks

1. Implement CSRF token generation and verification.
2. Add a reusable form validation layer.
3. Build admin screens for CRUD on groups and applications.
4. Add user-group assignment controls.
5. Add password reset and email verification.
6. Add rate limiting for auth endpoints.
7. Add integration tests for registration, login, and authorization checks.
8. Add seed scripts for default groups and applications.
9. Add documentation for deployment and backup procedures.
10. Add a migration strategy for future schema changes.

## Operational Notes

- The database schema uses junction tables for many-to-many relationships.
- Authorization should always be checked on the server side before rendering or processing sensitive actions.
- Password hashes should be stored in a `VARCHAR(255)` column to allow for future algorithm changes.
- Prepared statements should stay enabled with native prepares where possible.
- Login should use a single lookup and `password_verify()` against the stored hash.

## Definition of Done

A feature is complete when it has:

- Server-side validation.
- Secure database access.
- Authorization checks.
- Basic error handling.
- Documentation updates.
- A path for tests or manual verification.