forget-passwords 0.2.9 → 0.2.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c60a2d4e21288d85c0331dc52cf188779d3cb868126f9307046a715f6cb9ffe
-  data.tar.gz: fcb2d206ae7f90152033156061793e6ad8453d862aff8ed1f33697d4c7f3901a
+  metadata.gz: 4db3ce83ab06fe2e7ba9fbf453370f1182e8fc6e7f888e1edd2851e1eb4dfe1a
+  data.tar.gz: '049d12c72b928352235e422c2c737a7c7827d5284a68054ea09f50c7d3a962d0'
 SHA512:
-  metadata.gz: 62c6dd29832cc21fed041dc49dd57557de4db7f9d6e73a3dd19624c50655d9cde301dfc02ca96877e273ed0f11c9b2731e2e7d0b0862a032d941a21584036519
-  data.tar.gz: 57b901b1dee840cd0bec6f4cf3211a30df85fbb946f7e335cf011297a40071f67a4fc84a63e25e783c5817c5db3c57fa22f339190f8b123eba7177c6d01319fe
+  metadata.gz: 2d3bc2353a0b41009cb7b537a67bc58210670095949afbe21ada7221912c3d6a91c580240d56803b159a32a73c3d4e1c756f7b34c288879be61f842740c6bf20
+  data.tar.gz: 3c7771eb7709deeeca3c7617be519168d6387c619b5e0de0a61243905bb8a4f5a9a2667ab6a63ada192c962a426301e2d83400a5370dc212aaa7e2ee1f69eefb

data/README.md

@@ -95,10 +95,11 @@ module to operate.
 
 ## Usage
 
-To start using ForgetPasswords, we'll assume you have done the necessary
-setup on the server (below), as well as all the necessary setup for an
-address to send e-mail from. After that, we'll need a database (this
-example uses PostgreSQL; you can of course skip this step for SQLite):
+To start using Forget Passwords, we'll assume you have done the
+necessary setup on the server (below), as well as all the necessary
+setup for an address to send e-mail from. After that, we'll need a
+database (this example uses PostgreSQL; you can of course skip this
+step for SQLite):
 
     $ createdb forgetpw
 
@@ -134,8 +135,8 @@ principle it is usable in other systems. What follows is the
 configuration for Apache 2.4.x or newer.
 
 First, we need to declare the authenticator (here it can be called
-anything but we are appropriately calling it `ForgetPasswords`) and where
-it's listening:
+anything but we are appropriately calling it `ForgetPasswords`) and
+where it's listening:
 
 ```apache
 AuthnzFcgiDefineProvider authn ForgetPasswords fcgi://localhost:10101/
@@ -155,7 +156,7 @@ throwaway user like `nobody`, and then subsequently deny that user. (I
 would consider this a design flaw in `mod_authnz_fcgi`.) The
 expression `%{reqenv:FCGI_USER}` (where the slug `FCGI_USER` is
 configurable on our side) is how the identity gets transmitted
-upstream from ForgetPasswords to the server.
+upstream from Forget Passwords to the server.
 
 ```apache
 <Location /protected>
@@ -174,7 +175,7 @@ Another idiosyncrasy of `mod_authnz_fcgi` is that while it uses the
 to the client necessarily has to come from the downstram content
 handler. As such, any other information from a _successful_
 authentication response needs to be smuggled out through environment
-variables. Since ForgetPasswords performs a redirect to remove the
+variables. Since Forget Passwords performs a redirect to remove the
 authentication token from the URL upon successful authentication, the
 following `mod_rewrite` configuration needs to be in place to turn the
 environment variable back into an actual redirect:
@@ -224,17 +225,42 @@ ProxyPass /logout     fcgi://localhost:10101/logout
 > crash with a protocol error. While the handling is less than
 > delicate, this is actually a reasonable expectation, as request
 > bodies are only read once off the wire and will thus be already
-> consumed (whether or not they contain the fields to which ForgetPasswords
-> is sensitive) when the content handler is invoked. (The way Apache
-> handles the request body, it _can_ be duplicated and reinserted into
-> the input stream, but that is a whole project unto itself.
+> consumed (whether or not they contain the fields to which Forget
+> Passwords is sensitive) when the content handler is invoked. (The
+> way Apache handles the request body, it _can_ be duplicated and
+> reinserted into the input stream, but that is a whole project unto
+> itself.
+
+### Caveats
+
+I have noticed that a `RewriteRule` (in a `.htaccess`) with the
+passthrough (`PT`) flag will short-circuit the redirect that happens
+when a user follows the link off an e-mail. Same ostensibly goes for
+overriding `DirectoryIndex` in a `.htaccess`. The observable effect is
+that the server returns 401 (and doesn't redirect/remove the query
+string) even though the cookie is set and the knock token is consumed.
+If you refresh the page, then it will say (correctly, from its point
+of view) that the link is expired. If you manually chop off the query
+string, it will correctly display the logged-in state.
+
+> One thing I didn't check is if it still returned a `Location:`
+> header, which the browser will ignore if the response code is
+> anything other than most (but not all) of the 300s and 201.
+
+This is likely because these configuration directives are causing
+subrequests and/or internal redirects, which triggers the handler, but
+doesn't convey its response to the client. This might be an inherent
+limitation of using FastCGI in `AUTHORIZER` mode, because there is no
+way to tell it that it is being triggered from a subrequest (unless
+there is?). More research is needed to probe potential interactions
+with other handlers.
 
 ## Templates
 
-ForgetPasswords has a number of UI states that are embedded in the gem. These
-take the form of template files. The functionality of these templates
-is currently at the absolute bare minimum required to do the job. The
-templates are XHTML, with a basic placeholder substitution
+Forget Passwords has a number of UI states that are embedded in the
+gem. These take the form of template files. The functionality of these
+templates is currently at the absolute bare minimum required to do the
+job. The templates are XHTML, with a basic placeholder substitution
 functionality, which can take place either in processing instructions
 (`<?var $WHATEVER?>`), or attribute values (`<elem
 attr="$WHATEVER"/>`).
@@ -303,7 +329,7 @@ form field by the name of `forward` that contains the current URL.
 
 This resource should actually never be seen, as it currently only
 arises when outside content-handling traffic is directed to locations
-other than the two specified by ForgetPasswords.
+other than the two specified by Forget Passwords.
 
 ### `knock_bad` (currently handled by `basic-409.xhtml`)
 
@@ -378,8 +404,8 @@ script can't connectd to the specified SMTP server.
 
 ### `email_sent` (currently handled by `email-sent.xhtml`)
 
-This is the confirmation page people see when ForgetPasswords has accepted
-their e-mmail address and sent the link-containing e-mail.
+This is the confirmation page people see when Forget Passwords has
+accepted their e-mmail address and sent the link-containing e-mail.
 
 ### `post_only` (currently handled by `post-405.xhtml`)
 
@@ -450,14 +476,15 @@ specific functions within the system, and have a stable location.
 
 * `login` is the target that accepts the `POST` request from the `401`
   page and others, that sends the e-mail and issues a confirmation. It
-  defaults to `/email-link`. This resource is powered by ForgetPasswords and
-  is used internally to configure the location of that resource.
+  defaults to `/email-link`. This resource is powered by Forget
+  Passwords and is used internally to configure the location of that
+  resource.
 * `logout` is the target that accepts the `POST` request to log
   out. It (rather predictably) defaults to `/logout`. This location is
-  also handled by ForgetPasswords.
+  also handled by Forget Passwords.
 * `logout_one` is a _static_ (or other arbitrary) target (i.e., _not_
-  handled by ForgetPasswords) that confirms the user has logged out their
-  current session. It defaults to `/logged-out`.
+  handled by Forget Passwords) that confirms the user has logged out
+  their current session. It defaults to `/logged-out`.
 * `logout_all` is another static target that confirms the user has
   logged out of all devices.
 
@@ -497,6 +524,15 @@ email:
   # additional SMTP configuration would go here, if applicable.
 ```
 
+## Alternate Authentication Methods
+
+It is possible to take the token in the cookie and feed it in as
+either a `Basic` authentication password or `Bearer` token. In the
+case of `Basic`, the username is ignored. This enables `curl` or API
+access, or other automated things like feed readers. There is
+currently no UI for this, but an "app password" management screen is
+potentially on the horizon.
+
 ## Future Directions
 
 This project began on something of a lark, with the intent to make a
@@ -534,22 +570,22 @@ of 2022-04-22), the focus can shift to keeping it that way.
 ### How about expanding out the templates?
 
 Localizing the templates is definitely a possibility, as well as
-making domain-specific overrides so a single ForgetPasswords daemon could
-handle multiple domains with tailor-fit responses for each. I am less
-sanguine about going hog-wild with the templates but I could see some
-kind of future plug-in interface so people could use their favourite
-flavour of templating engine.
+making domain-specific overrides so a single Forget Passwords daemon
+could handle multiple domains with tailor-fit responses for each. I am
+less sanguine about going hog-wild with the templates but I could see
+some kind of future plug-in interface so people could use their
+favourite flavour of templating engine.
 
 ### Reconcile with OAuth
 
-The authentication cookie used by ForgetPasswords bears a striking
+The authentication cookie used by Forget Passwords bears a striking
 resemblance to an [OAuth](https://oauth.net/) bearer token, such that
 could actually _be_ (at least a proxy for) an OAuth bearer token.
 Indeed, bearer tokens would make for an _excellent_ cleavage plane for
 _segmented_ authentication: Method X to bearer token, then bearer
 token to `REMOTE_USER`. This means we could have multiple
-authentication mechanisms (ForgetPasswords, OAuth, X.509, Kerberos, boring
-old password, whatever) operating in the same space at once.
+authentication mechanisms (Forget Passwords, OAuth, X.509, Kerberos,
+boring old password, whatever) operating in the same space at once.
 
 ### The really interesting thing is `mod_authnz_fcgi`
 
@@ -566,7 +602,7 @@ the content handler, that can be addressed directly—provided you write
 your module in C. What `mod_authnz_fcgi` does is tap the
 _authentication_ phase of Apache's request-handling loop and open it
 up to cheap scripts written in any language that speak FastCGI. This
-means that stand-alone modules like ForgetPasswords can be used in
+means that stand-alone modules like Forget Passwords can be used in
 conjunction with *any* downstream Web application framework or
 development strategy. Some additional observations:
 

data/lib/forget-passwords/version.rb

@@ -1,3 +1,3 @@
 module ForgetPasswords
-  VERSION = '0.2.9'
+  VERSION = '0.2.13'
 end

data/lib/forget-passwords.rb

@@ -11,6 +11,7 @@ require 'rack'
 require 'rack/request'
 require 'rack/response'
 
+require 'base64'
 require 'mail'
 
 module ForgetPasswords
@@ -384,7 +385,8 @@ module ForgetPasswords
       resp.set_header "Variable-#{@vars[:redirect]}", target.to_s if
         target != uri # (note this should always be true)
       resp.set_cookie @keys[:cookie], {
-        value: token, secure: req.ssl?, httponly: true, domain: uri.host,
+        value: token, secure: req.ssl?, httponly: true,
+        domain: uri.host, path: ?/, same_site: :strict,
         expires: time_delta(@state.expiry[:cookie]),
       }
 
@@ -397,12 +399,12 @@ module ForgetPasswords
       resp
     end
 
-    def handle_cookie req, token = nil
-      token ||= req.cookies[@keys[:cookie]]
-
+    def handle_token req, token, now = Time.now
       resp = Rack::Response.new
 
-      vars = { LOGIN: @targets[:login], FORWARD: req_uri(req).to_s }
+      uri  = req_uri req
+
+      vars = { LOGIN: @targets[:login], FORWARD: uri.to_s }
 
       # check if token is well-formed
       raise_error(409, :cookie_bad, req, vars: vars) unless token_ok? token
@@ -416,20 +418,13 @@ module ForgetPasswords
         user = @state.user_for(token, record: true, cookie: true)
 
       raise_error(403, :email_not_listed, req, vars: vars) unless
-        @state.acl.listed? req_uri(req), user.email
+        @state.acl.listed? uri, user.email
 
-      now = Time.now
       @state.freshen_token token, from: now
 
       # stamp the token
       @state.stamp_token token, req.ip, seen: now
 
-      # update the cookie expiration
-      resp.set_cookie @keys[:cookie], {
-        value: token, secure: req.ssl?, httponly: true,
-        expires: time_delta(@state.expiry[:cookie], now),
-      }
-
       # just set the variable
       resp.set_header "Variable-#{@vars[:user]}", user.principal.to_s
 
@@ -439,6 +434,23 @@ module ForgetPasswords
       resp
     end
 
+    def handle_cookie req, token = nil
+      token ||= req.cookies[@keys[:cookie]]
+
+      now  = Time.now
+      resp = handle_token req, token, now
+      uri  = req_uri req
+
+      # update the cookie expiration
+      resp.set_cookie @keys[:cookie], {
+        value: token, secure: req.ssl?, httponly: true,
+        domain: uri.host, path: ?/, same_site: :strict,
+        expires: time_delta(@state.expiry[:cookie], now),
+      }
+
+      resp
+    end
+
     def handle_login req
       uri  = req_uri req
       resp = Rack::Response.new
@@ -519,23 +531,24 @@ module ForgetPasswords
       resp
     end
 
-    # def handle_post req
-    #   return Rack::Response[403, { 'Content-Type' => 'text/plain' }, 'wat lol']
-
-    #   if logout = req.POST[@keys[:logout]]
-    #     handle_logout req, logout
-    #   elsif email = req.POST[@keys[:email]]
-    #     handle_login req, email
-    #   elsif token = req.cookies[@keys[:cookie]]
-    #     # next check for a cookie
-    #     handle_cookie req, token
-    #   else
-    #     default_401 req
-    #   end
-    # end
-
     def handle_auth req
-      if knock = req.GET[@keys[:query]]
+      auth = req.get_header('Authorization') || req.env['HTTP_AUTHORIZATION']
+      if auth and !auth.strip.empty?
+        mech, *auth = auth.strip.split
+        token = case mech.downcase
+                when 'basic'
+                  # can't trust/use rack here
+                  Base64.decode64(auth.first || '').split(?:, 2).last
+                when 'bearer'
+                  auth.first
+                end
+
+        if token
+          handle_token req, token
+        else
+          default_401 req
+        end
+      elsif knock = req.GET[@keys[:query]]
         # check for a knock first; this overrides everything
         handle_knock req, knock
       # elsif req.post?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: forget-passwords
 version: !ruby/object:Gem::Version
-  version: 0.2.9
+  version: 0.2.13
 platform: ruby
 authors:
 - Dorian Taylor
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-04-24 00:00:00.000000000 Z
+date: 2022-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -305,7 +305,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.11
 signing_key:
 specification_version: 4
 summary: Web authentication module for the extremely lazy