--- a/mod_auth_oauth_external/mod_auth_oauth_external.lua	Thu Apr 30 10:53:14 2026 +0100
+++ b/mod_auth_oauth_external/mod_auth_oauth_external.lua	Sat May 02 16:10:48 2026 +0200
@@ -4,17 +4,22 @@
 local json = require "util.json";
 local sasl = require "util.sasl";
 
+-- Details about the OAuth2 Issuer
 local issuer_identity = module:get_option_string("oauth_external_issuer");
 local oidc_discovery_url = module:get_option_string("oauth_external_discovery_url",
 	issuer_identity and issuer_identity .. "/.well-known/oauth-authorization-server" or nil);
+
+-- OAuth2 endpoints
+-- These could be discovered dynamically if unset
 local validation_endpoint = module:get_option_string("oauth_external_validation_endpoint");
 local token_endpoint = module:get_option_string("oauth_external_token_endpoint");
 
+-- Field used to decide the XMPP address localpart
 local username_field = module:get_option_string("oauth_external_username_field", "preferred_username");
-local allow_plain = module:get_option_boolean("oauth_external_resource_owner_password", true);
 
--- XXX Hold up, does whatever done here even need any of these things? Are we
--- the OAuth client? Is the XMPP client the OAuth client? What are we???
+-- Settings needed for Resource Owner Password Grant, where Prosody acts as an OAuth2 Client
+-- Since at this time, no clients support SASL OAUTHBEARER, this is the only way this works
+local allow_plain = module:get_option_boolean("oauth_external_resource_owner_password", true);
 local client_id = module:get_option_string("oauth_external_client_id");
 local client_secret = module:get_option_string("oauth_external_client_secret");
 local scope = module:get_option_string("oauth_external_scope", "openid");