Re: [PATCH 06/13] docs: indicate new credential protocol fields

From: brian m. carlson <sandals@crustytoothpaste.net>
Date: Mar 25, 2024, 23:37 UTC
Message-ID: <ZgIKqJaE79-Erzif@tapette.crustytoothpaste.net>
In-Reply-To: <20240325231609.284-1-mirth.hickford@gmail.com>

On 2024-03-25 at 23:16:09, M Hickford wrote:

Show 10 quoted lines

> > +`authtype`::
> > +	This indicates that the authentication scheme in question should be used.
> > +	Common values for HTTP and HTTPS include `basic`, `digest`, and `ntlm`,
> > +	although the latter two are insecure and should not be used.  If `credential`
> > +	is used, this may be set to an arbitrary string suitable for the protocol in
> > +	question (usually HTTP).
> 
> How about adding 'bearer' to this list? Popular hosts Bitbucket
> https://bitbucket.org and Gitea/Forgejo (such as https://codeberg.org)
> support Bearer auth with OAuth tokens.

Sure, I can do that.

Show 12 quoted lines

> > ++
> > +This value should not be sent unless the appropriate capability (see below) is
> > +provided on input.
> > +
> > +`credential`::
> > +	The pre-encoded credential, suitable for the protocol in question (usually
> > +	HTTP).  If this key is sent, `authtype` is mandatory, and `username` and
> > +	`password` are not used.
> 
> A credential protocol attribute named 'credential' is confusing. How
> about 'authorization' since it determines the HTTP Authorization
> header? This detail is surely worth mentioning too.

I don't want this to be very specific to HTTP, so I don't think that's a great name. As I mentioned in the cover letter, I might well extend this to IMAP and SMTP for our mail handling in the future, and that name wouldn't work well there.

I named it `credential` because, well, it's the credential that's used in the protocol. I feel like saying that the field represents "the authorization" sounds unnatural. It's not wrong, per se, but it sounds confusing.

I'm open to other ideas if you or others have them, but between these two, I think I'd prefer to stick with `credential`.

-- 
brian m. carlson (they/them or he/him)
Toronto, Ontario, CA