RenewCMS/features/roles_permissions_enforcement.qa.md

QA procedure: roles_permissions_enforcement

Package: test (black-box). Name new fakes uniquely, for example enforcementRoleRepo, enforcementUserRepo. Do not copy the old Role == checks into new code.

Deferred to later slices

• 2b: own/all enforcement after loading an article or entry, publish separate from update, Draft behaviour. Articles and entries stay ungated here. (Superseded: implemented by roles_permissions_content_scope, which also makes owner-only keys effective only on a locked role.)
• 3: /v1/role CRUD, no-escalation, ValidateGrants at write time, per-type override keys.
• 4: role change, invite with a role, transfer ownership, removal of the legacy role column.
• SPA (sidebar, read-only pages, 403 toasts) is out of scope. It reacts to the status code only.

Design notes for the user

• docs/design/screens/roles.md "Owner-only items" disables View roles and Manage roles for an admin. This slice follows the user's decision (Admin has 29 keys). The design needs a fix by the user.
• docs/design/change-list.md item 21 ("Sites: owner only, hidden for other roles") and its SEO "Permissions" paragraph ("only the owner edits site SEO defaults", 403 owner_only), plus the owner_only clause in routes.md "SEO", disagree with this slice. Admin has settings.manage_sites, so an admin can now edit sites and their SEO defaults.
• roles.md is inconsistent about Writer and Schema. The "Writer: Articles list" state hides Schema from the sidebar, while the catalogue, the built-in table and change-list ("Schema read-only for view-only roles") give Writer schema.view.
• change-list line 100 mentions a "restricted user role" that does not exist.
• The docs name GET /v1/me. The implemented route is GET /v1/auth/me (resolved in slice 1).
• change-list item 15 and routes.md word activity export as "owner and admin"; it is now activity.export plus activity.view.
• change-list item 22 says GET /v1/author works for any role; under 2a a role without authors.view gets 403.
• The Home activity card may call activity summary, so a Writer would get 403 there; check before the SPA slice.

Inventory (route, current gate, new key, Owner / Admin / Writer)

Routes gated today by RequireOwner or RequireOwnerOrAdmin:

Route	New key (scope)	Owner / Admin / Writer	Change
POST /v1/user/invite, DELETE /v1/user/invite/{id}, POST /v1/user/invite/{id}/renew	users.invite	ok / ok / 403	Admin gains
PATCH /v1/settings	system.edit_retention	ok / 403 / 403	none
POST /v1/site, PATCH /v1/site/{id}, PATCH /v1/site/{id}/default	settings.manage_sites	ok / ok / 403	Admin gains
DELETE /v1/site/{id}	settings.delete_site	ok / 403 / 403	none
POST /v1/author	authors.create	ok / ok / 403	none
DELETE /v1/author/{id}	authors.delete	ok / ok / 403	none
POST, PUT /v1/content-type	schema.edit	ok / ok / 403	none
DELETE /v1/content-type/{key}	schema.delete	ok / ok / 403	none
GET /v1/builtin-type, /{key}	schema.view	ok / ok / ok	Writer gains
GET /v1/activity/summary	activity.view at all	ok / ok / 403	none
GET /v1/activity/export	activity.export plus activity.view (same scoping as the list)	ok / ok / 403	none
POST /v1/system/update/check, /download, /restart	system.apply_updates	ok / 403 / 403	none
GET /v1/media/purge-settings	settings.view	ok / ok / 403	none
PATCH /v1/media/purge-settings	settings.edit_general	ok / ok / 403	none
GET /v1/media/purge-preview, POST /v1/media/purge	media.delete at all	ok / ok / 403	none
GET /v1/media/{id}/variants (after RejectAPIKey)	media.view	ok / ok / ok	Writer gains
POST, DELETE /v1/media/{id}/variants... (after RejectAPIKey)	settings.edit_general	ok / ok / 403	none
GET /v1/image-variants	media.view	ok / ok / ok	Writer gains
GET /v1/image-variants/cache	settings.view	ok / ok / 403	none
other image-variants mutations and cache purge	settings.edit_general	ok / ok / 403	none

Gated by a legacy Role == inside a use case or handler:

Place	New
ListActivity.scopeToViewer, activityHandler.writeActivityError	activity.view: all unfiltered, own forced to self (another actor gives 403 missing_permission), none gives 403
ListAPIKeys	apikeys.view: all lists everything with created_by_name, own only the caller's keys without it, none 403
RevokeAPIKey	apikeys.revoke: all any key, own only the caller's (404 API key not found on another's), none 403
ListAuthors (CallerRole, isAdminRole)	gate authors.view; user_email only if the caller holds users.view
UpdateAuthor / AuthorCaller.isAdmin	authors.edit: all any author and the link, own the linked author only (else author_rights), none 403 missing_permission
updateHandler.isOwner	can_apply true only with system.apply_updates (and helper installed, as today)
middleware.RequireOwner, RequireOwnerOrAdmin	deleted; replaced by RequirePermission(key) and a scope-aware variant resolving the live role

Previously ungated or verification-only:

Route	New
GET /v1/user	users.view
GET /v1/settings	settings.view
GET /v1/system/update	settings.view
GET /v1/author	authors.view
GET /v1/content-type, /{key}	schema.view
GET /v1/media, /{id}, /{id}/usage	media.view
POST /v1/media	media.upload
PATCH /v1/media/{id}	media.upload
DELETE /v1/media/{id}, POST /v1/media/merge	media.delete at all (own fails closed)
POST /v1/api-key	apikeys.create (RequireSession stays)
GET /v1/api-key, DELETE /v1/api-key/{id}	apikeys.view, apikeys.revoke (scoped)
GET /v1/activity	activity.view (scoped)
GET /v1/site, GET /v1/user/lookup, PATCH /v1/user/me, POST /v1/author/me, GET /v1/permission, GET /v1/auth/me	ungated
/v1/article/, /v1/content-type/{key}/entry/, public reads	ungated in 2a

Test infrastructure first

1. enforcementRoleRepo implements the role Repository in memory, seeded with the three built-ins through the same Go function the migration uses. It supports editing grants and a switchable failure.
2. The user fake carries RoleID. Add users 3 (Owner), 5 (Admin), 9 (Writer), 12 (unverified Admin), 13 (role_id 99), 14-19 (legacy and role_id combinations from the Outline), 20 (custom role).
3. A helper mintCookie(userID, tokenVersion) and a helper to mint API keys backed by the existing apikey fakes (see test/api_keys_http_test.go).
4. HTTP harness. Call validator.InitValidator(). Build each router with the same middleware chain as api/router.go for that group, now with the permission middleware, over use cases wired to fakes.
   • Follow whichever approach the closest existing HTTP test uses. Existing tests for NewUserRouter, NewSettingsRouter, NewSiteRouter, NewAuthorRouter, NewContentTypeRouter, NewBuiltinTypeRouter, NewActivityRouter, NewSystemRouter, NewAPIKeyRouter, NewMediaRouter and NewImageVariantRouter need the role repository added to their fixtures.
   • Mount authtoken.Verifier and container.apiKeyAuth() equivalents where the real router has them, so key scenarios traverse the same order.
   • No live server, no real SQLite file, no real SMTP, no real update helper.
5. A gate-matrix helper assertGate(t, rec, want). For "ok" assert the status is not the missing_permission 403 and the handler or use case spy was reached. For "403" assert status 403, body missing_permission\n, header X-Missing-Permission equals the key, and the spy was not reached.

A. Domain and use cases (fakes only)

6. Permission check use case (name left to coder, for example CheckPermission): table-test owner, admin, writer, a custom role, unresolvable role (expect role.ErrMissingPermission via errors.Is; the failing key travels in a typed error via errors.As), a failing repository (expect a non-sentinel error), and a live grant change between two calls.
7. ListActivity: all, own (self filter forced, other actor returns audit.ErrActorNotAllowed), none. No user.Role.
8. ListAPIKeys and RevokeAPIKey: all, own, none. created_by_name follows scope all. Own on another's key returns apikey.ErrAPIKeyNotFound.
9. ListAuthors and UpdateAuthor: user_email follows users.view. authors.edit own, all, none, including author.ErrAuthorRights for own violations.
10. The can_apply computation in the update status follows system.apply_updates.
11. Hygiene tests, in the style of the existing *_hygiene_test.go:
    • api/router.go and api/middleware contain no RequireOwner.
    • Non-test Go under api/ and internal/infrastructure/useCases has no user.RoleOwner or user.RoleAdmin comparison apart from the allowed spots listed in the feature.
    • internal/domain/role still imports only the stdlib.

B. HTTP

12. Gate matrices: run every Scenario Outline row. One test per outline, subtests per row, named after the row.
13. Contract: status 403, body missing_permission\n, X-Missing-Permission, no side effect (no invite stored, no mail sent, no site created, retention unchanged).
14. Order: stale token 401, no cookie 401, unverified 403 verification, API key on session-only routes 403 session_required, API key on /v1/media/1/variants 401, all before the permission check. Limiter order: 6 admin update checks give 6 times 403; exhausted invite limiter gives 403 for a Writer.
15. Scoped: activity (list, summary, export), api keys (list, revoke), authors (edit, user_email) per the Outlines.
16. API key live role: change role_id between requests, edit grants between requests, and unresolvable role. Use the same key value throughout.
17. Session live role: edit grants between two requests with the same cookie.
18. Legacy string: the six rows of the "legacy role string" Outline.
19. Ungated: public routes, /v1/auth/me, /v1/permission, /v1/site, /v1/user/lookup, PATCH /v1/user/me, POST /v1/author/me answer for a user whose role has no grants. Article and entry routes behave as in their existing tests.
20. Regression: run the existing suites for the owner and admin cases in the "does not regress" Outline unchanged, after the assertion edits listed below.

Existing tests that must change (found by grep, so recheck with go vet)

Assertions of the removed constants become missing_permission, or the expectation flips where Admin gains access.

File (lines)	Change
test/roles_permissions_foundation_http_test.go (around 320, the "Existing role checks are untouched" Outline)	Superseded. The admin rows for invite and /system/update/check move to this slice (invite becomes ok, update check becomes missing_permission). Keep the owner rows.
test/update_http_test.go:248; test/update_download_http_test.go:187; test/update_restart_http_test.go:263-264	Admin 403 body becomes missing_permission
test/activity_log_backend_http_test.go:280, 735; test/activity_filter_cards_and_export_http_test.go:75; test/activity_next_cleanup_test.go:199	Message becomes missing_permission. The "editor" fixtures need a Writer or custom role_id. Admin retention read stays 200.
test/user_roles_test.go:280; test/invite_management_test.go:410; test/api_keys_http_test.go:434, 573	Admin invite is now allowed. Other Owner-required assertions become missing_permission. API key list and revoke fixtures need roles.
test/seo_output_sitemap_http_test.go:167; test/seo_data_site_http_test.go; test/site_acceptance_test.go; test/authors_backend_http_test.go	Admin PATCH /v1/site/{id} is now allowed. Message assertions for non-admins become missing_permission.
test/custom_content_types_test.go:131	"member without a role" gets 403 missing_permission. The fixture needs an unresolvable or empty role.
test/media_purge_http_test.go:160-167; test/media_purge_qa_test.go:31; test/image_variants_per_image_http_test.go:152-155; test/image_variants_cache_http_test.go:32-33; test/image_variants_admin_http_test.go:42-47	The "editor", "plain" and "empty role" users need role_ids. Expected body becomes missing_permission.
every test that builds users with a legacy Role and no RoleID	Add RoleID (or rely on the fallback for "owner" and "admin" only). Users with legacy roles like "editor" or "" are now unresolvable.

Existing features to amend or mark superseded

Edit the owner/admin 403 clauses in place or add a "superseded by roles_permissions_enforcement" note.

• roles_permissions_foundation (last Outline)
• user_roles, invite_management, invitations
• sites_backend, sites_authors_integration, seo_data_backend, seo_output_backend, seo_sites_articles_integration
• authors_backend
• activity-log-backend, activity_filter_cards_and_export, activity_home_card_and_retention
• api_keys, integration_api_key_routes, integration
• media_purge, media_cleanup_spa, image-variants, image_variants_cache, image_variants_per_image_api
• updates_download_stage, updates_restart_helper, updates_release_feed, container_update_guidance
• custom_content_types, custom_content_types_support

Also check the matching .qa.md files and these non-test texts: web/src/data/apiCatalogue.ts (OWNER_REQUIRED_MESSAGE, OWNER_OR_ADMIN_MESSAGE), web/src/views/IntegrationView.vue ("Owner and admin routes answer 403…") and anything under internal/infrastructure/llmdocs that documents the old messages. The SPA stores handle 403 by status only, so they should be unaffected; this is a manual check.

Manual verification

• Start task dev:api on a copy of a migrated database. As the admin, check that settings are readable and software and retention updates return 403. As the owner, check everything still works.
• Create an API key as an admin, change that user to Writer by editing users.role_id in the database copy, and confirm the same key now gets 403 on a schema write.
• The SPA is untouched, so the admin will still see owner-only UI hidden. That is expected until the SPA slices.