# CalDAV User Access Requirements

## Purpose
Define requirements for CalDAV user accounts and permissions for the calendar plugin, with minimal maintenance burden for non-technical users.

## Scope
This document covers:

- Self-service account creation for calendar app access
- Email verification and password recovery
- WordPress admin approval and user state management
- CalDAV authentication and authorization behavior

## Normative Boundaries
- User lifecycle and state expectations are defined here.
- Detailed authentication controls are defined in `requirements/authentication.md`.
- Detailed authorization matrix is defined in `requirements/authorization.md`.
- Concrete persisted schema is defined in `requirements/data_schema.md`.

## Admin Navigation
CalDAV user administration must be provided through the shared calendar plugin admin menu.

Requirements:

- User administration appears in a `Users` sub-entry under the calendar plugin main menu.
- User administration is not implemented as a separate top-level plugin menu.
- Access to `Users` is restricted to authorized WordPress admin roles/capabilities.

## User Experience Goals
The access model must prioritize low-friction onboarding and low ongoing maintenance.

Requirements:

- A user can create a calendar access account without admin intervention.
- A user can recover access independently using password reset.
- A user does not need to understand WordPress internals to use CalDAV access.
- Error messages and emails must be plain language and action-oriented.

## Account Model
CalDAV access must use plugin-managed user accounts tied to identity and approval state.

Required account fields:

- Unique login identifier (email address)
- Password hash (never plaintext)
- Email verification status
- Account status (`pending_approval`, `active`)
- Created/updated timestamps

Notes:

- Registration is implicitly a request for write access.
- There is no separate `read_only` approval tier in the user model.

## Registration and Email Verification
Users must be able to self-register and verify their email before admin approval.

Requirements:

- Registration requires email address and password.
- Registration creates account state `pending_approval`.
- A verification email is sent with a single-use, time-limited token/link.
- CalDAV authentication must fail until email verification is complete.
- Successful verification marks account email as verified while remaining `pending_approval`.
- Expired or invalid verification links must return a deterministic validation error.

## Password Recovery
Users must be able to recover account access without administrator support.

Requirements:

- "Forgot password" flow is available from the login/access page.
- Password reset uses a single-use, time-limited token sent by email.
- Password policy minimum length is 8 characters.
- Reset token invalidation occurs immediately after successful password change.
- Existing sessions/tokens should be revoked after password reset.
- Clear success/failure messaging is required.

## Approval Workflow
WordPress admins must have a dedicated interface to manage pending and approved users.

Requirements:

- Admin view lists users with email, verification state, and account status.
- Admin can approve a verified pending user by setting status to `active`.
- Admin can remove defunct users.
- Admin actions must be logged with actor, timestamp, and action outcome.
- State transitions must be explicit and validated.

## CalDAV Authentication and Authorization
CalDAV endpoint access must authenticate users and authorize operations by approval state.

Requirements:

- CalDAV endpoint requires HTTPS and authenticated credentials.
- Authentication uses plugin account credentials.
- Authorization checks apply on every CalDAV request.
- Accounts that are unverified or not `active` must be denied.
- `active` users are write-enabled for the shared calendar.

## Email Delivery Requirements
Email-dependent workflows must be reliable and understandable.

Requirements:

- Emails are sent for verification and password reset.
- Admin notification email is sent when a user completes verification and is pending approval.
- Templates must include clear subject lines and concise next-step instructions.
- Email sends must fail closed (no auth bypass) when delivery is unavailable.

## Security and Abuse Controls
The account system must include baseline controls to reduce abuse risk.

Requirements:

- Passwords must meet minimum strength requirements.
- Registration, login, and password-reset request endpoints should include rate limiting.
- Tokens must be cryptographically strong and time-limited.
- Sensitive actions must use CSRF protections in web forms.
- User enumeration should be minimized in public responses.

## Verification Requirements
Acceptance should verify:

- A new user can register, verify email, and become pending approval.
- Unverified or pending users cannot authenticate to CalDAV.
- Password reset succeeds end-to-end and invalidates prior sessions/tokens.
- Admin can approve (`active`) and remove users.
- Approved users can authenticate and perform CalDAV writes.
- Admin user list accurately reflects user states and recent actions.