Refine POP support; switch to true line-by-line parsing

Also add login_hint to OAuth permission URL and improve debug log messaging

Author: simonrob

emailproxy.config

@@ -6,20 +6,20 @@ documentation = This is a sample Email OAuth 2.0 Proxy configuration file. Confi
 
 [Server setup]
 documentation = Local servers are specified as demonstrated below where, for example, the section heading [IMAP-1993]
-	gives the type (which can be IMAP or SMTP) and the local port to listen on (i.e., 1993, etc). The local port number
-	must be above 1023 (unless the proxy script is run via sudo), below 65536, and unique across local servers. Multiple
-	accounts can share the same server, however. Each server section must specify the `server_address` and `server_port`
-	of the remote server that it will be proxying - you can obtain these values from your email provider, or use the
-	details below for Office 365 and/or Gmail.
+	gives the type (which can be IMAP, POP or SMTP) and the local port number to listen on (i.e., 1993, etc). The local
+	port must be above 1023 (unless the proxy script is run via sudo), below 65536, and unique across local servers.
+	Multiple accounts can share the same server, however. Each server section must specify the `server_address` and
+	`server_port` of the remote server that it will be proxying - you can obtain these values from your email provider,
+	or use the details below for Office 365 and/or Gmail.
 
-	To allow the proxy to operate, your email client must be set up to use an unencrypted connection for both SMTP and
-	IMAP (i.e., no STARTTLS or SSL/TLS, just plain login credentials). The proxy will create a secure connection on your
+	To allow the proxy to operate, your email client must be set up to use an unencrypted connection for IMAP/SMTP/POP
+	(i.e., no STARTTLS or SSL/TLS, just plain login credentials). The proxy will create a secure connection on your
 	behalf to the remote server from the outset by default (i.e., implicit SSL/TLS); see below if STARTTLS is required.
 
 	Server customisation:
 	- If your SMTP server uses the STARTTLS approach, add `starttls = True`, as shown in the [SMTP-1587] example below
 	(assumed to be False otherwise). With this parameter set, STARTTLS negotiation will be handled by the proxy on your
-	behalf (i.e., do not enable STARTTLS in your client). IMAP STARTTLS is not currently supported.
+	behalf (i.e., do not enable STARTTLS in your client). IMAP STARTTLS and POP STARTTLS are not currently supported.
 
 	- If the property `local_address` is not specified, its value is assumed to be `localhost`. If required, this
 	parameter can be used to set an IP address or hostname for the proxy to listen on.
@@ -36,29 +36,37 @@ local_address = localhost
 server_address = outlook.office365.com
 server_port = 993
 
+[POP-1995]
+server_address = outlook.office365.com
+server_port = 995
+
 [SMTP-1587]
 server_address = smtp.office365.com
 server_port = 587
 starttls = True
 
-[IMAP-1995]
+[IMAP-2993]
 server_address = imap.gmail.com
 server_port = 993
 
-[SMTP-1465]
+[POP-2995]
+server_address = pop.gmail.com
+server_port = 995
+
+[SMTP-2465]
 server_address = smtp.gmail.com
 server_port = 465
 
 
 [Account setup]
 documentation = Accounts are specified using your email address as the section heading (e.g., [[email protected]],
-	below). Account usernames (i.e., email addresses) must be unique - only one entry per account is permitted. Each
-	account section must provide values for `permission_url`, `token_url`, `oauth2_scope` and `redirect_uri`. If you
-	are adding an account for a service other than Office 365 or Gmail then the provider's documentation should give
-	these details. For Gmail and Office 365 you can simply copy the values from the examples below.
+	etc, below). Account usernames (i.e., email addresses) must be unique - only one entry per account is permitted.
+	Each account section must provide values for `permission_url`, `token_url`, `oauth2_scope` and `redirect_uri`. If
+	you are adding an account for a service other than the examples shown below then the provider's documentation should
+	provide these details.
 
 	You will also need to add your own `client_id` and `client_secret` values as indicated below. These can either be
-	copied from an existing source (such as another email client that supports OAuth 2.0), or you can register and use
+	reused from an existing source (such as another email client that supports OAuth 2.0), or you can register and use
 	your own desktop app API client credentials. See https://developers.google.com/identity/protocols/oauth2/native-app
 	and the Microsoft link below for details. Multiple accounts on the same server can use the same values for the
 	`client_id` and `client_secret` properties; just duplicate these in each account's entry below. Note that there are
@@ -68,8 +76,9 @@ documentation = Accounts are specified using your email address as the section h
 	Once the proxy is correctly configured, after the first successful use of an account its access token details will
 	be cached in this configuration file, encrypted with the password you use in your email client. The password set in
 	your email client is not used for authentication (which is done separately via a web browser), so it can be
-	different to your real account password, which is helpful for debugging. See the proxy's readme for more information
-	and further configuration options: https://github.com/simonrob/email-oauth2-proxy/blob/main/README.md.
+	different to your real account password, which is helpful for debugging. Please note, though, that all clients that
+	use a particular account via the proxy should use the same password to avoid repeated re-authentication requests.
+	See the proxy's README.md file for more information and further configuration options.
 
 	Office 365 customisation:
 	- If your Office 365 configuration requires a tenant ID, place it in both `permission_url` and `token_url` in place
@@ -88,7 +97,7 @@ documentation = Accounts are specified using your email address as the section h
 [[email protected]]
 permission_url = https://login.microsoftonline.com/common/oauth2/v2.0/authorize
 token_url = https://login.microsoftonline.com/common/oauth2/v2.0/token
-oauth2_scope = https://outlook.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/SMTP.Send offline_access
+oauth2_scope = https://outlook.office365.com/IMAP.AccessAsUser.All https://outlook.office365.com/POP.AccessAsUser.All https://outlook.office365.com/SMTP.Send offline_access
 redirect_uri = http://localhost
 client_id = *** your client id here ***
 client_secret = *** your client secret here ***