RenewCMS/features/invitations.qa.md

QA procedure: invitations

Package: test (black-box). New fakes must have unique type names across the package: mockInviteRepo (implements invite.Repository with an in-memory slice and a failSwitch), plus a fixedClock only if the use case takes one. Reuse mockUserRepo and stubHasher (user_test.go) and mockMailRepo (mail_test.go; SentEmails entries expose Address, Template, Data; fail.failNext("Send")).

Setup shared by every case

1. Call validator.InitValidator() once.
2. Use cases: useCases.NewCreateInviteUseCase(userRepo, inviteRepo, &stubHasher{}, mailRepo, "https://cms.example.com") and useCases.NewListUsersAndInvitesUseCase(userRepo, inviteRepo) (final names are the coder's; constructors take only domain interfaces).
3. Handler: user.NewHandler(updateProfile, createInvite, listUsersAndInvites) mounted on a fresh chi.NewRouter() mirroring NewUserRouter: jwtauth.Verifier + jwtauth.Authenticator with jwtauth.New("HS256", []byte("test-secret"), nil), RequireCurrentToken(getUser), RequireVerifiedUser(getUser), then POST /invite and GET /. POST /invite is also wrapped in RequireOwner(getUser), placed before the limiter. For the rate-limit case wrap only POST /invite in RequireOwner(getUser) + TrustedProxyRealIP(nil) + NewRateLimiter(2, time.Minute). Requests via httptest; jwt cookie built with the user_id and token_version claims as in test/verified_account_required_http_test.go. No live server, no real SQLite, no real SMTP.
4. Seed users: verified id 7 "marta" with Role: owner; unverified id 8 for the 403 cases. Time is real: build invites with ExpiresAt/CreatedAt relative to time.Now() and compare with a 5 s tolerance.

POST /v1/user/invite

5. Body {"email":"Sam.Oliveira@Renew.example"}, cookie for 7 -> 201. Decode into map[string]json.RawMessage: the key set is exactly id, kind, email, status, created_at, expires_at, with kind="invite", email="sam.oliveira@renew.example", status="pending"; none of code, hashed_code, verification_code, password. inviteRepo holds one invite: lower-case email, InvitedBy==7, AcceptedAt nil, abs(ExpiresAt - (CreatedAt+72h)) < 5s, stored code == "hashed:"+rawCode (stubHasher) where rawCode is taken from the mail data; the stored code is not equal to rawCode.
6. mailRepo.SentEmails has exactly one entry: Address, Template=="invitation", data of the invitation mail type with Host=="https://cms.example.com", Email the invited address, InvitedBy=="marta" and a uuid-shaped VerificationCode.
7. Inviter with DisplayName:"Ines Duarte" -> InvitedBy=="Ines Duarte". Inviter with an empty display name -> username.
8. Table for 400 ({"email":"sam.oliveira@renew"}, {"email":""}, {}, {"email":"not-an-email"}, not json): status 400, inviteRepo empty, SentEmails empty.
9. Existing user with email "Jonas@Renew.example", invite jonas@renew.example -> 409, body exactly the new apperr constant "This address already has an account.", no invite, no mail. This case pins that the match is case-insensitive.
10. Seed a pending invite (expires in 2 days) for the address -> 409, body "There's already a pending invite for this address.", the seeded invite unchanged (same code hash and expiry), no mail.
11. Seed an expired invite (expired 1 h ago) -> 201; inviteRepo has exactly one invite for the address, with a different code hash and an expiry about 3 days out; one mail sent.
12. mailRepo.fail.failNext("Send") -> 500, body "Couldn't send the invite. Try again in a moment.", inviteRepo empty. Repeat the same request without re-arming -> 201. With a seeded expired invite and a failing send -> 500 and no invite for that address remains.
13. Auth table (POST): no cookie -> 401; cookie of unverified user 8 -> 403; cookie with stale token_version -> 401; cookie of a verified admin (seeded with Role: admin) -> 403, plain text body exactly apperr.OwnerRequiredErrorMessage. Each asserts no invite and no mail.
14. Rate limit: limiter of 2 per minute, RemoteAddr 203.0.113.20:1234, three valid POSTs -> 201, 201, 429; third body is exactly apperr.TooManyRequestsErrorMessage, has Retry-After, and adds no invite or mail. GET / from the same address afterwards is not 429.

GET /v1/user/

15. Seed per the feature scenario (three users, an expired, a pending and an accepted invite, with the stated CreatedAt values). 200; decode as []map[string]json.RawMessage. Assert length 5, order (pending sam, expired p.huber, ines, jonas, marta), key sets exactly as specified: id, kind, username, display_name, email, role, status, created_at for user items and id, kind, email, status, created_at for invite items, accepted invite absent, and none of the forbidden keys anywhere. Also assert the raw body string contains each accepted user's own email address.
16. Only user 7 -> array with exactly one kind:"user" item, status accepted.
17. Invite created 3 days + 1 minute ago -> status:"expired"; created 2 days ago -> pending; with AcceptedAt set -> not listed.
18. Auth table (GET): no cookie -> 401; unverified -> 403.

Use-case level (no HTTP)

19. CreateInvite on a repository holding a user with the same email -> errors.Is(err, invite.ErrEmailHasAccount); live pending invite -> errors.Is(err, invite.ErrPendingInvite) (sentinel names are the coder's). A mail failure wraps the mail repository error and the Delete of the invite is called (if Delete also fails, both errors are joined, as CreateUser does).

Mailer (real embedded templates, no SMTP)

20. mailer.MailRepository{}.Render("invitation", data) with Host:"https://cms.example.com", VerificationCode:"abc-123", Email:"lea@example.com", InvitedBy:"Ines Duarte" returns subject "Ines Duarte invited you to RenewCMS" and a body containing https://cms.example.com/invite/accept?c=abc-123, lea@example.com and Ines Duarte. An InvitedBy of <b>x</b> is HTML-escaped in body. Subjects for verification and password-reset are unchanged, and an unknown template still gets the default subject.
21. internal/infrastructure/mailer/templates/invitation.html is byte-identical to docs/design/source/emails/invitation.html (read both files and compare).

Regression: registration (extends registration_gate_and_verification_email.qa.md)

22. With one verified user and a pending invite for sam.oliveira@renew.example, POST /v1/auth/register with that email -> 403, body exactly apperr.RegistrationClosedErrorMessage, no user created, no mail sent.
23. Empty user repository -> POST /v1/auth/register still 200 with a jwt cookie and one verification mail, and inviteRepo untouched. GET /v1/auth/registration still reports closed when a verified user and a pending invite exist.

Manual verification (not exercised by the Go tests)

• Start the app once against a fresh SQLite file: the invites table exists (model registered in AutoMigrate in api/dependecyInjection.go) and inviting persists across a restart.
• Send a real invitation through a real or sandboxed SMTP server: the subject line, the rendering in a mail client (light and dark) and that the link {PUBLIC_URL}/invite/accept?c=... carries the raw code. The screen the link opens is not designed and is out of scope, so the link will not resolve in the SPA yet.
• SPA copy for the 429 ("Too many invites. Wait a moment, then try again.") is a note for the later SPA slice and is not tested here. The SPA keys list rows by kind and id, since a user and an invite can share a numeric id.
• Layering check by review: use cases import only internal/domain/*; the mailer subject logic lives in internal/infrastructure/mailer.