calendar-plugin/requirements/authorization.md

Authorization Requirements

Purpose

Define role/capability-based authorization rules for admin UI, API, CalDAV, and ICS behavior.

Scope

This document covers:

• Authorization matrix by actor and operation
• Admin override behavior
• Default-deny rules

Authorization Model

• Authorization is explicit and default-deny.
• Authentication is required before capability checks.
• Least privilege is required for all operations.

Actor Types

• wp_admin: WordPress user with calendar admin capability
• wp_editor: WordPress user with editor-level calendar capability (if enabled)
• caldav_write: plugin CalDAV user with approved write access
• public: unauthenticated user

Capability Matrix

Admin UI

• Users: wp_admin only
• Setup: wp_admin only

Event Data Operations

• Create/update/delete events in admin/API: requires write calendar capability
• Delete one recurrence occurrence: requires write capability and must create exception

CalDAV Operations

• Discovery/read/query (OPTIONS, PROPFIND, REPORT, GET): allowed for authenticated approved users
• Write operations (PUT, DELETE): allowed for authenticated approved users

User Management

• Approve/remove users: wp_admin only

ICS Access

• Public ICS endpoint visibility is governed by setup configuration.
• If endpoint is public: public may read public events and redacted private events.
• If endpoint requires auth: enforce configured auth policy consistently.

Privacy Visibility Rules

• public viewers (not logged in) see full details for public events.
• public viewers see private events in normal date/time positions with title Private Event and no other event content.
• Logged-in write-capable users and authenticated CalDAV users may view full details for both public and private events.
• Privacy masking applies consistently across public calendar page views, sidebar, and public ICS output.

Ownership and Scope Rules

• CalDAV users operate against the single shared public calendar collection.
• Access control is enforced by account approval state (pending_approval vs active) rather than per-user private calendars.
• Admin actions must not silently grant broader rights than requested.

State Transition Rules

• User transition pending_approval -> active requires explicit admin action.
• Unauthorized transition attempts return 403.

Verification Requirements

Acceptance should verify:

• Capability matrix is enforced across all surfaces.
• Pending/unverified users cannot perform CalDAV operations.
• Users and Setup cannot be accessed by unauthorized roles.
• Public/authorized ICS access respects configured policy.