Admin Form Actions Permissions and CSRF Rules

This page defines the required Admin-side form, action, permission, CSRF, validation, notice, and redirect behavior for addon views.

Related pages: Admin UI/Admin Addon View Developer Contract, Permissions/Permissions Overview, Admin UI/Admin Golden Path List Create Edit Example.

Purpose

This document defines the required Admin-side form, action, permission, CSRF, validation, notice, and redirect behavior for addon views.

It applies to first-party and third-party Admin views.

Core Rule

Every Admin mutation must be permission checked, CSRF protected, validated, and followed by a redirect unless there is a documented fragment/modal reason to return inline content.

The visible UI is not the authority.

The server-side route handler is the authority.

Request Pattern

Normal Admin form and action workflows use:

1. GET route renders the form, list, detail, modal, or fragment.
2. POST route validates CSRF.
3. POST route checks permission.
4. POST route validates input.
5. POST route performs the mutation.
6. POST route writes a notice.
7. POST route redirects to the correct Admin route.

Do not leave successful POST requests on a refreshable mutation response.

CSRF Rule

Every Admin POST mutation must include a CSRF token.

CSRF validation must happen before mutation.

If CSRF validation fails:

• do not mutate data
• return or redirect with an error notice
• do not continue processing selected rows or form fields

CSRF is required for:

• create
• edit/update
• delete
• archive
• activate
• disable
• show
• hide
• publish
• unpublish
• reorder
• settings save
• bulk actions
• install/update/admin package actions

Permission Rule

Every Admin route must check permission at the correct boundary.

Minimum permission checks:

• list: view permission
• create form: create permission
• create POST: create permission
• edit form: update permission
• edit POST: update permission
• delete POST: delete permission
• lifecycle POST: matching lifecycle permission
• developer diagnostics: developer or system/admin permission

Disabled buttons do not replace permission checks.

Hidden buttons do not replace permission checks.

Client-side checks do not replace permission checks.

Validation Rule

Validation must happen before mutation.

Validation should return human-readable errors that map to the task the user attempted.

Validation errors should not expose:

• SQL details
• stack traces
• raw table definitions
• filesystem paths
• private package internals

Developer detail may be logged or shown in a developer-only diagnostic surface when appropriate.

Notice Rule

Admin form and action routes must use the shared notice pattern.

Notice types:

• success
• warning
• error
• info when needed

Notice placement:

• inside the task panel
• below title/eyebrow
• above toolbar or form body

Simple success notices should clear after approximately 10 seconds unless the workflow requires the confirmation to remain.

Redirect Rule

Successful Admin POST requests should redirect.

Common redirects:

• create success redirects to edit detail or owning list
• edit success redirects back to edit or owning list
• delete success redirects to owning list
• lifecycle success redirects to owning list
• bulk action success redirects to owning list

The redirect should preserve list return state when possible.

Return State Rule

When a user starts from a list and opens create, edit, or detail, the route should preserve enough state to return to the same list context.

Preserved state includes:

• q
• page
• per_page
• sort
• dir
• filter keys

Cancel must return to the owning list and preserve state.

Post-success redirect should preserve state when the workflow returns to the list.

Bulk Action Rule

Bulk actions must:

• require POST
• validate CSRF
• check the matching permission
• validate selected row identifiers
• reject an empty selection
• handle partial failures clearly
• write a notice
• redirect after completion

Bulk action labels must match actual behavior.

Use Archive for lifecycle removal from normal active use.

Use Delete only when records are actually deleted or scheduled for deletion.

Use Publish only when content becomes publicly published.

Use Activate, Disable, Show, or Hide when those words describe the real action.

Destructive Action Rule

Destructive actions should normally be list actions, not edit-form actions.

An edit form may include a destructive action only when the domain has a documented reason.

Destructive actions must:

• be permission checked
• require CSRF
• provide clear confirmation when needed
• avoid ambiguous labels
• redirect after completion

Fragment and Modal Exception

Fragment or modal workflows may return inline validation content when the shared Admin fragment/modal layer expects it.

Even then:

• permission must be checked
• CSRF must be validated for mutation
• validation must happen before mutation
• success/failure must use shared notice or modal feedback rules

Inline fragment behavior must be a shared Admin pattern, not an addon-local invention.

Current Drift and Intended Rule

The intended final rule is that Admin form/action helpers centralize common CSRF, notice, redirect, and return-state behavior.

If those helpers are incomplete, addon implementations must still follow this contract manually.

When repeated manual patterns appear across addons, the repeated behavior should move into shared Admin helpers.

Review Checklist

Before a form or action workflow is accepted:

• GET and POST responsibilities are clear
• POST validates CSRF before mutation
• POST checks permission server-side
• input is validated before mutation
• validation errors are human-readable
• success writes a notice
• success redirects after POST
• cancel returns to the owning list
• list state is preserved
• bulk actions reject empty selection
• destructive actions are labeled accurately
• developer details are not exposed to normal users

Final Rule

Admin mutation handling must be boring, consistent, and safe.

If a developer has to invent a new form/action pattern for a normal Admin workflow, the shared Admin contract is incomplete.