toolchest 0.3.2 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c78a7f55b37d501c0e2d5c4e164048ea4d176f2eb7126c232953a1c4c52e1da
-  data.tar.gz: 403d4c3b8ee52953630e52f0d4d31f1a31e9d406511fdfdd7c4f47a67f083bf6
+  metadata.gz: db7d29ec671adac8f24512bf3d190dedb55250dfd846b31c5906feac16771130
+  data.tar.gz: a3c7414f1c60e5997942fdacfa70ee3a368e6a0cd2b237eab2b1d187351cb10d
 SHA512:
-  metadata.gz: c4c8ca2520fc43e69398fffa2f25a08db7ec0566c7f9453f5fb5d442744e4c42be5ac53ffcb037ad5181a4bac8395970f0ea9b1c925fd6cfe6ab044f1e097b72
-  data.tar.gz: b0fd64277dd46191d91681b7c3cbaf14b70b03ac80324fe9d1a01e6b2455486e2d6c6c3c2dbd214430be2867d7f5967538f6ad4a2d76ed855664c44d14c0da65
+  metadata.gz: 68779c02c513ba5dc8052407a015de6fddda8e44c5aa6add4daeb204eb08fe7b41b997a6a2791e90b62ab1dc558d467d3ad722cbee5baca32fccbe7a04692203
+  data.tar.gz: d63e96b09cdf89b09a31e902b593f55b4399ab347c5af3daa033c50c03054c654e0338fe2f9eb31544f19522e65bb1c30f9181c33a040e14a2c26dbf91b5371c

data/LLMS.txt

@@ -213,7 +213,12 @@ end
 
 Types: `:string`, `:integer`, `:number`, `:boolean`, `:object`, `[:object]`, `[:string]`, etc.
 
-Options on `tool`: `name: "custom_tool_name"`, `access: :read` or `access: :write` (for scope filtering + annotations), `annotations: { openWorldHint: true }` (override hints).
+Options on `tool`:
+
+- `name: "custom_tool_name"` — override generated tool name
+- `access: :read` or `access: :write` — scope filtering + MCP annotations
+- `scope: "admin"` or `scope: ["admin", "superuser"]` — per-tool scope override (see below)
+- `annotations: { openWorldHint: true }` — override MCP hints
 
 `access: :read` → `readOnlyHint: true, destructiveHint: false`. `access: :write` → `readOnlyHint: false, destructiveHint: true`.
 
@@ -345,6 +350,22 @@ Scopes filter `tools/list` — clients only see tools their token allows. Fails
 
 Disable: `config.filter_tools_by_scope = false`
 
+### Per-tool scope override
+
+When a tool doesn't fit its toolbox's scope boundary, set `scope:` to bypass the convention:
+
+```ruby
+tool "Move ticket", scope: "admin" do       # only "admin" scope grants access
+  param :status, :string, "New status"
+end
+
+tool "Escalate", scope: ["admin", "superuser"] do  # either scope works (OR)
+  param :id, :string, "ID"
+end
+```
+
+`scope:` replaces convention matching for that tool. `tickets:write` won't grant access to a tool with `scope: "admin"`. Enforced on both `tools/list` and `tools/call`.
+
 ### Optional scopes (checkboxes on consent)
 
 ```ruby

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)`:
@@ -421,6 +477,32 @@ end
 
 Turn it off: `config.filter_tools_by_scope = false`
 
+### Per-tool scope override
+
+The convention derives scopes from the toolbox name — `OrdersToolbox` tools require `orders:*`. When a tool doesn't fit its toolbox's scope boundary, override it:
+
+```ruby
+class TicketsToolbox < ApplicationToolbox
+  tool "List tickets" do
+  end
+  def list = # ... requires tickets:read (convention)
+
+  # Only tokens with the "admin" scope can see or call this tool
+  tool "Move ticket", scope: "admin" do
+    param :status, :string, "New status"
+  end
+  def move = # ...
+
+  # Either "admin" OR "superuser" grants access
+  tool "Escalate ticket", scope: ["admin", "superuser"] do
+    param :id, :string, "Ticket ID"
+  end
+  def escalate = # ...
+end
+```
+
+`scope:` replaces the convention entirely for that tool — `tickets:write` won't grant access to a tool with `scope: "admin"`. The token must include the literal scope string. Enforced on both `tools/list` (visibility) and `tools/call` (execution).
+
 ### Optional scopes (checkboxes)
 
 By default, the consent screen is all-or-nothing — approve all requested scopes or deny. Enable `optional_scopes` and users get checkboxes:

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,16 @@ 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) }
+      end
 
       prefix = tool_definition.toolbox_class.controller_name.split("/").last
       tool_access = tool_definition.access_level ||

data/lib/toolchest/tool_definition.rb

@@ -1,14 +1,15 @@
 module Toolchest
   class ToolDefinition
-    attr_reader :method_name, :description, :params, :toolbox_class, :custom_name, :access_level, :annotations
+    attr_reader :method_name, :description, :params, :toolbox_class, :custom_name, :access_level, :scope, :annotations
 
-    def initialize(method_name:, description:, params:, toolbox_class:, custom_name: nil, access_level: nil, annotations: nil)
+    def initialize(method_name:, description:, params:, toolbox_class:, custom_name: nil, access_level: nil, scope: nil, annotations: nil)
       @method_name = method_name.to_sym
       @description = description
       @params = params
       @toolbox_class = toolbox_class
       @custom_name = custom_name
       @access_level = access_level
+      @scope = scope ? Array(scope) : nil
       @annotations = annotations
     end
 

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
@@ -46,10 +48,10 @@ module Toolchest
           .flat_map { |a| a.send(:own_prompts) }
       end
 
-      def tool(description, name: nil, access: nil, annotations: nil, &block)
+      def tool(description, name: nil, access: nil, scope: nil, annotations: nil, &block)
         builder = ToolBuilder.new
         builder.instance_eval(&block) if block
-        @_pending_tool = { description: description, custom_name: name, access_level: access, annotations: annotations, builder: builder }
+        @_pending_tool = { description:, custom_name: name, access_level: access, scope:, annotations:, builder: }
       end
 
       def default_param(name, type, description = "", **options)
@@ -110,12 +112,46 @@ module Toolchest
           toolbox_class: self,
           custom_name: pending[:custom_name],
           access_level: pending[:access_level],
+          scope: pending[:scope],
           annotations: pending[:annotations]
         )
 
         @_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
@@ -127,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.2"
+  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.2
+  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