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

["brian m. carlson" <sandals@crustytoothpaste.net>]

[-- Attachment #1: Type: text/plain, Size: 1846 bytes --]

On 2024-03-25 at 23:16:09, M Hickford wrote:
> > +`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.

> > ++
> > +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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 262 bytes --]