# 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.