RenewCMS/features/roles_permissions_content_scope.qa.md

QA procedure: roles_permissions_content_scope

Package: test (black-box). Name new fakes uniquely, for example contentScopeRoleRepo, contentScopeArticleRepo, contentScopeEntryRepo. Reuse the fakes and helpers of test/roles_permissions_enforcement_support_test.go (mintCookie, assertGate, the API key minting helper) where they fit. Do not copy any Role.Allows, Role == or hand-rolled own/all comparison into new code: the tests call the exported domain helper.

Deferred to later slices

• 3: /v1/role CRUD, no-escalation, writing typed grants, cleanup of typed rows of deleted content types. Done by roles_permissions_roles_api.
• 4: role change, invite with role, ownership transfer, removal of the legacy role column.
• 5-7: SPA (View only mark, "Ask an editor to publish.", disabled Delete). The SPA reacts to the status code and the X-Missing-Permission header only. /auth/me exposing typed grants (the API side is done by roles_permissions_roles_api).
• Not changed: GET /v1/media/{id}/usage still lists articles and entries for any media.view holder. media.delete own fails closed. Entry relation summaries are not gated by the related type.

Design notes for the user

• docs/design is silent on Read=Own. The draft encodes the decision recorded in the feature Background ("visible = online OR covered" for articles, filtered list and 404 for entries). If the user chooses another option, edit the "Reading articles", "The article list is the visible set" and "Entries follow the read scope" tables.
• The design says "Publish hidden for roles without it; status shows Draft with Ask an editor to publish." The API only answers 403 content.publish. The copy is the SPA's.
• roles.md "Escalation blocked" talks about granting Publish: All when the editor holds only Own. That is slice 3.
• A custom content type with a built-in key is now refused at creation (409). Mention it in docs/design when the Schema screens are reviewed.

Inventory (route, key, gate, after the load, Owner / Admin / Writer)

Route	Key (type)	Gate before load	After the load	Owner / Admin / Writer
GET /v1/article	content.read (article)	none, public	visible set = online OR covered, filters items, total, counts, ?status, ?seo	all / all / all
GET /v1/article/{id}, /{id}/seo	content.read (article)	none, public	invisible gives 404 Article not found	all / all / all
POST /v1/article	content.create (article)	typed not none	created_by = caller, offline	ok / ok / ok
PATCH /v1/article/{id}	content.update (article)	typed not none	Permits(created_by)	ok / ok / ok
DELETE /v1/article/{id}	content.delete (article)	typed not none	Permits(created_by)	ok / ok / 403
PATCH /v1/article/{id}/publish, /unpublish	content.publish (article)	typed not none	Permits(created_by)	ok / ok / 403
POST /v1/article/{id}/seo/check	content.read (article)	typed not none	visible set, else 404	ok / ok / ok
GET /v1/content-type/{key}/entry	content.read ({key})	typed not none	own filters list	all / all / all
GET /v1/content-type/{key}/entry/{id}	content.read ({key})	typed not none	own and not creator gives 404 entry_not_found	ok / ok / ok
POST /v1/content-type/{key}/entry	content.create ({key})	typed not none	created_by = caller	ok / ok / ok
PUT /v1/content-type/{key}/entry/{id}	content.update ({key})	typed not none	Permits(created_by)	ok / ok / ok
DELETE /v1/content-type/{key}/entry/{id}	content.delete ({key})	typed not none	Permits(created_by)	ok / ok / 403
POST /v1/content-type	schema.edit	as 2a	creating a key equal to a built-in key gives 409 content_type_key_taken	ok / ok / 403
DELETE /v1/media/{id}, POST /v1/media/merge	media.delete	all only	n/a (no creator on images)	ok / ok / 403
GET /v1/media, /{id}, /{id}/usage	media.view	as 2a	usage not filtered	ok / ok / ok
POST /v1/media, PATCH /v1/media/{id}	media.upload	as 2a	none	ok / ok / ok
PATCH /v1/author/{id}	authors.edit	as 2a	link-based own	as 2a

Routes that no key gates after 2b among the content routes: none. Entry routes need no content.publish. No schedule route exists.

Test infrastructure first

1. contentScopeRoleRepo: in-memory role Repository, seeded with the three built-ins through the same Go function the migration uses, plus the custom roles and users 21-27 of the feature Background. Supports editing grants and role_id between calls, a switchable failure, and call counters for Get, GetByName and List (ListGrants was removed by roles_permissions_roles_api). Its Get returns the role with Grants filled, like the persistence repository.
2. User fake with a Get call counter (existing mockUserRepo plus a counter, or a wrapper). Users 3, 5, 9, 12 (unverified Admin), 13 (role_id 99), 20 (hand-placed owner-only), 21-27.
3. Article fake and entry fake seeded with the ids, states and created_by values of the Background. Both record writes, so "article unchanged", "entry stored" and "nothing stored" are asserted on the store. A recording audit.Recorder to assert "no audit event".
4. HTTP harness: validator.InitValidator(). Build NewArticleRouter and NewContentTypeRouter equivalents mounted on a fresh chi.NewRouter() mirroring api/router.go: authtoken.Verifier, container.apiKeyAuth() equivalent, the new optional-access middleware on the public article group, Authenticator, RequireCurrentToken, RequireVerifiedUser, the typed permission gate, and the handlers over real use cases wired to the fakes. No live server, no real SQLite, no real SMTP.
5. assertGate(t, rec, key) from 2a for the 403 contract. A helper assertUnchanged(t, store, id, snapshot).
6. A helper grantsOf("content.update=own", "content.update:events=none", ...) parsing the row notation of the feature into []role.Grant, so table rows read like the feature.

A. Domain (no fakes needed)

7. GrantSet.ScopeFor: run every row of the "ScopeFor resolves wildcard and typed keys" Outline through Role{Grants: ...}.GrantSet(). Include the 101-character type key and "Bad Key".
8. GrantSet.Permits: the 7 rows of the "One helper decides own and all" Outline.
9. Duplicates: build the set from the rows in both orders, expect the same most restrictive scope. Include a toggle key stored at own (expect none) and an unknown scope string (expect none).
10. ValidateGrants: the 10 rows of the Outline; the duplicate error is the new sentinel role.ErrDuplicateGrant.
11. Owner-only: Role{Locked: false, Grants: system.apply_updates=all}.GrantSet() has no owner-only scope for any of the 5 owner-only keys. Role{Locked: true} keeps them. BuiltInRoles() Owner keeps all 34, Admin none of the 5.
12. Hygiene tests, in the style of *_hygiene_test.go:
    • internal/domain/role imports only the stdlib.
    • Role has no Allows, AllowsFor, scopeOf (reflect on method set, or grep the non-test Go).
    • Non-test Go under api/ and internal/infrastructure/useCases has no comparison of CreatedBy with a caller id, and no direct index into a GrantSet, outside internal/domain/role.
    • api/router.go and api/middleware hold no string literal equal to a catalogue key (parse the Go file, compare string literals with role.Catalogue()).
    • Drift: every catalogue key has an exported constant in roleKeys.go, and every constant is a catalogue key.

B. Use cases (fakes only)

13. CheckPermission (typed variant) table: Owner, Admin, Writer, each custom role, an unresolvable role (role.ErrMissingPermission via errors.Is, key via errors.As), a failing repository (non-sentinel error), and a live grant change between two calls.
14. Counters: for one Require call, List is 0 (was ListGrants), Get (or GetByName for a legacy owner/admin) is 1. Same for GetMyAccessUseCase.Get.
15. Article use cases (get, list, update, update-is-online, delete, create, SEO check): table of caller grants × article × expected error or result, per the feature Outlines. Assert for refusals: error is role.MissingPermissionError{Key: "content.update"} and so on, the store is unchanged, the recorder has no event, and no site/author/image lookup happened (counters on those fakes).
16. Entry use cases (list, get, create, update, delete): same, including created_by unchanged on update, own-filtered list totals and ?q= over the own set, and entry.ErrEntryNotFound for a non-owned read under own.
17. Order: scope check after the load and before validation: PUT with an invalid body for a non-owned entry gives the scope error, not FieldError.
18. CreateContentType with each of the 5 built-in keys returns contenttype.ErrKeyTaken.
19. GetMyAccess: effective grants (duplicates normalised, owner-only dropped on unlocked roles, typed rows not listed).

C. HTTP

20. Gate and scope matrices: run every row of each Scenario Outline of the feature. One test per Outline, subtests named after the row. Reset the stores for each row.
21. Contract: every 403 row via assertGate (header is the base key), no side effect, no audit event.
22. Public article routes: no cookie, unverified Admin (user 12), user 27, user 13 (role_id 99), API key. Assert 200/404 per the Outline and that no 403 is ever returned. Role repo failure gives 500; an anonymous request leaves the role repo counters at 0.
23. List: the 7 rows with items, total, counts. Assert counts.suggestions and ?seo= consider only visible articles (add a suggestions-bearing draft owned by someone else, hidden from user 22).
24. Publish: all rows, plus the audit assertions (one article.publish / article.unpublish, none on refusal), plus "update never changes status" (is_online in the PATCH body ignored) and "new article is a draft".
25. Typed grants: the 13 rows, plus unknown type under wildcard (404) and under typed-only grants (403, no content type lookup counter).
26. Live role: edit grants and role_id between requests with the same cookie and the same API key.
27. API key: article created through the key has created_by of the creator.
28. Order: unverified 403, stale token 401, no cookie 401 before the permission gate on the authed article and entry routes.
29. Loads per request: with the counting fakes, a gated session request performs at most 1 user Get and exactly 1 role Get, 0 List (was ListGrants); with an API key at most 2 user Get. Run on one article route and one entry route.
30. Owner-only: user 20 with a hand-placed system.apply_updates=all gets 403 on POST /v1/system/update/check; /auth/me omits it.
31. Media rows of the Outline and the "usage not filtered" assertion.
32. Regression: run the 2a Outline "Existing owner and admin behaviour does not regress", the authors.edit Outline and the activity/api-key scope Outlines unchanged.

Existing tests that must change (found by grep; recheck with go vet -tags nofrontend ./test/...)

File (lines)	Change
test/roles_permissions_foundation_test.go:38-53	Role.Allows scenarios move to GrantSet.ScopeFor/Permits. The "unknown key" row keeps asserting ErrUnknownPermission from Lookup
test/role_hardening_test.go:202-212, 250-277	Allows/AllowsFor rows move to GrantSet. Line 212 becomes the Owner role's grant set holding system.apply_updates
test/roles_permissions_enforcement_test.go:37-38, 83-85, 146-171	The hand-made custom role with system.apply_updates now gets ErrMissingPermission (line 83-85 flips). TestGrantSet uses catalogue keys, not "a", "b", "c". NewGrantSet becomes Role.GrantSet()
test/roles_permissions_enforcement_http_test.go:343	Custom role grantsOf("system.apply_updates") on POST /v1/system/update/check flips from ok to 403
test/roles_permissions_enforcement_support_test.go:79; test/roles_permissions_enforcement_scope_test.go:252, 275, 297-346; test/api_keys_test.go:178-179	role.NewGrantSet(...) call sites move to Role{...}.GrantSet() (owner-only keys need Locked: true in the fixture)
tests that build the article or entry routers by hand (test/article_publishing_http_test.go, edit_article_body_http_test.go, articles_list_http_test.go, articles_pagination_api_http_test.go, public_article_read_test.go, public_article_listing_test.go, article_body_format_test.go, article_body_unlimited_http_test.go, article_title_rules_test.go, seo_data_article_http_test.go, authors_backend_articles_http_test.go, delete_article_keeps_images_test.go, remove_legacy_article_image_alias_http_test.go, not_found_errors_test.go, stale_token_invalidation_http_test.go, site_articles_acceptance_test.go, custom_content_types_support_http_test.go, relation_field_type_http_test.go, media_field_type_http_test.go, activity_log_producers_http_test.go)	Mount the new middleware and give the role repository to the fixture. Users with legacy role "" or "editor" now get missing_permission on writes: give them a role_id (Writer, Editor-like custom role or Admin). Public draft visibility assertions: unverified and no-grant callers see online only
test/custom_content_types_test.go (and usecases)	Add the built-in key rows (409). Entry use case calls take the caller grants

Existing features to amend or mark superseded

Add a "superseded by roles_permissions_content_scope" note or edit in place:

• roles_permissions_enforcement: the Background clause "enforcement honours any grant it finds, including an owner-only key...", the Outline row system.apply_updates=all | POST /v1/system/update/check | ok, the scenario "Articles and entries are not gated in this slice", and its QA "Deferred" 2b line.
• roles_permissions_foundation: the Background line Role.Allows(key, owned bool), the three Allows scenarios, and the sentence "per-type overrides ... deferred to slice 3" (the read side is implemented here, writing stays in slice 3).
• article_publishing, articles_list, articles_pagination, public_article_read, public_article_listing, edit_article_body, article_body_format, article_title_rules, delete_article_keeps_images, not_found_errors, seo_data_backend, seo_output_backend, seo_sites_articles_integration (draft visibility now depends on content.read).
• custom_content_types, custom_content_types_support, relation_field_type, media_field_type (entry routes are role-gated, built-in keys reserved).
• Matching .qa.md files for each of the above.

Manual verification

• Start task dev:api on a copy of a migrated database. As the Writer: publish returns 403, saving a draft works and stays a draft. As the Admin: publish works.
• With two accounts on a custom role holding content.update=own, confirm account B gets 403 on A's article and entry, and A can edit them.
• Set a typed grant by editing role_permission in the database copy (content.update:article with scope none) and confirm article edits return 403 while entry edits still work. Typed grants can now also be written through PUT /v1/role/{id} (roles_permissions_roles_api).
• Confirm no password or secret appears in any scenario. Env vars are referenced by name only (JWT_SECRET).