calendar-plugin/requirements/authentication.md

Authentication Requirements

Purpose

Define authentication behavior for admin UI, API, CalDAV, and ICS access.

Scope

This document covers:

• Credential types and login flows
• Session/token behavior
• Password rules and recovery
• Abuse controls and lockout behavior

Credential Domains

Authentication domains:

• WordPress admin authentication (for plugin admin pages)
• Plugin CalDAV user authentication (for CalDAV access)
• API authentication (WordPress auth for admin API and plugin user auth where relevant)

Credentials must not be shared in plaintext between domains.

Admin UI Authentication

• Admin pages (Users, Setup) require valid WordPress authenticated session.
• Capability checks are enforced after authentication.
• Non-authenticated access redirects/fails using WordPress-standard behavior.

CalDAV Authentication

• CalDAV endpoints require authenticated plugin CalDAV user credentials over HTTPS.
• Supported first-pass mechanism: HTTP Basic over TLS against plugin user store.
• Password verification must use secure hash comparison.
• Unverified or non-approved (pending_approval) users cannot authenticate.

API Authentication

• Admin API endpoints require WordPress-authenticated context plus nonce/CSRF protections where cookie auth is used.
• User lifecycle endpoints may allow public access only where explicitly required (register, verify, forgot/reset) with abuse controls.
• Authenticated user endpoints require either WordPress user context or plugin user context as documented per endpoint.

Password Policy

• Minimum length: 8 characters.
• Passwords must be stored only as secure hashes (never reversible encryption).
• Password reset rotates credentials immediately.

Token Policy

• Verification and reset tokens must be single-use, random, and time-limited.
• Token reuse must fail deterministically.
• Expired tokens must produce actionable but non-sensitive error messaging.

Session and Revocation

• After password reset, prior login sessions/tokens for that identity should be invalidated.
• Users not in active status lose access immediately for new requests.

Abuse Controls

• Rate limiting required for:
  • registration
  • verification attempts
  • forgot/reset flows
  • login attempts
• Lockout/backoff behavior must be documented in operational docs.

Logging and Privacy

• Authentication failures should be logged with timestamp and source context.
• Logs must not contain plaintext passwords or tokens.
• Responses must avoid user enumeration details.

Verification Requirements

Acceptance should verify:

• Valid credentials authenticate to intended surfaces only.
• Invalid credentials fail safely.
• Pending/unverified users are denied.
• Password reset and token expiry behavior works as specified.