authtown 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5354c22eca5eed6bbf2bdfb9abc22b34681b4eea99ae84a22e692a522b12df64
-  data.tar.gz: ccf72db36f90a5059724f1df6aaa4c16ac261bf8f7fa27c093b08ffe010c35f5
+  metadata.gz: 0a1e9c9ffe66cbcc014a3b43c534d43cffb1e5693889b37c0bbf58ce7934c17b
+  data.tar.gz: b93025f12b596cced088cbc8dc5a524392f71c7f782e2f05c00938b555ef901d
 SHA512:
-  metadata.gz: ffa84f2f6d723e4c790ee27a242231fcfcb3c70f4567f163d431a7b76d750911e3b98a4d63a4d40cdcd663da20ac4f7d932d59f0107732077d93cd68307d48af
-  data.tar.gz: 6444e3cf4af35c02c8c88bf6bd93d17aa2226e81ea193f7353eaae3b8a757d1a201209945a08939604ae5f6586d9f8075edbbf876da5026f31ead98e2bb7b79c
+  metadata.gz: 7c6e9ced5cf4b15284a451e590c34cbe97a33e940876b3bd28ab0117b6ee7ee38c9eeecb3edadb6509614b42190930d770a77ebb49a8a762cfd11430e0b478ba
+  data.tar.gz: 898616d041384839c3358bbe439947f0299ae639ebd6410d44912b7252f2c16b3f80d6e5ae2f77b35cd16bd7785f2b89a5331296dd7bfffcb52225e1ef4db442

data/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2025-01-12
+
+- Fix incorrect Rodauth method override
+
 ## [0.4.0] - 2024-05-06
 
 - Another refactor to support latest updates in Bridgetown v2

data/README.md

@@ -1,35 +1,388 @@
 # Authtown: Rodauth integration for Bridgetown
 
-A Bridgetown plugin which provides authentication and account management via database access and SSR routes.
+A Bridgetown plugin which provides authentication and account management via database access and SSR routes, powered by [Rodauth](https://rodauth.jeremyevans.net). 
 
-**WIP: not yet for public use!**
+**WIP — public 1.0 release coming soon once Bridgetown 2.0 ships!**
 
 ## Installation
 
+As a prerequisite to installing Authtown, make sure you've set up Sequel database access via the [bridgetown_sequel](https://github.com/bridgetownrb/bridgetown_sequel) plugin. You'll also need a way to send mail (Authtown will install the `mail` gem automatically) via a service like Sendgrid, Mailgun, etc. In addition, if you haven't already, you will need to add the `dotenv` and `bridgetown-routes` plugins as described in your `Gemfile` and `config/initializers.rb` file. Finally, for an easy way to generate account forms, install the [Lifeform](https://github.com/bridgetownrb/lifeform) plugin.
+
 Run this command to add this plugin to your site's Gemfile:
 
 ```shell
 bundle add authtown
 ```
 
-Then add the initializer to your configuration in `config/initializers.rb`:
+Then set up a mail initializer file:
+
+```ruby
+Bridgetown.initializer :mail do |password:|
+  # set up options below for your particular email service
+  Mail.defaults do
+    delivery_method :smtp,
+                    address: "smtp.sendgrid.net",
+                    port: 465,
+                    user_name: "apikey",
+                    password:,
+                    authentication: :plain,
+                    tls: true
+  end
+end
+```
+
+And call that from your configuration in `config/initializers.rb`:
+
+```ruby
+only :server do
+  init :mail do # set up options below
+    password ENV.fetch("SERVICE_API_KEY", nil) # can come from .env file or hosting environment
+  end
+end
+```
+
+Next, add Authtown's initialization for your configuration. Here's a basic set of options:
+
+```ruby
+init :lifeform
+
+init :authtown do
+  # Defaults, uncomment to modify:
+  #
+  # account_landing_page "/account/profile"
+  # user_class_resolver -> { User }
+  # user_name_field :first_name
+
+  rodauth_config -> do
+    email_from "Your Name <youremail@example.com>"
+
+    reset_password_email_body do
+      "Howdy! You or somebody requested a password reset for your account.\n" \
+        "If that's legit, here's the link:\n#{reset_password_email_link}\n\n" \
+        "Otherwise, you may safely ignore this message.\n\nThanks!\n–You @ Company"
+    end
+
+    enable :http_basic_auth if Bridgetown.env.test?
+
+    # You can define additional options here as provided by Rodauth directly
+  end
+end
+```
+
+You will need to generate a secret key for Roda's session handling. Run `bin/bridgetown secret` to copy that into your .env file.
+
+```env
+RODA_SECRET_KEY=1f8dbd0da3a4...
+```
+
+You will also need to generate a Sequel migration for your user accounts. Here is an example, you can tweak as necessary. Run `bin/bridgetown db::migrations:new filename=create_users`, then edit the file:
+
+```ruby
+Sequel.migration do
+  change do
+    extension :date_arithmetic
+
+    create_table(:users) do
+      primary_key :id, type: :Bignum
+      citext :email, null: false
+      constraint :valid_email, email: /^[^,;@ \r\n]+@[^,@; \r\n]+\.[^,@; \r\n]+$/
+      String :first_name
+      String :password_hash, null: false
+      index :email, unique: true
+
+      DateTime :created_at
+      DateTime :updated_at
+    end
+
+    # Used by the remember me feature
+    create_table(:account_remember_keys) do
+      foreign_key :id, :users, primary_key: true, type: :Bignum
+      String :key, null: false
+      DateTime :deadline, { null: false, default: Sequel.date_add(Sequel::CURRENT_TIMESTAMP, days: 30) }
+    end
+
+    create_table(:account_password_reset_keys) do
+      foreign_key :id, :users, primary_key: true, type: :Bignum
+      String :key, null: false
+      DateTime :deadline, { null: false, default: Sequel.date_add(Sequel::CURRENT_TIMESTAMP, days: 1) }
+      DateTime :email_last_sent, null: false, default: Sequel::CURRENT_TIMESTAMP
+    end
+  end
+end
+```
+
+Also create your User model:
+
+```ruby
+# ./models/user.rb
+
+require "bcrypt"
+
+class User < Sequel::Model
+  def self.password_for_string(str) # helper method
+    BCrypt::Password.create(str).to_s
+  end
+end
+```
+
+And then run `bin/bridgetown db:migrate`.
+
+Now, let's set up our forms and auth pages. We'll begin by creating an Account form:
 
 ```ruby
-init :authtown
+# ./models/forms/account.rb
+
+module Forms
+  class Account < Lifeform::Form
+    fields do
+      field rodauth.login_param.to_sym,
+            type: :email,
+            label: rodauth.login_label,
+            required: true,
+            autocomplete: "username",
+            autofocus: true
+      field :name,
+            label: "Your Name",
+            autocomplete: "name",
+            required: true
+      field rodauth.password_param.to_sym,
+            type: :password,
+            label: rodauth.password_label,
+            required: true,
+            autocomplete: rodauth.password_field_autocomplete_value
+      field :submit, type: :submit_button, label: rodauth.login_button
+    end
+  end
+end
 ```
 
-## Usage
+Next, let's create the pages for logging in or creating an account.
+
+**src/_routes/auth/login.erb**
+
+```erb
+---<%
+render_with do
+  layout :page,
+  title "Sign In"
+end
+%>---
+
+<% if rodauth.logged_in? %>
+  <p style="text-align:center">
+    It looks like you're already signed in. Would you like to <a href="/account/profile">view your profile?</a>
+  </p>
+<% end %>
+
+<article>
+  <%= render Forms::Account.new(id: "login-form", url: rodauth.login_path, class: "centered") do |f| %>
+    <%= render "form_errors" %>
+    <%=
+      render f.field(
+        rodauth.login_param,
+        value: r.params[rodauth.login_param],
+        aria: { invalid: rodauth.field_error(rodauth.login_param).present? }
+      )
+    %>
+    <%=
+      render f.field(
+        rodauth.password_param,
+        aria: { invalid: rodauth.field_error(rodauth.password_param).present? }
+      ) %>
+    <%=
+      render f.field(:submit)
+    %>
+  <% end %>
+</article>
+
+<p>Need to reset password? <a href="<%= rodauth.reset_password_request_path %>">Guess so ➞</a></p>
+
+<hr />
+
+<p>Don't have an account yet? <a href="<%= rodauth.create_account_path %>">Sign up today!</a></p>
+```
+
+**src/_routes/auth/create-account.erb**
+
+```erb
+---<%
+render_with do
+  layout :page,
+  title "Sign Up"
+end
+%>---
+
+<% if rodauth.logged_in? %>
+  <p style="text-align:center">
+    It looks like you're already signed in. Would you like to <a href="/account/profile">view your profile?</a>
+  </p>
+<% end %>
+
+<article>
+  <%= render Forms::Account.new(url: rodauth.create_account_path, class: "centered") do |f| %>
+    <%= render "form_errors" %>
+    <%=
+      render f.field(
+        rodauth.login_param,
+        value: r.params[rodauth.login_param],
+        aria: { invalid: rodauth.field_error(rodauth.login_param).present? }
+      )
+    %>
+    <%=
+      render f.field(
+        :first_name,
+        value: r.params[:first_name]
+      )
+    %>
+    <%=
+      render f.field(
+        rodauth.password_param,
+        aria: { invalid: rodauth.field_error(rodauth.password_param).present? }
+      ) %>
+    <%=
+      render f.field(:submit, label: rodauth.create_account_button)
+    %>
+  <% end %>
+</article>
+
+<% unless rodauth.logged_in? %>
+  <p style="text-align:center">Have an account already? <a href="/auth/login">Sign in here</a>.</p>
+<% end %>
+```
+
+**src/_partials/form_errors.erb**
+
+```erb
+<form-errors>
+  <p aria-live="assertive">
+    <% if flash[:error] %>
+      <%= flash[:error] %>:
+      <br/>
+      <small>
+        <% if rodauth.field_error(rodauth.login_param) %>
+          <%= rodauth.field_error(rodauth.login_param) %>
+        <% end %>
+        <% if rodauth.field_error(rodauth.password_param) %>
+          <%= rodauth.field_error(rodauth.password_param) %>
+        <% end %>
+      </small>
+    <% end %>
+  </p>
+</form-errors>
+```
+
+We'll still need ones for password reset, but let's hold off for the moment. We're almost ready to test this out, but you'll also need an account profile page for when the user's successfully signed in:
+
+**src/_routes/account/profile.erb**
+
+```erb
+---<%
+rodauth.require_authentication # always include this before logged-in only routes
+
+render_with do
+  layout :page,
+  title "Your Account"
+end
+%>---
+
+<%= markdownify do %>
+  
+Welcome back, **<%= current_user.first_name %>**.
+
+(other content here)
+
+<% end %>
+
+<hr />
+
+<form method="post" action="<%= rodauth.logout_path %>">
+  <%= csrf_tag(rodauth.logout_path) %>
+  <p>You’re logged in as: <strong><%= current_user.email %></strong>.</p>
+  <button type="submit"><%= rodauth.logout_button %></button>
+</form>
+```
+
+At this point, you should be able to start up your Bridgetown site, navigate to `/auth/create-account`, and test creating an account, logging out, logging back in, etc.
+
+As a final step, we'll need to handle password reset. Add the following pages:
+
+**src/_routes/auth/reset-password-request.erb**
+
+```erb
+---<%
+render_with do
+  layout :page,
+  title "Reset Your Password"
+end
+%>---
+
+<article>
+<%= render Forms::Account.new(url: rodauth.reset_password_request_path, class: "centered") do |f| %>
+  <%= render "form_errors" %>
+  <%=
+    render f.field(
+      rodauth.login_param,
+      value: r.params[rodauth.login_param],
+      aria: { invalid: rodauth.field_error(rodauth.login_param).present? }
+    )
+  %>
+  <%=
+    render f.field(:submit, label: rodauth.reset_password_request_button)
+  %>
+<% end %>
+</article>
+```
+
+
+**src/_routes/auth/reset-password.erb**
+
+```erb
+---<%
+render_with do
+  layout :page,
+  title "Save New Password"
+end
+%>---
+
+<article>
+<%= render Forms::Account.new(url: rodauth.reset_password_path, class: "centered") do |f| %>
+  <%= render "form_errors" %>
+  <%=
+    render f.field(
+      rodauth.password_param,
+      aria: { invalid: rodauth.field_error(rodauth.password_param).present? }
+    )
+  %>
+  <%=
+    render f.field(:submit, label: rodauth.reset_password_button)
+  %>
+<% end %>
+</article>
+```
+
+**src/_routes/account/reset-link-sent.erb**
+
+```erb
+---<%
+render_with do
+  layout :page
+  title "Reset Link Sent"
+end
+%>---
+
+<p style="text-align: center">Check your email, it should be arriving in just a moment.</p>
+```
 
-The plugin will…
+Now when you navigate to `/auth/reset-password-request`, you should be able to get a link for saving a new password.
 
-## Testing
+## Testing the Gem
 
 * Run `bundle exec rake test` to run the test suite
 * Or run `script/cibuild` to validate with Rubocop and Minitest together.
 
 ## Contributing
 
-1. Fork it (https://github.com/username/my-awesome-plugin/fork)
+1. Fork it (https://github.com/bridgetownrb/authtown)
 2. Clone the fork using `git clone` to your local development machine.
 3. Create your feature branch (`git checkout -b my-new-feature`)
 4. Commit your changes (`git commit -am 'Add some feature'`)

data/lib/authtown/initializer.rb

@@ -19,6 +19,7 @@ Bridgetown.initializer :authtown do |
 
   config.only :server do
     require "authtown/routes/rodauth"
+    require "authtown/rodauth_mixin"
 
     # @param app [Class<Roda>]
     config.roda do |app|
@@ -78,6 +79,8 @@ Bridgetown.initializer :authtown do |
 
         instance_exec(&rodauth_config) if rodauth_config
       end
+
+      app.rodauth.prepend Authtown::RodauthMixin
     end
   end
 

data/lib/authtown/rodauth_mixin.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# This gets prepended into the RodAuth class after plugin load
+module Authtown::RodauthMixin
+  def login_failed_reset_password_request_form
+    # part of reset_password internals…no-op since we're rendering our own forms
+  end
+end

data/lib/authtown/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Authtown
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end

data/lib/authtown/view_mixin.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# This gets prepended into the RodaApp class
 module Authtown::ViewMixin
   def locals = @_route_locals
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: authtown
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Bridgetown Team
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-05-06 00:00:00.000000000 Z
+date: 2025-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bridgetown
@@ -133,6 +133,7 @@ files:
 - lib/authtown.rb
 - lib/authtown/builder.rb
 - lib/authtown/initializer.rb
+- lib/authtown/rodauth_mixin.rb
 - lib/authtown/routes/rodauth.rb
 - lib/authtown/version.rb
 - lib/authtown/view_mixin.rb