[elpa] externals/url-http-oauth-demo 828ef46e55 05/13: Add background documentation

[Thomas Fitzsimmons]

branch: externals/url-http-oauth-demo
commit 828ef46e55511d581bf1ef722a4eeacccefc1ae3
Author: Thomas Fitzsimmons <fitzsim@fitzsim.org>
Commit: Thomas Fitzsimmons <fitzsim@fitzsim.org>

    Add background documentation
    
    * url-http-oauth-demo.el: Add Background section.
    (url-http-oauth-interpose): Rename.  Document arguments.
---
 url-http-oauth-demo.el | 104 ++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 95 insertions(+), 9 deletions(-)

diff --git a/url-http-oauth-demo.el b/url-http-oauth-demo.el
index 0ab1598b0c..b86563d2b9 100644
--- a/url-http-oauth-demo.el
+++ b/url-http-oauth-demo.el
@@ -22,8 +22,72 @@
 
 ;;; Commentary:
 ;;
-;; This package demonstrates an OAuth 2.0 flow for Sourcehut using the
-;; built-in GNU Emacs URL library and the url-http-oauth package.
+;; This package demonstrates OAuth 2.0 authentication and
+;; authorization to Sourcehut, using the built-in `url' and
+;; `auth-source'libraries and the new `url-http-oauth' package.
+;;
+;; Background:
+;;
+;; Sourcehut has implemented OAuth 2.0 for its services.  Its
+;; implementation is unique in that it is released as Free Software,
+;; and does not require JavaScript for any of the OAuth 2.0 steps.
+;;
+;; Here is a diagram summarizing protocol, adapted from RFC 6749:
+;;
+;;           `url' and `url-http-oauth' implement
+;;                  these middle steps
+;; +--------+                               +------------------------+
+;; |        |--(A)- Authorization Request ->|    (Resource Owner)    |
+;; |        |                               |                        |
+;; |        |<-(B)-- Authorization Grant ---| You, the Human,        |
+;; |        |                               | user of Emacs and      |
+;; |        |                               | Sourcehut, performing  |
+;; |        |                               | steps in a web browser |
+;; |        |                               +------------------------+
+;; |        |
+;; |        |                               +----------------------+
+;; |        |--(C)-- Authorization Grant -->|(Authorization Server)|
+;; |(Client)|                               |                      |
+;; |        |<-(D)----- Access Token -------| URLs starting with   |
+;; | Emacs  |                               | meta.sr.ht/oauth2    |
+;; |        |                               +----------------------+
+;; |        |
+;; |        |                               +--------------------+
+;; |        |--(E)----- Access Token ------>| (Resource Server)  |
+;; |        |                               |                    |
+;; |        |<-(F)--- Protected Resource ---| URLs starting with |
+;; |        |                               | meta.sr.ht/query   |
+;; +--------+                               +--------------------+
+;;
+;; For generality¹ there is no web browser automation.  Here is a
+;; breakdown of Steps A and B:
+;;
+;; Step A:
+;;      A.1: A request URL is shown in the minibuffer; the minibuffer
+;;           prompts for a response URL and waits.
+;;      A.2: The user copies the request URL into their web browser of
+;;           choice¹.
+;;      A.3: The user authenticates to Sourcehut, using the web browser.
+;;      A.4: The user authorizes Emacs to access their Sourcehut
+;;           resource, using the web browser.
+;;      A.5: The web browser redirects to a URL; this redirection may
+;;           fail or it may not.  All that matters is the URL itself,
+;;           which will contain a "code" query argument.
+;;      A.6: The user copies the full "code" URL from the web browser.
+;;
+;; Step B:   The user pastes the full "code" URL into the minibuffer
+;;           and presses RET.
+;;
+;; The remaining steps, C through F, are all handled within Emacs.
+;;
+;; 1. For example, when running Emacs in a VT100 terminal emulator
+;;    through two SSH hops.
+;;
+;; 2. For Sourcehut in particular, steps A.2 through A.5 can be done
+;;    using EWW because Sourcehut does not need JavaScript.  Today EWW
+;;    needs to run in a separate process so it does not conflict with
+;;    url-http-oauth, which blocks the minibuffer waiting for the
+;;    response URL.
 ;;
 ;; Installation:
 ;;
@@ -37,14 +101,36 @@
 ;;; Code:
 (require 'url-http-oauth)
 
-;;; Register "https://meta.sr.ht/query"; as needing OAuth 2.0 for
-;;; authentication.
+;;; Tell Emacs that "https://meta.sr.ht/query"; uses OAuth 2.0 for
+;;; authentication and authorization.
 ;;;###autoload
-(url-http-oauth-register-resource "https://meta.sr.ht/query";
-                                  "https://meta.sr.ht/oauth2/authorize";
-                                  "https://meta.sr.ht/oauth2/access-token";
-                                  "107ba4a9-2a96-4420-8818-84ec1f112405"
-                                  'prompt)
+(url-http-oauth-interpose
+ ;; This is the URL that the `url-http-oauth-demo' package wants to do
+ ;; stuff with.  Everything else is authentication and authorization
+ ;; to satisfy OAuth 2.0 requirements.
+ "https://meta.sr.ht/query";
+ ;; These are the authorization and token endpoints, published in
+ ;; "https://man.sr.ht/meta.sr.ht/oauth.md";.  There is no way to
+ ;; autodiscover them from "https://meta.sr.ht/query";.
+ "https://meta.sr.ht/oauth2/authorize";
+ "https://meta.sr.ht/oauth2/access-token";
+ ;; This is the client identifier, which can be generated by the user,
+ ;; or by the Emacs library developer, at
+ ;; "https://meta.sr.ht/oauth2/client-registration";.
+ "107ba4a9-2a96-4420-8818-84ec1f112405"
+ ;; This is the client secret, which will be generated as part of
+ ;; client registration, at
+ ;; "https://meta.sr.ht/oauth2/client-registration";.  If the user
+ ;; generates the client secret, they should note it down.  If the
+ ;; Emacs library developer generates it, they should make it
+ ;; available to the users of their library somehow.  In either case,
+ ;; Emacs will prompt for it, and store it, ideally GPG-encrypted,
+ ;; using `auth-source'.  An example, no-longer-active client secret
+ ;; string is "CeuivTBzZbqJ4iTc+VEdPZJODkBHhuCj4bIqQQAONYaOUGubNM0yG
+ ;; ZU3P7ant959W1RkzgvXSeNf2mdxuk5EfA==".  The user would paste this
+ ;; 88 character client secret string into the minibuffer when
+ ;; prompted.
+ 'prompt)
 
 ;;;###autoload
 (defun url-http-oauth-demo-get-profile-name ()