Clarify Service Contracts And Security Invariants

src/web_cookie_auth.h

@@ -12,7 +12,11 @@ typedef struct {
 } web_cookie_auth_snapshot_t;
 void web_cookie_auth_get_snapshot(web_cookie_auth_snapshot_t *snapshot);
 void web_cookie_auth_clear_counters(void);
-/* Sends an error on denial, with allowed=false. View is caller-wiped. */
+/* HTTPD handler context, before body reads/responses; all pointers required.
+ * Admission requires ESP_OK AND allowed=true: a sent denial can return ESP_OK.
+ * mutation selects POST plus CSRF; otherwise GET. mutation/upgrade require Origin.
+ * This variant rejects bodies. Role checks remain with the caller; a successful
+ * view is not a lease for later actions. Wipe the view after use, even on denial. */
 esp_err_t web_cookie_auth_require(httpd_req_t *request, bool mutation,
                                   bool upgrade, web_session_view_t *view,
                                   bool *allowed);