toolchest 0.3.3 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 545413528704477fdfc39328f3380e82b1f80c9be8096bc36fe201cddf90ce02
-  data.tar.gz: 4beea37ac5456c21b9b4ec41711643f5c1b2155669e2370badb2e03ad45c0b49
+  metadata.gz: db7d29ec671adac8f24512bf3d190dedb55250dfd846b31c5906feac16771130
+  data.tar.gz: a3c7414f1c60e5997942fdacfa70ee3a368e6a0cd2b237eab2b1d187351cb10d
 SHA512:
-  metadata.gz: 60ef42ecc96cecf2c0a9b9ea26cf786dc72ced48fafa1840cc56f53141657f9791fc2ec2446dc328f6463aaca9cc37564f9365e8a7c851b30256cdb8fb9e3669
-  data.tar.gz: a8ea33024b69f8154a78d7a4664afdbddc57e01b87c4daa5f01b64dc5a8d1191b44004d9fedd060a57a013bc87cc14f8c462be683d08d82d78708d16210d98e1
+  metadata.gz: 68779c02c513ba5dc8052407a015de6fddda8e44c5aa6add4daeb204eb08fe7b41b997a6a2791e90b62ab1dc558d467d3ad722cbee5baca32fccbe7a04692203
+  data.tar.gz: d63e96b09cdf89b09a31e902b593f55b4399ab347c5af3daa033c50c03054c654e0338fe2f9eb31544f19522e65bb1c30f9181c33a040e14a2c26dbf91b5371c

data/README.md

@@ -31,6 +31,8 @@ rails s
 ```ruby
 # app/toolboxes/application_toolbox.rb
 class ApplicationToolbox < Toolchest::Toolbox
+  helper_method :current_user
+
   def current_user = auth&.resource_owner
 
   rescue_from ActiveRecord::RecordNotFound do |e|
@@ -39,7 +41,7 @@ class ApplicationToolbox < Toolchest::Toolbox
 end
 ```
 
-This is your ApplicationController. `auth` returns a `Toolchest::AuthContext` with `.resource_owner` (whatever your `authenticate` block returns), `.scopes` (always from the token), and `.token` (the raw record). Define `current_user` as a convenience, add shared error handling, include your gems.
+This is your ApplicationController. `auth` returns a `Toolchest::AuthContext` with `.resource_owner` (whatever your `authenticate` block returns), `.scopes` (always from the token), and `.token` (the raw record). Define `current_user` as a convenience and expose it to views with `helper_method`, add shared error handling, include your gems.
 
 ```ruby
 # app/toolboxes/orders_toolbox.rb
@@ -130,6 +132,41 @@ render_errors @order            # MCP error from ActiveModel errors
 
 `render :show` after mutations. Most toolboxes need one or two views.
 
+### View helpers
+
+Toolbox methods aren't available in views by default — views only get instance variables. Use `helper_method` to expose methods, same as a Rails controller:
+
+```ruby
+class ApplicationToolbox < Toolchest::Toolbox
+  helper_method :current_user, :admin?
+
+  def current_user = auth&.resource_owner
+  def admin? = current_user&.admin?
+end
+```
+
+Now `current_user` and `admin?` work in any view:
+
+```ruby
+# app/views/toolboxes/orders/show.json.jb
+{
+  id: @order.id,
+  status: @order.status,
+  viewer: current_user.name,
+  can_edit: admin?
+}
+```
+
+Include entire modules with `helper`:
+
+```ruby
+class ApplicationToolbox < Toolchest::Toolbox
+  helper FormattingHelper
+end
+```
+
+Both `helper_method` and `helper` inherit through the toolbox hierarchy — define them in `ApplicationToolbox` and every toolbox gets them.
+
 ### Resources and prompts
 
 Supported, though most toolboxes won't need them.
@@ -360,6 +397,25 @@ Toolchest::OauthAccessGrant.revoke_all_for(app, user.id)
 app.destroy  # cascades to all grants and tokens
 ```
 
+### Controller behavior
+
+The consent screen and authorized applications page inherit from your app's `ApplicationController` by default — so they get your auth, layout, nav, etc. Route helpers like `root_path` in your layout work automatically (Toolchest delegates unresolved `_path`/`_url` helpers to `main_app`).
+
+If you don't want host app behavior on these pages:
+
+```ruby
+# config/initializers/toolchest.rb
+Toolchest.base_controller = "ActionController::Base"
+```
+
+To disable the route helper delegation:
+
+```ruby
+Toolchest.delegate_route_helpers = false
+```
+
+API-only endpoints (token exchange, metadata, dynamic registration) always use `ActionController::API` regardless of this setting.
+
 ### Custom
 
 If the built-in strategies don't fit, pass any object that responds to `#authenticate(request)`:

data/app/controllers/toolchest/application_controller.rb

@@ -0,0 +1,5 @@
+module Toolchest
+  class ApplicationController < Toolchest.base_controller.constantize
+    helper Toolchest::RouteDelegation if Toolchest.delegate_route_helpers
+  end
+end

data/app/controllers/toolchest/oauth/authorizations_controller.rb

@@ -1,6 +1,6 @@
 module Toolchest
   module Oauth
-    class AuthorizationsController < ::ApplicationController
+    class AuthorizationsController < Toolchest::ApplicationController
       before_action :authenticate_resource_owner!
       before_action :validate_client!
 

data/app/controllers/toolchest/oauth/authorized_applications_controller.rb

@@ -1,6 +1,6 @@
 module Toolchest
   module Oauth
-    class AuthorizedApplicationsController < ::ApplicationController
+    class AuthorizedApplicationsController < Toolchest::ApplicationController
       before_action :authenticate_resource_owner!
 
       # GET /mcp/oauth/authorized_applications

data/app/controllers/toolchest/oauth/metadata_controller.rb

@@ -1,6 +1,6 @@
 module Toolchest
   module Oauth
-    class MetadataController < ::ApplicationController
+    class MetadataController < ActionController::API
       # GET /.well-known/oauth-authorization-server(/*rest)
       def authorization_server
         mount_path, cfg = resolve_mount

data/app/controllers/toolchest/oauth/registrations_controller.rb

@@ -1,7 +1,6 @@
 module Toolchest
   module Oauth
-    class RegistrationsController < ::ApplicationController
-      skip_forgery_protection
+    class RegistrationsController < ActionController::API
       wrap_parameters false
 
       # POST /register — Dynamic Client Registration (RFC 7591)
@@ -9,7 +8,14 @@ module Toolchest
       # at authorization time via the resource param.
       def create
         name = (params[:client_name] || "MCP Client").truncate(255)
-        uris = Array(params[:redirect_uris])
+        uris = Array(params[:redirect_uris]).map(&:to_s)
+
+        if uris.any? { |u| u.match?(/[\r\n]/) }
+          return render json: {
+            error: "invalid_client_metadata",
+            error_description: "Redirect URIs must not contain newlines"
+          }, status: :bad_request
+        end
 
         if uris.size > 10
           return render json: {

data/app/controllers/toolchest/oauth/tokens_controller.rb

@@ -1,7 +1,6 @@
 module Toolchest
   module Oauth
-    class TokensController < ::ApplicationController
-      skip_forgery_protection
+    class TokensController < ActionController::API
 
       # POST /mcp/oauth/token
       def create
@@ -46,7 +45,9 @@ module Toolchest
           return error_response("invalid_grant", "PKCE verification failed")
         end
 
-        grant.revoke!
+        unless grant.revoke_atomically!
+          return error_response("invalid_grant", "Authorization code already used")
+        end
 
         token = Toolchest::OauthAccessToken.create_for(
           application: app,

data/app/models/toolchest/oauth_access_grant.rb

@@ -24,6 +24,13 @@ module Toolchest
 
     def revoke! = update!(revoked_at: Time.current)
 
+    # Atomic revocation — returns true only if THIS call revoked the grant.
+    # Prevents race conditions where two concurrent token exchanges both
+    # find the grant active and both mint tokens (RFC 6749 §4.1.2).
+    def revoke_atomically!
+      self.class.where(id: id, revoked_at: nil).update_all(revoked_at: Time.current) > 0
+    end
+
     def uses_pkce? = code_challenge.present?
 
     def verify_pkce(code_verifier)

data/lib/generators/toolchest/consent_generator.rb

@@ -4,11 +4,12 @@ require "rails/generators/base"
 module Toolchest
   module Generators
     class ConsentGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../..", __dir__)
+
       desc "Eject the OAuth consent view for customization"
 
       def copy_consent_view
-        engine_view = File.expand_path("../../../../app/views/toolchest/oauth/authorizations/new.html.erb", __dir__)
-        copy_file engine_view, "app/views/toolchest/oauth/authorizations/new.html.erb"
+        copy_file "app/views/toolchest/oauth/authorizations/new.html.erb"
       end
 
       def show_instructions

data/lib/generators/toolchest/oauth_views_generator.rb

@@ -4,23 +4,25 @@ require "rails/generators/base"
 module Toolchest
   module Generators
     class OauthViewsGenerator < Rails::Generators::Base
+      source_root File.expand_path("../../../..", __dir__)
+
       desc "Eject all OAuth views and controllers for customization"
 
       def copy_views
-        engine_views = File.expand_path("../../../../app/views/toolchest/oauth", __dir__)
+        views_dir = File.join(self.class.source_root, "app/views/toolchest/oauth")
 
-        Dir[File.join(engine_views, "**", "*.erb")].each do |src|
-          relative = src.sub(engine_views + "/", "")
-          copy_file src, "app/views/toolchest/oauth/#{relative}"
+        Dir[File.join(views_dir, "**", "*.erb")].each do |src|
+          relative = src.sub(views_dir + "/", "")
+          copy_file "app/views/toolchest/oauth/#{relative}"
         end
       end
 
       def copy_controllers
-        engine_controllers = File.expand_path("../../../../app/controllers/toolchest/oauth", __dir__)
+        controllers_dir = File.join(self.class.source_root, "app/controllers/toolchest/oauth")
 
-        Dir[File.join(engine_controllers, "**", "*.rb")].each do |src|
-          relative = src.sub(engine_controllers + "/", "")
-          copy_file src, "app/controllers/toolchest/oauth/#{relative}"
+        Dir[File.join(controllers_dir, "**", "*.rb")].each do |src|
+          relative = src.sub(controllers_dir + "/", "")
+          copy_file "app/controllers/toolchest/oauth/#{relative}"
         end
       end
 

data/lib/toolchest/renderer.rb

@@ -12,6 +12,7 @@ module Toolchest
 
         lookup = ActionView::LookupContext.new(view_paths)
         view = ActionView::Base.with_empty_template_cache.new(lookup, assigns, nil)
+        apply_helpers(view, toolbox)
 
         result = view.render(template: template_name, formats: [:json])
 
@@ -73,6 +74,17 @@ module Toolchest
         assigns
       end
 
+      def apply_helpers(view, toolbox)
+        toolbox.class.helper_modules.each { |mod| view.extend(mod) }
+
+        toolbox.class.helper_methods.each do |method_name|
+          tb = toolbox
+          view.define_singleton_method(method_name) do |*args, **kwargs, &block|
+            tb.send(method_name, *args, **kwargs, &block)
+          end
+        end
+      end
+
       def view_paths
         paths = []
         if defined?(Rails) && Rails.respond_to?(:root) && Rails.root

data/lib/toolchest/route_delegation.rb

@@ -0,0 +1,27 @@
+module Toolchest
+  # Delegates unresolved _path/_url helpers to main_app so the host
+  # application's layout works inside engine-rendered views without
+  # requiring main_app. prefixes everywhere.
+  #
+  # Included as a view helper by the engine when
+  # Toolchest.delegate_route_helpers is true (the default).
+  #
+  # To disable:
+  #
+  #   # config/initializers/toolchest.rb
+  #   Toolchest.delegate_route_helpers = false
+  #
+  module RouteDelegation
+    def method_missing(method, *args, **kwargs, &block)
+      if method.to_s.end_with?("_path", "_url") && main_app.respond_to?(method)
+        main_app.public_send(method, *args, **kwargs, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      (method.to_s.end_with?("_path", "_url") && main_app.respond_to?(method)) || super
+    end
+  end
+end

data/lib/toolchest/router.rb

@@ -217,7 +217,12 @@ module Toolchest
     READ_ACTIONS = Set.new(%i[show index list search]).freeze
 
     def tool_allowed_by_scopes?(tool_definition, scopes)
-      return true if scopes.empty?
+      if scopes.empty?
+        # Token has no scopes. Allow only if the server hasn't declared any
+        # scopes either (convention-based filtering without declarations).
+        # When scopes ARE configured, empty token scopes = no access (fail closed).
+        return Toolchest.configuration(@mount_key).scopes.empty?
+      end
 
       if tool_definition.scope
         return tool_definition.scope.any? { |s| scopes.include?(s) }

data/lib/toolchest/toolbox.rb

@@ -16,6 +16,8 @@ module Toolchest
         subclass.instance_variable_set(:@_resources, [])
         subclass.instance_variable_set(:@_prompts, [])
         subclass.instance_variable_set(:@_pending_tool, nil)
+        subclass.instance_variable_set(:@_helper_methods, [])
+        subclass.instance_variable_set(:@_helper_modules, [])
       end
 
       def tool_definitions
@@ -117,6 +119,39 @@ module Toolchest
         @_tool_definitions[method_name.to_sym] = definition
       end
 
+      # Expose toolbox methods as view helpers, like controller helper_method.
+      #
+      #   helper_method :current_user, :admin?
+      #
+      def helper_method(*methods)
+        @_helper_methods.concat(methods.map(&:to_sym))
+      end
+
+      # Include modules as view helpers.
+      #
+      #   helper ApplicationHelper
+      #   helper FormattingHelper, CurrencyHelper
+      #
+      def helper(*modules)
+        @_helper_modules.concat(modules)
+      end
+
+      def helper_methods
+        ancestors
+          .select { |a| a.respond_to?(:own_helper_methods, true) }
+          .reverse
+          .flat_map { |a| a.send(:own_helper_methods) }
+          .uniq
+      end
+
+      def helper_modules
+        ancestors
+          .select { |a| a.respond_to?(:own_helper_modules, true) }
+          .reverse
+          .flat_map { |a| a.send(:own_helper_modules) }
+          .uniq
+      end
+
       def controller_name = name&.underscore&.chomp("_toolbox") || "anonymous"
 
       protected
@@ -128,6 +163,10 @@ module Toolchest
       def own_resources = @_resources || []
 
       def own_prompts = @_prompts || []
+
+      def own_helper_methods = @_helper_methods || []
+
+      def own_helper_modules = @_helper_modules || []
     end
 
     attr_reader :params

data/lib/toolchest/version.rb

@@ -1,3 +1,3 @@
 module Toolchest
-  VERSION = "0.3.3"
+  VERSION = "0.3.5"
 end

data/lib/toolchest.rb

@@ -4,6 +4,7 @@ require "toolchest/version"
 
 module Toolchest
   autoload :App, "toolchest/app"
+  autoload :RouteDelegation, "toolchest/route_delegation"
   autoload :AuthContext, "toolchest/auth_context"
   autoload :Configuration, "toolchest/configuration"
   autoload :Current, "toolchest/current"
@@ -68,11 +69,28 @@ module Toolchest
     # When multiple OAuth mounts exist, bare /.well-known/* resolves to this mount
     attr_accessor :default_oauth_mount
 
+    # Parent class for engine HTML controllers. Default: "::ApplicationController".
+    # Set to "ActionController::Base" to avoid inheriting host app behavior.
+    attr_writer :base_controller
+    def base_controller
+      @base_controller || "::ApplicationController"
+    end
+
+    # Delegate unresolved _path/_url helpers to main_app so the host
+    # layout renders correctly inside engine views. Default: true.
+    # Set to false in an initializer to disable.
+    attr_writer :delegate_route_helpers
+    def delegate_route_helpers
+      @delegate_route_helpers != false
+    end
+
     def reset!
       @configs = nil
       @routers = nil
       @apps = nil
       @default_oauth_mount = nil
+      @base_controller = nil
+      @delegate_route_helpers = nil
     end
 
     # Reset only routers/apps (preserves config set by initializers)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toolchest
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.5
 platform: ruby
 authors:
 - Nora
@@ -46,6 +46,7 @@ files:
 - LICENSE
 - LLMS.txt
 - README.md
+- app/controllers/toolchest/application_controller.rb
 - app/controllers/toolchest/oauth/authorizations_controller.rb
 - app/controllers/toolchest/oauth/authorized_applications_controller.rb
 - app/controllers/toolchest/oauth/metadata_controller.rb
@@ -88,6 +89,7 @@ files:
 - lib/toolchest/parameters.rb
 - lib/toolchest/rack_app.rb
 - lib/toolchest/renderer.rb
+- lib/toolchest/route_delegation.rb
 - lib/toolchest/router.rb
 - lib/toolchest/rspec.rb
 - lib/toolchest/sampling_builder.rb