Re: auth-source tokens

[Ted Zlatanov <tzz@lifelogs.com>]

Here's my auth-source API proposal.  `auth-source-user-or-password' will
still be provided but this will be the main entry point.  In some ways
it's a Lisp-y interpretation of the Secrets API.

We may end up with a C implementation of some parts for security, so I'm
trying to move away from plain values and to use tokens instead.  As
you'll see at the end of the docstring, if the token's :value key holds
a function, the user has to call it (I may provide a helper function for
this).  That makes it much easier to provide secure storage for the
tokens.

Backends are searched with the same SPEC as the tokens themselves.  That
lets the user and applications define arbitrary search criteria for
backends, including the "username" mentioned earlier in this thread.  It
also simplifies the API and the auth-source internals.

:max is an important change.  It ensures we stop searching backends as
soon as we have enough tokens and defaults to 1.

:create is another important one.  It unifies create-if-missing and
delete-existing in a clean way (I think).

Because this will affect many parts of Emacs, I want feedback before I
implement it.  I've spent a lot of time thinking about this API so I
hope you'll agree it's an improvement over
`auth-source-user-or-password'.  I have some code written but didn't
append it because I'm perfectly willing to throw it away if the API has
flaws, and I think it's harder to ask for that if you see working code :)

Thanks
Ted

(defun auth-source-search (&rest spec)
  "Parse `auth-sources' for matches of the SPEC plist.

Common keys are :type, :max, :host, :protocol, and :user.

A string value is matched as a regex for the
file (netrc) backend and literally by the Secrets API.  A symbol
is matched as its string value.  All the SPEC values can be
single values or lists.

:create t means to create a token if possible.  When it is
'rewrite-existing, any matching existing token will be copied
into the new token and deleted.  This defaults to nil and will
generate an error if used with :max greater than 1..

:max N means to return at most N items (defaults to 1)

:types (A B C) means to match only tokens of types A, B, or C.
Common types include `password and `login.  Defaults to t.

:host (X Y Z) means to match only hosts X, Y, or Z as a regular
expression.  Defaults to t.

:protocol (P Q R) means to match only protocols P, Q, or R.
Defaults to t.

:K (V1 V2 V3) for any other key K will match values V1, V2, or
V3.  If any of the values are strings, they are matched as
regular expressions in the file (netrc) backend and literally in
the Secrets API.  If any are symbols, they are matched literally
as the symbol name.

Return value is a list with at most :max tokens.  Each token is a
plist with keys :backend, :value, :type, :max, :host, :protocol,
and :user, plus any other keys provided by the backend.

The token's :value key can hold a function.  In that case you must call
it to obtain the actual value."
)