calendar-plugin/requirements/caldav_users.md

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.