searls-auth 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e2b6983e76f48e3663946462d67f0dfdf62914aa8187c29a332111f430335f2
-  data.tar.gz: 0cfbab5b379a053ff0f23406e25c045caa6d7ca2c249330d0ac24b459e6f1ecf
+  metadata.gz: c23b1737c22e177cbc5da56d7aab735c39408b87c6954b59b15b5f6fc3553021
+  data.tar.gz: 9906eabdf2bf3593d993bdfc6a6ac5234f346a9fa4f0c26b773fa4291a80fd3a
 SHA512:
-  metadata.gz: 820ae8d2258753dd6e7f2f9bea7054537f0242aacc5218f220cc3a83d639a11a5204bcca728a95ec06e4ae8094994609abf0859f5df8162684a56c42bd27757b
-  data.tar.gz: 9d6f9469c3c4d99cd42f0b410f89934951924c605cff3fe9bf7490064d790d1a814b20e154574de45d525b325acaac6ccd793496f2ffbc83645042e4f2a0268f
+  metadata.gz: 2cbd987345d290d2648a67817531f571482f56002a71b5a7a0aacae01f89afc93cc799cf248712f3eae72c630623d4915cf0f3d5f8c71e238a740a9701a6bd35
+  data.tar.gz: a1e03993409a4306dfe443385c993fa6e9d53f2328914311c46996c263212fcbe0b7d45e93d1a7ed092dc45ea4c2eadb149384d11a97dca097240648ee8f052e

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.1.1] - 2025-04-27
+
+* Improve error message when token generation fails due to a token not being configured on the user model
+
 ## [0.1.0] - 2025-04-26
 
 * Add `max_allowed_short_code_attempts` configuration, beyond which the code is erased from the session and the user needs to login again (default: 10)

data/README.md

@@ -1 +1,89 @@
 # searls-auth
+
+This gem provides a Ruby on Rails engine that implements a minimal, opinionated, and pleasant email-based authentication system. It has zero other dependencies, which is the correct number of dependencies.
+
+For a detailed walk-through with pictures and whatnot, check out this [example app README](/example/simple_app/README.md). Below you'll find the basic steps for getting started.
+
+## Install it
+
+Add it to your Gemfile and `bundle` it:
+
+```ruby
+gem "searls-auth"
+```
+
+## Mount it
+
+Next, you need to mount the gem's Engine to host any of the authentication controllers and mailers.
+
+You can mount the engine at whatever you path you like (mounting it to "/" can result in some goofy behavior, so maybe not that one). I just do "/auth" because I'm boring:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # …
+  mount Searls::Auth::Engine => "/auth"
+  # …
+end
+```
+
+If you run your development server and visit [http://localhost:3000/auth/login](http://localhost:3000/auth/login), you should see an ugly login page. (If things look really goofy, it's because the gem defaults to your app's `"application"` layout).
+
+## Secure it
+
+If you've got a `User` model with an `email` attribute, you're two-thirds of the way to this thing working. All you need now is to associate [a secure token](https://api.rubyonrails.org/classes/ActiveRecord/TokenFor/ClassMethods.html#method-i-generates_token_for) with the model named `:email_auth`.
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  # …
+  generates_token_for :email_auth, expires_in: 30.minutes
+  # …
+end
+```
+
+(You can [name all these things whatever you want](#configure-it), but this is what searls-auth will assume by default.)
+
+I'm writing this README as I add searls-auth to my new [POSSE Party](https://posseparty.com) app. As soon as I added the above line I visited [http://localhost:3000/auth/login](http://localhost:3000/auth/login), typed in my email, hit "Log in", and saw this email get sent (thanks to [letter_opener](https://github.com/ryanb/letter_opener)):
+
+![A default searls-auth login email](https://github.com/user-attachments/assets/07114dae-a95b-49bd-ba57-92042c62c1b7)
+
+When I pasted in the six-digit code into the (also ugly) default verification page, it auto-submitted the form. That's because my has a vanilla [import maps](https://guides.rubyonrails.org/working_with_javascript_in_rails.html#import-maps) configuration, the least-bad of the various JavaScript ordeals Rails has on offer. (Don't use import maps? Then I leave figuring out how to load the gem's [Stimulus controllers](app/javascript/controllers/searls_auth_login_controller.js) as an exercise to the reader.)
+
+I repeated the process to ensure the "magic link" also would have worked by visiting [http://localhost:3000/auth/logout](http://localhost:3000/auth/logout) and then clicking the link.
+
+## Configure it
+
+Almost every user-facing thing searls-auth does is configurable, because authentication is an _intimate and precious_ thing that every application must find a way to tweak, brand, and confuse.
+
+To configure things, create an initializer:
+
+```
+touch config/initializers/searls_auth.rb
+```
+
+And paste this into it as a starting point:
+
+```ruby
+Rails.application.config.after_initialize do
+  Searls::Auth.configure do |config|
+    # You can find the defaults here-ish:
+    # https://github.com/searlsco/searls-auth/blob/main/lib/searls/auth.rb#L14
+    #
+    # The expected type of each option is documented inline here-ish:
+    # https://github.com/searlsco/searls-auth/blob/main/lib/searls/auth/config.rb#L3
+    #
+    # (Note that many options can take a proc or a value, which you may want)
+    #
+    # Override any option like this:
+    # config.app_name = "POSSE Party"
+  end
+end
+```
+As stated in the comment above, you can find each configuration and its default value in the code.
+
+## Use it
+
+Of course, having a user be "logged in" or not doesn't mean anything if your application doesn't do anything with the knowledge. Users that are logged in will have `session[:user_id]` set to the value of the logged-in user's ID. Logged out users won't have anything set to `session[:user_id]`. What you do with that is your job, not this gem. (Wait, after 20 years does this mean I finally understand the difference between authentication and authorization? Better late than never.)
+
+If this is your first rodeo and you just read the previous paragraph and thought, _yeah, but now what?_, check out the tail end of the [example app README](/example/simple_app/README.md), which shows an approach that a lot of apps use.

data/lib/searls/auth/config.rb

@@ -2,12 +2,12 @@ module Searls
   module Auth
     Config = Struct.new(
       # Data setup
-      :user_finder_by_email, # proc (email)
-      :user_finder_by_id, # proc (id)
-      :user_finder_by_token, # proc (token)
-      :user_initializer, # proc (params)
+      :user_finder_by_email, # proc(email)
+      :user_finder_by_id, # proc(id)
+      :user_finder_by_token, # proc(token)
+      :user_initializer, # proc(params)
       :user_name_method, # string
-      :token_generator, # proc ()
+      :token_generator, # proc()
       :token_expiry_minutes, # integer
       # Controller setup
       :preserve_session_keys_after_logout, # array of symbols
@@ -21,11 +21,11 @@ module Searls
       :mail_login_template_path, # string
       :mail_login_template_name, # string
       # Routing setup
-      :redirect_path_after_register, # string or proc, all new registrations redirect here
-      :default_redirect_path_after_login, # string or proc, only redirected here if redirect_path param not set
+      :redirect_path_after_register, # string or proc(user, params, request, routes), all new registrations redirect here
+      :default_redirect_path_after_login, # string or proc(user, params, request, routes), only redirected here if redirect_path param not set
       # Hook setup
-      :validate_registration, # proc (user, params, errors = []), must return an array of error messages where empty means valid
-      :after_login_success, # proc (user)
+      :validate_registration, # proc(user, params, errors = []), must return an array of error messages where empty means valid
+      :after_login_success, # proc(user)
       # Branding setup
       :app_name, # string
       :app_url, # string

data/lib/searls/auth/emails_link.rb

@@ -4,12 +4,31 @@ module Searls
       def email(user:, short_code:, redirect_path: nil, redirect_subdomain: nil)
         LoginLinkMailer.with(
           user:,
-          token: Searls::Auth.config.token_generator.call(user),
+          token: generate_token!(user),
           short_code:,
           redirect_path:,
           redirect_subdomain:
         ).login_link.deliver_later
       end
+
+      private
+
+      def generate_token!(user)
+        Searls::Auth.config.token_generator.call(user)
+      rescue KeyError => e
+        raise Error, <<~MSG
+          Secure token generation for user failed!
+
+          Message: #{e.message}
+          User: #{user.inspect}
+
+          This can probably be fixed by adding a line like this to your #{user.class.name} class:
+
+            generates_token_for :email_auth, expires_in: 30.minutes
+
+          Otherwise, you may want to override searls-auth's "token_generator" setting with a proc of your own.
+        MSG
+      end
     end
   end
 end

data/lib/searls/auth/version.rb

@@ -1,5 +1,5 @@
 module Searls
   module Auth
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: searls-auth
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Justin Searls