feat: enhance authentication endpoints and request handling for improved user experience

- Updated ChangePasswordEndpoint, LoginEndpoint, LogoutEndpoint, MeEndpoint, PermissionsEndpoint, RefreshEndpoint, RegisterEndpoint, OAuthCallbackEndpoint, and OAuthProviderEndpoint to utilize structured request and response types, improving clarity and maintainability.
- Implemented consistent error handling and response formatting across endpoints, ensuring uniformity in API responses.
- Introduced new request structures for handling parameters in ChangePasswordRequest, LoginRequest, LogoutRequest, MeRequest, PermissionsRequest, RefreshTokenRequest, and RegisterRequest, enhancing modularity and organization.
- Refactored response structures to include JSON serialization, improving the overall response handling in the authentication flow.

Author: eliasjpr

src/azu_cli/templates/auth/src/endpoints/auth/change_password_endpoint.cr.ecr

@@ -1,4 +1,5 @@
 require "../../models/user"
+require "../../response/auth/change_password_json"
 <%- if using_jwt? || using_authly? %>
 require "jwt"
 <%- end %>
@@ -11,29 +12,43 @@ module <%= project.camelcase %>::Auth
 
     def call : Auth::ChangePasswordResponse | Azu::Response::Empty
       user = current_user
-      halt 401, {error: "Not authenticated"}.to_json unless user
+      unless user
+        context.response.status = HTTP::Status::UNAUTHORIZED
+        context.response.content_type = "application/json"
+        context.response.print({error: "Not authenticated"}.to_json)
+        return Azu::Response::Empty.new
+      end
 
       req = change_password_request
       unless req.valid?
-        halt 422, {errors: req.errors}.to_json
+        context.response.status = HTTP::Status::UNPROCESSABLE_ENTITY
+        context.response.content_type = "application/json"
+        context.response.print({errors: req.errors}.to_json)
+        return Azu::Response::Empty.new
       end
 
       u = user.not_nil!
       unless u.verify_password(req.current_password)
-        halt 401, {error: "Current password is incorrect"}.to_json
+        context.response.status = HTTP::Status::UNAUTHORIZED
+        context.response.content_type = "application/json"
+        context.response.print({error: "Current password is incorrect"}.to_json)
+        return Azu::Response::Empty.new
       end
 
       u.password = req.new_password
       unless u.save
-        halt 422, {errors: u.errors}.to_json
+        context.response.status = HTTP::Status::UNPROCESSABLE_ENTITY
+        context.response.content_type = "application/json"
+        context.response.print({errors: u.errors}.to_json)
+        return Azu::Response::Empty.new
       end
 
       Auth::ChangePasswordResponse.new
     end
 
     private def current_user : ::User?
       <%- if using_jwt? || using_authly? %>
-      token = request.headers["Authorization"]?.try(&.sub("Bearer ", ""))
+      token = context.request.headers["Authorization"]?.try(&.sub("Bearer ", ""))
       return nil unless token
 
       payload, header = JWT.decode(token, jwt_secret, JWT::Algorithm::HS256)

src/azu_cli/templates/auth/src/endpoints/auth/login_endpoint.cr.ecr

@@ -1,5 +1,6 @@
 <%# Requires first (Crystal convention) %>
 require "../../models/user"
+require "../../response/auth/login_json"
 <%- if using_jwt? || using_authly? %>
 require "jwt"
 <%- end %>
@@ -13,12 +14,18 @@ module <%= project.camelcase %>::Auth
     def call : Auth::LoginResponse | Azu::Response::Empty
       req = login_request
       unless req.valid?
-        halt 422, {errors: req.errors}.to_json
+        context.response.status = HTTP::Status::UNPROCESSABLE_ENTITY
+        context.response.content_type = "application/json"
+        context.response.print({errors: req.errors}.to_json)
+        return Azu::Response::Empty.new
       end
 
       user = ::User.authenticate(req.email, req.password)
       unless user
-        halt 401, {error: "Invalid email or password"}.to_json
+        context.response.status = HTTP::Status::UNAUTHORIZED
+        context.response.content_type = "application/json"
+        context.response.print({error: "Invalid email or password"}.to_json)
+        return Azu::Response::Empty.new
       end
 
       <%- if using_jwt? || using_authly? %>

src/azu_cli/templates/auth/src/endpoints/auth/logout_endpoint.cr.ecr

@@ -1,13 +1,14 @@
+require "../../requests/auth/logout_request"
+require "../../response/auth/logout_json"
+
 module <%= project.camelcase %>::Auth
   struct LogoutEndpoint
-    include Azu::Endpoint(Azu::Request::Empty, Auth::LogoutResponse | Azu::Response::Empty)
+    include Azu::Endpoint(Auth::LogoutRequest, Auth::LogoutResponse)
 
     post "/auth/logout"
 
-    def call : Auth::LogoutResponse | Azu::Response::Empty
-      <%- if using_session? %>
-      session.delete("user_id")
-      <%- end %>
+    def call : Auth::LogoutResponse
+      session.delete("_csrf_token") if respond_to?(:session)
       Auth::LogoutResponse.new
     end
   end

src/azu_cli/templates/auth/src/endpoints/auth/me_endpoint.cr.ecr

@@ -1,37 +1,37 @@
 <%# Requires first (Crystal convention) %>
 require "../../models/user"
+require "../../requests/auth/me_request"
+require "../../response/auth/me_json"
 <%- if using_jwt? || using_authly? %>
 require "jwt"
 <%- end %>
 
 module <%= project.camelcase %>::Auth
   struct MeEndpoint
-    include Azu::Endpoint(Azu::Request::Empty, Auth::MeResponse | Azu::Response::Empty)
+    include Azu::Endpoint(Auth::MeRequest, Auth::MeResponse | Azu::Response::Empty)
 
     get "/auth/me"
 
     def call : Auth::MeResponse | Azu::Response::Empty
       user = current_user
-      halt 401, {error: "Not authenticated"}.to_json unless user
+      unless user
+        context.response.status = HTTP::Status::UNAUTHORIZED
+        context.response.content_type = "application/json"
+        context.response.print({error: "Not authenticated"}.to_json)
+        return Azu::Response::Empty.new
+      end
 
       u = user.not_nil!
-      data = {
-        "id" => JSON::Any.new(u.id),
-        "email" => JSON::Any.new(u.email),
-        "name" => JSON::Any.new(u.name || ""),
-        "role" => JSON::Any.new(u.role),
-      } of String => JSON::Any
-      Auth::MeResponse.new(data)
+      Auth::MeResponse.new(u.id, u.email, u.name, u.role)
     end
 
     private def current_user : ::User?
       <%- if using_jwt? || using_authly? %>
-      token = request.headers["Authorization"]?.try(&.sub("Bearer ", ""))
+      token = context.request.headers["Authorization"]?.try(&.sub("Bearer ", ""))
       return nil unless token
+
       payload, header = JWT.decode(token, jwt_secret, JWT::Algorithm::HS256)
-      user_id = payload["sub"]?.try(&.as_s).try(&.to_i64)
-      return nil unless user_id
-      ::User.find(user_id)
+      ::User.find(payload["sub"].as_s.to_i64)
       <%- else %>
       id_val = session["user_id"]?
       return nil unless id_val

src/azu_cli/templates/auth/src/endpoints/auth/oauth_callback_endpoint.cr.ecr

@@ -8,24 +8,39 @@ require "jwt"
 
 module <%= project.camelcase %>::Auth
   struct OAuthCallbackEndpoint
-    include Azu::Endpoint(Azu::Request::Empty, Azu::Response::Empty | Auth::LoginResponse)
+    include Azu::Endpoint(Azu::Request, Azu::Response::Empty | Auth::LoginResponse)
 
     get "/auth/oauth/:provider/callback"
 
     def call : Azu::Response::Empty | Auth::LoginResponse
       provider = params[":provider"]? || params["provider"]?
       code = params["code"]?
       state = params["state"]?
-      halt 400, {error: "provider required"}.to_json unless provider
-      halt 400, {error: "code required"}.to_json unless code
+      unless provider
+        context.response.status = HTTP::Status::BAD_REQUEST
+        context.response.content_type = "application/json"
+        context.response.print({error: "provider required"}.to_json)
+        return Azu::Response::Empty.new
+      end
+      unless code
+        context.response.status = HTTP::Status::BAD_REQUEST
+        context.response.content_type = "application/json"
+        context.response.print({error: "code required"}.to_json)
+        return Azu::Response::Empty.new
+      end
 
       callback = oauth_callback_url(provider)
       token = Authly.exchange_code(provider, code, callback, state)
       profile = Authly.fetch_profile(provider, token)
 
       email = profile["email"]?.try(&.to_s)
       name = profile["name"]?.try(&.to_s)
-      halt 422, {error: "email not available from provider"}.to_json unless email
+      unless email
+        context.response.status = HTTP::Status::UNPROCESSABLE_ENTITY
+        context.response.content_type = "application/json"
+        context.response.print({error: "email not available from provider"}.to_json)
+        return Azu::Response::Empty.new
+      end
 
       user = ::User.find_by(email: email) || begin
         u = ::User.new

src/azu_cli/templates/auth/src/endpoints/auth/oauth_provider_endpoint.cr.ecr

@@ -8,13 +8,18 @@ require "jwt"
 
 module <%= project.camelcase %>::Auth
   struct OAuthProviderEndpoint
-    include Azu::Endpoint(Azu::Request::Empty, Azu::Response::Empty | Auth::LoginResponse)
+    include Azu::Endpoint(Azu::Request, Azu::Response::Empty | Auth::LoginResponse)
 
     get "/auth/oauth/:provider"
 
     def call : Azu::Response::Empty | Auth::LoginResponse
       provider = params[":provider"]? || params["provider"]?
-      halt 400, {error: "provider required"}.to_json unless provider
+      unless provider
+        context.response.status = HTTP::Status::BAD_REQUEST
+        context.response.content_type = "application/json"
+        context.response.print({error: "provider required"}.to_json)
+        return Azu::Response::Empty.new
+      end
 
       callback = oauth_callback_url(provider)
 

src/azu_cli/templates/auth/src/endpoints/auth/permissions_endpoint.cr.ecr

@@ -1,34 +1,40 @@
 <%- if rbac_enabled? %>
 <%# Requires first (Crystal convention) %>
 require "../../models/user"
+require "../../requests/auth/permissions_request"
+require "../../response/auth/permissions_json"
 <%- if using_jwt? || using_authly? %>
 require "jwt"
 <%- end %>
 
 module <%= project.camelcase %>::Auth
   struct PermissionsEndpoint
-    include Azu::Endpoint(Azu::Request::Empty, Auth::PermissionsResponse | Azu::Response::Empty)
+    include Azu::Endpoint(Auth::PermissionsRequest, Auth::PermissionsResponse | Azu::Response::Empty)
 
     get "/auth/permissions"
 
     def call : Auth::PermissionsResponse | Azu::Response::Empty
       user = current_user
-      halt 401, {error: "Not authenticated"}.to_json unless user
+      unless user
+        context.response.status = HTTP::Status::UNAUTHORIZED
+        context.response.content_type = "application/json"
+        context.response.print({error: "Not authenticated"}.to_json)
+        return Azu::Response::Empty.new
+      end
 
       u = user.not_nil!
-      perms = u.permissions.map(&.name)
       roles = u.roles.map(&.name)
-      Auth::PermissionsResponse.new(perms, roles)
+      permissions = u.permissions.map(&.name)
+      Auth::PermissionsResponse.new(roles, permissions)
     end
 
     private def current_user : ::User?
       <%- if using_jwt? || using_authly? %>
-      token = request.headers["Authorization"]?.try(&.sub("Bearer ", ""))
+      token = context.request.headers["Authorization"]?.try(&.sub("Bearer ", ""))
       return nil unless token
+
       payload, header = JWT.decode(token, jwt_secret, JWT::Algorithm::HS256)
-      user_id = payload["sub"]?.try(&.as_s).try(&.to_i64)
-      return nil unless user_id
-      ::User.find(user_id)
+      ::User.find(payload["sub"].as_s.to_i64)
       <%- else %>
       id_val = session["user_id"]?
       return nil unless id_val

src/azu_cli/templates/auth/src/endpoints/auth/refresh_endpoint.cr.ecr

@@ -1,6 +1,7 @@
 <%- if using_jwt? || using_authly? %>
 <%# Requires first (Crystal convention) %>
 require "../../models/user"
+require "../../response/auth/refresh_json"
 require "jwt"
 
 module <%= project.camelcase %>::Auth
@@ -12,68 +13,79 @@ module <%= project.camelcase %>::Auth
     def call : Auth::RefreshResponse | Azu::Response::Empty
       req = refresh_token_request
       unless req.valid?
-        halt 422, {errors: req.errors}.to_json
+        context.response.status = HTTP::Status::UNPROCESSABLE_ENTITY
+        context.response.content_type = "application/json"
+        context.response.print({errors: req.errors}.to_json)
+        return Azu::Response::Empty.new
       end
 
+      <%- if using_jwt? || using_authly? %>
       payload, header = JWT.decode(req.refresh_token, jwt_refresh_secret, JWT::Algorithm::HS256)
       unless payload["type"]? == "refresh"
-        halt 401, {error: "Invalid refresh token"}.to_json
+        context.response.status = HTTP::Status::UNAUTHORIZED
+        context.response.content_type = "application/json"
+        context.response.print({error: "Invalid refresh token"}.to_json)
+        return Azu::Response::Empty.new
       end
 
-      user_id = payload["sub"]?.try(&.as_s).try(&.to_i64)
-      user = user_id ? ::User.find(user_id) : nil
-      unless user
-        halt 401, {error: "User not found"}.to_json
-      end
-
-      access = generate_access_token(user.not_nil!)
-      refresh = generate_refresh_token(user.not_nil!)
-      Auth::RefreshResponse.new(access, refresh)
-    rescue JWT::Error
-      halt 401, {error: "Invalid refresh token"}.to_json
+      access = generate_access_from_payload(payload)
+      new_refresh = generate_refresh_from_payload(payload)
+      Auth::RefreshResponse.new(access, new_refresh)
+      <%- else %>
+      context.response.status = HTTP::Status::BAD_REQUEST
+      context.response.content_type = "application/json"
+      context.response.print({error: "Refresh tokens require JWT strategy"}.to_json)
+      return Azu::Response::Empty.new
+      <%- end %>
     end
 
-    private def generate_access_token(user : ::User) : String
+    <%- if using_jwt? || using_authly? %>
+    private def generate_access_from_payload(payload : Hash(String, JSON::Any)) : String
       now = Time.utc
-      payload = {
-        "sub" => user.id.to_s,
+      sub = payload["sub"].as_s
+      role = payload["role"]?.try(&.as_s) || "user"
+      new_payload = {
+        "sub" => sub,
         "iat" => now.to_unix,
         "exp" => (now + 15.minutes).to_unix,
         "iss" => jwt_issuer,
         "aud" => jwt_audience,
-        "role" => user.role,
+        "role" => role,
       }
-      JWT.encode(payload, jwt_secret, JWT::Algorithm::HS256)
+      JWT.encode(new_payload, jwt_secret, JWT::Algorithm::HS256)
     end
 
-    private def generate_refresh_token(user : ::User) : String
+    private def generate_refresh_from_payload(payload : Hash(String, JSON::Any)) : String
       now = Time.utc
-      payload = {
-        "sub" => user.id.to_s,
+      sub = payload["sub"].as_s
+      new_payload = {
+        "sub" => sub,
         "iat" => now.to_unix,
         "exp" => (now + 7.days).to_unix,
         "type" => "refresh",
       }
-      JWT.encode(payload, jwt_refresh_secret, JWT::Algorithm::HS256)
-    end
-
-    private def jwt_secret : String
-      ENV["JWT_SECRET"]? || raise "JWT_SECRET environment variable not set"
+      JWT.encode(new_payload, jwt_refresh_secret, JWT::Algorithm::HS256)
     end
 
     private def jwt_refresh_secret : String
       ENV["JWT_REFRESH_SECRET"]? || raise "JWT_REFRESH_SECRET environment variable not set"
     end
 
+    private def jwt_secret : String
+      ENV["JWT_SECRET"]? || raise "JWT_SECRET environment variable not set"
+    end
+
     private def jwt_issuer : String
       ENV["JWT_ISSUER"]? || "<%= project.downcase %>-api"
     end
 
     private def jwt_audience : String
       ENV["JWT_AUDIENCE"]? || "<%= project.downcase %>-client"
     end
+    <%- end %>
   end
 end
+
 <%- end %>