docs: document authz trust boundary and annotate RequireRoles

internal/http/middleware/authz.go

@@ -39,6 +39,9 @@ func ActorFromContext(ctx context.Context) (Actor, bool) {
 	return actor, true
 }
 
+// RequireRoles enforces RBAC allow-listing. It does NOT authenticate the actor headers.
+// SECURITY: This middleware trusts the upstream gateway to authenticate the actor headers.
+// In production, an API Gateway or JWT middleware must run before this layer.
 func RequireRoles(next http.Handler, allowedRoles ...string) http.Handler {
 	allowed := make(map[string]struct{}, len(allowedRoles))
 	for _, role := range allowedRoles {