standard_id 0.31.0 → 0.33.0

data/lib/standard_id/routing.rb

@@ -0,0 +1,133 @@
+require "action_dispatch/routing/mapper"
+
+module StandardId
+  # Route-mapper extensions, available inside `Rails.application.routes.draw`.
+  module Routing
+    # Documents this helper can draw, mapped to their path and controller.
+    WELL_KNOWN_DOCUMENTS = {
+      oauth_authorization_server: {
+        path: "oauth-authorization-server",
+        to: "standard_id/api/well_known/oauth_authorization_server#show"
+      },
+      openid_configuration: {
+        path: "openid-configuration",
+        to: "standard_id/api/well_known/openid_configuration#show"
+      },
+      jwks: {
+        path: "jwks.json",
+        to: "standard_id/api/well_known/jwks#show"
+      }
+    }.freeze
+
+    # Draw StandardId's discovery documents at the ORIGIN ROOT.
+    #
+    #   # config/routes.rb
+    #   Rails.application.routes.draw do
+    #     standard_id_well_known_routes at: "/api/v1"
+    #     namespace :api do
+    #       mount StandardId::ApiEngine, at: "/", as: :standard_id_api
+    #     end
+    #   end
+    #
+    # ## Why the gem cannot just route these itself
+    #
+    # The engine's own `.well-known` routes live INSIDE its mount, so an app
+    # mounting ApiEngine at `/api/v1` serves them at
+    # `/api/v1/.well-known/openid-configuration`. But RFC 8615 clients probe the
+    # **origin root**, which is outside any engine mount — a mapper helper in the
+    # host's routes file is the only place these can be drawn.
+    #
+    # ## The path-inserted form, and why it is not optional
+    #
+    # For each document this draws BOTH:
+    #
+    #   /.well-known/oauth-authorization-server
+    #   /.well-known/oauth-authorization-server/api/v1     <- RFC 8414 §3.1
+    #
+    # The second is the spec's form for an issuer that carries a path: the
+    # well-known segment is INSERTED BEFORE the issuer's path rather than appended
+    # to it. It looks redundant and it is not. It is the URL Claude Code actually
+    # requests in production against a path-carrying issuer; without it the client
+    # 404s, falls back to issuer-relative defaults (hitting the engine's real
+    # `/authorize` instead of a host audience shim), and every subsequent
+    # authenticated request 401s. That failure is remote from its cause and hard
+    # to diagnose, which is why the route is drawn for you rather than documented
+    # as an extra step.
+    #
+    # Both forms serve the same document. The mount path is stamped into the
+    # route defaults so DiscoveryResolver can build endpoint URLs off it — a root
+    # route has no SCRIPT_NAME to read it from.
+    #
+    # @param at [String] the path ApiEngine is mounted at ("/" or "" for root).
+    #   Used both to build the path-inserted routes and to resolve endpoint URLs.
+    # @param only [Array<Symbol>, Symbol, nil] restrict to these documents.
+    #   Keys: :oauth_authorization_server, :openid_configuration, :jwks. Apps
+    #   that keep a host-owned metadata controller but want the gem's JWKS at the
+    #   root pass `only: :jwks`.
+    # @param except [Array<Symbol>, Symbol, nil] the inverse of `only`.
+    # @param extra_paths [Array<String>] additional path-inserted suffixes beyond
+    #   `at:`. For serving the same document under a second issuer path (e.g. a
+    #   protected resource at `/mcp`) without a second route block.
+    # @param path_inserted [Boolean] set false to draw only the bare root forms.
+    #   Defaults to true; turning it off is what reintroduces the Claude Code
+    #   failure above, so it exists only for apps that route those themselves.
+    def standard_id_well_known_routes(at:, only: nil, except: nil, extra_paths: [], path_inserted: true)
+      mount_path = StandardId::Oauth::DiscoveryResolver.normalize_path(at)
+      documents = StandardId::Routing.selected_documents(only: only, except: except)
+
+      suffixes = path_inserted ? ([mount_path] + Array(extra_paths)).map { |p| StandardId::Oauth::DiscoveryResolver.normalize_path(p) } : []
+      suffixes = suffixes.reject(&:empty?).uniq
+
+      defaults = { StandardId::Oauth::DiscoveryResolver::MOUNT_PATH_PARAM => mount_path }
+
+      scope ".well-known" do
+        documents.each do |name, config|
+          get config[:path], to: config[:to], as: :"standard_id_root_#{name}", defaults: defaults
+
+          # jwks.json is a concrete file path, not a metadata document whose
+          # location RFC 8414 §3.1 relocates — a path-inserted variant of it
+          # would advertise a URL no spec describes.
+          next if name == :jwks
+
+          suffixes.each_with_index do |suffix, index|
+            get "#{config[:path]}#{suffix}",
+              to: config[:to],
+              as: :"standard_id_root_#{name}_at_#{index}",
+              defaults: defaults
+          end
+        end
+      end
+    end
+
+    # @return [Hash] the WELL_KNOWN_DOCUMENTS entries `only:`/`except:` select
+    def self.selected_documents(only: nil, except: nil)
+      if only.present? && except.present?
+        raise ArgumentError, "standard_id_well_known_routes accepts `only:` or `except:`, not both"
+      end
+
+      keys = WELL_KNOWN_DOCUMENTS.keys
+      requested = Array(only).map(&:to_sym) + Array(except).map(&:to_sym)
+      unknown = requested - keys
+      if unknown.any?
+        raise ArgumentError,
+          "Unknown StandardId well-known document(s): #{unknown.join(', ')}. Valid: #{keys.join(', ')}"
+      end
+
+      selected = if only.present?
+        Array(only).map(&:to_sym)
+      elsif except.present?
+        keys - Array(except).map(&:to_sym)
+      else
+        keys
+      end
+
+      WELL_KNOWN_DOCUMENTS.slice(*selected)
+    end
+  end
+end
+
+# Included directly rather than through a load hook: ActionDispatch has no
+# `:action_dispatch_routing_mapper` hook, and this file is required from
+# lib/standard_id.rb during Bundler.require — long before any routes file is
+# evaluated — so the mapper method is defined by the time a host calls it.
+ActionDispatch::Routing::Mapper.include(StandardId::Routing)

data/lib/standard_id/version.rb

@@ -1,3 +1,3 @@
 module StandardId
-  VERSION = "0.31.0"
+  VERSION = "0.33.0"
 end

data/lib/standard_id.rb

@@ -6,6 +6,7 @@ require "standard_id/api_engine"
 require "standard_id/config_schema"
 require "standard_id/config/schema"
 require "standard_id/scope_config"
+require "standard_id/association_strict_loading"
 require "standard_id/errors"
 require "standard_id/events"
 require "standard_id/events/subscribers/base"
@@ -44,7 +45,9 @@ require "standard_id/oauth/subflows/base"
 require "standard_id/oauth/subflows/traditional_code_grant"
 require "standard_id/oauth/subflows/social_login_grant"
 require "standard_id/oauth/passwordless_otp_flow"
+require "standard_id/oauth/discovery_resolver"
 require "standard_id/oauth/discovery_document"
+require "standard_id/routing"
 require "standard_id/oauth/consent_payload"
 require "standard_id/oauth/client_registration"
 require "standard_id/passwordless/base_strategy"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: standard_id
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.33.0
 platform: ruby
 authors:
 - Jaryl Sim
@@ -133,6 +133,7 @@ files:
 - app/controllers/standard_id/api/base_controller.rb
 - app/controllers/standard_id/api/oauth/base_controller.rb
 - app/controllers/standard_id/api/oauth/callback/providers_controller.rb
+- app/controllers/standard_id/api/oauth/introspections_controller.rb
 - app/controllers/standard_id/api/oauth/registrations_controller.rb
 - app/controllers/standard_id/api/oauth/revocations_controller.rb
 - app/controllers/standard_id/api/oauth/tokens_controller.rb
@@ -238,6 +239,7 @@ files:
 - lib/standard_id/api/session_manager.rb
 - lib/standard_id/api/token_manager.rb
 - lib/standard_id/api_engine.rb
+- lib/standard_id/association_strict_loading.rb
 - lib/standard_id/authorization_bypass.rb
 - lib/standard_id/bearer_token_extraction.rb
 - lib/standard_id/config/callable_validator.rb
@@ -267,6 +269,7 @@ files:
 - lib/standard_id/oauth/client_registration.rb
 - lib/standard_id/oauth/consent_payload.rb
 - lib/standard_id/oauth/discovery_document.rb
+- lib/standard_id/oauth/discovery_resolver.rb
 - lib/standard_id/oauth/implicit_authorization_flow.rb
 - lib/standard_id/oauth/oauth_session_persistence.rb
 - lib/standard_id/oauth/password_flow.rb
@@ -287,6 +290,7 @@ files:
 - lib/standard_id/provider_registry.rb
 - lib/standard_id/providers/base.rb
 - lib/standard_id/rate_limit_store.rb
+- lib/standard_id/routing.rb
 - lib/standard_id/scope_config.rb
 - lib/standard_id/session_type_resolver.rb
 - lib/standard_id/testing.rb